diff --git a/docs/vyos.vyos.vyos_config_module.rst b/docs/vyos.vyos.vyos_config_module.rst index d1b1c7b0..054ae208 100644 --- a/docs/vyos.vyos.vyos_config_module.rst +++ b/docs/vyos.vyos.vyos_config_module.rst @@ -1,511 +1,512 @@ .. _vyos.vyos.vyos_config_module: ********************* vyos.vyos.vyos_config ********************* **Manage VyOS configuration on remote device** Version added: 1.0.0 .. contents:: :local: :depth: 1 Synopsis -------- - This module provides configuration file management of VyOS devices. It provides arguments for managing both the configuration file and state of the active configuration. All configuration statements are based on `set` and `delete` commands in the device configuration. Parameters ---------- .. raw:: html
Parameter Choices/Defaults Comments
allow_password_change
string
    Choices:
  • all
  • plaintext ←
  • encrypted
  • none
The allow_password_change argument specifies whether any configuration lines which would change a user's password should be filtered out. By default only plaintext password changes are allowed and any encrypted-password keys are filtered out. In order to allow all password updates, both plaintext and encrypted, set this argument to all.
Not applied when replace is set to config; the candidate is loaded as-is via VyOS's native load, which has no equivalent filtering mechanism.
backup
boolean
    Choices:
  • no ←
  • yes
The backup argument will backup the current devices active configuration to the Ansible control host prior to making any changes. If the backup_options value is not given, the backup file will be located in the backup folder in the playbook root directory or role root directory, if playbook is part of an ansible role. If the directory does not exist, it is created.
backup_options
dictionary
This is a dict object containing configurable options related to backup file path. The value of this option is read only when backup is set to yes, if backup is set to no this option will be silently ignored.
dir_path
path
This option provides the path ending with directory name in which the backup configuration file will be stored. If the directory does not exist it will be first created and the filename is either the value of filename or default filename as described in filename options description. If the path value is not given in that case a backup directory will be created in the current working directory and backup configuration will be copied in filename within backup directory.
filename
string
The filename to be used to store the backup configuration. If the filename is not given it will be generated based on the hostname, current time and date in format defined by <hostname>_config.<current-date>@<current-time>
comment
string
Default:
"configured by vyos_config"
Allows a commit description to be specified to be included when the configuration is committed. If the configuration is not changed or committed, this argument is ignored.
config
string
The config argument specifies the base configuration to use to compare against the desired configuration. If this value is not specified, the module will automatically retrieve the current active configuration from the remote device. The configuration lines in the option value should be similar to how it will appear if present in the running-configuration of the device including indentation to ensure idempotency and correct diff.
Ignored when replace is set to config.
confirm
string
    Choices:
  • automatic
  • manual
  • none ←
The confirm argument will tell vyos to revert to the previous configuration if not explicitly confirmed after applying the new config. When set to automatic this module will automatically confirm the configuration, if the current session remains working with the new config. When set to manual, this module does not issue the confirmation itself.
confirm_timeout
integer
Default:
10
Minutes to wait for confirmation before reverting the configuration. Does not apply when confirm is set to none .
lines
list / elements=string
The ordered set of commands that should be configured in the section. The commands must be the exact same commands as found in the device running-config as found in the device running-config to ensure idempotency and correct diff. Be sure to note the configuration command syntax as some commands are automatically modified by the device config parser.
Not supported when replace is set to config -- see replace below.
match
string
    Choices:
  • line ←
  • none
The match argument controls the method used to match against the current active configuration. By default, the desired config is matched against the active config and the deltas are loaded. If the match argument is set to none the active configuration is ignored and the configuration is always loaded.
Ignored when replace is set to config, since no line-level diff is computed in that mode.
replace
string
    Choices:
  • line ←
  • config
Controls how the module applies configuration to the device.
When set to line (default), the module computes a set/delete command diff and pushes only the changed lines -- this is the existing behavior, unchanged.
When set to config, the module uploads the full candidate configuration (src) to the device and issues VyOS's native load command in configuration mode, which replaces the running configuration wholesale with the candidate's exact contents. VyOS's own configuration engine performs the reconciliation, rather than the module computing per-line deltas. This mirrors the mechanism offered by cisco.iosxr.iosxr_config's replace=config.
replace=config requires src and does not accept lines -- there is no way to convert flat set/delete commands into the hierarchical form load requires without re-implementing VyOS's own config-tree builder.
As with src in the default line mode, the module does not validate the candidate's contents or format under replace=config -- supplying a well-formed, complete configuration is the caller's responsibility.
replace=config requires the device to accept file transfer (SCP) over the same network_cli SSH session used for configuration commands.
replace=config writes the candidate to a fixed path on the device (overwritten on each run, matching cisco.iosxr.iosxr_config's own replace=config precedent). Running replace=config concurrently against the same host is not supported.
Any configuration present on the device but omitted from the candidate will be removed, including management interfaces, SSH access, and login users if they are omitted. Always supply a complete configuration, never a partial one.
When capturing a candidate from the device's own output (for example via show configuration) rather than from a trusted, separately maintained source, be aware that VyOS may return masked placeholder values (for example a run of literal asterisks) in place of local users' encrypted-password/plaintext-password values when queried through automation, even though the identical command returns the real value when typed interactively at a terminal. Pushing a masked capture back through replace=config sends the literal placeholder as the new password value; VyOS's own commit-time validation is expected to reject an obviously malformed hash, but a masked value that happens to pass basic format validation could apply silently. Prefer sourcing replace=config candidates from a trusted, version-controlled artifact rather than a live automated capture whenever the configuration contains local password-based users.
Even under check_mode, the candidate is written to a temporary file on the device so that VyOS's own compare can produce an accurate preview diff. No commit occurs in check mode.
When combined with backup=yes, the value of changed reflects whether the backup file's content changed on the Ansible control node, not whether the device configuration changed -- this is existing behavior in the shared netcommon action plugin backing config-family modules across collections, not specific to replace=config.
save
boolean
    Choices:
  • no ←
  • yes
The save argument controls whether or not changes made to the active configuration are saved to disk. This is independent of committing the config. When set to True, the active configuration is saved.
src
path
The src argument specifies the path to the source config file to load. The source config file can either be in bracket format or set format. The source file can include Jinja2 template variables. The configuration lines in the source file should be similar to how it will appear if present in the running-configuration of the device including indentation to ensure idempotency and correct diff.
When replace is set to config, src is required and must contain a complete configuration in hierarchical/bracket format -- the same format produced by show configuration or found in /config/config.boot. Flat set/delete command format (as produced by show configuration commands) is not accepted in that mode; VyOS's native load command rejects it with a parse error.

Notes ----- .. note:: - Tested against VyOS 1.3.8, 1.4.2, the upcoming 1.5, and the rolling release of spring 2025. - This module works with connection ``ansible.netcommon.network_cli``. See `the VyOS OS Platform Options <../network/user_guide/platform_vyos.html>`_. - 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. - ``replace=config`` currently has no way to scope its effect to part of the configuration; it always operates against the entire device configuration. There is no ``path`` parameter to constrain it to a subtree. - For more information on using Ansible to manage network devices see the :ref:`Ansible Network Guide ` Examples -------- .. code-block:: yaml - name: configure the remote device vyos.vyos.vyos_config: lines: - set system host-name {{ inventory_hostname }} - set service lldp - delete service dhcp-server - name: backup and load from file vyos.vyos.vyos_config: src: vyos.cfg backup: true - name: render a Jinja2 template onto the VyOS router vyos.vyos.vyos_config: src: vyos_template.j2 - name: revert after ten minutes, if connection is lost vyos.vyos.vyos_config: src: vyos_template.j2 confirm: automatic - name: for idempotency, use full-form commands vyos.vyos.vyos_config: lines: # - set int eth eth2 description 'OUTSIDE' - set interface ethernet eth2 description 'OUTSIDE' - name: configurable backup path vyos.vyos.vyos_config: backup: true backup_options: filename: backup.cfg dir_path: /home/user - - name: replace the entire running config with a full candidate (native load) + - name: capture the complete hierarchical configuration for editing # replace=config requires the complete desired configuration in # hierarchical/bracket format -- never a partial one, and never flat - # set-command format. A safe pattern is to back up the current config, - # edit it, then replace with the edited whole, as shown here. + # set-command format. `backup: true` alone won't work here: it captures + # flat set-command output (via `show configuration commands`), which + # replace=config's underlying `load` command rejects. Capture the + # hierarchical form directly instead, edit it, then replace with the + # edited whole, as shown here. + vyos.vyos.vyos_command: + commands: "show configuration" + register: current_config + + - name: (edit current_config.stdout[0] as needed, save it locally, then) vyos.vyos.vyos_config: - backup: true - backup_options: - filename: pre_replace_backup.cfg - register: backup_result - - - name: (edit backup_result's backup file as needed, then) - vyos.vyos.vyos_config: - src: /home/user/pre_replace_backup_edited.cfg + src: /home/user/edited_config.cfg replace: config Return Values ------------- Common return values are documented `here `_, the following are the fields unique to this module: .. raw:: html
Key Returned Description
backup_path
string
when backup is yes
The full path to the backup file

Sample:
/playbooks/ansible/backup/vyos_config.2016-07-16@22:28:34
commands
list
always
In replace=line mode (default), the list of set/delete commands sent to the device.
In replace=config mode, contains only the single load <path> command actually issued to the device -- not an itemized diff. See diff for the actual change content, sourced from VyOS's own compare output.

Sample:
['...', '...']
date
string
when backup is yes
The date extracted from the backup file name

Sample:
2016-07-16
filename
string
when backup is yes and filename is not specified in backup options
The name of the backup file

Sample:
vyos_config.2016-07-16@22:28:34
filtered
list
always
The list of configuration commands removed to avoid a load failure.
Not populated when replace is set to config.

Sample:
['...', '...']
shortname
string
when backup is yes and filename is not specified in backup options
The full path to the backup file excluding the timestamp

Sample:
/playbooks/ansible/backup/vyos_config
time
string
when backup is yes
The time extracted from the backup file name

Sample:
22:28:34


Status ------ Authors ~~~~~~~ - Nathaniel Case (@Qalthos) diff --git a/docs/vyos.vyos.vyos_user_module.rst b/docs/vyos.vyos.vyos_user_module.rst index 42b8ccce..0f1ab9a2 100644 --- a/docs/vyos.vyos.vyos_user_module.rst +++ b/docs/vyos.vyos.vyos_user_module.rst @@ -1,514 +1,518 @@ .. _vyos.vyos.vyos_user_module: ******************* vyos.vyos.vyos_user ******************* **Manage the collection of local users on VyOS device** Version added: 1.0.0 .. contents:: :local: :depth: 1 Synopsis -------- - This module provides declarative management of the local usernames configured on network devices. It allows playbooks to manage either individual usernames or the collection of usernames in the current running config. It also supports purging usernames from the configuration that are not explicitly defined. Parameters ---------- .. raw:: html
Parameter Choices/Defaults Comments
aggregate
list / elements=dictionary
The set of username objects to be configured on the remote VyOS device. The list entries can either be the username or a hash of username and properties. This argument is mutually exclusive with the name argument.

aliases: users, collection
configured_password
string
The password to be configured on the VyOS device. The password needs to be provided in clear and it will be encrypted on the device.
encrypted_password
string
The encrypted password of the user account on the remote device. Note that unlike the configured_password argument, this argument ignores the update_password and updates if the value is different from the one in the device running config.
full_name
string
The full_name argument provides the full name of the user account to be created on the remote device. This argument accepts any text string value.
name
string / required
The username to be configured on the VyOS device. This argument accepts a string value and is mutually exclusive with the aggregate argument.
public_keys
list / elements=dictionary
Public keys for authentiction over SSH.
key
string / required
Public key string (base64 encoded)
name
string / required
Name of the key (usually in the form of user@hostname)
type
string / required
    Choices:
  • ssh-dss
  • ssh-rsa
  • ecdsa-sha2-nistp256
  • ecdsa-sha2-nistp384
  • ssh-ed25519
  • ecdsa-sha2-nistp521
    • +
  • sk-ecdsa-sha2-nistp256@openssh.com
    • +
  • sk-ssh-ed25519@openssh.com
Type of the key
state
string
    Choices:
  • present
  • absent
Configures the state of the username definition as it relates to the device operational configuration. When set to present, the username(s) should be configured in the device active configuration and when set to absent the username(s) should not be in the device active configuration
update_password
string
    Choices:
  • on_create
  • always
Since passwords are encrypted in the device running config, this argument will instruct the module when to change the password. When set to always, the password will always be updated in the device and when set to on_create the password will be updated only if the username is created.
configured_password
string
The password to be configured on the VyOS device. The password needs to be provided in clear and it will be encrypted on the device.
encrypted_password
string
The encrypted password of the user account on the remote device. Note that unlike the configured_password argument, this argument ignores the update_password and updates if the value is different from the one in the device running config.
full_name
string
The full_name argument provides the full name of the user account to be created on the remote device. This argument accepts any text string value.
name
string
The username to be configured on the VyOS device. This argument accepts a string value and is mutually exclusive with the aggregate argument.
public_keys
list / elements=dictionary
Public keys for authentiction over SSH.
key
string / required
Public key string (base64 encoded)
name
string / required
Name of the key (usually in the form of user@hostname)
type
string / required
    Choices:
  • ssh-dss
  • ssh-rsa
  • ecdsa-sha2-nistp256
  • ecdsa-sha2-nistp384
  • ssh-ed25519
  • ecdsa-sha2-nistp521
    • +
  • sk-ecdsa-sha2-nistp256@openssh.com
    • +
  • sk-ssh-ed25519@openssh.com
Type of the key
purge
boolean
    Choices:
  • no ←
  • yes
Instructs the module to consider the resource definition absolute. It will remove any previously configured usernames on the device with the exception of the `admin` user (the current defined set of users).
state
string
    Choices:
  • present ←
  • absent
Configures the state of the username definition as it relates to the device operational configuration. When set to present, the username(s) should be configured in the device active configuration and when set to absent the username(s) should not be in the device active configuration
update_password
string
    Choices:
  • on_create
  • always ←
Since passwords are encrypted in the device running config, this argument will instruct the module when to change the password. When set to always, the password will always be updated in the device and when set to on_create the password will be updated only if the username is created.

Notes ----- .. note:: - Tested against VyOS 1.3.8, 1.4.2, the upcoming 1.5, and the rolling release of spring 2025. - This module works with connection ``ansible.netcommon.network_cli``. See `the VyOS OS Platform Options <../network/user_guide/platform_vyos.html>`_. - For more information on using Ansible to manage network devices see the :ref:`Ansible Network Guide ` Examples -------- .. code-block:: yaml - name: create a new user vyos.vyos.vyos_user: name: ansible configured_password: password state: present - name: remove all users except admin vyos.vyos.vyos_user: purge: true - name: set multiple users to level operator vyos.vyos.vyos_user: aggregate: - name: netop - name: netend state: present - name: Change Password for User netop vyos.vyos.vyos_user: name: netop configured_password: '{{ new_password }}' update_password: always state: present Return Values ------------- Common return values are documented `here `_, the following are the fields unique to this module: .. raw:: html
Key Returned Description
commands
list
always
The list of configuration mode commands to send to the device

Sample:
['set system login user authentication plaintext-password password']


Status ------ Authors ~~~~~~~ - Trishna Guha (@trishnaguha) diff --git a/plugins/modules/vyos_config.py b/plugins/modules/vyos_config.py index fe3b7072..43dc6f7c 100644 --- a/plugins/modules/vyos_config.py +++ b/plugins/modules/vyos_config.py @@ -1,626 +1,627 @@ #!/usr/bin/python # # This file is part of Ansible # # Ansible is free software: you can redistribute it and/or modify # it under the terms of the GNU General Public License as published by # the Free Software Foundation, either version 3 of the License, or # (at your option) any later version. # # Ansible is distributed in the hope that it will be useful, # but WITHOUT ANY WARRANTY; without even the implied warranty of # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the # GNU General Public License for more details. # # You should have received a copy of the GNU General Public License # along with Ansible. If not, see . # from __future__ import absolute_import, division, print_function __metaclass__ = type DOCUMENTATION = """ module: vyos_config author: Nathaniel Case (@Qalthos) short_description: Manage VyOS configuration on remote device description: - This module provides configuration file management of VyOS devices. It provides arguments for managing both the configuration file and state of the active configuration. All configuration statements are based on `set` and `delete` commands in the device configuration. version_added: 1.0.0 extends_documentation_fragment: - vyos.vyos.vyos notes: - Tested against VyOS 1.3.8, 1.4.2, the upcoming 1.5, and the rolling release of spring 2025. - This module works with connection C(ansible.netcommon.network_cli). See L(the VyOS OS Platform Options,../network/user_guide/platform_vyos.html). - 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. - C(replace=config) currently has no way to scope its effect to part of the configuration; it always operates against the entire device configuration. There is no C(path) parameter to constrain it to a subtree. options: lines: description: - The ordered set of commands that should be configured in the section. The commands must be the exact same commands as found in the device running-config as found in the device running-config to ensure idempotency and correct diff. Be sure to note the configuration command syntax as some commands are automatically modified by the device config parser. - Not supported when C(replace) is set to C(config) -- see C(replace) below. type: list elements: str src: description: - The C(src) argument specifies the path to the source config file to load. The source config file can either be in bracket format or set format. The source file can include Jinja2 template variables. The configuration lines in the source file should be similar to how it will appear if present in the running-configuration of the device including indentation to ensure idempotency and correct diff. - When C(replace) is set to C(config), C(src) is required and must contain a complete configuration in hierarchical/bracket format -- the same format produced by C(show configuration) or found in C(/config/config.boot). Flat C(set)/C(delete) command format (as produced by C(show configuration commands)) is not accepted in that mode; VyOS's native C(load) command rejects it with a parse error. type: path match: description: - The C(match) argument controls the method used to match against the current active configuration. By default, the desired config is matched against the active config and the deltas are loaded. If the C(match) argument is set to C(none) the active configuration is ignored and the configuration is always loaded. - Ignored when C(replace) is set to C(config), since no line-level diff is computed in that mode. type: str default: line choices: - line - none backup: description: - The C(backup) argument will backup the current devices active configuration to the Ansible control host prior to making any changes. If the C(backup_options) value is not given, the backup file will be located in 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. type: bool default: no comment: description: - Allows a commit description to be specified to be included when the configuration is committed. If the configuration is not changed or committed, this argument is ignored. default: configured by vyos_config type: str confirm: description: - The C(confirm) argument will tell vyos to revert to the previous configuration if not explicitly confirmed after applying the new config. When set to C(automatic) this module will automatically confirm the configuration, if the current session remains working with the new config. When set to C(manual), this module does not issue the confirmation itself. type: str default: none choices: - automatic - manual - none confirm_timeout: description: - Minutes to wait for confirmation before reverting the configuration. Does not apply when C(confirm) is set to C(none) . type: int default: 10 config: description: - The C(config) argument specifies the base configuration to use to compare against the desired configuration. If this value is not specified, the module will automatically retrieve the current active configuration from the remote device. The configuration lines in the option value should be similar to how it will appear if present in the running-configuration of the device including indentation to ensure idempotency and correct diff. - Ignored when C(replace) is set to C(config). type: str save: description: - The C(save) argument controls whether or not changes made to the active configuration are saved to disk. This is independent of committing the config. When set to C(True), the active configuration is saved. type: bool default: no backup_options: description: - This is a dict object containing configurable options related to backup file path. The value of this option is read only when C(backup) is set to I(yes), if C(backup) is set to I(no) this option will be silently ignored. suboptions: filename: description: - 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 _config.@ type: str dir_path: description: - 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 C(filename) or default filename as described in C(filename) options description. If the path value is not given in that case a I(backup) directory will be created in the current working directory and backup configuration will be copied in C(filename) within I(backup) directory. type: path type: dict replace: description: - Controls how the module applies configuration to the device. - When set to C(line) (default), the module computes a set/delete command diff and pushes only the changed lines -- this is the existing behavior, unchanged. - When set to C(config), the module uploads the full candidate configuration (C(src)) to the device and issues VyOS's native C(load) command in configuration mode, which replaces the running configuration wholesale with the candidate's exact contents. VyOS's own configuration engine performs the reconciliation, rather than the module computing per-line deltas. This mirrors the mechanism offered by C(cisco.iosxr.iosxr_config)'s C(replace=config). - C(replace=config) requires C(src) and does not accept C(lines) -- there is no way to convert flat set/delete commands into the hierarchical form C(load) requires without re-implementing VyOS's own config-tree builder. - As with C(src) in the default C(line) mode, the module does not validate the candidate's contents or format under C(replace=config) -- supplying a well-formed, complete configuration is the caller's responsibility. - C(replace=config) requires the device to accept file transfer (SCP) over the same C(network_cli) SSH session used for configuration commands. - C(replace=config) writes the candidate to a fixed path on the device (overwritten on each run, matching C(cisco.iosxr.iosxr_config)'s own C(replace=config) precedent). Running C(replace=config) concurrently against the same host is not supported. - Any configuration present on the device but omitted from the candidate will be removed, including management interfaces, SSH access, and login users if they are omitted. Always supply a complete configuration, never a partial one. - When capturing a candidate from the device's own output (for example via C(show configuration)) rather than from a trusted, separately maintained source, be aware that VyOS may return masked placeholder values (for example a run of literal asterisks) in place of local users' C(encrypted-password)/C(plaintext-password) values when queried through automation, even though the identical command returns the real value when typed interactively at a terminal. Pushing a masked capture back through C(replace=config) sends the literal placeholder as the new password value; VyOS's own commit-time validation is expected to reject an obviously malformed hash, but a masked value that happens to pass basic format validation could apply silently. Prefer sourcing C(replace=config) candidates from a trusted, version-controlled artifact rather than a live automated capture whenever the configuration contains local password-based users. - Even under C(check_mode), the candidate is written to a temporary file on the device so that VyOS's own C(compare) can produce an accurate preview diff. No C(commit) occurs in check mode. - When combined with C(backup=yes), the value of C(changed) reflects whether the backup file's content changed on the Ansible control node, not whether the device configuration changed -- this is existing behavior in the shared netcommon action plugin backing config-family modules across collections, not specific to C(replace=config). type: str default: line choices: - line - config allow_password_change: description: - The C(allow_password_change) argument specifies whether any configuration lines which would change a user's password should be filtered out. By default only plaintext password changes are allowed and any encrypted-password keys are filtered out. In order to allow all password updates, both plaintext and encrypted, set this argument to C(all). - Not applied when C(replace) is set to C(config); the candidate is loaded as-is via VyOS's native C(load), which has no equivalent filtering mechanism. type: str default: plaintext choices: - all - plaintext - encrypted - none """ EXAMPLES = """ - name: configure the remote device vyos.vyos.vyos_config: lines: - set system host-name {{ inventory_hostname }} - set service lldp - delete service dhcp-server - name: backup and load from file vyos.vyos.vyos_config: src: vyos.cfg backup: true - name: render a Jinja2 template onto the VyOS router vyos.vyos.vyos_config: src: vyos_template.j2 - name: revert after ten minutes, if connection is lost vyos.vyos.vyos_config: src: vyos_template.j2 confirm: automatic - name: for idempotency, use full-form commands vyos.vyos.vyos_config: lines: # - set int eth eth2 description 'OUTSIDE' - set interface ethernet eth2 description 'OUTSIDE' - name: configurable backup path vyos.vyos.vyos_config: backup: true backup_options: filename: backup.cfg dir_path: /home/user -- name: replace the entire running config with a full candidate (native load) +- name: capture the complete hierarchical configuration for editing # replace=config requires the complete desired configuration in # hierarchical/bracket format -- never a partial one, and never flat - # set-command format. A safe pattern is to back up the current config, - # edit it, then replace with the edited whole, as shown here. + # set-command format. `backup: true` alone won't work here: it captures + # flat set-command output (via `show configuration commands`), which + # replace=config's underlying `load` command rejects. Capture the + # hierarchical form directly instead, edit it, then replace with the + # edited whole, as shown here. + vyos.vyos.vyos_command: + commands: "show configuration" + register: current_config + +- name: (edit current_config.stdout[0] as needed, save it locally, then) vyos.vyos.vyos_config: - backup: true - backup_options: - filename: pre_replace_backup.cfg - register: backup_result - -- name: (edit backup_result's backup file as needed, then) - vyos.vyos.vyos_config: - src: /home/user/pre_replace_backup_edited.cfg + src: /home/user/edited_config.cfg replace: config """ RETURN = """ commands: description: - In C(replace=line) mode (default), the list of set/delete commands sent to the device. - In C(replace=config) mode, contains only the single C(load ) command actually issued to the device -- not an itemized diff. See C(diff) for the actual change content, sourced from VyOS's own C(compare) output. returned: always type: list sample: ['...', '...'] filtered: description: - The list of configuration commands removed to avoid a load failure. - Not populated when C(replace) is set to C(config). returned: always type: list sample: ['...', '...'] backup_path: description: The full path to the backup file returned: when backup is yes type: str sample: /playbooks/ansible/backup/vyos_config.2016-07-16@22:28:34 filename: description: The name of the backup file returned: when backup is yes and filename is not specified in backup options type: str sample: vyos_config.2016-07-16@22:28:34 shortname: description: The full path to the backup file excluding the timestamp returned: when backup is yes and filename is not specified in backup options type: str sample: /playbooks/ansible/backup/vyos_config date: description: The date extracted from the backup file name returned: when backup is yes type: str sample: "2016-07-16" time: description: The time extracted from the backup file name returned: when backup is yes type: str sample: "22:28:34" """ import os import re import tempfile from ansible.module_utils._text import to_bytes, to_text from ansible.module_utils.basic import AnsibleModule from ansible.module_utils.connection import ConnectionError from ansible_collections.vyos.vyos.plugins.module_utils.network.vyos.vyos import ( copy_file, get_config, get_connection, load_config, run_commands, ) DEFAULT_COMMENT = "configured by vyos_config" PASSWORD_NEEDLE = re.compile( r"(?:set|delete) system login user \S+ authentication (encrypted|plaintext)-password", ) def get_candidate(module): contents = module.params["src"] or module.params["lines"] if module.params["src"]: contents = contents.splitlines() if len(contents) > 0: line = contents[0].split() if len(line) > 0 and line[0] in ("set", "delete"): contents = format_commands(contents) contents = "\n".join(contents) return contents def format_commands(commands): """ This function format the input commands and removes the prepend white spaces for command lines having 'set' or 'delete' and it skips empty lines. :param commands: :return: list of commands """ return [ line.strip() if line.split()[0] in ("set", "delete") else line for line in commands if len(line.strip()) > 0 ] def diff_config(commands, config): config = [str(c).replace("'", "") for c in config.splitlines()] updates = list() visited = set() for line in commands: item = str(line).replace("'", "") if not item.startswith("set") and not item.startswith("delete"): raise ValueError("line must start with either `set` or `delete`") elif item.startswith("set") and item not in config: updates.append(line) elif item.startswith("delete"): if not config: updates.append(line) else: item = re.sub(r"delete", "set", item) for entry in config: if entry.startswith(item) and line not in visited: updates.append(line) visited.add(line) return list(updates) def sanitize_config(config, result, allow): result["filtered"] = list() if allow == "all": return index_to_filter = list() for index, line in enumerate(list(config)): found = PASSWORD_NEEDLE.search(line) if found is None: continue if allow == found[1]: continue result["filtered"].append(line) index_to_filter.append(index) # Delete all filtered configs for filter_index in sorted(index_to_filter, reverse=True): del config[filter_index] def run(module, result): # get the current active config from the node or passed in via # the config param config = module.params["config"] or get_config(module) # create the candidate config object from the arguments candidate = get_candidate(module) # create loadable config that includes only the configuration updates connection = get_connection(module) try: response = connection.get_diff( candidate=candidate, running=config, diff_match=module.params["match"], ) except ConnectionError as exc: module.fail_json(msg=to_text(exc, errors="surrogate_then_replace")) commands = response.get("config_diff") allow_password_change = module.params["allow_password_change"] sanitize_config(commands, result, allow=allow_password_change) result["commands"] = commands commit = not module.check_mode comment = module.params["comment"] confirm = None if module.params["confirm"] == "automatic" or module.params["confirm"] == "manual": confirm = module.params["confirm_timeout"] diff = None if commands: diff = load_config(module, commands, commit=commit, comment=comment, confirm=confirm) if module.params["confirm"] == "automatic": run_commands(module, ["configure", "confirm", "exit"]) if result.get("filtered"): result["warnings"].append( "Some configuration commands were removed, please see the filtered key", ) result["changed"] = True if module._diff: result["diff"] = {"prepared": diff} def run_replace_config(module, result): # replace=config: push the full candidate to the device and let VyOS's # own `load` command perform the replacement natively, rather than # computing a set/delete diff in Python. # # Deliberately smaller than cisco.iosxr's equivalent implementation: # - No bidirectional pre-diff to decide whether anything changed -- # confirmed on real VyOS 1.5 hardware that `load` of an # already-applied file, followed by `compare`, natively reports # "No changes between working and active configurations" with no # Python-side pre-check needed. # - No special `replace=` argument threaded through load_config()/ # edit_config() -- confirmed that `load ` behaves as an ordinary # configuration command through the existing configure/compare/commit # flow already implemented in Cliconf.edit_config(), unmodified. # # Candidate format requirement (hierarchical/bracket, not flat # set/delete) is enforced by VyOS's own `load` parser, not by this # module -- confirmed empirically: flat set-command input produces # "ValueError: Failed to parse config: Syntax error...". # module.params["src"] is already the rendered file *content* by this # point, not a path -- netcommon's generic action plugin for src-based # network config modules reads the local file and substitutes its # (Jinja2-rendered) content into this param before the module runs. Same # assumption get_candidate() already relies on elsewhere in this file. candidate = to_bytes(module.params["src"], errors="surrogate_or_strict") tmp = tempfile.NamedTemporaryFile(delete=False) local_path = tmp.name try: tmp.write(candidate) tmp.close() # Fixed remote filename, always overwritten -- same precedent as # cisco.iosxr.iosxr_config's copy_file_to_node(), which always # writes to the same "/harddisk:/ansible_config.txt". Avoids # per-run temp-file accumulation on the device, at the accepted # cost (shared with iosxr_config) that two concurrent replace=config # runs against the same host could race on this path. remote_path = "/tmp/ansible_vyos_replace.cfg" copy_file(module, local_path, remote_path, "scp") finally: os.unlink(local_path) commit = not module.check_mode comment = module.params["comment"] confirm = None if module.params["confirm"] == "automatic" or module.params["confirm"] == "manual": confirm = module.params["confirm_timeout"] diff = load_config( module, ["load %s" % remote_path], commit=commit, comment=comment, confirm=confirm, ) if module.params["confirm"] == "automatic" and diff and not module.check_mode: run_commands(module, ["configure", "confirm", "exit"]) result["commands"] = ["load %s" % remote_path] result["filtered"] = [] result["changed"] = bool(diff) if module._diff: result["diff"] = {"prepared": diff} def main(): backup_spec = dict(filename=dict(), dir_path=dict(type="path")) argument_spec = dict( src=dict(type="path"), lines=dict(type="list", elements="str"), match=dict(default="line", choices=["line", "none"]), comment=dict(default=DEFAULT_COMMENT), confirm=dict(choices=["automatic", "manual", "none"], default="none"), confirm_timeout=dict(type="int", default=10), config=dict(), backup=dict(type="bool", default=False), backup_options=dict(type="dict", options=backup_spec), save=dict(type="bool", default=False), replace=dict(type="str", default="line", choices=["line", "config"]), allow_password_change=dict( default="plaintext", choices=["all", "encrypted", "plaintext", "none"], ), ) mutually_exclusive = [("lines", "src")] required_if = [("replace", "config", ["src"])] module = AnsibleModule( argument_spec=argument_spec, mutually_exclusive=mutually_exclusive, required_if=required_if, supports_check_mode=True, ) warnings = list() result = dict(changed=False, warnings=warnings) if module.params["backup"]: result["__backup__"] = get_config(module=module) if module.params["replace"] == "config": run_replace_config(module, result) elif any((module.params["src"], module.params["lines"])): run(module, result) if module.params["save"]: diff = run_commands(module, commands=["configure", "compare saved"])[1] if diff not in { "[edit]", "No changes between working and saved configurations.\n\n[edit]", }: if not module.check_mode: run_commands(module, commands=["save"]) result["changed"] = True run_commands(module, commands=["exit"]) if ( result.get("changed") and module.params["replace"] != "config" and any((module.params["src"], module.params["lines"])) ): msg = ( "To ensure idempotency and correct diff the input configuration lines should be" " similar to how they appear if present in" " the running configuration on device" ) if module.params["src"]: msg += " including the indentation" if "warnings" in result: result["warnings"].append(msg) else: result["warnings"] = msg module.exit_json(**result) if __name__ == "__main__": main() diff --git a/tests/integration/targets/vyos_config/tests/cli/replace_config.yaml b/tests/integration/targets/vyos_config/tests/cli/replace_config.yaml index c71a8d5f..1e208275 100644 --- a/tests/integration/targets/vyos_config/tests/cli/replace_config.yaml +++ b/tests/integration/targets/vyos_config/tests/cli/replace_config.yaml @@ -1,260 +1,289 @@ --- - debug: msg="START cli/replace_config.yaml on connection={{ ansible_connection }}" # SAFETY NOTE: replace=config requires a COMPLETE configuration in # hierarchical/bracket format (the same format `show configuration` / # /config/config.boot use) -- never flat set/delete commands (VyOS's `load` # rejects those with a parse error) and never a partial candidate (anything # omitted is deleted, including management interfaces, SSH, and login # users). Every step below operates on a full baseline captured live from # the device itself, edited in place -- never a minimal hand-written or # statically-shipped candidate. This also sidesteps a real safety concern: # a checked-in static fixture would either need fake device-specific data # (interface hw-ids, password hashes) that's wrong for every real target, # or genuine credentials baked into git -- capturing live avoids both. # # NOTE on `src` / templates/replace_config_candidate.cfg: this file's # entire content is the single Jinja2 expression # "{{ replace_config_candidate_content }}". netcommon's action plugin # (_handle_src_option) reads whatever `src` points to and renders it as a # Jinja2 template using the play's own templar *before* the module runs -- # this lets us point `src` at one static, checked-in, device-agnostic file # for every task below, and change only the in-memory fact # (replace_config_candidate_content) each time, with zero local file # writes and therefore no delegate_to/connection wrangling at all. # This mechanism is deprecated upstream (removal after 2028-01-01) in favor # of a `content:` module parameter -- cisco.iosxr.iosxr_config already has # one; vyos_config does not yet. Adding `content:` to vyos_config, mirroring # iosxr_config, would let this test drop the deprecated path entirely, but # that's real module-feature scope beyond this PR, not test plumbing. # # NOTE on `backup`: intentionally not combined with the idempotency # assertions in this file. `backup=yes`'s `changed` reflects whether the # backup file on the control node changed, not whether the device changed # (see DOCUMENTATION) -- this is pre-existing, shared netcommon action # plugin behavior, not specific to replace=config, and asserting on it here # would conflate two unrelated things. # -# NOTE on teardown: this file captures the device's true pre-test -# configuration *before* making any changes (original_full_config below) +# NOTE on teardown: this file captures the device's true pre-test SAVED +# configuration *before* making any changes (original_config_capture below) # and restores exactly that via the same replace=config mechanism the rest # of the file exercises, inside an `always` block -- so a failure partway # through (not just a clean run) still leaves the device as it was found, # rather than at a hard-coded value that may differ from whatever was # actually there originally. +# +# NOTE on unsaved changes: the restore above is only correct if the device +# had NO unsaved running-config changes before this test started -- this +# file cannot safely capture or restore the live running config (see the +# masked-secrets note below), only the saved state in config.boot. The +# pre-test check immediately below fails fast rather than silently +# discarding any pre-existing unsaved work. + +- name: check for pre-existing unsaved changes before this test begins + vyos.vyos.vyos_command: + commands: + - configure + - compare saved + - exit + register: pre_test_save_diff + +- name: fail fast if the device has unsaved changes before this test starts + ansible.builtin.assert: + that: + - >- + pre_test_save_diff.stdout[1] in + ['[edit]', 'No changes between working and saved configurations.\n\n[edit]'] + fail_msg: >- + This device has unsaved configuration changes from before this test + started. Teardown restores from a capture of /config/config.boot (the + saved state) taken before setup, and cannot safely preserve unsaved + running-config changes that predate this test -- doing so would + silently discard them. Save or discard any pending changes on this + device before running this test. - name: capture original full config before any changes, for teardown restoration vyos.vyos.vyos_command: commands: "cat /config/config.boot" register: original_config_capture - name: safety check -- fail fast if the device masked secrets in the original capture ansible.builtin.assert: that: - "'****************' not in original_config_capture.stdout[0]" fail_msg: >- show configuration returned masked secret placeholders in this capture. This is a known VyOS behavior when querying via automation (see DOCUMENTATION note on replace=config); this test cannot safely continue with a masked candidate. Re-run against a lab image/session where show configuration returns real values, or adjust the baseline capture method. - block: - name: setup baseline marker value vyos.vyos.vyos_config: lines: - set system option reboot-on-upgrade-failure '7' match: none # save=true is required here: commit alone updates the running config # but not /config/config.boot, which our baseline capture below reads # directly. Without an explicit save, config.boot can reflect a stale # value from any earlier save in the device's history rather than what # was just committed -- confirmed as the root cause of a real failure # during development (a stale, unrelated value silently made it into # the candidate instead of this task's freshly-committed one). save: true - name: capture full hierarchical baseline config from the device # cat /config/config.boot directly, rather than `show configuration` -- # confirmed during development that `show configuration` returns masked # placeholder values for local users' password hashes when queried via # automation (vyos_command/network_cli), even though the same rendering # shows real values when typed interactively. /config/config.boot is the # same underlying file `show configuration` renders (confirmed identical # structure during development), read directly rather than through # VyOS's `show` masking layer. vyos.vyos.vyos_command: commands: "cat /config/config.boot" register: baseline_show # VyOS appears to mask local users' encrypted-password/plaintext-password # values (a run of literal asterisks) specifically when show configuration # is queried through automation (vyos_command/network_cli), even though the # identical command returns the real hash when typed interactively at a # terminal -- observed directly during development of this test. Pushing a # masked capture back through replace=config sends the literal placeholder # as the new password value and fails at commit (see DOCUMENTATION for the # broader implication of this for replace=config generally). Fail fast here # with a clear, actionable message rather than letting that surface as a # confusing device-side "Invalid encrypted password" commit failure deep # inside the actual test. - name: safety check -- fail fast if the device masked secrets in this capture ansible.builtin.assert: that: - "'****************' not in baseline_show.stdout[0]" fail_msg: >- show configuration returned masked secret placeholders in this capture. This is a known VyOS behavior when querying via automation (see DOCUMENTATION note on replace=config); this test cannot safely continue with a masked candidate. Re-run against a lab image/session where show configuration returns real values, or adjust the baseline capture method. - name: build edited candidate content (v1 -- change the marker value only) ansible.builtin.set_fact: edited_candidate_v1: >- {{ baseline_show.stdout[0] | replace('reboot-on-upgrade-failure "7"', 'reboot-on-upgrade-failure "12"') }} # Fail fast here if the substitution above silently didn't match -- # config.boot quotes leaf values (reboot-on-upgrade-failure "7"), and a # search string that misses that quoting produces a silent no-op edit # rather than an error, which is a real bug caught during development: # the candidate ends up byte-identical to the (possibly stale) capture, # and any resulting diff reflects leftover device state rather than this # test's intended edit. - name: sanity check the marker edit actually took effect ansible.builtin.assert: that: - ('reboot-on-upgrade-failure "12"' in edited_candidate_v1) - ('reboot-on-upgrade-failure "7"' not in edited_candidate_v1) fail_msg: >- The marker substitution did not match anything in the captured baseline -- edited_candidate_v1 is identical to the raw capture. Check that the baseline actually contains reboot-on-upgrade-failure "7" (quoted) and that the setup task's save=true actually persisted before this capture ran. - name: sanity check candidate still contains SSH/management essentials ansible.builtin.assert: that: - "'service' in edited_candidate_v1" - "'ssh' in edited_candidate_v1" - "'login' in edited_candidate_v1" - name: replace with edited full config (native load) register: result diff: true vyos.vyos.vyos_config: src: "{{ role_path }}/templates/replace_config_candidate.cfg" replace: config vars: replace_config_candidate_content: "{{ edited_candidate_v1 }}" - assert: that: - result.changed == true - result.commands == ["load /tmp/ansible_vyos_replace.cfg"] # replace=config surfaces VyOS's own compare() output verbatim in # diff, not an itemized set/delete list -- commands is deliberately # not the change content in this mode (see RETURN docs). Checking # the specific new value (not just the field name) is deliberate -- # a weaker check here previously let a wrong-value regression through # undetected for several tasks. - ('reboot-on-upgrade-failure "12"' in (result.diff.prepared | default(''))) - name: verify connectivity survived vyos.vyos.vyos_facts: gather_subset: min register: facts_check - assert: that: - facts_check is succeeded - name: re-run the identical replace (idempotency check, no backup involved) register: result_repeat vyos.vyos.vyos_config: src: "{{ role_path }}/templates/replace_config_candidate.cfg" replace: config vars: replace_config_candidate_content: "{{ edited_candidate_v1 }}" - assert: that: - result_repeat.changed == false - name: confirm replace=config rejects a candidate without src register: no_src_result ignore_errors: true vyos.vyos.vyos_config: replace: config - assert: that: - no_src_result is failed - "'src' in no_src_result.msg" - name: confirm replace=config rejects lines+src together register: lines_and_src_result ignore_errors: true vyos.vyos.vyos_config: replace: config src: "{{ role_path }}/templates/replace_config_candidate.cfg" lines: - "set system host-name foo" vars: replace_config_candidate_content: "{{ edited_candidate_v1 }}" - assert: that: - lines_and_src_result is failed - name: build edited candidate content (v2 -- further marker change, for check_mode) ansible.builtin.set_fact: edited_candidate_v2: >- {{ edited_candidate_v1 | replace('reboot-on-upgrade-failure "12"', 'reboot-on-upgrade-failure "20"') }} - name: sanity check the v2 marker edit actually took effect ansible.builtin.assert: that: - ('reboot-on-upgrade-failure "20"' in edited_candidate_v2) - ('reboot-on-upgrade-failure "12"' not in edited_candidate_v2) - name: check_mode preview does not commit check_mode: true diff: true register: check_result vyos.vyos.vyos_config: src: "{{ role_path }}/templates/replace_config_candidate.cfg" replace: config vars: replace_config_candidate_content: "{{ edited_candidate_v2 }}" - assert: that: - check_result.changed == true - ('reboot-on-upgrade-failure "20"' in (check_result.diff.prepared | default(''))) - name: confirm check_mode preview above was not actually applied vyos.vyos.vyos_command: commands: "show configuration commands | match reboot-on-upgrade-failure" register: post_check_value - assert: that: - "'20' not in post_check_value.stdout[0]" - "'12' in post_check_value.stdout[0]" always: - - name: teardown -- restore the true original configuration captured before any changes + - name: teardown -- restore the true original saved configuration captured before any changes vyos.vyos.vyos_config: src: "{{ role_path }}/templates/replace_config_candidate.cfg" replace: config save: true vars: replace_config_candidate_content: "{{ original_config_capture.stdout[0] }}" - debug: msg="END cli/replace_config.yaml on connection={{ ansible_connection }}"