Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

 
ON THIS PAGE
 

Use the juniper.device.junos_command and juniper.device.junos_rpc Ansible Modules to Execute Commands and RPCs

You can use the juniper.device.junos_command and juniper.device.junos_rpc Ansible modules to execute operational mode commands and RPCs on devices running Junos OS and devices running Junos OS Evolved.

Juniper Networks provides Ansible modules that you can use to execute operational mode commands and remote procedure calls (RPCs) on Junos devcies. Table 1 outlines the modules. If you are already using a given set of modules from the juniper.device collection, use the modules for that set.

Table 1: Command and RPC Modules

Collection

Module Set

Module Name

juniper.device collection

juniper.device

juniper.device.command

juniper.device.rpc

junipernetworks.junos

juniper.device.junos_command

juniper.device.junos_rpc

The following sections discuss how to the use the juniper.device.junos_command and juniper.device.junos_rpc modules and what to expect in the module response. Table 2 briefly summarizes the modules' supported actions.

Table 2: Summary of junos_command and junos_rpc Actions
Module Action Module Arguments

Supported Ansible Connections
(ansible.netcommon.*)

junos_command

Execute one or more CLI commands

  • commands

  • netconf

  • network_cli

Execute one or more RPCs and optionally include RPC arguments

  • rpcs

  • netconf
Evaluate command or RPC output

  • commands or rpcs

  • wait_for

  • match (Optional)

  • netconf

junos_rpc

Execute an RPC and optionally include RPC arguments and attributes

  • rpc

  • args (Optional)

  • attrs (Optional)

  • netconf

Execute Commands with the junos_command Module

The juniper.device.junos_command module enables you to execute operational mode commands on Junos devices. The module requires one argument, commands, which can be a single command or a list of one or more commands to execute on the device.

The following playbook executes two commands on each device in the inventory group. The playbook displays the module response in standard output (stdout).

For information about the module’s response and output format, see Understanding the Module Response and Specify the Format for Command or RPC Output.

Execute RPCs with the junos_command or junos_rpc Module

The Junos XML API is an XML representation of Junos OS configuration statements and operational mode commands. It defines an XML equivalent for all statements in the Junos OS configuration hierarchy and many of the operational mode commands that you issue in the Junos OS CLI. Each operational mode command with a Junos XML counterpart maps to a request tag element and, if necessary, a response tag element. Request tags are used in RPCs within NETCONF or Junos XML protocol sessions to request information from a Junos device. The server returns the response using Junos XML elements enclosed within the corresponding response tag element.

Note:

For information about mapping CLI commands to RPC request tags, see the Junos XML API Explorer for operational tags.

The juniper.device.junos_command module and the juniper.device.junos_rpc module enable you to execute RPCs on Junos devices. The junos_command module enables you to execute multiple RPCs in a single task with the option to include inline RPC arguments. The junos_rpc module enables you to execute a single RPC with the option to include RPC arguments and attributes. The following sections show how to use the modules to execute RPCs.

junos_command Module

To use the junos_command module to execute RPCs, include the rpcs parameter. The rpcs parameter can be a single RPC request tag or a list of RPC request tags. You can optionally include any number of RPC arguments that are supported by that RPC. Specify the arguments inline as key=value pairs. The following playbook uses the junos_command module to execute multiple RPCs:

junos_rpc Module

To use the junos_rpc module to execute a single RPC, include the rpc parameter and specify the RPC to execute. The following playbook executes the get-software-information RPC on each device in the inventory group and displays the module response in stdout. The RPC is equivalent to the show version operational mode command.

junos_rpc Module with Arguments and Attributes

The junos_rpc module supports the args and attrs options. Use the args option to specify a dictionary of RPC arguments and values. If an individual RPC argument does not require a value, set its value equal to true. Use the attrs option to specify a dictionary of attributes for the RPC.

Note:

You can use a hyphen or an underscore in RPC argument names. For example, you can represent the interface-name argument as interface-name or interface_name.

The following playbook executes the get-interface-information RPC on each device in the inventory group and displays the module response in stdout. The module arguments include the args option to request terse level output for the lo0.0 interface only. The RPC is equivalent to the show interfaces lo0.0 terse operational mode command.

The following playbook executes the <get-configuration database="candidate" inherit="inherit"/> RPC on each device in the inventory group. The attrs option includes the database and inherit RPC attributes. The RPC returns the post-inheritance candidate configuration for each device.

For information about the module’s response and output format, see Understanding the Module Response and Specify the Format for Command or RPC Output.

Evaluate Command and RPC Output

The junos_command module enables you to evaluate output as part of the task. If the specified conditions are false, the task fails, and the playbook skips the remaining tasks for that device. A playbook might evaluate the output in order to determine whether to perform the remaining tasks on a device. For example, if the model or Junos OS version does not match a specified condition, the playbook might skip subsequent installation or configuration tasks for that device.

You can use junos_command to evaluate command or RPC output. However, the following requirements must be met:

  • The Ansible connection must be set to ansible.netcommon.netconf.

  • The match conditions must use the appropriate syntax for the requested format.

You use the wait_for argument to specify the conditions to evaluate. If you define multiple conditions, you can include the match argument to define the match policy. Set match to all to indicate that all conditions must be satisfied. Alternatively, set match to any if only one condition must be satisfied.

You can evaluate conditions in the output of multiple commands. To define conditions for different command output, reference the result for that command, for example, result[0] for the first command, result[1] for the second command, and so on.

You can also evaluate conditions using any output format. However, the conditions must use the appropriate syntax for that format. For example, for text and set formats, use string operators like contains or matches. For XML and JSON output, specify the appropriate dictionary path.

The following playbook executes the show version command and checks for the model number and version number in the command output, which defaults to text format.

The task includes match: all. Thus, the task passes for a given device if all of the conditions are true. If the conditions are not met, the task fails with an error, and the playbook ignores any remaining tasks for that device.

In the following output, the first device matches all of the specified criteria and the task succeeds. The second device does not match one of the conditions and thus the task fails.

Similarly, you can evaluate RPC output. The following playbook uses the junos_command module with the equivalent RPC to perform the same evaluation as in the previous example. The task requests text output instead of the default RPC output format, which is XML.

To evaluate XML output, update the wait_for conditions to use the appropriate dictionary paths.

Similarly, for JSON output:

Understanding the Module Response

The junos_command and junos_rpc modules store the RPC reply from the device within several different keys in the module response. Table 3 outlines the different fields. The output returns some fields only for certain formats.

Table 3: junos_command and junos_rpc Output
Module Output Field Description
junos_command output

For XML format only, the XML responses transformed to JSON.
stdout

A list with the responses for the requested commands.
stdout_lines

The stdout value split into a list.
junos_rpc output The RPC reply in the requested format.
output_lines For text format only, the text output split into lines.
xml

The XML RPC reply string.

Specify the Format for Command or RPC Output

When you use the junos_command module to execute commands, the default output format is text. When you use the junos_command module or the junos_rpc module to execute RPCs, the default format is XML.

To specify a different output format, include the parameter specific to that module, and set the value equal to the required format. Table 4 outlines the parameters, supported formats, and default format for each module. If you use the junos_command module to execute multiple commands or RPCs, you can specify only a single format.

Table 4: junos_command and junos_rpc Output Format
Module

Module
Argument

 Supported Values
junos_command display

  • json

  • text (default for commands)

  • set (configuration output only)

  • xml (default for rpcs)
junos_rpc output

  • json

  • text

  • xml (default)

The following playbook uses the junos_command module to execute two RPCs on each device in the inventory group. The playbook requests text format for the output of all executed RPCs.

In the module's response, the stdout and stdout_lines keys contain the RPC reply in text format instead of the default XML output.

The following playbook uses the junos_rpc module to execute an RPC on each device in the inventory group. The playbook requests text format for the RPC output.

For junos_rpc, the module's response includes the output, output_lines, and xml keys. In this case, the module returns output_lines only when you request text format.

Related Documentation