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:

• junos-eznc >= 2.5.0
• Python >= 2.7

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
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.
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.

Common Connection-related Options

In addition to the Module-specific Options, the following connection-related options are also supported by this module:

parameter	type	required	default	choices	comments
attempts	int	no	10		The number of times to try connecting and logging in to the Junos device. This option is only applicable when using mode = 'telnet' or mode = 'serial'. Mutually exclusive with the console option.
baud	int	no	9600		The serial baud rate, in bits per second, used to connect to the Junos device. This option is only applicable when using mode = 'serial'. Mutually exclusive with the console option.
console	str	no	none		An alternate method of specifying a NETCONF over serial console connection to the Junos device using Telnet to a console server. The value of this option must be a string in the format --telnet <console_hostname>,<console_port_number>. This option is deprecated. It is present only for backwards compatibility. The string value of this option is exactly equivalent to specifying host with a value of <console_hostname>, mode with a value of telnet, and port with a value of <console_port_number>. Mutually exclusive with the mode, port, baud, and attempts options.
cs_passwd	str	no			The password used to authenticate with the console server over SSH. This option is only required if you want to connect to a device over console using SSH as transport. Mutually exclusive with the console option. aliases: console_password
cs_user	str	no			The username used to authenticate with the console server over SSH. This option is only required if you want to connect to a device over console using SSH as transport. Mutually exclusive with the console option. aliases: console_username
host	str	yes	{{ inventory_hostname }}		The hostname or IP address of the Junos device to which the connection should be established. This is normally the Junos device itself, but is the hostname or IP address of a console server when connecting to the console of the device by setting the mode option to the value telnet. This option is required, but does not have to be specified explicitly by the user because it defaults to {{ inventory_hostname }}. aliases: hostname, ip
mode	str	no	none	none telnet serial	The PyEZ mode used to establish a NETCONF connection to the Junos device. A value of none uses the default NETCONF over SSH mode. Depending on the values of the host and port options, a value of telnet results in either a direct NETCONF over Telnet connection to the Junos device, or a NETCONF over serial console connection to the Junos device using Telnet to a console server. A value of serial results in a NETCONF over serial console connection to the Junos device. Mutually exclusive with the console option.
passwd	str	no	The first defined value from the following list 1) The ANSIBLE_NET_PASSWORD environment variable. (used by Ansible Tower) 2) The value specified using the -k or --ask-pass command line arguments to the ansible or ansible-playbook command. 3) none (An empty password/passphrase)		The password, or ssh key's passphrase, used to authenticate with the Junos device. If this option is not specified, authentication is attempted using an empty password, or ssh key passphrase. aliases: password
port	int or str	no	830 if mode = none, 23 if mode = 'telnet', '/dev/ttyUSB0' if (mode = 'serial')		The TCP port number or serial device port used to establish the connection. Mutually exclusive with the console option.
provider	dict	no			An alternative syntax for specifying the connection options. Rather than specifying each connection-related top-level option, the connection-related options may be specified as a dictionary of suboptions to the provider option. All connection-related options must either be specified as top-level options or as suboptions of the provider option. You can not combine the two methods of specifying connection-related options.
	Dictionary object provider parameter type required default choices comments attempts int no 10 The number of times to try connecting and logging in to the Junos device. This option is only applicable when using mode = 'telnet' or mode = 'serial'. Mutually exclusive with the console option. baud int no 9600 The serial baud rate, in bits per second, used to connect to the Junos device. This option is only applicable when using mode = 'serial'. Mutually exclusive with the console option. console str no none An alternate method of specifying a NETCONF over serial console connection to the Junos device using Telnet to a console server. The value of this option must be a string in the format --telnet <console_hostname>,<console_port_number>. This option is deprecated. It is present only for backwards compatibility. The string value of this option is exactly equivalent to specifying host with a value of <console_hostname>, mode with a value of telnet, and port with a value of <console_port_number>. Mutually exclusive with the mode, port, baud, and attempts options. host str yes {{ inventory_hostname }} The hostname or IP address of the Junos device to which the connection should be established. This is normally the Junos device itself, but is the hostname or IP address of a console server when connecting to the console of the device by setting the mode option to the value telnet. This option is required, but does not have to be specified explicitly by the user because it defaults to {{ inventory_hostname }}. mode str no none none telnet serial The PyEZ mode used to establish a NETCONF connection to the Junos device. A value of none uses the default NETCONF over SSH mode. Depending on the values of the host and port options, a value of telnet results in either a direct NETCONF over Telnet connection to the Junos device, or a NETCONF over serial console connection to the Junos device using Telnet to a console server. A value of serial results in a NETCONF over serial console connection to the Junos device. Mutually exclusive with the console option. passwd str no The first defined value from the following list 1) The ANSIBLE_NET_PASSWORD environment variable. (used by Ansible Tower) 2) The value specified using the -k or --ask-pass command line arguments to the ansible or ansible-playbook command. 3) none (An empty password/passphrase) The password, or ssh key's passphrase, used to authenticate with the Junos device. If this option is not specified, authentication is attempted using an empty password, or ssh key passphrase. port int or str no 830 if mode = none, 23 if mode = 'telnet', '/dev/ttyUSB0' if (mode = 'serial') The TCP port number or serial device port used to establish the connection. Mutually exclusive with the console option. ssh_private_key_file path no The first defined value from the following list 1) The ANSIBLE_NET_SSH_KEYFILE environment variable. (used by Ansible Tower) 2) The value specified using the --private-key or --key-file command line arguments to the ansible or ansible-playbook command. 3) none (the file specified in the user's SSH configuration, or the operating-system-specific default) The path to the SSH private key file used to authenticate with the Junos device. If this option is not specified, and no default value is found using the algorithm below, then the SSH private key file specified in the user's SSH configuration, or the operating-system-specific default is used. This must be in the RSA PEM format, and not the newer OPENSSH format. To check if the private key is in the correct format, issue the command `head -n1 ~/.ssh/some_private_key` and ensure that it's RSA and not OPENSSH. To create a key in the RSA PEM format, issue the command `ssh-keygen -m PEM -t rsa -b 4096`. To convert an OPENSSH key to an RSA key, issue the command `ssh-keygen -p -m PEM -f ~/.ssh/some_private_key` ssh_config path no The path to the SSH client configuration file. If this option is not specified, then the PyEZ Device instance by default queries file ~/.ssh/config. timeout int no 30 The maximum number of seconds to wait for RPC responses from the Junos device. This option does NOT control the initial connection timeout value. user str yes The first defined value from the following list 1) The ANSIBLE_NET_USERNAME environment variable. (used by Ansible Tower) 2) The remote_user as defined by Ansible. Ansible sets this value via several methods including a) -u or --user command line arguments to the ansible or ansible-playbook command. b) ANSIBLE_REMOTE_USER environment variable. c) remote_user configuration setting. See the Ansible documentation for the precedence used to set the remote_user value. 3) The USER environment variable. The username used to authenticate with the Junos device. This option is required, but does not have to be specified explicitly by the user due to the algorithm for determining the default value. cs_user str no The username used to authenticate with the console server over SSH. This option is only required if you want to connect to a device over console using SSH as transport. Mutually exclusive with the console option. cs_passwd str no The password used to authenticate with the console server over SSH. This option is only required if you want to connect to a device over console using SSH as transport. Mutually exclusive with the console option.
ssh_config	path	no			The path to the SSH client configuration file. If this option is not specified, then the PyEZ Device instance by default queries file ~/.ssh/config.
ssh_private_key_file	path	no	The first defined value from the following list 1) The ANSIBLE_NET_SSH_KEYFILE environment variable. (used by Ansible Tower) 2) The value specified using the --private-key or --key-file command line arguments to the ansible or ansible-playbook command. 3) none (the file specified in the user's SSH configuration, or the operating-system-specific default)		The path to the SSH private key file used to authenticate with the Junos device. If this option is not specified, and no default value is found using the algorithm below, then the SSH private key file specified in the user's SSH configuration, or the operating-system-specific default is used. This must be in the RSA PEM format, and not the newer OPENSSH format. To check if the private key is in the correct format, issue the command `head -n1 ~/.ssh/some_private_key` and ensure that it's RSA and not OPENSSH. To create a key in the RSA PEM format, issue the command `ssh-keygen -m PEM -t rsa -b 4096`. To convert an OPENSSH key to an RSA key, issue the command `ssh-keygen -p -m PEM -f ~/.ssh/some_private_key` aliases: ssh_keyfile
timeout	int	no	30		The maximum number of seconds to wait for RPC responses from the Junos device. This option does NOT control the initial connection timeout value.
user	str	yes	The first defined value from the following list 1) The ANSIBLE_NET_USERNAME environment variable. (used by Ansible Tower) 2) The remote_user as defined by Ansible. Ansible sets this value via several methods including a) -u or --user command line arguments to the ansible or ansible-playbook command. b) ANSIBLE_REMOTE_USER environment variable. c) remote_user configuration setting. See the Ansible documentation for the precedence used to set the remote_user value. 3) The USER environment variable.		The username used to authenticate with the Junos device. This option is required, but does not have to be specified explicitly by the user due to the algorithm for determining the default value. aliases: username

Common Logging-related Options

In addition to the Module-specific Options, the following logging-related options are also supported by this module:

parameter	type	required	default	choices	comments
level	str	no	WARNING	INFO DEBUG	The level of information to be logged can be modified using this option 1) By default, messages at level WARNING or higher are logged. 2) If the -v or --verbose command-line options to the ansible-playbook command are specified, messages at level INFO or higher are logged. 3) If the -vv (or more verbose) command-line option to the ansible-playbook command is specified, or the ANSIBLE_DEBUG environment variable is set, then messages at level DEBUG or higher are logged. 4) If level is mentioned then messages at level level or more are logged.
logdir	path	no	none		The path to a directory, on the Ansible control machine, where debugging information for the particular task is logged. If this option is specified, debugging information is logged to a file named {{ inventory_hostname }}.log in the directory specified by the logdir option. The log file must be writeable. If the file already exists, it is appended. It is the users responsibility to delete/rotate log files. The level of information logged in this file is controlled by Ansible's verbosity, debug options and level option in task 1) By default, messages at level WARNING or higher are logged. 2) If the -v or --verbose command-line options to the ansible-playbook command are specified, messages at level INFO or higher are logged. 3) If the -vv (or more verbose) command-line option to the ansible-playbook command is specified, or the ANSIBLE_DEBUG environment variable is set, then messages at level DEBUG or higher are logged. 4) If level is mentioned then messages at level level or more are logged. The logfile and logdir options are mutually exclusive. The logdir option is recommended for all new playbooks. aliases: log_dir
logfile	path	no	none		The path to a file, on the Ansible control machine, where debugging information for the particular task is logged. The log file must be writeable. If the file already exists, it is appended. It is the users responsibility to delete/rotate log files. The level of information logged in this file is controlled by Ansible's verbosity, debug options and level option in task 1) By default, messages at level WARNING or higher are logged. 2) If the -v or --verbose command-line options to the ansible-playbook command are specified, messages at level INFO or higher are logged. 3) If the -vv (or more verbose) command-line option to the ansible-playbook command is specified, or the ANSIBLE_DEBUG environment variable is set, then messages at level DEBUG or higher are logged. 4) If level is mentioned then messages at level level or more are logged. 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 logfile 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 logdir option in new playbooks. The logfile and logdir options are mutually exclusive. aliases: log_file

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

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.