diff --git a/changelogs/fragments/t6828-vyos_config-enforce.yml b/changelogs/fragments/t6828-vyos_config-enforce.yml new file mode 100644 index 00000000..f1f63603 --- /dev/null +++ b/changelogs/fragments/t6828-vyos_config-enforce.yml @@ -0,0 +1,3 @@ +--- +minor_changes: + - vyos_config - Add `enforce` match mode, which enforces the supplied configuration as the desired end-state. diff --git a/docs/vyos.vyos.vyos_config_module.rst b/docs/vyos.vyos.vyos_config_module.rst index bf91bb0f..2f6f8b7e 100644 --- a/docs/vyos.vyos.vyos_config_module.rst +++ b/docs/vyos.vyos.vyos_config_module.rst @@ -1,458 +1,461 @@ .. _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.
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 true, if backup is set to false 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.
confirm
string
    Choices:
  • automatic
  • manual
    • -
  • none ←
    • +
  • 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.
+
Defaults to automatic when match is set to enforce, since enforce can generate delete commands for configuration not mentioned in the candidate and a bad commit should self-revert rather than leave the device unreachable. Defaults to none for all other match values.
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.
match
string
    Choices:
  • line ←
    • +
  • enforce
  • 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.
+
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. If the match argument is set to enforce, the supplied lines or src are treated as the complete desired end-state of the configuration, rather than a set of deltas to apply. enforce enforces only the top-level configuration sections present in the supplied candidate as complete end-states; existing configuration within those sections but not mentioned in the candidate is removed, so enforce can generate delete commands for configuration the candidate does not mention. Top-level sections the candidate does not reference at all are left completely untouched. enforce is intended for candidates made up of set commands only; supplying delete lines alongside match=enforce is not supported and will raise an error.
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.

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. - 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: + match: enforce 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 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
The list of configuration commands sent to the device

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

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/cliconf/vyos.py b/plugins/cliconf/vyos.py index 96c24c15..e693f820 100644 --- a/plugins/cliconf/vyos.py +++ b/plugins/cliconf/vyos.py @@ -1,356 +1,426 @@ # (c) 2017 Red Hat Inc. # # 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 = """ author: Ansible Networking Team (@ansible-network) name: vyos short_description: Use vyos cliconf to run command on VyOS platform description: - This vyos plugin provides low level abstraction apis for sending and receiving CLI commands from VyOS network devices. version_added: 1.0.0 options: config_commands: description: - Specifies a list of commands that can make configuration changes to the target device. - When `ansible_network_single_user_mode` is enabled, if a command sent to the device is present in this list, the existing cache is invalidated. version_added: 2.0.0 type: list elements: str default: [] vars: - name: ansible_vyos_config_commands """ import json import re from ansible.errors import AnsibleConnectionFailure from ansible.module_utils._text import to_text from ansible.module_utils.common._collections_compat import Mapping +from ansible.plugins.cliconf import CliconfBase from ansible_collections.ansible.netcommon.plugins.module_utils.network.common.config import ( NetworkConfig, ) from ansible_collections.ansible.netcommon.plugins.module_utils.network.common.utils import to_list -from ansible_collections.ansible.netcommon.plugins.plugin_utils.cliconf_base import CliconfBase + +from ansible_collections.vyos.vyos.plugins.cliconf_utils.vyosconf import VyosConf class Cliconf(CliconfBase): __rpc__ = CliconfBase.__rpc__ + [ "commit", "discard_changes", "get_diff", "run_commands", ] def __init__(self, *args, **kwargs): super(Cliconf, self).__init__(*args, **kwargs) self._device_info = {} def get_device_info(self): if not self._device_info: device_info = {} device_info["network_os"] = "vyos" reply = self.get("show version") data = to_text(reply, errors="surrogate_or_strict").strip() match = re.search(r"Version:\s*(.*)", data) if match: device_info["network_os_version"] = match.group(1) if device_info["network_os_version"]: match = re.search(r"VyOS\s*(\d+\.\d+)", device_info["network_os_version"]) if match: device_info["network_os_major_version"] = match.group(1) match = re.search(r"(?:HW|Hardware) model:\s*(\S+)", data) if match: device_info["network_os_model"] = match.group(1) reply = self.get("show host name") device_info["network_os_hostname"] = to_text( reply, errors="surrogate_or_strict", ).strip() self._device_info = device_info return self._device_info def get_config(self, flags=None, format=None): if format: option_values = self.get_option_values() if format not in option_values["format"]: raise ValueError( "'format' value %s is invalid. Valid values of format are %s" % (format, ", ".join(option_values["format"])), ) if not flags: flags = [] if format == "text": command = "show configuration" else: command = "show configuration commands" command += " ".join(to_list(flags)) command = command.strip() out = self.send_command(command) return out def edit_config( - self, candidate=None, commit=True, replace=None, diff=False, comment=None, confirm=None + self, + candidate=None, + commit=True, + replace=None, + diff=False, + comment=None, + confirm=None, ): resp = {} operations = self.get_device_operations() self.check_edit_config_capability(operations, candidate, commit, replace, comment) results = [] requests = [] self.send_command("configure") for cmd in to_list(candidate): if not isinstance(cmd, Mapping): cmd = {"command": cmd} results.append(self.send_command(**cmd)) requests.append(cmd["command"]) out = self.get("compare") out = to_text(out, errors="surrogate_or_strict") diff_config = out if not out.startswith("No changes") else None if diff_config: if commit: try: self.commit(comment, confirm) except AnsibleConnectionFailure as e: msg = "commit failed: %s" % e.message self.discard_changes() raise AnsibleConnectionFailure(msg) else: self.send_command("exit") else: self.discard_changes() else: self.send_command("exit") if ( to_text(self._connection.get_prompt(), errors="surrogate_or_strict") .strip() .endswith("#") ): self.discard_changes() if diff_config: resp["diff"] = diff_config resp["response"] = results resp["request"] = requests return resp def get( self, command=None, prompt=None, answer=None, sendonly=False, newline=True, output=None, check_all=False, ): if not command: raise ValueError("must provide value of command to execute") if output: raise ValueError("'output' value %s is not supported for get" % output) return self.send_command( command=command, prompt=prompt, answer=answer, sendonly=sendonly, newline=newline, check_all=check_all, ) def commit(self, comment=None, confirm=None): if confirm: if comment: command = 'commit-confirm {0} comment "{1}"'.format(confirm, comment) else: command = "commit-confirm {0}".format(confirm) self.send_command(command, "Proceed?", "\n") else: if comment: command = 'commit comment "{0}"'.format(comment) else: command = "commit" self.send_command(command) def discard_changes(self): self.send_command("exit discard") def get_diff( self, candidate=None, running=None, diff_match="line", diff_ignore_lines=None, path=None, diff_replace=None, ): diff = {} device_operations = self.get_device_operations() option_values = self.get_option_values() if candidate is None and device_operations["supports_generate_diff"]: raise ValueError("candidate configuration is required to generate diff") if diff_match not in option_values["diff_match"]: raise ValueError( "'match' value %s in invalid, valid values are %s" % (diff_match, ", ".join(option_values["diff_match"])), ) if diff_replace: raise ValueError("'replace' in diff is not supported") if diff_ignore_lines: raise ValueError("'diff_ignore_lines' in diff is not supported") if path: raise ValueError("'path' in diff is not supported") - set_format = candidate.startswith("set") or candidate.startswith("delete") + first_line = next( + ( + stripped + for stripped in (line.strip() for line in candidate.splitlines()) + if stripped and not stripped.startswith("#") + ), + "", + ) + set_format = first_line.startswith("set") or first_line.startswith("delete") candidate_obj = NetworkConfig(indent=4, contents=candidate) if not set_format: config = [c.line for c in candidate_obj.items] commands = list() - # this filters out less specific lines for item in config: for index, entry in enumerate(commands): if item.startswith(entry): del commands[index] break commands.append(item) candidate_commands = ["set %s" % cmd.replace(" {", "") for cmd in commands] else: - candidate_commands = str(candidate).strip().split("\n") + candidate_commands = [ + line.strip() + for line in str(candidate).splitlines() + if line.strip() and not line.lstrip().startswith("#") + ] if diff_match == "none": diff["config_diff"] = list(candidate_commands) return diff + if diff_match == "enforce": + if running is None: + raise ValueError( + "diff_match=enforce requires a running configuration to diff against", + ) + + enforce_candidate_lines = list(candidate_commands) + + if not enforce_candidate_lines: + raise ValueError( + "diff_match=enforce received an empty candidate (after stripping blank/" + "comment lines); refusing to treat that as a desired end-state of " + "'delete everything'. Provide 'set' commands describing the desired " + "configuration.", + ) + + for line in enforce_candidate_lines: + tokens = line.strip().split() + if tokens[0] != "set": + raise ValueError( + "diff_match=enforce treats the candidate as the complete desired " + "configuration end-state and only supports 'set' commands; " + "line does not start with 'set' (found: {0!r})".format( + line.strip(), + ), + ) + if len(VyosConf().parse_line(line)[1]) < 1: + raise ValueError( + "diff_match=enforce only supports complete 'set' commands with at least " + "a path and a leaf; got: {0!r}".format(line.strip()), + ) + running_conf = VyosConf( + [ + line + for line in running.splitlines() + if line.strip() and not line.lstrip().startswith("#") + ], + ) + + candidate_conf = VyosConf(enforce_candidate_lines) + diff["config_diff"] = running_conf.diff_commands_to(candidate_conf) + for cmd in diff["config_diff"]: + if re.match(r"^delete\s+service\s+ssh\b", cmd): + raise ValueError( + "diff_match=enforce refuses to generate 'delete service ssh ...' " + "commands, since this could sever the management connection. " + "Remove SSH configuration explicitly with a separate match=line " + "or match=none task instead.", + ) + return diff running_commands = [str(c).replace("'", "") for c in running.splitlines()] updates = list() visited = set() for line in candidate_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 running_commands: updates.append(line) elif item.startswith("delete"): if not running_commands: updates.append(line) else: item = re.sub(r"delete", "set", item) for entry in running_commands: if re.match(rf"^{re.escape(item)}\b", entry) and line not in visited: updates.append(line) visited.add(line) diff["config_diff"] = list(updates) return diff def run_commands(self, commands=None, check_rc=True): if commands is None: raise ValueError("'commands' value is required") responses = list() for cmd in to_list(commands): if not isinstance(cmd, Mapping): cmd = {"command": cmd} output = cmd.pop("output", None) if output: raise ValueError("'output' value %s is not supported for run_commands" % output) try: out = self.send_command(**cmd) except AnsibleConnectionFailure as e: if check_rc: raise out = getattr(e, "err", e) responses.append(out) return responses def get_device_operations(self): return { "supports_diff_replace": False, "supports_commit": True, "supports_rollback": False, "supports_defaults": False, "supports_onbox_diff": True, "supports_commit_comment": True, "supports_multiline_delimiter": False, "supports_diff_match": True, "supports_diff_ignore_lines": False, "supports_generate_diff": False, "supports_replace": False, } def get_option_values(self): return { "format": ["text", "set"], - "diff_match": ["line", "none"], + "diff_match": ["line", "enforce", "none"], "diff_replace": [], "output": [], } def get_capabilities(self): result = super(Cliconf, self).get_capabilities() result["device_operations"] = self.get_device_operations() result.update(self.get_option_values()) return json.dumps(result) def set_cli_prompt_context(self): """ Make sure we are in the operational cli mode :return: None """ if self._connection.connected: self._update_cli_prompt_context(config_context="#", exit_command="exit discard") diff --git a/plugins/cliconf_utils/__init__.py b/plugins/cliconf_utils/__init__.py new file mode 100644 index 00000000..e69de29b diff --git a/plugins/cliconf_utils/vyosconf.py b/plugins/cliconf_utils/vyosconf.py new file mode 100644 index 00000000..a3ed6887 --- /dev/null +++ b/plugins/cliconf_utils/vyosconf.py @@ -0,0 +1,257 @@ +# +# 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 + +import re + + +class _KeepExistingSentinel: + """Unique marker for 'preserve whatever's already here' in a diff. + Deliberately not a plain string/value: a real config leaf could + legitimately be "..." (e.g. a description), and a string sentinel + would collide with it. An object identity never can. + """ + + def __repr__(self): + return "" + + +KEEP_EXISTING_VALUES = _KeepExistingSentinel() + + +class VyosConf: + def __init__(self, commands=None): + self.config = {} + if isinstance(commands, list): + self.run_commands(commands) + + def set_entry(self, path, leaf): + """ + This function sets a value in the configuration given a path. + :param path: list of strings to traverse in the config + :param leaf: value to set at the destination + :return: dict + """ + target = self.config + path = path + [leaf] + for key in path: + if key not in target or not isinstance(target[key], dict): + target[key] = {} + target = target[key] + return self.config + + def del_entry(self, path, leaf): + """ + This function deletes a value from the configuration given a path + and also removes all the parents that are now empty. If the leaf + does not exist at the given path, the configuration is left + unchanged (delete is treated as a no-op, matching VyOS's own + behaviour when deleting a path that isn't set). + :param path: list of strings to traverse in the config + :param leaf: value to delete at the destination + :return: dict + """ + target = self.config + first_no_sibling_key = None + for key in path: + if key not in target: + return self.config + if len(target[key]) <= 1: + if first_no_sibling_key is None: + first_no_sibling_key = [target, key] + else: + first_no_sibling_key = None + target = target[key] + + if leaf not in target: + return self.config + + if first_no_sibling_key is None: + first_no_sibling_key = [target, leaf] + + target = first_no_sibling_key[0] + target_key = first_no_sibling_key[1] + del target[target_key] + return self.config + + def check_entry(self, path, leaf): + """ + This function checks if a value exists in the config. + :param path: list of strings to traverse in the config + :param leaf: value to check for existence + :return: bool + """ + target = self.config + path = path + [leaf] + for key in path: + if key not in target or not isinstance(target[key], dict): + return False + target = target[key] + return True + + def parse_line(self, line): + """ + This function parses a given command from string. + :param line: line to parse + :return: [command, path, leaf] + """ + line = re.match(r"^('(.*)'|\"(.*)\"|([^#\"']*))*", line).group(0).strip() + if not line: + return ["", [], ""] + path = re.findall(r"('.*?'|\".*?\"|\S+)", line) + if not path: + return ["", [], ""] + leaf = path[-1] + if leaf.startswith('"') and leaf.endswith('"'): + leaf = leaf[1:-1] + if leaf.startswith("'") and leaf.endswith("'"): + leaf = leaf[1:-1] + return [path[0], path[1:-1], leaf] + + def run_command(self, command): + """ + This function runs a given command string. + :param command: command to run + :return: dict + """ + [cmd, path, leaf] = self.parse_line(command) + if cmd.startswith("set"): + self.set_entry(path, leaf) + if cmd.startswith("del"): + self.del_entry(path, leaf) + return self.config + + def run_commands(self, commands): + """ + This function runs a list of command strings. + :param commands: commands to run + :return: dict + """ + for c in commands: + self.run_command(c) + return self.config + + def check_command(self, command): + """ + This function checks a command for existence in the config. + :param command: command to check + :return: bool + """ + [cmd, path, leaf] = self.parse_line(command) + if cmd.startswith("set"): + return self.check_entry(path, leaf) + if cmd.startswith("del"): + return not self.check_entry(path, leaf) + return True + + def check_commands(self, commands): + """ + This function checks a list of commands for existence in the config. + :param commands: list of commands to check + :return: [bool] + """ + return [self.check_command(c) for c in commands] + + def quote_key(self, key): + """ + This function adds quotes to key if quotes are needed for correct parsing. + :param key: str to wrap in quotes if needed + :return: str + """ + if len(key) == 0: + return "" + if '"' in key: + return "'" + key + "'" + if "'" in key: + return '"' + key + '"' + if not re.match(r"^[a-zA-Z0-9./-]*$", key): + return "'" + key + "'" + return key + + def build_commands(self, structure=None, nested=False): + """ + This function builds a list of commands to recreate the current configuration. + :return: [str] + """ + if not isinstance(structure, dict): + structure = self.config + if len(structure) == 0: + return [""] if nested else [] + commands = [] + for key, value in structure.items(): + quoted_key = self.quote_key(key) + for c in self.build_commands(value, True): + commands.append((quoted_key + " " + c).strip()) + if nested: + return commands + return ["set " + c for c in commands] + + def diff_to(self, other, structure): + if not isinstance(other, dict): + other = {} + if len(structure) == 0: + return ([], [""]) + if not isinstance(structure, dict): + structure = {} + if len(other) == 0: + return ([""], []) + if len(other) == 0 and len(structure) == 0: + return ([], []) + + toset = [] + todel = [] + for key in structure.keys(): + quoted_key = self.quote_key(key) + if key in other: + # keys in both configs, pls compare subkeys + (subset, subdel) = self.diff_to(other[key], structure[key]) + for s in subset: + toset.append(quoted_key + " " + s) + for d in subdel: + todel.append(quoted_key + " " + d) + else: + # keys only in this, delete if KEEP_EXISTING_VALUES not set + if KEEP_EXISTING_VALUES not in other: + todel.append(quoted_key) + continue # del + for key, value in other.items(): + if key == KEEP_EXISTING_VALUES: + continue + quoted_key = self.quote_key(key) + if key not in structure: + # keys only in other, pls set all subkeys + (subset, subdel) = self.diff_to(other[key], None) + for s in subset: + toset.append(quoted_key + " " + s) + + return (toset, todel) + + def diff_commands_to(self, other): + """ + This function calculates the required commands to change the current into + the given configuration. Only top-level sections present in the desired + configuration are enforced; top-level sections the candidate does not + mention at all are left completely untouched. + :param other: VyosConf + :return: [str] + """ + scoped_structure = {k: v for k, v in self.config.items() if k in other.config} + (toset, todel) = self.diff_to(other.config, scoped_structure) + return ["delete " + c.strip() for c in todel] + ["set " + c.strip() for c in toset] diff --git a/plugins/modules/vyos_config.py b/plugins/modules/vyos_config.py index 46e51f3b..39380f3e 100644 --- a/plugins/modules/vyos_config.py +++ b/plugins/modules/vyos_config.py @@ -1,449 +1,485 @@ #!/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. 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. 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. 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. + C(none), the active configuration is ignored and the configuration is always + loaded. If the C(match) argument is set to C(enforce), the supplied C(lines) + or C(src) are treated as the complete desired end-state of the configuration, + rather than a set of deltas to apply. + C(enforce) enforces only the top-level configuration + sections present in the supplied candidate as complete end-states; + existing configuration within those sections but not mentioned in the + candidate is removed, so C(enforce) can generate C(delete) commands for + configuration the candidate does not mention. Top-level sections the + candidate does not reference at all are left completely untouched. + C(enforce) is intended for candidates made up of C(set) commands only; + supplying C(delete) lines alongside C(match=enforce) is not supported + and will raise an error. type: str default: line choices: - line + - enforce - 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: false 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. + - Defaults to C(automatic) when C(match) is set to C(enforce), since C(enforce) + can generate C(delete) commands for configuration not mentioned in the + candidate and a bad commit should self-revert rather than leave the device + unreachable. Defaults to C(none) for all other C(match) values. 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. 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: false 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 C(true), if C(backup) is set to C(false) 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 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). 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: + match: enforce 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 """ RETURN = """ commands: description: The list of configuration commands sent to the device returned: always type: list sample: ['...', '...'] filtered: description: The list of configuration commands removed to avoid a load failure 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 re from ansible.module_utils._text import 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 ( get_config, get_connection, load_config, run_commands, ) + DEFAULT_COMMENT = "configured by vyos_config" PASSWORD_NEEDLE = re.compile( - r"set system login user \S+ authentication (encrypted|plaintext)-password", + r"(?:set|delete) system login user \S+ authentication (encrypted|plaintext)-password", +) + +# diff_match=enforce's scoping can collapse an entire untouched subtree into +# a single parent delete (e.g. "delete system login" when a candidate +# touches system without restating login, or "delete system login user +# admin" without a specific authentication line). PASSWORD_NEEDLE can't see +# into a collapsed delete to know whether it removes a password -- since +# real users almost always have one configured, treat any subtree-level +# login deletion as password-bearing by default, same conservative stance +# as PASSWORD_NEEDLE itself. +LOGIN_SUBTREE_DELETE_NEEDLE = re.compile( + r"^delete system login(?:\s+user\s+\S+(?:\s+authentication)?)?\s*$", ) +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 not None: + if allow == found[1]: + continue + result["filtered"].append(line) + index_to_filter.append(index) + continue + + if LOGIN_SUBTREE_DELETE_NEEDLE.match(line.strip()): + 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 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 + confirm_param = module.params["confirm"] + if confirm_param is None: + confirm_param = "automatic" if module.params["match"] == "enforce" else "none" + commit = not module.check_mode comment = module.params["comment"] confirm = None - if module.params["confirm"] == "automatic" or module.params["confirm"] == "manual": + if confirm_param in ("automatic", "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": + if confirm_param == "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 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"]), + match=dict(default="line", choices=["line", "enforce", "none"]), comment=dict(default=DEFAULT_COMMENT), - confirm=dict(choices=["automatic", "manual", "none"], default="none"), + 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), allow_password_change=dict( default="plaintext", choices=["all", "encrypted", "plaintext", "none"], ), ) mutually_exclusive = [("lines", "src")] module = AnsibleModule( argument_spec=argument_spec, mutually_exclusive=mutually_exclusive, supports_check_mode=True, ) warnings = list() result = dict(changed=False, warnings=warnings) if module.params["backup"]: result["__backup__"] = get_config(module=module) if 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 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/enforce.yaml b/tests/integration/targets/vyos_config/tests/cli/enforce.yaml new file mode 100644 index 00000000..8fa0e61b --- /dev/null +++ b/tests/integration/targets/vyos_config/tests/cli/enforce.yaml @@ -0,0 +1,124 @@ +--- +- debug: msg="START cli/enforce.yaml on connection={{ ansible_connection }}" + +# SAFETY: this file exercises match=enforce's full end-state enforcement, +# which fully enforces every top-level section the candidate touches. +# NEVER include any "system ..." line in an enforce candidate below -- +# system login (including the currently-authenticated user) lives under +# that top-level section, and enforce would attempt to delete it if not +# restated. service ssh must also be restated in every candidate that +# touches "service", or the module's built-in guard refuses the run +# (see the dedicated guard test near the end of this file). + +- name: setup baseline config + vyos.vyos.vyos_config: + lines: + - set system host-name {{ inventory_hostname_short }} + - set service lldp + - set protocols static + - set service ssh port 22 + match: none + +- block: + - name: enforce end-state with match=enforce (should remove lldp, keep static+ssh, add ntp) + register: result + vyos.vyos.vyos_config: + lines: + - set protocols static + - set service ssh port 22 + - set service ntp server 192.0.2.1 + match: enforce + + - assert: + that: + - result.changed == true + - "'delete service lldp' in result.commands" + - "'set service ntp server 192.0.2.1' in result.commands" + - "'delete protocols static' not in result.commands" + - "'delete service ssh port 22' not in result.commands" + + - name: check match=enforce is idempotent against the same end-state + register: result + vyos.vyos.vyos_config: + lines: + - set protocols static + - set service ssh port 22 + - set service ntp server 192.0.2.1 + match: enforce + + - assert: + that: + - result.changed == false + + - name: match=enforce tolerates blank lines and comments in the candidate + register: result + vyos.vyos.vyos_config: + lines: + - "# this is a comment" + - "" + - set protocols static + - set service ssh port 22 + - set service ntp server 192.0.2.1 + match: enforce + + - assert: + that: + - result.changed == false + + - name: match=enforce rejects an incomplete set command + register: result + ignore_errors: true + vyos.vyos.vyos_config: + lines: + - set service ssh port 22 + - set + match: enforce + + - assert: + that: + - result.failed == true + + - name: match=enforce rejects delete lines in the candidate + register: result + ignore_errors: true + vyos.vyos.vyos_config: + lines: + - set service ssh port 22 + - delete protocols static + match: enforce + + - assert: + that: + - result.failed == true + + - name: match=enforce refuses a candidate that would delete service ssh + register: result + ignore_errors: true + vyos.vyos.vyos_config: + lines: + - set service ntp server 192.0.2.1 + match: enforce + + - assert: + that: + - result.failed == true + - "'delete service ssh' in result.msg" + + always: + - name: teardown + vyos.vyos.vyos_config: + lines: + - set system host-name {{ inventory_hostname_short }} + - set service ssh port 22 + match: none + + - name: remove leftover test config + vyos.vyos.vyos_config: + lines: + - delete service ntp + - delete protocols static + - delete service lldp + match: none + ignore_errors: true + +- debug: msg="END cli/enforce.yaml on connection={{ ansible_connection }}" diff --git a/tests/unit/cliconf/__init__.py b/tests/unit/cliconf/__init__.py new file mode 100644 index 00000000..e69de29b diff --git a/tests/unit/cliconf/test_utils_vyosconf.py b/tests/unit/cliconf/test_utils_vyosconf.py new file mode 100644 index 00000000..dbc296e6 --- /dev/null +++ b/tests/unit/cliconf/test_utils_vyosconf.py @@ -0,0 +1,217 @@ +# +# 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 + +import unittest + +from ansible_collections.vyos.vyos.plugins.cliconf_utils.vyosconf import ( + KEEP_EXISTING_VALUES, + VyosConf, +) + + +class TestListElements(unittest.TestCase): + def test_add(self): + conf = VyosConf() + conf.set_entry(["a", "b"], "c") + self.assertEqual(conf.config, {"a": {"b": {"c": {}}}}) + conf.set_entry(["a", "b"], "d") + self.assertEqual(conf.config, {"a": {"b": {"c": {}, "d": {}}}}) + conf.set_entry(["a", "c"], "b") + self.assertEqual( + conf.config, + {"a": {"b": {"c": {}, "d": {}}, "c": {"b": {}}}}, + ) + conf.set_entry(["a", "c", "b"], "d") + self.assertEqual( + conf.config, + {"a": {"b": {"c": {}, "d": {}}, "c": {"b": {"d": {}}}}}, + ) + + def test_del(self): + conf = VyosConf() + conf.set_entry(["a", "b"], "c") + conf.set_entry(["a", "c", "b"], "d") + conf.set_entry(["a", "b"], "d") + self.assertEqual( + conf.config, + {"a": {"b": {"c": {}, "d": {}}, "c": {"b": {"d": {}}}}}, + ) + conf.del_entry(["a", "c", "b"], "d") + self.assertEqual(conf.config, {"a": {"b": {"c": {}, "d": {}}}}) + conf.set_entry(["a", "b", "c"], "d") + conf.del_entry(["a", "b", "c"], "d") + self.assertEqual(conf.config, {"a": {"b": {"d": {}}}}) + + def test_del_missing_leaf_is_noop(self): + """ + Deleting a leaf that was never set must leave the config unchanged. + Regression test: del_entry() used to raise KeyError when the leaf's + parent had siblings, and could delete an unrelated ancestor subtree + (or the entire config) when the parent path had no siblings. + """ + # parent has siblings: previously raised KeyError + conf = VyosConf() + conf.set_entry(["a", "b"], "c") + conf.set_entry(["a", "b"], "d") + conf.del_entry(["a", "b"], "nonexistent") + self.assertEqual(conf.config, {"a": {"b": {"c": {}, "d": {}}}}) + + # parent path is an unbranched chain: previously deleted the + # entire config instead of no-op'ing + conf = VyosConf() + conf.set_entry(["a", "b"], "d") + conf.del_entry(["a", "b"], "c") + self.assertEqual(conf.config, {"a": {"b": {"d": {}}}}) + + # missing intermediate path element already behaved correctly; + # confirm it still does + conf = VyosConf() + conf.set_entry(["a", "b"], "c") + conf.del_entry(["a", "x"], "c") + self.assertEqual(conf.config, {"a": {"b": {"c": {}}}}) + + def test_parse(self): + conf = VyosConf() + self.assertListEqual( + conf.parse_line("set a b c"), + ["set", ["a", "b"], "c"], + ) + self.assertListEqual( + conf.parse_line('set a b "c"'), + ["set", ["a", "b"], "c"], + ) + self.assertListEqual( + conf.parse_line("set a b 'c d'"), + ["set", ["a", "b"], "c d"], + ) + self.assertListEqual( + conf.parse_line("set a b 'c'"), + ["set", ["a", "b"], "c"], + ) + self.assertListEqual( + conf.parse_line("delete a b 'c'"), + ["delete", ["a", "b"], "c"], + ) + self.assertListEqual( + conf.parse_line("del a b 'c'"), + ["del", ["a", "b"], "c"], + ) + self.assertListEqual( + conf.parse_line("set a b '\"c'"), + ["set", ["a", "b"], '"c'], + ) + self.assertListEqual( + conf.parse_line("set a b 'c' #this is a comment"), + ["set", ["a", "b"], "c"], + ) + self.assertListEqual( + conf.parse_line("set a b '#c'"), + ["set", ["a", "b"], "#c"], + ) + + def test_run_commands(self): + self.assertEqual( + VyosConf(["set a b 'c'", "set a c 'b'"]).config, + {"a": {"b": {"c": {}}, "c": {"b": {}}}}, + ) + self.assertEqual( + VyosConf(["set a b c 'd'", "set a c 'b'", "del a b c d"]).config, + {"a": {"c": {"b": {}}}}, + ) + + def test_build_commands(self): + self.assertEqual( + sorted( + VyosConf( + [ + "set a b 'c a'", + "set a c a", + "set a c b", + "delete a c a", + ], + ).build_commands(), + ), + sorted(["set a b 'c a'", "set a c b"]), + ) + self.assertEqual( + sorted( + VyosConf( + [ + "set a b 10.0.0.1/24", + "set a c ABCabc123+/=", + "set a d $6$ABC.abc.123.+./=..", + ], + ).build_commands(), + ), + sorted( + [ + "set a b 10.0.0.1/24", + "set a c 'ABCabc123+/='", + "set a d '$6$ABC.abc.123.+./=..'", + ], + ), + ) + + def test_check_commands(self): + conf = VyosConf(["set a b 'c a'", "set a c b"]) + self.assertListEqual( + conf.check_commands( + ["set a b 'c a'", "del a c b", "set a b 'c'", "del a a a"], + ), + [True, False, False, True], + ) + + def test_diff_commands_to(self): + conf = VyosConf(["set a b 'c a'", "set a c b"]) + + self.assertListEqual( + conf.diff_commands_to(VyosConf(["set a c b"])), + ["delete a b"], + ) + self.assertListEqual( + conf.diff_commands_to(VyosConf(["set a b 'c a'", "set a c b"])), + [], + ) + + # KEEP_EXISTING_VALUES is no longer reachable via 'set'/'delete' + # command text (see #6): a literal "..." leaf is now an ordinary + # value, not a sentinel, so nothing is suppressed here. + self.assertListEqual( + conf.diff_commands_to(VyosConf(["set a b ..."])), + ["delete a b 'c a'", "delete a c", "set a b ..."], + ) + + def test_diff_commands_to_keep_existing_values_sentinel(self): + # KEEP_EXISTING_VALUES is only reachable via the Python API now. + # Build the candidate tree directly to prove diff_to() still + # honours it when used that way. + conf = VyosConf(["set a b 'c a'", "set a c b"]) + candidate = VyosConf() + candidate.config = {"a": {"b": {KEEP_EXISTING_VALUES: {}}}} + + self.assertListEqual( + conf.diff_commands_to(candidate), + ["delete a c"], + ) + + +if __name__ == "__main__": + unittest.main() diff --git a/tests/unit/modules/network/vyos/test_vyos_config.py b/tests/unit/modules/network/vyos/test_vyos_config.py index e732ca60..8e6b1e65 100644 --- a/tests/unit/modules/network/vyos/test_vyos_config.py +++ b/tests/unit/modules/network/vyos/test_vyos_config.py @@ -1,179 +1,531 @@ # # (c) 2016 Red Hat Inc. # # 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 . # Make coding more python3-ish from __future__ import absolute_import, division, print_function + __metaclass__ = type from unittest.mock import MagicMock, patch from ansible_collections.vyos.vyos.plugins.cliconf.vyos import Cliconf from ansible_collections.vyos.vyos.plugins.modules import vyos_config from ansible_collections.vyos.vyos.tests.unit.modules.utils import set_module_args from .vyos_module import TestVyosModule, load_fixture class TestVyosConfigModule(TestVyosModule): module = vyos_config def setUp(self): super(TestVyosConfigModule, self).setUp() self.mock_get_config = patch( "ansible_collections.vyos.vyos.plugins.modules.vyos_config.get_config", ) self.get_config = self.mock_get_config.start() self.mock_load_config = patch( "ansible_collections.vyos.vyos.plugins.modules.vyos_config.load_config", ) self.load_config = self.mock_load_config.start() self.mock_run_commands = patch( "ansible_collections.vyos.vyos.plugins.modules.vyos_config.run_commands", ) self.run_commands = self.mock_run_commands.start() self.mock_get_connection = patch( "ansible_collections.vyos.vyos.plugins.modules.vyos_config.get_connection", ) self.get_connection = self.mock_get_connection.start() self.cliconf_obj = Cliconf(MagicMock()) self.running_config = load_fixture("vyos_config_config.cfg") self.conn = self.get_connection() self.conn.edit_config = MagicMock() self.running_config = load_fixture("vyos_config_config.cfg") def tearDown(self): super(TestVyosConfigModule, self).tearDown() self.mock_get_config.stop() self.mock_load_config.stop() self.mock_run_commands.stop() self.mock_get_connection.stop() def load_fixtures(self, commands=None, filename=None): config_file = "vyos_config_config.cfg" self.get_config.return_value = load_fixture(config_file) self.load_config.return_value = None def test_vyos_config_unchanged(self): src = load_fixture("vyos_config_config.cfg") self.conn.get_diff = MagicMock(return_value=self.cliconf_obj.get_diff(src, src)) set_module_args(dict(src=src)) self.execute_module() def test_vyos_config_src(self): src = load_fixture("vyos_config_src.cfg") set_module_args(dict(src=src)) candidate = "\n".join(self.module.format_commands(src.splitlines())) commands = [ "set system host-name foo", "delete interfaces ethernet eth0 address", ] self.conn.get_diff = MagicMock( return_value=self.cliconf_obj.get_diff(candidate, self.running_config), ) self.execute_module(changed=True, commands=commands) def test_vyos_config_src_brackets(self): src = load_fixture("vyos_config_src_brackets.cfg") set_module_args(dict(src=src)) commands = [ "set interfaces ethernet eth0 address 10.10.10.10/24", "set policy route testroute rule 1 set table 10", "set system host-name foo", ] self.conn.get_diff = MagicMock(side_effect=self.cliconf_obj.get_diff) self.execute_module(changed=True, commands=commands) def test_vyos_config_backup(self): set_module_args(dict(backup=True)) result = self.execute_module() self.assertIn("__backup__", result) def test_vyos_config_lines(self): commands = ["set system host-name foo"] set_module_args(dict(lines=commands)) candidate = "\n".join(commands) self.conn.get_diff = MagicMock( return_value=self.cliconf_obj.get_diff(candidate, self.running_config), ) self.execute_module(changed=True, commands=commands) def test_vyos_config_config(self): config = "set system host-name localhost" new_config = ["set system host-name router"] set_module_args(dict(lines=new_config, config=config)) candidate = "\n".join(new_config) self.conn.get_diff = MagicMock(return_value=self.cliconf_obj.get_diff(candidate, config)) self.execute_module(changed=True, commands=new_config) def test_vyos_config_match_none(self): lines = [ "set system interfaces ethernet eth0 address 1.2.3.4/24", "set system interfaces ethernet eth0 description test string", ] set_module_args(dict(lines=lines, match="none")) candidate = "\n".join(lines) self.conn.get_diff = MagicMock( return_value=self.cliconf_obj.get_diff(candidate, None, diff_match="none"), ) self.execute_module(changed=True, commands=lines, sort=False) + def test_vyos_config_match_enforce(self): + lines = [ + "set interfaces ethernet eth0 address '1.2.3.4/24'", + "set interfaces ethernet eth0 description 'test string'", + ] + set_module_args(dict(lines=lines, match="enforce")) + candidate = "\n".join(lines) + + response = self.cliconf_obj.get_diff( + candidate, + self.running_config, + diff_match="enforce", + ) + + self.conn.get_diff = MagicMock(return_value=response) + result = self.execute_module(changed=True, sort=False) + + self.conn.get_diff.assert_called_once_with( + candidate=candidate, + running=self.running_config, + diff_match="enforce", + ) + + expected_config_diff = [ + "delete interfaces ethernet eth1", + ] + self.assertEqual(response["config_diff"], expected_config_diff) + + expected_commands = expected_config_diff + self.assertEqual(result["commands"], expected_commands) + def test_vyos_config_confirm_automatic(self): src = load_fixture("vyos_config_src.cfg") confirm_timeout = 7 set_module_args(dict(src=src, confirm="automatic", confirm_timeout=confirm_timeout)) candidate = "\n".join(self.module.format_commands(src.splitlines())) commands = [ "set system host-name foo", "delete interfaces ethernet eth0 address", ] self.conn.get_diff = MagicMock( return_value=self.cliconf_obj.get_diff(candidate, self.running_config), ) self.execute_module(changed=True, commands=commands) self.assertEqual(self.load_config.call_args[1]["confirm"], confirm_timeout) self.run_commands.assert_called_once() self.assertEqual( ["configure", "confirm", "exit"], self.run_commands.call_args[0][1], ) def test_vyos_config_confirm_manual(self): lines = [ "set system host-name foo", ] confirm_timeout = 12 set_module_args(dict(lines=lines, confirm="manual", confirm_timeout=confirm_timeout)) candidate = "\n".join(lines) self.conn.get_diff = MagicMock( return_value=self.cliconf_obj.get_diff(candidate, self.running_config), ) self.execute_module(changed=True, commands=lines) self.assertEqual(self.load_config.call_args[1]["confirm"], confirm_timeout) self.run_commands.assert_not_called() + + def test_vyos_config_match_enforce_blank_lines(self): + """enforce diff must not raise IndexError on blank lines in running config.""" + running_with_blanks = self.running_config + "\n\n" + candidate = "set interfaces ethernet eth0 address 1.2.3.4/24" + response = self.cliconf_obj.get_diff(candidate, running_with_blanks, diff_match="enforce") + self.assertIn("config_diff", response) + + def test_vyos_config_match_enforce_additions(self): + lines = [ + "set interfaces ethernet eth0 address '1.2.3.4/24'", + "set interfaces ethernet eth0 description 'test string'", + "set interfaces ethernet eth2 address '192.0.2.1/24'", + ] + set_module_args(dict(lines=lines, match="enforce")) + candidate = "\n".join(lines) + response = self.cliconf_obj.get_diff( + candidate, + self.running_config, + diff_match="enforce", + ) + self.conn.get_diff = MagicMock(return_value=response) + result = self.execute_module(changed=True, sort=False) + self.conn.get_diff.assert_called_once_with( + candidate=candidate, + running=self.running_config, + diff_match="enforce", + ) + self.assertIn( + "set interfaces ethernet eth2 address 192.0.2.1/24", + response["config_diff"], + ) + self.assertEqual(result["commands"], response["config_diff"]) + + def test_vyos_config_match_enforce_rejects_delete_lines(self): + """ + match=enforce treats the candidate as the complete desired end-state. + A candidate containing 'delete' lines must be rejected rather than + silently producing a diff that removes most/all of the running + config (regression test for a candidate that is a no-op/delete-only + input generating deletes for everything the candidate omits). + """ + lines = ["delete interfaces ethernet eth0 address"] + candidate = "\n".join(lines) + + with self.assertRaises(ValueError): + self.cliconf_obj.get_diff( + candidate, + self.running_config, + diff_match="enforce", + ) + + def test_vyos_config_match_enforce_rejects_empty_candidate(self): + """ + A candidate that is empty, whitespace-only, or comment-only must be + rejected rather than silently treated as an empty desired end-state + (which would generate deletes for the entire running config). + Comment-only candidates are also stripped away entirely by upstream + NetworkConfig parsing before reaching VyosConf, so this is a second, + distinct route to the same mass-deletion failure mode as the + 'delete' lines case above. + """ + for candidate in ("", " ", "# just a comment"): + with self.assertRaises(ValueError): + self.cliconf_obj.get_diff( + candidate, + self.running_config, + diff_match="enforce", + ) + + def test_vyos_config_match_enforce_requires_running(self): + """ + diff_match=enforce with running=None must raise a clear ValueError + instead of falling through to an AttributeError on + running.splitlines(). + """ + with self.assertRaises(ValueError): + self.cliconf_obj.get_diff( + "set system host-name foo", + None, + diff_match="enforce", + ) + + def test_vyos_config_match_enforce_ignores_comment_lines(self): + """ + Comment lines mixed in with 'set' lines must be stripped out rather + than causing the whole candidate to be rejected as not starting + with 'set'. + """ + candidate = "\n".join( + [ + "set interfaces ethernet eth0 address '1.2.3.4/24'", + "# a note about this interface", + "set interfaces ethernet eth0 description 'test string'", + ], + ) + running = "set interfaces ethernet eth0 address '1.2.3.4/24'" + response = self.cliconf_obj.get_diff( + candidate, + running, + diff_match="enforce", + ) + self.assertIn( + "set interfaces ethernet eth0 description 'test string'", + response["config_diff"], + ) + + def test_sanitize_config_filters_password_delete_lines(self): + """ + sanitize_config()/PASSWORD_NEEDLE must filter 'delete ... password' + lines the same way it filters 'set ... password' lines, since + match=enforce can generate deletes for password config the candidate + omits. Without this, allow_password_change=none/plaintext/encrypted + would fail to catch a password-affecting delete. + """ + result = {} + commands = [ + "set system host-name foo", + "delete system login user admin authentication encrypted-password", + "set system login user admin authentication plaintext-password 'secret'", + ] + vyos_config.sanitize_config(commands, result, allow="none") + self.assertIn( + "delete system login user admin authentication encrypted-password", + result["filtered"], + ) + self.assertIn( + "set system login user admin authentication plaintext-password 'secret'", + result["filtered"], + ) + self.assertNotIn("set system host-name foo", result["filtered"]) + + def test_vyos_config_match_enforce_refuses_ssh_deletion(self): + """ + match=enforce must refuse to generate 'delete service ssh ...' + commands, since this could sever the management connection. + Regression test for the incident where an enforce candidate that + didn't restate 'service ssh' generated a delete for it. + """ + running = "\n".join( + [ + "set service ssh port '22'", + "set service lldp", + ], + ) + candidate = "set service lldp" + + with self.assertRaises(ValueError): + self.cliconf_obj.get_diff( + candidate, + running, + diff_match="enforce", + ) + + def test_vyos_config_confirm_defaults_to_automatic_for_match_enforce(self): + """ + confirm defaults to 'automatic' when match=enforce and confirm is + not explicitly set, since enforce can generate broad deletes and a + bad commit should self-revert rather than leave the device + unreachable. + """ + lines = [ + "set interfaces ethernet eth0 address '1.2.3.4/24'", + "set interfaces ethernet eth0 description 'test string'", + ] + set_module_args(dict(lines=lines, match="enforce")) + candidate = "\n".join(lines) + response = self.cliconf_obj.get_diff( + candidate, + self.running_config, + diff_match="enforce", + ) + self.conn.get_diff = MagicMock(return_value=response) + + self.execute_module(changed=True, sort=False) + + self.assertEqual(self.load_config.call_args[1]["confirm"], 10) + self.run_commands.assert_called_once() + self.assertEqual( + ["configure", "confirm", "exit"], + self.run_commands.call_args[0][1], + ) + + def test_vyos_config_confirm_stays_none_for_other_match_values(self): + """ + confirm stays 'none' (no confirm kwarg passed, no auto-confirm + run_commands call) when match is not 'enforce' and confirm is not + explicitly set -- the new conditional default must not change + existing behaviour for match=line/none. + """ + lines = ["set system host-name foo"] + set_module_args(dict(lines=lines)) + candidate = "\n".join(lines) + self.conn.get_diff = MagicMock( + return_value=self.cliconf_obj.get_diff(candidate, self.running_config), + ) + + self.execute_module(changed=True, commands=lines) + + self.assertIsNone(self.load_config.call_args[1]["confirm"]) + self.run_commands.assert_not_called() + + def test_vyos_config_match_enforce_rejects_comment_disguised_as_command(self): + """ + A line like 'set # comment' has 3 raw tokens (passing a naive + token-count check) but parse_line() strips the trailing comment, + leaving no actual path/leaf. This must still be rejected rather + than silently contributing an empty/degenerate entry to the diff. + """ + for bad_line in ("set # comment", "set foo # comment"): + candidate = "\n".join(["set system host-name foo", bad_line]) + with self.assertRaises(ValueError): + self.cliconf_obj.get_diff( + candidate, + self.running_config, + diff_match="enforce", + ) + + def test_sanitize_config_filters_collapsed_login_subtree_deletes(self): + """ + match=enforce's scoping can collapse an untouched subtree into a + single parent delete (e.g. 'delete system login' when a candidate + touches system without restating login, rather than an itemized + per-field delete). PASSWORD_NEEDLE alone can't see into a collapsed + delete to know it removes a password -- it must be treated as + password-bearing by default under any restrictive + allow_password_change value. + """ + result = {} + commands = [ + "set system host-name foo", + "delete system login", + ] + vyos_config.sanitize_config(commands, result, allow="none") + self.assertIn("delete system login", result["filtered"]) + self.assertNotIn("set system host-name foo", result["filtered"]) + + def test_sanitize_config_filters_collapsed_login_user_subtree_delete(self): + """ + Same collapse risk at the per-user level: 'delete system login + user admin' (no specific authentication line) must also be + treated as password-bearing. + """ + result = {} + commands = [ + "set system host-name foo", + "delete system login user admin", + ] + vyos_config.sanitize_config(commands, result, allow="none") + self.assertIn("delete system login user admin", result["filtered"]) + + def test_sanitize_config_allows_collapsed_login_subtree_delete_when_all(self): + """ + allow_password_change=all must still let a collapsed login-subtree + delete through, same as it already does for explicit password + lines. + """ + result = {} + commands = [ + "set system host-name foo", + "delete system login", + ] + vyos_config.sanitize_config(commands, result, allow="all") + self.assertEqual(result["filtered"], []) + + def test_vyos_config_match_enforce_accepts_bracket_format_src(self): + """ + match=enforce must accept bracket-format candidates the same way + match=line/none already do -- enforce_candidate_lines is now built + from the same shared, correctly-normalized candidate_commands + rather than parsing raw candidate text independently (which had no + concept of bracket format at all). + """ + candidate = "system {\n host-name foo\n}\n" + response = self.cliconf_obj.get_diff( + candidate, + self.running_config, + diff_match="enforce", + ) + self.assertIn("set system host-name foo", response["config_diff"]) + + def test_vyos_config_match_line_ignores_comment_and_blank_lines(self): + """ + A src/lines candidate containing comment or blank lines must not + raise under match=line -- these are stripped during candidate + normalization the same way match=enforce already does, rather than + hitting the 'line must start with set or delete' check. + """ + lines = [ + "# a note", + "", + "set system host-name foo", + ] + set_module_args(dict(lines=lines)) + candidate = "\n".join(lines) + self.conn.get_diff = MagicMock( + return_value=self.cliconf_obj.get_diff(candidate, self.running_config), + ) + self.execute_module(changed=True, commands=["set system host-name foo"]) + + def test_sanitize_config_filters_collapsed_login_user_authentication_subtree_delete(self): + """ + A candidate that keeps other settings for a user but omits that + user's entire authentication subtree collapses to 'delete system + login user authentication' -- one level deeper than the + per-user collapse already covered. This must also be treated as + password-bearing under the default allow_password_change=plaintext, + not just under allow_password_change=none. + """ + result = {} + commands = [ + "set system host-name foo", + "delete system login user admin authentication", + ] + vyos_config.sanitize_config(commands, result, allow="plaintext") + self.assertIn( + "delete system login user admin authentication", + result["filtered"], + ) + self.assertNotIn("set system host-name foo", result["filtered"])