From c4f5cf8a055efe21d211aa1674932ffa9e0f1c68 Mon Sep 17 00:00:00 2001 From: rahkumar651991 Date: Wed, 24 Mar 2021 13:17:29 +0530 Subject: [PATCH 1/4] Removing provider from the readthedocs for collection --- .../plugins/module_utils/juniper_junos_common.py | 13 ------------- requirements.txt | 4 ++-- 2 files changed, 2 insertions(+), 15 deletions(-) diff --git a/ansible_collections/juniper/device/plugins/module_utils/juniper_junos_common.py b/ansible_collections/juniper/device/plugins/module_utils/juniper_junos_common.py index f61e1add..77262d28 100644 --- a/ansible_collections/juniper/device/plugins/module_utils/juniper_junos_common.py +++ b/ansible_collections/juniper/device/plugins/module_utils/juniper_junos_common.py @@ -344,19 +344,6 @@ class ModuleDocFragment(object): # Build actual DOCUMENTATION string by putting the pieces together. CONNECTION_DOCUMENTATION = ''' connection_options:''' + _CONNECT_DOCUMENTATION + ''' - provider: - description: - - 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 I(provider) option. All connection-related options - must either be specified as top-level options or as suboptions of - the I(provider) option. You can not combine the two methods of - specifying connection-related options. - required: false - default: none - type: dict - suboptions:''' + _SUB_CONNECT_DOCUMENTATION + ''' requirements: - U(junos-eznc|https://github.com/Juniper/py-junos-eznc) >= ''' + cfg.MIN_PYEZ_VERSION + ''' - Python >= 3.5 diff --git a/requirements.txt b/requirements.txt index 2ec42d6b..737434c0 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,5 +1,5 @@ ansible >= 2.10 junos-eznc >= 2.5.4 -jsnapy>=1.3.4 +jsnapy>=1.3.6 jxmlease -xmltodict \ No newline at end of file +xmltodict From 5f43fea9e9e4e3e873bfe87d42e6e873792352fd Mon Sep 17 00:00:00 2001 From: rahkumar651991 Date: Wed, 31 Mar 2021 18:04:11 +0530 Subject: [PATCH 2/4] Adding support for variables to be passed in vars --- .../juniper/device/plugins/action/extract_data.py | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/ansible_collections/juniper/device/plugins/action/extract_data.py b/ansible_collections/juniper/device/plugins/action/extract_data.py index a3a24113..62f10847 100644 --- a/ansible_collections/juniper/device/plugins/action/extract_data.py +++ b/ansible_collections/juniper/device/plugins/action/extract_data.py @@ -35,15 +35,15 @@ import os connection_spec_fallbacks = { - 'host': ['host', 'ansible_host', 'inventory_hostname'], - 'user': ['user', 'ansible_connection_user', 'ansible_ssh_user', 'ansible_user'], + 'host': ['host', 'hostname', 'ip', 'ansible_host', 'inventory_hostname'], + 'user': ['user', 'username', 'ansible_connection_user', 'ansible_ssh_user', 'ansible_user'], 'passwd': ['passwd', 'ansible_ssh_pass', 'ansible_pass'], 'port': ['port', 'ansible_ssh_port', 'ansible_port'], 'ssh_private_key_file': ['ssh_private_key_file', 'ansible_ssh_private_key_file', 'ansible_private_key_file', 'ssh_keyfile'], 'ssh_config': ['ssh_config'], - 'cs_user': ['cs_user'], - 'cs_passwd': ['cs_passwd'], + 'cs_user': ['cs_user', 'console_username'], + 'cs_passwd': ['cs_passwd', 'console_password'], 'attempts': ['attempts'], 'baud': ['baud'], 'console': ['console'], @@ -85,6 +85,12 @@ def extract(self, tmp=None, task_vars=None): for task_var_key in connection_spec_fallbacks[key]: if task_var_key in task_vars: new_connection_args[key] = task_vars[task_var_key] + # check if the value is in form of a variable {{var}} + # In case of variables, resolve it to the value + index = str(new_connection_args[key]).find('{{') + if index == 0: + tempKey = new_connection_args[key][2:-2].strip() + new_connection_args[key] = task_vars[tempKey] break # Backwards compatible behavior to fallback to USER env. variable. From b8cad085fd440a9929ec763ebb796a847de41206 Mon Sep 17 00:00:00 2001 From: rahkumar651991 Date: Mon, 12 Apr 2021 21:24:24 +0530 Subject: [PATCH 3/4] Adding alias for the parameters --- .../juniper/device/plugins/action/extract_data.py | 2 +- .../juniper/device/plugins/connection/pyez.py | 5 +++++ 2 files changed, 6 insertions(+), 1 deletion(-) diff --git a/ansible_collections/juniper/device/plugins/action/extract_data.py b/ansible_collections/juniper/device/plugins/action/extract_data.py index 62f10847..6b4df350 100644 --- a/ansible_collections/juniper/device/plugins/action/extract_data.py +++ b/ansible_collections/juniper/device/plugins/action/extract_data.py @@ -37,7 +37,7 @@ connection_spec_fallbacks = { 'host': ['host', 'hostname', 'ip', 'ansible_host', 'inventory_hostname'], 'user': ['user', 'username', 'ansible_connection_user', 'ansible_ssh_user', 'ansible_user'], - 'passwd': ['passwd', 'ansible_ssh_pass', 'ansible_pass'], + 'passwd': ['passwd', 'password', 'ansible_ssh_pass', 'ansible_pass'], 'port': ['port', 'ansible_ssh_port', 'ansible_port'], 'ssh_private_key_file': ['ssh_private_key_file', 'ansible_ssh_private_key_file', 'ansible_private_key_file', 'ssh_keyfile'], diff --git a/ansible_collections/juniper/device/plugins/connection/pyez.py b/ansible_collections/juniper/device/plugins/connection/pyez.py index c5e87a53..11f93923 100644 --- a/ansible_collections/juniper/device/plugins/connection/pyez.py +++ b/ansible_collections/juniper/device/plugins/connection/pyez.py @@ -50,6 +50,8 @@ vars: - name: ansible_host - name: host + - name: hostname + - name: ip port: description: - Specifies the port on the remote device that listens for connections when establishing @@ -91,6 +93,7 @@ vars: - name: ansible_user - name: user + - name: username password: description: - Configures the user password used to authenticate to the remote device when @@ -100,6 +103,7 @@ - name: ansible_ssh_pass - name: ansible_ssh_password - name: passwd + - name: password pyez_console: description: - console option. @@ -197,6 +201,7 @@ - name: ANSIBLE_PYEZ_SSH_CONFIG vars: - name: ansible_pyez_ssh_config + - name: ssh_config """ import pickle From ad4f6f30e45543f7a5d95667252b7a93488a8bff Mon Sep 17 00:00:00 2001 From: rahkumar651991 Date: Fri, 16 Apr 2021 14:10:17 +0530 Subject: [PATCH 4/4] Readthedocs related changes to generate inndex file properly --- .../juniper/device/docs/ansible2rst.py | 8 +- .../juniper/device/docs/command.rst | 568 +++++++++ .../juniper/device/docs/config.rst | 1020 +++++++++++++++++ .../juniper/device/docs/facts.rst | 511 +++++++++ .../juniper/device/docs/jsnapy.rst | 499 ++++++++ .../juniper/device/docs/ping.rst | 773 +++++++++++++ .../juniper/device/docs/pmtud.rst | 561 +++++++++ .../juniper/device/docs/rpc.rst | 639 +++++++++++ .../juniper/device/docs/software.rst | 686 +++++++++++ .../juniper/device/docs/srx_cluster.rst | 454 ++++++++ .../juniper/device/docs/system.rst | 565 +++++++++ .../juniper/device/docs/table.rst | 576 ++++++++++ 12 files changed, 6856 insertions(+), 4 deletions(-) create mode 100644 ansible_collections/juniper/device/docs/command.rst create mode 100644 ansible_collections/juniper/device/docs/config.rst create mode 100644 ansible_collections/juniper/device/docs/facts.rst create mode 100644 ansible_collections/juniper/device/docs/jsnapy.rst create mode 100644 ansible_collections/juniper/device/docs/ping.rst create mode 100644 ansible_collections/juniper/device/docs/pmtud.rst create mode 100644 ansible_collections/juniper/device/docs/rpc.rst create mode 100644 ansible_collections/juniper/device/docs/software.rst create mode 100644 ansible_collections/juniper/device/docs/srx_cluster.rst create mode 100644 ansible_collections/juniper/device/docs/system.rst create mode 100644 ansible_collections/juniper/device/docs/table.rst diff --git a/ansible_collections/juniper/device/docs/ansible2rst.py b/ansible_collections/juniper/device/docs/ansible2rst.py index 34cfbd6e..fd3ab65f 100755 --- a/ansible_collections/juniper/device/docs/ansible2rst.py +++ b/ansible_collections/juniper/device/docs/ansible2rst.py @@ -238,8 +238,8 @@ def get_docstring(filename, verbose=False): data = read_docstring(filename, verbose=verbose) # add fragments to documentation - if data.get('doc', False): - add_fragments(data['doc'], filename) + # if data.get('doc', False): + # add_fragments(data['doc'], filename) return data['doc'], data['plainexamples'], data['returndocs'], data['metadata'] @@ -392,7 +392,7 @@ def process_module(fname, template, outputname, aliases=None): # here is where we build the table of contents... text = template.render(doc) - write_data(text, outputname, module_name, OUTPUTDIR) + # write_data(text, outputname, module_name, OUTPUTDIR) ##################################################################################### @@ -410,7 +410,7 @@ def main(): index_file_path = os.path.join(OUTPUTDIR, "index.rst") index_file = open(index_file_path, "w") index_file.write('juniper.device Ansible Modules\n') - index_file.write('=================================================\n') + index_file.write('==============================\n') index_file.write('\n') index_file.write('Contents:\n') index_file.write('\n') diff --git a/ansible_collections/juniper/device/docs/command.rst b/ansible_collections/juniper/device/docs/command.rst new file mode 100644 index 00000000..aa1ba5f4 --- /dev/null +++ b/ansible_collections/juniper/device/docs/command.rst @@ -0,0 +1,568 @@ +.. _command: + +command ++++++++ +Execute one or more CLI commands on a Junos device + + + +.. contents:: + :local: + :depth: 2 + + +Synopsis +-------- + + +* Execute one or more CLI commands on a Junos device. +* Alias command +* This module does NOT use the Junos CLI to execute the CLI command. Instead, it uses the ```` RPC over a NETCONF channel. The ```` 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.2 +* Python >= 3.5 + + + +.. _module-specific-options-label: + +Module-specific Options +----------------------- +The following options may be specified for this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
parametertyperequireddefaultchoicescomments
commands
listyesnone +
A list of one or more CLI commands to execute on the Junos device.
+
aliases: cli, command, cmd, cmds
+
dest
pathnoNone +
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
pathnoNone +
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 strnotext
  • 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
boolnoTrue
  • 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 :ref:`module-specific-options-label`, the following connection-related options are also supported by this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
parametertyperequireddefaultchoicescomments
attempts
intno10 +
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
intno9600 +
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
strnonone +
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
strno +
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
strno +
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
stryes{{ 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
strnonone
  • 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
strnoThe 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 strno830 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_config
pathno +
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
pathnoThe 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
intno30 +
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
stryesThe 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 :ref:`module-specific-options-label`, the following logging-related options are also supported by this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
parametertyperequireddefaultchoicescomments
level
strnoWARNING
  • 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
pathnonone +
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
pathnonone +
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
+
+
+ +.. _command-examples-label: + +Examples +-------- + +:: + + + - name: 'Explicit host argument' + hosts: junos + connection: local + gather_facts: no + collections: + - juniper.device + + tasks: + - name: "Execute single command in text format" + command: + commands: "show configuration system services netconf traceoptions" + format: text + + - name: "Execute command with login credentials" + command: + host: "10.x.x.x." + user: "user" + passwd: "user123" + commands: + - "show system storage" + register: junos_result + + - name: Execute three commands. + 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: show route with XML output - show version with JSON output + command: + commands: + - "show route" + - "show version" + formats: + - "xml" + - "json" + + - name: Multiple commands, save outputs, but don't return them + command: + commands: + - "show route" + - "show version" + formats: + - "xml" + dest_dir: "../Output" + return_output: false + + - name: save output to dest + command: + command: + - "show route" + - "show lldp neighbors" + dest: "/tmp/{{ inventory_hostname }}.commands.output" + + + +Return Values +------------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
namedescriptionreturnedtypesample
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.
+ 		successboolFalse
command +
The CLI command which was executed.
+ 		alwaysstr
failed +
Indicates if the task failed. See the results key for additional details.
+ 		alwaysbool
format +
The format of the command response.
+ 		alwaysstr
msg +
A human-readable message indicating the result.
+ 		alwaysstr
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. + + diff --git a/ansible_collections/juniper/device/docs/config.rst b/ansible_collections/juniper/device/docs/config.rst new file mode 100644 index 00000000..c31cb80d --- /dev/null +++ b/ansible_collections/juniper/device/docs/config.rst @@ -0,0 +1,1020 @@ +.. _config: + +config +++++++ +Manipulate the configuration of a Junos device + + + +.. contents:: + :local: + :depth: 2 + + +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: +#. 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. +#. 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. +#. 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 " operation + without actually performing an additional commit. + * If the configuration check fails, further processing stops, the module + fails, and an error is reported. +#. 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. +#. 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. +#. 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 " 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. +#. 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: + +* `junos-eznc `_ >= 2.5.2 +* Python >= 3.5 + + + +.. _module-specific-options-label: + +Module-specific Options +----------------------- +The following options may be specified for this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
parametertyperequireddefaultchoicescomments
check
boolnotrue (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
intnonone +
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
strnonone +
Provide a comment to be used with the commit operation.
+
This option is only valid if the commit option is true.
+
commit
boolnotrue (false if retrieve is set and load and rollback are not set)
  • yes
  • no
 +
Perform a commit operation.
+
commit_empty_changes
boolnoFalse
  • yes
  • no
 +
Perform a commit operation, even if there are no changes between the candidate configuration and the committed configuration.
+
config_mode
strnoexclusive
  • exclusive
  • private
 +
The mode used to access the candidate configuration database.
+
aliases: config_access, edit_mode, edit_access
+
confirmed
intnonone +
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
pathnonone +
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
pathnonone +
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
boolnotrue (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
pathnoNone +
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
strnonone +
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
strnonone (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 strnonone +
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
listnonone +
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
strnonone
  • 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
dictnoNone +
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
strnonone
  • none
  • candidate
  • committed
 +
The configuration database to be retrieved.
+
return_output
boolnoTrue
  • 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 strnonone
  • 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
pathnonone +
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
pathnonone +
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
strnonone +
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
dictnonone +
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
+
+
+ +Common Connection-related Options +--------------------------------- +In addition to the :ref:`module-specific-options-label`, the following connection-related options are also supported by this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
parametertyperequireddefaultchoicescomments
attempts
intno10 +
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
intno9600 +
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
strnonone +
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
strno +
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
strno +
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
stryes{{ 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
strnonone
  • 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
strnoThe 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 strno830 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_config
pathno +
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
pathnoThe 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
intno30 +
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
stryesThe 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 :ref:`module-specific-options-label`, the following logging-related options are also supported by this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
parametertyperequireddefaultchoicescomments
level
strnoWARNING
  • 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
pathnonone +
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
pathnonone +
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
+
+
+ +.. _config-examples-label: + +Examples +-------- + +:: + + + --- + - name: 'Explicit host argument' + hosts: junos + connection: local + gather_facts: no + collections: + - juniper.device + + tasks: + - name: Retrieve the committed configuration + 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. + 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. + config: + config_mode: 'private' + rollback: 1 + register: response + + - name: Print the config changes. + debug: + var: response.diff_lines + + - name: Rollback to the rescue config. + config: + rollback: 'rescue' + register: response + - name: Print the complete response. + debug: + var: response + + - name: Load override from a file. + config: + load: 'override' + src: "{{ inventory_hostname }}.conf" + register: response + + - name: Print the complete response. + debug: + var: response + + - name: Load from a Jinja2 template. + 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. + 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 + 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. + 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. + 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. + 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 + 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) + config: + check: true + diff: false + commit: false + register: response + + - name: Print the complete response + debug: + var: response + + - name: fetch config from the device with filter and login credentials + config: + host: "10.x.x.x" + user: "user" + passwd: "user123" + port: "22" + retrieve: 'committed' + format: xml + commit: no + check: no + diff: no + dest_dir: "/tmp/" + filter: re0 + return_output: True + register: config_output + + + +Return Values +------------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
namedescriptionreturnedtypesample
changed +
Indicates if the device's configuration has changed, or would have changed when in check mode.
+ 		successbool
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 dict that contains a single key named "prepared". Value associated with that key is a single multi-line string in "diff" format.
+ 		when load or rollback is specified, diff is true, and return_output is true.dict
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.
+ 		alwaysbool
file +
The value of the src option.
+ 		when load is not none and src is not nonestr
msg +
A human-readable message indicating the result.
+ 		alwaysstr
+
+
+ + +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. + + diff --git a/ansible_collections/juniper/device/docs/facts.rst b/ansible_collections/juniper/device/docs/facts.rst new file mode 100644 index 00000000..e02ab78d --- /dev/null +++ b/ansible_collections/juniper/device/docs/facts.rst @@ -0,0 +1,511 @@ +.. _facts: + +facts ++++++ +Retrieve facts from a Junos device + + + +.. contents:: + :local: + :depth: 2 + + +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: + +* `junos-eznc `_ >= 2.5.2 +* Python >= 3.5 + + + +.. _module-specific-options-label: + +Module-specific Options +----------------------- +The following options may be specified for this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
parametertyperequireddefaultchoicescomments
config_format
nonone
  • none
  • xml
  • set
  • text
  • json
 +
The format of the configuration returned. The specified format must be supported by the target Junos device.
+
savedir
pathnonone +
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.
+
+
+ +Common Connection-related Options +--------------------------------- +In addition to the :ref:`module-specific-options-label`, the following connection-related options are also supported by this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
parametertyperequireddefaultchoicescomments
attempts
intno10 +
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
intno9600 +
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
strnonone +
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
strno +
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
strno +
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
stryes{{ 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
strnonone
  • 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
strnoThe 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 strno830 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_config
pathno +
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
pathnoThe 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
intno30 +
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
stryesThe 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 :ref:`module-specific-options-label`, the following logging-related options are also supported by this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
parametertyperequireddefaultchoicescomments
level
strnoWARNING
  • 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
pathnonone +
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
pathnonone +
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
+
+
+ +.. _facts-examples-label: + +Examples +-------- + +:: + + + --- + - name: 'Explicit host argument' + hosts: junos + connection: local + gather_facts: no + collections: + - juniper.device + + tasks: + - name: "Get facts" + facts: + register: response + + - name: Facts with login credentials + facts: + host: "10.x.x.x" + user: "user" + passwd: "user123" + port: "22" + + - name: Facts in telnet mode + facts: + host: "10.x.x.x" + user: "user" + passwd: "user123" + port: "23" + mode: "telnet" + + # Print a fact + + # Using config_format option + + # Print the config + + # Using savedir option + + # Print the saved JSON file + + + +Return Values +------------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
namedescriptionreturnedtypesample
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.
+ 		successcomplex
contains: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
namedescriptionreturnedtypesample
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
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.
+ 		successbool
re_name +
The name of the current Routing Engine to which Ansible is connected.
+ 		successstr
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.
+ 		successbool
+
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.
+ 		successboolFalse
facts +
Returned for backwards compatibility. Returns the same keys and values which are returned under ansible_facts.junos.
+ 		successdict
failed +
Indicates if the task failed.
+ 		alwaysboolFalse
+
+
+ + +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. + + diff --git a/ansible_collections/juniper/device/docs/jsnapy.rst b/ansible_collections/juniper/device/docs/jsnapy.rst new file mode 100644 index 00000000..a2c506ec --- /dev/null +++ b/ansible_collections/juniper/device/docs/jsnapy.rst @@ -0,0 +1,499 @@ +.. _jsnapy: + +jsnapy +++++++ +Execute JSNAPy tests on a Junos device + + + +.. contents:: + :local: + :depth: 2 + + +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 :ref:`jsnapy-examples-label`.) +* 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: + +* `junos-eznc `_ >= 2.5.2 +* Python >= 3.5 + + + +.. _module-specific-options-label: + +Module-specific Options +----------------------- +The following options may be specified for this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
parametertyperequireddefaultchoicescomments
action
stryesnone
  • check
  • snapcheck
  • snap_pre
  • snap_post
 +
The JSNAPy action to perform.
+
config_file
pathnonone +
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
pathno/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 pathnonone +
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.
+
+
+ +Common Connection-related Options +--------------------------------- +In addition to the :ref:`module-specific-options-label`, the following connection-related options are also supported by this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
parametertyperequireddefaultchoicescomments
attempts
intno10 +
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
intno9600 +
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
strnonone +
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
strno +
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
strno +
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
stryes{{ 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
strnonone
  • 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
strnoThe 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 strno830 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_config
pathno +
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
pathnoThe 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
intno30 +
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
stryesThe 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 :ref:`module-specific-options-label`, the following logging-related options are also supported by this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
parametertyperequireddefaultchoicescomments
level
strnoWARNING
  • 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
pathnonone +
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
pathnonone +
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
+
+
+ +.. _jsnapy-examples-label: + +Examples +-------- + +:: + + + --- + - name: Examples of jsnapy + hosts: junos-all + connection: local + gather_facts: no + collections: + - juniper.device + + tasks: + - name: JUNOS Post Checklist + 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 + 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" + jsnapy: + action: "snap_pre" + test_files: "tests/test_loopback.yml" + + - name: "Collect Post Snapshot" + jsnapy: + action: "snap_post" + test_files: "tests/test_loopback.yml" + + - name: "Check after Pre and Post Snapshots" + 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 +------------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
namedescriptionreturnedtypesample
action +
The JSNAPy action performed as specified by the action option.
+ 		successstr
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.
+ 		successbool
failed +
Indicates if the task failed.
+ 		alwaysbool
msg +
A human-readable message indicating the result of the JSNAPy tests.
+ 		alwaysstr
+
+
+ + +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. + + diff --git a/ansible_collections/juniper/device/docs/ping.rst b/ansible_collections/juniper/device/docs/ping.rst new file mode 100644 index 00000000..72516d37 --- /dev/null +++ b/ansible_collections/juniper/device/docs/ping.rst @@ -0,0 +1,773 @@ +.. _ping: + +ping +++++ +Execute ping from a Junos device + + + +.. contents:: + :local: + :depth: 2 + + +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: + +* `junos-eznc `_ >= 2.5.2 +* Python >= 3.5 + + + +.. _module-specific-options-label: + +Module-specific Options +----------------------- +The following options may be specified for this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
parametertyperequireddefaultchoicescomments
acceptable_percent_loss
intno0 +
Maximum percentage of packets that may be lost and still consider the task not to have failed.
+
aliases: acceptable_packet_loss
+
count
intno5 +
Number of packets to send.
+
dest
stryesnone +
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
boolnoFalse
  • yes
  • no
 +
Set Do Not Fragment bit on ping packets.
+
interface
strnonone +
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
boolnoTrue
  • yes
  • no
 +
Send ping requests rapidly
+
routing_instance
strnonone +
Name of the source routing instance from which the ping is originated. If not specified, the default routing instance is used.
+
size
intnonone (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
strnonone +
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
intnonone (default ttl for device) +
Maximum number of IP routers (hops) allowed between source and destination.
+
+
+ +Common Connection-related Options +--------------------------------- +In addition to the :ref:`module-specific-options-label`, the following connection-related options are also supported by this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
parametertyperequireddefaultchoicescomments
attempts
intno10 +
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
intno9600 +
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
strnonone +
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
strno +
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
strno +
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
stryes{{ 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
strnonone
  • 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
strnoThe 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 strno830 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_config
pathno +
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
pathnoThe 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
intno30 +
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
stryesThe 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 :ref:`module-specific-options-label`, the following logging-related options are also supported by this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
parametertyperequireddefaultchoicescomments
level
strnoWARNING
  • 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
pathnonone +
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
pathnonone +
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
+
+
+ +.. _ping-examples-label: + +Examples +-------- + +:: + + + --- + - name: Examples of ping + hosts: junos-all + connection: local + gather_facts: no + collections: + - juniper.device + + tasks: + - name: Ping 192.68.1.1 with default parameters. Fails if any packets lost. + ping: + dest: "192.68.1.1" + + - name: Ping 192.68.1.1 Allow 50% packet loss. Register response. + 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. + 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. + 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. + 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. + 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. + 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. + 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. + ping: + dest: "192.168.1.1" + routing_instance: "red" + + - name: Ping the all-hosts multicast address from the ge-0/0/0.0 interface + ping: + dest: "224.0.0.1" + interface: "ge-0/0/0.0" + + + +Return Values +------------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
namedescriptionreturnedtypesample
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.
+ 		alwaysbool
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.
+ 		alwaysstr
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 presentlist
+
+
+ + +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. + + diff --git a/ansible_collections/juniper/device/docs/pmtud.rst b/ansible_collections/juniper/device/docs/pmtud.rst new file mode 100644 index 00000000..bedca7b4 --- /dev/null +++ b/ansible_collections/juniper/device/docs/pmtud.rst @@ -0,0 +1,561 @@ +.. _pmtud: + +pmtud ++++++ +Perform path MTU discovery from a Junos device to a destination + + + +.. contents:: + :local: + :depth: 2 + + +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: + +* `junos-eznc `_ >= 2.5.2 +* Python >= 3.5 + + + +.. _module-specific-options-label: + +Module-specific Options +----------------------- +The following options may be specified for this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
parametertyperequireddefaultchoicescomments
dest
stryesnone +
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
strnonone +
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
intno512 +
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
intno1500 +
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
strnonone +
Name of the source routing instance from which the ping is originated.
+
If not specified, the default routing instance is used.
+
source
strnonone +
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
+
+
+ +Common Connection-related Options +--------------------------------- +In addition to the :ref:`module-specific-options-label`, the following connection-related options are also supported by this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
parametertyperequireddefaultchoicescomments
attempts
intno10 +
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
intno9600 +
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
strnonone +
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
strno +
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
strno +
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
stryes{{ 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
strnonone
  • 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
strnoThe 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 strno830 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_config
pathno +
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
pathnoThe 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
intno30 +
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
stryesThe 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 :ref:`module-specific-options-label`, the following logging-related options are also supported by this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
parametertyperequireddefaultchoicescomments
level
strnoWARNING
  • 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
pathnonone +
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
pathnonone +
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
+
+
+ +.. _pmtud-examples-label: + +Examples +-------- + +:: + + + --- + - name: Examples of pmtud + hosts: junos-all + connection: local + gather_facts: no + collections: + - juniper.device + + tasks: + - name: Perform PMTUD to 192.68.1.1 with default parameters. + pmtud: + dest: "192.68.1.1" + + - name: Perform PMTUD to 192.68.1.1. Register response. + 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. + 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. + 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. + 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. + pmtud: + dest: "192.68.1.1" + routing_instance: "red" + register: response + - name: Print the discovered MTU. + debug: + var: response.inet_mtu + + + +Return Values +------------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
namedescriptionreturnedtypesample
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.
+ 		alwaysbool
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 presentlist
+
+
+ + +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. + + diff --git a/ansible_collections/juniper/device/docs/rpc.rst b/ansible_collections/juniper/device/docs/rpc.rst new file mode 100644 index 00000000..6f85f873 --- /dev/null +++ b/ansible_collections/juniper/device/docs/rpc.rst @@ -0,0 +1,639 @@ +.. _rpc: + +rpc ++++ +Execute one or more NETCONF RPCs on a Junos device + + + +.. contents:: + :local: + :depth: 2 + + +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: + +* `junos-eznc `_ >= 2.5.2 +* Python >= 3.5 + + + +.. _module-specific-options-label: + +Module-specific Options +----------------------- +The following options may be specified for this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
parametertyperequireddefaultchoicescomments
attrs
dict or list of dictnonone +
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
pathnoNone +
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
pathnoNone +
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
strnonone +
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 strnoxml
  • 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
+
ignore_warning
bool, str, or list of strnonone +
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.
+
kwargs
dict or list of dictnonone +
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:`rpc-examples-label`.
+
aliases: kwarg, args, arg
+
return_output
boolnoTrue
  • 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
listyesnone +
A list of one or more NETCONF RPCs to execute on the Junos device.
+
aliases: rpc
+
+
+ +Common Connection-related Options +--------------------------------- +In addition to the :ref:`module-specific-options-label`, the following connection-related options are also supported by this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
parametertyperequireddefaultchoicescomments
attempts
intno10 +
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
intno9600 +
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
strnonone +
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
strno +
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
strno +
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
stryes{{ 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
strnonone
  • 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
strnoThe 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 strno830 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_config
pathno +
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
pathnoThe 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
intno30 +
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
stryesThe 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 :ref:`module-specific-options-label`, the following logging-related options are also supported by this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
parametertyperequireddefaultchoicescomments
level
strnoWARNING
  • 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
pathnonone +
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
pathnonone +
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
+
+
+ +.. _rpc-examples-label: + +Examples +-------- + +:: + + + --- + - name: 'Explicit host argument' + hosts: junos + connection: local + gather_facts: no + collections: + - juniper.device + + tasks: + - name: "Execute RPC with filters" + rpc: + rpcs: + - "get-config" + format: xml + filter: re0 + attr: name=re0 + register: test1 + ignore_errors: True + + - name: Check TEST 1 + debug: + var: test1 + + - name: "Execute RPC with host data and store logging" + rpc: + host: "10.x.x.x" + user: "user" + passwd: "user123" + port: "22" + rpcs: + - "get-software-information" + logfile: "/var/tmp/rpc.log" + ignore_warning: true + register: test1 + ignore_errors: True + + - name: "Print results - summary" + debug: + var: test1.stdout_lines + + - name: "Execute multiple RPC" + rpc: + rpcs: + - "get-config" + - "get-software-information" + + - name: Get Device Configuration for vlan - 1 + rpc: + rpc: "get-config" + filter_xml: "" + dest: "get_config_vlan.conf" + register: junos + + - name: Get interface information with kwargs + rpc: + rpc: get-interface-information + kwargs: + interface_name: em1 + media: True + format: json + dest: get_interface_information.conf + register: junos + + +Return Values +------------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
namedescriptionreturnedtypesample
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.
+ 		alwaysdict
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.
+ 		successbool
failed +
Indicates if the task failed. See the results key for additional details.
+ 		alwaysbool
format +
The format of the RPC response from the list of formats in the formats option.
+ 		alwaysstr
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.
+ 		alwaysdict
msg +
A human-readable message indicating the result.
+ 		alwaysstr
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.
+ 		alwaysstr
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. + + diff --git a/ansible_collections/juniper/device/docs/software.rst b/ansible_collections/juniper/device/docs/software.rst new file mode 100644 index 00000000..69730ccb --- /dev/null +++ b/ansible_collections/juniper/device/docs/software.rst @@ -0,0 +1,686 @@ +.. _software: + +software +++++++++ +Install software on a Junos device + + + +.. contents:: + :local: + :depth: 2 + + +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: + +#. 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. +#. If the *local_package* option is specified, compute the MD5 checksum + of the *local_package* file on the local Ansible control machine. +#. 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. +#. If the *cleanfs* option is ``true``, the default, then perform the + equivalent of the ``request system storage cleanup`` CLI command. +#. 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. +#. Install the software pacakge from the *remote_package* location on the + target Junos device using the options specified. +#. 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: + +* `junos-eznc `_ >= 2.5.2 +* Python >= 3.5 + + + +.. _module-specific-options-label: + +Module-specific Options +----------------------- +The following options may be specified for this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
parametertyperequireddefaultchoicescomments
all_re
boolnoTrue
  • 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
strnonone +
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
strnomd5 +
The algorithm to use when calculating the checksum of the local and remote software packages.
+
checksum_timeout
intno300 (5 minutes) +
The number of seconds to wait for the calculation of the checksum to complete on the target Junos device.
+
cleanfs
boolnotrue (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
intno300 (5 minutes) +
The number of seconds to wait for the request system storage cleanup to complete on the target Junos device.
+
force_host
boolnoFalse
  • yes
  • no
 +
Forces the upgrade of the Host Software package on QFX-series devices.
+
install_timeout
intno1800 (30 minutes) +
The number of seconds to wait for the software installation to complete on the target Junos device.
+
issu
boolnoFalse
  • 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
dictnonone +
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
pathnonone +
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
boolnoFalse
  • 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
boolnoFalse
  • 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
listnoFalse +
install software on the members in a mixed Virtual Chassis. Currently we are not doing target package check this option is provided.
+
reboot
boolnoTrue
  • yes
  • no
 +
Indicates if the target Junos device should be rebooted after performing the software install.
+
reboot_pause
intno10 +
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
pathno/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
boolnoFalse
  • yes
  • no
 +
Whether or not to have the target Junos device should validate the current configuration against the new software package.
+
version
strnoAttempt 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
boolnoFalse
  • yes
  • no
 +
Whether or not this is a vmhost software installation.
+
+
+ +Common Connection-related Options +--------------------------------- +In addition to the :ref:`module-specific-options-label`, the following connection-related options are also supported by this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
parametertyperequireddefaultchoicescomments
attempts
intno10 +
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
intno9600 +
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
strnonone +
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
strno +
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
strno +
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
stryes{{ 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
strnonone
  • 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
strnoThe 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 strno830 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_config
pathno +
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
pathnoThe 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
intno30 +
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
stryesThe 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 :ref:`module-specific-options-label`, the following logging-related options are also supported by this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
parametertyperequireddefaultchoicescomments
level
strnoWARNING
  • 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
pathnonone +
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
pathnonone +
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
+
+
+ +.. _software-examples-label: + +Examples +-------- + +:: + + + --- + - name: 'Explicit host argument' + hosts: junos + connection: local + gather_facts: no + collections: + - juniper.device + + tasks: + - name: Execute a basic Junos software upgrade. + software: + local_package: "./images/" + register: response + + - name: Print the complete response. + debug: + var: response + + - name: Upgrade Junos OS from package copied at device + software: + host: "10.x.x.x" + user: "user" + passwd: "user123" + remote_package: "/var/tmp/junos-install-mx-x86-64-20.1R1.5.tgz" + no_copy: false + cleanfs: false + validate: true + register: response + + + +Return Values +------------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
namedescriptionreturnedtypesample
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.
+ 		successbool
check_mode +
Indicates whether or not the module ran in check mode.
+ 		successbool
failed +
Indicates if the task failed.
+ 		alwaysbool
msg +
A human-readable message indicating the result of the software installation.
+ 		alwaysstr
+
+
+ + +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. + + diff --git a/ansible_collections/juniper/device/docs/srx_cluster.rst b/ansible_collections/juniper/device/docs/srx_cluster.rst new file mode 100644 index 00000000..207b1799 --- /dev/null +++ b/ansible_collections/juniper/device/docs/srx_cluster.rst @@ -0,0 +1,454 @@ +.. _srx_cluster: + +srx_cluster ++++++++++++ +Add or remove SRX chassis cluster configuration + + + +.. contents:: + :local: + :depth: 2 + + +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: + +* `junos-eznc `_ >= 2.5.2 +* Python >= 3.5 + + + +.. _module-specific-options-label: + +Module-specific Options +----------------------- +The following options may be specified for this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
parametertyperequireddefaultchoicescomments
cluster_id
intnonone +
The cluster ID to configure.
+
Required when enable is true.
+
aliases: cluster
+
enable
boolyesnone
  • 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
intnonone +
The node ID to configure. (0 or 1)
+
Required when enable is true.
+
aliases: node
+
+
+ +Common Connection-related Options +--------------------------------- +In addition to the :ref:`module-specific-options-label`, the following connection-related options are also supported by this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
parametertyperequireddefaultchoicescomments
attempts
intno10 +
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
intno9600 +
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
strnonone +
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
strno +
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
strno +
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
stryes{{ 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
strnonone
  • 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
strnoThe 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 strno830 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_config
pathno +
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
pathnoThe 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
intno30 +
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
stryesThe 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 :ref:`module-specific-options-label`, the following logging-related options are also supported by this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
parametertyperequireddefaultchoicescomments
level
strnoWARNING
  • 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
pathnonone +
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
pathnonone +
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
+
+
+ +.. _srx_cluster-examples-label: + +Examples +-------- + +:: + + + --- + - name: Manipulate the SRX cluster configuration of Junos SRX devices + hosts: junos-all + connection: local + gather_facts: no + collections: + - juniper.device + tasks: + - name: Enable an SRX cluster + 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 + srx_cluster: + enable: false + register: response + - name: Print the response. + debug: + var: response.config_lines + + + +Return Values +------------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
namedescriptionreturnedtypesample
changed +
Indicates if the device's configuration has changed, or would have changed when in check mode.
+ 		successbool
failed +
Indicates if the task failed.
+ 		alwaysbool
msg +
A human-readable message indicating the result.
+ 		alwaysstr
reboot +
Indicates if a reboot of the device has been initiated.
+ 		successbool
+
+
+ + +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. + + diff --git a/ansible_collections/juniper/device/docs/system.rst b/ansible_collections/juniper/device/docs/system.rst new file mode 100644 index 00000000..0a1a9d7d --- /dev/null +++ b/ansible_collections/juniper/device/docs/system.rst @@ -0,0 +1,565 @@ +.. _system: + +system +++++++ +Initiate operational actions on the Junos system + + + +.. contents:: + :local: + :depth: 2 + + +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: + +* `junos-eznc `_ >= 2.5.2 +* Python >= 3.5 + + + +.. _module-specific-options-label: + +Module-specific Options +----------------------- +The following options may be specified for this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
parametertyperequireddefaultchoicescomments
action
stryesnone
  • 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
boolnoTrue
  • 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
strnonone +
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
intno0 +
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
boolnoFalse
  • 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
boolnoFalse
  • 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.
+
vmhost
boolnoFalse
  • yes
  • no
 +
Whether or not this is a vmhost reboot.
+
+
+ +Common Connection-related Options +--------------------------------- +In addition to the :ref:`module-specific-options-label`, the following connection-related options are also supported by this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
parametertyperequireddefaultchoicescomments
attempts
intno10 +
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
intno9600 +
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
strnonone +
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
strno +
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
strno +
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
stryes{{ 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
strnonone
  • 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
strnoThe 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 strno830 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_config
pathno +
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
pathnoThe 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
intno30 +
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
stryesThe 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 :ref:`module-specific-options-label`, the following logging-related options are also supported by this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
parametertyperequireddefaultchoicescomments
level
strnoWARNING
  • 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
pathnonone +
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
pathnonone +
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
+
+
+ +.. _system-examples-label: + +Examples +-------- + +:: + + + --- + - name: 'Explicit host argument' + hosts: junos + connection: local + gather_facts: no + collections: + - juniper.device + + tasks: + - name: Reboot all REs of the device + system: + action: "reboot" + + - name: Power off the other RE of the device. + system: + action: "shutdown" + othe_re: True + + - name: Reboot this RE at 8pm today. + system: + action: "reboot" + all_re: False + at: "20:00" + + - name: Halt the system on 25 January 2018 at 4pm. + system: + action: "halt" + at: "1801251600" + + - name: Reboot the system in 30 minutes. + system: + action: "reboot" + in_min: 30 + + - name: Reboot the system in 30 minutes. + system: + action: "reboot" + at: "+30m" + + - name: Zeroize the local RE only. + system: + action: "zeroize" + all_re: False + + - name: Zeroize all REs and overwrite medea. + system: + action: "zeroize" + media: True + + + +Return Values +------------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
namedescriptionreturnedtypesample
action +
The value of the action option.
+ 		alwaysstr
all_re +
The value of the all_re option.
+ 		alwaysstr
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.
+ 		alwaysbool
failed +
Indicates if the task failed.
+ 		alwaysbool
media +
The value of the media option.
+ 		alwaysstr
msg +
A human-readable message indicating the result.
+ 		alwaysstr
other_re +
The value of the other_re option.
+ 		alwaysstr
+
+
+ + +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. + + diff --git a/ansible_collections/juniper/device/docs/table.rst b/ansible_collections/juniper/device/docs/table.rst new file mode 100644 index 00000000..bfc323ed --- /dev/null +++ b/ansible_collections/juniper/device/docs/table.rst @@ -0,0 +1,576 @@ +.. _table: + +table ++++++ +Retrieve data from a Junos device using a PyEZ table/view + + + +.. contents:: + :local: + :depth: 2 + + +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: + +* `junos-eznc `_ >= 2.5.2 +* Python >= 3.5 + + + +.. _module-specific-options-label: + +Module-specific Options +----------------------- +The following options may be specified for this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
parametertyperequireddefaultchoicescomments
file
pathyesnone +
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
dictnonone +
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
pathnoop 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
strnolist_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
strnoThe 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.
+
+
+ +Common Connection-related Options +--------------------------------- +In addition to the :ref:`module-specific-options-label`, the following connection-related options are also supported by this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
parametertyperequireddefaultchoicescomments
attempts
intno10 +
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
intno9600 +
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
strnonone +
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
strno +
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
strno +
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
stryes{{ 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
strnonone
  • 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
strnoThe 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 strno830 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_config
pathno +
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
pathnoThe 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
intno30 +
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
stryesThe 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 :ref:`module-specific-options-label`, the following logging-related options are also supported by this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
parametertyperequireddefaultchoicescomments
level
strnoWARNING
  • 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
pathnonone +
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
pathnonone +
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
+
+
+ +.. _table-examples-label: + +Examples +-------- + +:: + + + --- + - name: Retrieve data from a Junos device using a PyEZ table/view. + hosts: junos-all + connection: local + gather_facts: no + collections: + - juniper.device + + tasks: + - name: Retrieve LLDP Neighbor Information Using PyEZ-included Table + table: + file: "lldp.yml" + register: response + - name: Print response + debug: + var: response + + - name: Retrieve routes within 192.68.1/8 + 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 + table: + file: "fpc.yaml" + path: "." + register: response + - name: Print response + debug: + var: response + + + +Return Values +------------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
namedescriptionreturnedtypesample
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.
+ 		successbool
failed +
Indicates if the task failed.
+ 		alwaysbool
msg +
A human-readable message indicating a summary of the result.
+ 		alwaysstr
resource +
The items retrieved by the table/view.
+ 		successlist 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. + +