Juniper.junos Ansible Modules

Contents:

juniper_junos_system

Initiate operational actions on the Junos system

New in version 2.0.0.

Synopsis

  • Initiate an operational action (shutdown, reboot, halt or zeroize) on a Junos system. The particular action to execute is defined by the mandatory action option.

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
action
 str yes none
  • shutdown
  • halt
  • reboot
  • zeroize
  • off
  • power-off
  • power_off
The action performed by the module.
The following actions are supported:
shutdown - Power off the Junos devices. The values off, power-off, and power_off are aliases for this value. This is the equivalent of the request system power-off CLI command.
halt - Stop the Junos OS running on the RE, but do not power off the system. Once the system is halted, it will reboot if a keystroke is entered on the console. This is the equivalent of the request system halt CLI command.
reboot - Reboot the system. This is the equivalent of the request system reboot CLI command.
zeroize - Restore the system (configuration, log files, etc.) to a factory default state. This is the equivalent of the request system zeroize CLI command.
all_re
 bool no True
  • yes
  • no
If the system has multiple Routing Engines and this option is true, then the action is performed on all REs in the system. If the system does not have multiple Routing Engines, then this option has no effect.
This option applies to all action values.
The all_re option is mutually exclusive with the other_re option.
at
 str no none
The time at which to shutdown, halt, or reboot the system.
The value may be specified in one of the following ways:
now - The action takes effect immediately.
+minutes — The action takes effect in minutes minutes from now.
yymmddhhmm — The action takes effect at yymmddhhmm absolute time, specified as year, month, day, hour, and minute.
hh:mm — The action takes effect at hh:mm absolute time on the current day, specified in 24-hour time.
The at option can not be used when the action option has a value of zeroize. The at option is mutually exclusive with the in_min option.
in_min
 int no none
Specify a delay, in minutes, before the shutdown, halt, or reboot.
The in_min option can not be used when the action option has a value of zeroize. The in_min option is mutually exclusive with the at option.
media
 bool no False
  • yes
  • no
Overwrite media when performing the zeroize operation. This option is only valid when the action option has a value of zeroize.
other_re
 bool no False
  • yes
  • no
If the system has dual Routing Engines and this option is true, then the action is performed on the other REs in the system. If the system does not have dual Routing Engines, then this option has no effect.
The other_re option can not be used when the action option has a value of zeroize.
The other_re option is mutually exclusive with the all_re option.

Examples

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

  tasks:
    - name: Reboot all REs of the device
      juniper_junos_system:
        action: "reboot"

    - name: Power off the other RE of the device.
      juniper_junos_system:
        action: "shutdown"
        othe_re: True

    - name: Reboot this RE at 8pm today.
      juniper_junos_system:
        action: "reboot"
        all_re: False
        at: "20:00"

    - name: Halt the system on 25 January 2018 at 4pm.
      juniper_junos_system:
        action: "halt"
        at: "1801251600"

    - name: Reboot the system in 30 minutes.
      juniper_junos_system:
        action: "reboot"
        in_min: 30

    - name: Reboot the system in 30 minutes.
      juniper_junos_system:
        action: "reboot"
        at: "+30m"

    - name: Zeroize the local RE only.
      juniper_junos_system:
        action: "zeroize"
        all_re: False

    - name: Zeroize all REs and overwrite medea.
      juniper_junos_system:
        action: "zeroize"
        media: True

Return Values

name description returned type sample
action
The value of the action option.
 always str
all_re
The value of the all_re option.
 always str
changed
Indicates if the device's state has changed. If the action is performed (or if it would have been performed when in check mode) then the value will be true. If there was an error before the action, then the value will be false.
 always bool
failed
Indicates if the task failed.
 always bool
media
The value of the media option.
 always str
msg
A human-readable message indicating the result.
 always str
other_re
The value of the other_re option.
 always str


Notes

Note

  • This module only INITIATES the action. It does NOT wait for the action to complete.
  • Some Junos devices are effected by a Junos defect which causes this Ansible module to hang indefinitely when connected to the Junos device via the console. This problem is not seen when connecting to the Junos device using the normal NETCONF over SSH transport connection. Therefore, it is recommended to use this module only with a NETCONF over SSH transport connection. However, this module does still permit connecting to Junos devices via the console port and this functionality may still be used for Junos devices running Junos versions less than 15.1.
  • 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.

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.

juniper_junos_config

Manipulate the configuration of a Junos device

New in version 2.0.0.

Synopsis

  • Manipulate the configuration of a Junos device. This module allows a combination of loading or rolling back, checking, diffing, retrieving, and committing the configuration of a Junos device. It performs the following steps in order:
  1. Open a candidate configuration database.
    • If the config_mode option has a value of exclusive, the default, take a lock on the candidate configuration database. If the lock fails the module fails and reports an error.
    • If the config_mode option has a value of private, open a private candidate configuration database. If opening the private configuration database fails the module fails and reports an error.
  2. Load configuration data into the candidate configuration database.
    • Configuration data may be loaded using the load or rollback options. If either of these options are specified, new configuration data is loaded. If neither option is specified, this step is skipped.
    • If the rollback option is specified, replace the candidate configuration with the previous configuration specified by the value of the rollback option.
    • If the load option is specified, load new configuration data.
    • The value of the load option defines the type of load which is performed.
    • The source of the new configuration data is one of the following:
      • src - A file path on the local Ansible control machine.
      • lines - A list of strings containing the configuration data.
      • template - A file path to a Jinja2 template on the local Ansible control machine. This template is rendered with the variables specified by the vars option. If the template option is specified, the vars option must also be specified.
      • url - A URL reachable from the target Junos device.
    • If the format option is specified, the configuration file being loaded is in the specified format, rather than the format determined from the file name.
  3. Check the validity of the candidate configuration database.
    • If the check option is true, the default, check the validity of the configuration by performing a “commit check” operation.
    • This option may be specified with diff false and commit false to confirm a previous “commit confirmed <min>” operation without actually performing an additional commit.
    • If the configuration check fails, further processing stops, the module fails, and an error is reported.
  4. Determine differences between the candidate and committed configuration databases.
    • If step 2 was not skipped, and the diff option is true, the default, perform a diff between the candidate and committed configuration databases.
    • If the diffs_file or dest_dir option is specified, save the generated configuration differences.
    • If the return_output option is true, the default, include the generated configuration difference in the diff and diff_lines keys of the module’s response.
  5. Retrieve the configuration database from the Junos device.
    • If the retrieve option is specified, retrieve the configuration database specified by the retrieve value from the target Junos device to the local Ansible control machine.
    • The format in which the configuration is retrieved is specified by the value of the format option.
    • The optional filter controls which portions of the configuration are retrieved.
    • If options are specified, they control the content of the configuration retrieved.
    • If the dest or dest_dir option is specified, save the retrieved configuration to a file on the local Ansible control machine.
    • If the return_output option is true, the default, include the retrieved configuration in the config, config_lines, and config_parsed keys of the module’s response.
  6. Commit the configuration changes.
    • If the commit option is true, the default, commit the configuration changes.
    • This option may be specified with diff false and check false to confirm a previous “commit confirmed <min>” operation.
    • If the comment option is specified, add the comment to the commit.
    • If the confirmed option is specified, perform a commit confirmed min operation where min is the value of the confirmed option.
    • If the check option is true and the check_commit_wait option is specified, wait check_commit_wait seconds before performing the commit.
  7. Close the candidate configuration database.
    • Close and discard the candidate configuration database.
    • If the config_mode option has a value of exclusive, the default, unlock the candidate configuration database.

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
check
 bool no true (false if retrieve is set and load and rollback are not set)
  • yes
  • no
Perform a commit check operation.

aliases: check_commit, commit_check
check_commit_wait
 int no none
The number of seconds to wait between check and commit operations.
This option is only valid if check is true and commit is true.
This option should not normally be needed. It works around an issue in some versions of Junos.
comment
 str no none
Provide a comment to be used with the commit operation.
This option is only valid if the commit option is true.
commit
 bool no true (false if retrieve is set and load and rollback are not set)
  • yes
  • no
Perform a commit operation.
commit_empty_changes
 bool no False
  • yes
  • no
Perform a commit operation, even if there are no changes between the candidate configuration and the committed configuration.
config_mode
 str no exclusive
  • exclusive
  • private
The mode used to access the candidate configuration database.

aliases: config_access, edit_mode, edit_access
confirmed
 int no none
Provide a confirmed timeout, in minutes, to be used with the commit operation.
This option is only valid if the commit option is true.
The value of this option is the number of minutes to wait for another commit operation before automatically rolling back the configuration change performed by this task. In other words, this option causes the module to perform a commit confirmed min where min is the value of the confirmed option. This option DOES NOT confirm a previous commit confirmed min operation. To confirm a previous commit operation, invoke this module with the check or commit option set to true.

aliases: confirm
dest
 path no none
The path to a file, on the local Ansible control machine, where the configuration will be saved if the retrieve option is specified.
The file must be writeable. If the file already exists, it is overwritten.
This option is only valid if the retrieve option is not none.
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. This is the directory where the configuration will be saved if the retrieve option is specified. It is also the directory where the configuration diff will be specified if the diff option is true.
This option is only valid if the retrieve option is not none or the diff option is true.
The retrieved configuration will be saved to a file named {{ inventory_hostname }}.format_extension in the dest_dir directory. Where format_extension is conf for text format, xml for XML format, json for JSON format, and set for set format.
If the diff option is true, the configuration diff will be saved to a file named {{ inventory_hostname }}.diff 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.
The dest_dir and diff_file options are mutually exclusive. The dest_dir option is recommended for all new playbooks.

aliases: destination_dir, destdir, savedir, save_dir
diff
 bool no true (false if retrieve is set and load and rollback are not set)
  • yes
  • no
Perform a configuration compare (aka diff) operation.

aliases: compare, diffs
diffs_file
 path no None
The path to a file, on the Ansible control machine, where the configuration differences will be saved if the diff option is specified.
The file must be writeable. If the file already exists, it is overwritten.
This option is only valid if the diff option is true.
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 diffs_file 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 diffs_file and dest_dir options are mutually exclusive.
filter
 str no none
A string of XML, or '/'-separated configuration hierarchies, which specifies a filter used to restrict the portions of the configuration which are retrieved. See PyEZ's get_config method documentation for details on the value of this option.

aliases: filter_xml
format
 str no none (auto-detect on load, text on retrieve)
  • xml
  • set
  • text
  • json
Specifies the format of the configuration retrieved, if retrieve is not none.
Specifies the format of the configuration to be loaded, if load is not none.
The specified format must be supported by the target Junos device.
ignore_warning
 bool, str, or list of str no none
A boolean, string or list of strings. If the value is true, ignore all warnings regardless of the warning message. If the value is a string, it will ignore warning(s) if the message of each warning matches the string. If the value is a list of strings, ignore warning(s) if the message of each warning matches at least one of the strings in the list. The value of the ignore_warning option is applied to the load and commit operations performed by this module.
lines
 list no none
Used with the load option. Specifies a list of list of configuration strings containing the configuration to be loaded.
The src, lines, template, and url options are mutually exclusive.
By default, the format of the configuration data is auto-dectected by the content of the first line in the lines list.
If the format option is specified, the format value overrides the format auto-detection.
load
 str no none
  • none
  • set
  • merge
  • update
  • replace
  • override
  • overwrite
Specifies the type of load operation to be performed.
The load and rollback options are mutually exclusive.
The choices have the following meanings:
none - Do not perform a load operation.
merge - Combine the new configuration with the existing configuration. If statements in the new configuration conflict with statements in the existing configuration, the statements in the new configuration replace those in the existing configuration.
replace - This option is a superset of the merge option. It combines the new configuration with the existing configuration. If the new configuration is in text format and a hierarchy level in the new configuartion is prefixed with the string replace:, then the hierarchy level in the new configuration replaces the entire corresponding hierarchy level in the existing configuration, regardles of the existence or content of that hierarchy level in the existing configuration. If the configuration is in XML format, the XML attribute replace = "replace" is equivalent to the text format's replace: prefix. If a configuration hierarchy in the new configuration is not prefixed with replace:, then the merge behavior is used. Specifically, for any statements in the new configuration which conflict with statements in the existing configuration, the statements in the new configuration replace those in the existing configuration.
override - Discard the entire existing configuration and replace it with the new configuration. When the configuration is later committed, all system processes are notified and the entire new configuration is marked as 'changed' even if some statements previously existed in the configuration. The value overwrite is a synonym for override.
update - This option is similar to the override option. The new configuration completely replaces the existing configuration. The difference comes when the configuration is later committed. This option performs a 'diff' between the new candidate configuration and the existing committed configuration. It then only notifies system processes repsonsible for the changed portions of the configuration, and only marks the actual configuration changes as 'changed'.
set - This option is used when the new configuration data is in set format (a series of configuration mode commands). The new configuration data is loaded line by line and may contain any configuration mode commands, such as set, delete, edit, or deactivate. This value must be specified if the new configuration is in set format.
options
 dict no None
Additional options, specified as a dictionary of key/value pairs, used when retrieving the configuration. See the <get-configuration> RPC documentation for information on available options.
retrieve
 str no none
  • none
  • candidate
  • committed
The configuration database to be retrieved.
return_output
 bool no True
  • yes
  • no
Indicates if the output of the diff and retreive options 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 configuration or diff 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.
rollback
 int or str no none
  • 0-49
  • rescue
Populate the candidate configuration from a previously committed configuration. This value can be a configuration number between 0 and 49, or the keyword rescue to load the previously saved rescue configuration.
By default, some Junos platforms store fewer than 50 previous configurations. Specifying a value greater than the number of previous configurations available, or specifying rescue when no rescue configuration has been saved, will result in an error when the module attempts to perform the rollback.
The rollback and load options are mutually exclusive.
src
 path no none
Used with the load option. Specifies the path to a file, on the local Ansible control machine, containing the configuration to be loaded.
The src, lines, template, and url options are mutually exclusive.
By default, the format of the configuration data is determined by the file extension of this path name. If the file has a .conf extension, the content is treated as text format. If the file has a .xml extension, the content is treated as XML format. If the file has a .set extension, the content is treated as Junos set commands.
If the format option is specified, the format value overrides the file-extension based format detection.

aliases: source, file
template
 path no none
The path to a Jinja2 template file, on the local Ansible control machine. This template file, along with the vars option, is used to generate the configuration to be loaded on the target Junos device.
The src, lines, template, and url options are mutually exclusive.
The template and vars options are required together. If one is specified, the other must be specified.

aliases: template_path
url
 str no none
A URL which specifies the configuration data to load on the target Junos device.
The Junos device uses this URL to load the configuration, therefore this URL must be reachable by the target Junos device.
The possible formats of this value are documented in the 'url' section of the <load-configuration> RPC documentation.
The src, lines, template, and url options are mutually exclusive.
vars
 dict no none
A dictionary of keys and values used to render the Jinja2 template specified by the template option.
The template and vars options are required together. If one is specified, the other must be specified.

aliases: template_vars

Examples

---
- name: Manipulate the configuration of Junos devices
  hosts: junos-all
  connection: local
  gather_facts: no
  roles:
    - Juniper.junos
  tasks:
    - name: Retrieve the committed configuration
      juniper_junos_config:
        retrieve: 'committed'
        diff: false
        check: false
        commit: false
      register: response
    - name: Print the lines in the config.
      debug:
        var: response.config_lines

    - name: Append .foo to the hostname using private config mode.
      juniper_junos_config:
        config_mode: 'private'
        load: 'merge'
        lines:
          - "set system host-name {{ inventory_hostname }}.foo"
      register: response
    - name: Print the config changes.
      debug:
        var: response.diff_lines

    - name: Rollback to the previous config.
      juniper_junos_config:
        config_mode: 'private'
        rollback: 1
      register: response
    - name: Print the config changes.
      debug:
        var: response.diff_lines

    - name: Rollback to the rescue config.
      juniper_junos_config:
        rollback: 'rescue'
      register: response
    - name: Print the complete response.
      debug:
        var: response

    - name: Load override from a file.
      juniper_junos_config:
        load: 'override'
        src: "{{ inventory_hostname }}.conf"
      register: response
    - name: Print the complete response.
      debug:
        var: response

    - name: Load from a Jinja2 template.
      juniper_junos_config:
        load: 'merge'
        format: 'xml'
        template: "{{ inventory_hostname }}.j2"
        vars:
          host: "{{ inventory_hostname }}"
      register: response
    - name: Print the complete response.
      debug:
        var: response

    - name: Load from a file on the Junos device.
      juniper_junos_config:
        load: 'merge'
        url: "{{ inventory_hostname }}.conf"
      register: response
    - name: Print the complete response.
      debug:
        var: response

    - name: Load from a file on the Junos device, skip the commit check
      juniper_junos_config:
        load: 'merge'
        url: "{{ inventory_hostname }}.conf"
        check: false
      register: response
    - name: Print the msg.
      debug:
        var: response.msg

    - name: Print diff between current and rollback 10. No check. No commit.
      juniper_junos_config:
        rollback: 11
        diff: true
        check: false
        commit: false
      register: response
    - name: Print the msg.
      debug:
        var: response

    - name: Retrieve [edit system services] of current committed config.
      juniper_junos_config:
        retrieve: 'committed'
        filter: 'system/services'
        diff: true
        check: false
        commit: false
      register: response
    - name: Print the resulting config lines.
      debug:
        var: response.config_lines

    - name: Enable NETCONF SSH and traceoptions, save config, and diffs.
      juniper_junos_config:
        load: 'merge'
        lines:
          - 'set system services netconf ssh'
          - 'set system services netconf traceoptions flag all'
          - 'set system services netconf traceoptions file netconf.log'
        format: 'set'
        retrieve: 'candidate'
        filter: 'system/services'
        comment: 'Enable NETCONF with traceoptions'
        dest_dir: './output'
      register: response
    - name: Print the complete response
      debug:
        var: response

    - name: Load conf. Confirm within 5 min. Wait 3 secs between chk and commit
      juniper_junos_config:
        load: 'merge'
        url: "{{ inventory_hostname }}.conf"
        confirm: 5
        check_commit_wait: 3
      register: response
    - name: Print the complete response
      debug:
        var: response
    - name: Confirm the previous commit with a commit check (but no commit)
      juniper_junos_config:
        check: true
        diff: false
        commit: false
      register: response
    - name: Print the complete response
      debug:
        var: response

Return Values

name description returned type sample
changed
Indicates if the device's configuration has changed, or would have changed when in check mode.
 success bool
config
The retrieved configuration. The value is a single multi-line string in the format specified by the format option.
 when retrieved is not none and return_output is true. str
config_lines
The retrieved configuration. The value is a list of single-line strings in the format specified by the format option.
 when retrieved is not none and return_output is true. list
config_parsed
The retrieved configuration 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 retrieved is not none, the format option is xml or json and return_output is true. dict
diff
The configuration differences between the previous and new configurations. The value is a single multi-line string in "diff" format.
 when load or rollback is specified, diff is true, and return_output is true. str
diff_lines
The configuration differences between the previous and new configurations. The value is a list of single-line strings in "diff" format.
 when load or rollback is specified, diff is true, and return_output is true. list
failed
Indicates if the task failed.
 always bool
file
The value of the src option.
 when load is not none and src is not none str
msg
A human-readable message indicating the result.
 always 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.

juniper_junos_pmtud

Perform path MTU discovery from a Junos device to a destination

New in version 2.0.0.

Synopsis

  • Determine the maximum IP MTU supported along a path from a Junos device to a user-specified destination by performing path MTU discovery (PMTUD) using the ping command. The reported MTU will be between min_test_size and max_size where min_test_size = (max_size - max_range + 1). If the actual path MTU is greater than max_size, then max_size will be reported. If the actual path MTU is less than min_test_size, then a failure will be reported.

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
dest
 str yes none
The IPv4 address, or hostname if DNS is configured on the Junos device, used as the destination of the PMTUD.

aliases: dest_ip, dest_host, destination, destination_ip, destination_host
interface
 str no none
The source interface from which the the PMTUD is performed. If not specified, the default Junos algorithm for determining the source interface is used.
max_range
 int no 512
The maximum range of MTU values, in bytes, which will be searched when performing path MTU discovery. This value must be 0 or a power of 2 (2^n) between 2 and 65536. The minimum IPv4 MTU value attempted when performing path MTU discovery is min_test_size = (max_size - max_range + 1)
max_size
 int no 1500
The maximum IPv4 MTU, in bytes, to attempt when performing path MTU discovery.
The value returned for inet_mtu will be no more than this value even if the path actually supports a higher MTU.
This value must be between 68 and 65496.
routing_instance
 str no none
Name of the source routing instance from which the ping is originated.
If not specified, the default routing instance is used.
source
 str no none
The IPv4 address, or hostname if DNS is configured on the Junos device, used as the source address of the PMTUD. If not specified, the Junos default algorithm for determining the source address is used.

aliases: source_ip, source_host, src, src_ip, src_host

Examples

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

  tasks:
    - name: Perform PMTUD to 192.68.1.1 with default parameters.
      juniper_junos_pmtud:
        dest: "192.68.1.1"

    - name: Perform PMTUD to 192.68.1.1. Register response.
      juniper_junos_pmtud:
        dest: "192.68.1.1"
      register: response
    - name: Print the discovered MTU.
      debug:
        var: response.inet_mtu

    - name: Perform PMTUD to 192.68.1.1. Search all possible MTU values.
      juniper_junos_pmtud:
        dest: "192.68.1.1"
        max_size: 65496
        max_range: 65536
      register: response
    - name: Print the discovered MTU.
      debug:
        var: response.inet_mtu

    - name: Perform PMTUD to 192.68.1.1. Source from ge-0/0/0.0 interface.
      juniper_junos_pmtud:
        dest: "192.68.1.1"
        interface: "ge-0/0/0.0"
      register: response
    - name: Print the discovered MTU.
      debug:
        var: response.inet_mtu

    - name: Perform PMTUD to 192.68.1.1. Source from 192.168.1.2.
      juniper_junos_pmtud:
        dest: "192.68.1.1"
        source: "192.168.1.2"
      register: response
    - name: Print the discovered MTU.
      debug:
        var: response.inet_mtu

    - name: Perform PMTUD to 192.68.1.1. Source from the red routing-instance.
      juniper_junos_pmtud:
        dest: "192.68.1.1"
        routing_instance: "red"
      register: response
    - name: Print the discovered MTU.
      debug:
        var: response.inet_mtu

Return Values

name description returned type sample
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.
 when PMTUD successfully executed. bool
failed
Indicates if the task failed.
 always bool
host
The destination IP/host of the PMTUD as specified by the dest option.
Keys dest and dest_ip are also returned for backwards compatibility.
 when PMTUD successfully executed. str
inet_mtu
The IPv4 path MTU size in bytes to the dest. This is the lesser of max_size and the actual path MTU to dest. If the actual path MTU is less than min_test_size, then a failure is reported. Where min_test_size = (max_size - max_range + 1)
 when PMTUD successfully executed. str
interface
The source interface of the PMTUD as specified by the interface option.
 when the interface option was specified. str
routing_instance
The routing-instance from which the PMTUD was performed as specified by the routing_instance option.
 when the routing_instance option was specified. str
source
The source IP/host of the PMTUD as specified by the source option.
Key source_ip is also returned for backwards compatibility.
 when the source option was specified. str
warnings
A list of warning strings, if any, produced from the ping.
 when warnings are present list


Notes

Note

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

Author

  • Martin Komon (@mkomon)
  • 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.

juniper_junos_srx_cluster

Add or remove SRX chassis cluster configuration

New in version 2.0.0.

Synopsis

  • Add an SRX chassis cluster configuration and reboot the device. Assuming the device is capable of forming an SRX cluster and has the correct cables connected, this will form an SRX cluster.
  • If an SRX chassis cluster is already present, setting cluster_enable to false will remove the SRX chassis cluster configuration and reboot the device causing the SRX cluster to be broken and the device to return to stand-alone mode.

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
cluster_id
 int no none
The cluster ID to configure.
Required when enable is true.

aliases: cluster
enable
 bool yes none
  • yes
  • no
Enable or disable cluster mode. When true cluster mode is enabled and cluster_id and node_id must also be specified. When false cluster mode is disabled and the device returns to stand-alone mode.

aliases: cluster_enable
node_id
 int no none
The node ID to configure. (0 or 1)
Required when enable is true.

aliases: node

Examples

---
- name: Manipulate the SRX cluster configuration of Junos SRX devices
  hosts: junos-all
  connection: local
  gather_facts: no
  roles:
    - Juniper.junos
  tasks:
    - name: Enable an SRX cluster
      juniper_junos_srx_cluster:
        enable: true
        cluster_id: 4
        node_id: 0
      register: response
    - name: Print the response.
      debug:
        var: response.config_lines

    - name: Disable an SRX cluster
      juniper_junos_srx_cluster:
        enable: false
      register: response
    - name: Print the response.
      debug:
        var: response.config_lines

Return Values

name description returned type sample
changed
Indicates if the device's configuration has changed, or would have changed when in check mode.
 success bool
failed
Indicates if the task failed.
 always bool
msg
A human-readable message indicating the result.
 always str
reboot
Indicates if a reboot of the device has been initiated.
 success bool


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.

juniper_junos_software

Install software on a Junos device

New in version 2.0.0.

Synopsis

  • Install a Junos OS image, or other software package, on a Junos device. This action is generally equivalent to the request system software add operational-mode CLI command. It performs the following steps in order:
  1. Compare the currently installed Junos version to the desired version specified by the version option.
    • If the current and desired versions are the same, stop and return changed with a value of false.
    • If running in check mode, and the current and desired versions differ, stop and return changed with a value of true.
    • Otherwise, proceed.
  2. If the local_package option is specified, compute the MD5 checksum of the local_package file on the local Ansible control machine.
  3. Check if the file exists at the remote_package location on the target Junos device. If so, compute the MD5 checksum of the file on the target Junos device.
  4. If the cleanfs option is true, the default, then perform the equivalent of the request system storage cleanup CLI command.
  5. If the checksums computed in steps 2 and 3 differ, or if the remote_package file does not exist on the target Junos device, then copy the package from local_package on the local Ansible control machine to remote_package on the target Junos device.
  6. Install the software pacakge from the remote_package location on the target Junos device using the options specified.
  7. If the reboot option is true, the default, initiate a reboot of the target Junos device.

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
all_re
 bool no True
  • yes
  • no
Whether or not to install the software on all Routing Engines of the target Junos device. If true, and the device has multiple Routing Engines, the software is installed on all Routing Engines. If false, the software is only installed on the current Routing Engine.
checksum
 str no none
The pre-calculated checksum, using the checksum_algorithm of the file specified by the local_package option. Specifying this option is simply an optimization to avoid repeatedly computing the checksum of the local_package file once for each target Junos host.
checksum_algorithm
 str no md5
The algorithm to use when calculating the checksum of the local and remote software packages.
checksum_timeout
 int no 300 (5 minutes)
The number of seconds to wait for the calculation of the checksum to complete on the target Junos device.
cleanfs
 bool no true (unless no_copy is true, then false)
  • yes
  • no
Whether or not to perform a request system storage cleanup prior to copying or installing the software.
cleanfs_timeout
 int no 300 (5 minutes)
The number of seconds to wait for the request system storage cleanup to complete on the target Junos device.
force_host
 bool no False
  • yes
  • no
Forces the upgrade of the Host Software package on QFX-series devices.
install_timeout
 int no 1800 (30 minutes)
The number of seconds to wait for the software installation to complete on the target Junos device.
issu
 bool no False
  • yes
  • no
Indicates if a unified in-service software upgrade (ISSU) should be attempted. ISSU enables the upgrade between two different Junos OS releases with no control plane disruption and minimal data plane traffic disruption.
In order for an ISSU to succeed, ISSU must be supported. This includes support for the current to desired Junos versions, the hardware of the target Junos device, and the current software configuration of the target Junos device.
The issu and nssu options are mutually exclusive.
kwargs
 dict no none
Additional keyword arguments and values which are passed to the <request-package-add> RPC used to install the software package. The value of this option is a dictionary of keywords and values.

aliases: kwarg, args, arg
local_package
 path no none
The path, on the local Ansible control machine, of a Junos software package. This Junos software package will be installed on the target Junos device.
If this option is specified, and a file with the same MD5 checksum doesn't already exist at the remote_package location on the target Junos device, then the file is copied from the local Ansible control machine to the target Junos device.
If this option is not specified, it is assumed that the software package already exists on the target Junos device. In this case, the remote_package option must be specified.

aliases: package
no_copy
 bool no False
  • yes
  • no
Indicates if the file containing the software package should be copied from the local_package location on the local Ansible control machine to the remote_package location on the target Junos device.
If the value is true, or if the local_package option is not specified, then the copy is skipped and the file must already exist at the remote_package location on the target Junos device.
nssu
 bool no False
  • yes
  • no
Indicates if a non-stop software upgrade (NSSU) should be attempted. NSSU enables the upgrade between two different Junos OS releases with minimal data plane traffic disruption.
NSSU is specific to EX-series Virtual Chassis systems or EX-series stand-alone systems with redundant Routing Engines.
In order for an NSSU to succeed, NSSU must be supported. This includes support for the current to desired Junos versions, the hardware of the target Junos device, and the current software configuration of the target Junos device.
The nssu and issu options are mutually exclusive.
pkg_set
 list no False
install software on the members in a mixed Virtual Chassis. Currently we are not doing target package check this option is provided.
reboot
 bool no True
  • yes
  • no
Indicates if the target Junos device should be rebooted after performing the software install.
reboot_pause
 int no 10
The amount of time, in seconds, to wait after the reboot is issued before the module returns. This gives time for the reboot to begin. The default value of 10 seconds is designed to ensure the device is no longer reachable (because the reboot has begun) when the next task begins. The value must be an integer greater than or equal to 0.
remote_package
 path no /var/tmp/ + filename portion of local_package
This option may take one of two formats.
The first format is a URL, from the perspective of the target Junos device, from which the device retrieves the software package to be installed. The acceptable formats for the URL value may be found here.
When using the URL format, the local_package and no_copy options must not be specified.
The second format is a file path, on the taget Junos device, to the software package.
If the local_package option is also specified, and the no_copy option is false, the software package will be copied from local_package to remote_package, if necessary.
If the no_copy option is true or the local_package option is not specified, then the file specified by this option must already exist on the target Junos device.
If this option is not specified, it is assumed that the software package will be copied into the /var/tmp directory on the target Junos device using the filename portion of the local_package option. In this case, the local_package option must be specified.
Specifying the remote_package option and not specifying the local_package option is equivalent to specifying the local_package option and the no_copy option. In this case, you no longer have to explicitly specify the no_copy option.
If the remote_package value is a directory (ends with /), then the filename portion of local_package will be appended to the remote_package value.
If the remote_package value is a file (does not end with /), then the filename portion of remote_package must be the same as the filename portion of local_package.
validate
 bool no False
  • yes
  • no
Whether or not to have the target Junos device should validate the current configuration against the new software package.
version
 str no Attempt to extract the version from the file name specified by the local_package or remote_package option values IF the package appears to be a Junos software package. Otherwise, none.
The version of software contained in the file specified by the local_package and/or remote_package options. This value should match the Junos version which will be reported by the device once the new software is installed. If the device is already running a version of software which matches the version option value, the software install is not necessary. In this case the module returns a changed value of false and an failed value of false and does not attempt to perform the software install.

aliases: target_version, new_version, desired_version
vmhost
 bool no False
  • yes
  • no
Whether or not this is a vmhost software installation.

Examples

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

  tasks:
    - name: Execute a basic Junos software upgrade.
      juniper_junos_software:
        local_package: "./images/"
      register: response
    - name: Print the complete response.
      debug:
        var: response

###### OLD EXAMPLES ##########
    - junos_install_os:
        host={{ inventory_hostname }}
        version=12.1X46-D10.2
        package=/usr/local/junos/images/junos-vsrx-12.1X46-D10.2-domestic.tgz
        logfile=/usr/local/junos/log/software.log
###### OLD EXAMPLES ##########

Return Values

name description returned type sample
changed
Indicates if the device's state has changed, or if the state would have changed when executing in check mode. This value is set to true when the version of software currently running on the target Junos device does not match the desired version of software specified by the version option. If the current and desired software versions match, the value of this key is set to false.
 success bool
check_mode
Indicates whether or not the module ran in check mode.
 success bool
failed
Indicates if the task failed.
 always bool
msg
A human-readable message indicating the result of the software installation.
 always str


Notes

Note

  • This module does support connecting to the console of a Junos device, but does not support copying the software package from the local Ansible control machine to the target Junos device while connected via the console. In this situation, the remote_package option must be specified, and the specified software package must already exist on the target Junos device.
  • This module returns after installing the software and, optionally, initiating a reboot of the target Junos device. It does not wait for the reboot to complete, and it does not verify that the desired version of software specified by the version option is actually activated on the target Junos device. It is the user’s responsibility to confirm the software installation using additional follow on tasks in their playbook.
  • The NETCONF system service must be enabled on the target Junos device.

Author

  • Jeremy Schulman
  • 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.

juniper_junos_ping

Execute ping from a Junos device

New in version 2.0.0.

Synopsis

  • Execute the ping command from a Junos device to a specified destination in order to test network reachability from the Junos device .

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
acceptable_percent_loss
 int no 0
Maximum percentage of packets that may be lost and still consider the task not to have failed.

aliases: acceptable_packet_loss
count
 int no 5
Number of packets to send.
dest
 str yes none
The IP address, or hostname if DNS is configured on the Junos device, used as the destination of the ping.

aliases: dest_ip, dest_host, destination, destination_ip, destination_host
do_not_fragment
 bool no False
  • yes
  • no
Set Do Not Fragment bit on ping packets.
interface
 str no none
The source interface from which the the ping is sent. If not specified, the default Junos algorithm for determining the source interface is used.
rapid
 bool no True
  • yes
  • no
Send ping requests rapidly
routing_instance
 str no none
Name of the source routing instance from which the ping is originated. If not specified, the default routing instance is used.
size
 int no none (default size for device)
The size of the ICMP payload of the ping.
Total size of the IP packet is size + the 20 byte IP header + the 8 byte ICMP header. Therefore, size of 1472 generates an IP packet of size 1500.
source
 str no none
The IP address, or hostname if DNS is configured on the Junos device, used as the source address of the ping. If not specified, the Junos default algorithm for determining the source address is used.

aliases: source_ip, source_host, src, src_ip, src_host
ttl
 int no none (default ttl for device)
Maximum number of IP routers (hops) allowed between source and destination.

Examples

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

  tasks:
    - name: Ping 192.68.1.1 with default parameters. Fails if any packets lost.
      juniper_junos_ping:
        dest: "192.68.1.1"

    - name: Ping 192.68.1.1 Allow 50% packet loss. Register response.
      juniper_junos_ping:
        dest: "192.68.1.1"
        acceptable_percent_loss: 50
      register: response
    - name: Print all keys in the response.
      debug:
        var: response

    - name: Ping 192.68.1.1. Send 20 packets. Register response.
      juniper_junos_ping:
        dest: "192.68.1.1"
        count: 20
      register: response
    - name: Print packet sent from the response.
      debug:
        var: response.packets_sent

    - name: Ping 192.68.1.1. Send 10 packets wihtout rapid. Register response.
      juniper_junos_ping:
        dest: "192.68.1.1"
        count: 10
        rapid: false
      register: response
    - name: Print the average round-trip-time from the response.
      debug:
        var: response.rtt_average

    - name: Ping www.juniper.net with ttl 15. Register response.
      juniper_junos_ping:
        dest: "www.juniper.net"
        ttl: 15
      register: response
    - name: Print the packet_loss percentage from the response.
      debug:
        var: response.packet_loss

    - name: Ping 192.68.1.1 with IP packet size of 1500. Register response.
      juniper_junos_ping:
        dest: "192.68.1.1"
        size: 1472
      register: response
    - name: Print the packets_received from the response.
      debug:
        var: response.packets_received

    - name: Ping 192.68.1.1 with do-not-fragment bit set. Register response.
      juniper_junos_ping:
        dest: "192.68.1.1"
        do_not_fragment: true
      register: response
    - name: Print the maximum round-trip-time from the response.
      debug:
        var: response.rtt_maximum

    - name: Ping 192.68.1.1 with source set to 192.68.1.2. Register response.
      juniper_junos_ping:
        dest: "192.68.1.1"
        source: "192.68.1.2"
      register: response
    - name: Print the source from the response.
      debug:
        var: response.source

    - name: Ping 192.168.1.1 from the red routing-instance.
      juniper_junos_ping:
        dest: "192.168.1.1"
        routing_instance: "red"

    - name: Ping the all-hosts multicast address from the ge-0/0/0.0 interface
      juniper_junos_ping:
        dest: "224.0.0.1"
        interface: "ge-0/0/0.0"

Return Values

name description returned type sample
acceptable_percent_loss
The acceptable packet loss (as a percentage) for this task as specified by the acceptable_percent_loss option.
 when ping successfully executed, even if the acceptable_percent_loss was exceeded. str
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.
 when ping successfully executed, even if the acceptable_percent_loss was exceeded. bool
count
The number of pings sent, as specified by the count option.
 when ping successfully executed, even if the acceptable_percent_loss was exceeded. str
do_not_fragment
Whether or not the do not fragment bit was set on the pings sent, as specified by the do_not_fragment option.
 when ping successfully executed, even if the acceptable_percent_loss was exceeded. bool
failed
Indicates if the task failed.
 always bool
host
The destination IP/host of the pings sent as specified by the dest option.
Keys dest and dest_ip are also returned for backwards compatibility.
 when ping successfully executed, even if the acceptable_percent_loss was exceeded. str
interface
The source interface of the pings sent as specified by the interface option.
 when ping successfully executed and the interface option was specified, even if the acceptable_percent_loss was exceeded. str
msg
A human-readable message indicating the result.
 always str
packet_loss
The percentage of packets lost.
 when ping successfully executed, even if the acceptable_percent_loss was exceeded. str
packets_received
The number of packets received.
 when ping successfully executed, even if the acceptable_percent_loss was exceeded. str
packets_sent
The number of packets sent.
 when ping successfully executed, even if the acceptable_percent_loss was exceeded. str
rapid
Whether or not the pings were sent rapidly, as specified by the rapid option.
 when ping successfully executed, even if the acceptable_percent_loss was exceeded. bool
routing_instance
The routing-instance from which the pings were sent as specified by the routing_instance option.
 when ping successfully executed and the routing_instance option was specified, even if the acceptable_percent_loss was exceeded. str
rtt_average
The average round-trip-time, in microseconds, of all ping responses received.
 when ping successfully executed, and packet_loss < 100%. str
rtt_maximum
The maximum round-trip-time, in microseconds, of all ping responses received.
 when ping successfully executed, and packet_loss < 100%. str
rtt_minimum
The minimum round-trip-time, in microseconds, of all ping responses received.
 when ping successfully executed, and packet_loss < 100%. str
rtt_stddev
The standard deviation of round-trip-time, in microseconds, of all ping responses received.
 when ping successfully executed, and packet_loss < 100%. str
size
The size in bytes of the ICMP payload on the pings sent as specified by the size option.
Total size of the IP packet is size + the 20 byte IP header + the 8 byte ICMP header. Therefore, size of 1472 generates an IP packet of size 1500.
 when ping successfully executed and the size option was specified, even if the acceptable_percent_loss was exceeded. str
source
The source IP/host of the pings sent as specified by the source option.
Key source_ip is also returned for backwards compatibility.
 when ping successfully executed and the source option was specified, even if the acceptable_percent_loss was exceeded. str
timeout
The number of seconds to wait for a response from the ping RPC.
 when ping successfully executed, even if the acceptable_percent_loss was exceeded. str
ttl
The time-to-live set on the pings sent as specified by the ttl option.
 when ping successfully executed and the ttl option was specified, even if the acceptable_percent_loss was exceeded. str
warnings
A list of warning strings, if any, produced from the ping.
 when warnings are present list


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.

juniper_junos_command

Execute one or more CLI commands on a Junos device

New in version 2.0.0.

Synopsis

  • Execute one or more CLI commands on a Junos device.
  • This module does NOT use the Junos CLI to execute the CLI command. Instead, it uses the <command> RPC over a NETCONF channel. The <command> RPC takes a CLI command as it’s input and is very similar to executing the command on the CLI, but you can NOT include any pipe modifies (i.e. | match, | count, etc.) with the CLI commands executed by this module.

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
commands
 list yes none
A list of one or more CLI commands to execute on the Junos device.

aliases: cli, command, cmd, cmds
dest
 path no None
The path to a file, on the Ansible control machine, where the output of the cli command 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 value of the dest option. 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 cli command will be saved. The output will be logged to a file named {{ inventory_hostname }}_command.format in the directory specified by the value of the dest_dir option.
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
formats
 str or list of str no text
  • text
  • xml
  • json
The format of the reply for the CLI command(s) specified by the commands 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 command(s) specified by the commands option. If a list of formats are specified, there must be one value in the list for each command specified by the commands option. Specifying the value xml for the formats option is similar to appending | display xml to a CLI command, and specifying the value json for the formats option is similar to appending | display json to a CLI command.

aliases: format, display, output
return_output
 bool no True
  • yes
  • no
Indicates if the output of the command 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 command 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.

Examples

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

  tasks:
    - name: Execute single "show version" command.
      juniper_junos_command:
        commands: "show version"
      register: response

    - name: Print the command output
      debug:
        var: response.stdout

    - name: Execute three commands.
      juniper_junos_command:
        commands:
          - "show version"
          - "show system uptime"
          - "show interface terse"
      register: response

    - name: Print the command output of each.
      debug:
        var: item.stdout
      with_items: "{{ response.results }}"

    - name: Two commands with XML output.
      juniper_junos_command:
        commands:
          - "show route"
          - "show lldp neighbors"
        format: xml

    - name: show route with XML output - show version with JSON output
      juniper_junos_command:
        commands:
          - "show route"
          - "show version"
        formats:
          - "xml"
          - "json"

    - name: save outputs in dest_dir
      juniper_junos_command:
        commands:
          - "show route"
          - "show version"
        dest_dir: "./output"

    - name: save output to dest
      juniper_junos_command:
        command: "show system uptime"
        dest: "/tmp/{{ inventory_hostname }}.uptime.output"

    - name: save output to dest
      juniper_junos_command:
        command:
          - "show route"
          - "show lldp neighbors"
        dest: "/tmp/{{ inventory_hostname }}.commands.output"

    - name: Multiple commands, save outputs, but don't return them
      juniper_junos_command:
        commands:
          - "show route"
          - "show version"
        formats:
          - "xml"
          - "json"
        dest_dir: "/tmp/outputs/"
        return_output: false

Return Values

name description returned type sample
changed
Indicates if the device's state has changed. Since this module does not change the operational or configuration state of the device, the value is always set to false.
You could use this module to execute a command which changes the operational state of the the device. For example, clear ospf neighbors. Beware, this module is unable to detect this situation, and will still return the value false for changed in this case.
 success bool False
command
The CLI command which was executed.
 always str
failed
Indicates if the task failed. See the results key for additional details.
 always bool
format
The format of the command response.
 always str
msg
A human-readable message indicating the result.
 always str
parsed_output
The command reply from the Junos device parsed into a JSON data structure. 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 command executed successfully, return_output is true, and the value of the formats option is xml or json. dict
results
The other keys are returned when a single command is specified for the commands option. When the value of the commands option is a list of commands, this key is returned instead. The value of this key is a list of dictionaries. Each element in the list corresponds to the commands in the commands option. The keys for each element in the list include all of the other keys listed. The failed key indicates if the individual command 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 commands ran successfully. In this case, check the value of the failed key for each element in the results list for the results of individual commands.
 when the commands option is a list value. list of dict
stdout
The command reply from the Junos device as a single multi-line string.
 when command executed successfully and return_output is true. str
stdout_lines
The command reply from the Junos device as a list of single-line strings.
 when command 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.

juniper_junos_table

Retrieve data from a Junos device using a PyEZ table/view

New in version 2.0.0.

Synopsis

  • Retrieve data from a Junos device using PyEZ’s operational table/views. This module may be used with the tables/views which are included in the PyEZ distribution or it may be used with user-defined tables/views.

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
file
 path yes none
Name of the YAML file, relative to the path option, that contains the table/view definition. The file name must end with the .yml or .yaml extension.
kwargs
 dict no none
Optional keyword arguments and values to the table's get() method. The value of this option is a dictionary of keywords and values which are used to refine the data return from performing a get() on the table. The exact keywords and values which are supported are specific to the table's definition and the underlying RPC which the table invokes.

aliases: kwarg, args, arg
path
 path no op directory in jnpr.junos.op
The directory containing the YAML table/view definition file as specified by the file option. The default value is the op directory in jnpr.junos.op. This is the directory containing the table/view definitions which are included in the PyEZ distribution.

aliases: directory, dir
response_type
 str no list_of_dicts
  • list_of_dicts
  • juniper_items
Defines the format of data returned by the module. See RETURN. The value of the resource key in the module's response is either a list of dictionaries list_of_dicts or PyEZ's native return format juniper_items. Because Ansible module's may only return JSON data, PyEZ's native return format juniper_items is translated into a list of lists.
table
 str no The name of the table defined in the file option.
Name of the PyEZ table used to retrieve data. If not specified, defaults to the name of the table defined in the file option. Any table names in file which begin with _ are ignored. If more than one table is defined in file, the module fails with an error message. In this case, you must manually specify the name of the table by setting this option.

Examples

---
- name: Retrieve data from a Junos device using a PyEZ table/view.
  hosts: junos-all
  connection: local
  gather_facts: no
  roles:
    - Juniper.junos

  tasks:
    - name: Retrieve LLDP Neighbor Information Using PyEZ-included Table
      juniper_junos_table:
        file: "lldp.yml"
      register: response
    - name: Print response
      debug:
        var: response

    - name: Retrieve routes within 192.68.1/8
      juniper_junos_table:
        file: "routes.yml"
        table: "RouteTable"
        kwargs:
          destination: "192.68.1.0/8"
        response_type: "juniper_items"
      register: response
    - name: Print response
      debug:
        var: response

    - name: Retrieve from custom table in playbook directory
      juniper_junos_table:
        file: "fpc.yaml"
        path: "."
      register: response
    - name: Print response
      debug:
        var: response

Return Values

name description returned type sample
changed
Indicates if the device's configuration has changed. Since this module does not change the operational or configuration state of the device, the value is always set to false.
 success bool
failed
Indicates if the task failed.
 always bool
msg
A human-readable message indicating a summary of the result.
 always str
resource
The items retrieved by the table/view.
 success list of dicts if response_type is list_of_dicts or list of lists if respsonse_type is juniper_items. # when response_type == 'list_of_dicts' [ { "local_int": "ge-0/0/3", "local_parent": "-", "remote_chassis_id": "00:05:86:08:d4:c0", "remote_port_desc": null, "remote_port_id": "ge-0/0/0", "remote_sysname": "r5", "remote_type": "Mac address" }, { "local_int": "ge-0/0/0", "local_parent": "-", "remote_chassis_id": "00:05:86:18:f3:c0", "remote_port_desc": null, "remote_port_id": "ge-0/0/2", "remote_sysname": "r4", "remote_type": "Mac address" } ] # when response_type == 'juniper_items' [ [ "ge-0/0/3", [ [ "local_parent", "-" ], [ "remote_port_id", "ge-0/0/0" ], [ "remote_chassis_id", "00:05:86:08:d4:c0" ], [ "remote_port_desc", null ], [ "remote_type", "Mac address" ], [ "local_int", "ge-0/0/3" ], [ "remote_sysname", "r5" ] ] ], [ "ge-0/0/0", [ [ "local_parent", "-" ], [ "remote_port_id", "ge-0/0/2" ], [ "remote_chassis_id", "00:05:86:18:f3:c0" ], [ "remote_port_desc", null ], [ "remote_type", "Mac address" ], [ "local_int", "ge-0/0/0" ], [ "remote_sysname", "r4" ] ] ] ]


Notes

Note

  • This module only works with operational tables/views; it does not work with configuration tables/views.
  • The NETCONF system service must be enabled on the target Junos device.

Author

  • Jason Edelman (@jedelman8)
  • Updated by 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.

juniper_junos_facts

Retrieve facts from a Junos device

New in version 2.0.0.

Synopsis

  • Retrieve facts from a Junos device using the PyEZ fact gathering system.
  • Also returns the committed configuration of the Junos device if the config_format option has a value other than none.

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
config_format
 no none
  • none
  • xml
  • set
  • text
  • json
The format of the configuration returned. The specified format must be supported by the target Junos device.
savedir
 path no none
A path to a directory, on the Ansible control machine, where facts will be stored in a JSON file.
The resulting JSON file is saved in savedir/hostname-facts.json.
The savedir directory is the value of the savedir option.
The hostname-facts.json filename begins with the value of the hostname fact returned from the Junos device, which might be different than the value of the host option passed to the module.
If the value of the savedir option is none, the default, then facts are NOT saved to a file.

Examples

---
- name: Gather facts from Junos devices
  hosts: junos-all
  connection: local
  gather_facts: no
  roles:
    - Juniper.junos
  tasks:
    - name: Gather Junos facts with no configuration
      juniper_junos_facts:

# Print a fact

# Using config_format option

# Print the config

# Using savedir option

# Print the saved JSON file

Return Values

name description returned type sample
ansible_facts.junos
Facts collected from the Junos device. This dictionary contains the keys listed in the contains section of this documentation PLUS all of the keys returned from PyEZ's fact gathering system. See PyEZ facts for a complete list of these keys and their meaning.
 success complex
contains:
name description returned type sample
master_state
The mastership state of the Routing Engine to which Ansible is connected. true if the RE is the master Routing Engine. false if the RE is not the master Routing Engine.
 success bool
config
The device's committed configuration, in the format specified by config_format, as a single multi-line string.
 when config_format is not none. str
re_name
The name of the current Routing Engine to which Ansible is connected.
 success str
has_2RE
Indicates if the device has more than one Routing Engine installed. Because Ansible does not allow keys to begin with a number, this fact is returned in place of PyEZ's 2RE fact.
 success bool
changed
Indicates if the device's state has changed. Since this module does not change the operational or configuration state of the device, the value is always set to false.
 success bool False
facts
Returned for backwards compatibility. Returns the same keys and values which are returned under ansible_facts.junos.
 success dict
failed
Indicates if the task failed.
 always bool False


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.

juniper_junos_jsnapy

Execute JSNAPy tests on a Junos device

New in version 2.0.0.

Synopsis

  • Execute Junos SNAPshot Adminsitrator (JSNAPy) tests against a Junos device. JSNAPy is documented on Github and this Day One Book
  • This module only reports failed if the module encounters an error and fails to execute the JSNAPy tests. If does NOT report failed if one or more of the JSNAPy tests fail. To check the test results, register the module’s response and use the assert module to verify the expected result in the response. (See Examples.)
  • A callback plugin which formats and prints JSNAPy test results for human consumption is also available. This callback plugin is enabled by adding callback_whitelist = jsnapy to the Ansible configuration file.

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
action
 str yes none
  • check
  • snapcheck
  • snap_pre
  • snap_post
The JSNAPy action to perform.
config_file
 path no none
The filename of a JSNAPy configuration file (in YAML format). The test_files option and the config_file option are mutually exclusive. Either the test_files option or the config_file option is required.
dir
 path no /etc/jsnapy/testfiles
The path to the directory containing the JSNAPy test file(s) specified by the test_files option or the JSNAPy configuration file specified by the config_file option.

aliases: directory
test_files
 list of path no none
The filename of file(s) in the dir directory. Each file contains JSNAPy test case definitions. The test_files option and the config_file option are mutually exclusive. Either the test_files option or the config_file option is required.

Examples

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

  tasks:
    - name: JUNOS Post Checklist
      juniper_junos_jsnapy:
        action: "snap_post"
        config_file: "first_test.yml"
        logfile: "migration_post.log"
      register: test1
    - name: Verify all JSNAPy tests passed
      assert:
        that:
          - "test1.passPercentage == 100"
    - name: Print the full test response
      debug:
        var: test1

    - name: Test based on a test_file directly
      juniper_junos_jsnapy:
       action: "snapcheck"
       test_files: "tests/test_junos_interface.yaml"
      register: test2
    - name: Verify all JSNAPy tests passed
      assert:
        that:
          - "test2.passPercentage == 100"
    - name: Print the full test response
      debug:
        var: test2

    - name: "Collect Pre Snapshot"
      juniper_junos_jsnapy:
        action: "snap_pre"
        test_files: "tests/test_loopback.yml"

    - name: "Collect Post Snapshot"
      juniper_junos_jsnapy:
        action: "snap_post"
        test_files: "tests/test_loopback.yml"

    - name: "Check after Pre and Post Snapshots"
      juniper_junos_jsnapy:
        action: "check"
        test_files: "tests/test_loopback.yml"
      register: test3
    - name: Verify all JSNAPy tests passed
      assert:
        that:
          - "test3.|succeeded"
          - "test3.passPercentage == 100"
    - name: Print the full test response
      debug:
        var: test3

Return Values

name description returned type sample
action
The JSNAPy action performed as specified by the action option.
 success str
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.
 success bool
failed
Indicates if the task failed.
 always bool
msg
A human-readable message indicating the result of the JSNAPy tests.
 always str


Notes

Note

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

Author

  • Juniper Networks
  • Roslan Zaki
  • Damien Garros
  • 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.