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

 

Juniper Networks provides support for using Ansible to manage devices running Junos OS. The juniper_junos_command and juniper_junos_rpc modules in the Juniper.junos Ansible role enable you to execute operational commands and RPCs on devices running Junos OS to perform operations or retrieve information. 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 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.

Executing Commands with the juniper_junos_command Module

The juniper_junos_command module enables you to execute CLI commands on devices running Junos OS. The module requires one argument, commands, which is a list of one or more Junos OS CLI commands to execute on the device.

Note

Starting in Ansible for Junos OS Release 2.0.0, the juniper_junos_command module replaces the functionality of the junos_cli module.

The following playbook executes two CLI commands on each device in the inventory group, and displays the module response in standard output.

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

Executing RPCs with the juniper_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 commands that you issue in CLI operational mode. 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 juniper_junos_rpc module enables you to execute RPCs on devices running Junos OS. The module requires one argument, rpcs, which is a list of one or more Junos OS RPCs to execute on the device.

Note

Starting in Ansible for Junos OS 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 CLI command, on each device in the inventory group and displays the module response in standard output.

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 Specifying the Format for the Command or RPC Output.

The juniper_junos_rpc module supports 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 elements 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_junos_command and juniper_junos_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 described here. The parsed_output key is only returned when the format of the data is XML or JSON.

  • 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

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 the module’s argument list.

Specifying the Format for the Command or RPC Output

The juniper_junos_command and juniper_junos_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 juniper_junos_command module returns the command output in text format, and the juniper_junos_rpc module returns 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:

Saving the Command or RPC Output to a File

When you use the juniper_junos_command or juniper_junos_rpc module to execute a command or RPC on a device, you can save the returned data in a file on the local Ansible control machine by including the dest or dest_dir module arguments. If an output file already exists with the target name, the module overwrites the file.

To specify the directory on the local Ansible control machine 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 machine:

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 machine:

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 the command or RPC output is saved on the local Ansible control machine, include the dest argument, and define the filename or the full path of the file. 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 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 machine. 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 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 Ansible for Junos OS Release 2.0.0, the juniper_junos_command module replaces the functionality of the junos_cli module.
Starting in Ansible for Junos OS Release 2.0.0, the juniper_junos_rpc module replaces the functionality of the junos_rpc module.