Use Ansible to Execute Commands and RPCs on Junos Devices
SUMMARY Use the Juniper Networks 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 Junos devices. Table 1 outlines the modules.
|
Content Set |
Module Name |
|---|---|
|
|
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.
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 Networks Modules
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 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.
---
- 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 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 Junos device. The server returns the response using Junos XML elements enclosed within the response tag element.
The juniper.device.rpc module enables you to execute RPCs on
Junos devices. The modules require 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
standard output. , The RPC is equivalent to the show interfaces
operational mode command. In this example, the rpc module
authenticates with the device by using SSH keys in the default location.
---
- 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 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 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 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.
---
- 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 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.
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 desired format. Supported formats
include:
-
json -
text -
xml
The formats parameter takes either a string or a list of
strings. When you execute multiple commands or RPCs and specify only 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:
---
- 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
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:
---
- 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 and
juniper.device.rpc modules to execute a command or RPC on a
device, you can save the returned data to 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.
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 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 and 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 and 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
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.
---
- 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.