Use Junos PyEZ to Execute RPCs on Junos Devices

All operational commands that have Junos XML counterparts are listed in the Junos XML API Explorer. You can also display the Junos XML request tag element for any operational mode command that has a Junos XML counterpart either on the CLI or using Junos PyEZ. Once you obtain the request tag, you can map it to the Junos PyEZ RPC method name.

To display the Junos XML request tag for a command in the CLI, include the | display xml rpc option after the command. The following example displays the request tag for the show route command:

user@router> show route | display xml rpc 
<rpc-reply xmlns:junos="http://xml.juniper.net/junos/15.1R1/junos">
    <rpc>
        <get-route-information>
        </get-route-information>
    </rpc>
</rpc-reply>

You can also display the Junos XML request tag for a command using Junos PyEZ. To display the request tag, call the Device instance display_xml_rpc() method, and include the command string and format='text' as arguments. For example:

from jnpr.junos import Device

with Device(host='router.example.com') as dev:   
    print (dev.display_xml_rpc('show route', format='text'))

Executing the program returns the request tag for the show route command.

<get-route-information>
</get-route-information>

You can map the request tags for an operational command to a Junos PyEZ RPC method name. To derive the RPC method name, replace any hyphens in the request tag with underscores (_) and remove the enclosing angle brackets. For example, the <get-route-information> request tag maps to the get_route_information() method name.

Each instance of Device has an rpc property that enables you to execute any RPC available through the Junos XML API. In a Junos PyEZ application, after establishing a connection with the device, you can execute the RPC by appending the rpc property and RPC method name to the device instance as shown in the following example:

from jnpr.junos import Device
from lxml import etree

with Device(host='dc1a.example.com') as dev:   
    #invoke the RPC equivalent to "show version"
    sw = dev.rpc.get_software_information()
    print(etree.tostring(sw, encoding='unicode'))

The return value is an XML object starting at the first element under the <rpc-reply> tag. In this case, the get_software_information() RPC returns the <software-information> element.

<software-information>
<host-name>dc1a</host-name>
...
</software-information>

Junos OS commands can have fixed-form options that do not have a value. For example, the Junos XML equivalent for the show interfaces terse command indicates that terse is an empty element.

user@router> show interfaces terse | display xml rpc
<rpc-reply xmlns:junos="http://xml.juniper.net/junos/14.1R1/junos">
    <rpc>
        <get-interface-information>
            <terse/>
        </get-interface-information>
    </rpc>
</rpc-reply>

To execute an RPC and include a command option that does not take a value, add the option to the RPC method’s argument list, change any dashes in the option name to underscores, and set it equal to True. The following code executes the Junos PyEZ RPC equivalent of the show interfaces terse command:

rsp = dev.rpc.get_interface_information(terse=True)

Junos OS commands can also have options that require a value. For example, in the following output, the interface-name element requires a value, which is the name of the interface for which you want to return information:

user@router> show interfaces ge-0/0/0 | display xml rpc
<rpc-reply xmlns:junos="http://xml.juniper.net/junos/14.1R1/junos">
    <rpc>
        <get-interface-information>
            <interface-name>ge-0/0/0</interface-name>
        </get-interface-information>
    </rpc>
</rpc-reply>

To execute an RPC and include a command option that requires a value, add the option to the RPC method’s argument list, change any dashes in the option name to underscores, and then set it equal to the appropriate value. The following example executes the Junos PyEZ RPC equivalent of the show interfaces ge-0/0/0 command:

rsp = dev.rpc.get_interface_information(interface_name='ge-0/0/0')

By default, the RPC return value is an XML object starting at the first element under the <rpc-reply> tag. You can also return the RPC output in text or JavaScript Object Notation (JSON) format by including either the {'format':'text'} or {'format':'json'} dictionary as the RPC method’s first argument.

The following example returns the output of the get_software_information() RPC in text format, which is identical to the output emitted for the show version command in the CLI, except that the RPC output is enclosed within an <output> element.

from jnpr.junos import Device
from lxml import etree  
    
with Device(host='router1.example.com') as dev:      
    sw_info_text = dev.rpc.get_software_information({'format':'text'})
    print(etree.tostring(sw_info_text))  

user@server:~$ python3 junos-pyez-rpc-text-format.py

<output>
Hostname: router1
Model: mx104
Junos: 18.3R1.9
JUNOS Base OS boot [18.3R1.9]
JUNOS Base OS Software Suite [18.3R1.9]
JUNOS Crypto Software Suite [18.3R1.9]
JUNOS Packet Forwarding Engine Support (TRIO) [18.3R1.9]
JUNOS Web Management [18.3R1.9]
JUNOS Online Documentation [18.3R1.9]
JUNOS SDN Software Suite [18.3R1.9]
JUNOS Services Application Level Gateways [18.3R1.9]
JUNOS Services COS [18.3R1.9]
JUNOS Services Jflow Container package [18.3R1.9]
JUNOS Services Stateful Firewall [18.3R1.9]
JUNOS Services NAT [18.3R1.9]
JUNOS Services RPM [18.3R1.9]
JUNOS Services Captive Portal and Content Delivery Container package [18.3R1.9]
JUNOS Macsec Software Suite [18.3R1.9]
JUNOS Services Crypto [18.3R1.9]
JUNOS Services IPSec [18.3R1.9]
JUNOS DP Crypto Software Software Suite [18.3R1.9]
JUNOS py-base-powerpc [18.3R1.9]
JUNOS py-extensions-powerpc [18.3R1.9]
JUNOS jsd [powerpc-18.3R1.9-jet-1]
JUNOS Kernel Software Suite [18.3R1.9]
JUNOS Routing Software Suite [18.3R1.9]
<output>

The following example returns the output of the get_software_information() RPC in JSON format.

from jnpr.junos import Device
from pprint import pprint

with Device(host='router1.example.com') as dev:      
    sw_info_json = dev.rpc.get_software_information({'format':'json'})
    pprint(sw_info_json)

user@server:~$ python3 junos-pyez-rpc-json-format.py
{u'software-information': [{u'host-name': [{u'data': u'router1'}],
                            u'junos-version': [{u'data': u'18.3R1.9'}],
                            u'package-information': [{u'comment': [{u'data': u'JUNOS Base OS boot [18.3R1.9]'}],
                                                      u'name': [{u'data': u'junos'}]},
                                                     {u'comment': [{u'data': u'JUNOS Base OS Software Suite [18.3R1.9]'}],
                                                      u'name': [{u'data': u'jbase'}]},
...

You can use Junos PyEZ to execute an RPC to retrieve operational information from Junos devices. Starting in Junos PyEZ Release 2.3.0, when you request XML output, you can filter the reply to return only specific elements. Filtering the output is beneficial when you have extensive operational output, but you only need to work with a subset of the data.

To filter the RPC reply to return only specific tags, include the RPC method’s filter_xml argument. The filter_xml parameter takes a string containing the subtree filter that selects the elements to return. The subtree filter returns the data that matches the selection criteria.

The following Junos PyEZ example executes the <get-interface-information> RPC and filters the output to retrieve just the <name> element for each <physical-interface> element in the reply:

from jnpr.junos import Device
from lxml import etree

with Device(host='router.example.com', use_filter=True) as dev:
    filter = '<interface-information><physical-interface><name/></physical-interface></interface-information>'
    result = dev.rpc.get_interface_information(filter_xml=filter)
    print (etree.tostring(result, encoding='unicode'))

When you execute the script, it displays each physical interface’s name element.

user@server:~$ python3 junos-pyez-get-interface-names.py
<interface-information style="normal"><physical-interface><name>
lc-0/0/0
</name></physical-interface><physical-interface><name>
pfe-0/0/0
</name></physical-interface><physical-interface><name>
pfh-0/0/0
</name></physical-interface><physical-interface><name>
xe-0/0/0
</name></physical-interface><physical-interface><name>
xe-0/1/0
</name></physical-interface><physical-interface><name>
ge-1/0/0
</name></physical-interface>
...
</interface-information>

RPC execution time can vary considerably depending on the RPC and the device. By default, NETCONF RPCs time out after 30 seconds. You can extend the timeout value by including the dev_timeout=seconds argument when you execute the RPC to ensure that the RPC does not time out during execution. dev_timeout adjusts the device timeout only for that single RPC operation.

dev.rpc.get_route_information(table='inet.0', dev_timeout=55)

When you execute an RPC, the RPC reply can include data that is wrapped in newlines or contains other superfluous whitespace. Unnecessary whitespace can make it difficult to parse the XML and find information using text-based searches. You can normalize an RPC reply, which strips out all leading and trailing whitespace and replaces sequences of internal whitespace characters with a single space.

Table 1 compares a default RPC reply to the normalized version. The default RPC reply includes many newlines that are not present in the normalized reply.

<interface-information style="terse">
<logical-interface>
<name>\nge-0/0/0.0\n</name>
<admin-status>\nup\n</admin-status>
<oper-status>\nup\n</oper-status>
<filter-information>\n</filter-information>
<address-family>
<address-family-name>\ninet\n</address-family-name>
<interface-address>
<ifa-local emit="emit">\n198.51.100.1/24\n</ifa-local>
</interface-address>
</address-family>
</logical-interface>
</interface-information>

<interface-information style="terse">
<logical-interface>
<name>ge-0/0/0.0</name>
<admin-status>up</admin-status>
<oper-status>up</oper-status>
<filter-information/>
<address-family>
<address-family-name>inet</address-family-name>
<interface-address>
<ifa-local emit="emit">198.51.100.1/24</ifa-local>
</interface-address>
</address-family>
</logical-interface>
</interface-information>

You can enable normalization for the duration of a session with a device, or you can normalize an individual RPC reply when you execute the RPC. To enable normalization for the entire device session, include normalize=True in the argument list either when you create the device instance or when you connect to the device using the open() method.

dev = Device(host='router1.example.com', user='root', normalize=True)

# or 

dev.open(normalize=True)

To normalize an individual RPC reply, include normalize=True in the argument list for that RPC method.

dev.rpc.rpc_method(normalize=True)

For example:

rsp = dev.rpc.get_interface_information(interface_name='ge-0/0/0.0', terse=True, normalize=True)

If you do not normalize the RPC reply, you must account for any whitespace when using XPath expressions that reference a specific node or value. The following example selects the IPv4 address for a logical interface. In the XPath expression, the predicate specifying the inet family must account for the additional whitespace in order for the search to succeed. The resulting value includes leading and trailing newlines.

rsp = dev.rpc.get_interface_information(interface_name='ge-0/0/0.0', terse=True)
print (rsp.xpath('.// \
    address-family[normalize-space(address-family-name)="inet"]/ \
    interface-address/ifa-local')[0].text)

'\n198.51.100.1/24\n'

When you normalize the RPC reply, any leading and trailing whitespace is removed, which makes text-based searches much more straightforward.

rsp = dev.rpc.get_interface_information(interface_name='ge-0/0/0.0', terse=True, normalize=True)
print (rsp.xpath('.//address-family[address-family-name="inet"]/ \
    interface-address/ifa-local')[0].text)

'198.51.100.1/24'