Create 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 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 devices running Junos OS. 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
}
}
}
}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.
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.
import junos-extension {
prefix junos;
}
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.
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.
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.
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
commandstatement and its substatements.junos:command "cli-command" { junos:action-execute { junos:script "action-script-filename"; } }In Junos OS Release 17.2 and earlier, define the
action-executeandscriptstatements, and optionally define thecommandstatement.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 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.
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 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.
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.
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:formatstatement, 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 } }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-formatstatement.container container-name-format { junos-odl:cli-format; // CLI formatting for the parent container }
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 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
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.
empty when executing the RPC’s command in the
Junos OS CLI.action-execute statement
is a substatement to command.junos-odl:format extension statement.