diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 44d93b1d1..208c6240d 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -1,10 +1,5 @@ --- repos: - - repo: https://github.com/ansible-network/collection_prep - rev: 1.1.1 - hooks: - - id: update-docs - - repo: https://github.com/pre-commit/pre-commit-hooks rev: v4.6.0 hooks: diff --git a/docs/ansible.netcommon.cli_backup_module.rst b/docs/ansible.netcommon.cli_backup_module.rst index 6785696c9..91ba57f8c 100644 --- a/docs/ansible.netcommon.cli_backup_module.rst +++ b/docs/ansible.netcommon.cli_backup_module.rst @@ -1,14 +1,19 @@ -.. _ansible.netcommon.cli_backup_module: +.. Created with antsibull-docs 2.9.0 -**************************** -ansible.netcommon.cli_backup -**************************** +ansible.netcommon.cli_backup module -- Back up device configuration from network devices over network\_cli +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -**Back up device configuration from network devices over network_cli** +This module is part of the `ansible.netcommon collection `_ (version 6.1.0). +It is not included in ``ansible-core``. +To check whether it is installed, run ``ansible-galaxy collection list``. -Version added: 4.2.0 +To install it, use: :code:`ansible-galaxy collection install ansible.netcommon`. + +To use it in a playbook, specify: ``ansible.netcommon.cli_backup``. + +New in ansible.netcommon 4.2.0 .. contents:: :local: @@ -17,7 +22,13 @@ Version added: 4.2.0 Synopsis -------- -- This module provides platform agnostic way of backing up text based configuration from network devices over network_cli connection plugin. + +- This module provides platform agnostic way of backing up text based configuration from network devices over network\_cli connection plugin. + +This module has a corresponding action plugin. + + + @@ -27,71 +38,69 @@ Parameters .. raw:: html - - - - - - - - - - - - - - - - - - - - - -
ParameterChoices/DefaultsComments
-
- defaults - -
- boolean -
- 		-
    Choices: -
  • no ←
    • -
  • yes
    • -
- 		-
The defaults argument will influence how the running-config is collected from the device. When the value is set to true, the command used to collect the running-config is append with the all keyword. When the value is set to false, the command is issued without the all keyword.
-
-
- dir_path - -
- path -
- 		- -
This option provides the path ending with directory name in which the backup configuration file will be stored. If the directory does not exist it will be first created and the filename is either the value of filename or default filename as described in filename options description. If the path value is not given in that case a backup directory will be created in the current working directory and backup configuration will be copied in filename within backup directory.
-
-
- filename - -
- string -
- 		- -
The filename to be used to store the backup configuration. If the filename is not given it will be generated based on the hostname, current time and date in format defined by <hostname>_config.<current-date>@<current-time>
-
-
+ + + + + + + + + + + + + + + + + + + + + +

Parameter

Comments

+
+

defaults

+ +

+ boolean +

+ 		+

The defaults argument will influence how the running-config is collected from the device. When the value is set to true, the command used to collect the running-config is append with the all keyword. When the value is set to false, the command is issued without the all keyword.

+

Choices:

+
    +

  • false ← (default)

    • +

  • true

    • +
+ +
+
+

dir_path

+ +

+ path +

+ 		+

This option provides the path ending with directory name in which the backup configuration file will be stored. If the directory does not exist it will be first created and the filename is either the value of filename or default filename as described in filename options description. If the path value is not given in that case a backup directory will be created in the current working directory and backup configuration will be copied in filename within backup directory.

+
+
+

filename

+ +

+ string +

+ 		+

The filename to be used to store the backup configuration. If the filename is not given it will be generated based on the hostname, current time and date in format defined by <hostname>_config.<current-date>@<current-time>

+
+ + Notes ----- -.. note:: - - This module is supported on ``ansible_network_os`` network platforms. See the :ref:`Network Platform Options ` for details. - +- This module is supported on \ :literal:`ansible\_network\_os`\ network platforms. See the :ref:\`Network Platform Options \\` for details. Examples @@ -99,6 +108,7 @@ Examples .. code-block:: yaml + - name: configurable backup path ansible.netcommon.cli_backup: filename: backup.cfg @@ -106,44 +116,52 @@ Examples + + Return Values ------------- -Common return values are documented `here `_, the following are the fields unique to this module: +The following are the fields unique to this module: .. raw:: html - - - - - - - - - - - -
KeyReturnedDescription
-
- backup_path - -
- string -
- 		always -
The full path to the backup file
-
-
Sample:
-
/playbooks/ansible/backup/hostname_config.2016-07-16@22:28:34
-
-

- - -Status ------- + + + + + + + + + + + + + +

Key

Description

+
+

backup_path

+ +

+ string +

+ 		+

The full path to the backup file

+

Returned: always

+

Sample: "/playbooks/ansible/backup/hostname_config.2016-07-16@22:28:34"

+
+ + Authors ~~~~~~~ - Kate Case (@Qalthos) + + + +Collection links +~~~~~~~~~~~~~~~~ + +* `Issue Tracker `__ +* `Repository (Sources) `__ diff --git a/docs/ansible.netcommon.cli_command_module.rst b/docs/ansible.netcommon.cli_command_module.rst index 11bd0eb82..84794b391 100644 --- a/docs/ansible.netcommon.cli_command_module.rst +++ b/docs/ansible.netcommon.cli_command_module.rst @@ -1,14 +1,19 @@ -.. _ansible.netcommon.cli_command_module: +.. Created with antsibull-docs 2.9.0 -***************************** -ansible.netcommon.cli_command -***************************** +ansible.netcommon.cli_command module -- Run a cli command on cli-based network devices +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -**Run a cli command on cli-based network devices** +This module is part of the `ansible.netcommon collection `_ (version 6.1.0). +It is not included in ``ansible-core``. +To check whether it is installed, run ``ansible-galaxy collection list``. -Version added: 1.0.0 +To install it, use: :code:`ansible-galaxy collection install ansible.netcommon`. + +To use it in a playbook, specify: ``ansible.netcommon.cli_command``. + +New in ansible.netcommon 1.0.0 .. contents:: :local: @@ -17,8 +22,14 @@ Version added: 1.0.0 Synopsis -------- + - Sends a command to a network device and returns the result read from the device. +This module has a corresponding action plugin. + + + + @@ -27,127 +38,123 @@ Parameters .. raw:: html - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ParameterChoices/DefaultsComments
-
- answer - -
- list - / elements=string -
- 		- -
The answer to reply with if prompt is matched. The value can be a single answer or a list of answer for multiple prompts. In case the command execution results in multiple prompts the sequence of the prompt and excepted answer should be in same order.
-
-
- check_all - -
- boolean -
- 		-
    Choices: -
  • no ←
    • -
  • yes
    • -
- 		-
By default if any one of the prompts mentioned in prompt option is matched it won't check for other prompts. This boolean flag, that when set to True will check for all the prompts mentioned in prompt option in the given order. If the option is set to True all the prompts should be received from remote host if not it will result in timeout.
-
-
- command - -
- string - / required -
- 		- -
The command to send to the remote network device. The resulting output from the command is returned, unless sendonly is set.
-
-
- newline - -
- boolean -
- 		-
    Choices: -
  • no
    • -
  • yes ←
    • -
- 		-
The boolean value, that when set to false will send answer to the device without a trailing newline.
-
-
- prompt - -
- list - / elements=string -
- 		- -
A single regex pattern or a sequence of patterns to evaluate the expected prompt from command.
-
-
- sendonly - -
- boolean -
- 		-
    Choices: -
  • no ←
    • -
  • yes
    • -
- 		-
The boolean value, that when set to true will send command to the device but not wait for a result.
-
-
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Parameter

Comments

+
+

answer

+ +

+ list + / elements=string +

+ 		+

The answer to reply with if prompt is matched. The value can be a single answer or a list of answer for multiple prompts. In case the command execution results in multiple prompts the sequence of the prompt and excepted answer should be in same order.

+
+
+

check_all

+ +

+ boolean +

+ 		+

By default if any one of the prompts mentioned in prompt option is matched it won't check for other prompts. This boolean flag, that when set to True will check for all the prompts mentioned in prompt option in the given order. If the option is set to True all the prompts should be received from remote host if not it will result in timeout.

+

Choices:

+
    +

  • false ← (default)

    • +

  • true

    • +
+ +
+
+

command

+ +

+ string + / required +

+ 		+

The command to send to the remote network device. The resulting output from the command is returned, unless sendonly is set.

+
+
+

newline

+ +

+ boolean +

+ 		+

The boolean value, that when set to false will send answer to the device without a trailing newline.

+

Choices:

+
    +

  • false

    • +

  • true ← (default)

    • +
+ +
+
+

prompt

+ +

+ list + / elements=string +

+ 		+

A single regex pattern or a sequence of patterns to evaluate the expected prompt from command.

+
+
+

sendonly

+ +

+ boolean +

+ 		+

The boolean value, that when set to true will send command to the device but not wait for a result.

+

Choices:

+
    +

  • false ← (default)

    • +

  • true

    • +
+ +
+ + Notes ----- -.. note:: - - This module is supported on ``ansible_network_os`` network platforms. See the :ref:`Network Platform Options ` for details. - +- This module is supported on \ :literal:`ansible\_network\_os`\ network platforms. See the :ref:\`Network Platform Options \\` for details. Examples @@ -155,6 +162,7 @@ Examples .. code-block:: yaml + - name: run show version on remote devices ansible.netcommon.cli_command: command: show version @@ -202,67 +210,67 @@ Examples + + Return Values ------------- -Common return values are documented `here `_, the following are the fields unique to this module: +The following are the fields unique to this module: .. raw:: html - - - - - - - - - - - - - - - - -
KeyReturnedDescription
-
- json - -
- dictionary -
- 		when the device response is valid JSON -
A dictionary representing a JSON-formatted response
-
-
Sample:
-
{ - "architecture": "i386", - "bootupTimestamp": 1532649700.56, - "modelName": "vEOS", - "version": "4.15.9M" - [...] - }
-
-
- stdout - -
- string -
- 		when sendonly is false -
The response from the command
-
-
Sample:
-
Version: VyOS 1.1.7[...]
-
-

- - -Status ------- + + + + + + + + + + + + + + + + + +

Key

Description

+
+

json

+ +

+ dictionary +

+ 		+

A dictionary representing a JSON-formatted response

+

Returned: when the device response is valid JSON

+

Sample: "{\n \"architecture\": \"i386\",\n \"bootupTimestamp\": 1532649700.56,\n \"modelName\": \"vEOS\",\n \"version\": \"4.15.9M\"\n [...]\n}\n"

+
+
+

stdout

+ +

+ string +

+ 		+

The response from the command

+

Returned: when sendonly is false

+

Sample: "Version: VyOS 1.1.7[...]"

+
+ + Authors ~~~~~~~ - Nathaniel Case (@Qalthos) + + + +Collection links +~~~~~~~~~~~~~~~~ + +* `Issue Tracker `__ +* `Repository (Sources) `__ diff --git a/docs/ansible.netcommon.cli_config_module.rst b/docs/ansible.netcommon.cli_config_module.rst index 1af9b2010..f5c3c38fc 100644 --- a/docs/ansible.netcommon.cli_config_module.rst +++ b/docs/ansible.netcommon.cli_config_module.rst @@ -1,14 +1,19 @@ -.. _ansible.netcommon.cli_config_module: +.. Created with antsibull-docs 2.9.0 -**************************** -ansible.netcommon.cli_config -**************************** +ansible.netcommon.cli_config module -- Push text based configuration to network devices over network\_cli ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -**Push text based configuration to network devices over network_cli** +This module is part of the `ansible.netcommon collection `_ (version 6.1.0). +It is not included in ``ansible-core``. +To check whether it is installed, run ``ansible-galaxy collection list``. -Version added: 1.0.0 +To install it, use: :code:`ansible-galaxy collection install ansible.netcommon`. + +To use it in a playbook, specify: ``ansible.netcommon.cli_config``. + +New in ansible.netcommon 1.0.0 .. contents:: :local: @@ -17,7 +22,13 @@ Version added: 1.0.0 Synopsis -------- -- This module provides platform agnostic way of pushing text based configuration to network devices over network_cli connection plugin. + +- This module provides platform agnostic way of pushing text based configuration to network devices over network\_cli connection plugin. + +This module has a corresponding action plugin. + + + @@ -27,261 +38,245 @@ Parameters .. raw:: html - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ParameterChoices/DefaultsComments
-
- backup - -
- boolean -
- 		-
    Choices: -
  • no ←
    • -
  • yes
    • -
- 		-
This argument will cause the module to create a full backup of the current running config from the remote device before any changes are made. If the backup_options value is not given, the backup file is written to the backup folder in the playbook root directory or role root directory, if playbook is part of an ansible role. If the directory does not exist, it is created.
-
-
- backup_options - -
- dictionary -
- 		- -
This is a dict object containing configurable options related to backup file path. The value of this option is read only when backup is set to yes, if backup is set to no this option will be silently ignored.
-
-
- dir_path - -
- path -
- 		- -
This option provides the path ending with directory name in which the backup configuration file will be stored. If the directory does not exist it will be first created and the filename is either the value of filename or default filename as described in filename options description. If the path value is not given in that case a backup directory will be created in the current working directory and backup configuration will be copied in filename within backup directory.
-
-
- filename - -
- string -
- 		- -
The filename to be used to store the backup configuration. If the filename is not given it will be generated based on the hostname, current time and date in format defined by <hostname>_config.<current-date>@<current-time>
-
-
- commit - -
- boolean -
- 		-
    Choices: -
  • no
    • -
  • yes
    • -
- 		-
The commit argument instructs the module to push the configuration to the device. This is mapped to module check mode.
-
-
- commit_comment - -
- string -
- 		- -
The commit_comment argument specifies a text string to be used when committing the configuration. If the commit argument is set to False, this argument is silently ignored. This argument is only valid for the platforms that support commit operation with comment.
-
-
- config - -
- string -
- 		- -
The config to be pushed to the network device. This argument is mutually exclusive with rollback and either one of the option should be given as input. To ensure idempotency and correct diff the configuration lines should be similar to how they appear if present in the running configuration on device including the indentation.
-
-
- defaults - -
- boolean -
- 		-
    Choices: -
  • no ←
    • -
  • yes
    • -
- 		-
The defaults argument will influence how the running-config is collected from the device. When the value is set to true, the command used to collect the running-config is append with the all keyword. When the value is set to false, the command is issued without the all keyword.
-
-
- diff_ignore_lines - -
- list - / elements=string -
- 		- -
Use this argument to specify one or more lines that should be ignored during the diff. This is used for lines in the configuration that are automatically updated by the system. This argument takes a list of regular expressions or exact line matches. Note that this parameter will be ignored if the platform has onbox diff support.
-
-
- diff_match - -
- string -
- 		-
    Choices: -
  • line
    • -
  • strict
    • -
  • exact
    • -
  • none
    • -
- 		-
Instructs the module on the way to perform the matching of the set of commands against the current device config. If diff_match is set to line, commands are matched line by line. If diff_match is set to strict, command lines are matched with respect to position. If diff_match is set to exact, command lines must be an equal match. Finally, if diff_match is set to none, the module will not attempt to compare the source configuration with the running configuration on the remote device. Note that this parameter will be ignored if the platform has onbox diff support.
-
-
- diff_replace - -
- string -
- 		-
    Choices: -
  • line
    • -
  • block
    • -
  • config
    • -
- 		-
Instructs the module on the way to perform the configuration on the device. If the diff_replace argument is set to line then the modified lines are pushed to the device in configuration mode. If the argument is set to block then the entire command block is pushed to the device in configuration mode if any line is not correct. Note that this parameter will be ignored if the platform has onbox diff support.
-
-
- multiline_delimiter - -
- string -
- 		- -
This argument is used when pushing a multiline configuration element to the device. It specifies the character to use as the delimiting character. This only applies to the configuration action.
-
-
- replace - -
- string -
- 		- -
If the replace argument is set to yes, it will replace the entire running-config of the device with the config argument value. For devices that support replacing running configuration from file on device like NXOS/JUNOS, the replace argument takes path to the file on the device that will be used for replacing the entire running-config. The value of config option should be None for such devices. Nexus 9K devices only support replace. Use net_put or nxos_file_copy in case of NXOS module to copy the flat file to remote device and then use set the fullpath to this argument.
-
-
- rollback - -
- integer -
- 		- -
The rollback argument instructs the module to rollback the current configuration to the identifier specified in the argument. If the specified rollback identifier does not exist on the remote device, the module will fail. To rollback to the most recent commit, set the rollback argument to 0. This option is mutually exclusive with config.
-
-
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Parameter

Comments

+
+

backup

+ +

+ boolean +

+ 		+

This argument will cause the module to create a full backup of the current running config from the remote device before any changes are made. If the backup_options value is not given, the backup file is written to the backup folder in the playbook root directory or role root directory, if playbook is part of an ansible role. If the directory does not exist, it is created.

+

Choices:

+
    +

  • false ← (default)

    • +

  • true

    • +
+ +
+
+

backup_options

+ +

+ dictionary +

+ 		+

This is a dict object containing configurable options related to backup file path. The value of this option is read only when backup is set to yes, if backup is set to no this option will be silently ignored.

+
+
+

dir_path

+ +

+ path +

+ 		+

This option provides the path ending with directory name in which the backup configuration file will be stored. If the directory does not exist it will be first created and the filename is either the value of filename or default filename as described in filename options description. If the path value is not given in that case a backup directory will be created in the current working directory and backup configuration will be copied in filename within backup directory.

+
+
+

filename

+ +

+ string +

+ 		+

The filename to be used to store the backup configuration. If the filename is not given it will be generated based on the hostname, current time and date in format defined by <hostname>_config.<current-date>@<current-time>

+
+
+

commit

+ +

+ boolean +

+ 		+

The commit argument instructs the module to push the configuration to the device. This is mapped to module check mode.

+

Choices:

+
    +

  • false

    • +

  • true

    • +
+ +
+
+

commit_comment

+ +

+ string +

+ 		+

The commit_comment argument specifies a text string to be used when committing the configuration. If the commit argument is set to False, this argument is silently ignored. This argument is only valid for the platforms that support commit operation with comment.

+
+
+

config

+ +

+ string +

+ 		+

The config to be pushed to the network device. This argument is mutually exclusive with rollback and either one of the option should be given as input. To ensure idempotency and correct diff the configuration lines should be similar to how they appear if present in the running configuration on device including the indentation.

+
+
+

defaults

+ +

+ boolean +

+ 		+

The defaults argument will influence how the running-config is collected from the device. When the value is set to true, the command used to collect the running-config is append with the all keyword. When the value is set to false, the command is issued without the all keyword.

+

Choices:

+
    +

  • false ← (default)

    • +

  • true

    • +
+ +
+
+

diff_ignore_lines

+ +

+ list + / elements=string +

+ 		+

Use this argument to specify one or more lines that should be ignored during the diff. This is used for lines in the configuration that are automatically updated by the system. This argument takes a list of regular expressions or exact line matches. Note that this parameter will be ignored if the platform has onbox diff support.

+
+
+

diff_match

+ +

+ string +

+ 		+

Instructs the module on the way to perform the matching of the set of commands against the current device config. If diff_match is set to line, commands are matched line by line. If diff_match is set to strict, command lines are matched with respect to position. If diff_match is set to exact, command lines must be an equal match. Finally, if diff_match is set to none, the module will not attempt to compare the source configuration with the running configuration on the remote device. Note that this parameter will be ignored if the platform has onbox diff support.

+

Choices:

+
    +

  • "line"

    • +

  • "strict"

    • +

  • "exact"

    • +

  • "none"

    • +
+ +
+
+

diff_replace

+ +

+ string +

+ 		+

Instructs the module on the way to perform the configuration on the device. If the diff_replace argument is set to line then the modified lines are pushed to the device in configuration mode. If the argument is set to block then the entire command block is pushed to the device in configuration mode if any line is not correct. Note that this parameter will be ignored if the platform has onbox diff support.

+

Choices:

+
    +

  • "line"

    • +

  • "block"

    • +

  • "config"

    • +
+ +
+
+

multiline_delimiter

+ +

+ string +

+ 		+

This argument is used when pushing a multiline configuration element to the device. It specifies the character to use as the delimiting character. This only applies to the configuration action.

+
+
+

replace

+ +

+ string +

+ 		+

If the replace argument is set to yes, it will replace the entire running-config of the device with the config argument value. For devices that support replacing running configuration from file on device like NXOS/JUNOS, the replace argument takes path to the file on the device that will be used for replacing the entire running-config. The value of config option should be None for such devices. Nexus 9K devices only support replace. Use net_put or nxos_file_copy in case of NXOS module to copy the flat file to remote device and then use set the fullpath to this argument.

+
+
+

rollback

+ +

+ integer +

+ 		+

The rollback argument instructs the module to rollback the current configuration to the identifier specified in the argument. If the specified rollback identifier does not exist on the remote device, the module will fail. To rollback to the most recent commit, set the rollback argument to 0. This option is mutually exclusive with config.

+
+ + Notes ----- -.. note:: - - The commands will be returned only for platforms that do not support onbox diff. The ``--diff`` option with the playbook will return the difference in configuration for devices that has support for onbox diff - - To ensure idempotency and correct diff the configuration lines in the relevant module options should be similar to how they appear if present in the running configuration on device including the indentation. - - This module is supported on ``ansible_network_os`` network platforms. See the :ref:`Network Platform Options ` for details. - +- The commands will be returned only for platforms that do not support onbox diff. The \ :literal:`--diff`\ option with the playbook will return the difference in configuration for devices that has support for onbox diff +- To ensure idempotency and correct diff the configuration lines in the relevant module options should be similar to how they appear if present in the running configuration on device including the indentation. +- This module is supported on \ :literal:`ansible\_network\_os`\ network platforms. See the :ref:\`Network Platform Options \\` for details. Examples @@ -289,6 +284,7 @@ Examples .. code-block:: yaml + - name: configure device with config ansible.netcommon.cli_config: config: "{{ lookup('template', 'basic/config.j2') }}" @@ -332,87 +328,83 @@ Examples + + Return Values ------------- -Common return values are documented `here `_, the following are the fields unique to this module: +The following are the fields unique to this module: .. raw:: html - - - - - - - - - - - - - - - - - - - - - -
KeyReturnedDescription
-
- backup_path - -
- string -
- 		when backup is yes -
The full path to the backup file
-
-
Sample:
-
/playbooks/ansible/backup/hostname_config.2016-07-16@22:28:34
-
-
- commands - -
- list -
- 		When supports_generated_diff=True and supports_onbox_diff=False in the platform's cliconf plugin -
The set of commands that will be pushed to the remote device
-
-
Sample:
-
['interface Loopback999', 'no shutdown']
-
-
- diff - -
- string -
- 		When supports_onbox_diff=True in the platform's cliconf plugin -
The diff generated on the device when the commands were applied
-
-
Sample:
-
--- system:/running-config - +++ session:/ansible_1599745461-session-config - @@ -4,7 +4,7 @@ - ! - transceiver qsfp default-mode 4x10G - ! - -hostname veos - +hostname veos3 - ! - spanning-tree mode mstp
-
-

- - -Status ------- + + + + + + + + + + + + + + + + + + + + + +

Key

Description

+
+

backup_path

+ +

+ string +

+ 		+

The full path to the backup file

+

Returned: when backup is yes

+

Sample: "/playbooks/ansible/backup/hostname_config.2016-07-16@22:28:34"

+
+
+

commands

+ +

+ list + / elements=string +

+ 		+

The set of commands that will be pushed to the remote device

+

Returned: When supports_generated_diff=True and supports_onbox_diff=False in the platform's cliconf plugin

+

Sample: ["interface Loopback999", "no shutdown"]

+
+
+

diff

+ +

+ string +

+ 		+

The diff generated on the device when the commands were applied

+

Returned: When supports_onbox_diff=True in the platform's cliconf plugin

+

Sample: "--- system:/running-config\n+++ session:/ansible_1599745461-session-config\n@@ -4,7 +4,7 @@\n !\n transceiver qsfp default-mode 4x10G\n !\n-hostname veos\n+hostname veos3\n !\n spanning-tree mode mstp"

+
+ + Authors ~~~~~~~ - Trishna Guha (@trishnaguha) + + + +Collection links +~~~~~~~~~~~~~~~~ + +* `Issue Tracker `__ +* `Repository (Sources) `__ diff --git a/docs/ansible.netcommon.cli_restore_module.rst b/docs/ansible.netcommon.cli_restore_module.rst index d13d87efb..2fe30ce2f 100644 --- a/docs/ansible.netcommon.cli_restore_module.rst +++ b/docs/ansible.netcommon.cli_restore_module.rst @@ -1,14 +1,19 @@ -.. _ansible.netcommon.cli_restore_module: +.. Created with antsibull-docs 2.9.0 -***************************** -ansible.netcommon.cli_restore -***************************** +ansible.netcommon.cli_restore module -- Restore device configuration to network devices over network\_cli ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -**Restore device configuration to network devices over network_cli** +This module is part of the `ansible.netcommon collection `_ (version 6.1.0). +It is not included in ``ansible-core``. +To check whether it is installed, run ``ansible-galaxy collection list``. -Version added: 6.1.0 +To install it, use: :code:`ansible-galaxy collection install ansible.netcommon`. + +To use it in a playbook, specify: ``ansible.netcommon.cli_restore``. + +New in ansible.netcommon 6.1.0 .. contents:: :local: @@ -17,8 +22,13 @@ Version added: 6.1.0 Synopsis -------- -- This module provides platform agnostic way of restore text based configuration to network devices over network_cli connection plugin. -- The module uses the platforms `config replace` commands to restore backup configuration that is already copied over to the appliance. + +- This module provides platform agnostic way of restore text based configuration to network devices over network\_cli connection plugin. +- The module uses the platforms \`config replace\` commands to restore backup configuration that is already copied over to the appliance. + + + + @@ -28,53 +38,51 @@ Parameters .. raw:: html - - - - - - - - - - - - - - - - -
ParameterChoices/DefaultsComments
-
- filename - -
- string -
- 		- -
Filename of the backup file, present in the appliance where the restore operation is to be performed. Check appliance for the configuration backup file name.
-
-
- path - -
- string -
- 		- -
The location in the target appliance where the file containing the backup exists. The path and the filename together create the input to the config replace command,
-
For an IOSXE appliance the path pattern is flash://<filename>
-
-
+ + + + + + + + + + + + + + + + + +

Parameter

Comments

+
+

filename

+ +

+ string +

+ 		+

Filename of the backup file, present in the appliance where the restore operation is to be performed. Check appliance for the configuration backup file name.

+
+
+

path

+ +

+ string +

+ 		+

The location in the target appliance where the file containing the backup exists. The path and the filename together create the input to the config replace command,

+

For an IOSXE appliance the path pattern is flash://<filename>

+
+ + Notes ----- -.. note:: - - This module is supported on ``ansible_network_os`` network platforms. See the :ref:`Network Platform Options ` for details. - +- This module is supported on \ :literal:`ansible\_network\_os`\ network platforms. See the :ref:\`Network Platform Options \\` for details. Examples @@ -82,6 +90,7 @@ Examples .. code-block:: yaml + - name: Restore IOS-XE configuration ansible.netcommon.cli_restore: filename: backupDday.cfg @@ -118,11 +127,18 @@ Examples -Status ------- + Authors ~~~~~~~ - Sagar Paul (@KB-perByte) + + + +Collection links +~~~~~~~~~~~~~~~~ + +* `Issue Tracker `__ +* `Repository (Sources) `__ diff --git a/docs/ansible.netcommon.comp_type5_filter.rst b/docs/ansible.netcommon.comp_type5_filter.rst index 130b68a71..d5e6d697c 100644 --- a/docs/ansible.netcommon.comp_type5_filter.rst +++ b/docs/ansible.netcommon.comp_type5_filter.rst @@ -1,14 +1,19 @@ -.. _ansible.netcommon.comp_type5_filter: +.. Created with antsibull-docs 2.9.0 -**************************** -ansible.netcommon.comp_type5 -**************************** +ansible.netcommon.comp_type5 filter -- The comp\_type5 filter plugin. ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -**The comp_type5 filter plugin.** +This filter plugin is part of the `ansible.netcommon collection `_ (version 6.1.0). +It is not included in ``ansible-core``. +To check whether it is installed, run ``ansible-galaxy collection list``. -Version added: 1.0.0 +To install it, use: :code:`ansible-galaxy collection install ansible.netcommon`. + +To use it in a playbook, specify: ``ansible.netcommon.comp_type5``. + +New in ansible.netcommon 1.0.0 .. contents:: :local: @@ -17,91 +22,93 @@ Version added: 1.0.0 Synopsis -------- -- The filter confirms configuration idempotency on use of type5_pw. + +- The filter confirms configuration idempotency on use of type5\_pw. + + + + + +Keyword parameters +------------------ -Parameters ----------- +This describes keyword parameters of the filter. These are the values ``key1=value1``, ``key2=value2`` and so on in the following +example: ``input | ansible.netcommon.comp_type5(key1=value1, key2=value2, ...)`` .. raw:: html - - - - - - - - - - - - - - - - - - - - - - - - - -
ParameterChoices/DefaultsConfigurationComments
-
- encrypted_password - -
- string - / required -
- 		- - -
The encrypted text.
-
-
- return_original - -
- boolean -
- 		-
    Choices: -
  • no
    • -
  • yes
    • -
- 		- -
Return the original text.
-
-
- unencrypted_password - -
- string - / required -
- 		- - -
The unencrypted text.
-
-
+ + + + + + + + + + + + + + + + + + + + + +

Parameter

Comments

+
+

encrypted_password

+ +

+ string + / required +

+ + 		+

The encrypted text.

+
+
+

return_original

+ +

+ boolean +

+ + 		+

Return the original text.

+

Choices:

+
    +

  • false

    • +

  • true

    • +
+ +
+
+

unencrypted_password

+ +

+ string + / required +

+ + 		+

The unencrypted text.

+
+ + Notes ----- -.. note:: - - The filter confirms configuration idempotency on use of type5_pw. - - Can be used to validate password post hashing username cisco secret 5 {{ ansible_ssh_pass | ansible.netcommon.comp_type5(encrypted, True) }} - +- The filter confirms configuration idempotency on use of type5\_pw. +- Can be used to validate password post hashing username cisco secret 5 {{ ansible\_ssh\_pass | ansible.netcommon.comp\_type5(encrypted, True) }} Examples @@ -109,6 +116,7 @@ Examples .. code-block:: yaml + # Using comp_type5 # playbook @@ -138,8 +146,7 @@ Examples -Status ------- + Authors @@ -150,3 +157,9 @@ Authors .. hint:: Configuration entries for each entry type have a low to high priority order. For example, a variable that is lower in the list will override a variable that is higher up. + +Collection links +~~~~~~~~~~~~~~~~ + +* `Issue Tracker `__ +* `Repository (Sources) `__ diff --git a/docs/ansible.netcommon.default_cliconf.rst b/docs/ansible.netcommon.default_cliconf.rst index 78e126aa1..a61f70089 100644 --- a/docs/ansible.netcommon.default_cliconf.rst +++ b/docs/ansible.netcommon.default_cliconf.rst @@ -1,14 +1,19 @@ -.. _ansible.netcommon.default_cliconf: +.. Created with antsibull-docs 2.9.0 -************************* -ansible.netcommon.default -************************* +ansible.netcommon.default cliconf -- General purpose cliconf plugin for new platforms ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -**General purpose cliconf plugin for new platforms** +This cliconf plugin is part of the `ansible.netcommon collection `_ (version 6.1.0). +It is not included in ``ansible-core``. +To check whether it is installed, run ``ansible-galaxy collection list``. -Version added: 5.2.0 +To install it, use: :code:`ansible-galaxy collection install ansible.netcommon`. + +To use it in a playbook, specify: ``ansible.netcommon.default``. + +New in ansible.netcommon 5.2.0 .. contents:: :local: @@ -17,6 +22,7 @@ Version added: 5.2.0 Synopsis -------- + - This plugin attemts to provide low level abstraction apis for sending and receiving CLI commands from arbitrary network devices. @@ -29,8 +35,10 @@ Synopsis -Status ------- + + + + Authors @@ -41,3 +49,9 @@ Authors .. hint:: Configuration entries for each entry type have a low to high priority order. For example, a variable that is lower in the list will override a variable that is higher up. + +Collection links +~~~~~~~~~~~~~~~~ + +* `Issue Tracker `__ +* `Repository (Sources) `__ diff --git a/docs/ansible.netcommon.default_netconf.rst b/docs/ansible.netcommon.default_netconf.rst index d8a836a36..3e22e84b2 100644 --- a/docs/ansible.netcommon.default_netconf.rst +++ b/docs/ansible.netcommon.default_netconf.rst @@ -1,14 +1,19 @@ -.. _ansible.netcommon.default_netconf: +.. Created with antsibull-docs 2.9.0 -************************* -ansible.netcommon.default -************************* +ansible.netcommon.default netconf -- Use default netconf plugin to run standard netconf commands as per RFC ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -**Use default netconf plugin to run standard netconf commands as per RFC** +This netconf plugin is part of the `ansible.netcommon collection `_ (version 6.1.0). +It is not included in ``ansible-core``. +To check whether it is installed, run ``ansible-galaxy collection list``. -Version added: 1.0.0 +To install it, use: :code:`ansible-galaxy collection install ansible.netcommon`. + +To use it in a playbook, specify: ``ansible.netcommon.default``. + +New in ansible.netcommon 1.0.0 .. contents:: :local: @@ -17,43 +22,47 @@ Version added: 1.0.0 Synopsis -------- + - This default plugin provides low level abstraction apis for sending and receiving netconf commands as per Netconf RFC specification. + + + + Parameters ---------- .. raw:: html - - - - - - - - - - - - - -
ParameterChoices/DefaultsConfigurationComments
-
- ncclient_device_handler - -
- string -
- 		- Default:
"default"
- 		- -
Specifies the ncclient device handler name for network os that support default netconf implementation as per Netconf RFC specification. To identify the ncclient device handler name refer ncclient library documentation.
-
-
+ + + + + + + + + + + + + +

Parameter

Comments

+
+

ncclient_device_handler

+ +

+ string +

+ + 		+

Specifies the ncclient device handler name for network os that support default netconf implementation as per Netconf RFC specification. To identify the ncclient device handler name refer ncclient library documentation.

+

Default: "default"

+
+ @@ -62,8 +71,6 @@ Parameters -Status ------- Authors @@ -74,3 +81,9 @@ Authors .. hint:: Configuration entries for each entry type have a low to high priority order. For example, a variable that is lower in the list will override a variable that is higher up. + +Collection links +~~~~~~~~~~~~~~~~ + +* `Issue Tracker `__ +* `Repository (Sources) `__ diff --git a/docs/ansible.netcommon.enable_become.rst b/docs/ansible.netcommon.enable_become.rst index 2c1fed0e8..978c5d6a8 100644 --- a/docs/ansible.netcommon.enable_become.rst +++ b/docs/ansible.netcommon.enable_become.rst @@ -1,14 +1,19 @@ -.. _ansible.netcommon.enable_become: +.. Created with antsibull-docs 2.9.0 -************************ -ansible.netcommon.enable -************************ +ansible.netcommon.enable become -- Switch to elevated permissions on a network device ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -**Switch to elevated permissions on a network device** +This become plugin is part of the `ansible.netcommon collection `_ (version 6.1.0). +It is not included in ``ansible-core``. +To check whether it is installed, run ``ansible-galaxy collection list``. -Version added: 1.0.0 +To install it, use: :code:`ansible-galaxy collection install ansible.netcommon`. + +To use it in a playbook, specify: ``ansible.netcommon.enable``. + +New in ansible.netcommon 1.0.0 .. contents:: :local: @@ -17,67 +22,88 @@ Version added: 1.0.0 Synopsis -------- + - This become plugins allows elevated permissions on a remote network device. + + + + Parameters ---------- .. raw:: html - - - - - - - - - - - - - -
ParameterChoices/DefaultsConfigurationComments
-
- become_pass - -
- - -
- 		- -
ini entries: -

[enable_become_plugin]
password = VALUE

-
-
env:ANSIBLE_BECOME_PASS
-
env:ANSIBLE_ENABLE_PASS
-
var: ansible_become_password
-
var: ansible_become_pass
-
var: ansible_enable_pass
- 		-
password
-
-
+ + + + + + + + + + + + + +

Parameter

Comments

+
+

become_pass

+ +

+ string +

+ + 		+

password

+

Configuration:

+
    +
  • +

    INI entry

    + 
    [enable_become_plugin]
+  password = VALUE
    + +
    • +
  • +

    Environment variable: ANSIBLE_BECOME_PASS

    + +
    • +
  • +

    Environment variable: ANSIBLE_ENABLE_PASS

    + +
    • +
  • +

    Variable: ansible_become_password

    + +
    • +
  • +

    Variable: ansible_become_pass

    + +
    • +
  • +

    Variable: ansible_enable_pass

    + +
    • +
+
-Notes ------ -.. note:: - - enable is really implemented in the network connection handler and as such can only be used with network connections. - - This plugin ignores the 'become_exe' and 'become_user' settings as it uses an API and not an executable. +Notes +----- +- enable is really implemented in the network connection handler and as such can only be used with network connections. +- This plugin ignores the 'become\_exe' and 'become\_user' settings as it uses an API and not an executable. -Status ------- Authors @@ -88,3 +114,9 @@ Authors .. hint:: Configuration entries for each entry type have a low to high priority order. For example, a variable that is lower in the list will override a variable that is higher up. + +Collection links +~~~~~~~~~~~~~~~~ + +* `Issue Tracker `__ +* `Repository (Sources) `__ diff --git a/docs/ansible.netcommon.grpc_config_module.rst b/docs/ansible.netcommon.grpc_config_module.rst index 9e751804b..d535dbbcc 100644 --- a/docs/ansible.netcommon.grpc_config_module.rst +++ b/docs/ansible.netcommon.grpc_config_module.rst @@ -1,14 +1,21 @@ -.. _ansible.netcommon.grpc_config_module: +.. Created with antsibull-docs 2.9.0 -***************************** -ansible.netcommon.grpc_config -***************************** +ansible.netcommon.grpc_config module -- Fetch configuration/state data from gRPC enabled target hosts. +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -**Fetch configuration/state data from gRPC enabled target hosts.** +This module is part of the `ansible.netcommon collection `_ (version 6.1.0). +It is not included in ``ansible-core``. +To check whether it is installed, run ``ansible-galaxy collection list``. -Version added: 3.1.0 +To install it, use: :code:`ansible-galaxy collection install ansible.netcommon`. +You need further requirements to be able to use this module, +see `Requirements `_ for details. + +To use it in a playbook, specify: ``ansible.netcommon.grpc_config``. + +New in ansible.netcommon 3.1.0 .. contents:: :local: @@ -17,11 +24,15 @@ Version added: 3.1.0 Synopsis -------- + - gRPC is a high performance, open-source universal RPC framework. - This module allows the user to append configs to an existing configuration in a gRPC enabled devices. +This module has a corresponding action plugin. +.. _ansible_collections.ansible.netcommon.grpc_config_module_requirements: + Requirements ------------ The below requirements are needed on the host that executes this module. @@ -30,127 +41,123 @@ The below requirements are needed on the host that executes this module. - protobuf + + + + Parameters ---------- .. raw:: html - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ParameterChoices/DefaultsComments
-
- backup - -
- boolean -
- 		-
    Choices: -
  • no ←
    • -
  • yes
    • -
- 		-
This argument will cause the module to create a full backup of the current running-config from the remote device before any changes are made. If the backup_options value is not given, the backup file is written to the backup folder in the playbook root directory or role root directory, if playbook is part of an ansible role. If the directory does not exist, it is created.
-
-
- backup_options - -
- dictionary -
- 		- -
This is a dict object containing configurable options related to backup file path. The value of this option is read only when backup is set to yes, if backup is set to no this option will be silently ignored.
-
-
- dir_path - -
- path -
- 		- -
This option provides the path ending with directory name in which the backup configuration file will be stored. If the directory does not exist it will be first created and the filename is either the value of filename or default filename as described in filename options description. If the path value is not given in that case a backup directory will be created in the current working directory and backup configuration will be copied in filename within backup directory.
-
-
- filename - -
- string -
- 		- -
The filename to be used to store the backup configuration. If the filename is not given it will be generated based on the hostname, current time and date in format defined by <hostname>_config.<current-date>@<current-time>
-
-
- config - -
- string -
- 		- -
This option specifies the string which acts as a filter to restrict the portions of the data to be retrieved from the target host device. If this option is not specified the entire configuration or state data is returned in response provided it is supported by target host.
-
-
- state - -
- string -
- 		- -
action to be performed
-
-
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Parameter

Comments

+
+

backup

+ +

+ boolean +

+ 		+

This argument will cause the module to create a full backup of the current running-config from the remote device before any changes are made. If the backup_options value is not given, the backup file is written to the backup folder in the playbook root directory or role root directory, if playbook is part of an ansible role. If the directory does not exist, it is created.

+

Choices:

+
    +

  • false ← (default)

    • +

  • true

    • +
+ +
+
+

backup_options

+ +

+ dictionary +

+ 		+

This is a dict object containing configurable options related to backup file path. The value of this option is read only when backup is set to yes, if backup is set to no this option will be silently ignored.

+
+
+

dir_path

+ +

+ path +

+ 		+

This option provides the path ending with directory name in which the backup configuration file will be stored. If the directory does not exist it will be first created and the filename is either the value of filename or default filename as described in filename options description. If the path value is not given in that case a backup directory will be created in the current working directory and backup configuration will be copied in filename within backup directory.

+
+
+

filename

+ +

+ string +

+ 		+

The filename to be used to store the backup configuration. If the filename is not given it will be generated based on the hostname, current time and date in format defined by <hostname>_config.<current-date>@<current-time>

+
+
+

config

+ +

+ string +

+ 		+

This option specifies the string which acts as a filter to restrict the portions of the data to be retrieved from the target host device. If this option is not specified the entire configuration or state data is returned in response provided it is supported by target host.

+
+
+

state

+ +

+ string +

+ 		+

action to be performed

+
+ + Notes ----- -.. note:: - - This module requires the gRPC system service be enabled on the target host being managed. - - This module supports the use of connection=connection=ansible.netcommon.grpc - - This module requires the value of 'ansible_network_os' or 'grpc_type' configuration option (refer ansible.netcommon.grpc connection plugin documentation) be defined as an inventory variable. - - Tested against iosxrv 9k version 6.1.2. - +- This module requires the gRPC system service be enabled on the target host being managed. +- This module supports the use of connection=connection=ansible.netcommon.grpc +- This module requires the value of 'ansible\_network\_os' or 'grpc\_type' configuration option (refer ansible.netcommon.grpc connection plugin documentation) be defined as an inventory variable. +- Tested against iosxrv 9k version 6.1.2. Examples @@ -158,6 +165,7 @@ Examples .. code-block:: yaml + - name: Merge static route config ansible.netcommon.grpc_config: config: @@ -193,93 +201,97 @@ Examples + + Return Values ------------- -Common return values are documented `here `_, the following are the fields unique to this module: +The following are the fields unique to this module: .. raw:: html - - - - - - - - - - - - - - - - - - - - - - - - - - -
KeyReturnedDescription
-
- backup_path - -
- string -
- 		when backup is yes -
The full path to the backup file
-
-
Sample:
-
/playbooks/ansible/backup/config.2022-07-16@22:28:34
-
-
- diff - -
- dictionary -
- 		when diff is enabled -
If --diff option in enabled while running, the before and after configuration change are returned as part of before and after key.
-
-
-
- stdout - -
- string -
- 		error mesage, when failure happens. empty , when the operation is successful -
The raw string containing response object received from the gRPC server.
-
-
Sample:
-
...
-
-
- stdout_lines - -
- list -
- 		always apart from low-level errors (such as action plugin) -
The value of stdout split into a list
-
-
Sample:
-
['...', '...']
-
-

- - -Status ------- + + + + + + + + + + + + + + + + + + + + + + + + + +

Key

Description

+
+

backup_path

+ +

+ string +

+ 		+

The full path to the backup file

+

Returned: when backup is yes

+

Sample: "/playbooks/ansible/backup/config.2022-07-16@22:28:34"

+
+
+

diff

+ +

+ dictionary +

+ 		+

If --diff option in enabled while running, the before and after configuration change are returned as part of before and after key.

+

Returned: when diff is enabled

+
+
+

stdout

+ +

+ string +

+ 		+

The raw string containing response object received from the gRPC server.

+

Returned: error mesage, when failure happens. empty , when the operation is successful

+

Sample: "..."

+
+
+

stdout_lines

+ +

+ list + / elements=string +

+ 		+

The value of stdout split into a list

+

Returned: always apart from low-level errors (such as action plugin)

+

Sample: ["...", "..."]

+
+ + Authors ~~~~~~~ - Gomathi Selvi S (@GomathiselviS) + + + +Collection links +~~~~~~~~~~~~~~~~ + +* `Issue Tracker `__ +* `Repository (Sources) `__ diff --git a/docs/ansible.netcommon.grpc_connection.rst b/docs/ansible.netcommon.grpc_connection.rst index 8e1985763..4982d4520 100644 --- a/docs/ansible.netcommon.grpc_connection.rst +++ b/docs/ansible.netcommon.grpc_connection.rst @@ -1,14 +1,21 @@ -.. _ansible.netcommon.grpc_connection: +.. Created with antsibull-docs 2.9.0 -********************** -ansible.netcommon.grpc -********************** +ansible.netcommon.grpc connection -- Provides a persistent connection using the gRPC protocol ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -**Provides a persistent connection using the gRPC protocol** +This connection plugin is part of the `ansible.netcommon collection `_ (version 6.1.0). +It is not included in ``ansible-core``. +To check whether it is installed, run ``ansible-galaxy collection list``. -Version added: 3.1.0 +To install it, use: :code:`ansible-galaxy collection install ansible.netcommon`. +You need further requirements to be able to use this connection plugin, +see `Requirements `_ for details. + +To use it in a playbook, specify: ``ansible.netcommon.grpc``. + +New in ansible.netcommon 3.1.0 .. contents:: :local: @@ -17,348 +24,476 @@ Version added: 3.1.0 Synopsis -------- + - This connection plugin provides a connection to remote devices over gRPC and is typically used with devices for sending and receiving RPC calls over gRPC framework. - Note this connection plugin requires the grpcio python library to be installed on the local Ansible controller. +.. _ansible_collections.ansible.netcommon.grpc_connection_requirements: + Requirements ------------ -The below requirements are needed on the local Ansible controller node that executes this connection. +The below requirements are needed on the local controller node that executes this connection. - grpcio - protobuf + + + + Parameters ---------- .. raw:: html - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ParameterChoices/DefaultsConfigurationComments
-
- certificate_chain_file - -
- string -
- 		- -
ini entries: -

[grpc_connection]
certificate_chain_file = VALUE

-
-
env:ANSIBLE_CERTIFICATE_CHAIN_FILE
-
var: ansible_certificate_chain_file
- 		-
The PEM encoded certificate chain file used to create a SSL-enabled channel. If the value is None, no certificate chain is used.
-
-
- grpc_type - -
- - -
- 		- Default:
"no"
- 		-
ini entries: -

[grpc_connection]
type = no

-
-
env:ANSIBLE_GRPC_CONNECTION_TYPE
-
var: ansible_grpc_connection_type
- 		-
This option indicates the grpc type and it can be used in place of network_os. (example cisco.iosxr.iosxr)
-
-
- host - -
- string -
- 		- Default:
"inventory_hostname"
- 		-
var: ansible_host
- 		-
Specifies the remote device FQDN or IP address to establish the gRPC connection to.
-
-
- import_modules - -
- boolean -
- 		- Default:
"yes"
- 		-
ini entries: -

[ansible_network]
import_modules = yes

-
-
env:ANSIBLE_NETWORK_IMPORT_MODULES
-
var: ansible_network_import_modules
- 		-
Reduce CPU usage and network module execution time by enabling direct execution. Instead of the module being packaged and executed by the shell, it will be directly executed by the Ansible control node using the same python interpreter as the Ansible process. Note- Incompatible with asynchronous mode. Note- Python 3 and Ansible 2.9.16 or greater required. Note- With Ansible 2.9.x fully qualified modules names are required in tasks.
-
-
- network_os - -
- string -
- 		- -
var: ansible_network_os
- 		-
Configures the device platform network operating system. This value is used to load a device specific grpc plugin to communicate with the remote device.
-
-
- password - -
- string -
- 		- -
var: ansible_password
-
var: ansible_ssh_pass
- 		-
Configures the user password used to authenticate to the remote device when first establishing the gRPC connection.
-
-
- persistent_command_timeout - -
- integer -
- 		- Default:
30
- 		-
ini entries: -

[persistent_connection]
command_timeout = 30

-
-
env:ANSIBLE_PERSISTENT_COMMAND_TIMEOUT
-
var: ansible_command_timeout
- 		-
Configures, in seconds, the amount of time to wait for a command to return from the remote device. If this timer is exceeded before the command returns, the connection plugin will raise an exception and close.
-
-
- persistent_connect_timeout - -
- integer -
- 		- Default:
30
- 		-
ini entries: -

[persistent_connection]
connect_timeout = 30

-
-
env:ANSIBLE_PERSISTENT_CONNECT_TIMEOUT
-
var: ansible_connect_timeout
- 		-
Configures, in seconds, the amount of time to wait when trying to initially establish a persistent connection. If this value expires before the connection to the remote device is completed, the connection will fail.
-
-
- persistent_log_messages - -
- boolean -
- 		- Default:
"no"
- 		-
ini entries: -

[persistent_connection]
log_messages = no

-
-
env:ANSIBLE_PERSISTENT_LOG_MESSAGES
-
var: ansible_persistent_log_messages
- 		-
This flag will enable logging the command executed and response received from target device in the ansible log file. For this option to work 'log_path' ansible configuration option is required to be set to a file path with write access.
-
Be sure to fully understand the security implications of enabling this option as it could create a security vulnerability by logging sensitive information in log file.
-
-
- port - -
- integer -
- 		- -
ini entries: -

[defaults]
remote_port = VALUE

-
-
env:ANSIBLE_REMOTE_PORT
-
var: ansible_port
- 		-
Specifies the port on the remote device that listens for connections when establishing the gRPC connection. If None only the host part will be used.
-
-
- private_key_file - -
- string -
- 		- -
ini entries: -

[grpc_connection]
private_key_file = VALUE

-
-
env:ANSIBLE_PRIVATE_KEY_FILE
-
var: ansible_private_key_file
- 		-
The PEM encoded private key file used to authenticate to the remote device when first establishing the grpc connection.
-
-
- remote_user - -
- string -
- 		- -
ini entries: -

[defaults]
remote_user = VALUE

-
-
env:ANSIBLE_REMOTE_USER
-
var: ansible_user
- 		-
The username used to authenticate to the remote device when the gRPC connection is first established. If the remote_user is not specified, the connection will use the username of the logged in user.
-
Can be configured from the CLI via the --user or -u options.
-
-
- root_certificates_file - -
- string -
- 		- -
ini entries: -

[grpc_connection]
root_certificates_file = VALUE

-
-
env:ANSIBLE_ROOT_CERTIFICATES_FILE
-
var: ansible_root_certificates_file
- 		-
The PEM encoded root certificate file used to create a SSL-enabled channel, if the value is None it reads the root certificates from a default location chosen by gRPC at runtime.
-
-
- ssl_target_name_override - -
- string -
- 		- -
ini entries: -

[grpc_connection]
ssl_target_name_override = VALUE

-
-
env:ANSIBLE_GPRC_SSL_TARGET_NAME_OVERRIDE
-
var: ansible_grpc_ssl_target_name_override
- 		-
The option overrides SSL target name used for SSL host name checking. The name used for SSL host name checking will be the target parameter (assuming that the secure channel is an SSL channel). If this parameter is specified and the underlying is not an SSL channel, it will just be ignored.
-
-
- - - - - - - - -Status ------- + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Parameter

Comments

+
+

certificate_chain_file

+ +

+ string +

+ + 		+

The PEM encoded certificate chain file used to create a SSL-enabled channel. If the value is None, no certificate chain is used.

+

Configuration:

+
    +
  • +

    INI entry

    + 
    [grpc_connection]
+  certificate_chain_file = VALUE
    + +
    • +
  • +

    Environment variable: ANSIBLE_CERTIFICATE_CHAIN_FILE

    + +
    • +
  • +

    Variable: ansible_certificate_chain_file

    + +
    • +
+
+
+

grpc_type

+ +

+ string +

+ + 		+

This option indicates the grpc type and it can be used in place of network_os. (example cisco.iosxr.iosxr)

+

Default: false

+

Configuration:

+
    +
  • +

    INI entry

    + 
    [grpc_connection]
+  type = false
    + +
    • +
  • +

    Environment variable: ANSIBLE_GRPC_CONNECTION_TYPE

    + +
    • +
  • +

    Variable: ansible_grpc_connection_type

    + +
    • +
+
+
+

host

+ +

+ string +

+ + 		+

Specifies the remote device FQDN or IP address to establish the gRPC connection to.

+

Default: "inventory_hostname"

+

Configuration:

+
    +
  • +

    Variable: ansible_host

    + +
    • +
+
+
+

import_modules

+ +

+ boolean +

+ + 		+

Reduce CPU usage and network module execution time by enabling direct execution. Instead of the module being packaged and executed by the shell, it will be directly executed by the Ansible control node using the same python interpreter as the Ansible process. Note- Incompatible with asynchronous mode. Note- Python 3 and Ansible 2.9.16 or greater required. Note- With Ansible 2.9.x fully qualified modules names are required in tasks.

+

Choices:

+
    +

  • false

    • +

  • true ← (default)

    • +
+ +

Configuration:

+
    +
  • +

    INI entry

    + 
    [ansible_network]
+  import_modules = true
    + +
    • +
  • +

    Environment variable: ANSIBLE_NETWORK_IMPORT_MODULES

    + +
    • +
  • +

    Variable: ansible_network_import_modules

    + +
    • +
+
+
+

network_os

+ +

+ string +

+ + 		+

Configures the device platform network operating system. This value is used to load a device specific grpc plugin to communicate with the remote device.

+

Configuration:

+
    +
  • +

    Variable: ansible_network_os

    + +
    • +
+
+
+

password

+ +

+ string +

+ + 		+

Configures the user password used to authenticate to the remote device when first establishing the gRPC connection.

+

Configuration:

+
    +
  • +

    Variable: ansible_password

    + +
    • +
  • +

    Variable: ansible_ssh_pass

    + +
    • +
+
+
+

persistent_command_timeout

+ +

+ integer +

+ + 		+

Configures, in seconds, the amount of time to wait for a command to return from the remote device. If this timer is exceeded before the command returns, the connection plugin will raise an exception and close.

+

Default: 30

+

Configuration:

+
    +
  • +

    INI entry

    + 
    [persistent_connection]
+  command_timeout = 30
    + +
    • +
  • +

    Environment variable: ANSIBLE_PERSISTENT_COMMAND_TIMEOUT

    + +
    • +
  • +

    Variable: ansible_command_timeout

    + +
    • +
+
+
+

persistent_connect_timeout

+ +

+ integer +

+ + 		+

Configures, in seconds, the amount of time to wait when trying to initially establish a persistent connection. If this value expires before the connection to the remote device is completed, the connection will fail.

+

Default: 30

+

Configuration:

+
    +
  • +

    INI entry

    + 
    [persistent_connection]
+  connect_timeout = 30
    + +
    • +
  • +

    Environment variable: ANSIBLE_PERSISTENT_CONNECT_TIMEOUT

    + +
    • +
  • +

    Variable: ansible_connect_timeout

    + +
    • +
+
+
+

persistent_log_messages

+ +

+ boolean +

+ + 		+

This flag will enable logging the command executed and response received from target device in the ansible log file. For this option to work 'log_path' ansible configuration option is required to be set to a file path with write access.

+

Be sure to fully understand the security implications of enabling this option as it could create a security vulnerability by logging sensitive information in log file.

+

Choices:

+
    +

  • false ← (default)

    • +

  • true

    • +
+ +

Configuration:

+
    +
  • +

    INI entry

    + 
    [persistent_connection]
+  log_messages = false
    + +
    • +
  • +

    Environment variable: ANSIBLE_PERSISTENT_LOG_MESSAGES

    + +
    • +
  • +

    Variable: ansible_persistent_log_messages

    + +
    • +
+
+
+

port

+ +

+ integer +

+ + 		+

Specifies the port on the remote device that listens for connections when establishing the gRPC connection. If None only the host part will be used.

+

Configuration:

+
    +
  • +

    INI entry

    + 
    [defaults]
+  remote_port = VALUE
    + +
    • +
  • +

    Environment variable: ANSIBLE_REMOTE_PORT

    + +
    • +
  • +

    Variable: ansible_port

    + +
    • +
+
+
+

private_key_file

+ +

+ string +

+ + 		+

The PEM encoded private key file used to authenticate to the remote device when first establishing the grpc connection.

+

Configuration:

+
    +
  • +

    INI entry

    + 
    [grpc_connection]
+  private_key_file = VALUE
    + +
    • +
  • +

    Environment variable: ANSIBLE_PRIVATE_KEY_FILE

    + +
    • +
  • +

    Variable: ansible_private_key_file

    + +
    • +
+
+
+

remote_user

+ +

+ string +

+ + 		+

The username used to authenticate to the remote device when the gRPC connection is first established. If the remote_user is not specified, the connection will use the username of the logged in user.

+

Can be configured from the CLI via the --user or -u options.

+

Configuration:

+
    +
  • +

    INI entry

    + 
    [defaults]
+  remote_user = VALUE
    + +
    • +
  • +

    Environment variable: ANSIBLE_REMOTE_USER

    + +
    • +
  • +

    Variable: ansible_user

    + +
    • +
+
+
+

root_certificates_file

+ +

+ string +

+ + 		+

The PEM encoded root certificate file used to create a SSL-enabled channel, if the value is None it reads the root certificates from a default location chosen by gRPC at runtime.

+

Configuration:

+
    +
  • +

    INI entry

    + 
    [grpc_connection]
+  root_certificates_file = VALUE
    + +
    • +
  • +

    Environment variable: ANSIBLE_ROOT_CERTIFICATES_FILE

    + +
    • +
  • +

    Variable: ansible_root_certificates_file

    + +
    • +
+
+
+

ssl_target_name_override

+ +

+ string +

+ + 		+

The option overrides SSL target name used for SSL host name checking. The name used for SSL host name checking will be the target parameter (assuming that the secure channel is an SSL channel). If this parameter is specified and the underlying is not an SSL channel, it will just be ignored.

+

Configuration:

+
    +
  • +

    INI entry

    + 
    [grpc_connection]
+  ssl_target_name_override = VALUE
    + +
    • +
  • +

    Environment variable: ANSIBLE_GPRC_SSL_TARGET_NAME_OVERRIDE

    + +
    • +
  • +

    Variable: ansible_grpc_ssl_target_name_override

    + +
    • +
+
+ + + + + + + + + Authors @@ -369,3 +504,9 @@ Authors .. hint:: Configuration entries for each entry type have a low to high priority order. For example, a variable that is lower in the list will override a variable that is higher up. + +Collection links +~~~~~~~~~~~~~~~~ + +* `Issue Tracker `__ +* `Repository (Sources) `__ diff --git a/docs/ansible.netcommon.grpc_get_module.rst b/docs/ansible.netcommon.grpc_get_module.rst index 480b5db11..4f7637b41 100644 --- a/docs/ansible.netcommon.grpc_get_module.rst +++ b/docs/ansible.netcommon.grpc_get_module.rst @@ -1,14 +1,21 @@ -.. _ansible.netcommon.grpc_get_module: +.. Created with antsibull-docs 2.9.0 -************************** -ansible.netcommon.grpc_get -************************** +ansible.netcommon.grpc_get module -- Fetch configuration/state data from gRPC enabled target hosts. ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -**Fetch configuration/state data from gRPC enabled target hosts.** +This module is part of the `ansible.netcommon collection `_ (version 6.1.0). +It is not included in ``ansible-core``. +To check whether it is installed, run ``ansible-galaxy collection list``. -Version added: 3.1.0 +To install it, use: :code:`ansible-galaxy collection install ansible.netcommon`. +You need further requirements to be able to use this module, +see `Requirements `_ for details. + +To use it in a playbook, specify: ``ansible.netcommon.grpc_get``. + +New in ansible.netcommon 3.1.0 .. contents:: :local: @@ -17,11 +24,15 @@ Version added: 3.1.0 Synopsis -------- + - gRPC is a high performance, open-source universal RPC framework. - This module allows the user to fetch configuration and state data from gRPC enabled devices. +This module has a corresponding action plugin. +.. _ansible_collections.ansible.netcommon.grpc_get_module_requirements: + Requirements ------------ The below requirements are needed on the host that executes this module. @@ -30,91 +41,90 @@ The below requirements are needed on the host that executes this module. - protobuf + + + + Parameters ---------- .. raw:: html - - - - - - - - - - - - - - - - - - - - - - - - - - -
ParameterChoices/DefaultsComments
-
- command - -
- string -
- 		- -
The option specifies the command to be executed on the target host and return the response in result. This option is supported if the gRPC target host supports executing CLI command over the gRPC connection.
-
-
- data_type - -
- string -
- 		- -
The type of data that should be fetched from the target host. The value depends on the capability of the gRPC server running on target host. The values can be config, oper etc. based on what is supported by the gRPC server. By default it will return both configuration and operational state data in response.
-
-
- display - -
- string -
- 		- -
Encoding scheme to use when serializing output from the device. The encoding scheme value depends on the capability of the gRPC server running on the target host. The values can be json, text etc.
-
-
- section - -
- string -
- 		- -
This option specifies the string which acts as a filter to restrict the portions of the data to be retrieved from the target host device. If this option is not specified the entire configuration or state data is returned in response provided it is supported by target host.
-

aliases: filter
-
-
+ + + + + + + + + + + + + + + + + + + + + + + + + +

Parameter

Comments

+
+

command

+ +

+ string +

+ 		+

The option specifies the command to be executed on the target host and return the response in result. This option is supported if the gRPC target host supports executing CLI command over the gRPC connection.

+
+
+

data_type

+ +

+ string +

+ 		+

The type of data that should be fetched from the target host. The value depends on the capability of the gRPC server running on target host. The values can be config, oper etc. based on what is supported by the gRPC server. By default it will return both configuration and operational state data in response.

+
+
+

display

+ +

+ string +

+ 		+

Encoding scheme to use when serializing output from the device. The encoding scheme value depends on the capability of the gRPC server running on the target host. The values can be json, text etc.

+
+
+
+

section

+ +

aliases: filter

+

+ string +

+ 		+

This option specifies the string which acts as a filter to restrict the portions of the data to be retrieved from the target host device. If this option is not specified the entire configuration or state data is returned in response provided it is supported by target host.

+
+ + Notes ----- -.. note:: - - This module requires the gRPC system service be enabled on the target host being managed. - - This module supports the use of connection=ansible.netcommon.grpc. - - This module requires the value of 'ansible_network_os or grpc_type' configuration option (refer ansible.netcommon.grpc connection plugin documentation) be defined as an inventory variable. - - Tested against iosxrv 9k version 6.1.2. - +- This module requires the gRPC system service be enabled on the target host being managed. +- This module supports the use of connection=ansible.netcommon.grpc. +- This module requires the value of 'ansible\_network\_os or grpc\_type' configuration option (refer ansible.netcommon.grpc connection plugin documentation) be defined as an inventory variable. +- Tested against iosxrv 9k version 6.1.2. Examples @@ -122,6 +132,7 @@ Examples .. code-block:: yaml + - name: Get bgp configuration data grpc_get: section: @@ -134,104 +145,73 @@ Examples + + Return Values ------------- -Common return values are documented `here `_, the following are the fields unique to this module: +The following are the fields unique to this module: .. raw:: html - - - - - - - - - - - - - - - - - - - - - -
KeyReturnedDescription
-
- output - -
- list -
- 		when the device response is valid JSON -
A dictionary representing a JSON-formatted response, if the response is a valid json string
-
-
Sample:
-
[{ - "Cisco-IOS-XR-ip-static-cfg:router-static": { - "default-vrf": { - "address-family": { - "vrfipv4": { - "vrf-unicast": { - "vrf-prefixes": { - "vrf-prefix": [ - { - "prefix": "0.0.0.0", - "prefix-length": 0, - "vrf-route": { - "vrf-next-hop-table": { - "vrf-next-hop-interface-name-next-hop-address": [ - { - "interface-name": "MgmtEth0/RP0/CPU0/0", - "next-hop-address": "10.0.2.2" - } - ] - } - } - } - ] - } - } - } - } - } - } - }]
-
-
- stdout - -
- string -
- 		always apart from low-level errors (such as action plugin) -
The raw string containing configuration or state data received from the gRPC server.
-
-
Sample:
-
...
-
-
- stdout_lines - -
- list -
- 		always apart from low-level errors (such as action plugin) -
The value of stdout split into a list
-
-
Sample:
-
['...', '...']
-
-

- - -Status ------- + + + + + + + + + + + + + + + + + + + + + +

Key

Description

+
+

output

+ +

+ list + / elements=string +

+ 		+

A dictionary representing a JSON-formatted response, if the response is a valid json string

+

Returned: when the device response is valid JSON

+

Sample: ["[{\n \"Cisco-IOS-XR-ip-static-cfg:router-static\": {\n \"default-vrf\": {\n \"address-family\": {\n \"vrfipv4\": {\n \"vrf-unicast\": {\n \"vrf-prefixes\": {\n \"vrf-prefix\": [\n {\n \"prefix\": \"0.0.0.0\"", "\n \"prefix-length\": 0", "\n \"vrf-route\": {\n \"vrf-next-hop-table\": {\n \"vrf-next-hop-interface-name-next-hop-address\": [\n {\n \"interface-name\": \"MgmtEth0/RP0/CPU0/0\"", "\n \"next-hop-address\": \"10.0.2.2\"\n }\n ]\n }\n }\n }\n ]\n }\n }\n }\n }\n }\n }\n}]\n"]

+
+
+

stdout

+ +

+ string +

+ 		+

The raw string containing configuration or state data received from the gRPC server.

+

Returned: always apart from low-level errors (such as action plugin)

+

Sample: "..."

+
+
+

stdout_lines

+ +

+ list + / elements=string +

+ 		+

The value of stdout split into a list

+

Returned: always apart from low-level errors (such as action plugin)

+

Sample: ["...", "..."]

+
+ + Authors @@ -239,3 +219,11 @@ Authors - Ganesh Nalawade (@ganeshrn) - Gomathi Selvi S (@GomathiselviS) + + + +Collection links +~~~~~~~~~~~~~~~~ + +* `Issue Tracker `__ +* `Repository (Sources) `__ diff --git a/docs/ansible.netcommon.hash_salt_filter.rst b/docs/ansible.netcommon.hash_salt_filter.rst index 04e6db28a..cbed1c56f 100644 --- a/docs/ansible.netcommon.hash_salt_filter.rst +++ b/docs/ansible.netcommon.hash_salt_filter.rst @@ -1,14 +1,19 @@ -.. _ansible.netcommon.hash_salt_filter: +.. Created with antsibull-docs 2.9.0 -*************************** -ansible.netcommon.hash_salt -*************************** +ansible.netcommon.hash_salt filter -- The hash\_salt filter plugin. ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -**The hash_salt filter plugin.** +This filter plugin is part of the `ansible.netcommon collection `_ (version 6.1.0). +It is not included in ``ansible-core``. +To check whether it is installed, run ``ansible-galaxy collection list``. -Version added: 1.0.0 +To install it, use: :code:`ansible-galaxy collection install ansible.netcommon`. + +To use it in a playbook, specify: ``ansible.netcommon.hash_salt``. + +New in ansible.netcommon 1.0.0 .. contents:: :local: @@ -17,53 +22,59 @@ Version added: 1.0.0 Synopsis -------- + - The filter plugin produces the salt from a hashed password. -- Using the parameters below - ``password | ansible.netcommon.hash_salt(template.yml``) +- Using the parameters below - \ :literal:`password | ansible.netcommon.hash\_salt(template.yml`\ ) + + + + + +Keyword parameters +------------------ -Parameters ----------- +This describes keyword parameters of the filter. These are the values ``key1=value1``, ``key2=value2`` and so on in the following +example: ``input | ansible.netcommon.hash_salt(key1=value1, key2=value2, ...)`` .. raw:: html - - - - - - - - - - - - - -
ParameterChoices/DefaultsConfigurationComments
-
- password - -
- string - / required -
- 		- - -
This source data on which hash_salt invokes.
-
For example password | ansible.netcommon.hash_salt, in this case password represents the hashed password.
-
-
+ + + + + + + + + + + + + +

Parameter

Comments

+
+

password

+ +

+ string + / required +

+ + 		+

This source data on which hash_salt invokes.

+

For example password | ansible.netcommon.hash_salt, in this case password represents the hashed password.

+
+ + Notes ----- -.. note:: - - The filter plugin produces the salt from a hashed password. - +- The filter plugin produces the salt from a hashed password. Examples @@ -71,6 +82,7 @@ Examples .. code-block:: yaml + # Using hash_salt # playbook @@ -99,8 +111,7 @@ Examples -Status ------- + Authors @@ -111,3 +122,9 @@ Authors .. hint:: Configuration entries for each entry type have a low to high priority order. For example, a variable that is lower in the list will override a variable that is higher up. + +Collection links +~~~~~~~~~~~~~~~~ + +* `Issue Tracker `__ +* `Repository (Sources) `__ diff --git a/docs/ansible.netcommon.httpapi_connection.rst b/docs/ansible.netcommon.httpapi_connection.rst index eb8e5b424..c3dac40ed 100644 --- a/docs/ansible.netcommon.httpapi_connection.rst +++ b/docs/ansible.netcommon.httpapi_connection.rst @@ -1,14 +1,19 @@ -.. _ansible.netcommon.httpapi_connection: +.. Created with antsibull-docs 2.9.0 -************************* -ansible.netcommon.httpapi -************************* +ansible.netcommon.httpapi connection -- Use httpapi to run command on network appliances +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -**Use httpapi to run command on network appliances** +This connection plugin is part of the `ansible.netcommon collection `_ (version 6.1.0). +It is not included in ``ansible-core``. +To check whether it is installed, run ``ansible-galaxy collection list``. -Version added: 1.0.0 +To install it, use: :code:`ansible-galaxy collection install ansible.netcommon`. + +To use it in a playbook, specify: ``ansible.netcommon.httpapi``. + +New in ansible.netcommon 1.0.0 .. contents:: :local: @@ -17,475 +22,633 @@ Version added: 1.0.0 Synopsis -------- + - This connection plugin provides a connection to remote devices over a HTTP(S)-based api. + + + + Parameters ---------- .. raw:: html - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ParameterChoices/DefaultsConfigurationComments
-
- become - -
- boolean -
- 		- Default:
"no"
- 		-
ini entries: -

[privilege_escalation]
become = no

-
-
env:ANSIBLE_BECOME
-
var: ansible_become
- 		-
The become option will instruct the CLI session to attempt privilege escalation on platforms that support it. Normally this means transitioning from user mode to enable mode in the CLI session. If become is set to True and the remote device does not support privilege escalation or the privilege has already been elevated, then this option is silently ignored.
-
Can be configured from the CLI via the --become or -b options.
-
-
- become_method - -
- string -
- 		- Default:
"sudo"
- 		-
ini entries: -

[privilege_escalation]
become_method = sudo

-
-
env:ANSIBLE_BECOME_METHOD
-
var: ansible_become_method
- 		-
This option allows the become method to be specified in for handling privilege escalation. Typically the become_method value is set to enable but could be defined as other values.
-
-
- ca_path - -
- path -
-
added in 5.2.0
- 		- -
var: ansible_httpapi_ca_path
- 		-
Path to CA cert bundle to use.
-
-
- ciphers - -
- list - / elements=string -
-
added in 5.0.0
- 		- -
var: ansible_httpapi_ciphers
- 		-
SSL/TLS Ciphers to use for requests
-
When a list is provided, all ciphers are joined in order with :
-
See the OpenSSL Cipher List Format for more details.
-
The available ciphers is dependent on the Python and OpenSSL/LibreSSL versions.
-
This option will have no effect on ansible-core<2.14 but a warning will be emitted.
-
-
- client_cert - -
- - -
-
added in 5.2.0
- 		- -
var: ansible_httpapi_client_cert
- 		-
PEM formatted certificate chain file to be used for SSL client authentication. This file can also include the key as well, and if the key is included, client_key is not required
-
-
- client_key - -
- - -
-
added in 5.2.0
- 		- -
var: ansible_httpapi_client_key
- 		-
PEM formatted file that contains the private key to be used for SSL client authentication. If client_cert contains both the certificate and key, this option is not required.
-
-
- host - -
- string -
- 		- Default:
"inventory_hostname"
- 		-
var: inventory_hostname
-
var: ansible_host
- 		-
Specifies the remote device FQDN or IP address to establish the HTTP(S) connection to.
-
-
- http_agent - -
- - -
-
added in 5.2.0
- 		- -
var: ansible_httpapi_http_agent
- 		-
User-Agent to use in the request.
-
-
- import_modules - -
- boolean -
- 		- Default:
"yes"
- 		-
ini entries: -

[ansible_network]
import_modules = yes

-
-
env:ANSIBLE_NETWORK_IMPORT_MODULES
-
var: ansible_network_import_modules
- 		-
Reduce CPU usage and network module execution time by enabling direct execution. Instead of the module being packaged and executed by the shell, it will be directly executed by the Ansible control node using the same python interpreter as the Ansible process. Note- Incompatible with asynchronous mode. Note- Python 3 and Ansible 2.9.16 or greater required. Note- With Ansible 2.9.x fully qualified modules names are required in tasks.
-
-
- network_os - -
- string -
- 		- -
var: ansible_network_os
- 		-
Configures the device platform network operating system. This value is used to load the correct httpapi plugin to communicate with the remote device
-
-
- password - -
- string -
- 		- -
var: ansible_password
-
var: ansible_httpapi_pass
-
var: ansible_httpapi_password
- 		-
Configures the user password used to authenticate to the remote device when needed for the device API.
-
-
- persistent_command_timeout - -
- integer -
- 		- Default:
30
- 		-
ini entries: -

[persistent_connection]
command_timeout = 30

-
-
env:ANSIBLE_PERSISTENT_COMMAND_TIMEOUT
-
var: ansible_command_timeout
- 		-
Configures, in seconds, the amount of time to wait for a command to return from the remote device. If this timer is exceeded before the command returns, the connection plugin will raise an exception and close.
-
-
- persistent_connect_timeout - -
- integer -
- 		- Default:
30
- 		-
ini entries: -

[persistent_connection]
connect_timeout = 30

-
-
env:ANSIBLE_PERSISTENT_CONNECT_TIMEOUT
-
var: ansible_connect_timeout
- 		-
Configures, in seconds, the amount of time to wait when trying to initially establish a persistent connection. If this value expires before the connection to the remote device is completed, the connection will fail.
-
-
- persistent_log_messages - -
- boolean -
- 		- Default:
"no"
- 		-
ini entries: -

[persistent_connection]
log_messages = no

-
-
env:ANSIBLE_PERSISTENT_LOG_MESSAGES
-
var: ansible_persistent_log_messages
- 		-
This flag will enable logging the command executed and response received from target device in the ansible log file. For this option to work 'log_path' ansible configuration option is required to be set to a file path with write access.
-
Be sure to fully understand the security implications of enabling this option as it could create a security vulnerability by logging sensitive information in log file.
-
-
- platform_type - -
- string -
- 		- -
env:ANSIBLE_PLATFORM_TYPE
-
var: ansible_platform_type
- 		-
Set type of platform.
-
-
- port - -
- integer -
- 		- -
ini entries: -

[defaults]
remote_port = VALUE

-
-
env:ANSIBLE_REMOTE_PORT
-
var: ansible_httpapi_port
- 		-
Specifies the port on the remote device that listens for connections when establishing the HTTP(S) connection.
-
When unspecified, will pick 80 or 443 based on the value of use_ssl.
-
-
- remote_user - -
- string -
- 		- -
ini entries: -

[defaults]
remote_user = VALUE

-
-
env:ANSIBLE_REMOTE_USER
-
var: ansible_user
- 		-
The username used to authenticate to the remote device when the API connection is first established. If the remote_user is not specified, the connection will use the username of the logged in user.
-
Can be configured from the CLI via the --user or -u options.
-
-
- session_key - -
- dictionary -
- 		- -
var: ansible_httpapi_session_key
- 		-
Configures the session key to be used to authenticate to the remote device when needed for the device API.
-
This should contain a dictionary representing the key name and value for the token.
-
When specified, password is ignored.
-
-
- use_proxy - -
- boolean -
- 		- Default:
"yes"
- 		-
var: ansible_httpapi_use_proxy
- 		-
Whether to use https_proxy for requests.
-
-
- use_ssl - -
- boolean -
- 		- Default:
"no"
- 		-
var: ansible_httpapi_use_ssl
- 		-
Whether to connect using SSL (HTTPS) or not (HTTP).
-
-
- validate_certs - -
- boolean -
- 		- Default:
"yes"
- 		-
var: ansible_httpapi_validate_certs
- 		-
Whether to validate SSL certificates
-
-
- - - - - - - - -Status ------- + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Parameter

Comments

+
+

become

+ +

+ boolean +

+ + 		+

The become option will instruct the CLI session to attempt privilege escalation on platforms that support it. Normally this means transitioning from user mode to enable mode in the CLI session. If become is set to True and the remote device does not support privilege escalation or the privilege has already been elevated, then this option is silently ignored.

+

Can be configured from the CLI via the --become or -b options.

+

Choices:

+
    +

  • false ← (default)

    • +

  • true

    • +
+ +

Configuration:

+
    +
  • +

    INI entry

    + 
    [privilege_escalation]
+  become = false
    + +
    • +
  • +

    Environment variable: ANSIBLE_BECOME

    + +
    • +
  • +

    Variable: ansible_become

    + +
    • +
+
+
+

become_method

+ +

+ string +

+ + 		+

This option allows the become method to be specified in for handling privilege escalation. Typically the become_method value is set to enable but could be defined as other values.

+

Default: "sudo"

+

Configuration:

+
    +
  • +

    INI entry

    + 
    [privilege_escalation]
+  become_method = sudo
    + +
    • +
  • +

    Environment variable: ANSIBLE_BECOME_METHOD

    + +
    • +
  • +

    Variable: ansible_become_method

    + +
    • +
+
+
+

ca_path

+ +

+ path +

+

added in ansible.netcommon 5.2.0

+ + 		+

Path to CA cert bundle to use.

+

Configuration:

+
    +
  • +

    Variable: ansible_httpapi_ca_path

    + +
    • +
+
+
+

ciphers

+ +

+ list + / elements=string +

+

added in ansible.netcommon 5.0.0

+ + 		+

SSL/TLS Ciphers to use for requests

+

When a list is provided, all ciphers are joined in order with :

+

See the OpenSSL Cipher List Format for more details.

+

The available ciphers is dependent on the Python and OpenSSL/LibreSSL versions.

+

This option will have no effect on ansible-core<2.14 but a warning will be emitted.

+

Configuration:

+
    +
  • +

    Variable: ansible_httpapi_ciphers

    + +
    • +
+
+
+

client_cert

+ +

+ string +

+

added in ansible.netcommon 5.2.0

+ + 		+

PEM formatted certificate chain file to be used for SSL client authentication. This file can also include the key as well, and if the key is included, client_key is not required

+

Configuration:

+
    +
  • +

    Variable: ansible_httpapi_client_cert

    + +
    • +
+
+
+

client_key

+ +

+ string +

+

added in ansible.netcommon 5.2.0

+ + 		+

PEM formatted file that contains the private key to be used for SSL client authentication. If client_cert contains both the certificate and key, this option is not required.

+

Configuration:

+
    +
  • +

    Variable: ansible_httpapi_client_key

    + +
    • +
+
+
+

host

+ +

+ string +

+ + 		+

Specifies the remote device FQDN or IP address to establish the HTTP(S) connection to.

+

Default: "inventory_hostname"

+

Configuration:

+
    +
  • +

    Variable: inventory_hostname

    + +
    • +
  • +

    Variable: ansible_host

    + +
    • +
+
+
+

http_agent

+ +

+ string +

+

added in ansible.netcommon 5.2.0

+ + 		+

User-Agent to use in the request.

+

Configuration:

+
    +
  • +

    Variable: ansible_httpapi_http_agent

    + +
    • +
+
+
+

import_modules

+ +

+ boolean +

+ + 		+

Reduce CPU usage and network module execution time by enabling direct execution. Instead of the module being packaged and executed by the shell, it will be directly executed by the Ansible control node using the same python interpreter as the Ansible process. Note- Incompatible with asynchronous mode. Note- Python 3 and Ansible 2.9.16 or greater required. Note- With Ansible 2.9.x fully qualified modules names are required in tasks.

+

Choices:

+
    +

  • false

    • +

  • true ← (default)

    • +
+ +

Configuration:

+
    +
  • +

    INI entry

    + 
    [ansible_network]
+  import_modules = true
    + +
    • +
  • +

    Environment variable: ANSIBLE_NETWORK_IMPORT_MODULES

    + +
    • +
  • +

    Variable: ansible_network_import_modules

    + +
    • +
+
+
+

network_os

+ +

+ string +

+ + 		+

Configures the device platform network operating system. This value is used to load the correct httpapi plugin to communicate with the remote device

+

Configuration:

+
    +
  • +

    Variable: ansible_network_os

    + +
    • +
+
+
+

password

+ +

+ string +

+ + 		+

Configures the user password used to authenticate to the remote device when needed for the device API.

+

Configuration:

+
    +
  • +

    Variable: ansible_password

    + +
    • +
  • +

    Variable: ansible_httpapi_pass

    + +
    • +
  • +

    Variable: ansible_httpapi_password

    + +
    • +
+
+
+

persistent_command_timeout

+ +

+ integer +

+ + 		+

Configures, in seconds, the amount of time to wait for a command to return from the remote device. If this timer is exceeded before the command returns, the connection plugin will raise an exception and close.

+

Default: 30

+

Configuration:

+
    +
  • +

    INI entry

    + 
    [persistent_connection]
+  command_timeout = 30
    + +
    • +
  • +

    Environment variable: ANSIBLE_PERSISTENT_COMMAND_TIMEOUT

    + +
    • +
  • +

    Variable: ansible_command_timeout

    + +
    • +
+
+
+

persistent_connect_timeout

+ +

+ integer +

+ + 		+

Configures, in seconds, the amount of time to wait when trying to initially establish a persistent connection. If this value expires before the connection to the remote device is completed, the connection will fail.

+

Default: 30

+

Configuration:

+
    +
  • +

    INI entry

    + 
    [persistent_connection]
+  connect_timeout = 30
    + +
    • +
  • +

    Environment variable: ANSIBLE_PERSISTENT_CONNECT_TIMEOUT

    + +
    • +
  • +

    Variable: ansible_connect_timeout

    + +
    • +
+
+
+

persistent_log_messages

+ +

+ boolean +

+ + 		+

This flag will enable logging the command executed and response received from target device in the ansible log file. For this option to work 'log_path' ansible configuration option is required to be set to a file path with write access.

+

Be sure to fully understand the security implications of enabling this option as it could create a security vulnerability by logging sensitive information in log file.

+

Choices:

+
    +

  • false ← (default)

    • +

  • true

    • +
+ +

Configuration:

+
    +
  • +

    INI entry

    + 
    [persistent_connection]
+  log_messages = false
    + +
    • +
  • +

    Environment variable: ANSIBLE_PERSISTENT_LOG_MESSAGES

    + +
    • +
  • +

    Variable: ansible_persistent_log_messages

    + +
    • +
+
+
+

platform_type

+ +

+ string +

+ + 		+

Set type of platform.

+

Configuration:

+
    +
  • +

    Environment variable: ANSIBLE_PLATFORM_TYPE

    + +
    • +
  • +

    Variable: ansible_platform_type

    + +
    • +
+
+
+

port

+ +

+ integer +

+ + 		+

Specifies the port on the remote device that listens for connections when establishing the HTTP(S) connection.

+

When unspecified, will pick 80 or 443 based on the value of use_ssl.

+

Configuration:

+
    +
  • +

    INI entry

    + 
    [defaults]
+  remote_port = VALUE
    + +
    • +
  • +

    Environment variable: ANSIBLE_REMOTE_PORT

    + +
    • +
  • +

    Variable: ansible_httpapi_port

    + +
    • +
+
+
+

remote_user

+ +

+ string +

+ + 		+

The username used to authenticate to the remote device when the API connection is first established. If the remote_user is not specified, the connection will use the username of the logged in user.

+

Can be configured from the CLI via the --user or -u options.

+

Configuration:

+
    +
  • +

    INI entry

    + 
    [defaults]
+  remote_user = VALUE
    + +
    • +
  • +

    Environment variable: ANSIBLE_REMOTE_USER

    + +
    • +
  • +

    Variable: ansible_user

    + +
    • +
+
+
+

session_key

+ +

+ dictionary +

+ + 		+

Configures the session key to be used to authenticate to the remote device when needed for the device API.

+

This should contain a dictionary representing the key name and value for the token.

+

When specified, password is ignored.

+

Configuration:

+
    +
  • +

    Variable: ansible_httpapi_session_key

    + +
    • +
+
+
+

use_proxy

+ +

+ boolean +

+ + 		+

Whether to use https_proxy for requests.

+

Choices:

+
    +

  • false

    • +

  • true ← (default)

    • +
+ +

Configuration:

+
    +
  • +

    Variable: ansible_httpapi_use_proxy

    + +
    • +
+
+
+

use_ssl

+ +

+ boolean +

+ + 		+

Whether to connect using SSL (HTTPS) or not (HTTP).

+

Choices:

+
    +

  • false ← (default)

    • +

  • true

    • +
+ +

Configuration:

+
    +
  • +

    Variable: ansible_httpapi_use_ssl

    + +
    • +
+
+
+

validate_certs

+ +

+ boolean +

+ + 		+

Whether to validate SSL certificates

+

Choices:

+
    +

  • false

    • +

  • true ← (default)

    • +
+ +

Configuration:

+
    +
  • +

    Variable: ansible_httpapi_validate_certs

    + +
    • +
+
+ + + + + + + + + Authors @@ -496,3 +659,9 @@ Authors .. hint:: Configuration entries for each entry type have a low to high priority order. For example, a variable that is lower in the list will override a variable that is higher up. + +Collection links +~~~~~~~~~~~~~~~~ + +* `Issue Tracker `__ +* `Repository (Sources) `__ diff --git a/docs/ansible.netcommon.libssh_connection.rst b/docs/ansible.netcommon.libssh_connection.rst index 42a5b4628..870540455 100644 --- a/docs/ansible.netcommon.libssh_connection.rst +++ b/docs/ansible.netcommon.libssh_connection.rst @@ -1,14 +1,19 @@ -.. _ansible.netcommon.libssh_connection: +.. Created with antsibull-docs 2.9.0 -************************ -ansible.netcommon.libssh -************************ +ansible.netcommon.libssh connection -- Run tasks using libssh for ssh connection +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -**Run tasks using libssh for ssh connection** +This connection plugin is part of the `ansible.netcommon collection `_ (version 6.1.0). +It is not included in ``ansible-core``. +To check whether it is installed, run ``ansible-galaxy collection list``. -Version added: 1.1.0 +To install it, use: :code:`ansible-galaxy collection install ansible.netcommon`. + +To use it in a playbook, specify: ``ansible.netcommon.libssh``. + +New in ansible.netcommon 1.1.0 .. contents:: :local: @@ -17,6 +22,7 @@ Version added: 1.1.0 Synopsis -------- + - Use the ansible-pylibssh python bindings to connect to targets - The python bindings use libssh C library (https://www.libssh.org/) to connect to targets - This plugin borrows a lot of settings from the ssh plugin as they both cover the same protocol. @@ -24,360 +30,547 @@ Synopsis + + + + Parameters ---------- .. raw:: html - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ParameterChoices/DefaultsConfigurationComments
-
- config_file - -
- path -
-
added in 5.1.0
- 		- -
ini entries: -

[libssh_connection]
config_file = VALUE

-
-
env:ANSIBLE_LIBSSH_CONFIG_FILE
-
var: ansible_libssh_config_file
- 		-
Alternate SSH config file location
-
-
- host_key_auto_add - -
- boolean -
- 		- -
ini entries: -

[libssh_connection]
host_key_auto_add = VALUE

-
-
env:ANSIBLE_LIBSSH_HOST_KEY_AUTO_ADD
- 		-
TODO: write it
-
-
- host_key_checking - -
- boolean -
- 		- Default:
"yes"
- 		-
ini entries: -

[defaults]
host_key_checking = yes

-

[libssh_connection]
host_key_checking = yes

-
-
env:ANSIBLE_HOST_KEY_CHECKING
-
env:ANSIBLE_SSH_HOST_KEY_CHECKING
-
env:ANSIBLE_LIBSSH_HOST_KEY_CHECKING
-
var: ansible_host_key_checking
-
var: ansible_ssh_host_key_checking
-
var: ansible_libssh_host_key_checking
- 		-
Set this to "False" if you want to avoid host key checking by the underlying tools Ansible uses to connect to the host
-
-
- look_for_keys - -
- boolean -
- 		- Default:
"yes"
- 		-
ini entries: -

[libssh_connection]
look_for_keys = yes

-
-
env:ANSIBLE_LIBSSH_LOOK_FOR_KEYS
- 		-
TODO: write it
-
-
- password - -
- string -
- 		- -
var: ansible_password
-
var: ansible_ssh_pass
-
var: ansible_ssh_password
-
var: ansible_libssh_pass
-
var: ansible_libssh_password
- 		-
Secret used to either login the ssh server or as a passphrase for ssh keys that require it
-
Can be set from the CLI via the --ask-pass option.
-
-
- password_prompt - -
- string -
-
added in 3.1.0
- 		- -
var: ansible_libssh_password_prompt
- 		-
Text to match when using keyboard-interactive authentication to determine if the prompt is for the password.
-
Requires ansible-pylibssh version >= 1.0.0
-
-
- proxy_command - -
- string -
- 		- Default:
""
- 		-
ini entries: -

[libssh_connection]
proxy_command =

-
-
env:ANSIBLE_LIBSSH_PROXY_COMMAND
-
var: ansible_paramiko_proxy_command
-
var: ansible_libssh_proxy_command
- 		-
Proxy information for running the connection via a jumphost.
-
Also this plugin will scan 'ssh_args', 'ssh_extra_args' and 'ssh_common_args' from the 'ssh' plugin settings for proxy information if set.
-
-
- pty - -
- boolean -
- 		- Default:
"yes"
- 		-
ini entries: -

[libssh_connection]
pty = yes

-
-
env:ANSIBLE_LIBSSH_PTY
- 		-
TODO: write it
-
-
- remote_addr - -
- string -
- 		- Default:
"inventory_hostname"
- 		-
var: inventory_hostname
-
var: ansible_host
-
var: ansible_ssh_host
-
var: ansible_libssh_host
- 		-
Address of the remote target
-
-
- remote_user - -
- string -
- 		- -
ini entries: -

[defaults]
remote_user = VALUE

-

[libssh_connection]
remote_user = VALUE

-
-
env:ANSIBLE_REMOTE_USER
-
env:ANSIBLE_LIBSSH_REMOTE_USER
-
var: ansible_user
-
var: ansible_ssh_user
-
var: ansible_libssh_user
- 		-
User to login/authenticate as
-
Can be set from the CLI via the --user or -u options.
-
-
- ssh_args - -
- string -
-
added in 3.2.0
- 		- -
ini entries: -

[ssh_connection]
ssh_args = VALUE

-
-
env:ANSIBLE_SSH_ARGS
-
var: ansible_ssh_args
- 		-
Arguments to pass to all ssh CLI tools.
-
ProxyCommand is the only supported argument.
-
This option is deprecated in favor of proxy_command and will be removed in a release after 2026-01-01.
-
-
- ssh_common_args - -
- string -
-
added in 3.2.0
- 		- -
ini entries: -

[ssh_connection]
ssh_common_args = VALUE

-
-
env:ANSIBLE_SSH_COMMON_ARGS
-
var: ansible_ssh_common_args
- 		-
Common extra arguments for all ssh CLI tools.
-
ProxyCommand is the only supported argument.
-
This option is deprecated in favor of proxy_command and will be removed in a release after 2026-01-01.
-
-
- ssh_extra_args - -
- string -
-
added in 3.2.0
- 		- -
ini entries: -

[ssh_connection]
ssh_extra_args = VALUE

-
-
env:ANSIBLE_SSH_EXTRA_ARGS
-
var: ansible_ssh_extra_args
- 		-
Extra arguments exclusive to the 'ssh' CLI tool.
-
ProxyCommand is the only supported argument.
-
This option is deprecated in favor of proxy_command and will be removed in a release after 2026-01-01.
-
-
- use_persistent_connections - -
- boolean -
- 		- Default:
"no"
- 		-
ini entries: -

[defaults]
use_persistent_connections = no

-
-
env:ANSIBLE_USE_PERSISTENT_CONNECTIONS
- 		-
Toggles the use of persistence for connections
-
-
- - - - - - - - -Status ------- + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Parameter

Comments

+
+

config_file

+ +

+ path +

+

added in ansible.netcommon 5.1.0

+ + 		+

Alternate SSH config file location

+

Configuration:

+
    +
  • +

    INI entry

    + 
    [libssh_connection]
+  config_file = VALUE
    + +
    • +
  • +

    Environment variable: ANSIBLE_LIBSSH_CONFIG_FILE

    + +
    • +
  • +

    Variable: ansible_libssh_config_file

    + +
    • +
+
+
+

host_key_auto_add

+ +

+ boolean +

+ + 		+

TODO: write it

+

Choices:

+
    +

  • false

    • +

  • true

    • +
+ +

Configuration:

+
    +
  • +

    INI entry

    + 
    [libssh_connection]
+  host_key_auto_add = VALUE
    + +
    • +
  • +

    Environment variable: ANSIBLE_LIBSSH_HOST_KEY_AUTO_ADD

    + +
    • +
+
+
+

host_key_checking

+ +

+ boolean +

+ + 		+

Set this to "False" if you want to avoid host key checking by the underlying tools Ansible uses to connect to the host

+

Choices:

+
    +

  • false

    • +

  • true ← (default)

    • +
+ +

Configuration:

+
    +
  • +

    INI entries

    + 
    [defaults]
+  host_key_checking = true
    + + 
    [libssh_connection]
+  host_key_checking = true
    + +
    • +
  • +

    Environment variable: ANSIBLE_HOST_KEY_CHECKING

    + +
    • +
  • +

    Environment variable: ANSIBLE_SSH_HOST_KEY_CHECKING

    + +
    • +
  • +

    Environment variable: ANSIBLE_LIBSSH_HOST_KEY_CHECKING

    + +
    • +
  • +

    Variable: ansible_host_key_checking

    + +
    • +
  • +

    Variable: ansible_ssh_host_key_checking

    + +
    • +
  • +

    Variable: ansible_libssh_host_key_checking

    + +
    • +
+
+
+

look_for_keys

+ +

+ boolean +

+ + 		+

TODO: write it

+

Choices:

+
    +

  • false

    • +

  • true ← (default)

    • +
+ +

Configuration:

+
    +
  • +

    INI entry

    + 
    [libssh_connection]
+  look_for_keys = true
    + +
    • +
  • +

    Environment variable: ANSIBLE_LIBSSH_LOOK_FOR_KEYS

    + +
    • +
+
+
+

password

+ +

+ string +

+ + 		+

Secret used to either login the ssh server or as a passphrase for ssh keys that require it

+

Can be set from the CLI via the --ask-pass option.

+

Configuration:

+
    +
  • +

    Variable: ansible_password

    + +
    • +
  • +

    Variable: ansible_ssh_pass

    + +
    • +
  • +

    Variable: ansible_ssh_password

    + +
    • +
  • +

    Variable: ansible_libssh_pass

    + +
    • +
  • +

    Variable: ansible_libssh_password

    + +
    • +
+
+
+

password_prompt

+ +

+ string +

+

added in ansible.netcommon 3.1.0

+ + 		+

Text to match when using keyboard-interactive authentication to determine if the prompt is for the password.

+

Requires ansible-pylibssh version >= 1.0.0

+

Configuration:

+
    +
  • +

    Variable: ansible_libssh_password_prompt

    + +
    • +
+
+
+

proxy_command

+ +

+ string +

+ + 		+

Proxy information for running the connection via a jumphost.

+

Also this plugin will scan 'ssh_args', 'ssh_extra_args' and 'ssh_common_args' from the 'ssh' plugin settings for proxy information if set.

+

Default: ""

+

Configuration:

+
    +
  • +

    INI entry

    + 
    [libssh_connection]
+  proxy_command = ""
    + +
    • +
  • +

    Environment variable: ANSIBLE_LIBSSH_PROXY_COMMAND

    + +
    • +
  • +

    Variable: ansible_paramiko_proxy_command

    + +
    • +
  • +

    Variable: ansible_libssh_proxy_command

    + +
    • +
+
+
+

pty

+ +

+ boolean +

+ + 		+

TODO: write it

+

Choices:

+
    +

  • false

    • +

  • true ← (default)

    • +
+ +

Configuration:

+
    +
  • +

    INI entry

    + 
    [libssh_connection]
+  pty = true
    + +
    • +
  • +

    Environment variable: ANSIBLE_LIBSSH_PTY

    + +
    • +
+
+
+

remote_addr

+ +

+ string +

+ + 		+

Address of the remote target

+

Default: "inventory_hostname"

+

Configuration:

+
    +
  • +

    Variable: inventory_hostname

    + +
    • +
  • +

    Variable: ansible_host

    + +
    • +
  • +

    Variable: ansible_ssh_host

    + +
    • +
  • +

    Variable: ansible_libssh_host

    + +
    • +
+
+
+

remote_user

+ +

+ string +

+ + 		+

User to login/authenticate as

+

Can be set from the CLI via the --user or -u options.

+

Configuration:

+
    +
  • +

    INI entries

    + 
    [defaults]
+  remote_user = VALUE
    + + 
    [libssh_connection]
+  remote_user = VALUE
    + +
    • +
  • +

    Environment variable: ANSIBLE_REMOTE_USER

    + +
    • +
  • +

    Environment variable: ANSIBLE_LIBSSH_REMOTE_USER

    + +
    • +
  • +

    Variable: ansible_user

    + +
    • +
  • +

    Variable: ansible_ssh_user

    + +
    • +
  • +

    Variable: ansible_libssh_user

    + +
    • +
+
+
+

ssh_args

+ +

+ string +

+

added in ansible.netcommon 3.2.0

+ + 		+

Arguments to pass to all ssh CLI tools.

+

ProxyCommand is the only supported argument.

+

This option is deprecated in favor of proxy_command and will be removed in a release after 2026-01-01.

+

Configuration:

+
    +
  • +

    INI entry

    + 
    [ssh_connection]
+  ssh_args = VALUE
    + +
    • +
  • +

    Environment variable: ANSIBLE_SSH_ARGS

    + +
    • +
  • +

    Variable: ansible_ssh_args

    + +
    • +
  • +

    CLI argument: --ssh-args

    + +
    • +
+
+
+

ssh_common_args

+ +

+ string +

+

added in ansible.netcommon 3.2.0

+ + 		+

Common extra arguments for all ssh CLI tools.

+

ProxyCommand is the only supported argument.

+

This option is deprecated in favor of proxy_command and will be removed in a release after 2026-01-01.

+

Configuration:

+
    +
  • +

    INI entry

    + 
    [ssh_connection]
+  ssh_common_args = VALUE
    + +
    • +
  • +

    Environment variable: ANSIBLE_SSH_COMMON_ARGS

    + +
    • +
  • +

    Variable: ansible_ssh_common_args

    + +
    • +
  • +

    CLI argument: --ssh-common-args

    + +
    • +
+
+
+

ssh_extra_args

+ +

+ string +

+

added in ansible.netcommon 3.2.0

+ + 		+

Extra arguments exclusive to the 'ssh' CLI tool.

+

ProxyCommand is the only supported argument.

+

This option is deprecated in favor of proxy_command and will be removed in a release after 2026-01-01.

+

Configuration:

+
    +
  • +

    INI entry

    + 
    [ssh_connection]
+  ssh_extra_args = VALUE
    + +
    • +
  • +

    Environment variable: ANSIBLE_SSH_EXTRA_ARGS

    + +
    • +
  • +

    Variable: ansible_ssh_extra_args

    + +
    • +
  • +

    CLI argument: --ssh-extra-args

    + +
    • +
+
+
+

use_persistent_connections

+ +

+ boolean +

+ + 		+

Toggles the use of persistence for connections

+

Choices:

+
    +

  • false ← (default)

    • +

  • true

    • +
+ +

Configuration:

+
    +
  • +

    INI entry

    + 
    [defaults]
+  use_persistent_connections = false
    + +
    • +
  • +

    Environment variable: ANSIBLE_USE_PERSISTENT_CONNECTIONS

    + +
    • +
+
+ + + + + + + + + Authors @@ -388,3 +581,9 @@ Authors .. hint:: Configuration entries for each entry type have a low to high priority order. For example, a variable that is lower in the list will override a variable that is higher up. + +Collection links +~~~~~~~~~~~~~~~~ + +* `Issue Tracker `__ +* `Repository (Sources) `__ diff --git a/docs/ansible.netcommon.memory_cache.rst b/docs/ansible.netcommon.memory_cache.rst new file mode 100644 index 000000000..1fcf3607f --- /dev/null +++ b/docs/ansible.netcommon.memory_cache.rst @@ -0,0 +1,58 @@ + +.. Created with antsibull-docs 2.9.0 + +ansible.netcommon.memory cache -- RAM backed, non persistent cache. ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +This cache plugin is part of the `ansible.netcommon collection `_ (version 6.1.0). + +It is not included in ``ansible-core``. +To check whether it is installed, run ``ansible-galaxy collection list``. + +To install it, use: :code:`ansible-galaxy collection install ansible.netcommon`. + +To use it in a playbook, specify: ``ansible.netcommon.memory``. + +New in ansible.netcommon 2.0.0 + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- + +- RAM backed cache that is not persistent. +- Tailored for networking use case. + + + + + + + + + + + + + + + + + +Authors +~~~~~~~ + +- Ansible Networking Team (@ansible-network) + + +.. hint:: + Configuration entries for each entry type have a low to high priority order. For example, a variable that is lower in the list will override a variable that is higher up. + +Collection links +~~~~~~~~~~~~~~~~ + +* `Issue Tracker `__ +* `Repository (Sources) `__ diff --git a/docs/ansible.netcommon.net_get_module.rst b/docs/ansible.netcommon.net_get_module.rst index 0b4a78de7..5c7c33db1 100644 --- a/docs/ansible.netcommon.net_get_module.rst +++ b/docs/ansible.netcommon.net_get_module.rst @@ -1,14 +1,21 @@ -.. _ansible.netcommon.net_get_module: +.. Created with antsibull-docs 2.9.0 -************************* -ansible.netcommon.net_get -************************* +ansible.netcommon.net_get module -- Copy a file from a network device to Ansible Controller ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -**Copy a file from a network device to Ansible Controller** +This module is part of the `ansible.netcommon collection `_ (version 6.1.0). +It is not included in ``ansible-core``. +To check whether it is installed, run ``ansible-galaxy collection list``. -Version added: 1.0.0 +To install it, use: :code:`ansible-galaxy collection install ansible.netcommon`. +You need further requirements to be able to use this module, +see `Requirements `_ for details. + +To use it in a playbook, specify: ``ansible.netcommon.net_get``. + +New in ansible.netcommon 1.0.0 .. contents:: :local: @@ -17,10 +24,14 @@ Version added: 1.0.0 Synopsis -------- + - This module provides functionality to copy file from network device to ansible controller. +This module has a corresponding action plugin. +.. _ansible_collections.ansible.netcommon.net_get_module_requirements: + Requirements ------------ The below requirements are needed on the host that executes this module. @@ -28,81 +39,83 @@ The below requirements are needed on the host that executes this module. - scp if using protocol=scp with paramiko + + + + Parameters ---------- .. raw:: html - - - - - - - - - - - - - - - - - - - - - -
ParameterChoices/DefaultsComments
-
- dest - -
- - -
- 		- Default:
["Same filename as specified in I(src). The path will be playbook root or role root directory if playbook is part of a role."]
- 		-
Specifies the destination file. The path to the destination file can either be the full path on the Ansible control host or a relative path from the playbook or role root directory.
-
-
- protocol - -
- - -
- 		-
    Choices: -
  • scp ←
    • -
  • sftp
    • -
- 		-
Protocol used to transfer file.
-
-
- src - -
- - - / required -
- 		- -
Specifies the source file. The path to the source file can either be the full path on the network device or a relative path as per path supported by destination network device.
-
-
+ + + + + + + + + + + + + + + + + + + + + +

Parameter

Comments

+
+

dest

+ +

+ string +

+ 		+

Specifies the destination file. The path to the destination file can either be the full path on the Ansible control host or a relative path from the playbook or role root directory.

+

Default: ["Same filename as specified in I(src). The path will be playbook root or role root directory if playbook is part of a role."]

+
+
+

protocol

+ +

+ string +

+ 		+

Protocol used to transfer file.

+

Choices:

+
    +

  • "scp" ← (default)

    • +

  • "sftp"

    • +
+ +
+
+

src

+ +

+ string + / required +

+ 		+

Specifies the source file. The path to the source file can either be the full path on the network device or a relative path as per path supported by destination network device.

+
+ + Notes ----- -.. note:: - - Some devices need specific configurations to be enabled before scp can work These configuration should be pre-configured before using this module e.g ios - ``ip scp server enable``. - - User privilege to do scp on network device should be pre-configured e.g. ios - need user privilege 15 by default for allowing scp. - - Default destination of source file. - - This module is supported on ``ansible_network_os`` network platforms. See the :ref:`Network Platform Options ` for details. - +- Some devices need specific configurations to be enabled before scp can work These configuration should be pre-configured before using this module e.g ios - \ :literal:`ip scp server enable`\ . +- User privilege to do scp on network device should be pre-configured e.g. ios - need user privilege 15 by default for allowing scp. +- Default destination of source file. +- This module is supported on \ :literal:`ansible\_network\_os`\ network platforms. See the :ref:\`Network Platform Options \\` for details. Examples @@ -110,6 +123,7 @@ Examples .. code-block:: yaml + - name: copy file from the network device to Ansible controller ansible.netcommon.net_get: src: running_cfg_ios1.txt @@ -122,11 +136,18 @@ Examples -Status ------- + Authors ~~~~~~~ - Deepak Agrawal (@dagrawal) + + + +Collection links +~~~~~~~~~~~~~~~~ + +* `Issue Tracker `__ +* `Repository (Sources) `__ diff --git a/docs/ansible.netcommon.net_ping_module.rst b/docs/ansible.netcommon.net_ping_module.rst index 1b197fae8..d9c0d7788 100644 --- a/docs/ansible.netcommon.net_ping_module.rst +++ b/docs/ansible.netcommon.net_ping_module.rst @@ -1,14 +1,19 @@ -.. _ansible.netcommon.net_ping_module: +.. Created with antsibull-docs 2.9.0 -************************** -ansible.netcommon.net_ping -************************** +ansible.netcommon.net_ping module -- Tests reachability using ping from a network device +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -**Tests reachability using ping from a network device** +This module is part of the `ansible.netcommon collection `_ (version 6.1.0). +It is not included in ``ansible-core``. +To check whether it is installed, run ``ansible-galaxy collection list``. -Version added: 1.0.0 +To install it, use: :code:`ansible-galaxy collection install ansible.netcommon`. + +To use it in a playbook, specify: ``ansible.netcommon.net_ping``. + +New in ansible.netcommon 1.0.0 .. contents:: :local: @@ -17,8 +22,14 @@ Version added: 1.0.0 Synopsis -------- + - Tests reachability using ping from network device to a remote destination. +This module has a corresponding action plugin. + + + + @@ -27,105 +38,99 @@ Parameters .. raw:: html - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ParameterChoices/DefaultsComments
-
- count - -
- - -
- 		- Default:
5
- 		-
Number of packets to send.
-
-
- dest - -
- - - / required -
- 		- -
The IP Address or hostname (resolvable by switch) of the remote node.
-
-
- source - -
- - -
- 		- -
The source IP Address.
-
-
- state - -
- - -
- 		-
    Choices: -
  • absent
    • -
  • present ←
    • -
- 		-
Determines if the expected result is success or fail.
-
-
- vrf - -
- - -
- 		- Default:
"default"
- 		-
The VRF to use for forwarding.
-
-
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Parameter

Comments

+
+

count

+ +

+ string +

+ 		+

Number of packets to send.

+

Default: 5

+
+
+

dest

+ +

+ string + / required +

+ 		+

The IP Address or hostname (resolvable by switch) of the remote node.

+
+
+

source

+ +

+ string +

+ 		+

The source IP Address.

+
+
+

state

+ +

+ string +

+ 		+

Determines if the expected result is success or fail.

+

Choices:

+
    +

  • "absent"

    • +

  • "present" ← (default)

    • +
+ +
+
+

vrf

+ +

+ string +

+ 		+

The VRF to use for forwarding.

+

Default: "default"

+
+ + Notes ----- -.. note:: - - For targets running Python, use the :ref:`ansible.builtin.shell ` module along with ping command instead. - - This module is supported on ``ansible_network_os`` network platforms. See the :ref:`Network Platform Options ` for details. - +- For targets running Python, use the \ `ansible.builtin.shell `__\ module along with ping command instead. +- This module is supported on \ :literal:`ansible\_network\_os`\ network platforms. See the :ref:\`Network Platform Options \\` for details. Examples @@ -133,6 +138,7 @@ Examples .. code-block:: yaml + - name: Test reachability to 10.10.10.10 using default vrf ansible.netcommon.net_ping: dest: 10.10.10.10 @@ -162,112 +168,113 @@ Examples + + Return Values ------------- -Common return values are documented `here `_, the following are the fields unique to this module: +The following are the fields unique to this module: .. raw:: html - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
KeyReturnedDescription
-
- commands - -
- list -
- 		always -
Show the command sent.
-
-
Sample:
-
['ping vrf prod 10.40.40.40 count 20 source loopback0']
-
-
- packet_loss - -
- string -
- 		always -
Percentage of packets lost.
-
-
Sample:
-
0%
-
-
- packets_rx - -
- integer -
- 		always -
Packets successfully received.
-
-
Sample:
-
20
-
-
- packets_tx - -
- integer -
- 		always -
Packets successfully transmitted.
-
-
Sample:
-
20
-
-
- rtt - -
- dictionary -
- 		always -
Show RTT stats.
-
-
Sample:
-
{'avg': 2, 'max': 8, 'min': 1}
-
-

- - -Status ------- + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Key

Description

+
+

commands

+ +

+ list + / elements=string +

+ 		+

Show the command sent.

+

Returned: always

+

Sample: ["ping vrf prod 10.40.40.40 count 20 source loopback0"]

+
+
+

packet_loss

+ +

+ string +

+ 		+

Percentage of packets lost.

+

Returned: always

+

Sample: "0%"

+
+
+

packets_rx

+ +

+ integer +

+ 		+

Packets successfully received.

+

Returned: always

+

Sample: 20

+
+
+

packets_tx

+ +

+ integer +

+ 		+

Packets successfully transmitted.

+

Returned: always

+

Sample: 20

+
+
+

rtt

+ +

+ dictionary +

+ 		+

Show RTT stats.

+

Returned: always

+

Sample: {"avg": 2, "max": 8, "min": 1}

+
+ + Authors ~~~~~~~ - Jacob McGill (@jmcgill298) + + + +Collection links +~~~~~~~~~~~~~~~~ + +* `Issue Tracker `__ +* `Repository (Sources) `__ diff --git a/docs/ansible.netcommon.net_put_module.rst b/docs/ansible.netcommon.net_put_module.rst index 470e94056..b84c5a9eb 100644 --- a/docs/ansible.netcommon.net_put_module.rst +++ b/docs/ansible.netcommon.net_put_module.rst @@ -1,14 +1,21 @@ -.. _ansible.netcommon.net_put_module: +.. Created with antsibull-docs 2.9.0 -************************* -ansible.netcommon.net_put -************************* +ansible.netcommon.net_put module -- Copy a file from Ansible Controller to a network device ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -**Copy a file from Ansible Controller to a network device** +This module is part of the `ansible.netcommon collection `_ (version 6.1.0). +It is not included in ``ansible-core``. +To check whether it is installed, run ``ansible-galaxy collection list``. -Version added: 1.0.0 +To install it, use: :code:`ansible-galaxy collection install ansible.netcommon`. +You need further requirements to be able to use this module, +see `Requirements `_ for details. + +To use it in a playbook, specify: ``ansible.netcommon.net_put``. + +New in ansible.netcommon 1.0.0 .. contents:: :local: @@ -17,10 +24,14 @@ Version added: 1.0.0 Synopsis -------- + - This module provides functionality to copy file from Ansible controller to network devices. +This module has a corresponding action plugin. +.. _ansible_collections.ansible.netcommon.net_put_module_requirements: + Requirements ------------ The below requirements are needed on the host that executes this module. @@ -28,100 +39,102 @@ The below requirements are needed on the host that executes this module. - scp if using protocol=scp with paramiko + + + + Parameters ---------- .. raw:: html - - - - - - - - - - - - - - - - - - - - - - - - - - -
ParameterChoices/DefaultsComments
-
- dest - -
- - -
- 		- Default:
["Filename from src and at default directory of user shell on network_os."]
- 		-
Specifies the destination file. The path to destination file can either be the full path or relative path as supported by network_os.
-
-
- mode - -
- - -
- 		-
    Choices: -
  • binary ←
    • -
  • text
    • -
- 		-
Set the file transfer mode. If mode is set to text then src file will go through Jinja2 template engine to replace any vars if present in the src file. If mode is set to binary then file will be copied as it is to destination device.
-
-
- protocol - -
- - -
- 		-
    Choices: -
  • scp ←
    • -
  • sftp
    • -
- 		-
Protocol used to transfer file.
-
-
- src - -
- - - / required -
- 		- -
Specifies the source file. The path to the source file can either be the full path on the Ansible control host or a relative path from the playbook or role root directory.
-
-
+ + + + + + + + + + + + + + + + + + + + + + + + + +

Parameter

Comments

+
+

dest

+ +

+ string +

+ 		+

Specifies the destination file. The path to destination file can either be the full path or relative path as supported by network_os.

+

Default: ["Filename from src and at default directory of user shell on network_os."]

+
+
+

mode

+ +

+ string +

+ 		+

Set the file transfer mode. If mode is set to text then src file will go through Jinja2 template engine to replace any vars if present in the src file. If mode is set to binary then file will be copied as it is to destination device.

+

Choices:

+
    +

  • "binary" ← (default)

    • +

  • "text"

    • +
+ +
+
+

protocol

+ +

+ string +

+ 		+

Protocol used to transfer file.

+

Choices:

+
    +

  • "scp" ← (default)

    • +

  • "sftp"

    • +
+ +
+
+

src

+ +

+ string + / required +

+ 		+

Specifies the source file. The path to the source file can either be the full path on the Ansible control host or a relative path from the playbook or role root directory.

+
+ + Notes ----- -.. note:: - - Some devices need specific configurations to be enabled before scp can work These configuration should be pre-configured before using this module e.g ios - ``ip scp server enable``. - - User privilege to do scp on network device should be pre-configured e.g. ios - need user privilege 15 by default for allowing scp. - - Default destination of source file. - - This module is supported on ``ansible_network_os`` network platforms. See the :ref:`Network Platform Options ` for details. - +- Some devices need specific configurations to be enabled before scp can work These configuration should be pre-configured before using this module e.g ios - \ :literal:`ip scp server enable`\ . +- User privilege to do scp on network device should be pre-configured e.g. ios - need user privilege 15 by default for allowing scp. +- Default destination of source file. +- This module is supported on \ :literal:`ansible\_network\_os`\ network platforms. See the :ref:\`Network Platform Options \\` for details. Examples @@ -129,6 +142,7 @@ Examples .. code-block:: yaml + - name: copy file from ansible controller to a network device ansible.netcommon.net_put: src: running_cfg_ios1.txt @@ -142,11 +156,18 @@ Examples -Status ------- + Authors ~~~~~~~ - Deepak Agrawal (@dagrawal) + + + +Collection links +~~~~~~~~~~~~~~~~ + +* `Issue Tracker `__ +* `Repository (Sources) `__ diff --git a/docs/ansible.netcommon.netconf_config_module.rst b/docs/ansible.netcommon.netconf_config_module.rst index f2c836686..79a587b1f 100644 --- a/docs/ansible.netcommon.netconf_config_module.rst +++ b/docs/ansible.netcommon.netconf_config_module.rst @@ -1,14 +1,21 @@ -.. _ansible.netcommon.netconf_config_module: +.. Created with antsibull-docs 2.9.0 -******************************** -ansible.netcommon.netconf_config -******************************** +ansible.netcommon.netconf_config module -- netconf device configuration ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -**netconf device configuration** +This module is part of the `ansible.netcommon collection `_ (version 6.1.0). +It is not included in ``ansible-core``. +To check whether it is installed, run ``ansible-galaxy collection list``. -Version added: 1.0.0 +To install it, use: :code:`ansible-galaxy collection install ansible.netcommon`. +You need further requirements to be able to use this module, +see `Requirements `_ for details. + +To use it in a playbook, specify: ``ansible.netcommon.netconf_config``. + +New in ansible.netcommon 1.0.0 .. contents:: :local: @@ -17,11 +24,14 @@ Version added: 1.0.0 Synopsis -------- + - Netconf is a network management protocol developed and standardized by the IETF. It is documented in RFC 6241. - This module allows the user to send a configuration XML file to a netconf device, and detects if there was a configuration change. +.. _ansible_collections.ansible.netcommon.netconf_config_module_requirements: + Requirements ------------ The below requirements are needed on the host that executes this module. @@ -29,366 +39,361 @@ The below requirements are needed on the host that executes this module. - ncclient + + + + Parameters ---------- .. raw:: html - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ParameterChoices/DefaultsComments
-
- backup - -
- boolean -
- 		-
    Choices: -
  • no ←
    • -
  • yes
    • -
- 		-
This argument will cause the module to create a full backup of the current running-config from the remote device before any changes are made. If the backup_options value is not given, the backup file is written to the backup folder in the playbook root directory or role root directory, if playbook is part of an ansible role. If the directory does not exist, it is created.
-
-
- backup_options - -
- dictionary -
- 		- -
This is a dict object containing configurable options related to backup file path. The value of this option is read only when backup is set to yes, if backup is set to no this option will be silently ignored.
-
-
- dir_path - -
- path -
- 		- -
This option provides the path ending with directory name in which the backup configuration file will be stored. If the directory does not exist it will be first created and the filename is either the value of filename or default filename as described in filename options description. If the path value is not given in that case a backup directory will be created in the current working directory and backup configuration will be copied in filename within backup directory.
-
-
- filename - -
- string -
- 		- -
The filename to be used to store the backup configuration. If the filename is not given it will be generated based on the hostname, current time and date in format defined by <hostname>_config.<current-date>@<current-time>
-
-
- commit - -
- boolean -
- 		-
    Choices: -
  • no
    • -
  • yes ←
    • -
- 		-
This boolean flag controls if the configuration changes should be committed or not after editing the candidate datastore. This option is supported only if remote Netconf server supports :candidate capability. If the value is set to False commit won't be issued after edit-config operation and user needs to handle commit or discard-changes explicitly.
-
-
- confirm - -
- integer -
- 		- Default:
0
- 		-
This argument will configure a timeout value for the commit to be confirmed before it is automatically rolled back. If the confirm_commit argument is set to False, this argument is silently ignored. If the value of this argument is set to 0, the commit is confirmed immediately. The remote host MUST support :candidate and :confirmed-commit capability for this option to .
-
-
- confirm_commit - -
- boolean -
- 		-
    Choices: -
  • no ←
    • -
  • yes
    • -
- 		-
This argument will execute commit operation on remote device. It can be used to confirm a previous commit.
-
-
- content - -
- raw -
- 		- -
The configuration data as defined by the device's data models, the value can be either in xml string format or text format or python dictionary representation of JSON format.
-
In case of json string format it will be converted to the corresponding xml string using xmltodict library before pushing onto the remote host.
-
In case the value of this option isn text format the format should be supported by remote Netconf server.
-
If the value of content option is in xml format in that case the xml value should have config as root tag.
-

aliases: xml
-
-
- default_operation - -
- string -
- 		-
    Choices: -
  • merge
    • -
  • replace
    • -
  • none
    • -
- 		-
The default operation for <edit-config> rpc, valid values are merge, replace and none. If the default value is merge, the configuration data in the content option is merged at the corresponding level in the target datastore. If the value is replace the data in the content option completely replaces the configuration in the target datastore. If the value is none the target datastore is unaffected by the configuration in the config option, unless and until the incoming configuration data uses the operation operation to request a different operation.
-
-
- delete - -
- boolean -
- 		-
    Choices: -
  • no ←
    • -
  • yes
    • -
- 		-
It instructs the module to delete the configuration from value mentioned in target datastore.
-
-
- error_option - -
- string -
- 		-
    Choices: -
  • stop-on-error ←
    • -
  • continue-on-error
    • -
  • rollback-on-error
    • -
- 		-
This option controls the netconf server action after an error occurs while editing the configuration.
-
If error_option=stop-on-error, abort the config edit on first error.
-
If error_option=continue-on-error, continue to process configuration data on error. The error is recorded and negative response is generated if any errors occur.
-
If error_option=rollback-on-error, rollback to the original configuration if any error occurs. This requires the remote Netconf server to support the error_option=rollback-on-error capability.
-
-
- format - -
- string -
- 		-
    Choices: -
  • xml
    • -
  • text
    • -
  • json
    • -
- 		-
The format of the configuration provided as value of content.
-
In case of json string format it will be converted to the corresponding xml string using xmltodict library before pushing onto the remote host.
-
In case of text format of the configuration should be supported by remote Netconf server.
-
If the value of format options is not given it tries to guess the data format of content option as one of xml or json or text.
-
If the data format is not identified it is set to xml by default.
-
-
- get_filter - -
- raw -
- 		- -
This argument specifies the XML string which acts as a filter to restrict the portions of the data retrieved from the remote device when comparing the before and after state of the device following calls to edit_config. When not specified, the entire configuration or state data is returned for comparison depending on the value of source option. The get_filter value can be either XML string or XPath or JSON string or native python dictionary, if the filter is in XPath format the NETCONF server running on remote host should support xpath capability else it will result in an error.
-
-
- lock - -
- string -
- 		-
    Choices: -
  • never
    • -
  • always ←
    • -
  • if-supported
    • -
- 		-
Instructs the module to explicitly lock the datastore specified as target. By setting the option value always is will explicitly lock the datastore mentioned in target option. It the value is never it will not lock the target datastore. The value if-supported lock the target datastore only if it is supported by the remote Netconf server.
-
-
- save - -
- boolean -
- 		-
    Choices: -
  • no ←
    • -
  • yes
    • -
- 		-
The save argument instructs the module to save the configuration in target datastore to the startup-config if changed and if :startup capability is supported by Netconf server.
-
-
- source_datastore - -
- string -
- 		- -
Name of the configuration datastore to use as the source to copy the configuration to the datastore mentioned by target option. The values can be either running, candidate, startup or a remote URL
-

aliases: source
-
-
- target - -
- string -
- 		-
    Choices: -
  • auto ←
    • -
  • candidate
    • -
  • running
    • -
- 		-
Name of the configuration datastore to be edited. - auto, uses candidate and fallback to running - candidate, edit <candidate/> datastore and then commit - running, edit <running/> datastore directly
-

aliases: datastore
-
-
- validate - -
- boolean -
- 		-
    Choices: -
  • no ←
    • -
  • yes
    • -
- 		-
This boolean flag if set validates the content of datastore given in target option. For this option to work remote Netconf server should support :validate capability.
-
-
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Parameter

Comments

+
+

backup

+ +

+ boolean +

+ 		+

This argument will cause the module to create a full backup of the current running-config from the remote device before any changes are made. If the backup_options value is not given, the backup file is written to the backup folder in the playbook root directory or role root directory, if playbook is part of an ansible role. If the directory does not exist, it is created.

+

Choices:

+
    +

  • false ← (default)

    • +

  • true

    • +
+ +
+
+

backup_options

+ +

+ dictionary +

+ 		+

This is a dict object containing configurable options related to backup file path. The value of this option is read only when backup is set to yes, if backup is set to no this option will be silently ignored.

+
+
+

dir_path

+ +

+ path +

+ 		+

This option provides the path ending with directory name in which the backup configuration file will be stored. If the directory does not exist it will be first created and the filename is either the value of filename or default filename as described in filename options description. If the path value is not given in that case a backup directory will be created in the current working directory and backup configuration will be copied in filename within backup directory.

+
+
+

filename

+ +

+ string +

+ 		+

The filename to be used to store the backup configuration. If the filename is not given it will be generated based on the hostname, current time and date in format defined by <hostname>_config.<current-date>@<current-time>

+
+
+

commit

+ +

+ boolean +

+ 		+

This boolean flag controls if the configuration changes should be committed or not after editing the candidate datastore. This option is supported only if remote Netconf server supports :candidate capability. If the value is set to False commit won't be issued after edit-config operation and user needs to handle commit or discard-changes explicitly.

+

Choices:

+
    +

  • false

    • +

  • true ← (default)

    • +
+ +
+
+

confirm

+ +

+ integer +

+ 		+

This argument will configure a timeout value for the commit to be confirmed before it is automatically rolled back. If the confirm_commit argument is set to False, this argument is silently ignored. If the value of this argument is set to 0, the commit is confirmed immediately. The remote host MUST support :candidate and :confirmed-commit capability for this option to .

+

Default: 0

+
+
+

confirm_commit

+ +

+ boolean +

+ 		+

This argument will execute commit operation on remote device. It can be used to confirm a previous commit.

+

Choices:

+
    +

  • false ← (default)

    • +

  • true

    • +
+ +
+
+
+

content

+ +

aliases: xml

+

+ any +

+ 		+

The configuration data as defined by the device's data models, the value can be either in xml string format or text format or python dictionary representation of JSON format.

+

In case of json string format it will be converted to the corresponding xml string using xmltodict library before pushing onto the remote host.

+

In case the value of this option isn text format the format should be supported by remote Netconf server.

+

If the value of content option is in xml format in that case the xml value should have config as root tag.

+
+
+

default_operation

+ +

+ string +

+ 		+

The default operation for <edit-config> rpc, valid values are merge, replace and none. If the default value is merge, the configuration data in the content option is merged at the corresponding level in the target datastore. If the value is replace the data in the content option completely replaces the configuration in the target datastore. If the value is none the target datastore is unaffected by the configuration in the config option, unless and until the incoming configuration data uses the operation operation to request a different operation.

+

Choices:

+
    +

  • "merge"

    • +

  • "replace"

    • +

  • "none"

    • +
+ +
+
+

delete

+ +

+ boolean +

+ 		+

It instructs the module to delete the configuration from value mentioned in target datastore.

+

Choices:

+
    +

  • false ← (default)

    • +

  • true

    • +
+ +
+
+

error_option

+ +

+ string +

+ 		+

This option controls the netconf server action after an error occurs while editing the configuration.

+

If error_option=stop-on-error, abort the config edit on first error.

+

If error_option=continue-on-error, continue to process configuration data on error. The error is recorded and negative response is generated if any errors occur.

+

If error_option=rollback-on-error, rollback to the original configuration if any error occurs. This requires the remote Netconf server to support the error_option=rollback-on-error capability.

+

Choices:

+
    +

  • "stop-on-error" ← (default)

    • +

  • "continue-on-error"

    • +

  • "rollback-on-error"

    • +
+ +
+
+

format

+ +

+ string +

+ 		+

The format of the configuration provided as value of content.

+

In case of json string format it will be converted to the corresponding xml string using xmltodict library before pushing onto the remote host.

+

In case of text format of the configuration should be supported by remote Netconf server.

+

If the value of format options is not given it tries to guess the data format of content option as one of xml or json or text.

+

If the data format is not identified it is set to xml by default.

+

Choices:

+
    +

  • "xml"

    • +

  • "text"

    • +

  • "json"

    • +
+ +
+
+

get_filter

+ +

+ any +

+ 		+

This argument specifies the XML string which acts as a filter to restrict the portions of the data retrieved from the remote device when comparing the before and after state of the device following calls to edit_config. When not specified, the entire configuration or state data is returned for comparison depending on the value of source option. The get_filter value can be either XML string or XPath or JSON string or native python dictionary, if the filter is in XPath format the NETCONF server running on remote host should support xpath capability else it will result in an error.

+
+
+

lock

+ +

+ string +

+ 		+

Instructs the module to explicitly lock the datastore specified as target. By setting the option value always is will explicitly lock the datastore mentioned in target option. It the value is never it will not lock the target datastore. The value if-supported lock the target datastore only if it is supported by the remote Netconf server.

+

Choices:

+
    +

  • "never"

    • +

  • "always" ← (default)

    • +

  • "if-supported"

    • +
+ +
+
+

save

+ +

+ boolean +

+ 		+

The save argument instructs the module to save the configuration in target datastore to the startup-config if changed and if :startup capability is supported by Netconf server.

+

Choices:

+
    +

  • false ← (default)

    • +

  • true

    • +
+ +
+
+
+

source_datastore

+ +

aliases: source

+

+ string +

+ 		+

Name of the configuration datastore to use as the source to copy the configuration to the datastore mentioned by target option. The values can be either running, candidate, startup or a remote URL

+
+
+
+

target

+ +

aliases: datastore

+

+ string +

+ 		+

Name of the configuration datastore to be edited. - auto, uses candidate and fallback to running - candidate, edit <candidate/> datastore and then commit - running, edit <running/> datastore directly

+

Choices:

+
    +

  • "auto" ← (default)

    • +

  • "candidate"

    • +

  • "running"

    • +
+ +
+
+

validate

+ +

+ boolean +

+ 		+

This boolean flag if set validates the content of datastore given in target option. For this option to work remote Netconf server should support :validate capability.

+

Choices:

+
    +

  • false ← (default)

    • +

  • true

    • +
+ +
+ + Notes ----- -.. note:: - - This module requires the netconf system service be enabled on the remote device being managed. - - This module supports devices with and without the candidate and confirmed-commit capabilities. It will always use the safer feature. - - This module supports the use of connection=netconf - - This module is supported on ``ansible_network_os`` network platforms. See the :ref:`Network Platform Options ` for details. - +- This module requires the netconf system service be enabled on the remote device being managed. +- This module supports devices with and without the candidate and confirmed-commit capabilities. It will always use the safer feature. +- This module supports the use of connection=netconf +- This module is supported on \ :literal:`ansible\_network\_os`\ network platforms. See the :ref:\`Network Platform Options \\` for details. Examples @@ -396,6 +401,7 @@ Examples .. code-block:: yaml + - name: use lookup filter to provide xml configuration ansible.netcommon.netconf_config: content: "{{ lookup('file', './config.xml') }}" @@ -558,75 +564,72 @@ Examples + + Return Values ------------- -Common return values are documented `here `_, the following are the fields unique to this module: +The following are the fields unique to this module: .. raw:: html - - - - - - - - - - - - - - - - - - - - - -
KeyReturnedDescription
-
- backup_path - -
- string -
- 		when backup is yes -
The full path to the backup file
-
-
Sample:
-
/playbooks/ansible/backup/config.2016-07-16@22:28:34
-
-
- diff - -
- dictionary -
- 		when diff is enabled -
If --diff option in enabled while running, the before and after configuration change are returned as part of before and after key.
-
-
Sample:
-
{'after': '<rpc-reply> <data> <configuration> <version>17.3R1.10</version>...<--snip-->', 'before': '<rpc-reply> <data> <configuration> <version>17.3R1.10</version>...<--snip-->'}
-
-
- server_capabilities - -
- list -
- 		success -
list of capabilities of the server
-
-
Sample:
-
['urn:ietf:params:netconf:base:1.1', 'urn:ietf:params:netconf:capability:confirmed-commit:1.0', 'urn:ietf:params:netconf:capability:candidate:1.0']
-
-

- - -Status ------- + + + + + + + + + + + + + + + + + + + + + +

Key

Description

+
+

backup_path

+ +

+ string +

+ 		+

The full path to the backup file

+

Returned: when backup is yes

+

Sample: "/playbooks/ansible/backup/config.2016-07-16@22:28:34"

+
+
+

diff

+ +

+ dictionary +

+ 		+

If --diff option in enabled while running, the before and after configuration change are returned as part of before and after key.

+

Returned: when diff is enabled

+

Sample: {"after": "<rpc-reply> <data> <configuration> <version>17.3R1.10</version>...<--snip-->", "before": "<rpc-reply> <data> <configuration> <version>17.3R1.10</version>...<--snip-->"}

+
+
+

server_capabilities

+ +

+ list + / elements=string +

+ 		+

list of capabilities of the server

+

Returned: success

+

Sample: ["urn:ietf:params:netconf:base:1.1", "urn:ietf:params:netconf:capability:confirmed-commit:1.0", "urn:ietf:params:netconf:capability:candidate:1.0"]

+
+ + Authors @@ -634,3 +637,11 @@ Authors - Leandro Lisboa Penz (@lpenz) - Ganesh Nalawade (@ganeshrn) + + + +Collection links +~~~~~~~~~~~~~~~~ + +* `Issue Tracker `__ +* `Repository (Sources) `__ diff --git a/docs/ansible.netcommon.netconf_connection.rst b/docs/ansible.netcommon.netconf_connection.rst index 8761e4b67..f37bbd98b 100644 --- a/docs/ansible.netcommon.netconf_connection.rst +++ b/docs/ansible.netcommon.netconf_connection.rst @@ -1,14 +1,21 @@ -.. _ansible.netcommon.netconf_connection: +.. Created with antsibull-docs 2.9.0 -************************* -ansible.netcommon.netconf -************************* +ansible.netcommon.netconf connection -- Provides a persistent connection using the netconf protocol ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -**Provides a persistent connection using the netconf protocol** +This connection plugin is part of the `ansible.netcommon collection `_ (version 6.1.0). +It is not included in ``ansible-core``. +To check whether it is installed, run ``ansible-galaxy collection list``. -Version added: 1.0.0 +To install it, use: :code:`ansible-galaxy collection install ansible.netcommon`. +You need further requirements to be able to use this connection plugin, +see `Requirements `_ for details. + +To use it in a playbook, specify: ``ansible.netcommon.netconf``. + +New in ansible.netcommon 1.0.0 .. contents:: :local: @@ -17,359 +24,520 @@ Version added: 1.0.0 Synopsis -------- + - This connection plugin provides a connection to remote devices over the SSH NETCONF subsystem. This connection plugin is typically used by network devices for sending and receiving RPC calls over NETCONF. - Note this connection plugin requires ncclient to be installed on the local Ansible controller. +.. _ansible_collections.ansible.netcommon.netconf_connection_requirements: + Requirements ------------ -The below requirements are needed on the local Ansible controller node that executes this connection. +The below requirements are needed on the local controller node that executes this connection. - ncclient + + + + Parameters ---------- .. raw:: html - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ParameterChoices/DefaultsConfigurationComments
-
- host - -
- string -
- 		- Default:
"inventory_hostname"
- 		-
var: inventory_hostname
-
var: ansible_host
- 		-
Specifies the remote device FQDN or IP address to establish the SSH connection to.
-
-
- host_key_checking - -
- boolean -
- 		- Default:
"yes"
- 		-
ini entries: -

[defaults]
host_key_checking = yes

-

[paramiko_connection]
host_key_checking = yes

-
-
env:ANSIBLE_HOST_KEY_CHECKING
-
env:ANSIBLE_SSH_HOST_KEY_CHECKING
-
env:ANSIBLE_NETCONF_HOST_KEY_CHECKING
-
var: ansible_host_key_checking
-
var: ansible_ssh_host_key_checking
-
var: ansible_netconf_host_key_checking
- 		-
Set this to "False" if you want to avoid host key checking by the underlying tools Ansible uses to connect to the host
-
-
- import_modules - -
- boolean -
- 		- Default:
"yes"
- 		-
ini entries: -

[ansible_network]
import_modules = yes

-
-
env:ANSIBLE_NETWORK_IMPORT_MODULES
-
var: ansible_network_import_modules
- 		-
Reduce CPU usage and network module execution time by enabling direct execution. Instead of the module being packaged and executed by the shell, it will be directly executed by the Ansible control node using the same python interpreter as the Ansible process. Note- Incompatible with asynchronous mode. Note- Python 3 and Ansible 2.9.16 or greater required. Note- With Ansible 2.9.x fully qualified modules names are required in tasks.
-
-
- look_for_keys - -
- boolean -
- 		- Default:
"yes"
- 		-
ini entries: -

[paramiko_connection]
look_for_keys = yes

-
-
env:ANSIBLE_PARAMIKO_LOOK_FOR_KEYS
- 		-
Enables looking for ssh keys in the usual locations for ssh keys (e.g. :file:`~/.ssh/id_*`).
-
-
- netconf_ssh_config - -
- string -
- 		- -
ini entries: -

[netconf_connection]
ssh_config = VALUE

-
-
env:ANSIBLE_NETCONF_SSH_CONFIG
-
var: ansible_netconf_ssh_config
- 		-
This variable is used to enable bastion/jump host with netconf connection. If set to True the bastion/jump host ssh settings should be present in ~/.ssh/config file, alternatively it can be set to custom ssh configuration file path to read the bastion/jump host settings.
-
-
- network_os - -
- string -
- 		- -
var: ansible_network_os
- 		-
Configures the device platform network operating system. This value is used to load a device specific netconf plugin. If this option is not configured (or set to auto), then Ansible will attempt to guess the correct network_os to use. If it can not guess a network_os correctly it will use default.
-
-
- password - -
- string -
- 		- -
var: ansible_password
-
var: ansible_ssh_pass
-
var: ansible_ssh_password
-
var: ansible_netconf_password
- 		-
Configures the user password used to authenticate to the remote device when first establishing the SSH connection.
-
-
- persistent_command_timeout - -
- integer -
- 		- Default:
30
- 		-
ini entries: -

[persistent_connection]
command_timeout = 30

-
-
env:ANSIBLE_PERSISTENT_COMMAND_TIMEOUT
-
var: ansible_command_timeout
- 		-
Configures, in seconds, the amount of time to wait for a command to return from the remote device. If this timer is exceeded before the command returns, the connection plugin will raise an exception and close.
-
-
- persistent_connect_timeout - -
- integer -
- 		- Default:
30
- 		-
ini entries: -

[persistent_connection]
connect_timeout = 30

-
-
env:ANSIBLE_PERSISTENT_CONNECT_TIMEOUT
-
var: ansible_connect_timeout
- 		-
Configures, in seconds, the amount of time to wait when trying to initially establish a persistent connection. If this value expires before the connection to the remote device is completed, the connection will fail.
-
-
- persistent_log_messages - -
- boolean -
- 		- Default:
"no"
- 		-
ini entries: -

[persistent_connection]
log_messages = no

-
-
env:ANSIBLE_PERSISTENT_LOG_MESSAGES
-
var: ansible_persistent_log_messages
- 		-
This flag will enable logging the command executed and response received from target device in the ansible log file. For this option to work 'log_path' ansible configuration option is required to be set to a file path with write access.
-
Be sure to fully understand the security implications of enabling this option as it could create a security vulnerability by logging sensitive information in log file.
-
-
- port - -
- integer -
- 		- Default:
830
- 		-
ini entries: -

[defaults]
remote_port = 830

-
-
env:ANSIBLE_REMOTE_PORT
-
var: ansible_port
- 		-
Specifies the port on the remote device that listens for connections when establishing the SSH connection.
-
-
- private_key_file - -
- string -
- 		- -
ini entries: -

[defaults]
private_key_file = VALUE

-
-
env:ANSIBLE_PRIVATE_KEY_FILE
-
var: ansible_private_key_file
- 		-
The private SSH key or certificate file used to authenticate to the remote device when first establishing the SSH connection.
-
-
- proxy_command - -
- string -
- 		- Default:
""
- 		-
ini entries: -

[paramiko_connection]
proxy_command =

-
-
env:ANSIBLE_NETCONF_PROXY_COMMAND
-
var: ansible_paramiko_proxy_command
-
var: ansible_netconf_proxy_command
- 		-
Proxy information for running the connection via a jumphost.
-
This requires ncclient >= 0.6.10 to be installed on the controller.
-
-
- remote_user - -
- string -
- 		- -
ini entries: -

[defaults]
remote_user = VALUE

-
-
env:ANSIBLE_REMOTE_USER
-
var: ansible_user
- 		-
The username used to authenticate to the remote device when the SSH connection is first established. If the remote_user is not specified, the connection will use the username of the logged in user.
-
Can be configured from the CLI via the --user or -u options.
-
-
- - - - - - - - -Status ------- + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Parameter

Comments

+
+

host

+ +

+ string +

+ + 		+

Specifies the remote device FQDN or IP address to establish the SSH connection to.

+

Default: "inventory_hostname"

+

Configuration:

+
    +
  • +

    Variable: inventory_hostname

    + +
    • +
  • +

    Variable: ansible_host

    + +
    • +
+
+
+

host_key_checking

+ +

+ boolean +

+ + 		+

Set this to "False" if you want to avoid host key checking by the underlying tools Ansible uses to connect to the host

+

Choices:

+
    +

  • false

    • +

  • true ← (default)

    • +
+ +

Configuration:

+
    +
  • +

    INI entries

    + 
    [defaults]
+  host_key_checking = true
    + + 
    [paramiko_connection]
+  host_key_checking = true
    + +
    • +
  • +

    Environment variable: ANSIBLE_HOST_KEY_CHECKING

    + +
    • +
  • +

    Environment variable: ANSIBLE_SSH_HOST_KEY_CHECKING

    + +
    • +
  • +

    Environment variable: ANSIBLE_NETCONF_HOST_KEY_CHECKING

    + +
    • +
  • +

    Variable: ansible_host_key_checking

    + +
    • +
  • +

    Variable: ansible_ssh_host_key_checking

    + +
    • +
  • +

    Variable: ansible_netconf_host_key_checking

    + +
    • +
+
+
+

import_modules

+ +

+ boolean +

+ + 		+

Reduce CPU usage and network module execution time by enabling direct execution. Instead of the module being packaged and executed by the shell, it will be directly executed by the Ansible control node using the same python interpreter as the Ansible process. Note- Incompatible with asynchronous mode. Note- Python 3 and Ansible 2.9.16 or greater required. Note- With Ansible 2.9.x fully qualified modules names are required in tasks.

+

Choices:

+
    +

  • false

    • +

  • true ← (default)

    • +
+ +

Configuration:

+
    +
  • +

    INI entry

    + 
    [ansible_network]
+  import_modules = true
    + +
    • +
  • +

    Environment variable: ANSIBLE_NETWORK_IMPORT_MODULES

    + +
    • +
  • +

    Variable: ansible_network_import_modules

    + +
    • +
+
+
+

look_for_keys

+ +

+ boolean +

+ + 		+

Enables looking for ssh keys in the usual locations for ssh keys (e.g. :file:`~/.ssh/id_*`).

+

Choices:

+
    +

  • false

    • +

  • true ← (default)

    • +
+ +

Configuration:

+
    +
  • +

    INI entry

    + 
    [paramiko_connection]
+  look_for_keys = true
    + +
    • +
  • +

    Environment variable: ANSIBLE_PARAMIKO_LOOK_FOR_KEYS

    + +
    • +
+
+
+

netconf_ssh_config

+ +

+ string +

+ + 		+

This variable is used to enable bastion/jump host with netconf connection. If set to True the bastion/jump host ssh settings should be present in ~/.ssh/config file, alternatively it can be set to custom ssh configuration file path to read the bastion/jump host settings.

+

Configuration:

+
    +
  • +

    INI entry

    + 
    [netconf_connection]
+  ssh_config = VALUE
    + +
    • +
  • +

    Environment variable: ANSIBLE_NETCONF_SSH_CONFIG

    + +
    • +
  • +

    Variable: ansible_netconf_ssh_config

    + +
    • +
+
+
+

network_os

+ +

+ string +

+ + 		+

Configures the device platform network operating system. This value is used to load a device specific netconf plugin. If this option is not configured (or set to auto), then Ansible will attempt to guess the correct network_os to use. If it can not guess a network_os correctly it will use default.

+

Configuration:

+
    +
  • +

    Variable: ansible_network_os

    + +
    • +
+
+
+

password

+ +

+ string +

+ + 		+

Configures the user password used to authenticate to the remote device when first establishing the SSH connection.

+

Configuration:

+
    +
  • +

    Variable: ansible_password

    + +
    • +
  • +

    Variable: ansible_ssh_pass

    + +
    • +
  • +

    Variable: ansible_ssh_password

    + +
    • +
  • +

    Variable: ansible_netconf_password

    + +
    • +
+
+
+

persistent_command_timeout

+ +

+ integer +

+ + 		+

Configures, in seconds, the amount of time to wait for a command to return from the remote device. If this timer is exceeded before the command returns, the connection plugin will raise an exception and close.

+

Default: 30

+

Configuration:

+
    +
  • +

    INI entry

    + 
    [persistent_connection]
+  command_timeout = 30
    + +
    • +
  • +

    Environment variable: ANSIBLE_PERSISTENT_COMMAND_TIMEOUT

    + +
    • +
  • +

    Variable: ansible_command_timeout

    + +
    • +
+
+
+

persistent_connect_timeout

+ +

+ integer +

+ + 		+

Configures, in seconds, the amount of time to wait when trying to initially establish a persistent connection. If this value expires before the connection to the remote device is completed, the connection will fail.

+

Default: 30

+

Configuration:

+
    +
  • +

    INI entry

    + 
    [persistent_connection]
+  connect_timeout = 30
    + +
    • +
  • +

    Environment variable: ANSIBLE_PERSISTENT_CONNECT_TIMEOUT

    + +
    • +
  • +

    Variable: ansible_connect_timeout

    + +
    • +
+
+
+

persistent_log_messages

+ +

+ boolean +

+ + 		+

This flag will enable logging the command executed and response received from target device in the ansible log file. For this option to work 'log_path' ansible configuration option is required to be set to a file path with write access.

+

Be sure to fully understand the security implications of enabling this option as it could create a security vulnerability by logging sensitive information in log file.

+

Choices:

+
    +

  • false ← (default)

    • +

  • true

    • +
+ +

Configuration:

+
    +
  • +

    INI entry

    + 
    [persistent_connection]
+  log_messages = false
    + +
    • +
  • +

    Environment variable: ANSIBLE_PERSISTENT_LOG_MESSAGES

    + +
    • +
  • +

    Variable: ansible_persistent_log_messages

    + +
    • +
+
+
+

port

+ +

+ integer +

+ + 		+

Specifies the port on the remote device that listens for connections when establishing the SSH connection.

+

Default: 830

+

Configuration:

+
    +
  • +

    INI entry

    + 
    [defaults]
+  remote_port = 830
    + +
    • +
  • +

    Environment variable: ANSIBLE_REMOTE_PORT

    + +
    • +
  • +

    Variable: ansible_port

    + +
    • +
+
+
+

private_key_file

+ +

+ string +

+ + 		+

The private SSH key or certificate file used to authenticate to the remote device when first establishing the SSH connection.

+

Configuration:

+
    +
  • +

    INI entry

    + 
    [defaults]
+  private_key_file = VALUE
    + +
    • +
  • +

    Environment variable: ANSIBLE_PRIVATE_KEY_FILE

    + +
    • +
  • +

    Variable: ansible_private_key_file

    + +
    • +
+
+
+

proxy_command

+ +

+ string +

+ + 		+

Proxy information for running the connection via a jumphost.

+

This requires ncclient >= 0.6.10 to be installed on the controller.

+

Default: ""

+

Configuration:

+
    +
  • +

    INI entry

    + 
    [paramiko_connection]
+  proxy_command = ""
    + +
    • +
  • +

    Environment variable: ANSIBLE_NETCONF_PROXY_COMMAND

    + +
    • +
  • +

    Variable: ansible_paramiko_proxy_command

    + +
    • +
  • +

    Variable: ansible_netconf_proxy_command

    + +
    • +
+
+
+

remote_user

+ +

+ string +

+ + 		+

The username used to authenticate to the remote device when the SSH connection is first established. If the remote_user is not specified, the connection will use the username of the logged in user.

+

Can be configured from the CLI via the --user or -u options.

+

Configuration:

+
    +
  • +

    INI entry

    + 
    [defaults]
+  remote_user = VALUE
    + +
    • +
  • +

    Environment variable: ANSIBLE_REMOTE_USER

    + +
    • +
  • +

    Variable: ansible_user

    + +
    • +
+
+ + + + + + + + + Authors @@ -380,3 +548,9 @@ Authors .. hint:: Configuration entries for each entry type have a low to high priority order. For example, a variable that is lower in the list will override a variable that is higher up. + +Collection links +~~~~~~~~~~~~~~~~ + +* `Issue Tracker `__ +* `Repository (Sources) `__ diff --git a/docs/ansible.netcommon.netconf_get_module.rst b/docs/ansible.netcommon.netconf_get_module.rst index 69edcec5d..c3aac61be 100644 --- a/docs/ansible.netcommon.netconf_get_module.rst +++ b/docs/ansible.netcommon.netconf_get_module.rst @@ -1,14 +1,21 @@ -.. _ansible.netcommon.netconf_get_module: +.. Created with antsibull-docs 2.9.0 -***************************** -ansible.netcommon.netconf_get -***************************** +ansible.netcommon.netconf_get module -- Fetch configuration/state data from NETCONF enabled network devices. +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -**Fetch configuration/state data from NETCONF enabled network devices.** +This module is part of the `ansible.netcommon collection `_ (version 6.1.0). +It is not included in ``ansible-core``. +To check whether it is installed, run ``ansible-galaxy collection list``. -Version added: 1.0.0 +To install it, use: :code:`ansible-galaxy collection install ansible.netcommon`. +You need further requirements to be able to use this module, +see `Requirements `_ for details. + +To use it in a playbook, specify: ``ansible.netcommon.netconf_get``. + +New in ansible.netcommon 1.0.0 .. contents:: :local: @@ -17,119 +24,126 @@ Version added: 1.0.0 Synopsis -------- + - NETCONF is a network management protocol developed and standardized by the IETF. It is documented in RFC 6241. - This module allows the user to fetch configuration and state data from NETCONF enabled network devices. +.. _ansible_collections.ansible.netcommon.netconf_get_module_requirements: + Requirements ------------ The below requirements are needed on the host that executes this module. -- ncclient (>=v0.5.2) +- ncclient (\>=v0.5.2) - jxmlease (for display=json) - xmltodict (for display=native) + + + + Parameters ---------- .. raw:: html - - - - - - - - - - - - - - - - - - - - - - - - - - -
ParameterChoices/DefaultsComments
-
- display - -
- string -
- 		-
    Choices: -
  • json
    • -
  • pretty
    • -
  • xml
    • -
  • native
    • -
- 		-
Encoding scheme to use when serializing output from the device. The option json will serialize the output as JSON data. If the option value is json it requires jxmlease to be installed on control node. The option pretty is similar to received XML response but is using human readable format (spaces, new lines). The option value xml is similar to received XML response but removes all XML namespaces.
-
-
- filter - -
- raw -
- 		- -
This argument specifies the string which acts as a filter to restrict the portions of the data to be are retrieved from the remote device. If this option is not specified entire configuration or state data is returned in result depending on the value of source option. The filter value can be either XML string or XPath or JSON string or native python dictionary, if the filter is in XPath format the NETCONF server running on remote host should support xpath capability else it will result in an error. If the filter is in JSON format the xmltodict library should be installed on the control node for JSON to XML conversion.
-
-
- lock - -
- string -
- 		-
    Choices: -
  • never ←
    • -
  • always
    • -
  • if-supported
    • -
- 		-
Instructs the module to explicitly lock the datastore specified as source. If no source is defined, the running datastore will be locked. By setting the option value always is will explicitly lock the datastore mentioned in source option. By setting the option value never it will not lock the source datastore. The value if-supported allows better interworking with NETCONF servers, which do not support the (un)lock operation for all supported datastores.
-
-
- source - -
- string -
- 		-
    Choices: -
  • running
    • -
  • candidate
    • -
  • startup
    • -
- 		-
This argument specifies the datastore from which configuration data should be fetched. Valid values are running, candidate and startup. If the source value is not set both configuration and state information are returned in response from running datastore.
-
-
+ + + + + + + + + + + + + + + + + + + + + + + + + +

Parameter

Comments

+
+

display

+ +

+ string +

+ 		+

Encoding scheme to use when serializing output from the device. The option json will serialize the output as JSON data. If the option value is json it requires jxmlease to be installed on control node. The option pretty is similar to received XML response but is using human readable format (spaces, new lines). The option value xml is similar to received XML response but removes all XML namespaces.

+

Choices:

+
    +

  • "json"

    • +

  • "pretty"

    • +

  • "xml"

    • +

  • "native"

    • +
+ +
+
+

filter

+ +

+ any +

+ 		+

This argument specifies the string which acts as a filter to restrict the portions of the data to be are retrieved from the remote device. If this option is not specified entire configuration or state data is returned in result depending on the value of source option. The filter value can be either XML string or XPath or JSON string or native python dictionary, if the filter is in XPath format the NETCONF server running on remote host should support xpath capability else it will result in an error. If the filter is in JSON format the xmltodict library should be installed on the control node for JSON to XML conversion.

+
+
+

lock

+ +

+ string +

+ 		+

Instructs the module to explicitly lock the datastore specified as source. If no source is defined, the running datastore will be locked. By setting the option value always is will explicitly lock the datastore mentioned in source option. By setting the option value never it will not lock the source datastore. The value if-supported allows better interworking with NETCONF servers, which do not support the (un)lock operation for all supported datastores.

+

Choices:

+
    +

  • "never" ← (default)

    • +

  • "always"

    • +

  • "if-supported"

    • +
+ +
+
+

source

+ +

+ string +

+ 		+

This argument specifies the datastore from which configuration data should be fetched. Valid values are running, candidate and startup. If the source value is not set both configuration and state information are returned in response from running datastore.

+

Choices:

+
    +

  • "running"

    • +

  • "candidate"

    • +

  • "startup"

    • +
+ +
+ + Notes ----- -.. note:: - - This module requires the NETCONF system service be enabled on the remote device being managed. - - This module supports the use of connection=netconf - - This module is supported on ``ansible_network_os`` network platforms. See the :ref:`Network Platform Options ` for details. - +- This module requires the NETCONF system service be enabled on the remote device being managed. +- This module supports the use of connection=netconf +- This module is supported on \ :literal:`ansible\_network\_os`\ network platforms. See the :ref:\`Network Platform Options \\` for details. Examples @@ -137,6 +151,7 @@ Examples .. code-block:: yaml + - name: Get running configuration and state data ansible.netcommon.netconf_get: @@ -285,90 +300,87 @@ Examples + + Return Values ------------- -Common return values are documented `here `_, the following are the fields unique to this module: +The following are the fields unique to this module: .. raw:: html - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
KeyReturnedDescription
-
- output - -
- complex -
- 		If the display format is selected as json it is returned as dict type and the conversion is done using jxmlease python library. If the display format is selected as native it is returned as dict type and the conversion is done using xmltodict python library. If the display format is xml or pretty it is returned as a string apart from low-level errors (such as action plugin). -
Based on the value of display option will return either the set of transformed XML to JSON format from the RPC response with type dict or pretty XML string response (human-readable) or response with namespace removed from XML string.
-
-
  -
- formatted_output - -
- string -
- 		-
Contains formatted response received from remote host as per the value in display format.
-
-
-
- stdout - -
- string -
- 		always apart from low-level errors (such as action plugin) -
The raw XML string containing configuration or state data received from the underlying ncclient library.
-
-
Sample:
-
...
-
-
- stdout_lines - -
- list -
- 		always apart from low-level errors (such as action plugin) -
The value of stdout split into a list
-
-
Sample:
-
['...', '...']
-
-

- - -Status ------- + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Key

Description

+
+

output

+ +

+ complex +

+ 		+

Based on the value of display option will return either the set of transformed XML to JSON format from the RPC response with type dict or pretty XML string response (human-readable) or response with namespace removed from XML string.

+

Returned: If the display format is selected as json it is returned as dict type and the conversion is done using jxmlease python library. If the display format is selected as native it is returned as dict type and the conversion is done using xmltodict python library. If the display format is xml or pretty it is returned as a string apart from low-level errors (such as action plugin).

+
+
+

formatted_output

+ +

+ string +

+ 		+

Contains formatted response received from remote host as per the value in display format.

+

Returned: success

+
+
+

stdout

+ +

+ string +

+ 		+

The raw XML string containing configuration or state data received from the underlying ncclient library.

+

Returned: always apart from low-level errors (such as action plugin)

+

Sample: "..."

+
+
+

stdout_lines

+ +

+ list + / elements=string +

+ 		+

The value of stdout split into a list

+

Returned: always apart from low-level errors (such as action plugin)

+

Sample: ["...", "..."]

+
+ + Authors @@ -376,3 +388,11 @@ Authors - Ganesh Nalawade (@ganeshrn) - Sven Wisotzky (@wisotzky) + + + +Collection links +~~~~~~~~~~~~~~~~ + +* `Issue Tracker `__ +* `Repository (Sources) `__ diff --git a/docs/ansible.netcommon.netconf_rpc_module.rst b/docs/ansible.netcommon.netconf_rpc_module.rst index ace497141..70f788e77 100644 --- a/docs/ansible.netcommon.netconf_rpc_module.rst +++ b/docs/ansible.netcommon.netconf_rpc_module.rst @@ -1,14 +1,21 @@ -.. _ansible.netcommon.netconf_rpc_module: +.. Created with antsibull-docs 2.9.0 -***************************** -ansible.netcommon.netconf_rpc -***************************** +ansible.netcommon.netconf_rpc module -- Execute operations on NETCONF enabled network devices. +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -**Execute operations on NETCONF enabled network devices.** +This module is part of the `ansible.netcommon collection `_ (version 6.1.0). +It is not included in ``ansible-core``. +To check whether it is installed, run ``ansible-galaxy collection list``. -Version added: 1.0.0 +To install it, use: :code:`ansible-galaxy collection install ansible.netcommon`. +You need further requirements to be able to use this module, +see `Requirements `_ for details. + +To use it in a playbook, specify: ``ansible.netcommon.netconf_rpc``. + +New in ansible.netcommon 1.0.0 .. contents:: :local: @@ -17,109 +24,112 @@ Version added: 1.0.0 Synopsis -------- + - NETCONF is a network management protocol developed and standardized by the IETF. It is documented in RFC 6241. - This module allows the user to execute NETCONF RPC requests as defined by IETF RFC standards as well as proprietary requests. +.. _ansible_collections.ansible.netcommon.netconf_rpc_module_requirements: + Requirements ------------ The below requirements are needed on the host that executes this module. -- ncclient (>=v0.5.2) +- ncclient (\>=v0.5.2) - jxmlease + + + + Parameters ---------- .. raw:: html - - - - - - - - - - - - - - - - - - - - - - - - - - -
ParameterChoices/DefaultsComments
-
- content - -
- string -
- 		- -
This argument specifies the optional request content (all RPC attributes). The content value can either be provided as XML formatted string or as dictionary.
-
-
- display - -
- string -
- 		-
    Choices: -
  • json
    • -
  • pretty
    • -
  • xml
    • -
- 		-
Encoding scheme to use when serializing output from the device. The option json will serialize the output as JSON data. If the option value is json it requires jxmlease to be installed on control node. The option pretty is similar to received XML response but is using human readable format (spaces, new lines). The option value xml is similar to received XML response but removes all XML namespaces.
-
-
- rpc - -
- string - / required -
- 		- -
This argument specifies the request (name of the operation) to be executed on the remote NETCONF enabled device.
-
-
- xmlns - -
- string -
- 		- -
NETCONF operations not defined in rfc6241 typically require the appropriate XML namespace to be set. In the case the request option is not already provided in XML format, the namespace can be defined by the xmlns option.
-
-
+ + + + + + + + + + + + + + + + + + + + + + + + + +

Parameter

Comments

+
+

content

+ +

+ string +

+ 		+

This argument specifies the optional request content (all RPC attributes). The content value can either be provided as XML formatted string or as dictionary.

+
+
+

display

+ +

+ string +

+ 		+

Encoding scheme to use when serializing output from the device. The option json will serialize the output as JSON data. If the option value is json it requires jxmlease to be installed on control node. The option pretty is similar to received XML response but is using human readable format (spaces, new lines). The option value xml is similar to received XML response but removes all XML namespaces.

+

Choices:

+
    +

  • "json"

    • +

  • "pretty"

    • +

  • "xml"

    • +
+ +
+
+

rpc

+ +

+ string + / required +

+ 		+

This argument specifies the request (name of the operation) to be executed on the remote NETCONF enabled device.

+
+
+

xmlns

+ +

+ string +

+ 		+

NETCONF operations not defined in rfc6241 typically require the appropriate XML namespace to be set. In the case the request option is not already provided in XML format, the namespace can be defined by the xmlns option.

+
+ + Notes ----- -.. note:: - - This module requires the NETCONF system service be enabled on the remote device being managed. - - This module supports the use of connection=netconf - - To execute ``get-config``, ``get`` or ``edit-config`` requests it is recommended to use the Ansible *netconf_get* and *netconf_config* modules. - - This module is supported on ``ansible_network_os`` network platforms. See the :ref:`Network Platform Options ` for details. - +- This module requires the NETCONF system service be enabled on the remote device being managed. +- This module supports the use of connection=netconf +- To execute \ :literal:`get-config`\ , \ :literal:`get`\ or \ :literal:`edit-config`\ requests it is recommended to use the Ansible \ :emphasis:`netconf\_get`\ and \ :emphasis:`netconf\_config`\ modules. +- This module is supported on \ :literal:`ansible\_network\_os`\ network platforms. See the :ref:\`Network Platform Options \\` for details. Examples @@ -127,6 +137,7 @@ Examples .. code-block:: yaml + - name: lock candidate ansible.netcommon.netconf_rpc: rpc: lock @@ -183,90 +194,87 @@ Examples + + Return Values ------------- -Common return values are documented `here `_, the following are the fields unique to this module: +The following are the fields unique to this module: .. raw:: html - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
KeyReturnedDescription
-
- output - -
- complex -
- 		when the display format is selected as JSON it is returned as dict type, if the display format is xml or pretty pretty it is returned as a string apart from low-level errors (such as action plugin). -
Based on the value of display option will return either the set of transformed XML to JSON format from the RPC response with type dict or pretty XML string response (human-readable) or response with namespace removed from XML string.
-
-
  -
- formatted_output - -
- string -
- 		-
Contains formatted response received from remote host as per the value in display format.
-
-
-
- stdout - -
- string -
- 		always apart from low-level errors (such as action plugin) -
The raw XML string containing configuration or state data received from the underlying ncclient library.
-
-
Sample:
-
...
-
-
- stdout_lines - -
- list -
- 		always apart from low-level errors (such as action plugin) -
The value of stdout split into a list
-
-
Sample:
-
['...', '...']
-
-

- - -Status ------- + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Key

Description

+
+

output

+ +

+ complex +

+ 		+

Based on the value of display option will return either the set of transformed XML to JSON format from the RPC response with type dict or pretty XML string response (human-readable) or response with namespace removed from XML string.

+

Returned: when the display format is selected as JSON it is returned as dict type, if the display format is xml or pretty pretty it is returned as a string apart from low-level errors (such as action plugin).

+
+
+

formatted_output

+ +

+ string +

+ 		+

Contains formatted response received from remote host as per the value in display format.

+

Returned: success

+
+
+

stdout

+ +

+ string +

+ 		+

The raw XML string containing configuration or state data received from the underlying ncclient library.

+

Returned: always apart from low-level errors (such as action plugin)

+

Sample: "..."

+
+
+

stdout_lines

+ +

+ list + / elements=string +

+ 		+

The value of stdout split into a list

+

Returned: always apart from low-level errors (such as action plugin)

+

Sample: ["...", "..."]

+
+ + Authors @@ -274,3 +282,11 @@ Authors - Ganesh Nalawade (@ganeshrn) - Sven Wisotzky (@wisotzky) + + + +Collection links +~~~~~~~~~~~~~~~~ + +* `Issue Tracker `__ +* `Repository (Sources) `__ diff --git a/docs/ansible.netcommon.network_cli_connection.rst b/docs/ansible.netcommon.network_cli_connection.rst index 35250272d..ab1204237 100644 --- a/docs/ansible.netcommon.network_cli_connection.rst +++ b/docs/ansible.netcommon.network_cli_connection.rst @@ -1,14 +1,21 @@ -.. _ansible.netcommon.network_cli_connection: +.. Created with antsibull-docs 2.9.0 -***************************** -ansible.netcommon.network_cli -***************************** +ansible.netcommon.network_cli connection -- Use network\_cli to run command on network appliances ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -**Use network_cli to run command on network appliances** +This connection plugin is part of the `ansible.netcommon collection `_ (version 6.1.0). +It is not included in ``ansible-core``. +To check whether it is installed, run ``ansible-galaxy collection list``. -Version added: 1.0.0 +To install it, use: :code:`ansible-galaxy collection install ansible.netcommon`. +You need further requirements to be able to use this connection plugin, +see `Requirements `_ for details. + +To use it in a playbook, specify: ``ansible.netcommon.network_cli``. + +New in ansible.netcommon 1.0.0 .. contents:: :local: @@ -17,15 +24,22 @@ Version added: 1.0.0 Synopsis -------- + - This connection plugin provides a connection to remote devices over the SSH and implements a CLI shell. This connection plugin is typically used by network devices for sending and receiving CLi commands to network devices. +.. _ansible_collections.ansible.netcommon.network_cli_connection_requirements: + Requirements ------------ -The below requirements are needed on the local Ansible controller node that executes this connection. +The below requirements are needed on the local controller node that executes this connection. + +- ansible-pylibssh if using \ :emphasis:`ssh\_type=libssh`\ + + + -- ansible-pylibssh if using *ssh_type=libssh* Parameters @@ -33,601 +47,826 @@ Parameters .. raw:: html - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ParameterChoices/DefaultsConfigurationComments
-
- become - -
- boolean -
- 		- Default:
"no"
- 		-
ini entries: -

[privilege_escalation]
become = no

-
-
env:ANSIBLE_BECOME
-
var: ansible_become
- 		-
The become option will instruct the CLI session to attempt privilege escalation on platforms that support it. Normally this means transitioning from user mode to enable mode in the CLI session. If become is set to True and the remote device does not support privilege escalation or the privilege has already been elevated, then this option is silently ignored.
-
Can be configured from the CLI via the --become or -b options.
-
-
- become_errors - -
- string -
- 		-
    Choices: -
  • ignore
    • -
  • warn
    • -
  • fail ←
    • -
- 		-
var: ansible_network_become_errors
- 		-
This option determines how privilege escalation failures are handled when become is enabled.
-
When set to ignore, the errors are silently ignored. When set to warn, a warning message is displayed. The default option fail, triggers a failure and halts execution.
-
-
- become_method - -
- string -
- 		- Default:
"sudo"
- 		-
ini entries: -

[privilege_escalation]
become_method = sudo

-
-
env:ANSIBLE_BECOME_METHOD
-
var: ansible_become_method
- 		-
This option allows the become method to be specified in for handling privilege escalation. Typically the become_method value is set to enable but could be defined as other values.
-
-
- host - -
- string -
- 		- Default:
"inventory_hostname"
- 		-
var: inventory_hostname
-
var: ansible_host
- 		-
Specifies the remote device FQDN or IP address to establish the SSH connection to.
-
-
- host_key_auto_add - -
- boolean -
- 		- Default:
"no"
- 		-
ini entries: -

[paramiko_connection]
host_key_auto_add = no

-
-
env:ANSIBLE_HOST_KEY_AUTO_ADD
- 		-
By default, Ansible will prompt the user before adding SSH keys to the known hosts file. Since persistent connections such as network_cli run in background processes, the user will never be prompted. By enabling this option, unknown host keys will automatically be added to the known hosts file.
-
Be sure to fully understand the security implications of enabling this option on production systems as it could create a security vulnerability.
-
-
- host_key_checking - -
- boolean -
- 		- Default:
"yes"
- 		-
ini entries: -

[defaults]
host_key_checking = yes

-

[persistent_connection]
host_key_checking = yes

-
-
env:ANSIBLE_HOST_KEY_CHECKING
-
env:ANSIBLE_SSH_HOST_KEY_CHECKING
-
var: ansible_host_key_checking
-
var: ansible_ssh_host_key_checking
- 		-
Set this to "False" if you want to avoid host key checking by the underlying tools Ansible uses to connect to the host
-
-
- import_modules - -
- boolean -
- 		- Default:
"yes"
- 		-
ini entries: -

[ansible_network]
import_modules = yes

-
-
env:ANSIBLE_NETWORK_IMPORT_MODULES
-
var: ansible_network_import_modules
- 		-
Reduce CPU usage and network module execution time by enabling direct execution. Instead of the module being packaged and executed by the shell, it will be directly executed by the Ansible control node using the same python interpreter as the Ansible process. Note- Incompatible with asynchronous mode. Note- Python 3 and Ansible 2.9.16 or greater required. Note- With Ansible 2.9.x fully qualified modules names are required in tasks.
-
-
- network_cli_retries - -
- integer -
- 		- Default:
3
- 		-
ini entries: -

[persistent_connection]
network_cli_retries = 3

-
-
env:ANSIBLE_NETWORK_CLI_RETRIES
-
var: ansible_network_cli_retries
- 		-
Number of attempts to connect to remote host. The delay time between the retires increases after every attempt by power of 2 in seconds till either the maximum attempts are exhausted or any of the persistent_command_timeout or persistent_connect_timeout timers are triggered.
-
-
- network_os - -
- string -
- 		- -
var: ansible_network_os
- 		-
Configures the device platform network operating system. This value is used to load the correct terminal and cliconf plugins to communicate with the remote device.
-
-
- password - -
- string -
- 		- -
var: ansible_password
-
var: ansible_ssh_pass
-
var: ansible_ssh_password
- 		-
Configures the user password used to authenticate to the remote device when first establishing the SSH connection.
-
-
- persistent_buffer_read_timeout - -
- float -
- 		- Default:
0.1
- 		-
ini entries: -

[persistent_connection]
buffer_read_timeout = 0.1

-
-
env:ANSIBLE_PERSISTENT_BUFFER_READ_TIMEOUT
-
var: ansible_buffer_read_timeout
- 		-
Configures, in seconds, the amount of time to wait for the data to be read from Paramiko channel after the command prompt is matched. This timeout value ensures that command prompt matched is correct and there is no more data left to be received from remote host.
-
-
- persistent_command_timeout - -
- integer -
- 		- Default:
30
- 		-
ini entries: -

[persistent_connection]
command_timeout = 30

-
-
env:ANSIBLE_PERSISTENT_COMMAND_TIMEOUT
-
var: ansible_command_timeout
- 		-
Configures, in seconds, the amount of time to wait for a command to return from the remote device. If this timer is exceeded before the command returns, the connection plugin will raise an exception and close.
-
-
- persistent_connect_timeout - -
- integer -
- 		- Default:
30
- 		-
ini entries: -

[persistent_connection]
connect_timeout = 30

-
-
env:ANSIBLE_PERSISTENT_CONNECT_TIMEOUT
-
var: ansible_connect_timeout
- 		-
Configures, in seconds, the amount of time to wait when trying to initially establish a persistent connection. If this value expires before the connection to the remote device is completed, the connection will fail.
-
-
- persistent_log_messages - -
- boolean -
- 		- Default:
"no"
- 		-
ini entries: -

[persistent_connection]
log_messages = no

-
-
env:ANSIBLE_PERSISTENT_LOG_MESSAGES
-
var: ansible_persistent_log_messages
- 		-
This flag will enable logging the command executed and response received from target device in the ansible log file. For this option to work 'log_path' ansible configuration option is required to be set to a file path with write access.
-
Be sure to fully understand the security implications of enabling this option as it could create a security vulnerability by logging sensitive information in log file.
-
-
- port - -
- integer -
- 		- Default:
22
- 		-
ini entries: -

[defaults]
remote_port = 22

-
-
env:ANSIBLE_REMOTE_PORT
-
var: ansible_port
- 		-
Specifies the port on the remote device that listens for connections when establishing the SSH connection.
-
-
- private_key_file - -
- string -
- 		- -
ini entries: -

[defaults]
private_key_file = VALUE

-
-
env:ANSIBLE_PRIVATE_KEY_FILE
-
var: ansible_private_key_file
- 		-
The private SSH key or certificate file used to authenticate to the remote device when first establishing the SSH connection.
-
-
- remote_user - -
- string -
- 		- -
ini entries: -

[defaults]
remote_user = VALUE

-
-
env:ANSIBLE_REMOTE_USER
-
var: ansible_user
- 		-
The username used to authenticate to the remote device when the SSH connection is first established. If the remote_user is not specified, the connection will use the username of the logged in user.
-
Can be configured from the CLI via the --user or -u options.
-
-
- single_user_mode - -
- boolean -
-
added in 2.0.0
- 		- Default:
"no"
- 		-
env:ANSIBLE_NETWORK_SINGLE_USER_MODE
-
var: ansible_network_single_user_mode
- 		-
This option enables caching of data fetched from the target for re-use. The cache is invalidated when the target device enters configuration mode.
-
Applicable only for platforms where this has been implemented.
-
-
- ssh_type - -
- string -
- 		-
    Choices: -
  • libssh
    • -
  • paramiko
    • -
  • auto ←
    • -
- 		-
ini entries: -

[persistent_connection]
ssh_type = auto

-
-
env:ANSIBLE_NETWORK_CLI_SSH_TYPE
-
var: ansible_network_cli_ssh_type
- 		-
The python package that will be used by the network_cli connection plugin to create a SSH connection to remote host.
-
libssh will use the ansible-pylibssh package, which needs to be installed in order to work.
-
paramiko will instead use the paramiko package to manage the SSH connection.
-
auto will use ansible-pylibssh if that package is installed, otherwise will fallback to paramiko.
-
-
- terminal_errors - -
- string -
-
added in 3.1.0
- 		-
    Choices: -
  • ignore
    • -
  • warn
    • -
  • fail ←
    • -
- 		-
var: ansible_network_terminal_errors
- 		-
This option determines how failures while setting terminal parameters are handled.
-
When set to ignore, the errors are silently ignored. When set to warn, a warning message is displayed. The default option fail, triggers a failure and halts execution.
-
-
- terminal_inital_prompt_newline - -
- boolean -
- 		- Default:
"yes"
- 		-
var: ansible_terminal_initial_prompt_newline
- 		-
This boolean flag, that when set to True will send newline in the response if any of values in terminal_initial_prompt is matched.
-
-
- terminal_initial_answer - -
- list - / elements=string -
- 		- -
var: ansible_terminal_initial_answer
- 		-
The answer to reply with if the terminal_initial_prompt is matched. The value can be a single answer or a list of answers for multiple terminal_initial_prompt. In case the login menu has multiple prompts the sequence of the prompt and excepted answer should be in same order and the value of terminal_prompt_checkall should be set to True if all the values in terminal_initial_prompt are expected to be matched and set to False if any one login prompt is to be matched.
-
-
- terminal_initial_prompt - -
- list - / elements=string -
- 		- -
var: ansible_terminal_initial_prompt
- 		-
A single regex pattern or a sequence of patterns to evaluate the expected prompt at the time of initial login to the remote host.
-
-
- terminal_initial_prompt_checkall - -
- boolean -
- 		- Default:
"no"
- 		-
var: ansible_terminal_initial_prompt_checkall
- 		-
By default the value is set to False and any one of the prompts mentioned in terminal_initial_prompt option is matched it won't check for other prompts. When set to True it will check for all the prompts mentioned in terminal_initial_prompt option in the given order and all the prompts should be received from remote host if not it will result in timeout.
-
-
- terminal_stderr_re - -
- list - / elements=dictionary -
- 		- -
var: ansible_terminal_stderr_re
- 		-
This option provides the regex pattern and optional flags to match the error string from the received response chunk. This option accepts pattern and flags keys. The value of pattern is a python regex pattern to match the response and the value of flags is the value accepted by flags argument of re.compile python method to control the way regex is matched with the response, for example 're.I'.
-
-
- terminal_stdout_re - -
- list - / elements=dictionary -
- 		- -
var: ansible_terminal_stdout_re
- 		-
A single regex pattern or a sequence of patterns along with optional flags to match the command prompt from the received response chunk. This option accepts pattern and flags keys. The value of pattern is a python regex pattern to match the response and the value of flags is the value accepted by flags argument of re.compile python method to control the way regex is matched with the response, for example 're.I'.
-
-
- - - - - - - - -Status ------- + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Parameter

Comments

+
+

become

+ +

+ boolean +

+ + 		+

The become option will instruct the CLI session to attempt privilege escalation on platforms that support it. Normally this means transitioning from user mode to enable mode in the CLI session. If become is set to True and the remote device does not support privilege escalation or the privilege has already been elevated, then this option is silently ignored.

+

Can be configured from the CLI via the --become or -b options.

+

Choices:

+
    +

  • false ← (default)

    • +

  • true

    • +
+ +

Configuration:

+
    +
  • +

    INI entry

    + 
    [privilege_escalation]
+  become = false
    + +
    • +
  • +

    Environment variable: ANSIBLE_BECOME

    + +
    • +
  • +

    Variable: ansible_become

    + +
    • +
+
+
+

become_errors

+ +

+ string +

+ + 		+

This option determines how privilege escalation failures are handled when become is enabled.

+

When set to ignore, the errors are silently ignored. When set to warn, a warning message is displayed. The default option fail, triggers a failure and halts execution.

+

Choices:

+
    +

  • "ignore"

    • +

  • "warn"

    • +

  • "fail" ← (default)

    • +
+ +

Configuration:

+
    +
  • +

    Variable: ansible_network_become_errors

    + +
    • +
+
+
+

become_method

+ +

+ string +

+ + 		+

This option allows the become method to be specified in for handling privilege escalation. Typically the become_method value is set to enable but could be defined as other values.

+

Default: "sudo"

+

Configuration:

+
    +
  • +

    INI entry

    + 
    [privilege_escalation]
+  become_method = sudo
    + +
    • +
  • +

    Environment variable: ANSIBLE_BECOME_METHOD

    + +
    • +
  • +

    Variable: ansible_become_method

    + +
    • +
+
+
+

host

+ +

+ string +

+ + 		+

Specifies the remote device FQDN or IP address to establish the SSH connection to.

+

Default: "inventory_hostname"

+

Configuration:

+
    +
  • +

    Variable: inventory_hostname

    + +
    • +
  • +

    Variable: ansible_host

    + +
    • +
+
+
+

host_key_auto_add

+ +

+ boolean +

+ + 		+

By default, Ansible will prompt the user before adding SSH keys to the known hosts file. Since persistent connections such as network_cli run in background processes, the user will never be prompted. By enabling this option, unknown host keys will automatically be added to the known hosts file.

+

Be sure to fully understand the security implications of enabling this option on production systems as it could create a security vulnerability.

+

Choices:

+
    +

  • false ← (default)

    • +

  • true

    • +
+ +

Configuration:

+
    +
  • +

    INI entry

    + 
    [paramiko_connection]
+  host_key_auto_add = false
    + +
    • +
  • +

    Environment variable: ANSIBLE_HOST_KEY_AUTO_ADD

    + +
    • +
+
+
+

host_key_checking

+ +

+ boolean +

+ + 		+

Set this to "False" if you want to avoid host key checking by the underlying tools Ansible uses to connect to the host

+

Choices:

+
    +

  • false

    • +

  • true ← (default)

    • +
+ +

Configuration:

+
    +
  • +

    INI entries

    + 
    [defaults]
+  host_key_checking = true
    + + 
    [persistent_connection]
+  host_key_checking = true
    + +
    • +
  • +

    Environment variable: ANSIBLE_HOST_KEY_CHECKING

    + +
    • +
  • +

    Environment variable: ANSIBLE_SSH_HOST_KEY_CHECKING

    + +
    • +
  • +

    Variable: ansible_host_key_checking

    + +
    • +
  • +

    Variable: ansible_ssh_host_key_checking

    + +
    • +
+
+
+

import_modules

+ +

+ boolean +

+ + 		+

Reduce CPU usage and network module execution time by enabling direct execution. Instead of the module being packaged and executed by the shell, it will be directly executed by the Ansible control node using the same python interpreter as the Ansible process. Note- Incompatible with asynchronous mode. Note- Python 3 and Ansible 2.9.16 or greater required. Note- With Ansible 2.9.x fully qualified modules names are required in tasks.

+

Choices:

+
    +

  • false

    • +

  • true ← (default)

    • +
+ +

Configuration:

+
    +
  • +

    INI entry

    + 
    [ansible_network]
+  import_modules = true
    + +
    • +
  • +

    Environment variable: ANSIBLE_NETWORK_IMPORT_MODULES

    + +
    • +
  • +

    Variable: ansible_network_import_modules

    + +
    • +
+
+
+

network_cli_retries

+ +

+ integer +

+ + 		+

Number of attempts to connect to remote host. The delay time between the retires increases after every attempt by power of 2 in seconds till either the maximum attempts are exhausted or any of the persistent_command_timeout or persistent_connect_timeout timers are triggered.

+

Default: 3

+

Configuration:

+
    +
  • +

    INI entry

    + 
    [persistent_connection]
+  network_cli_retries = 3
    + +
    • +
  • +

    Environment variable: ANSIBLE_NETWORK_CLI_RETRIES

    + +
    • +
  • +

    Variable: ansible_network_cli_retries

    + +
    • +
+
+
+

network_os

+ +

+ string +

+ + 		+

Configures the device platform network operating system. This value is used to load the correct terminal and cliconf plugins to communicate with the remote device.

+

Configuration:

+
    +
  • +

    Variable: ansible_network_os

    + +
    • +
+
+
+

password

+ +

+ string +

+ + 		+

Configures the user password used to authenticate to the remote device when first establishing the SSH connection.

+

Configuration:

+
    +
  • +

    Variable: ansible_password

    + +
    • +
  • +

    Variable: ansible_ssh_pass

    + +
    • +
  • +

    Variable: ansible_ssh_password

    + +
    • +
+
+
+

persistent_buffer_read_timeout

+ +

+ float +

+ + 		+

Configures, in seconds, the amount of time to wait for the data to be read from Paramiko channel after the command prompt is matched. This timeout value ensures that command prompt matched is correct and there is no more data left to be received from remote host.

+

Default: 0.1

+

Configuration:

+
    +
  • +

    INI entry

    + 
    [persistent_connection]
+  buffer_read_timeout = 0.1
    + +
    • +
  • +

    Environment variable: ANSIBLE_PERSISTENT_BUFFER_READ_TIMEOUT

    + +
    • +
  • +

    Variable: ansible_buffer_read_timeout

    + +
    • +
+
+
+

persistent_command_timeout

+ +

+ integer +

+ + 		+

Configures, in seconds, the amount of time to wait for a command to return from the remote device. If this timer is exceeded before the command returns, the connection plugin will raise an exception and close.

+

Default: 30

+

Configuration:

+
    +
  • +

    INI entry

    + 
    [persistent_connection]
+  command_timeout = 30
    + +
    • +
  • +

    Environment variable: ANSIBLE_PERSISTENT_COMMAND_TIMEOUT

    + +
    • +
  • +

    Variable: ansible_command_timeout

    + +
    • +
+
+
+

persistent_connect_timeout

+ +

+ integer +

+ + 		+

Configures, in seconds, the amount of time to wait when trying to initially establish a persistent connection. If this value expires before the connection to the remote device is completed, the connection will fail.

+

Default: 30

+

Configuration:

+
    +
  • +

    INI entry

    + 
    [persistent_connection]
+  connect_timeout = 30
    + +
    • +
  • +

    Environment variable: ANSIBLE_PERSISTENT_CONNECT_TIMEOUT

    + +
    • +
  • +

    Variable: ansible_connect_timeout

    + +
    • +
+
+
+

persistent_log_messages

+ +

+ boolean +

+ + 		+

This flag will enable logging the command executed and response received from target device in the ansible log file. For this option to work 'log_path' ansible configuration option is required to be set to a file path with write access.

+

Be sure to fully understand the security implications of enabling this option as it could create a security vulnerability by logging sensitive information in log file.

+

Choices:

+
    +

  • false ← (default)

    • +

  • true

    • +
+ +

Configuration:

+
    +
  • +

    INI entry

    + 
    [persistent_connection]
+  log_messages = false
    + +
    • +
  • +

    Environment variable: ANSIBLE_PERSISTENT_LOG_MESSAGES

    + +
    • +
  • +

    Variable: ansible_persistent_log_messages

    + +
    • +
+
+
+

port

+ +

+ integer +

+ + 		+

Specifies the port on the remote device that listens for connections when establishing the SSH connection.

+

Default: 22

+

Configuration:

+
    +
  • +

    INI entry

    + 
    [defaults]
+  remote_port = 22
    + +
    • +
  • +

    Environment variable: ANSIBLE_REMOTE_PORT

    + +
    • +
  • +

    Variable: ansible_port

    + +
    • +
+
+
+

private_key_file

+ +

+ string +

+ + 		+

The private SSH key or certificate file used to authenticate to the remote device when first establishing the SSH connection.

+

Configuration:

+
    +
  • +

    INI entry

    + 
    [defaults]
+  private_key_file = VALUE
    + +
    • +
  • +

    Environment variable: ANSIBLE_PRIVATE_KEY_FILE

    + +
    • +
  • +

    Variable: ansible_private_key_file

    + +
    • +
+
+
+

remote_user

+ +

+ string +

+ + 		+

The username used to authenticate to the remote device when the SSH connection is first established. If the remote_user is not specified, the connection will use the username of the logged in user.

+

Can be configured from the CLI via the --user or -u options.

+

Configuration:

+
    +
  • +

    INI entry

    + 
    [defaults]
+  remote_user = VALUE
    + +
    • +
  • +

    Environment variable: ANSIBLE_REMOTE_USER

    + +
    • +
  • +

    Variable: ansible_user

    + +
    • +
+
+
+

single_user_mode

+ +

+ boolean +

+

added in ansible.netcommon 2.0.0

+ + 		+

This option enables caching of data fetched from the target for re-use. The cache is invalidated when the target device enters configuration mode.

+

Applicable only for platforms where this has been implemented.

+

Choices:

+
    +

  • false ← (default)

    • +

  • true

    • +
+ +

Configuration:

+
    +
  • +

    Environment variable: ANSIBLE_NETWORK_SINGLE_USER_MODE

    + +
    • +
  • +

    Variable: ansible_network_single_user_mode

    + +
    • +
+
+
+

ssh_type

+ +

+ string +

+ + 		+

The python package that will be used by the network_cli connection plugin to create a SSH connection to remote host.

+

libssh will use the ansible-pylibssh package, which needs to be installed in order to work.

+

paramiko will instead use the paramiko package to manage the SSH connection.

+

auto will use ansible-pylibssh if that package is installed, otherwise will fallback to paramiko.

+

Choices:

+
    +

  • "libssh"

    • +

  • "paramiko"

    • +

  • "auto" ← (default)

    • +
+ +

Configuration:

+
    +
  • +

    INI entry

    + 
    [persistent_connection]
+  ssh_type = auto
    + +
    • +
  • +

    Environment variable: ANSIBLE_NETWORK_CLI_SSH_TYPE

    + +
    • +
  • +

    Variable: ansible_network_cli_ssh_type

    + +
    • +
+
+
+

terminal_errors

+ +

+ string +

+

added in ansible.netcommon 3.1.0

+ + 		+

This option determines how failures while setting terminal parameters are handled.

+

When set to ignore, the errors are silently ignored. When set to warn, a warning message is displayed. The default option fail, triggers a failure and halts execution.

+

Choices:

+
    +

  • "ignore"

    • +

  • "warn"

    • +

  • "fail" ← (default)

    • +
+ +

Configuration:

+
    +
  • +

    Variable: ansible_network_terminal_errors

    + +
    • +
+
+
+

terminal_inital_prompt_newline

+ +

+ boolean +

+ + 		+

This boolean flag, that when set to True will send newline in the response if any of values in terminal_initial_prompt is matched.

+

Choices:

+
    +

  • false

    • +

  • true ← (default)

    • +
+ +

Configuration:

+
    +
  • +

    Variable: ansible_terminal_initial_prompt_newline

    + +
    • +
+
+
+

terminal_initial_answer

+ +

+ list + / elements=string +

+ + 		+

The answer to reply with if the terminal_initial_prompt is matched. The value can be a single answer or a list of answers for multiple terminal_initial_prompt. In case the login menu has multiple prompts the sequence of the prompt and excepted answer should be in same order and the value of terminal_prompt_checkall should be set to True if all the values in terminal_initial_prompt are expected to be matched and set to False if any one login prompt is to be matched.

+

Configuration:

+
    +
  • +

    Variable: ansible_terminal_initial_answer

    + +
    • +
+
+
+

terminal_initial_prompt

+ +

+ list + / elements=string +

+ + 		+

A single regex pattern or a sequence of patterns to evaluate the expected prompt at the time of initial login to the remote host.

+

Configuration:

+
    +
  • +

    Variable: ansible_terminal_initial_prompt

    + +
    • +
+
+
+

terminal_initial_prompt_checkall

+ +

+ boolean +

+ + 		+

By default the value is set to False and any one of the prompts mentioned in terminal_initial_prompt option is matched it won't check for other prompts. When set to True it will check for all the prompts mentioned in terminal_initial_prompt option in the given order and all the prompts should be received from remote host if not it will result in timeout.

+

Choices:

+
    +

  • false ← (default)

    • +

  • true

    • +
+ +

Configuration:

+
    +
  • +

    Variable: ansible_terminal_initial_prompt_checkall

    + +
    • +
+
+
+

terminal_stderr_re

+ +

+ list + / elements=dictionary +

+ + 		+

This option provides the regex pattern and optional flags to match the error string from the received response chunk. This option accepts pattern and flags keys. The value of pattern is a python regex pattern to match the response and the value of flags is the value accepted by flags argument of re.compile python method to control the way regex is matched with the response, for example 're.I'.

+

Configuration:

+
    +
  • +

    Variable: ansible_terminal_stderr_re

    + +
    • +
+
+
+

terminal_stdout_re

+ +

+ list + / elements=dictionary +

+ + 		+

A single regex pattern or a sequence of patterns along with optional flags to match the command prompt from the received response chunk. This option accepts pattern and flags keys. The value of pattern is a python regex pattern to match the response and the value of flags is the value accepted by flags argument of re.compile python method to control the way regex is matched with the response, for example 're.I'.

+

Configuration:

+
    +
  • +

    Variable: ansible_terminal_stdout_re

    + +
    • +
+
+ + + + + + + + + Authors @@ -638,3 +877,9 @@ Authors .. hint:: Configuration entries for each entry type have a low to high priority order. For example, a variable that is lower in the list will override a variable that is higher up. + +Collection links +~~~~~~~~~~~~~~~~ + +* `Issue Tracker `__ +* `Repository (Sources) `__ diff --git a/docs/ansible.netcommon.network_resource_module.rst b/docs/ansible.netcommon.network_resource_module.rst index e99579a76..df303dbc3 100644 --- a/docs/ansible.netcommon.network_resource_module.rst +++ b/docs/ansible.netcommon.network_resource_module.rst @@ -1,14 +1,19 @@ -.. _ansible.netcommon.network_resource_module: +.. Created with antsibull-docs 2.9.0 -********************************** -ansible.netcommon.network_resource -********************************** +ansible.netcommon.network_resource module -- Manage resource modules +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -**Manage resource modules** +This module is part of the `ansible.netcommon collection `_ (version 6.1.0). +It is not included in ``ansible-core``. +To check whether it is installed, run ``ansible-galaxy collection list``. -Version added: 2.4.0 +To install it, use: :code:`ansible-galaxy collection install ansible.netcommon`. + +To use it in a playbook, specify: ``ansible.netcommon.network_resource``. + +New in ansible.netcommon 2.4.0 .. contents:: :local: @@ -17,10 +22,16 @@ Version added: 2.4.0 Synopsis -------- + - Get list of available resource modules for given os name - Retrieve given resource module configuration facts - Push given resource module configuration +This module has a corresponding action plugin. + + + + @@ -29,104 +40,96 @@ Parameters .. raw:: html - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ParameterChoices/DefaultsComments
-
- config - -
- raw -
- 		- -
The resource module configuration. For details on the type and structure of this option refer the individual resource module platform documentation.
-
-
- name - -
- string -
- 		- -
The name of the resource module to manage.
-
The resource module should be supported for given os_name, if not supported it will result in error.
-
-
- os_name - -
- string -
- 		- -
The name of the os to manage the resource modules.
-
The name should be fully qualified collection name format, that is <namespace>.<collection-name>.<plugin-name>.
-
If value of this option is not set the os value will be read from ansible_network_os variable.
-
If value of both os_name and ansible_network_os is not set it will result in error.
-
-
- running_config - -
- - -
- 		- -
This option is used only with state parsed.
-
The value of this option should be the output received from the host device by executing the cli command to get the resource configuration on host.
-
The state parsed reads the configuration from running_config option and transforms it into Ansible structured data as per the resource module's argspec and the value is then returned in the parsed key within the result.
-
-
- state - -
- - -
- 		- -
The state the configuration should be left in.
-
For supported values refer the individual resource module platform documentation.
-
-
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Parameter

Comments

+
+

config

+ +

+ any +

+ 		+

The resource module configuration. For details on the type and structure of this option refer the individual resource module platform documentation.

+
+
+

name

+ +

+ string +

+ 		+

The name of the resource module to manage.

+

The resource module should be supported for given os_name, if not supported it will result in error.

+
+
+

os_name

+ +

+ string +

+ 		+

The name of the os to manage the resource modules.

+

The name should be fully qualified collection name format, that is <namespace>.<collection-name>.<plugin-name>.

+

If value of this option is not set the os value will be read from ansible_network_os variable.

+

If value of both os_name and ansible_network_os is not set it will result in error.

+
+
+

running_config

+ +

+ string +

+ 		+

This option is used only with state parsed.

+

The value of this option should be the output received from the host device by executing the cli command to get the resource configuration on host.

+

The state parsed reads the configuration from running_config option and transforms it into Ansible structured data as per the resource module's argspec and the value is then returned in the parsed key within the result.

+
+
+

state

+ +

+ string +

+ 		+

The state the configuration should be left in.

+

For supported values refer the individual resource module platform documentation.

+
+ + Notes ----- -.. note:: - - Refer the individual module documentation for the valid inputs of *state* and *config* modules. - +- Refer the individual module documentation for the valid inputs of \ :emphasis:`state`\ and \ :emphasis:`config`\ modules. Examples @@ -134,6 +137,7 @@ Examples .. code-block:: yaml + - name: get list of resource modules for given network_os ansible.netcommon.network_resource: register: result @@ -173,95 +177,101 @@ Examples + + Return Values ------------- -Common return values are documented `here `_, the following are the fields unique to this module: +The following are the fields unique to this module: .. raw:: html - - - - - - - - - - - - - - - - - - - - - - - - - - -
KeyReturnedDescription
-
- after - -
- list -
- 		when changed and when state and/or config option is set -
The configuration as structured data after module completion.
-
-
Sample:
-
The configuration returned will always be in the same format of the parameters above.
-
-
- before - -
- list -
- 		When state and/or config option is set -
The configuration as structured data prior to module invocation.
-
-
Sample:
-
The configuration returned will always be in the same format of the parameters above.
-
-
- commands - -
- list -
- 		When state and/or config option is set -
The set of commands pushed to the remote device
-
-
Sample:
-
['ip access-list extended 110']
-
-
- modules - -
- list -
- 		When only os_name or ansible_network_os is set -
List of resource modules supported for given OS.
-
-
Sample:
-
['acl_interfaces', 'acls', 'bgp_global']
-
-

- - -Status ------- + + + + + + + + + + + + + + + + + + + + + + + + + +

Key

Description

+
+

after

+ +

+ list + / elements=string +

+ 		+

The configuration as structured data after module completion.

+

Returned: when changed and when state and/or config option is set

+

Sample: ["The configuration returned will always be in the same format of the parameters above."]

+
+
+

before

+ +

+ list + / elements=string +

+ 		+

The configuration as structured data prior to module invocation.

+

Returned: When state and/or config option is set

+

Sample: ["The configuration returned will always be in the same format of the parameters above."]

+
+
+

commands

+ +

+ list + / elements=string +

+ 		+

The set of commands pushed to the remote device

+

Returned: When state and/or config option is set

+

Sample: ["ip access-list extended 110"]

+
+
+

modules

+ +

+ list + / elements=string +

+ 		+

List of resource modules supported for given OS.

+

Returned: When only os_name or ansible_network_os is set

+

Sample: ["acl_interfaces", "acls", "bgp_global"]

+
+ + Authors ~~~~~~~ - Ganesh B. Nalawade (@ganeshrn) + + + +Collection links +~~~~~~~~~~~~~~~~ + +* `Issue Tracker `__ +* `Repository (Sources) `__ diff --git a/docs/ansible.netcommon.parse_cli_filter.rst b/docs/ansible.netcommon.parse_cli_filter.rst index 0c0069af1..8066f4b5a 100644 --- a/docs/ansible.netcommon.parse_cli_filter.rst +++ b/docs/ansible.netcommon.parse_cli_filter.rst @@ -1,14 +1,19 @@ -.. _ansible.netcommon.parse_cli_filter: +.. Created with antsibull-docs 2.9.0 -*************************** -ansible.netcommon.parse_cli -*************************** +ansible.netcommon.parse_cli filter -- parse\_cli filter plugin. ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -**parse_cli filter plugin.** +This filter plugin is part of the `ansible.netcommon collection `_ (version 6.1.0). +It is not included in ``ansible-core``. +To check whether it is installed, run ``ansible-galaxy collection list``. -Version added: 1.0.0 +To install it, use: :code:`ansible-galaxy collection install ansible.netcommon`. + +To use it in a playbook, specify: ``ansible.netcommon.parse_cli``. + +New in ansible.netcommon 1.0.0 .. contents:: :local: @@ -17,70 +22,73 @@ Version added: 1.0.0 Synopsis -------- + - The filter plugins converts the output of a network device CLI command into structured JSON output. -- Using the parameters below - ``xml_data | ansible.netcommon.parse_cli(template.yml``) +- Using the parameters below - \ :literal:`xml\_data | ansible.netcommon.parse\_cli(template.yml`\ ) + + + + + +Keyword parameters +------------------ -Parameters ----------- +This describes keyword parameters of the filter. These are the values ``key1=value1``, ``key2=value2`` and so on in the following +example: ``input | ansible.netcommon.parse_cli(key1=value1, key2=value2, ...)`` .. raw:: html - - - - - - - - - - - - - - - - - - - -
ParameterChoices/DefaultsConfigurationComments
-
- output - -
- raw - / required -
- 		- - -
This source data on which parse_cli invokes.
-
-
- tmpl - -
- string -
- 		- - -
The spec file should be valid formatted YAML. It defines how to parse the CLI output and return JSON data.
-
For example cli_data | ansible.netcommon.parse_cli(template.yml), in this case cli_data represents cli output.
-
-
+ + + + + + + + + + + + + + + + + +

Parameter

Comments

+
+

output

+ +

+ any + / required +

+ + 		+

This source data on which parse_cli invokes.

+
+
+

tmpl

+ +

+ string +

+ + 		+

The spec file should be valid formatted YAML. It defines how to parse the CLI output and return JSON data.

+

For example cli_data | ansible.netcommon.parse_cli(template.yml), in this case cli_data represents cli output.

+
+ + Notes ----- -.. note:: - - The parse_cli filter will load the spec file and pass the command output through it, returning JSON output. The YAML spec file defines how to parse the CLI output - +- The parse\_cli filter will load the spec file and pass the command output through it, returning JSON output. The YAML spec file defines how to parse the CLI output Examples @@ -88,6 +96,7 @@ Examples .. code-block:: yaml + # Using parse_cli # outputConfig @@ -177,8 +186,7 @@ Examples -Status ------- + Authors @@ -189,3 +197,9 @@ Authors .. hint:: Configuration entries for each entry type have a low to high priority order. For example, a variable that is lower in the list will override a variable that is higher up. + +Collection links +~~~~~~~~~~~~~~~~ + +* `Issue Tracker `__ +* `Repository (Sources) `__ diff --git a/docs/ansible.netcommon.parse_cli_textfsm_filter.rst b/docs/ansible.netcommon.parse_cli_textfsm_filter.rst index 56a07e315..742a78193 100644 --- a/docs/ansible.netcommon.parse_cli_textfsm_filter.rst +++ b/docs/ansible.netcommon.parse_cli_textfsm_filter.rst @@ -1,14 +1,19 @@ -.. _ansible.netcommon.parse_cli_textfsm_filter: +.. Created with antsibull-docs 2.9.0 -*********************************** -ansible.netcommon.parse_cli_textfsm -*********************************** +ansible.netcommon.parse_cli_textfsm filter -- parse\_cli\_textfsm filter plugin. +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -**parse_cli_textfsm filter plugin.** +This filter plugin is part of the `ansible.netcommon collection `_ (version 6.1.0). +It is not included in ``ansible-core``. +To check whether it is installed, run ``ansible-galaxy collection list``. -Version added: 1.0.0 +To install it, use: :code:`ansible-galaxy collection install ansible.netcommon`. + +To use it in a playbook, specify: ``ansible.netcommon.parse_cli_textfsm``. + +New in ansible.netcommon 1.0.0 .. contents:: :local: @@ -17,70 +22,73 @@ Version added: 1.0.0 Synopsis -------- + - The network filters also support parsing the output of a CLI command using the TextFSM library. To parse the CLI output with TextFSM use this filter. -- Using the parameters below - ``data | ansible.netcommon.parse_cli_textfsm(template.yml``) +- Using the parameters below - \ :literal:`data | ansible.netcommon.parse\_cli\_textfsm(template.yml`\ ) + + + + + +Keyword parameters +------------------ -Parameters ----------- +This describes keyword parameters of the filter. These are the values ``key1=value1``, ``key2=value2`` and so on in the following +example: ``input | ansible.netcommon.parse_cli_textfsm(key1=value1, key2=value2, ...)`` .. raw:: html - - - - - - - - - - - - - - - - - - - -
ParameterChoices/DefaultsConfigurationComments
-
- template - -
- string -
- 		- - -
The template to compare it with.
-
For example data | ansible.netcommon.parse_cli_textfsm(template.yml), in this case data represents this option.
-
-
- value - -
- raw - / required -
- 		- - -
This source data on which parse_cli_textfsm invokes.
-
-
+ + + + + + + + + + + + + + + + + +

Parameter

Comments

+
+

template

+ +

+ string +

+ + 		+

The template to compare it with.

+

For example data | ansible.netcommon.parse_cli_textfsm(template.yml), in this case data represents this option.

+
+
+

value

+ +

+ any + / required +

+ + 		+

This source data on which parse_cli_textfsm invokes.

+
+ + Notes ----- -.. note:: - - Use of the TextFSM filter requires the TextFSM library to be installed. - +- Use of the TextFSM filter requires the TextFSM library to be installed. Examples @@ -88,6 +96,7 @@ Examples .. code-block:: yaml + # Using parse_cli_textfsm - name: "Fetch command output" @@ -134,8 +143,7 @@ Examples -Status ------- + Authors @@ -146,3 +154,9 @@ Authors .. hint:: Configuration entries for each entry type have a low to high priority order. For example, a variable that is lower in the list will override a variable that is higher up. + +Collection links +~~~~~~~~~~~~~~~~ + +* `Issue Tracker `__ +* `Repository (Sources) `__ diff --git a/docs/ansible.netcommon.parse_xml_filter.rst b/docs/ansible.netcommon.parse_xml_filter.rst index 487d79b82..d1377d1bb 100644 --- a/docs/ansible.netcommon.parse_xml_filter.rst +++ b/docs/ansible.netcommon.parse_xml_filter.rst @@ -1,14 +1,19 @@ -.. _ansible.netcommon.parse_xml_filter: +.. Created with antsibull-docs 2.9.0 -*************************** -ansible.netcommon.parse_xml -*************************** +ansible.netcommon.parse_xml filter -- The parse\_xml filter plugin. ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -**The parse_xml filter plugin.** +This filter plugin is part of the `ansible.netcommon collection `_ (version 6.1.0). +It is not included in ``ansible-core``. +To check whether it is installed, run ``ansible-galaxy collection list``. -Version added: 1.0.0 +To install it, use: :code:`ansible-galaxy collection install ansible.netcommon`. + +To use it in a playbook, specify: ``ansible.netcommon.parse_xml``. + +New in ansible.netcommon 1.0.0 .. contents:: :local: @@ -17,70 +22,73 @@ Version added: 1.0.0 Synopsis -------- + - This filter will load the spec file and pass the command output through it, returning JSON output. - The YAML spec file defines how to parse the CLI output. -Parameters ----------- + + + + +Keyword parameters +------------------ + +This describes keyword parameters of the filter. These are the values ``key1=value1``, ``key2=value2`` and so on in the following +example: ``input | ansible.netcommon.parse_xml(key1=value1, key2=value2, ...)`` .. raw:: html - - - - - - - - - - - - - - - - - - - -
ParameterChoices/DefaultsConfigurationComments
-
- output - -
- raw - / required -
- 		- - -
This source xml on which parse_xml invokes.
-
-
- tmpl - -
- string -
- 		- - -
The spec file should be valid formatted YAML. It defines how to parse the XML output and return JSON data.
-
For example xml_data | ansible.netcommon.parse_xml(template.yml), in this case xml_data represents xml data option.
-
-
+ + + + + + + + + + + + + + + + + +

Parameter

Comments

+
+

output

+ +

+ any + / required +

+ + 		+

This source xml on which parse_xml invokes.

+
+
+

tmpl

+ +

+ string +

+ + 		+

The spec file should be valid formatted YAML. It defines how to parse the XML output and return JSON data.

+

For example xml_data | ansible.netcommon.parse_xml(template.yml), in this case xml_data represents xml data option.

+
+ + Notes ----- -.. note:: - - To convert the XML output of a network device command into structured JSON output. - +- To convert the XML output of a network device command into structured JSON output. Examples @@ -88,6 +96,7 @@ Examples .. code-block:: yaml + # Using parse_xml # example_output.xml @@ -209,8 +218,7 @@ Examples -Status ------- + Authors @@ -221,3 +229,9 @@ Authors .. hint:: Configuration entries for each entry type have a low to high priority order. For example, a variable that is lower in the list will override a variable that is higher up. + +Collection links +~~~~~~~~~~~~~~~~ + +* `Issue Tracker `__ +* `Repository (Sources) `__ diff --git a/docs/ansible.netcommon.persistent_connection.rst b/docs/ansible.netcommon.persistent_connection.rst index d2c01a494..d574c41ea 100644 --- a/docs/ansible.netcommon.persistent_connection.rst +++ b/docs/ansible.netcommon.persistent_connection.rst @@ -1,14 +1,19 @@ -.. _ansible.netcommon.persistent_connection: +.. Created with antsibull-docs 2.9.0 -**************************** -ansible.netcommon.persistent -**************************** +ansible.netcommon.persistent connection -- Use a persistent unix socket for connection +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -**Use a persistent unix socket for connection** +This connection plugin is part of the `ansible.netcommon collection `_ (version 6.1.0). +It is not included in ``ansible-core``. +To check whether it is installed, run ``ansible-galaxy collection list``. -Version added: 1.0.0 +To install it, use: :code:`ansible-galaxy collection install ansible.netcommon`. + +To use it in a playbook, specify: ``ansible.netcommon.persistent``. + +New in ansible.netcommon 1.0.0 .. contents:: :local: @@ -17,128 +22,179 @@ Version added: 1.0.0 Synopsis -------- + - This is a helper plugin to allow making other connections persistent. + + + + Parameters ---------- .. raw:: html - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ParameterChoices/DefaultsConfigurationComments
-
- import_modules - -
- boolean -
- 		- Default:
"yes"
- 		-
ini entries: -

[ansible_network]
import_modules = yes

-
-
env:ANSIBLE_NETWORK_IMPORT_MODULES
-
var: ansible_network_import_modules
- 		-
Reduce CPU usage and network module execution time by enabling direct execution. Instead of the module being packaged and executed by the shell, it will be directly executed by the Ansible control node using the same python interpreter as the Ansible process. Note- Incompatible with asynchronous mode. Note- Python 3 and Ansible 2.9.16 or greater required. Note- With Ansible 2.9.x fully qualified modules names are required in tasks.
-
-
- persistent_command_timeout - -
- integer -
- 		- Default:
30
- 		-
ini entries: -

[persistent_connection]
command_timeout = 30

-
-
env:ANSIBLE_PERSISTENT_COMMAND_TIMEOUT
-
var: ansible_command_timeout
- 		-
Configures, in seconds, the amount of time to wait for a command to return from the remote device. If this timer is exceeded before the command returns, the connection plugin will raise an exception and close.
-
-
- persistent_connect_timeout - -
- integer -
- 		- Default:
30
- 		-
ini entries: -

[persistent_connection]
connect_timeout = 30

-
-
env:ANSIBLE_PERSISTENT_CONNECT_TIMEOUT
-
var: ansible_connect_timeout
- 		-
Configures, in seconds, the amount of time to wait when trying to initially establish a persistent connection. If this value expires before the connection to the remote device is completed, the connection will fail.
-
-
- persistent_log_messages - -
- boolean -
- 		- Default:
"no"
- 		-
ini entries: -

[persistent_connection]
log_messages = no

-
-
env:ANSIBLE_PERSISTENT_LOG_MESSAGES
-
var: ansible_persistent_log_messages
- 		-
This flag will enable logging the command executed and response received from target device in the ansible log file. For this option to work 'log_path' ansible configuration option is required to be set to a file path with write access.
-
Be sure to fully understand the security implications of enabling this option as it could create a security vulnerability by logging sensitive information in log file.
-
-
- - - - - - - - -Status ------- + + + + + + + + + + + + + + + + + + + + + + + + + +

Parameter

Comments

+
+

import_modules

+ +

+ boolean +

+ + 		+

Reduce CPU usage and network module execution time by enabling direct execution. Instead of the module being packaged and executed by the shell, it will be directly executed by the Ansible control node using the same python interpreter as the Ansible process. Note- Incompatible with asynchronous mode. Note- Python 3 and Ansible 2.9.16 or greater required. Note- With Ansible 2.9.x fully qualified modules names are required in tasks.

+

Choices:

+
    +

  • false

    • +

  • true ← (default)

    • +
+ +

Configuration:

+
    +
  • +

    INI entry

    + 
    [ansible_network]
+  import_modules = true
    + +
    • +
  • +

    Environment variable: ANSIBLE_NETWORK_IMPORT_MODULES

    + +
    • +
  • +

    Variable: ansible_network_import_modules

    + +
    • +
+
+
+

persistent_command_timeout

+ +

+ integer +

+ + 		+

Configures, in seconds, the amount of time to wait for a command to return from the remote device. If this timer is exceeded before the command returns, the connection plugin will raise an exception and close.

+

Default: 30

+

Configuration:

+
    +
  • +

    INI entry

    + 
    [persistent_connection]
+  command_timeout = 30
    + +
    • +
  • +

    Environment variable: ANSIBLE_PERSISTENT_COMMAND_TIMEOUT

    + +
    • +
  • +

    Variable: ansible_command_timeout

    + +
    • +
+
+
+

persistent_connect_timeout

+ +

+ integer +

+ + 		+

Configures, in seconds, the amount of time to wait when trying to initially establish a persistent connection. If this value expires before the connection to the remote device is completed, the connection will fail.

+

Default: 30

+

Configuration:

+
    +
  • +

    INI entry

    + 
    [persistent_connection]
+  connect_timeout = 30
    + +
    • +
  • +

    Environment variable: ANSIBLE_PERSISTENT_CONNECT_TIMEOUT

    + +
    • +
  • +

    Variable: ansible_connect_timeout

    + +
    • +
+
+
+

persistent_log_messages

+ +

+ boolean +

+ + 		+

This flag will enable logging the command executed and response received from target device in the ansible log file. For this option to work 'log_path' ansible configuration option is required to be set to a file path with write access.

+

Be sure to fully understand the security implications of enabling this option as it could create a security vulnerability by logging sensitive information in log file.

+

Choices:

+
    +

  • false ← (default)

    • +

  • true

    • +
+ +

Configuration:

+
    +
  • +

    INI entry

    + 
    [persistent_connection]
+  log_messages = false
    + +
    • +
  • +

    Environment variable: ANSIBLE_PERSISTENT_LOG_MESSAGES

    + +
    • +
  • +

    Variable: ansible_persistent_log_messages

    + +
    • +
+
+ + + + + + + + + Authors @@ -149,3 +205,9 @@ Authors .. hint:: Configuration entries for each entry type have a low to high priority order. For example, a variable that is lower in the list will override a variable that is higher up. + +Collection links +~~~~~~~~~~~~~~~~ + +* `Issue Tracker `__ +* `Repository (Sources) `__ diff --git a/docs/ansible.netcommon.pop_ace_filter.rst b/docs/ansible.netcommon.pop_ace_filter.rst index a8dfe8452..7d8d72ec3 100644 --- a/docs/ansible.netcommon.pop_ace_filter.rst +++ b/docs/ansible.netcommon.pop_ace_filter.rst @@ -1,14 +1,19 @@ -.. _ansible.netcommon.pop_ace_filter: +.. Created with antsibull-docs 2.9.0 -************************* -ansible.netcommon.pop_ace -************************* +ansible.netcommon.pop_ace filter -- Remove ace entries from a acl source of truth. +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -**Remove ace entries from a acl source of truth.** +This filter plugin is part of the `ansible.netcommon collection `_ (version 6.1.0). +It is not included in ``ansible-core``. +To check whether it is installed, run ``ansible-galaxy collection list``. -Version added: 5.1.0 +To install it, use: :code:`ansible-galaxy collection install ansible.netcommon`. + +To use it in a playbook, specify: ``ansible.netcommon.pop_ace``. + +New in ansible.netcommon 5.1.0 .. contents:: :local: @@ -17,285 +22,261 @@ Version added: 5.1.0 Synopsis -------- + - This plugin removes specific keys from a provided acl data. -- Using the parameters below - ``acls_data | ansible.netcommon.pop_ace(filter_options=filter_options, match_criteria=match_criteria``) +- Using the parameters below - \ :literal:`acls\_data | ansible.netcommon.pop\_ace(filter\_options=filter\_options, match\_criteria=match\_criteria`\ ) + + -Parameters ----------- + + +Keyword parameters +------------------ + +This describes keyword parameters of the filter. These are the values ``key1=value1``, ``key2=value2`` and so on in the following +example: ``input | ansible.netcommon.pop_ace(key1=value1, key2=value2, ...)`` .. raw:: html - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ParameterChoices/DefaultsConfigurationComments
-
- data - -
- raw - / required -
- 		- - -
This option represents a list of dictionaries of acls facts.
-
For example acls_data | ansible.netcommon.pop_ace(filter_options=filter_options, match_criteria=match_criteria), in this case acls_data represents this option.
-
-
- filter_options - -
- dictionary -
- 		- - -
Specify filtering options which drives the filter plugin.
-
-
- failed_when - -
- string -
- 		-
    Choices: -
  • missing ←
    • -
  • never
    • -
- 		- -
On missing it fails when there is no match with the ACL data supplied
-
On never it would never fail
-
-
- match_all - -
- boolean -
- 		-
    Choices: -
  • no ←
    • -
  • yes
    • -
- 		- -
When true ensures ace removed only when it matches all match criteria
-
-
- remove - -
- string -
- 		-
    Choices: -
  • first
    • -
  • all ←
    • -
- 		- -
Remove first removes one ace from each ACL entry on match
-
Remove all is more aggressive and removes more than one on match
-
-
- match_criteria - -
- dictionary - / required -
- 		- - -
Specify the matching configuration of the ACEs to remove.
-
-
- acl_name - -
- string -
- 		- - -
ACL name to match
-
-
- afi - -
- string - / required -
- 		- - -
Specify afi to match
-
-
- destination - -
- string -
- 		- - -
Destination address/ host/ any of the ACE to natch
-
-
- grant - -
- string -
- 		- - -
Grant type permit or deny to match
-
-
- protocol - -
- string -
- 		- - -
Protocol name of the ACE to match
-
-
- sequence - -
- string -
- 		- - -
Sequence number of the ACE to match
-
-
- source - -
- string -
- 		- - -
Source address/ host/ any of the ACE to match
-
-
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Parameter

Comments

+
+

data

+ +

+ any + / required +

+ + 		+

This option represents a list of dictionaries of acls facts.

+

For example acls_data | ansible.netcommon.pop_ace(filter_options=filter_options, match_criteria=match_criteria), in this case acls_data represents this option.

+
+
+

filter_options

+ +

+ dictionary +

+ + 		+

Specify filtering options which drives the filter plugin.

+
+
+

failed_when

+ +

+ string +

+ + 		+

On missing it fails when there is no match with the ACL data supplied

+

On never it would never fail

+

Choices:

+
    +

  • "missing" ← (default)

    • +

  • "never"

    • +
+ +
+
+

match_all

+ +

+ boolean +

+ + 		+

When true ensures ace removed only when it matches all match criteria

+

Choices:

+
    +

  • false ← (default)

    • +

  • true

    • +
+ +
+
+

remove

+ +

+ string +

+ + 		+

Remove first removes one ace from each ACL entry on match

+

Remove all is more aggressive and removes more than one on match

+

Choices:

+
    +

  • "first"

    • +

  • "all" ← (default)

    • +
+ +
+
+

match_criteria

+ +

+ dictionary + / required +

+ + 		+

Specify the matching configuration of the ACEs to remove.

+
+
+

acl_name

+ +

+ string +

+ + 		+

ACL name to match

+
+
+

afi

+ +

+ string + / required +

+ + 		+

Specify afi to match

+
+
+

destination

+ +

+ string +

+ + 		+

Destination address/ host/ any of the ACE to natch

+
+
+

grant

+ +

+ string +

+ + 		+

Grant type permit or deny to match

+
+
+

protocol

+ +

+ string +

+ + 		+

Protocol name of the ACE to match

+
+
+

sequence

+ +

+ string +

+ + 		+

Sequence number of the ACE to match

+
+
+

source

+ +

+ string +

+ + 		+

Source address/ host/ any of the ACE to match

+
+ + Notes ----- -.. note:: - - The filter plugin has been tested with facts collected for acls resource module on Cisco IOSXE, IOSXR and NXOS. - +- The filter plugin has been tested with facts collected for acls resource module on Cisco IOSXE, IOSXR and NXOS. Examples @@ -303,6 +284,7 @@ Examples .. code-block:: yaml + ## Playbook with filter plugin example vars: filter_options: @@ -1211,8 +1193,7 @@ Examples -Status ------- + Authors @@ -1223,3 +1204,9 @@ Authors .. hint:: Configuration entries for each entry type have a low to high priority order. For example, a variable that is lower in the list will override a variable that is higher up. + +Collection links +~~~~~~~~~~~~~~~~ + +* `Issue Tracker `__ +* `Repository (Sources) `__ diff --git a/docs/ansible.netcommon.restconf_config_module.rst b/docs/ansible.netcommon.restconf_config_module.rst index 5db4bb495..516d952b4 100644 --- a/docs/ansible.netcommon.restconf_config_module.rst +++ b/docs/ansible.netcommon.restconf_config_module.rst @@ -1,14 +1,19 @@ -.. _ansible.netcommon.restconf_config_module: +.. Created with antsibull-docs 2.9.0 -********************************* -ansible.netcommon.restconf_config -********************************* +ansible.netcommon.restconf_config module -- Handles create, update, read and delete of configuration data on RESTCONF enabled devices. +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -**Handles create, update, read and delete of configuration data on RESTCONF enabled devices.** +This module is part of the `ansible.netcommon collection `_ (version 6.1.0). +It is not included in ``ansible-core``. +To check whether it is installed, run ``ansible-galaxy collection list``. -Version added: 1.0.0 +To install it, use: :code:`ansible-galaxy collection install ansible.netcommon`. + +To use it in a playbook, specify: ``ansible.netcommon.restconf_config``. + +New in ansible.netcommon 1.0.0 .. contents:: :local: @@ -17,106 +22,109 @@ Version added: 1.0.0 Synopsis -------- + - RESTCONF is a standard mechanisms to allow web applications to configure and manage data. RESTCONF is a IETF standard and documented on RFC 8040. - This module allows the user to configure data on RESTCONF enabled devices. + + + + Parameters ---------- .. raw:: html - - - - - - - - - - - - - - - - - - - - - - - - - - -
ParameterChoices/DefaultsComments
-
- content - -
- string -
- 		- -
The configuration data in format as specififed in format option. Required unless method is delete.
-
-
- format - -
- string -
- 		-
    Choices: -
  • json ←
    • -
  • xml
    • -
- 		-
The format of the configuration provided as value of content. Accepted values are xml and json and the given configuration format should be supported by remote RESTCONF server.
-
-
- method - -
- string -
- 		-
    Choices: -
  • post ←
    • -
  • put
    • -
  • patch
    • -
  • delete
    • -
- 		-
The RESTCONF method to manage the configuration change on device. The value post is used to create a data resource or invoke an operation resource, put is used to replace the target data resource, patch is used to modify the target resource, and delete is used to delete the target resource.
-
-
- path - -
- string - / required -
- 		- -
URI being used to execute API calls.
-
-
+ + + + + + + + + + + + + + + + + + + + + + + + + +

Parameter

Comments

+
+

content

+ +

+ string +

+ 		+

The configuration data in format as specififed in format option. Required unless method is delete.

+
+
+

format

+ +

+ string +

+ 		+

The format of the configuration provided as value of content. Accepted values are xml and json and the given configuration format should be supported by remote RESTCONF server.

+

Choices:

+
    +

  • "json" ← (default)

    • +

  • "xml"

    • +
+ +
+
+

method

+ +

+ string +

+ 		+

The RESTCONF method to manage the configuration change on device. The value post is used to create a data resource or invoke an operation resource, put is used to replace the target data resource, patch is used to modify the target resource, and delete is used to delete the target resource.

+

Choices:

+
    +

  • "post" ← (default)

    • +

  • "put"

    • +

  • "patch"

    • +

  • "delete"

    • +
+ +
+
+

path

+ +

+ string + / required +

+ 		+

URI being used to execute API calls.

+
+ + Notes ----- -.. note:: - - This module requires the RESTCONF system service be enabled on the remote device being managed. - - This module is supported with *ansible_connection* value of *ansible.netcommon.httpapi* and *ansible_network_os* value of *ansible.netcommon.restconf*. - - This module is tested against Cisco IOSXE 16.12.02 version. - +- This module requires the RESTCONF system service be enabled on the remote device being managed. +- This module is supported with \ :emphasis:`ansible\_connection`\ value of \ :emphasis:`ansible.netcommon.httpapi`\ and \ :emphasis:`ansible\_network\_os`\ value of \ :emphasis:`ansible.netcommon.restconf`\ . +- This module is tested against Cisco IOSXE 16.12.02 version. Examples @@ -124,6 +132,7 @@ Examples .. code-block:: yaml + - name: create l3vpn services ansible.netcommon.restconf_config: path: /config/ietf-l3vpn-svc:l3vpn-svc/vpn-services @@ -145,82 +154,67 @@ Examples + + Return Values ------------- -Common return values are documented `here `_, the following are the fields unique to this module: +The following are the fields unique to this module: .. raw:: html - - - - - - - - - - - - - - - - -
KeyReturnedDescription
-
- candidate - -
- dictionary -
- 		When the method is not delete -
The configuration sent to the device.
-
-
Sample:
-
{ - "vpn-service": [ - { - "customer-name": "red", - "vpn-id": "blue_vpn1", - "vpn-service-topology": "ietf-l3vpn-svc:any-to-any" - } - ] - }
-
-
- running - -
- dictionary -
- 		When the method is not delete -
The current running configuration on the device.
-
-
Sample:
-
{ - "vpn-service": [ - { - "vpn-id": "red_vpn2", - "customer-name": "blue", - "vpn-service-topology": "ietf-l3vpn-svc:any-to-any" - }, - { - "vpn-id": "blue_vpn1", - "customer-name": "red", - "vpn-service-topology": "ietf-l3vpn-svc:any-to-any" - } - ] - }
-
-

- - -Status ------- + + + + + + + + + + + + + + + + + +

Key

Description

+
+

candidate

+ +

+ dictionary +

+ 		+

The configuration sent to the device.

+

Returned: When the method is not delete

+

Sample: {"vpn-service": [{"customer-name": "red", "vpn-id": "blue_vpn1", "vpn-service-topology": "ietf-l3vpn-svc:any-to-any"}]}

+
+
+

running

+ +

+ dictionary +

+ 		+

The current running configuration on the device.

+

Returned: When the method is not delete

+

Sample: {"vpn-service": [{"customer-name": "blue", "vpn-id": "red_vpn2", "vpn-service-topology": "ietf-l3vpn-svc:any-to-any"}, {"customer-name": "red", "vpn-id": "blue_vpn1", "vpn-service-topology": "ietf-l3vpn-svc:any-to-any"}]}

+
+ + Authors ~~~~~~~ - Ganesh Nalawade (@ganeshrn) + + + +Collection links +~~~~~~~~~~~~~~~~ + +* `Issue Tracker `__ +* `Repository (Sources) `__ diff --git a/docs/ansible.netcommon.restconf_get_module.rst b/docs/ansible.netcommon.restconf_get_module.rst index e271438c6..b0333bbf7 100644 --- a/docs/ansible.netcommon.restconf_get_module.rst +++ b/docs/ansible.netcommon.restconf_get_module.rst @@ -1,14 +1,19 @@ -.. _ansible.netcommon.restconf_get_module: +.. Created with antsibull-docs 2.9.0 -****************************** -ansible.netcommon.restconf_get -****************************** +ansible.netcommon.restconf_get module -- Fetch configuration/state data from RESTCONF enabled devices. +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -**Fetch configuration/state data from RESTCONF enabled devices.** +This module is part of the `ansible.netcommon collection `_ (version 6.1.0). +It is not included in ``ansible-core``. +To check whether it is installed, run ``ansible-galaxy collection list``. -Version added: 1.0.0 +To install it, use: :code:`ansible-galaxy collection install ansible.netcommon`. + +To use it in a playbook, specify: ``ansible.netcommon.restconf_get``. + +New in ansible.netcommon 1.0.0 .. contents:: :local: @@ -17,90 +22,95 @@ Version added: 1.0.0 Synopsis -------- + - RESTCONF is a standard mechanisms to allow web applications to access the configuration data and state data developed and standardized by the IETF. It is documented in RFC 8040. - This module allows the user to fetch configuration and state data from RESTCONF enabled devices. + + + + Parameters ---------- .. raw:: html - - - - - - - - - - - - - - - - - - - - - -
ParameterChoices/DefaultsComments
-
- content - -
- string -
- 		-
    Choices: -
  • config
    • -
  • nonconfig
    • -
  • all
    • -
- 		-
The content is a query parameter that controls how descendant nodes of the requested data nodes in path will be processed in the reply. If value is config return only configuration descendant data nodes of value in path. If value is nonconfig return only non-configuration descendant data nodes of value in path. If value is all return all descendant data nodes of value in path
-
-
- output - -
- string -
- 		-
    Choices: -
  • json ←
    • -
  • xml
    • -
- 		-
The output of response received.
-
-
- path - -
- string - / required -
- 		- -
URI being used to execute API calls.
-
-
+ + + + + + + + + + + + + + + + + + + + + +

Parameter

Comments

+
+

content

+ +

+ string +

+ 		+

The content is a query parameter that controls how descendant nodes of the requested data nodes in path will be processed in the reply. If value is config return only configuration descendant data nodes of value in path. If value is nonconfig return only non-configuration descendant data nodes of value in path. If value is all return all descendant data nodes of value in path

+

Choices:

+
    +

  • "config"

    • +

  • "nonconfig"

    • +

  • "all"

    • +
+ +
+
+

output

+ +

+ string +

+ 		+

The output of response received.

+

Choices:

+
    +

  • "json" ← (default)

    • +

  • "xml"

    • +
+ +
+
+

path

+ +

+ string + / required +

+ 		+

URI being used to execute API calls.

+
+ + Notes ----- -.. note:: - - This module requires the RESTCONF system service be enabled on the remote device being managed. - - This module is supported with *ansible_connection* value of *ansible.netcommon.httpapi* and *ansible_network_os* value of *ansible.netcommon.restconf*. - - This module is tested against Cisco IOSXE 16.12.02 version. - +- This module requires the RESTCONF system service be enabled on the remote device being managed. +- This module is supported with \ :emphasis:`ansible\_connection`\ value of \ :emphasis:`ansible.netcommon.httpapi`\ and \ :emphasis:`ansible\_network\_os`\ value of \ :emphasis:`ansible.netcommon.restconf`\ . +- This module is tested against Cisco IOSXE 16.12.02 version. Examples @@ -108,60 +118,59 @@ Examples .. code-block:: yaml + - name: get l3vpn services ansible.netcommon.restconf_get: path: /config/ietf-l3vpn-svc:l3vpn-svc/vpn-services + + Return Values ------------- -Common return values are documented `here `_, the following are the fields unique to this module: +The following are the fields unique to this module: .. raw:: html - - - - - - - - - - - -
KeyReturnedDescription
-
- response - -
- dictionary -
- 		when the device response is valid JSON -
A dictionary representing a JSON-formatted response
-
-
Sample:
-
{ - "vpn-services": { - "vpn-service": [ - { - "customer-name": "red", - "vpn-id": "blue_vpn1", - "vpn-service-topology": "ietf-l3vpn-svc:any-to-any" - } - ] - } - }
-
-

- - -Status ------- + + + + + + + + + + + + + +

Key

Description

+
+

response

+ +

+ dictionary +

+ 		+

A dictionary representing a JSON-formatted response

+

Returned: when the device response is valid JSON

+

Sample: {"vpn-services": {"vpn-service": [{"customer-name": "red", "vpn-id": "blue_vpn1", "vpn-service-topology": "ietf-l3vpn-svc:any-to-any"}]}}

+
+ + Authors ~~~~~~~ - Ganesh Nalawade (@ganeshrn) + + + +Collection links +~~~~~~~~~~~~~~~~ + +* `Issue Tracker `__ +* `Repository (Sources) `__ diff --git a/docs/ansible.netcommon.restconf_httpapi.rst b/docs/ansible.netcommon.restconf_httpapi.rst index 00031ed8b..5b1bde633 100644 --- a/docs/ansible.netcommon.restconf_httpapi.rst +++ b/docs/ansible.netcommon.restconf_httpapi.rst @@ -1,14 +1,19 @@ -.. _ansible.netcommon.restconf_httpapi: +.. Created with antsibull-docs 2.9.0 -************************** -ansible.netcommon.restconf -************************** +ansible.netcommon.restconf httpapi -- HttpApi Plugin for devices supporting Restconf API +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -**HttpApi Plugin for devices supporting Restconf API** +This httpapi plugin is part of the `ansible.netcommon collection `_ (version 6.1.0). +It is not included in ``ansible-core``. +To check whether it is installed, run ``ansible-galaxy collection list``. -Version added: 1.0.0 +To install it, use: :code:`ansible-galaxy collection install ansible.netcommon`. + +To use it in a playbook, specify: ``ansible.netcommon.restconf``. + +New in ansible.netcommon 1.0.0 .. contents:: :local: @@ -17,44 +22,54 @@ Version added: 1.0.0 Synopsis -------- + - This HttpApi plugin provides methods to connect to Restconf API endpoints. + + + + Parameters ---------- .. raw:: html - - - - - - - - - - - - - -
ParameterChoices/DefaultsConfigurationComments
-
- root_path - -
- string -
- 		- Default:
"/restconf"
- 		-
var: ansible_httpapi_restconf_root
- 		-
Specifies the location of the Restconf root.
-
-
+ + + + + + + + + + + + + +

Parameter

Comments

+
+

root_path

+ +

+ string +

+ + 		+

Specifies the location of the Restconf root.

+

Default: "/restconf"

+

Configuration:

+
    +
  • +

    Variable: ansible_httpapi_restconf_root

    + +
    • +
+
+ @@ -63,8 +78,6 @@ Parameters -Status ------- Authors @@ -75,3 +88,9 @@ Authors .. hint:: Configuration entries for each entry type have a low to high priority order. For example, a variable that is lower in the list will override a variable that is higher up. + +Collection links +~~~~~~~~~~~~~~~~ + +* `Issue Tracker `__ +* `Repository (Sources) `__ diff --git a/docs/ansible.netcommon.telnet_module.rst b/docs/ansible.netcommon.telnet_module.rst index 18a9769db..9bd75aea1 100644 --- a/docs/ansible.netcommon.telnet_module.rst +++ b/docs/ansible.netcommon.telnet_module.rst @@ -1,14 +1,19 @@ -.. _ansible.netcommon.telnet_module: +.. Created with antsibull-docs 2.9.0 -************************ -ansible.netcommon.telnet -************************ +ansible.netcommon.telnet module -- Executes a low-down and dirty telnet command ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -**Executes a low-down and dirty telnet command** +This module is part of the `ansible.netcommon collection `_ (version 6.1.0). +It is not included in ``ansible-core``. +To check whether it is installed, run ``ansible-galaxy collection list``. -Version added: 1.0.0 +To install it, use: :code:`ansible-galaxy collection install ansible.netcommon`. + +To use it in a playbook, specify: ``ansible.netcommon.telnet``. + +New in ansible.netcommon 1.0.0 .. contents:: :local: @@ -17,9 +22,15 @@ Version added: 1.0.0 Synopsis -------- + - Executes a low-down and dirty telnet command, not going through the module subsystem. - This is mostly to be used for enabling ssh on devices that only have telnet enabled by default. +This module has a corresponding action plugin. + + + + @@ -28,222 +39,205 @@ Parameters .. raw:: html - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ParameterChoices/DefaultsComments
-
- command - -
- list - / elements=string - / required -
- 		- -
List of commands to be executed in the telnet session.
-

aliases: commands
-
-
- crlf - -
- boolean -
- 		-
    Choices: -
  • no ←
    • -
  • yes
    • -
- 		-
Sends a CRLF (Carrage Return) instead of just a LF (Line Feed).
-
-
- host - -
- string -
- 		- Default:
"remote_addr"
- 		-
The host/target on which to execute the command
-
-
- login_prompt - -
- string -
- 		- Default:
"login: "
- 		-
Login or username prompt to expect
-
-
- password - -
- string -
- 		- -
The password for login
-
-
- password_prompt - -
- string -
- 		- Default:
"Password: "
- 		-
Login or username prompt to expect
-
-
- pause - -
- integer -
- 		- Default:
1
- 		-
Seconds to pause between each command issued
-
-
- port - -
- integer -
- 		- Default:
23
- 		-
Remote port to use
-
-
- prompts - -
- list - / elements=string -
- 		- Default:
["$"]
- 		-
List of prompts expected before sending next command
-
-
- send_newline - -
- boolean -
- 		-
    Choices: -
  • no ←
    • -
  • yes
    • -
- 		-
Sends a newline character upon successful connection to start the terminal session.
-
-
- timeout - -
- integer -
- 		- Default:
120
- 		-
timeout for remote operations
-
-
- user - -
- string -
- 		- Default:
"remote_user"
- 		-
The user for login
-
-
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Parameter

Comments

+
+
+

command

+ +

aliases: commands

+

+ list + / elements=string + / required +

+ 		+

List of commands to be executed in the telnet session.

+
+
+

crlf

+ +

+ boolean +

+ 		+

Sends a CRLF (Carrage Return) instead of just a LF (Line Feed).

+

Choices:

+
    +

  • false ← (default)

    • +

  • true

    • +
+ +
+
+

host

+ +

+ string +

+ 		+

The host/target on which to execute the command

+

Default: "remote_addr"

+
+
+

login_prompt

+ +

+ string +

+ 		+

Login or username prompt to expect

+

Default: "login: "

+
+
+

password

+ +

+ string +

+ 		+

The password for login

+
+
+

password_prompt

+ +

+ string +

+ 		+

Login or username prompt to expect

+

Default: "Password: "

+
+
+

pause

+ +

+ integer +

+ 		+

Seconds to pause between each command issued

+

Default: 1

+
+
+

port

+ +

+ integer +

+ 		+

Remote port to use

+

Default: 23

+
+
+

prompts

+ +

+ list + / elements=string +

+ 		+

List of prompts expected before sending next command

+

Default: ["$"]

+
+
+

send_newline

+ +

+ boolean +

+ 		+

Sends a newline character upon successful connection to start the terminal session.

+

Choices:

+
    +

  • false ← (default)

    • +

  • true

    • +
+ +
+
+

timeout

+ +

+ integer +

+ 		+

timeout for remote operations

+

Default: 120

+
+
+

user

+ +

+ string +

+ 		+

The user for login

+

Default: "remote_user"

+
+ + Notes ----- -.. note:: - - The ``environment`` keyword does not work with this task - +- The \ :literal:`environment`\ keyword does not work with this task Examples @@ -251,6 +245,7 @@ Examples .. code-block:: yaml + - name: send configuration commands to IOS ansible.netcommon.telnet: user: cisco @@ -276,44 +271,53 @@ Examples + + Return Values ------------- -Common return values are documented `here `_, the following are the fields unique to this module: +The following are the fields unique to this module: .. raw:: html - - - - - - - - - - - -
KeyReturnedDescription
-
- output - -
- list -
- 		always -
output of each command is an element in this list
-
-
Sample:
-
['success', 'success', '', 'warning .. something']
-
-

- - -Status ------- + + + + + + + + + + + + + +

Key

Description

+
+

output

+ +

+ list + / elements=string +

+ 		+

output of each command is an element in this list

+

Returned: always

+

Sample: ["success", "success", "", "warning .. something"]

+
+ + Authors ~~~~~~~ - Ansible Core Team + + + +Collection links +~~~~~~~~~~~~~~~~ + +* `Issue Tracker `__ +* `Repository (Sources) `__ diff --git a/docs/ansible.netcommon.type5_pw_filter.rst b/docs/ansible.netcommon.type5_pw_filter.rst index a7fe830bc..a64ca6325 100644 --- a/docs/ansible.netcommon.type5_pw_filter.rst +++ b/docs/ansible.netcommon.type5_pw_filter.rst @@ -1,14 +1,19 @@ -.. _ansible.netcommon.type5_pw_filter: +.. Created with antsibull-docs 2.9.0 -************************** -ansible.netcommon.type5_pw -************************** +ansible.netcommon.type5_pw filter -- The type5\_pw filter plugin. ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -**The type5_pw filter plugin.** +This filter plugin is part of the `ansible.netcommon collection `_ (version 6.1.0). +It is not included in ``ansible-core``. +To check whether it is installed, run ``ansible-galaxy collection list``. -Version added: 1.0.0 +To install it, use: :code:`ansible-galaxy collection install ansible.netcommon`. + +To use it in a playbook, specify: ``ansible.netcommon.type5_pw``. + +New in ansible.netcommon 1.0.0 .. contents:: :local: @@ -17,69 +22,72 @@ Version added: 1.0.0 Synopsis -------- + - Filter plugin to produce cisco type5 hashed password. -- Using the parameters below - ``xml_data | ansible.netcommon.type5_pw(template.yml``) +- Using the parameters below - \ :literal:`xml\_data | ansible.netcommon.type5\_pw(template.yml`\ ) + + + + + +Keyword parameters +------------------ -Parameters ----------- +This describes keyword parameters of the filter. These are the values ``key1=value1``, ``key2=value2`` and so on in the following +example: ``input | ansible.netcommon.type5_pw(key1=value1, key2=value2, ...)`` .. raw:: html - - - - - - - - - - - - - - - - - - - -
ParameterChoices/DefaultsConfigurationComments
-
- password - -
- string - / required -
- 		- - -
The password to be hashed.
-
-
- salt - -
- string -
- 		- - -
Mention the salt to hash the password.
-
-
+ + + + + + + + + + + + + + + + + +

Parameter

Comments

+
+

password

+ +

+ string + / required +

+ + 		+

The password to be hashed.

+
+
+

salt

+ +

+ string +

+ + 		+

Mention the salt to hash the password.

+
+ + Notes ----- -.. note:: - - The filter plugin generates cisco type5 hashed password. - +- The filter plugin generates cisco type5 hashed password. Examples @@ -87,6 +95,7 @@ Examples .. code-block:: yaml + # Using type5_pw - name: Set some facts @@ -113,8 +122,7 @@ Examples -Status ------- + Authors @@ -125,3 +133,9 @@ Authors .. hint:: Configuration entries for each entry type have a low to high priority order. For example, a variable that is lower in the list will override a variable that is higher up. + +Collection links +~~~~~~~~~~~~~~~~ + +* `Issue Tracker `__ +* `Repository (Sources) `__ diff --git a/docs/ansible.netcommon.vlan_expander_filter.rst b/docs/ansible.netcommon.vlan_expander_filter.rst index bcde65b03..d62181cf5 100644 --- a/docs/ansible.netcommon.vlan_expander_filter.rst +++ b/docs/ansible.netcommon.vlan_expander_filter.rst @@ -1,14 +1,19 @@ -.. _ansible.netcommon.vlan_expander_filter: +.. Created with antsibull-docs 2.9.0 -******************************* -ansible.netcommon.vlan_expander -******************************* +ansible.netcommon.vlan_expander filter -- The vlan\_expander filter plugin. ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -**The vlan_expander filter plugin.** +This filter plugin is part of the `ansible.netcommon collection `_ (version 6.1.0). +It is not included in ``ansible-core``. +To check whether it is installed, run ``ansible-galaxy collection list``. -Version added: 2.3.0 +To install it, use: :code:`ansible-galaxy collection install ansible.netcommon`. + +To use it in a playbook, specify: ``ansible.netcommon.vlan_expander``. + +New in ansible.netcommon 2.3.0 .. contents:: :local: @@ -17,52 +22,58 @@ Version added: 2.3.0 Synopsis -------- -- Expand shorthand list of VLANs to list all VLANs. Inverse of vlan_parser -- Using the parameters below - ``vlans_data | ansible.netcommon.vlan_expander`` + +- Expand shorthand list of VLANs to list all VLANs. Inverse of vlan\_parser +- Using the parameters below - \ :literal:`vlans\_data | ansible.netcommon.vlan\_expander`\ + + + + + +Keyword parameters +------------------ -Parameters ----------- +This describes keyword parameters of the filter. These are the values ``key1=value1``, ``key2=value2`` and so on in the following +example: ``input | ansible.netcommon.vlan_expander(key1=value1, key2=value2, ...)`` .. raw:: html - - - - - - - - - - - - - -
ParameterChoices/DefaultsConfigurationComments
-
- data - -
- string - / required -
- 		- - -
This option represents a string containing the range of vlans.
-
-
+ + + + + + + + + + + + + +

Parameter

Comments

+
+

data

+ +

+ string + / required +

+ + 		+

This option represents a string containing the range of vlans.

+
+ + Notes ----- -.. note:: - - The filter plugin extends vlans when data provided in range or comma separated. - +- The filter plugin extends vlans when data provided in range or comma separated. Examples @@ -70,6 +81,7 @@ Examples .. code-block:: yaml + # Using vlan_expander - name: Setting host facts for vlan_expander filter plugin @@ -105,8 +117,7 @@ Examples -Status ------- + Authors @@ -117,3 +128,9 @@ Authors .. hint:: Configuration entries for each entry type have a low to high priority order. For example, a variable that is lower in the list will override a variable that is higher up. + +Collection links +~~~~~~~~~~~~~~~~ + +* `Issue Tracker `__ +* `Repository (Sources) `__ diff --git a/docs/ansible.netcommon.vlan_parser_filter.rst b/docs/ansible.netcommon.vlan_parser_filter.rst index 43419d06a..93776986b 100644 --- a/docs/ansible.netcommon.vlan_parser_filter.rst +++ b/docs/ansible.netcommon.vlan_parser_filter.rst @@ -1,14 +1,19 @@ -.. _ansible.netcommon.vlan_parser_filter: +.. Created with antsibull-docs 2.9.0 -***************************** -ansible.netcommon.vlan_parser -***************************** +ansible.netcommon.vlan_parser filter -- The vlan\_parser filter plugin. ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -**The vlan_parser filter plugin.** +This filter plugin is part of the `ansible.netcommon collection `_ (version 6.1.0). +It is not included in ``ansible-core``. +To check whether it is installed, run ``ansible-galaxy collection list``. -Version added: 1.0.0 +To install it, use: :code:`ansible-galaxy collection install ansible.netcommon`. + +To use it in a playbook, specify: ``ansible.netcommon.vlan_parser``. + +New in ansible.netcommon 1.0.0 .. contents:: :local: @@ -17,89 +22,90 @@ Version added: 1.0.0 Synopsis -------- + - The filter plugin converts a list of vlans to IOS like vlan configuration. - Converts list to a list of range of numbers into multiple lists. -- ``vlans_data | ansible.netcommon.vlan_parser(first_line_len = 20, other_line_len=20``) +- \ :literal:`vlans\_data | ansible.netcommon.vlan\_parser(first\_line\_len = 20, other\_line\_len=20`\ ) + + + + + +Keyword parameters +------------------ -Parameters ----------- +This describes keyword parameters of the filter. These are the values ``key1=value1``, ``key2=value2`` and so on in the following +example: ``input | ansible.netcommon.vlan_parser(key1=value1, key2=value2, ...)`` .. raw:: html - - - - - - - - - - - - - - - - - - - - - - - - - -
ParameterChoices/DefaultsConfigurationComments
-
- data - -
- list - / required -
- 		- - -
This option represents a list containing vlans.
-
-
- first_line_len - -
- integer -
- 		- Default:
48
- 		- -
The first line of the list can be first_line_len characters long.
-
-
- other_line_len - -
- integer -
- 		- Default:
44
- 		- -
The subsequent list lines can be other_line_len characters.
-
-
+ + + + + + + + + + + + + + + + + + + + + +

Parameter

Comments

+
+

data

+ +

+ list + / elements=string + / required +

+ + 		+

This option represents a list containing vlans.

+
+
+

first_line_len

+ +

+ integer +

+ + 		+

The first line of the list can be first_line_len characters long.

+

Default: 48

+
+
+

other_line_len

+ +

+ integer +

+ + 		+

The subsequent list lines can be other_line_len characters.

+

Default: 44

+
+ + Notes ----- -.. note:: - - The filter plugin extends vlans when data provided in range or comma separated. - +- The filter plugin extends vlans when data provided in range or comma separated. Examples @@ -107,6 +113,7 @@ Examples .. code-block:: yaml + # Using vlan_parser - name: Setting host facts for vlan_parser filter plugin @@ -167,8 +174,7 @@ Examples -Status ------- + Authors @@ -179,3 +185,9 @@ Authors .. hint:: Configuration entries for each entry type have a low to high priority order. For example, a variable that is lower in the list will override a variable that is higher up. + +Collection links +~~~~~~~~~~~~~~~~ + +* `Issue Tracker `__ +* `Repository (Sources) `__