Use the juniper.device.command and juniper.device.rpc
Ansible Modules to Execute Commands and RPCs on Junos Devices
You can use the juniper.device.command and
juniper.device.rpc Ansible modules to execute operational mode commands
and RPCs on Junos devices.
Juniper Networks provides Ansible modules that you can use to execute operational mode
commands and remote procedure calls (RPCs) on devices running Junos OS and devices
running Junos OS Evolved. 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.
|
Collection |
Module Set |
Module Name |
|---|---|---|
|
|
|
|
|
|
The following sections discuss how to the use the juniper.device.command
and juniper.device.rpc modules, parse the module response, specify the
output format, and save the output to a file.
To more easily extract targeted data from operational output, you can also use the
juniper.device.table module with custom or predefined Junos
PyEZ operational tables. For more information, see Use Ansible with Junos PyEZ Tables to Retrieve Operational Information from Junos Devices.
How to Execute Commands with the juniper.device.command
Module
The juniper.device.command module enables you to execute
operational mode commands on Junos devices. The module requires one argument,
commands, which is a list of one or more Junos OS
operational mode commands to execute on the device.
The following playbook executes two operational mode commands on each device in the inventory group. The playbook displays the module response in standard output (stdout).
---
- name: Get device information
hosts: dc1
connection: local
gather_facts: no
tasks:
- name: Get software and uptime information
juniper.device.command:
commands:
- "show version"
- "show system uptime"
register: junos_result
- name: Print response
ansible.builtin.debug:
var: junos_result
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.device.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.
The juniper.device.rpc module enables you to execute RPCs on
Junos devices. The module requires one argument, rpcs, which is
a list of one or more Junos OS RPCs to execute on the device.
The following playbook executes the get-interface-information
RPC on each device in the inventory group and displays the module response in
stdout. The RPC is equivalent to the show interfaces
operational mode command.
---
- name: Execute RPC
hosts: dc1
connection: local
gather_facts: no
tasks:
- name: Get interface information
juniper.device.rpc:
rpcs: "get-interface-information"
register: junos_result
- name: Print response
ansible.builtin.debug:
var: junos_result
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 juniper.device.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
-
A list of dictionaries that supplies 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 kwargs list item equal to an empty dictionary
{}. If an individual RPC argument does not require a value,
set its value equal to true.
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 stdout. The
get-interface-information RPC requests terse level output
for the lo0.0 interface. 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.
---
- name: Get Device Information
hosts: dc1a
connection: local
gather_facts: no
tasks:
- name: Get device information
juniper.device.rpc:
rpcs:
- "get-interface-information"
- "get-lldp-interface-neighbors"
- "get-software-information"
kwargs:
- interface_name: "lo0.0"
terse: true
- interface_device: "ge-0/0/0"
- {}
register: junos_result
- name: Print response
ansible.builtin.debug:
var: junos_result
Understanding the Module Response
The juniper.device.command and juniper.device.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 present 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. It includes all the keys that are returned for that command or RPC.
For example, the following response corresponds to executing a single RPC:
"junos_result": {
"attrs": null,
"changed": false,
"failed": false,
"format": "xml",
"kwargs": null,
"msg": "The RPC executed successfully.",
"parsed_output": {
"interface-information": {
"physical-interface": [
[...output omitted...]
}
},
"rpc": "get-interface-information",
"stdout": "<interface-information style=\"normal\">\n <physical-interface>\n
[...output omitted...] </physical-interface>\n</interface-information>\n"
"stdout_lines": [
"<interface-information style=\"normal\">",
" <physical-interface>",
[...output omitted...]
" </physical-interface>",
"</interface-information>"
]
}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.
tasks:
- name: Get interface information
juniper.device.rpc:
rpcs: "get-interface-information"
return_output: false
register: junos_result
How to Specify the Format for the Command or RPC Output
The 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 module returns the command output in text format,
and the 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 required format. Supported formats
include:
-
json -
text -
xml
The formats parameter takes either a string or a list of
strings. When you specify only a single format, all executed commands or RPCs
use that format. To specify a different format for each command or RPC, set the
formats argument to a list of the required formats. The
number of formats must be the same as the number of commands or RPCs.
The following playbook executes two RPCs on each device in the inventory group. The playbook requests text format for the output of all executed RPCs.
---
- name: Get device information
hosts: dc1
connection: local
gather_facts: no
tasks:
- name: Get software and system uptime information
juniper.device.rpc:
rpcs:
- "get-software-information"
- "get-system-uptime-information"
formats: text
register: junos_result
- name: Print response
ansible.builtin.debug:
var: junos_result
In the module's response, the stdout and
stdout_lines keys contain the RPC reply in text format.
The following playbook executes two RPCs on each device in the inventory group. The module requests the output for the first RPC in text format and the output for the second RPC in JSON format.
---
- name: Get device information
hosts: dc1
connection: local
gather_facts: no
tasks:
- name: Get software and system uptime information
juniper.device.rpc:
rpcs:
- "get-software-information"
- "get-system-uptime-information"
formats:
- "text"
- "json"
register: junos_result
- name: Print response
ansible.builtin.debug:
var: junos_result
How to Save the Command or RPC Output to a File
When you use the juniper.device.command or
juniper.device.rpc module, you can save the returned data
to a file on the local Ansible control node. To save the data, include the
dest or dest_dir module argument. 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.
If you save the data to a file and do not want to duplicate the 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. Omitting the keys might be
necessary if the device returns a significant amount of data.
The following sections outline how to use the dest_dir and
dest options.
dest_dir
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. The playbook saves the output for each RPC for each device in a separate file in the playbook directory on the Ansible control node.
---
- name: Get device information
hosts: dc1
connection: local
gather_facts: no
tasks:
- name: Get software and uptime information
juniper.device.rpc:
rpcs:
- "get-software-information"
- "get-system-uptime-information"
dest_dir: "{{ playbook_dir }}"
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. The playbook saves the output for each command for each device in a separate file in the playbook directory on the Ansible control node:
---
- name: Get device information
hosts: dc1
connection: local
gather_facts: no
tasks:
- name: Get software and uptime information
juniper.device.command:
commands:
- "show version"
- "show system uptime"
dest_dir: "{{ playbook_dir }}"
The resulting output files for host dc1a.example.net are:
-
dc1a.example.net_show_version.text
-
dc1a.example.net_show_system_uptime.text
dest
You can use the dest option to specify the output file to
which all command or RPC output for a target node is saved on the local
Ansible control node. 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 playbook saves the output for all RPCs in a separate file for each device. The file is placed in the playbook directory on the Ansible control node. Each file is uniquely identified by the device hostname.
---
- name: Get device information
hosts: dc1
connection: local
gather_facts: no
tasks:
- name: Get software and uptime information
juniper.device.rpc:
rpcs:
- "get-software-information"
- "get-system-uptime-information"
dest: "{{ inventory_hostname }}-system-information.xml"
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.