Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

 

Creating Custom RPCs in YANG for Devices Running Junos OS

 

Juniper Networks provides YANG modules that define the remote procedure calls (RPCs) for Junos OS operational commands. Starting in Junos OS Release 16.1R3, you can also create YANG data models that define custom RPCs for supported 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. When you extend the operational command hierarchy with a custom YANG RPC, you must also supply an action script that serves as the handler for the RPC. The RPC definition references the action script, which is invoked when you execute the RPC.

This topic outlines the general steps for creating a YANG module that defines a custom RPC for devices running Junos OS. For information about creating an RPC action script and customizing the RPC’s CLI output see Creating Action Scripts for YANG RPCs on Devices Running Junos OS and Understanding Junos OS YANG Extensions for Formatting RPC Output.

This section presents a generic template for a YANG module that defines an RPC for devices running Junos OS. The template is followed by a detailed explanation of the different sections and statements in the template.

RPCs are defined within modules. The module name should be descriptive and indicate the general purpose of the RPCs that are included in that module, and the module namespace must be unique.

Note

As per RFC 6020, YANG - A Data Modeling Language for the Network Configuration Protocol (NETCONF), the module name and the base name of the file in which the module resides must be identical. For example, if the module name is get-if-info, the module’s filename must be get-if-info.yang.

The module must import the Junos OS DDL extensions module and define a prefix. The extensions module includes YANG extensions that are required in the definition of RPCs executed on devices running Junos OS.

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.

If any of the RPCs in the module render formatted ASCII output, the module must import the Junos OS ODL extensions module and define a prefix. The ODL extensions module defines YANG extensions that you use to precisely specify how to render the output when you execute the operational command for that RPC in the CLI or when you request the RPC output in text format.

Include the organization responsible for the module as well as a description of the module.

Within the module, you can define one or more RPCs, each with a unique name. The RPC name is used to remotely execute the RPC, and thus should clearly indicate the RPC’s purpose. The RPC purpose can be further clarified in the description statement. If you also define a CLI command for the RPC, the CLI displays the RPC description in the context-sensitive help for that command listing.

Within the RPC definition, define the command, action-execute, and script statements, which are Junos OS DDL extension statements. The command statement defines the operational command that you use to execute the RPC in the Junos OS CLI. To execute the RPC remotely, use the RPC name for the request tag.

The action-execute statement and script substatement must be defined for every RPC. The script substatement defines the name of the action script that is invoked when you execute the RPC. You must define one and only one action script for each RPC.

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.

  • In Junos OS Release 17.3 and later, define the command statement and its substatements.

  • In Junos OS Release 17.2 and earlier, define the action-execute and script statements, and optionally define the command statement.

Note

You must add the YANG module and action script to the device as part of a new or existing YANG package by issuing the request system yang add or request system yang update command. Thus, you only need to provide the name and not the path of the action script for the junos:script statement.

Note

If your action script is written in Python, you must configure the [edit system scripts language python] statement on each device where the script will be executed.

Input parameters to the RPC operation are defined within the optional input statement. When you execute the RPC, Junos OS invokes the RPC’s action script and passes all of the input parameters to the script.

Note

Starting in Junos OS Release 19.2R1, custom YANG RPCs support input parameters of type empty when executing the RPC’s command in the Junos OS CLI. In earlier releases, input parameters of type empty are only supported when executing the RPC in a NETCONF or Junos XML protocol session.

The optional output statement encloses the output parameters to the RPC operation. The output statement can include one top-level root container. It is a good practice to correlate the name of the root container and the RPC name. For example, if the RPC name is get-xyz-information, the container name might be xyz-information. Substatements to the output statement define nodes under the RPC’s output node. In the XML output, this would translate into XML elements under the <rpc-reply> element.

Within the root container, you can include leaf and container statements. Leaf statements describe the data included in the RPC output for that container.

By default, the format for RPC output is XML. You can also define formatted ASCII output that is displayed when you execute the operational command for that RPC in the CLI or when you request the RPC output in text format.

Note

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

  • Starting in Junos OS Release 17.3, you define the CLI formatting by defining a junos-odl:format statement, which is a Junos OS ODL extension statement.

  • Prior to Junos OS Release 17.3, you define the CLI formatting for a given container within a child container that includes the junos-odl:cli-format statement.

Within the statement or container that defines the CLI formatting, you can customize the RPC’s CLI output by using statements defined in the Junos OS ODL extensions module. For more information about rendering formatted ASCII output, see Customizing YANG RPC Output on Devices Running Junos OS. You can also stipulate when the data in a particular container is emitted in an RPC's CLI output. For information about constructing different levels of output for the same RPC, see Defining Different Levels of Output in Custom YANG RPCs for Devices Running Junos OS.

To use the RPC on a device running Junos OS, download the module and action script to the device, and add the files to a new or existing YANG package by issuing the request system yang add or request system yang update operational command. To execute the RPC in the CLI, issue the command defined by the junos:command statement. To execute the RPC remotely, use the RPC name in an RPC request operation.

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.

When you execute the RPC in the CLI by issuing the command defined by the junos:command statement, the device displays the RPC output in the CLI format defined by the RPC. If the RPC does not define CLI formatting, by default, no output is displayed for that RPC in the CLI. However, you can still display the XML output for that RPC in the CLI by appending the | display xml filter to the command.

For more information about YANG RPCs, see RFC 6020, YANG - A Data Modeling Language for the Network Configuration Protocol (NETCONF), and related RFCs.

Release History Table
Release
Description
Starting in Junos OS Release 19.2R1, custom YANG RPCs support input parameters of type empty when executing the RPC’s command in the Junos OS CLI.
Starting in Junos OS Release 17.3, the action-execute statement is a substatement to command.
Starting in Junos OS Release 17.3, the CLI formatting for a custom RPC is defined within the junos-odl:format extension statement.
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.