juniper_junos_rpc

Execute one or more NETCONF RPCs on a Junos device

New in version 2.0.0.

Synopsis

  • Execute one or more NETCONF RPCs on a Junos device.
  • Use the | display xml rpc modifier to determine the equivalent RPC name for a Junos CLI command. For example, show version | display xml rpc reveals the equivalent RPC name is get-software-information.

Requirements

The following software packages must be installed on hosts that execute this module:

Module-specific Options

The following options may be specified for this module:

parameter type required default choices comments
attrs
dict or list of dict no none
The attributes and values to the RPCs specified by the rpcs option. The value of this option can either be a single dictionary of keywords and values, or a list of dictionaries containing keywords and values.
There is a one-to-one correspondence between the elements in the kwargs list and the RPCs in the rpcs list. In other words, the two lists must always contain the same number of elements.

aliases: attr
dest
path no None
The path to a file, on the Ansible control machine, where the output of the RPC will be saved.
The file must be writeable. If the file already exists, it is overwritten.
When tasks are executed against more than one target host, one process is forked for each target host. (Up to the maximum specified by the forks configuration. See forks for details.) This means that the value of this option must be unique per target host. This is usually accomplished by including {{ inventory_hostname }} in the dest value. It is the user's responsibility to ensure this value is unique per target host.
For this reason, this option is deprecated. It is maintained for backwards compatibility. Use the dest_dir option in new playbooks. The dest and dest_dir options are mutually exclusive.

aliases: destination
dest_dir
path no None
The path to a directory, on the Ansible control machine, where the output of the RPC will be saved. The output will be logged to a file named {{ inventory_hostname }}_rpc.format in the dest_dir directory.
The destination file must be writeable. If the file already exists, it is overwritten. It is the users responsibility to ensure a unique dest_dir value is provided for each execution of this module within a playbook.
The dest_dir and dest options are mutually exclusive. The dest_dir option is recommended for all new playbooks.

aliases: destination_dir, destdir
filter
str no none
This argument only applies if the rpcs option contains a single RPC with the value get-config. When used, this value specifies an XML filter used to restrict the portions of the configuration which are retrieved. See the PyEZ get_config method for details on the value of this option.

aliases: filter_xml
formats
str or list of str no xml
  • text
  • xml
  • json
The format of the reply for the RPCs specified by the rpcs option.
The specified format(s) must be supported by the target Junos device.
The value of this option can either be a single format, or a list of formats. If a single format is specified, it applies to all RPCs specified by the rpcs option. If a list of formats are specified, there must be one value in the list for each RPC specified by the rpcs option.

aliases: format, display, output
kwargs
dict or list of dict no none
The keyword arguments and values to the RPCs specified by the rpcs option. The value of this option can either be a single dictionary of keywords and values, or a list of dictionaries containing keywords and values.
There must be a one-to-one correspondence between the elements in the kwargs list and the RPCs in the rpcs list. In other words, the two lists must always contain the same number of elements. For RPC arguments which do not require a value, specify the value of True as shown in the :ref:`juniper_junos_rpc-examples-label`.

aliases: kwarg, args, arg
return_output
bool no True
  • yes
  • no
Indicates if the output of the RPC should be returned in the module's response. You might want to set this option to false, and set the dest_dir option, if the RPC output is very large and you only need to save the output rather than using it's content in subsequent tasks/plays of your playbook.
rpcs
list yes none
A list of one or more NETCONF RPCs to execute on the Junos device.

aliases: rpc

Examples

---
- name: Examples of juniper_junos_rpc
  hosts: junos-all
  connection: local
  gather_facts: no
  roles:
    - Juniper.junos

  tasks:
    - name: Execute single get-software-information RPC.
      juniper_junos_rpc:
        rpcs: "get-software-information"
      register: response
    - name: Print the RPC's output as a single multi-line string.
      debug:
        var: response.stdout

###### OLD EXAMPLES ##########
- junos_rpc:
  host={{ inventory_hostname }}
  rpc=get-interface-information
  dest=get_interface_information.conf
  register=junos

- junos_rpc:
  host={{ inventory_hostname }}
  rpc=get-interface-information
  kwargs="interface_name=em0"
  format=xml/text/json
  dest=get_interface_information.conf
  register=junos

# Example to fetch device configuration
- name: Get Device Configuration
  junos_rpc:
    host={{ inventory_hostname }}
    rpc=get-config
    dest=get_config.conf

# Fetch configuration over console server connection using PyEZ >= 2.0
- name: Get Device Configuration
  junos_rpc:
    host={{ inventory_hostname }}
    port=7005
    mode='telnet'
    rpc=get-config
    dest=get_config.conf

# Example to fetch device configuration
- name: Get Device Configuration for interface
  junos_rpc:
    host={{ inventory_hostname }}
    rpc=get-config
    filter_xml="<configuration><interfaces/></configuration>"
    dest=get_config.conf
  register: junos

# Example to fetch configuration in json for >=14.2
# and use it with rpc_reply
- name: Get Device Configuration
  hosts: all
  roles:
    - Juniper.junos
  connection: local
  gather_facts: no
  tasks:
    - name: Get interface information
      junos_rpc:
        host: "{{ inventory_hostname }}"
        rpc: get-interface-information
        kwargs:
          interface_name: em0
          media: True
        format: json
        dest: get_interface_information.conf
      register: junos

    - name: Print configuration
      debug: msg="{{ junos.rpc_reply }}"
###### OLD EXAMPLES ##########

Return Values

name description returned type sample
attrs
The RPC attributes and values from the list of dictionaries in the attrs option. This will be none if no attributes are applied to the RPC.
always dict
changed
Indicates if the device's state has changed. Since this module doesn't change the operational or configuration state of the device, the value is always set to false.
You could use this module to execute an RPC which changes the operational state of the the device. For example, clear-ospf-neighbor-information. Beware, this module is unable to detect this situation, and will still return a changed value of false in this case.
success bool
failed
Indicates if the task failed. See the results key for additional details.
always bool
format
The format of the RPC response from the list of formats in the formats option.
always str
kwargs
The keyword arguments from the list of dictionaries in the kwargs option. This will be none if no kwargs are applied to the RPC.
always dict
msg
A human-readable message indicating the result.
always str
parsed_output
The RPC reply from the Junos device parsed into a JSON datastructure. For XML replies, the response is parsed into JSON using the jxmlease library. For JSON the response is parsed using the Python json library.
When Ansible converts the jxmlease or native Python data structure into JSON, it does not guarantee that the order of dictionary/object keys are maintained.
when RPC executed successfully, return_output is true, and the RPC format is xml or json. dict
results
The other keys are returned when a single RPC is specified for the rpcs option. When the value of the rpcs option is a list of RPCs, this key is returned instead. The value of this key is a list of dictionaries. Each element in the list corresponds to the RPCs in the rpcs option. The keys for each element in the list include all of the other keys listed. The failed key indicates if the individual RPC failed. In this case, there is also a top-level failed key. The top-level failed key will have a value of false if ANY of the RPCs ran successfully. In this case, check the value of the failed key for each element in the results list for the results of individual RPCs.
when the rpcs option is a list value. list of dict
rpc
The RPC which was executed from the list of RPCs in the rpcs option.
always str
stdout
The RPC reply from the Junos device as a single multi-line string.
when RPC executed successfully and return_output is true. str
stdout_lines
The RPC reply from the Junos device as a list of single-line strings.
when RPC executed successfully and return_output is true. list of str


Notes

Note

  • The NETCONF system service must be enabled on the target Junos device.

Author

  • Juniper Networks - Stacy Smith (@stacywsmith)

Status

This module is flagged as stableinterface which means that the maintainers for this module guarantee that no backward incompatible interface changes will be made.