Create Custom RPCs in YANG for Devices Running Junos OS
You can also create YANG data models that define custom RPCs for devices running Junos OS or devices running Junos OS Evolved.
Juniper Networks provides YANG modules that define the remote procedure calls (RPCs) for operational commands on devices running Junos OS and devices running Junos OS Evolved. You can also create YANG data models that define custom RPCs for supported devices. 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; when you execute the RPC, the device invokes the script.
This topic outlines the general steps for creating a YANG module that defines a custom RPC for devices running Junos OS or devices running Junos OS Evolved. For information about creating an RPC action script and customizing the RPC’s CLI output see Create Action Scripts for YANG RPCs on Junos Devices 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 Junos devices. The template is followed by a detailed explanation of the different sections and statements in the template.
module module-name {
namespace "namespace";
prefix prefix;
import junos-extension {
prefix junos;
}
import junos-extension-odl {
prefix junos-odl;
}
organization
"organization";
description
"module-description";
rpc rpc-name {
description "RPC-description";
junos:command "cli-command" {
junos:action-execute {
junos:script "action-script-filename";
}
}
input {
leaf input-param1 {
type type;
description description;
}
leaf input-param2 {
type type;
description description;
}
// additional leaf definitions
}
output {
container output-container-name {
container container-name {
leaf output-param1 {
type type;
description description;
// optional formatting statements
}
// additional leaf definitions
junos-odl:format container-name-format {
// CLI formatting for the parent container
}
}
// Additional containers
}
}
}
}You define RPCs within modules. The module name should be descriptive and indicate the general purpose of the RPCs defined in that module. The module namespace must be unique.
module module-name {
namespace "namespace";
prefix prefix;
}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 or devices running Junos OS Evolved.
import junos-extension {
prefix junos;
}
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 text output. The device emits text output when you execute the operational command for that RPC in the CLI or when you request the RPC output in text format.
import junos-extension-odl {
prefix junos-odl;
}
Include the organization responsible for the module as well as a description of the module.
organization
"organization";
description
"module-description";
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.
rpc rpc-name {
description "RPC-description";
}
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.
Every RPC must define the action-execute statement and script
substatement. 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.
junos:command "cli-command" {
junos:action-execute {
junos:script "action-script-filename";
}
}
You must add the YANG module and action script to the device as part of a new or existing YANG
package. Thus, you only need to provide the name and not the path of the action
script for the junos:script statement.
If your action script is written in Python, you must enable the device to execute unsigned Python
scripts by configuring the language python or language
python3 statement under the [edit system scripts]
hierarchy level on each device where you will execute the script.
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.
input {
leaf input-param1 {
type type;
description description;
}
leaf input-param2 {
type type;
description description;
}
// additional leaf definitions
}
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.
output {
container output-container-name {
...
}
}
Within the root container, you can include leaf and container statements.
Leaf statements describe the data included in the RPC output for that
container.
output {
container output-container-name {
container container-name {
leaf output-param1 {
type type;
description description;
}
// additional leaf definitions
}
}
}
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.
You define the CLI formatting by defining a junos-odl:format statement,
which is a Junos OS ODL extension statement.
output {
container output-container-name {
container container-name {
leaf output-param1 {
type type;
description description;
// optional formatting statements
}
// additional leaf definitions
junos-odl:format container-name-format {
// CLI formatting for the parent container
}
}
// Additional containers
}
}
Within the 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 Customize 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 Define Different Levels of Output in Custom YANG RPCs for Junos Devices.
To use the RPC on a device running Junos OS:
- Download the module and action script to the device.
- Add the files to a new or existing YANG package by issuing the
request system yang addorrequest system yang updateoperational command. - Execute the RPC.
- To execute the RPC in the CLI, issue the command defined by the
junos:commandstatement. - To execute the RPC remotely, use the RPC name in an RPC request operation.
- To execute the RPC in the CLI, issue the command defined by the
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.
Change History Table
Feature support is determined by the platform and release you are using. Use Feature Explorer to determine if a feature is supported on your platform.
empty when executing the RPC’s command in the
Junos OS CLI.