Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

Defining Different Levels of Output in Custom YANG RPCs for Devices Running Junos OS

 

Defining Different Levels of Output in Custom YANG RPCs

You can define custom RPCs for devices running Junos OS using YANG. The RPC output can be customized to emit different data and CLI formatting depending on the RPC input. This enables you to create different styles, or levels of output, for the same RPC.

You can request the desired style by including the appropriate value for the input argument when you invoke the RPC. The action script must process this argument and emit the XML output for the requested style. Junos OS then translates the XML into the corresponding CLI output defined for that style. The RPC template presented in this topic creates two styles: brief and detail.

To create different styles for the output of an RPC:

  1. In the YANG module that includes the RPC, import the Junos OS ODL extensions module, which defines YANG extensions that you use to precisely specify how to render the output when you execute the RPC’s command in the CLI or when you request the RPC output in text format.

    Note

    Starting in Junos OS Release 17.4R1, the Junos OS YANG modules use a new naming convention for the module’s name, filename, and namespace.

  2. In the RPC input parameters, include a leaf statement with type enumeration, and use an enum statement to define a name for each style.

    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.

  3. In the RPC output statement, create separate junos-odl:style statements that define the CLI formatting for each style. The identifier for each style statement should match one of the style names defined within the enumerated leaf statement.

    Note

    Starting in Junos OS Release 17.3, the CLI formatting for a custom RPC is defined within the junos-odl:format extension statement, and junos-odl:format is a substatement to junos-odl:style. In earlier releases, the CLI formatting is defined using a container that includes the junos-odl:cli-format statement, and the junos-odl:style statement is included within that container.

  4. In the RPC’s action script, process the input argument, and emit the XML output for the requested style enclosed in a parent element with a tag name identical to the style name.

The following code outlines the general structure of the RPC and enclosing module. When you invoke the RPC in the CLI and include the input argument level and specify either brief or detail, Junos OS renders the output defined for that style.

To execute the RPC in the CLI, issue the command defined by the junos:command statement, and specify the style by including the appropriate command-line argument, which in this example is level.

user@host> cli-command level brief

Example: Defining Different Levels of Output

This example presents a simple custom YANG RPC and action script that determine if a host is reachable and print different levels of output depending on the user input.

Requirements

This example uses the following hardware and software components:

  • Device running Junos OS Release 17.3R1 or later that supports custom YANG modules.

Overview of the RPC and Action Script

The YANG module presented in this section defines a custom RPC to ping the specified host and return the result using different levels of output based on the user’s input. The YANG module rpc-style-test is saved in the rpc-style-test.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-host-status RPC. The <get-host-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 host-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-style-test.py to retrieve the information required by the RPC and return the XML output elements for each level of output 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 two input parameters, hostip and level. The hostip parameter is the host to check for reachability. The level parameter is used to select between the different styles for the RPC output. When the user executes the RPC, the user includes the target host’s IP address and a level, brief or detail. The action script defines the default value for level as 'brief', so if the user omits this argument, the RPC will print the output corresponding to the brief style.

The RPC also defines the output nodes that must be emitted by the corresponding action script. The root node is the <host-status-information> element, which encloses either the <brief> or the <detail> element, depending on the user input, along with the child output nodes specified for each level of output. Both levels of output include the <hostip> and <status> child elements, but the <detail> element also includes the <date> child element. The junos-odl:format statements define the formatting for the output that is displayed in the CLI. This node is not emitted in the output XML tree.

The action script pings the host to determine if it is reachable and sets the status based on the results. The script then constructs and prints the XML for the RPC output based on the specified level argument. The XML tree must exactly match the hierarchy defined in the RPC.

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

YANG Module

The YANG module, rpc-style-test.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-style-test.py.

Action Script

The following action script prints different levels of output based on the value of the level argument. The script defines a default value of 'brief' for the level argument so that if the user omits the argument, the brief style of output is the default.

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-style-test.yang action-script /var/tmp/rpc-style-test.py
  4. Add the YANG module and action script to a new YANG package.

    user@host> request system yang add package rpc-style-test module /var/tmp/rpc-style-test.yang action-script /var/tmp/rpc-style-test.py
  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 hostip input argument, and include the level argument for each different level of output.

user@host> show host-status hostip 198.51.100.1 level brief

You can view the corresponding XML by appending | display xml to the command.

user@host> show host-status hostip 198.51.100.1 level brief | display xml

Similarly, for the detailed output:

user@host> show host-status hostip 198.51.100.10 level detail
user@host> show host-status hostip 198.51.100.10 level detail | display xml

Meaning

When the RPC is executed, the action script is invoked. The action script prints the XML hierarchy for the given level of 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.