diff --git a/docs/cidr_merge_filter.rst b/docs/cidr_merge_filter.rst deleted file mode 100644 index 2103c561d..000000000 --- a/docs/cidr_merge_filter.rst +++ /dev/null @@ -1,14 +0,0 @@ - -.. Created with antsibull-docs 2.9.0 - -ansible.netcommon.cidr_merge filter -+++++++++++++++++++++++++++++++++++ - -- This redirect is part of the `ansible.netcommon collection `_ (version 6.1.0). - - -- This redirect has been **deprecated**. Please update your tasks to use the new name ``ansible.utils.cidr_merge`` instead. - It will be removed in a major release after 2024-01-01 of ansible.netcommon. -- This is a redirect to the ansible.utils.cidr_merge filter plugin. -- This redirect does **not** work with Ansible 2.9. -- The collection contains the following information on this deprecation: Use 'ansible.utils.cidr\_merge' module instead. diff --git a/docs/cli_backup_module.rst b/docs/cli_backup_module.rst deleted file mode 100644 index a14d6d3c4..000000000 --- a/docs/cli_backup_module.rst +++ /dev/null @@ -1,168 +0,0 @@ - -.. Created with antsibull-docs 2.9.0 - -ansible.netcommon.cli_backup module -- 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``. - -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: - :depth: 1 - - -Synopsis --------- - -- 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. - - - - - - - -Parameters ----------- - -.. raw:: html - - - - - - - - - - - - - - - - - - - - - - -

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 ------ - -- This module is supported on \ :literal:`ansible\_network\_os`\ network platforms. See the :ref:\`Network Platform Options \\` for details. - - -Examples --------- - -.. code-block:: yaml - - - - name: configurable backup path - ansible.netcommon.cli_backup: - filename: backup.cfg - dir_path: /home/user - - - - - -Return Values -------------- -The following are the fields unique to this module: - -.. raw:: html - - - - - - - - - - - - - - -

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/cli_command_module.rst b/docs/cli_command_module.rst deleted file mode 100644 index 226478230..000000000 --- a/docs/cli_command_module.rst +++ /dev/null @@ -1,277 +0,0 @@ - -.. Created with antsibull-docs 2.9.0 - -ansible.netcommon.cli_command module -- 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``. - -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: - :depth: 1 - - -Synopsis --------- - -- Sends a command to a network device and returns the result read from the device. - -This module has a corresponding action plugin. - - - - - - - -Parameters ----------- - -.. raw:: html - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

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 ------ - -- This module is supported on \ :literal:`ansible\_network\_os`\ network platforms. See the :ref:\`Network Platform Options \\` for details. - - -Examples --------- - -.. code-block:: yaml - - - - name: run show version on remote devices - ansible.netcommon.cli_command: - command: show version - - - name: run command with json formatted output - ansible.netcommon.cli_command: - command: show version | json - - - name: run command expecting user confirmation - ansible.netcommon.cli_command: - command: commit replace - prompt: This commit will replace or remove the entire running configuration - answer: "yes" - - - name: run command expecting user confirmation - ansible.netcommon.cli_command: - command: show interface summary - prompt: Press any key to continue - answer: y - newline: false - - - name: run config mode command and handle prompt/answer - ansible.netcommon.cli_command: - command: "{{ item }}" - prompt: - - Exit with uncommitted changes - answer: y - loop: - - configure - - set system syslog file test any any - - exit - - - name: multiple prompt, multiple answer (mandatory check for all prompts) - ansible.netcommon.cli_command: - command: copy sftp sftp://user@host//user/test.img - check_all: true - prompt: - - Confirm download operation - - Password - - Do you want to change that to the standby image - answer: - - y - - - - y - - - - - -Return Values -------------- -The following are the fields unique to this module: - -.. raw:: html - - - - - - - - - - - - - - - - - - -

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/cli_config_module.rst b/docs/cli_config_module.rst deleted file mode 100644 index c2eea492d..000000000 --- a/docs/cli_config_module.rst +++ /dev/null @@ -1,411 +0,0 @@ - -.. Created with antsibull-docs 2.9.0 - -ansible.netcommon.cli_config module -- 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``. - -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: - :depth: 1 - - -Synopsis --------- - -- 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. - - - - - - - -Parameters ----------- - -.. raw:: html - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

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 ------ - -- 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 --------- - -.. code-block:: yaml - - - - name: configure device with config - ansible.netcommon.cli_config: - config: "{{ lookup('template', 'basic/config.j2') }}" - - - name: multiline config - ansible.netcommon.cli_config: - config: | - hostname foo - feature nxapi - - - name: configure device with config with defaults enabled - ansible.netcommon.cli_config: - config: "{{ lookup('template', 'basic/config.j2') }}" - defaults: "yes" - - - name: Use diff_match - ansible.netcommon.cli_config: - config: "{{ lookup('file', 'interface_config') }}" - diff_match: none - - - name: nxos replace config - ansible.netcommon.cli_config: - replace: bootflash:nxoscfg - - - name: junos replace config - ansible.netcommon.cli_config: - replace: /var/home/ansible/junos01.cfg - - - name: commit with comment - ansible.netcommon.cli_config: - config: set system host-name foo - commit_comment: this is a test - - - name: configurable backup path - ansible.netcommon.cli_config: - config: "{{ lookup('template', 'basic/config.j2') }}" - backup: "yes" - backup_options: - filename: backup.cfg - dir_path: /home/user - - - - - -Return Values -------------- -The following are the fields unique to this module: - -.. raw:: html - - - - - - - - - - - - - - - - - - - - - - -

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/cli_restore_module.rst b/docs/cli_restore_module.rst deleted file mode 100644 index 40682c41e..000000000 --- a/docs/cli_restore_module.rst +++ /dev/null @@ -1,145 +0,0 @@ - -.. Created with antsibull-docs 2.9.0 - -ansible.netcommon.cli_restore module -- 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``. - -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: - :depth: 1 - - -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. - - - - - - - - -Parameters ----------- - -.. raw:: html - - - - - - - - - - - - - - - - - - -

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 ------ - -- This module is supported on \ :literal:`ansible\_network\_os`\ network platforms. See the :ref:\`Network Platform Options \\` for details. - - -Examples --------- - -.. code-block:: yaml - - - - name: Restore IOS-XE configuration - ansible.netcommon.cli_restore: - filename: backupDday.cfg - path: flash:// - - # Command fired - # ------------- - # config replace flash://backupDday.cfg force - - # Task Output - # ----------- - # - # ok: [BATMON] => changed=false - # __restore__: |- - # The rollback configlet from the last pass is listed below: - # ******** - # !List of Rollback Commands: - # Building configuration... - # Current configuration : 3781 bytes - # end - # ******** - # - # - # Rollback aborted after 5 passes - # The following commands are failed to apply to the IOS image. - # ******** - # Building configuration... - # Current configuration : 3781 bytes - # ******** - # invocation: - # module_args: - # filename: backupDday.cfg - - - - - - - -Authors -~~~~~~~ - -- Sagar Paul (@KB-perByte) - - - -Collection links -~~~~~~~~~~~~~~~~ - -* `Issue Tracker `__ -* `Repository (Sources) `__ - diff --git a/docs/comp_type5_filter.rst b/docs/comp_type5_filter.rst deleted file mode 100644 index 818e9601b..000000000 --- a/docs/comp_type5_filter.rst +++ /dev/null @@ -1,166 +0,0 @@ - -.. Created with antsibull-docs 2.9.0 - -ansible.netcommon.comp_type5 filter -- 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``. - -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: - :depth: 1 - - -Synopsis --------- - -- The filter confirms configuration idempotency on use of type5\_pw. - - - - - - - - -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.comp_type5(key1=value1, key2=value2, ...)`` - -.. raw:: html - - - - - - - - - - - - - - - - - - - - - - -

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 ------ - -- 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 --------- - -.. code-block:: yaml - - - # Using comp_type5 - - # playbook - - - name: Set the facts - ansible.builtin.set_fact: - unencrypted_password: "cisco@123" - encrypted_password: "$1$avs$uSTOEMh65ADDBREAKqzvpb9yBMpzd/" - - - name: Invoke comp_type5 - ansible.builtin.debug: - msg: "{{ unencrypted_password | ansible.netcommon.comp_type5(encrypted_password, False) }}" - - # Task Output - # ----------- - # - # TASK [Set the facts] - # ok: [35.155.113.92] => changed=false - # ansible_facts: - # encrypted_password: $1$avs$uSTOEMh65ADDBREAKqzvpb9yBMpzd/ - # unencrypted_password: cisco@123 - - # TASK [Invoke comp_type5] - # ok: [35.155.113.92] => - # msg: true - - - - - - - -Authors -~~~~~~~ - -- Ken Celenza (@itdependsnetworks) - - -.. 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/default_cliconf.rst b/docs/default_cliconf.rst deleted file mode 100644 index 56638db86..000000000 --- a/docs/default_cliconf.rst +++ /dev/null @@ -1,58 +0,0 @@ - -.. Created with antsibull-docs 2.9.0 - -ansible.netcommon.default cliconf -- 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``. - -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: - :depth: 1 - - -Synopsis --------- - -- This plugin attemts to provide low level abstraction apis for sending and receiving CLI commands from arbitrary network devices. - - - - - - - - - - - - - - - - - -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/default_netconf.rst b/docs/default_netconf.rst deleted file mode 100644 index 44931bf67..000000000 --- a/docs/default_netconf.rst +++ /dev/null @@ -1,90 +0,0 @@ - -.. Created with antsibull-docs 2.9.0 - -ansible.netcommon.default netconf -- 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``. - -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: - :depth: 1 - - -Synopsis --------- - -- This default plugin provides low level abstraction apis for sending and receiving netconf commands as per Netconf RFC specification. - - - - - - - - -Parameters ----------- - -.. raw:: html - - - - - - - - - - - - - - -

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"

-
- - - - - - - - - - - -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/enable_become.rst b/docs/enable_become.rst deleted file mode 100644 index 29f1207ed..000000000 --- a/docs/enable_become.rst +++ /dev/null @@ -1,123 +0,0 @@ - -.. Created with antsibull-docs 2.9.0 - -ansible.netcommon.enable become -- 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``. - -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: - :depth: 1 - - -Synopsis --------- - -- This become plugins allows elevated permissions on a remote network device. - - - - - - - - -Parameters ----------- - -.. raw:: html - - - - - - - - - - - - - - -

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 ------ - -- 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. - - - - - - - -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/grpc_config_module.rst b/docs/grpc_config_module.rst deleted file mode 100644 index 62c5b941a..000000000 --- a/docs/grpc_config_module.rst +++ /dev/null @@ -1,298 +0,0 @@ - -.. Created with antsibull-docs 2.9.0 - -ansible.netcommon.grpc_config module -- 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``. - -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: - :depth: 1 - - -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. - -- grpcio -- protobuf - - - - - - -Parameters ----------- - -.. raw:: html - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

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 ------ - -- 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 --------- - -.. code-block:: yaml - - - - name: Merge static route config - ansible.netcommon.grpc_config: - config: - Cisco-IOS-XR-ip-static-cfg:router-static: - default-vrf: - address-family: - vrfipv4: - vrf-unicast: - vrf-prefixes: - vrf-prefix: - - prefix: "1.2.3.6" - prefix-length: 32 - vrf-route: - vrf-next-hop-table: - vrf-next-hop-next-hop-address: - - next-hop-address: "10.0.2.2" - state: merged - - - name: Merge bgp config - ansible.netcommon.grpc_config: - config: "{{ lookup('file', 'bgp.json') }}" - state: merged - - - name: Find diff - diff: true - ansible.netcommon.grpc_config: - config: "{{ lookup('file', 'bgp_start.yml') }}" - state: merged - - - name: Backup running config - ansible.netcommon.grpc_config: - backup: true - - - - - -Return Values -------------- -The following are the fields unique to this module: - -.. raw:: html - - - - - - - - - - - - - - - - - - - - - - - - - - -

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/grpc_connection.rst b/docs/grpc_connection.rst deleted file mode 100644 index c29d9a522..000000000 --- a/docs/grpc_connection.rst +++ /dev/null @@ -1,513 +0,0 @@ - -.. Created with antsibull-docs 2.9.0 - -ansible.netcommon.grpc connection -- 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``. - -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: - :depth: 1 - - -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 controller node that executes this connection. - -- grpcio -- protobuf - - - - - - -Parameters ----------- - -.. raw:: html - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

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 -~~~~~~~ - -- 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/grpc_get_module.rst b/docs/grpc_get_module.rst deleted file mode 100644 index 55c9d330c..000000000 --- a/docs/grpc_get_module.rst +++ /dev/null @@ -1,230 +0,0 @@ - -.. Created with antsibull-docs 2.9.0 - -ansible.netcommon.grpc_get module -- 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``. - -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: - :depth: 1 - - -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. - -- grpcio -- protobuf - - - - - - -Parameters ----------- - -.. raw:: html - - - - - - - - - - - - - - - - - - - - - - - - - - -

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 ------ - -- 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 --------- - -.. code-block:: yaml - - - - name: Get bgp configuration data - grpc_get: - section: - Cisco-IOS-XR-ip-static-cfg:router-static: - - null - - name: run cli command - grpc_get: - command: "show version" - display: text - - - - - -Return Values -------------- -The following are the fields unique to this module: - -.. raw:: html - - - - - - - - - - - - - - - - - - - - - - -

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 -~~~~~~~ - -- Ganesh Nalawade (@ganeshrn) -- Gomathi Selvi S (@GomathiselviS) - - - -Collection links -~~~~~~~~~~~~~~~~ - -* `Issue Tracker `__ -* `Repository (Sources) `__ - diff --git a/docs/hash_salt_filter.rst b/docs/hash_salt_filter.rst deleted file mode 100644 index 2705189a5..000000000 --- a/docs/hash_salt_filter.rst +++ /dev/null @@ -1,131 +0,0 @@ - -.. Created with antsibull-docs 2.9.0 - -ansible.netcommon.hash_salt filter -- 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``. - -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: - :depth: 1 - - -Synopsis --------- - -- The filter plugin produces the salt from a hashed password. -- Using the parameters below - \ :literal:`password | ansible.netcommon.hash\_salt(template.yml`\ ) - - - - - - - - -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.hash_salt(key1=value1, key2=value2, ...)`` - -.. raw:: html - - - - - - - - - - - - - - -

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 ------ - -- The filter plugin produces the salt from a hashed password. - - -Examples --------- - -.. code-block:: yaml - - - # Using hash_salt - - # playbook - - - name: Set the facts - ansible.builtin.set_fact: - password: "$1$avs$uSTOEMh65ADDBREAKqzvpb9yBMpzd/" - - - name: Invoke hash_salt - ansible.builtin.debug: - msg: "{{ password | ansible.netcommon.hash_salt() }}" - - - # Task Output - # ----------- - # - # TASK [Set the facts] - # ok: [host] => changed=false - # ansible_facts: - # password: $1$avs$uSTOEMh65ADDBREAKqzvpb9yBMpzd/ - - # TASK [Invoke hash_salt] - # ok: [host] => - # msg: avs - - - - - - - -Authors -~~~~~~~ - -- Ken Celenza (@itdependsnetworks) - - -.. 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/httpapi_connection.rst b/docs/httpapi_connection.rst deleted file mode 100644 index ad94d732e..000000000 --- a/docs/httpapi_connection.rst +++ /dev/null @@ -1,668 +0,0 @@ - -.. Created with antsibull-docs 2.9.0 - -ansible.netcommon.httpapi connection -- 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``. - -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: - :depth: 1 - - -Synopsis --------- - -- This connection plugin provides a connection to remote devices over a HTTP(S)-based api. - - - - - - - - -Parameters ----------- - -.. raw:: html - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

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 -~~~~~~~ - -- 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/hwaddr_filter.rst b/docs/hwaddr_filter.rst deleted file mode 100644 index a52363b00..000000000 --- a/docs/hwaddr_filter.rst +++ /dev/null @@ -1,14 +0,0 @@ - -.. Created with antsibull-docs 2.9.0 - -ansible.netcommon.hwaddr filter -+++++++++++++++++++++++++++++++ - -- This redirect is part of the `ansible.netcommon collection `_ (version 6.1.0). - - -- This redirect has been **deprecated**. Please update your tasks to use the new name ``ansible.utils.hwaddr`` instead. - It will be removed in a major release after 2024-01-01 of ansible.netcommon. -- This is a redirect to the ansible.utils.hwaddr filter plugin. -- This redirect does **not** work with Ansible 2.9. -- The collection contains the following information on this deprecation: Use 'ansible.utils.hwaddr' module instead. diff --git a/docs/index.rst b/docs/index.rst deleted file mode 100644 index bbe0b3b5b..000000000 --- a/docs/index.rst +++ /dev/null @@ -1,116 +0,0 @@ - -.. Created with antsibull-docs 2.9.0 - - -Ansible.Netcommon -================= - -Collection version 6.1.0 - -.. contents:: - :local: - :depth: 1 - -Description ------------ - -Ansible Collection with common content to help automate the management of network, security, and cloud devices. - -**Author:** - -* Ansible Network Community (ansible-network) - -**Supported ansible-core versions:** - -* 2.14.0 or newer - -Collection links -~~~~~~~~~~~~~~~~ - -* `Issue Tracker `__ -* `Repository (Sources) `__ - - - -Plugin Index ------------- - -These are the plugins in the ansible.netcommon collection: - - -Modules -~~~~~~~ - -* `cli_backup module `_ -- Back up device configuration from network devices over network\_cli -* `cli_command module `_ -- Run a cli command on cli-based network devices -* `cli_config module `_ -- Push text based configuration to network devices over network\_cli -* `cli_restore module `_ -- Restore device configuration to network devices over network\_cli -* `grpc_config module `_ -- Fetch configuration/state data from gRPC enabled target hosts. -* `grpc_get module `_ -- Fetch configuration/state data from gRPC enabled target hosts. -* `net_get module `_ -- Copy a file from a network device to Ansible Controller -* `net_ping module `_ -- Tests reachability using ping from a network device -* `net_put module `_ -- Copy a file from Ansible Controller to a network device -* `netconf_config module `_ -- netconf device configuration -* `netconf_get module `_ -- Fetch configuration/state data from NETCONF enabled network devices. -* `netconf_rpc module `_ -- Execute operations on NETCONF enabled network devices. -* `network_resource module `_ -- Manage resource modules -* `restconf_config module `_ -- Handles create, update, read and delete of configuration data on RESTCONF enabled devices. -* `restconf_get module `_ -- Fetch configuration/state data from RESTCONF enabled devices. -* `telnet module `_ -- Executes a low-down and dirty telnet command - - -Become Plugins -~~~~~~~~~~~~~~ - -* `enable become `_ -- Switch to elevated permissions on a network device - - -Cache Plugins -~~~~~~~~~~~~~ - -* `memory cache `_ -- RAM backed, non persistent cache. - - -Cliconf Plugins -~~~~~~~~~~~~~~~ - -* `default cliconf `_ -- General purpose cliconf plugin for new platforms - - -Connection Plugins -~~~~~~~~~~~~~~~~~~ - -* `grpc connection `_ -- Provides a persistent connection using the gRPC protocol -* `httpapi connection `_ -- Use httpapi to run command on network appliances -* `libssh connection `_ -- Run tasks using libssh for ssh connection -* `netconf connection `_ -- Provides a persistent connection using the netconf protocol -* `network_cli connection `_ -- Use network\_cli to run command on network appliances -* `persistent connection `_ -- Use a persistent unix socket for connection - - -Filter Plugins -~~~~~~~~~~~~~~ - -* `comp_type5 filter `_ -- The comp\_type5 filter plugin. -* `hash_salt filter `_ -- The hash\_salt filter plugin. -* `parse_cli filter `_ -- parse\_cli filter plugin. -* `parse_cli_textfsm filter `_ -- parse\_cli\_textfsm filter plugin. -* `parse_xml filter `_ -- The parse\_xml filter plugin. -* `pop_ace filter `_ -- Remove ace entries from a acl source of truth. -* `type5_pw filter `_ -- The type5\_pw filter plugin. -* `vlan_expander filter `_ -- The vlan\_expander filter plugin. -* `vlan_parser filter `_ -- The vlan\_parser filter plugin. - - -Httpapi Plugins -~~~~~~~~~~~~~~~ - -* `restconf httpapi `_ -- HttpApi Plugin for devices supporting Restconf API - - -Netconf Plugins -~~~~~~~~~~~~~~~ - -* `default netconf `_ -- Use default netconf plugin to run standard netconf commands as per RFC - - diff --git a/docs/ip4_hex_filter.rst b/docs/ip4_hex_filter.rst deleted file mode 100644 index b1ae7ef50..000000000 --- a/docs/ip4_hex_filter.rst +++ /dev/null @@ -1,14 +0,0 @@ - -.. Created with antsibull-docs 2.9.0 - -ansible.netcommon.ip4_hex filter -++++++++++++++++++++++++++++++++ - -- This redirect is part of the `ansible.netcommon collection `_ (version 6.1.0). - - -- This redirect has been **deprecated**. Please update your tasks to use the new name ``ansible.utils.ipv4_hex`` instead. - It will be removed in a major release after 2024-01-01 of ansible.netcommon. -- This is a redirect to the ansible.utils.ipv4_hex filter plugin. -- This redirect does **not** work with Ansible 2.9. -- The collection contains the following information on this deprecation: Use 'ansible.utils.ip4\_hex' module instead. diff --git a/docs/ipaddr_filter.rst b/docs/ipaddr_filter.rst deleted file mode 100644 index ceac8f6c1..000000000 --- a/docs/ipaddr_filter.rst +++ /dev/null @@ -1,14 +0,0 @@ - -.. Created with antsibull-docs 2.9.0 - -ansible.netcommon.ipaddr filter -+++++++++++++++++++++++++++++++ - -- This redirect is part of the `ansible.netcommon collection `_ (version 6.1.0). - - -- This redirect has been **deprecated**. Please update your tasks to use the new name ``ansible.utils.ipaddr`` instead. - It will be removed in a major release after 2024-01-01 of ansible.netcommon. -- This is a redirect to the ansible.utils.ipaddr filter plugin. -- This redirect does **not** work with Ansible 2.9. -- The collection contains the following information on this deprecation: Use 'ansible.utils.ipaddr' module instead. diff --git a/docs/ipmath_filter.rst b/docs/ipmath_filter.rst deleted file mode 100644 index 5537e0764..000000000 --- a/docs/ipmath_filter.rst +++ /dev/null @@ -1,14 +0,0 @@ - -.. Created with antsibull-docs 2.9.0 - -ansible.netcommon.ipmath filter -+++++++++++++++++++++++++++++++ - -- This redirect is part of the `ansible.netcommon collection `_ (version 6.1.0). - - -- This redirect has been **deprecated**. Please update your tasks to use the new name ``ansible.utils.ipmath`` instead. - It will be removed in a major release after 2024-01-01 of ansible.netcommon. -- This is a redirect to the ansible.utils.ipmath filter plugin. -- This redirect does **not** work with Ansible 2.9. -- The collection contains the following information on this deprecation: Use 'ansible.utils.ipmath' module instead. diff --git a/docs/ipsubnet_filter.rst b/docs/ipsubnet_filter.rst deleted file mode 100644 index bf825c201..000000000 --- a/docs/ipsubnet_filter.rst +++ /dev/null @@ -1,14 +0,0 @@ - -.. Created with antsibull-docs 2.9.0 - -ansible.netcommon.ipsubnet filter -+++++++++++++++++++++++++++++++++ - -- This redirect is part of the `ansible.netcommon collection `_ (version 6.1.0). - - -- This redirect has been **deprecated**. Please update your tasks to use the new name ``ansible.utils.ipsubnet`` instead. - It will be removed in a major release after 2024-01-01 of ansible.netcommon. -- This is a redirect to the ansible.utils.ipsubnet filter plugin. -- This redirect does **not** work with Ansible 2.9. -- The collection contains the following information on this deprecation: Use 'ansible.utils.ipsubnet' module instead. diff --git a/docs/ipv4_filter.rst b/docs/ipv4_filter.rst deleted file mode 100644 index 3bd1f4e19..000000000 --- a/docs/ipv4_filter.rst +++ /dev/null @@ -1,14 +0,0 @@ - -.. Created with antsibull-docs 2.9.0 - -ansible.netcommon.ipv4 filter -+++++++++++++++++++++++++++++ - -- This redirect is part of the `ansible.netcommon collection `_ (version 6.1.0). - - -- This redirect has been **deprecated**. Please update your tasks to use the new name ``ansible.utils.ipv4`` instead. - It will be removed in a major release after 2024-01-01 of ansible.netcommon. -- This is a redirect to the ansible.utils.ipv4 filter plugin. -- This redirect does **not** work with Ansible 2.9. -- The collection contains the following information on this deprecation: Use 'ansible.utils.ipv4' module instead. diff --git a/docs/ipv6_filter.rst b/docs/ipv6_filter.rst deleted file mode 100644 index bc06c22f5..000000000 --- a/docs/ipv6_filter.rst +++ /dev/null @@ -1,14 +0,0 @@ - -.. Created with antsibull-docs 2.9.0 - -ansible.netcommon.ipv6 filter -+++++++++++++++++++++++++++++ - -- This redirect is part of the `ansible.netcommon collection `_ (version 6.1.0). - - -- This redirect has been **deprecated**. Please update your tasks to use the new name ``ansible.utils.ipv6`` instead. - It will be removed in a major release after 2024-01-01 of ansible.netcommon. -- This is a redirect to the ansible.utils.ipv6 filter plugin. -- This redirect does **not** work with Ansible 2.9. -- The collection contains the following information on this deprecation: Use 'ansible.utils.ipv6' module instead. diff --git a/docs/ipwrap_filter.rst b/docs/ipwrap_filter.rst deleted file mode 100644 index d8582536d..000000000 --- a/docs/ipwrap_filter.rst +++ /dev/null @@ -1,14 +0,0 @@ - -.. Created with antsibull-docs 2.9.0 - -ansible.netcommon.ipwrap filter -+++++++++++++++++++++++++++++++ - -- This redirect is part of the `ansible.netcommon collection `_ (version 6.1.0). - - -- This redirect has been **deprecated**. Please update your tasks to use the new name ``ansible.utils.ipwrap`` instead. - It will be removed in a major release after 2024-01-01 of ansible.netcommon. -- This is a redirect to the ansible.utils.ipwrap filter plugin. -- This redirect does **not** work with Ansible 2.9. -- The collection contains the following information on this deprecation: Use 'ansible.utils.ipwrap' module instead. diff --git a/docs/libssh_connection.rst b/docs/libssh_connection.rst deleted file mode 100644 index b091748ee..000000000 --- a/docs/libssh_connection.rst +++ /dev/null @@ -1,590 +0,0 @@ - -.. Created with antsibull-docs 2.9.0 - -ansible.netcommon.libssh 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``. - -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: - :depth: 1 - - -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. - - - - - - - - -Parameters ----------- - -.. raw:: html - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

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 -~~~~~~~ - -- 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/macaddr_filter.rst b/docs/macaddr_filter.rst deleted file mode 100644 index 12f9738c1..000000000 --- a/docs/macaddr_filter.rst +++ /dev/null @@ -1,14 +0,0 @@ - -.. Created with antsibull-docs 2.9.0 - -ansible.netcommon.macaddr filter -++++++++++++++++++++++++++++++++ - -- This redirect is part of the `ansible.netcommon collection `_ (version 6.1.0). - - -- This redirect has been **deprecated**. Please update your tasks to use the new name ``ansible.utils.macaddr`` instead. - It will be removed in a major release after 2024-01-01 of ansible.netcommon. -- This is a redirect to the ansible.utils.macaddr filter plugin. -- This redirect does **not** work with Ansible 2.9. -- The collection contains the following information on this deprecation: Use 'ansible.utils.macaddr' module instead. diff --git a/docs/memory_cache.rst b/docs/memory_cache.rst deleted file mode 100644 index f03bf6674..000000000 --- a/docs/memory_cache.rst +++ /dev/null @@ -1,59 +0,0 @@ - -.. 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/net_get_module.rst b/docs/net_get_module.rst deleted file mode 100644 index 526e6fa78..000000000 --- a/docs/net_get_module.rst +++ /dev/null @@ -1,154 +0,0 @@ - -.. Created with antsibull-docs 2.9.0 - -ansible.netcommon.net_get module -- 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``. - -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: - :depth: 1 - - -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. - -- scp if using protocol=scp with paramiko - - - - - - -Parameters ----------- - -.. raw:: html - - - - - - - - - - - - - - - - - - - - - - -

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 ------ - -- 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 --------- - -.. code-block:: yaml - - - - name: copy file from the network device to Ansible controller - ansible.netcommon.net_get: - src: running_cfg_ios1.txt - - - name: copy file from ios to common location at /tmp - ansible.netcommon.net_get: - src: running_cfg_sw1.txt - dest: /tmp/ios1.txt - - - - - - - -Authors -~~~~~~~ - -- Deepak Agrawal (@dagrawal) - - - -Collection links -~~~~~~~~~~~~~~~~ - -* `Issue Tracker `__ -* `Repository (Sources) `__ - diff --git a/docs/net_ping_module.rst b/docs/net_ping_module.rst deleted file mode 100644 index 1ff5371e7..000000000 --- a/docs/net_ping_module.rst +++ /dev/null @@ -1,281 +0,0 @@ - -.. Created with antsibull-docs 2.9.0 - -ansible.netcommon.net_ping module -- 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``. - -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: - :depth: 1 - - -Synopsis --------- - -- Tests reachability using ping from network device to a remote destination. - -This module has a corresponding action plugin. - - - - - - - -Parameters ----------- - -.. raw:: html - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

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 ------ - -- 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 --------- - -.. code-block:: yaml - - - - name: Test reachability to 10.10.10.10 using default vrf - ansible.netcommon.net_ping: - dest: 10.10.10.10 - - - name: Test reachability to 10.20.20.20 using prod vrf - ansible.netcommon.net_ping: - dest: 10.20.20.20 - vrf: prod - - - name: Test unreachability to 10.30.30.30 using default vrf - ansible.netcommon.net_ping: - dest: 10.30.30.30 - state: absent - - - name: Test reachability to 10.40.40.40 using prod vrf and setting count and source - ansible.netcommon.net_ping: - dest: 10.40.40.40 - source: loopback0 - vrf: prod - count: 20 - - - Note: - - For targets running Python, use the M(ansible.builtin.shell) module along with ping command instead. - - Example: - name: ping - shell: ping -c 1 - - - - - -Return Values -------------- -The following are the fields unique to this module: - -.. raw:: html - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

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/net_put_module.rst b/docs/net_put_module.rst deleted file mode 100644 index a4e00ee5d..000000000 --- a/docs/net_put_module.rst +++ /dev/null @@ -1,174 +0,0 @@ - -.. Created with antsibull-docs 2.9.0 - -ansible.netcommon.net_put module -- 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``. - -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: - :depth: 1 - - -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. - -- scp if using protocol=scp with paramiko - - - - - - -Parameters ----------- - -.. raw:: html - - - - - - - - - - - - - - - - - - - - - - - - - - -

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 ------ - -- 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 --------- - -.. code-block:: yaml - - - - name: copy file from ansible controller to a network device - ansible.netcommon.net_put: - src: running_cfg_ios1.txt - - - name: copy file at root dir of flash in slot 3 of sw1(ios) - ansible.netcommon.net_put: - src: running_cfg_sw1.txt - protocol: sftp - dest: flash3:/running_cfg_sw1.txt - - - - - - - -Authors -~~~~~~~ - -- Deepak Agrawal (@dagrawal) - - - -Collection links -~~~~~~~~~~~~~~~~ - -* `Issue Tracker `__ -* `Repository (Sources) `__ - diff --git a/docs/netconf_config_module.rst b/docs/netconf_config_module.rst deleted file mode 100644 index e84f9a23d..000000000 --- a/docs/netconf_config_module.rst +++ /dev/null @@ -1,648 +0,0 @@ - -.. Created with antsibull-docs 2.9.0 - -ansible.netcommon.netconf_config module -- 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``. - -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: - :depth: 1 - - -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. - -- ncclient - - - - - - -Parameters ----------- - -.. raw:: html - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

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 ------ - -- 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 --------- - -.. code-block:: yaml - - - - name: use lookup filter to provide xml configuration - ansible.netcommon.netconf_config: - content: "{{ lookup('file', './config.xml') }}" - - - name: set ntp server in the device - ansible.netcommon.netconf_config: - content: | - - - - true - - ntp1 -
127.0.0.1
 - - - - - - - name: wipe ntp configuration - ansible.netcommon.netconf_config: - content: | - - - - false - - ntp1 - - - - - - - name: configure interface while providing different private key file path (for connection=netconf) - ansible.netcommon.netconf_config: - backup: true - register: backup_junos_location - vars: - ansible_private_key_file: /home/admin/.ssh/newprivatekeyfile - - - name: configurable backup path - ansible.netcommon.netconf_config: - backup: true - backup_options: - filename: backup.cfg - dir_path: /home/user - - - name: "configure using direct native format configuration (cisco iosxr)" - ansible.netcommon.netconf_config: - format: json - content: - { - "config": - { - "interface-configurations": - { - "@xmlns": "http://cisco.com/ns/yang/Cisco-IOS-XR-ifmgr-cfg", - "interface-configuration": - { - "active": "act", - "description": "test for ansible Loopback999", - "interface-name": "Loopback999", - }, - }, - }, - } - get_filter: - { - "interface-configurations": - { - "@xmlns": "http://cisco.com/ns/yang/Cisco-IOS-XR-ifmgr-cfg", - "interface-configuration": null, - }, - } - - - name: "configure using json string format configuration (cisco iosxr)" - ansible.netcommon.netconf_config: - format: json - content: | - { - "config": { - "interface-configurations": { - "@xmlns": "http://cisco.com/ns/yang/Cisco-IOS-XR-ifmgr-cfg", - "interface-configuration": { - "active": "act", - "description": "test for ansible Loopback999", - "interface-name": "Loopback999" - } - } - } - } - get_filter: | - { - "interface-configurations": { - "@xmlns": "http://cisco.com/ns/yang/Cisco-IOS-XR-ifmgr-cfg", - "interface-configuration": null - } - } - - # Make a round-trip interface description change, diff the before and after - # this demonstrates the use of the native display format and several utilities - # from the ansible.utils collection - - - name: Define the openconfig interface filter - set_fact: - filter: - interfaces: - "@xmlns": "http://openconfig.net/yang/interfaces" - interface: - name: Ethernet2 - - - name: Get the pre-change config using the filter - ansible.netcommon.netconf_get: - source: running - filter: "{{ filter }}" - display: native - register: pre - - - name: Update the description - ansible.utils.update_fact: - updates: - - path: pre.output.data.interfaces.interface.config.description - value: "Configured by ansible {{ 100 | random }}" - register: updated - - - name: Apply the new configuration - ansible.netcommon.netconf_config: - content: - config: - interfaces: "{{ updated.pre.output.data.interfaces }}" - - - name: Get the post-change config using the filter - ansible.netcommon.netconf_get: - source: running - filter: "{{ filter }}" - display: native - register: post - - - name: Show the differences between the pre and post configurations - ansible.utils.fact_diff: - before: "{{ pre.output.data|ansible.utils.to_paths }}" - after: "{{ post.output.data|ansible.utils.to_paths }}" - # TASK [Show the differences between the pre and post configurations] ******** - # --- before - # +++ after - # @@ -1,11 +1,11 @@ - # { - # - "@time-modified": "2020-10-23T12:27:17.462332477Z", - # + "@time-modified": "2020-10-23T12:27:21.744541708Z", - # "@xmlns": "urn:ietf:params:xml:ns:netconf:base:1.0", - # "interfaces.interface.aggregation.config['fallback-timeout']['#text']": "90", - # "interfaces.interface.aggregation.config['fallback-timeout']['@xmlns']": "http://arista.com/yang/openconfig/interfaces/augments", - # "interfaces.interface.aggregation.config['min-links']": "0", - # "interfaces.interface.aggregation['@xmlns']": "http://openconfig.net/yang/interfaces/aggregate", - # - "interfaces.interface.config.description": "Configured by ansible 56", - # + "interfaces.interface.config.description": "Configured by ansible 67", - # "interfaces.interface.config.enabled": "true", - # "interfaces.interface.config.mtu": "0", - # "interfaces.interface.config.name": "Ethernet2", - - - - - -Return Values -------------- -The following are the fields unique to this module: - -.. raw:: html - - - - - - - - - - - - - - - - - - - - - - -

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 -~~~~~~~ - -- Leandro Lisboa Penz (@lpenz) -- Ganesh Nalawade (@ganeshrn) - - - -Collection links -~~~~~~~~~~~~~~~~ - -* `Issue Tracker `__ -* `Repository (Sources) `__ - diff --git a/docs/netconf_connection.rst b/docs/netconf_connection.rst deleted file mode 100644 index 07c1e00b5..000000000 --- a/docs/netconf_connection.rst +++ /dev/null @@ -1,557 +0,0 @@ - -.. Created with antsibull-docs 2.9.0 - -ansible.netcommon.netconf connection -- 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``. - -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: - :depth: 1 - - -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 controller node that executes this connection. - -- ncclient - - - - - - -Parameters ----------- - -.. raw:: html - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

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 -~~~~~~~ - -- 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/netconf_get_module.rst b/docs/netconf_get_module.rst deleted file mode 100644 index b94ea6087..000000000 --- a/docs/netconf_get_module.rst +++ /dev/null @@ -1,399 +0,0 @@ - -.. Created with antsibull-docs 2.9.0 - -ansible.netcommon.netconf_get module -- 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``. - -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: - :depth: 1 - - -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) -- jxmlease (for display=json) -- xmltodict (for display=native) - - - - - - -Parameters ----------- - -.. raw:: html - - - - - - - - - - - - - - - - - - - - - - - - - - -

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 ------ - -- 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 --------- - -.. code-block:: yaml - - - - name: Get running configuration and state data - ansible.netcommon.netconf_get: - - - name: Get configuration and state data from startup datastore - ansible.netcommon.netconf_get: - source: startup - - - name: Get system configuration data from running datastore state (junos) - ansible.netcommon.netconf_get: - source: running - filter: - - - name: Get configuration and state data in JSON format - ansible.netcommon.netconf_get: - display: json - - - name: get schema list using subtree w/ namespaces - ansible.netcommon.netconf_get: - display: json - filter: - lock: never - - - name: get schema list using xpath - ansible.netcommon.netconf_get: - display: xml - filter: /netconf-state/schemas/schema - - - name: get interface configuration with filter (iosxr) - ansible.netcommon.netconf_get: - display: pretty - filter: - lock: if-supported - - - name: Get system configuration data from running datastore state (junos) - ansible.netcommon.netconf_get: - source: running - filter: - lock: if-supported - - - name: Get complete configuration data from running datastore (SROS) - ansible.netcommon.netconf_get: - source: running - filter: - - - name: Get complete state data (SROS) - ansible.netcommon.netconf_get: - filter: - - - name: "get configuration with json filter string and native output (using xmltodict)" - netconf_get: - filter: | - { - "interface-configurations": { - "@xmlns": "http://cisco.com/ns/yang/Cisco-IOS-XR-ifmgr-cfg", - "interface-configuration": null - } - } - display: native - - - name: Define the Cisco IOSXR interface filter - set_fact: - filter: - interface-configurations: - "@xmlns": "http://cisco.com/ns/yang/Cisco-IOS-XR-ifmgr-cfg" - interface-configuration: null - - - name: "get configuration with native filter type using set_facts" - ansible.netcommon.netconf_get: - filter: "{{ filter }}" - display: native - register: result - - - name: "get configuration with direct native filter type" - ansible.netcommon.netconf_get: - filter: - { - "interface-configurations": - { - "@xmlns": "http://cisco.com/ns/yang/Cisco-IOS-XR-ifmgr-cfg", - "interface-configuration": null, - }, - } - display: native - register: result - - # Make a round-trip interface description change, diff the before and after - # this demonstrates the use of the native display format and several utilities - # from the ansible.utils collection - - - name: Define the openconfig interface filter - set_fact: - filter: - interfaces: - "@xmlns": "http://openconfig.net/yang/interfaces" - interface: - name: Ethernet2 - - - name: Get the pre-change config using the filter - ansible.netcommon.netconf_get: - source: running - filter: "{{ filter }}" - display: native - register: pre - - - name: Update the description - ansible.utils.update_fact: - updates: - - path: pre.output.data.interfaces.interface.config.description - value: "Configured by ansible {{ 100 | random }}" - register: updated - - - name: Apply the new configuration - ansible.netcommon.netconf_config: - content: - config: - interfaces: "{{ updated.pre.output.data.interfaces }}" - - - name: Get the post-change config using the filter - ansible.netcommon.netconf_get: - source: running - filter: "{{ filter }}" - display: native - register: post - - - name: Show the differences between the pre and post configurations - ansible.utils.fact_diff: - before: "{{ pre.output.data|ansible.utils.to_paths }}" - after: "{{ post.output.data|ansible.utils.to_paths }}" - # TASK [Show the differences between the pre and post configurations] ******** - # --- before - # +++ after - # @@ -1,11 +1,11 @@ - # { - # - "@time-modified": "2020-10-23T12:27:17.462332477Z", - # + "@time-modified": "2020-10-23T12:27:21.744541708Z", - # "@xmlns": "urn:ietf:params:xml:ns:netconf:base:1.0", - # "interfaces.interface.aggregation.config['fallback-timeout']['#text']": "90", - # "interfaces.interface.aggregation.config['fallback-timeout']['@xmlns']": "http://arista.com/yang/openconfig/interfaces/augments", - # "interfaces.interface.aggregation.config['min-links']": "0", - # "interfaces.interface.aggregation['@xmlns']": "http://openconfig.net/yang/interfaces/aggregate", - # - "interfaces.interface.config.description": "Configured by ansible 56", - # + "interfaces.interface.config.description": "Configured by ansible 67", - # "interfaces.interface.config.enabled": "true", - # "interfaces.interface.config.mtu": "0", - # "interfaces.interface.config.name": "Ethernet2", - - - - - -Return Values -------------- -The following are the fields unique to this module: - -.. raw:: html - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

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 -~~~~~~~ - -- Ganesh Nalawade (@ganeshrn) -- Sven Wisotzky (@wisotzky) - - - -Collection links -~~~~~~~~~~~~~~~~ - -* `Issue Tracker `__ -* `Repository (Sources) `__ - diff --git a/docs/netconf_rpc_module.rst b/docs/netconf_rpc_module.rst deleted file mode 100644 index 7da34cf7b..000000000 --- a/docs/netconf_rpc_module.rst +++ /dev/null @@ -1,293 +0,0 @@ - -.. Created with antsibull-docs 2.9.0 - -ansible.netcommon.netconf_rpc module -- 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``. - -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: - :depth: 1 - - -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) -- jxmlease - - - - - - -Parameters ----------- - -.. raw:: html - - - - - - - - - - - - - - - - - - - - - - - - - - -

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 ------ - -- 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 --------- - -.. code-block:: yaml - - - - name: lock candidate - ansible.netcommon.netconf_rpc: - rpc: lock - content: - target: - candidate: - - - name: unlock candidate - ansible.netcommon.netconf_rpc: - rpc: unlock - xmlns: urn:ietf:params:xml:ns:netconf:base:1.0 - content: "{'target': {'candidate': None}}" - - - name: discard changes - ansible.netcommon.netconf_rpc: - rpc: discard-changes - - - name: get-schema - ansible.netcommon.netconf_rpc: - rpc: get-schema - xmlns: urn:ietf:params:xml:ns:yang:ietf-netconf-monitoring - content: - identifier: ietf-netconf - version: '2011-06-01' - - - name: copy running to startup - ansible.netcommon.netconf_rpc: - rpc: copy-config - content: - source: - running: - target: - startup: - - - name: get schema list with JSON output - ansible.netcommon.netconf_rpc: - rpc: get - content: | - - - - - - display: json - - - name: get schema using XML request - ansible.netcommon.netconf_rpc: - rpc: get-schema - xmlns: urn:ietf:params:xml:ns:yang:ietf-netconf-monitoring - content: | - ietf-netconf-monitoring - 2010-10-04 - display: json - - - - - -Return Values -------------- -The following are the fields unique to this module: - -.. raw:: html - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

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 -~~~~~~~ - -- Ganesh Nalawade (@ganeshrn) -- Sven Wisotzky (@wisotzky) - - - -Collection links -~~~~~~~~~~~~~~~~ - -* `Issue Tracker `__ -* `Repository (Sources) `__ - diff --git a/docs/network_cli_connection.rst b/docs/network_cli_connection.rst deleted file mode 100644 index d1f44cfe4..000000000 --- a/docs/network_cli_connection.rst +++ /dev/null @@ -1,886 +0,0 @@ - -.. Created with antsibull-docs 2.9.0 - -ansible.netcommon.network_cli connection -- 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``. - -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: - :depth: 1 - - -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 controller node that executes this connection. - -- ansible-pylibssh if using \ :emphasis:`ssh\_type=libssh`\ - - - - - - -Parameters ----------- - -.. raw:: html - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

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 -~~~~~~~ - -- 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/network_in_network_filter.rst b/docs/network_in_network_filter.rst deleted file mode 100644 index c633a398c..000000000 --- a/docs/network_in_network_filter.rst +++ /dev/null @@ -1,14 +0,0 @@ - -.. Created with antsibull-docs 2.9.0 - -ansible.netcommon.network_in_network filter -+++++++++++++++++++++++++++++++++++++++++++ - -- This redirect is part of the `ansible.netcommon collection `_ (version 6.1.0). - - -- This redirect has been **deprecated**. Please update your tasks to use the new name ``ansible.utils.network_in_network`` instead. - It will be removed in a major release after 2024-01-01 of ansible.netcommon. -- This is a redirect to the ansible.utils.network_in_network filter plugin. -- This redirect does **not** work with Ansible 2.9. -- The collection contains the following information on this deprecation: Use 'ansible.utils.network\_in\_network' module instead. diff --git a/docs/network_in_usable_filter.rst b/docs/network_in_usable_filter.rst deleted file mode 100644 index d51b0dfef..000000000 --- a/docs/network_in_usable_filter.rst +++ /dev/null @@ -1,14 +0,0 @@ - -.. Created with antsibull-docs 2.9.0 - -ansible.netcommon.network_in_usable filter -++++++++++++++++++++++++++++++++++++++++++ - -- This redirect is part of the `ansible.netcommon collection `_ (version 6.1.0). - - -- This redirect has been **deprecated**. Please update your tasks to use the new name ``ansible.utils.network_in_usable`` instead. - It will be removed in a major release after 2024-01-01 of ansible.netcommon. -- This is a redirect to the ansible.utils.network_in_usable filter plugin. -- This redirect does **not** work with Ansible 2.9. -- The collection contains the following information on this deprecation: Use 'ansible.utils.network\_in\_usable' module instead. diff --git a/docs/network_resource_module.rst b/docs/network_resource_module.rst deleted file mode 100644 index 3aa3e0ec0..000000000 --- a/docs/network_resource_module.rst +++ /dev/null @@ -1,278 +0,0 @@ - -.. Created with antsibull-docs 2.9.0 - -ansible.netcommon.network_resource module -- 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``. - -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: - :depth: 1 - - -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. - - - - - - - -Parameters ----------- - -.. raw:: html - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

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 ------ - -- Refer the individual module documentation for the valid inputs of \ :emphasis:`state`\ and \ :emphasis:`config`\ modules. - - -Examples --------- - -.. code-block:: yaml - - - - name: get list of resource modules for given network_os - ansible.netcommon.network_resource: - register: result - - - name: fetch acl config for - ansible.netcommon.network_resource: - os_name: cisco.ios.ios - name: acls - state: gathered - - - name: manage acl config for cisco.ios.ios network os. - ansible.netcommon.network_resource: - name: acls - config: - - afi: ipv4 - acls: - - name: test_acl - acl_type: extended - aces: - - grant: deny - protocol_options: - tcp: - fin: true - source: - address: 192.0.2.0 - wildcard_bits: 0.0.0.255 - destination: - address: 192.0.3.0 - wildcard_bits: 0.0.0.255 - port_protocol: - eq: www - option: - traceroute: true - ttl: - eq: 10 - state: merged - - - - - -Return Values -------------- -The following are the fields unique to this module: - -.. raw:: html - - - - - - - - - - - - - - - - - - - - - - - - - - -

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/next_nth_usable_filter.rst b/docs/next_nth_usable_filter.rst deleted file mode 100644 index dc8cb3d33..000000000 --- a/docs/next_nth_usable_filter.rst +++ /dev/null @@ -1,14 +0,0 @@ - -.. Created with antsibull-docs 2.9.0 - -ansible.netcommon.next_nth_usable filter -++++++++++++++++++++++++++++++++++++++++ - -- This redirect is part of the `ansible.netcommon collection `_ (version 6.1.0). - - -- This redirect has been **deprecated**. Please update your tasks to use the new name ``ansible.utils.next_nth_usable`` instead. - It will be removed in a major release after 2024-01-01 of ansible.netcommon. -- This is a redirect to the ansible.utils.next_nth_usable filter plugin. -- This redirect does **not** work with Ansible 2.9. -- The collection contains the following information on this deprecation: Use 'ansible.utils.next\_nth\_usable' module instead. diff --git a/docs/nthhost_filter.rst b/docs/nthhost_filter.rst deleted file mode 100644 index 392cfea07..000000000 --- a/docs/nthhost_filter.rst +++ /dev/null @@ -1,14 +0,0 @@ - -.. Created with antsibull-docs 2.9.0 - -ansible.netcommon.nthhost filter -++++++++++++++++++++++++++++++++ - -- This redirect is part of the `ansible.netcommon collection `_ (version 6.1.0). - - -- This redirect has been **deprecated**. Please update your tasks to use the new name ``ansible.utils.nthhost`` instead. - It will be removed in a major release after 2024-01-01 of ansible.netcommon. -- This is a redirect to the ansible.utils.nthhost filter plugin. -- This redirect does **not** work with Ansible 2.9. -- The collection contains the following information on this deprecation: Use 'ansible.utils.nthhost' module instead. diff --git a/docs/parse_cli_filter.rst b/docs/parse_cli_filter.rst deleted file mode 100644 index e33a5f5a0..000000000 --- a/docs/parse_cli_filter.rst +++ /dev/null @@ -1,206 +0,0 @@ - -.. Created with antsibull-docs 2.9.0 - -ansible.netcommon.parse_cli filter -- 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``. - -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: - :depth: 1 - - -Synopsis --------- - -- The filter plugins converts the output of a network device CLI command into structured JSON output. -- Using the parameters below - \ :literal:`xml\_data | ansible.netcommon.parse\_cli(template.yml`\ ) - - - - - - - - -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_cli(key1=value1, key2=value2, ...)`` - -.. raw:: html - - - - - - - - - - - - - - - - - - -

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 ------ - -- 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 --------- - -.. code-block:: yaml - - - # Using parse_cli - - # outputConfig - - # ip dhcp pool Data - # import all - # network 192.168.1.0 255.255.255.0 - # update dns - # default-router 192.168.1.1 - # dns-server 192.168.1.1 8.8.8.8 - # option 42 ip 192.168.1.1 - # domain-name test.local - # lease 8 - - # pconnection.yml - - # --- - # vars: - # dhcp_pool: - # name: "{{ item.name }}" - # network: "{{ item.network_ip }}" - # subnet: "{{ item.network_subnet }}" - # dns_servers: "{{ item.dns_servers_1 }}{{ item.dns_servers_2 }}" - # domain_name: "{{ item.domain_name_0 }}{{ item.domain_name_1 }}{{ item.domain_name_2 }}{{ item.domain_name_3 }}" - # options: "{{ item.options_1 }}{{ item.options_2 }}" - # lease_days: "{{ item.lease_days }}" - # lease_hours: "{{ item.lease_hours }}" - # lease_minutes: "{{ item.lease_minutes }}" - - # keys: - # dhcp_pools: - # value: "{{ dhcp_pool }}" - # items: "^ip dhcp pool ( - # ?P[^\\n]+)\\s+(?:import (?Pall)\\s*)?(?:network (?P[\\d.]+) - # (?P[\\d.]+)?\\s*)?(?:update dns\\s*)?(?:host (?P[\\d.]+) - # (?P[\\d.]+)\\s*)?(?:domain-name (?P[\\w._-]+)\\s+)? - # (?:default-router (?P[\\d.]+)\\s*)?(?:dns-server - # (?P(?:[\\d.]+ ?)+ ?)+\\s*)?(?:domain-name (?P[\\w._-]+)\\s+)? - # (?P(?:option [^\\n]+\\n*\\s*)*)?(?:domain-name (?P[\\w._-]+)\\s+)?(?P(?:option [^\\n]+\\n*\\s*)*)? - # (?:dns-server (?P(?:[\\d.]+ ?)+ ?)+\\s*)?(?:domain-name - # (?P[\\w._-]+)\\s*)?(lease (?P\\d+)(?: (?P\\d+))?(?: (?P\\d+))?\\s*)?(?:update arp)?" - - # playbook - - - name: Add config data - ansible.builtin.set_fact: - opconfig: "{{lookup('ansible.builtin.file', 'outputConfig') }}" - - - name: Parse Data - ansible.builtin.set_fact: - output: "{{ opconfig | parse_cli('pconnection.yml') }}" - - - # Task Output - # ----------- - # - # TASK [Add config data] - # ok: [host] => changed=false - # ansible_facts: - # xml: |- - # ip dhcp pool Data - # import all - # network 192.168.1.0 255.255.255.0 - # update dns - # default-router 192.168.1.1 - # dns-server 192.168.1.1 8.8.8.8 - # option 42 ip 192.168.1.1 - # domain-name test.local - # lease 8 - - # TASK [Parse Data] - # ok: [host] => changed=false - # ansible_facts: - # output: - # dhcp_pools: - # - dns_servers: 192.168.1.1 8.8.8.8 - # domain_name: test.local - # lease_days: 8 - # lease_hours: null - # lease_minutes: null - # name: Data - # network: 192.168.1.0 - # options: |- - # option 42 ip 192.168.1.1 - # subnet: 255.255.255.0 - - - - - - - -Authors -~~~~~~~ - -- Peter Sprygada (@privateip) - - -.. 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/parse_cli_textfsm_filter.rst b/docs/parse_cli_textfsm_filter.rst deleted file mode 100644 index 07da770ac..000000000 --- a/docs/parse_cli_textfsm_filter.rst +++ /dev/null @@ -1,163 +0,0 @@ - -.. Created with antsibull-docs 2.9.0 - -ansible.netcommon.parse_cli_textfsm filter -- 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``. - -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: - :depth: 1 - - -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 - \ :literal:`data | ansible.netcommon.parse\_cli\_textfsm(template.yml`\ ) - - - - - - - - -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_cli_textfsm(key1=value1, key2=value2, ...)`` - -.. raw:: html - - - - - - - - - - - - - - - - - - -

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 ------ - -- Use of the TextFSM filter requires the TextFSM library to be installed. - - -Examples --------- - -.. code-block:: yaml - - - # Using parse_cli_textfsm - - - name: "Fetch command output" - cisco.ios.ios_command: - commands: - - show lldp neighbors - register: lldp_output - - - name: "Invoke parse_cli_textfsm" - ansible.builtin.set_fact: - device_neighbors: "{{ lldp_output.stdout[0] | parse_cli_textfsm('~/ntc-templates/templates/cisco_ios_show_lldp_neighbors.textfsm') }}" - - - name: "Debug" - ansible.builtindebug: - msg: "{{ device_neighbors }}" - - # Task Output - # ----------- - # - # TASK [Fetch command output] - # ok: [rtr-2] - - # TASK [Invoke parse_cli_textfsm] - # ok: [rtr-1] - - # TASK [Debug] - # ok: [rtr-1] => { - # "msg": [ - # { - # "CAPABILITIES": "R", - # "LOCAL_INTERFACE": "Gi0/0", - # "NEIGHBOR": "rtr-3", - # "NEIGHBOR_INTERFACE": "Gi0/0" - # }, - # { - # "CAPABILITIES": "R", - # "LOCAL_INTERFACE": "Gi0/1", - # "NEIGHBOR": "rtr-1", - # "NEIGHBOR_INTERFACE": "Gi0/1" - # } - # ] - # } - - - - - - - -Authors -~~~~~~~ - -- Peter Sprygada (@privateip) - - -.. 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/parse_xml_filter.rst b/docs/parse_xml_filter.rst deleted file mode 100644 index ecd2eb369..000000000 --- a/docs/parse_xml_filter.rst +++ /dev/null @@ -1,238 +0,0 @@ - -.. Created with antsibull-docs 2.9.0 - -ansible.netcommon.parse_xml filter -- 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``. - -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: - :depth: 1 - - -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. - - - - - - - - -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 - - - - - - - - - - - - - - - - - - -

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 ------ - -- To convert the XML output of a network device command into structured JSON output. - - -Examples --------- - -.. code-block:: yaml - - - # Using parse_xml - - # example_output.xml - - # - # - # - # - # - # - # 0/0/CPU0 - # - # true - # ntp-leap-no-warning - # - # - # ntp-mode-client - # true - #
10.1.1.1
- # 0 - # - # -1 - # - # - # - # ntp-mode-client - # true - #
172.16.252.29
- # 255 - # - # 991 - # - # - # - # - # - # - # - - # parse_xml.yml - - # --- - # vars: - # ntp_peers: - # address: "{{ item.address }}" - # reachability: "{{ item.reachability}}" - # keys: - # result: - # value: "{{ ntp_peers }}" - # top: data/ntp/nodes/node/associations - # items: - # address: peer-summary-info/peer-info-common/address - # reachability: peer-summary-info/peer-info-common/reachability - - - - name: Facts setup - ansible.builtin.set_fact: - xml: "{{ lookup('file', 'example_output.xml') }}" - - - name: Parse xml invocation - ansible.builtin.debug: - msg: "{{ xml | ansible.netcommon.parse_xml('parse_xml.yml') }}" - - - # Task Output - # ----------- - # - # TASK [set xml Data] - # ok: [host] => changed=false - # ansible_facts: - # xml: |- - # - # - # - # - # - # - # 0/0/CPU0 - # - # true - # ntp-leap-no-warning - # - # - # ntp-mode-client - # true - #
10.1.1.1
- # 0 - # - # -1 - # - # - # - # ntp-mode-client - # true - #
172.16.252.29
- # 255 - # - # 991 - # - # - # - # - # - # - # - - # TASK [Parse Data] - # ok: [host] => changed=false - # ansible_facts: - # output: - # result: - # - address: - # - 10.1.1.1 - # - 172.16.252.29 - # reachability: - # - '0' - # - '255' - - - - - - - -Authors -~~~~~~~ - -- Ganesh Nalawade (@ganeshrn) - - -.. 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/persistent_connection.rst b/docs/persistent_connection.rst deleted file mode 100644 index cea37e7d7..000000000 --- a/docs/persistent_connection.rst +++ /dev/null @@ -1,214 +0,0 @@ - -.. Created with antsibull-docs 2.9.0 - -ansible.netcommon.persistent 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``. - -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: - :depth: 1 - - -Synopsis --------- - -- This is a helper plugin to allow making other connections persistent. - - - - - - - - -Parameters ----------- - -.. raw:: html - - - - - - - - - - - - - - - - - - - - - - - - - - -

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 -~~~~~~~ - -- 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/pop_ace_filter.rst b/docs/pop_ace_filter.rst deleted file mode 100644 index e1a0bbe54..000000000 --- a/docs/pop_ace_filter.rst +++ /dev/null @@ -1,1213 +0,0 @@ - -.. Created with antsibull-docs 2.9.0 - -ansible.netcommon.pop_ace filter -- 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``. - -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: - :depth: 1 - - -Synopsis --------- - -- This plugin removes specific keys from a provided acl data. -- Using the parameters below - \ :literal:`acls\_data | ansible.netcommon.pop\_ace(filter\_options=filter\_options, match\_criteria=match\_criteria`\ ) - - - - - - - - -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 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

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 ------ - -- The filter plugin has been tested with facts collected for acls resource module on Cisco IOSXE, IOSXR and NXOS. - - -Examples --------- - -.. code-block:: yaml - - - ## Playbook with filter plugin example - vars: - filter_options: - match_all: true - match_criteria: - afi: "ipv4" - source: "192.0.2.0" - destination: "192.0.3.0" - acls_data: - - acls: - - aces: - - destination: - address: 192.0.3.0 - wildcard_bits: 0.0.0.255 - dscp: ef - grant: deny - protocol: icmp - protocol_options: - icmp: - traceroute: true - sequence: 10 - source: - address: 192.0.2.0 - wildcard_bits: 0.0.0.255 - ttl: - eq: 10 - - destination: - host: 198.51.110.0 - port_protocol: - eq: telnet - grant: deny - protocol: tcp - protocol_options: - tcp: - ack: true - sequence: 20 - source: - host: 198.51.100.0 - acl_type: extended - name: "110" - - aces: - - destination: - address: 198.51.101.0 - port_protocol: - eq: telnet - wildcard_bits: 0.0.0.255 - grant: deny - protocol: tcp - protocol_options: - tcp: - ack: true - sequence: 10 - source: - address: 198.51.100.0 - wildcard_bits: 0.0.0.255 - tos: - service_value: 12 - - destination: - address: 192.0.4.0 - port_protocol: - eq: www - wildcard_bits: 0.0.0.255 - dscp: ef - grant: deny - protocol: tcp - protocol_options: - tcp: - ack: true - sequence: 20 - source: - address: 192.0.3.0 - wildcard_bits: 0.0.0.255 - ttl: - lt: 20 - acl_type: extended - name: "123" - - aces: - - grant: deny - sequence: 10 - source: - host: 192.168.1.200 - - grant: deny - sequence: 20 - source: - address: 192.168.2.0 - wildcard_bits: 0.0.0.255 - acl_type: standard - name: std_acl - - aces: - - destination: - address: 192.0.3.0 - port_protocol: - eq: www - wildcard_bits: 0.0.0.255 - grant: deny - option: - traceroute: true - protocol: tcp - protocol_options: - tcp: - fin: true - sequence: 10 - source: - address: 192.0.2.0 - wildcard_bits: 0.0.0.255 - ttl: - eq: 10 - acl_type: extended - name: test - afi: ipv4 - - acls: - - aces: - - destination: - any: true - port_protocol: - eq: telnet - dscp: af11 - grant: deny - protocol: tcp - protocol_options: - tcp: - ack: true - sequence: 10 - source: - any: true - port_protocol: - eq: www - name: R1_TRAFFIC - afi: ipv6 - - tasks: - - name: Remove ace entries from a provided data - ansible.builtin.debug: - msg: "{{ acls_data | ansible.netcommon.pop_ace(filter_options=filter_options, match_criteria=match_criteria) }}" - - ## Output - # PLAY [Filter plugin example pop_ace] ****************************************************************************************************************** - - # TASK [Remove ace entries from a provided data] *********************************************************************************************************** - # ok: [xe_machine] => - # msg: - # clean_acls: - # acls: - # - acls: - # - aces: - # - destination: - # host: 198.51.110.0 - # port_protocol: - # eq: telnet - # grant: deny - # protocol: tcp - # protocol_options: - # tcp: - # ack: true - # sequence: 20 - # source: - # host: 198.51.100.0 - # name: '110' - # - aces: - # - destination: - # address: 198.51.101.0 - # port_protocol: - # eq: telnet - # wildcard_bits: 0.0.0.255 - # grant: deny - # protocol: tcp - # protocol_options: - # tcp: - # ack: true - # sequence: 10 - # source: - # address: 198.51.100.0 - # wildcard_bits: 0.0.0.255 - # tos: - # service_value: 12 - # - destination: - # address: 192.0.4.0 - # port_protocol: - # eq: www - # wildcard_bits: 0.0.0.255 - # dscp: ef - # grant: deny - # protocol: tcp - # protocol_options: - # tcp: - # ack: true - # sequence: 20 - # source: - # address: 192.0.3.0 - # wildcard_bits: 0.0.0.255 - # ttl: - # lt: 20 - # name: '123' - # - aces: - # - grant: deny - # sequence: 10 - # source: - # host: 192.168.1.200 - # - grant: deny - # sequence: 20 - # source: - # address: 192.168.2.0 - # wildcard_bits: 0.0.0.255 - # name: std_acl - # afi: ipv4 - # - acls: - # - aces: - # - destination: - # any: true - # port_protocol: - # eq: telnet - # dscp: af11 - # grant: deny - # protocol: tcp - # protocol_options: - # tcp: - # ack: true - # sequence: 10 - # source: - # any: true - # port_protocol: - # eq: www - # name: R1_TRAFFIC - # afi: ipv6 - # removed_aces: - # acls: - # - acls: - # - aces: - # - destination: - # address: 192.0.3.0 - # wildcard_bits: 0.0.0.255 - # dscp: ef - # grant: deny - # protocol: icmp - # protocol_options: - # icmp: - # traceroute: true - # sequence: 10 - # source: - # address: 192.0.2.0 - # wildcard_bits: 0.0.0.255 - # ttl: - # eq: 10 - # name: '110' - # - aces: - # - destination: - # address: 192.0.3.0 - # port_protocol: - # eq: www - # wildcard_bits: 0.0.0.255 - # grant: deny - # option: - # traceroute: true - # protocol: tcp - # protocol_options: - # tcp: - # fin: true - # sequence: 10 - # source: - # address: 192.0.2.0 - # wildcard_bits: 0.0.0.255 - # ttl: - # eq: 10 - # name: test - # afi: ipv4 - # - acls: [] - # afi: ipv6 - - - ## Playbook with workflow example - _tasks: - - name: Gather ACLs config from device existing ACLs config - cisco.ios.ios_acls: - state: gathered - register: result_gathered - - - name: Setting host facts for pop_ace filter plugin - ansible.builtin.set_fact: - acls_facts: "{{ result_gathered.gathered }}" - filter_options: - match_all: true - match_criteria: - afi: "ipv4" - source: "192.0.2.0" - destination: "192.0.3.0" - - - name: Invoke pop_ace filter plugin - ansible.builtin.set_fact: - clean_acls: "{{ acls_facts | ansible.netcommon.pop_ace(filter_options=filter_options, match_criteria=match_criteria) }}" - - - name: Override ACLs config with device existing ACLs config - cisco.ios.ios_acls: - state: overridden - config: "{{ clean_acls['clean_acls']['acls'] | from_yaml }}" - - ## Output - - # PLAYBOOK: pop_ace_example.yml *********************************************** - - # PLAY [Filter plugin example pop_ace] **************************************** - - # TASK [Gather ACLs config with device existing ACLs config] ********************* - # ok: [xe_machine] => changed=false - # gathered: - # - acls: - # - aces: - # - destination: - # address: 192.0.3.0 - # wildcard_bits: 0.0.0.255 - # dscp: ef - # grant: deny - # protocol: icmp - # protocol_options: - # icmp: - # traceroute: true - # sequence: 10 - # source: - # address: 192.0.2.0 - # wildcard_bits: 0.0.0.255 - # ttl: - # eq: 10 - # - destination: - # host: 198.51.110.0 - # port_protocol: - # eq: telnet - # grant: deny - # protocol: tcp - # protocol_options: - # tcp: - # ack: true - # sequence: 20 - # source: - # host: 198.51.100.0 - # acl_type: extended - # name: '110' - # - aces: - # - destination: - # address: 198.51.101.0 - # port_protocol: - # eq: telnet - # wildcard_bits: 0.0.0.255 - # grant: deny - # protocol: tcp - # protocol_options: - # tcp: - # ack: true - # sequence: 10 - # source: - # address: 198.51.100.0 - # wildcard_bits: 0.0.0.255 - # tos: - # service_value: 12 - # - destination: - # address: 192.0.4.0 - # port_protocol: - # eq: www - # wildcard_bits: 0.0.0.255 - # dscp: ef - # grant: deny - # protocol: tcp - # protocol_options: - # tcp: - # ack: true - # sequence: 20 - # source: - # address: 192.0.3.0 - # wildcard_bits: 0.0.0.255 - # ttl: - # lt: 20 - # acl_type: extended - # name: '123' - # - aces: - # - grant: deny - # sequence: 10 - # source: - # host: 192.168.1.200 - # - grant: deny - # sequence: 20 - # source: - # address: 192.168.2.0 - # wildcard_bits: 0.0.0.255 - # acl_type: standard - # name: std_acl - # - aces: - # - destination: - # address: 192.0.3.0 - # port_protocol: - # eq: www - # wildcard_bits: 0.0.0.255 - # grant: deny - # option: - # traceroute: true - # protocol: tcp - # protocol_options: - # tcp: - # fin: true - # sequence: 10 - # source: - # address: 192.0.2.0 - # wildcard_bits: 0.0.0.255 - # ttl: - # eq: 10 - # acl_type: extended - # name: test - # afi: ipv4 - # - acls: - # - aces: - # - destination: - # any: true - # port_protocol: - # eq: telnet - # dscp: af11 - # grant: deny - # protocol: tcp - # protocol_options: - # tcp: - # ack: true - # sequence: 10 - # source: - # any: true - # port_protocol: - # eq: www - # name: R1_TRAFFIC - # afi: ipv6 - # invocation: - # module_args: - # config: null - # running_config: null - # state: gathered - - # TASK [Setting host facts for pop_ace filter plugin] ************************* - # ok: [xe_machine] => changed=false - # ansible_facts: - # acls_facts: - # - acls: - # - aces: - # - destination: - # address: 192.0.3.0 - # wildcard_bits: 0.0.0.255 - # dscp: ef - # grant: deny - # protocol: icmp - # protocol_options: - # icmp: - # traceroute: true - # sequence: 10 - # source: - # address: 192.0.2.0 - # wildcard_bits: 0.0.0.255 - # ttl: - # eq: 10 - # - destination: - # host: 198.51.110.0 - # port_protocol: - # eq: telnet - # grant: deny - # protocol: tcp - # protocol_options: - # tcp: - # ack: true - # sequence: 20 - # source: - # host: 198.51.100.0 - # acl_type: extended - # name: '110' - # - aces: - # - destination: - # address: 198.51.101.0 - # port_protocol: - # eq: telnet - # wildcard_bits: 0.0.0.255 - # grant: deny - # protocol: tcp - # protocol_options: - # tcp: - # ack: true - # sequence: 10 - # source: - # address: 198.51.100.0 - # wildcard_bits: 0.0.0.255 - # tos: - # service_value: 12 - # - destination: - # address: 192.0.4.0 - # port_protocol: - # eq: www - # wildcard_bits: 0.0.0.255 - # dscp: ef - # grant: deny - # protocol: tcp - # protocol_options: - # tcp: - # ack: true - # sequence: 20 - # source: - # address: 192.0.3.0 - # wildcard_bits: 0.0.0.255 - # ttl: - # lt: 20 - # acl_type: extended - # name: '123' - # - aces: - # - grant: deny - # sequence: 10 - # source: - # host: 192.168.1.200 - # - grant: deny - # sequence: 20 - # source: - # address: 192.168.2.0 - # wildcard_bits: 0.0.0.255 - # acl_type: standard - # name: std_acl - # - aces: - # - destination: - # address: 192.0.3.0 - # port_protocol: - # eq: www - # wildcard_bits: 0.0.0.255 - # grant: deny - # option: - # traceroute: true - # protocol: tcp - # protocol_options: - # tcp: - # fin: true - # sequence: 10 - # source: - # address: 192.0.2.0 - # wildcard_bits: 0.0.0.255 - # ttl: - # eq: 10 - # acl_type: extended - # name: test - # afi: ipv4 - # - acls: - # - aces: - # - destination: - # any: true - # port_protocol: - # eq: telnet - # dscp: af11 - # grant: deny - # protocol: tcp - # protocol_options: - # tcp: - # ack: true - # sequence: 10 - # source: - # any: true - # port_protocol: - # eq: www - # name: R1_TRAFFIC - # afi: ipv6 - # filter_options: - # match_all: true - # match_criteria: - # afi: ipv4 - # destination: 192.0.3.0 - # source: 192.0.2.0 - - # TASK [Invoke pop_ace filter plugin] ***************************************** - # ok: [xe_machine] => changed=false - # ansible_facts: - # clean_acls: - # clean_acls: - # acls: - # - acls: - # - aces: - # - destination: - # host: 198.51.110.0 - # port_protocol: - # eq: telnet - # grant: deny - # protocol: tcp - # protocol_options: - # tcp: - # ack: true - # sequence: 20 - # source: - # host: 198.51.100.0 - # name: '110' - # - aces: - # - destination: - # address: 198.51.101.0 - # port_protocol: - # eq: telnet - # wildcard_bits: 0.0.0.255 - # grant: deny - # protocol: tcp - # protocol_options: - # tcp: - # ack: true - # sequence: 10 - # source: - # address: 198.51.100.0 - # wildcard_bits: 0.0.0.255 - # tos: - # service_value: 12 - # - destination: - # address: 192.0.4.0 - # port_protocol: - # eq: www - # wildcard_bits: 0.0.0.255 - # dscp: ef - # grant: deny - # protocol: tcp - # protocol_options: - # tcp: - # ack: true - # sequence: 20 - # source: - # address: 192.0.3.0 - # wildcard_bits: 0.0.0.255 - # ttl: - # lt: 20 - # name: '123' - # - aces: - # - grant: deny - # sequence: 10 - # source: - # host: 192.168.1.200 - # - grant: deny - # sequence: 20 - # source: - # address: 192.168.2.0 - # wildcard_bits: 0.0.0.255 - # name: std_acl - # afi: ipv4 - # - acls: - # - aces: - # - destination: - # any: true - # port_protocol: - # eq: telnet - # dscp: af11 - # grant: deny - # protocol: tcp - # protocol_options: - # tcp: - # ack: true - # sequence: 10 - # source: - # any: true - # port_protocol: - # eq: www - # name: R1_TRAFFIC - # afi: ipv6 - # removed_aces: - # acls: - # - acls: - # - aces: - # - destination: - # address: 192.0.3.0 - # wildcard_bits: 0.0.0.255 - # dscp: ef - # grant: deny - # protocol: icmp - # protocol_options: - # icmp: - # traceroute: true - # sequence: 10 - # source: - # address: 192.0.2.0 - # wildcard_bits: 0.0.0.255 - # ttl: - # eq: 10 - # name: '110' - # - aces: - # - destination: - # address: 192.0.3.0 - # port_protocol: - # eq: www - # wildcard_bits: 0.0.0.255 - # grant: deny - # option: - # traceroute: true - # protocol: tcp - # protocol_options: - # tcp: - # fin: true - # sequence: 10 - # source: - # address: 192.0.2.0 - # wildcard_bits: 0.0.0.255 - # ttl: - # eq: 10 - # name: test - # afi: ipv4 - # - acls: [] - # afi: ipv6 - - # TASK [Override ACLs config with device existing ACLs config] ******************* - # changed: [xe_machine] => changed=true - # after: - # - acls: - # - aces: - # - destination: - # host: 198.51.110.0 - # port_protocol: - # eq: telnet - # grant: deny - # protocol: tcp - # protocol_options: - # tcp: - # ack: true - # sequence: 20 - # source: - # host: 198.51.100.0 - # acl_type: extended - # name: '110' - # - aces: - # - destination: - # address: 198.51.101.0 - # port_protocol: - # eq: telnet - # wildcard_bits: 0.0.0.255 - # grant: deny - # protocol: tcp - # protocol_options: - # tcp: - # ack: true - # sequence: 10 - # source: - # address: 198.51.100.0 - # wildcard_bits: 0.0.0.255 - # tos: - # service_value: 12 - # - destination: - # address: 192.0.4.0 - # port_protocol: - # eq: www - # wildcard_bits: 0.0.0.255 - # dscp: ef - # grant: deny - # protocol: tcp - # protocol_options: - # tcp: - # ack: true - # sequence: 20 - # source: - # address: 192.0.3.0 - # wildcard_bits: 0.0.0.255 - # ttl: - # lt: 20 - # acl_type: extended - # name: '123' - # - aces: - # - grant: deny - # sequence: 10 - # source: - # host: 192.168.1.200 - # - grant: deny - # sequence: 20 - # source: - # address: 192.168.2.0 - # wildcard_bits: 0.0.0.255 - # acl_type: standard - # name: std_acl - # afi: ipv4 - # - acls: - # - aces: - # - destination: - # any: true - # port_protocol: - # eq: telnet - # dscp: af11 - # grant: deny - # protocol: tcp - # protocol_options: - # tcp: - # ack: true - # sequence: 10 - # source: - # any: true - # port_protocol: - # eq: www - # name: R1_TRAFFIC - # afi: ipv6 - # before: - # - acls: - # - aces: - # - destination: - # address: 192.0.3.0 - # wildcard_bits: 0.0.0.255 - # dscp: ef - # grant: deny - # protocol: icmp - # protocol_options: - # icmp: - # traceroute: true - # sequence: 10 - # source: - # address: 192.0.2.0 - # wildcard_bits: 0.0.0.255 - # ttl: - # eq: 10 - # - destination: - # host: 198.51.110.0 - # port_protocol: - # eq: telnet - # grant: deny - # protocol: tcp - # protocol_options: - # tcp: - # ack: true - # sequence: 20 - # source: - # host: 198.51.100.0 - # acl_type: extended - # name: '110' - # - aces: - # - destination: - # address: 198.51.101.0 - # port_protocol: - # eq: telnet - # wildcard_bits: 0.0.0.255 - # grant: deny - # protocol: tcp - # protocol_options: - # tcp: - # ack: true - # sequence: 10 - # source: - # address: 198.51.100.0 - # wildcard_bits: 0.0.0.255 - # tos: - # service_value: 12 - # - destination: - # address: 192.0.4.0 - # port_protocol: - # eq: www - # wildcard_bits: 0.0.0.255 - # dscp: ef - # grant: deny - # protocol: tcp - # protocol_options: - # tcp: - # ack: true - # sequence: 20 - # source: - # address: 192.0.3.0 - # wildcard_bits: 0.0.0.255 - # ttl: - # lt: 20 - # acl_type: extended - # name: '123' - # - aces: - # - grant: deny - # sequence: 10 - # source: - # host: 192.168.1.200 - # - grant: deny - # sequence: 20 - # source: - # address: 192.168.2.0 - # wildcard_bits: 0.0.0.255 - # acl_type: standard - # name: std_acl - # - aces: - # - destination: - # address: 192.0.3.0 - # port_protocol: - # eq: www - # wildcard_bits: 0.0.0.255 - # grant: deny - # option: - # traceroute: true - # protocol: tcp - # protocol_options: - # tcp: - # fin: true - # sequence: 10 - # source: - # address: 192.0.2.0 - # wildcard_bits: 0.0.0.255 - # ttl: - # eq: 10 - # acl_type: extended - # name: test - # afi: ipv4 - # - acls: - # - aces: - # - destination: - # any: true - # port_protocol: - # eq: telnet - # dscp: af11 - # grant: deny - # protocol: tcp - # protocol_options: - # tcp: - # ack: true - # sequence: 10 - # source: - # any: true - # port_protocol: - # eq: www - # name: R1_TRAFFIC - # afi: ipv6 - # commands: - # - ip access-list extended 110 - # - no 10 deny icmp 192.0.2.0 0.0.0.255 192.0.3.0 0.0.0.255 traceroute dscp ef ttl eq 10 - # - no ip access-list extended test - - - - - - - -Authors -~~~~~~~ - -- Sagar Paul (@KB-perByte) - - -.. 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/previous_nth_usable_filter.rst b/docs/previous_nth_usable_filter.rst deleted file mode 100644 index f8183a71e..000000000 --- a/docs/previous_nth_usable_filter.rst +++ /dev/null @@ -1,14 +0,0 @@ - -.. Created with antsibull-docs 2.9.0 - -ansible.netcommon.previous_nth_usable filter -++++++++++++++++++++++++++++++++++++++++++++ - -- This redirect is part of the `ansible.netcommon collection `_ (version 6.1.0). - - -- This redirect has been **deprecated**. Please update your tasks to use the new name ``ansible.utils.previous_nth_usable`` instead. - It will be removed in a major release after 2024-01-01 of ansible.netcommon. -- This is a redirect to the ansible.utils.previous_nth_usable filter plugin. -- This redirect does **not** work with Ansible 2.9. -- The collection contains the following information on this deprecation: Use 'ansible.utils.previous\_nth\_usable' module instead. diff --git a/docs/reduce_on_network_filter.rst b/docs/reduce_on_network_filter.rst deleted file mode 100644 index 6b2d4fdf8..000000000 --- a/docs/reduce_on_network_filter.rst +++ /dev/null @@ -1,14 +0,0 @@ - -.. Created with antsibull-docs 2.9.0 - -ansible.netcommon.reduce_on_network filter -++++++++++++++++++++++++++++++++++++++++++ - -- This redirect is part of the `ansible.netcommon collection `_ (version 6.1.0). - - -- This redirect has been **deprecated**. Please update your tasks to use the new name ``ansible.utils.reduce_on_network`` instead. - It will be removed in a major release after 2024-01-01 of ansible.netcommon. -- This is a redirect to the ansible.utils.reduce_on_network filter plugin. -- This redirect does **not** work with Ansible 2.9. -- The collection contains the following information on this deprecation: Use 'ansible.utils.reduce\_on\_network' module instead. diff --git a/docs/restconf_config_module.rst b/docs/restconf_config_module.rst deleted file mode 100644 index 2a72e7ed7..000000000 --- a/docs/restconf_config_module.rst +++ /dev/null @@ -1,221 +0,0 @@ - -.. Created with antsibull-docs 2.9.0 - -ansible.netcommon.restconf_config module -- 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``. - -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: - :depth: 1 - - -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 - - - - - - - - - - - - - - - - - - - - - - - - - - -

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 ------ - -- 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 --------- - -.. code-block:: yaml - - - - name: create l3vpn services - ansible.netcommon.restconf_config: - path: /config/ietf-l3vpn-svc:l3vpn-svc/vpn-services - content: | - { - "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" - } - ] - } - - - - - -Return Values -------------- -The following are the fields unique to this module: - -.. raw:: html - - - - - - - - - - - - - - - - - - -

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/restconf_get_module.rst b/docs/restconf_get_module.rst deleted file mode 100644 index 747477ee5..000000000 --- a/docs/restconf_get_module.rst +++ /dev/null @@ -1,177 +0,0 @@ - -.. Created with antsibull-docs 2.9.0 - -ansible.netcommon.restconf_get module -- 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``. - -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: - :depth: 1 - - -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 - - - - - - - - - - - - - - - - - - - - - - -

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 ------ - -- 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 --------- - -.. code-block:: yaml - - - - name: get l3vpn services - ansible.netcommon.restconf_get: - path: /config/ietf-l3vpn-svc:l3vpn-svc/vpn-services - - - - - -Return Values -------------- -The following are the fields unique to this module: - -.. raw:: html - - - - - - - - - - - - - - -

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/restconf_httpapi.rst b/docs/restconf_httpapi.rst deleted file mode 100644 index 320e258c8..000000000 --- a/docs/restconf_httpapi.rst +++ /dev/null @@ -1,97 +0,0 @@ - -.. Created with antsibull-docs 2.9.0 - -ansible.netcommon.restconf httpapi -- 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``. - -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: - :depth: 1 - - -Synopsis --------- - -- This HttpApi plugin provides methods to connect to Restconf API endpoints. - - - - - - - - -Parameters ----------- - -.. raw:: html - - - - - - - - - - - - - - -

Parameter

Comments

-
-

root_path

- -

- string -

- - 		-

Specifies the location of the Restconf root.

-

Default: "/restconf"

-

Configuration:

-
    -
  • -

    Variable: ansible_httpapi_restconf_root

    - -
    • -
-
- - - - - - - - - - - -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/slaac_filter.rst b/docs/slaac_filter.rst deleted file mode 100644 index 9b79fa96d..000000000 --- a/docs/slaac_filter.rst +++ /dev/null @@ -1,14 +0,0 @@ - -.. Created with antsibull-docs 2.9.0 - -ansible.netcommon.slaac filter -++++++++++++++++++++++++++++++ - -- This redirect is part of the `ansible.netcommon collection `_ (version 6.1.0). - - -- This redirect has been **deprecated**. Please update your tasks to use the new name ``ansible.utils.slaac`` instead. - It will be removed in a major release after 2024-01-01 of ansible.netcommon. -- This is a redirect to the ansible.utils.slaac filter plugin. -- This redirect does **not** work with Ansible 2.9. -- The collection contains the following information on this deprecation: Use 'ansible.utils.slaac' module instead. diff --git a/docs/telnet_module.rst b/docs/telnet_module.rst deleted file mode 100644 index d5aa080d2..000000000 --- a/docs/telnet_module.rst +++ /dev/null @@ -1,324 +0,0 @@ - -.. Created with antsibull-docs 2.9.0 - -ansible.netcommon.telnet module -- 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``. - -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: - :depth: 1 - - -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. - - - - - - - -Parameters ----------- - -.. raw:: html - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

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 ------ - -- The \ :literal:`environment`\ keyword does not work with this task - - -Examples --------- - -.. code-block:: yaml - - - - name: send configuration commands to IOS - ansible.netcommon.telnet: - user: cisco - password: cisco - login_prompt: "Username: " - prompts: - - "[>#]" - command: - - terminal length 0 - - configure terminal - - hostname ios01 - - - name: run show commands - ansible.netcommon.telnet: - user: cisco - password: cisco - login_prompt: "Username: " - prompts: - - "[>#]" - command: - - terminal length 0 - - show version - - - - - -Return Values -------------- -The following are the fields unique to this module: - -.. raw:: html - - - - - - - - - - - - - - -

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/type5_pw_filter.rst b/docs/type5_pw_filter.rst deleted file mode 100644 index 1a4546658..000000000 --- a/docs/type5_pw_filter.rst +++ /dev/null @@ -1,142 +0,0 @@ - -.. Created with antsibull-docs 2.9.0 - -ansible.netcommon.type5_pw filter -- 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``. - -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: - :depth: 1 - - -Synopsis --------- - -- Filter plugin to produce cisco type5 hashed password. -- Using the parameters below - \ :literal:`xml\_data | ansible.netcommon.type5\_pw(template.yml`\ ) - - - - - - - - -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.type5_pw(key1=value1, key2=value2, ...)`` - -.. raw:: html - - - - - - - - - - - - - - - - - - -

Parameter

Comments

-
-

password

- -

- string - / required -

- - 		-

The password to be hashed.

-
-
-

salt

- -

- string -

- - 		-

Mention the salt to hash the password.

-
- - - - -Notes ------ - -- The filter plugin generates cisco type5 hashed password. - - -Examples --------- - -.. code-block:: yaml - - - # Using type5_pw - - - name: Set some facts - ansible.builtin.set_fact: - password: "cisco@123" - - - name: Filter type5_pw invocation - ansible.builtin.debug: - msg: "{{ password | ansible.netcommon.type5_pw(salt='avs') }}" - - - # Task Output - # ----------- - # - # TASK [Set some facts] - # ok: [host] => changed=false - # ansible_facts: - # password: cisco@123 - - # TASK [Filter type5_pw invocation] - # ok: [host] => - # msg: $1$avs$uSTOEMh65qzvpb9yBMpzd/ - - - - - - - -Authors -~~~~~~~ - -- Ken Celenza (@itdependsnetworks) - - -.. 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/vlan_expander_filter.rst b/docs/vlan_expander_filter.rst deleted file mode 100644 index 10f346188..000000000 --- a/docs/vlan_expander_filter.rst +++ /dev/null @@ -1,137 +0,0 @@ - -.. Created with antsibull-docs 2.9.0 - -ansible.netcommon.vlan_expander filter -- 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``. - -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: - :depth: 1 - - -Synopsis --------- - -- 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 ------------------- - -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 - - - - - - - - - - - - - - -

Parameter

Comments

-
-

data

- -

- string - / required -

- - 		-

This option represents a string containing the range of vlans.

-
- - - - -Notes ------ - -- The filter plugin extends vlans when data provided in range or comma separated. - - -Examples --------- - -.. code-block:: yaml - - - # Using vlan_expander - - - name: Setting host facts for vlan_expander filter plugin - ansible.builtin.set_fact: - vlan_ranges: "1,10-12,15,20-22" - - - name: Invoke vlan_expander filter plugin - ansible.builtin.set_fact: - extended_vlans: "{{ vlan_ranges | ansible.netcommon.vlan_expander }}" - - - # Task Output - # ----------- - # - # TASK [Setting host facts for vlan_expander filter plugin] - # ok: [host] => changed=false - # ansible_facts: - # vlan_ranges: 1,10-12,15,20-22 - - # TASK [Invoke vlan_expander filter plugin] - # ok: [host] => changed=false - # ansible_facts: - # extended_vlans: - # - 1 - # - 10 - # - 11 - # - 12 - # - 15 - # - 20 - # - 21 - # - 22 - - - - - - - -Authors -~~~~~~~ - -- Akira Yokochi (@akira6592) - - -.. 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/vlan_parser_filter.rst b/docs/vlan_parser_filter.rst deleted file mode 100644 index 9cc6e5921..000000000 --- a/docs/vlan_parser_filter.rst +++ /dev/null @@ -1,194 +0,0 @@ - -.. Created with antsibull-docs 2.9.0 - -ansible.netcommon.vlan_parser filter -- 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``. - -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: - :depth: 1 - - -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. -- \ :literal:`vlans\_data | ansible.netcommon.vlan\_parser(first\_line\_len = 20, other\_line\_len=20`\ ) - - - - - - - - -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.vlan_parser(key1=value1, key2=value2, ...)`` - -.. raw:: html - - - - - - - - - - - - - - - - - - - - - - -

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 ------ - -- The filter plugin extends vlans when data provided in range or comma separated. - - -Examples --------- - -.. code-block:: yaml - - - # Using vlan_parser - - - name: Setting host facts for vlan_parser filter plugin - ansible.builtin.set_fact: - vlans: - [ - 100, - 1688, - 3002, - 3003, - 3004, - 3005, - 3102, - 3103, - 3104, - 3105, - 3802, - 3900, - 3998, - 3999, - ] - - - name: Invoke vlan_parser filter plugin - ansible.builtin.set_fact: - vlans_ranges: "{{ vlans | ansible.netcommon.vlan_parser(first_line_len = 20, other_line_len=20) }}" - - - # Task Output - # ----------- - # - # TASK [Setting host facts for vlan_parser filter plugin] - # ok: [host] => changed=false - # ansible_facts: - # vlans: - # - 100 - # - 1688 - # - 3002 - # - 3003 - # - 3004 - # - 3005 - # - 3102 - # - 3103 - # - 3104 - # - 3105 - # - 3802 - # - 3900 - # - 3998 - # - 3999 - - # TASK [Invoke vlan_parser filter plugin] - # ok: [host] => changed=false - # ansible_facts: - # msg: - # - 100,1688,3002-3005 - # - 3102-3105,3802,3900 - # - 3998,3999 - - - - - - - -Authors -~~~~~~~ - -- Steve Dodd (@idahood) - - -.. 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) `__ -