Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

Example: Using a Custom YANG RPC to Retrieve Operational Information on Devices Running Junos OS

 

You can add YANG data models that define custom RPCs on devices running Junos OS. Creating custom RPCs enables you to precisely define the input parameters and operations and the output fields and formatting for your specific operational tasks on those devices. This example presents a custom RPC and action script that retrieve operational information from the device and display customized CLI output.

The RPC is added to the Junos OS schema on the device. When the RPC is executed in the CLI, it prints the name and operational status for the requested physical interfaces.

Requirements

This example uses the following hardware and software components:

  • MX Series router running Junos OS Release 17.3R1.

Overview of the RPC and Action Script

The YANG module presented in this section defines a custom RPC to return the name and operational status of certain physical interfaces. The YANG module rpc-interface-status is saved in the rpc-interface-status.yang file. The module imports the Junos OS extension modules, which provide the extensions required to execute custom RPCs on the device and to customize the CLI output.

The module defines the get-interface-status RPC. The <get-interface-status> request tag is used to remotely execute the RPC on the device. In the RPC definition, the junos:command statement defines the command that is used to execute the RPC in the CLI, which in this case is show intf status.

The junos:action-execute and junos:script statements define the action script that is invoked when the RPC is executed. This example uses a Python action script named rpc-interface-status.py to retrieve the information required by the RPC and return the XML output elements as defined in the RPC output statement.

Note

Starting in Junos OS Release 17.3, the action-execute statement is a substatement to command. In earlier releases, the action-execute and command statements are placed at the same level, and the command statement is optional.

The RPC has one input parameter named match, which determines the interfaces to include in the output. When the user executes the RPC, the user includes a string that matches on the desired interfaces, for example ge-0*. An empty string ("") matches on all interfaces. The action script defines the default value for match as an empty string, so if the user omits this argument, the output will include information for all interfaces.

The RPC also defines the output nodes that must be emitted by the corresponding action script. The root node is the <interface-status-info> element, which contains zero or more <status-info> elements that enclose the <interface> and <status> nodes for a matched interface. The junos-odl:format statement interface-status-info-format defines the formatting for the output that is displayed in the CLI. This node is not emitted in the output XML tree.

This example presents two versions of the Python action script. The scripts demonstrate different means to retrieve the operational command output, but both scripts emit identical RPC output. The first action script uses the Python subprocess module to execute the show interfaces match-value | display xml command and then converts the string output into XML. The second action script uses Junos PyEZ to execute the RPC equivalent of the show interfaces match-value command. Both scripts use identical code to parse the command output and extract the name and operational status for each physical interface. The scripts construct the XML for the RPC output and then print the output, which returns the information back to the device. The XML tree must exactly match the hierarchy defined in the RPC.

Note

Devices running Junos OS define release-dependent namespaces for many of the elements in the operational output, including the <interface-information> element. In order to make the RPC Junos OS-release independent, the code uses the local-name() function in the XPath expressions for these elements. You might choose to include the namespace mapping as an argument to xpath() and qualify the elements with the appropriate namespace.

The module containing the RPC and the action script file are added to the device as part of a new YANG package named intf-rpc.

YANG Module

The YANG module, rpc-interface-status.yang, defines the RPC, the command used to execute the RPC in the CLI, and the name of the action script to invoke when the RPC is executed. The base name of the file must match the module name.

The corresponding action script is rpc-interface-status.py. This example presents two action scripts that use different means to retrieve the data. Both scripts emit the same RPC XML output.

Action Script

The following action script uses the Python subprocess module to execute the operational command and retrieve the data:

Action Script (Junos PyEZ)

The following action script uses Junos PyEZ to execute the operational command and retrieve the data:

Loading the RPC on the Device

To add the RPC and action script to the Junos OS schema on a device running Junos OS:

  1. Download the YANG module and action script to the device running Junos OS.
  2. Ensure that the Python action script meets the following requirements:
    • File owner is either root or a user in the Junos OS super-user login class.

    • Only the file owner has write permission for the file.

  3. (Optional) Validate the syntax for the YANG module and action script.

    user@host> request system yang validate module /var/tmp/rpc-interface-status.yang action-script /var/tmp/rpc-interface-status.py
  4. Add the YANG module and action script to a new YANG package.

    user@host> request system yang add package intf-rpc module /var/tmp/rpc-interface-status.yang action-script /var/tmp/rpc-interface-status.py
    Note

    Starting in Junos OS Release 17.3R1, when you load custom YANG data models onto the device, you do not need to explicitly load any required Junos OS extension modules. In earlier releases, you must load the Junos OS extension modules for any packages that use the modules.

  5. When the system prompts you to restart the Junos OS CLI, press Enter to accept the default value of yes, or type yes and press Enter.

Enabling Execution of Python Scripts

To enable the device to execute unsigned Python scripts, configure the language python statement.

Verifying the RPC

Purpose

Verify that the RPC is working as expected.

Action

From operational mode, execute the RPC in the CLI by issuing the command defined by the junos:command statement in the RPC definition, and include the match input argument. In this example, the match argument is used to match on all interfaces that start with ge-0.

user@host> show intf status match ge-0*

You can also adjust the match condition to return different sets of interfaces. For example:

user@host> show intf status match *e-0/*/0

To return the same output in XML format, append the | display xml filter to the command.

user@host> show intf status match *e-0/*/0 | display xml
Note

To match on all interfaces, either omit the match argument or set the value of the argument to an empty string ("").

Meaning

When the RPC is executed, the action script is invoked. The action script runs the operational command to retrieve interface information from the device, parses the output for the desired information, and prints the XML hierarchy for the RPC output as defined in the RPC output statement. When the RPC is executed in the CLI, the device uses the CLI formatting defined in the RPC to convert the XML output into the displayed CLI output. To return the original XML output, append the | display xml filter to the command.

Note

When the RPC is executed remotely using the RPC request tag, the default format for the output is XML.

Troubleshooting RPC Execution Errors

Problem

Description:

When you execute the RPC, the device generates the following error:

Cause

The user who invoked the RPC does not have the necessary permissions to execute the corresponding Python action script.

Solution

Users can only execute unsigned Python scripts on devices running Junos OS when the script's file permissions include read permission for the first class that the user falls within, in the order of user, group, or others.

Verify whether the script has the necessary permissions for that user to execute the script, and adjust the permissions, if appropriate. If you update the permissions, you must also update the YANG package in order for this change to take effect. For example:

% ls -l rpc-interface-status.py
% chmod 644 rpc-interface-status.py
% ls -l rpc-interface-status.py
% cli
user@host> request system yang update intf-rpc action-script /var/tmp/rpc-interface-status.py