Using Junos PyEZ to Execute RPCs on Devices Running Junos OS

 

You can use Junos PyEZ to execute RPCs on demand on devices running Junos OS. After creating an instance of the Device class, you can execute RPCs as a property of the Device instance. You can perform most of the same operational commands using Junos PyEZ that you can execute in the CLI.

The Junos XML API is an XML representation of Junos OS configuration statements and operational mode commands. It defines an XML equivalent for all statements in the Junos OS configuration hierarchy and many of the commands that you issue in CLI operational mode. Each operational mode command with a Junos XML counterpart maps to a request tag element and, if necessary, a response tag element. Request tags are used in remote procedure calls (RPCs) within NETCONF or Junos XML protocol sessions to request information from a device running Junos OS. The server returns the response using Junos XML elements enclosed within the response tag element.

When you use Junos PyEZ to execute RPCs, you map the request tag name to a method name. This topic outlines how to map CLI commands to Junos PyEZ RPCs, how to execute RPCs using Junos PyEZ, and how to normalize the RPC reply.

Mapping Junos OS Commands to Junos PyEZ RPCs

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

Starting in Junos PyEZ Release 1.2, 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:

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

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.

Executing RPCs as a Property of the Device Instance

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:

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.

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.

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:

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:

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:

Specifying the RPC Output Format

By default, the RPC return value is an XML object starting at the first element under the <rpc-reply> tag. Starting in Junos PyEZ Release 1.2.3, 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.

Note

RPC output in JSON format is only supported on devices running Junos OS Release 14.2 and later releases.

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.

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

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

user@server:~$ python junos-pyez-rpc-json-format.py

Specifying the RPC Timeout

RPC execution time can vary considerably depending on the RPC and the device. By default, NETCONF RPCs time out after 30 seconds. Starting in Junos PyEZ Release 1.2, 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.

Normalizing the XML RPC Reply

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. Starting in Junos PyEZ Release 1.2, 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.

Table 1: Comparison of a Default and Normalized RPC Reply

Default RPC Reply

Normalized RPC 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.

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

For example:

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.

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