Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

Using Ansible to Execute Commands and RPCs on Devices Running Junos OS

 
Summary

Use the Juniper Networks Ansible modules to execute operational mode commands and RPCs on devices running Junos OS.

Juniper Networks supports using Ansible to manage devices running Junos OS and provides Ansible modules that enable you to execute operational mode commands and remote procedure calls (RPCs) on the devices. Table 1 outlines the modules.

Table 1: Command and RPC Modules

Content Set

Module Name

juniper.device collection

command

rpc

Juniper.junos role

juniper_junos_command

juniper_junos_rpc

The following sections discuss how to the use the modules, parse the module response, specify the output format, and save the output to a file.

Note

To more easily extract targeted data from operational output, you can also use the table or juniper_junos_table module with custom or predefined Junos PyEZ operational tables. For more information, see Using Ansible with Junos PyEZ Tables to Retrieve Operational Information from Devices Running Junos OS.

How to Execute Commands with the Juniper Networks Modules

The command and juniper_junos_command modules enable you to execute operational mode commands on devices running Junos OS. The modules require one argument, commands, which is a list of one or more Junos OS operational mode commands to execute on the device.

Note

Starting in Juniper.junos Release 2.0.0, the juniper_junos_command module replaces the functionality of the junos_cli module.

The following playbook executes two operational mode commands on each device in the inventory group and displays the module response in standard output. In this example, the command module authenticates with the device by using SSH keys in the default location.

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

How to Execute RPCs with the Juniper Networks Modules

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 remote procedure calls (RPCs) within NETCONF or Junos XML protocol sessions to request information from a device running Junos OS. The server returns the response using Junos XML elements enclosed within the response tag element.

The rpc and juniper_junos_rpc modules enable you to execute RPCs on devices running Junos OS. The modules require one argument, rpcs, which is a list of one or more Junos OS RPCs to execute on the device.

Note

Starting in Juniper.junos Release 2.0.0, the juniper_junos_rpc module replaces the functionality of the junos_rpc module.

The following playbook executes the get-interface-information RPC, which is equivalent to the show interfaces operational mode command, on each device in the inventory group and displays the module response in standard output. In this example, the rpc module authenticates with the device by using SSH keys in the default location.

Note

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

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

The rpc and juniper_junos_rpc modules support the kwargs option, which enables you to specify keyword arguments and values for the RPCs. The value of kwargs can be a single dictionary of keywords and values, or it can be a list of dictionaries that supply arguments for multiple RPCs. There must be a one-to-one correspondence between the items in the kwargs list and the RPCs in the rpcs list. If you execute multiple RPCs, and an RPC does not require any arguments, set the corresponding list item equal to an empty dictionary {}. If an individual RPC argument does not require a value, set its value equal to True.

Note

You must use underscores in RPC arguments in place of hyphens, which can cause exceptions or errors in certain circumstances.

The following playbook executes the specified RPCs on each device in the inventory group and displays the module response in standard output. The get-interface-information RPC requests terse level output for the lo0.0 interface, and the get-lldp-interface-neighbors RPC requests information for the ge-0/0/0 interface. The get-software-information RPC uses an empty dictionary to execute the RPC with no additional arguments.

Understanding the Module Response

The Juniper Networks command and RPC modules store the RPC reply from the device within several different keys in the module response. The data for each key is structured as follows:

  • stdout—RPC reply is a single multi-line string.

  • stdout_lines—RPC reply is a list of single line strings.

  • parsed_output—RPC reply is parsed into a JavaScript Object Notation (JSON) data structure. This key is only returned when the format of the data is XML or JSON.

If the module executes a single command or RPC, the module’s response places the returned keys at the top level. If the module executes multiple commands or RPCs, the module’s response instead includes a results key, which is a list of dictionaries. Each element in the list corresponds to a single command or RPC and includes all the keys that would be returned for that command or RPC.

In some instances, command or RPC output can be extensive, and it might be necessary to suppress the output in the module’s response. To omit the output keys in the module’s response, include return_output: false in that module’s argument list.

How to Specify the Format for the Command or RPC Output

The Juniper Networks command and RPC modules store the RPC reply from the device within several different keys in the module response: stdout, stdout_lines, and parsed_output. The parsed_output key, which is only present when the command or RPC output format is XML or JSON, contains data that is parsed into a JSON data structure.

The stdout and stdout_lines keys contain data in the default format defined for the module. By default, the command and juniper_junos_command modules return the command output in text format, and the rpc and juniper_junos_rpc modules return the RPC output in XML format. To specify a different output format, include the formats argument, and set the value equal to the desired format. To request text format, Junos XML elements, or JSON format, use 'text', 'xml', or 'json' respectively. The requested format must be supported by the device on which the command or RPC is executed.

The formats parameter takes either a string or a list of strings. When you execute multiple commands or RPCs and only specify a single format, the output format is the same for all executed commands and RPCs. To specify a different format for the output of each command or RPC, set the formats argument to a list of the desired formats. The list must specify the same number of formats as there are commands or RPCs.

The following playbook executes two RPCs on each device in the inventory group and requests text format for the output of all executed RPCs:

When the playbook is executed, the stdout and stdout_lines keys in the module response contain the RPC reply in text format.

The following playbook executes two RPCs on each device in the inventory group and requests the output for the first RPC in text format and the output for the second RPC in JSON format:

How to Save the Command or RPC Output to a File

When you use the Juniper Networks modules to execute a command or RPC on a device, you can save the returned data in a file on the local Ansible control node by including the dest or dest_dir module arguments. Whereas the dest_dir option saves the output for each command or RPC in separate files for a device, the dest option saves the output for all commands and RPCs in the same file for a device. If an output file already exists with the target name, the module overwrites the file.

To specify the directory on the local Ansible control node where the retrieved data is saved, include the dest_dir argument, and define the path to the target directory. The module stores the output for each command or RPC executed on a device in a separate file named hostname_name.format where:

  • hostname—Hostname of the device on which the command or RPC is executed.

  • name—Name of the command or RPC executed on the managed device. The module replaces spaces in the command name with underscores ( _ ).

  • format—Format of the output, which can be json, text, or xml.

The following playbook executes two RPCs on each device in the inventory group and saves the output for each RPC for each device in a separate file in the playbook directory on the Ansible control node:

The resulting output files for host dc1a.example.net are:

  • dc1a.example.net_get-software-information.xml

  • dc1a.example.net_get-system-uptime-information.xml

Similarly, the following playbook executes the equivalent commands on each device in the inventory group and saves the output for each command for each device in a separate file in the playbook directory on the Ansible control node:

The resulting output files for host dc1a.example.net are:

  • dc1a.example.net_show_version.text

  • dc1a.example.net_show_system_uptime.text

To specify the path and filename to which all command or RPC output for a target node is saved on the local Ansible control node, include the dest argument, and define the filename or the full path of the file. If you include the dest argument, but omit the directory, the files are saved in the playbook directory. If you execute commands or RPCs on multiple devices, the dest argument must include a variable such as {{ inventory_hostname }} to differentiate the filename for each device. If you do not differentiate the filenames, the output file for each device will overwrite the output file of the other devices.

The following playbook executes RPCs on each device in the inventory group. The output for all RPCs is stored in a separate file for each device, and the file is placed in the playbook directory on the Ansible control node. Each file is uniquely identified by the device hostname.

For example, the resulting output file for host dc1a.example.net is dc1a.example.net-system-information.xml and contains the output for all RPCs executed on the device.

If you are saving the data to a file and do not want to duplicate the command or RPC output in the module’s response, you can optionally include return_output: false in the module’s argument list. Setting return_output to false causes the module to omit the output keys in the module’s response. Doing this might be necessary if the devices return a significant amount of data.

Release History Table
Release
Description
Starting in Juniper.junos Release 2.0.0, the juniper_junos_command module replaces the functionality of the junos_cli module.
Starting in Juniper.junos Release 2.0.0, the juniper_junos_rpc module replaces the functionality of the junos_rpc module.