diff --git a/.coderabbit.yaml b/.coderabbit.yaml index c14e52eb..2b9a02a4 100644 --- a/.coderabbit.yaml +++ b/.coderabbit.yaml @@ -1,205 +1,204 @@ # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json # # Per-repo CodeRabbit override for vyos/vyos.vyos (Ansible network collection). # # Most behavior is inherited from the org-level central baseline at # https://github.com/vyos/coderabbit/blob/production/.coderabbit.yaml. # This file keeps only what's distinct to this repo: # - Ansible-collection-specific `path_instructions` (15 entries). # - Two `path_filters` entries that aren't in the central list. # - `base_branches: [main]` — central uses VyOS release-train names; this # repo is an Ansible collection that lives on `main`. # - `knowledge_base.jira` scoped to VD. # # Migrated from standalone (591-line rich config from T8584, sha # 38eae56fb991b63e0c89245e4ef5fc130d3f5c8b) to centralized inheritance # mode under T8851 on 2026-05-24. The standalone config preceded # `vyos/coderabbit` central-config introduction (2026-05-12). inheritance: true reviews: auto_review: base_branches: - main path_filters: # Repo-specific filters that aren't in the central baseline. The # central already filters `!**/__pycache__/**`, `!**/*.pyc`, # `!**/*.egg-info/**`, `!**/.venv/**`, `!**/.worktrees/**` — so they # are not repeated here. - - '!changelogs/changelog.yaml' - - '!.collections/**' + - "!changelogs/changelog.yaml" + - "!.collections/**" path_instructions: # ── Global PR hygiene ────────────────────────────────────────────── - - path: '**' + - path: "**" instructions: | This is the vyos.vyos Ansible network collection (namespace=vyos, name=vyos, version=6.0.0). PR titles must follow the format `T{id}: description` referencing a Phorge task at vyos.dev. Every PR must include a changelog fragment in changelogs/fragments/ (YAML, valid keys: major_changes, minor_changes, breaking_changes, deprecated_features, removed_features, security_fixes, bugfixes, known_issues, doc_changes, trivial; plus release_summary as a prelude section). Style: black line-length=100, isort profile=black line_length=100, flake8 max-line-length=120. Do not suggest 88-char wrapping. # ── Module entry points ──────────────────────────────────────────── - - path: 'plugins/modules/vyos_*.py' + - path: "plugins/modules/vyos_*.py" instructions: | Module entry points. Each file must contain three YAML triple-string blocks: DOCUMENTATION, EXAMPLES, and RETURN — this is Ansible's documentation contract, not Python docstrings. Verify: - DOCUMENTATION includes: module, author, short_description, description, version_added, extends_documentation_fragment (vyos.vyos.vyos), options with types and descriptions, and a notes section listing tested VyOS versions. - EXAMPLES has at least one working task per supported state. - RETURN documents all return keys with description, returned, type, and sample. - The module wires argspec, config, and facts classes correctly. - State choices include the full set where applicable: merged, replaced, overridden, deleted, gathered, parsed, rendered. Do not add Python-style docstrings (def-level) to these files — the YAML blocks are the canonical documentation. # ── Argspec (auto-generated) ─────────────────────────────────────── - - path: 'plugins/module_utils/network/vyos/argspec/**' + - path: "plugins/module_utils/network/vyos/argspec/**" instructions: | Auto-generated by the Ansible resource module builder. These files carry a "DO NOT EDIT" warning header. Do not suggest modifications to auto-generated argspec files — changes will be overwritten. If the schema needs updating, the resource module builder must regenerate it. Only flag issues if the argument_spec dict has obvious type mismatches or missing required fields that would cause runtime failures. # ── Config classes ───────────────────────────────────────────────── - - path: 'plugins/module_utils/network/vyos/config/**' + - path: "plugins/module_utils/network/vyos/config/**" instructions: | Config builders extending ansible.netcommon ConfigBase or ResourceModule. These generate VyOS CLI commands from desired state. Verify: - execute_module() handles all declared states correctly. - set_config() and _set_config() process gathered facts and desired config without data loss. - Command generation produces valid VyOS CLI syntax (set/delete prefixes, proper quoting of values with spaces). - No silent swallowing of unknown keys — unknown config should raise or warn. - Methods that compare current vs desired state handle empty/None gracefully. Some older config files have auto-generated headers — do not restructure those. # ── Facts classes ────────────────────────────────────────────────── - - path: 'plugins/module_utils/network/vyos/facts/**' + - path: "plugins/module_utils/network/vyos/facts/**" instructions: | Facts classes parse raw VyOS CLI output into structured dicts. Verify: - Regex patterns handle edge cases (missing fields, empty values, quoted strings). - populate() returns a clean dict even when device output is incomplete. - get_device_data() uses the correct show command for the resource. - facts/facts.py FACT_RESOURCE_SUBSETS and FACT_LEGACY_SUBSETS stay in sync with available fact classes. - Legacy facts (facts/legacy/) use run_commands(); resource facts use get_resource_connection(). # ── RM Templates ─────────────────────────────────────────────────── - - path: 'plugins/module_utils/network/vyos/rm_templates/*.py' + - path: "plugins/module_utils/network/vyos/rm_templates/*.py" instructions: | Parser templates mapping structured data to VyOS CLI commands and vice versa. Files with a `_14` suffix target VyOS 1.4+ behavior — do not suggest merging them with the base version. Verify: - _tmplt_* helper functions produce syntactically valid VyOS commands. - Regex patterns in PARSERS list correctly capture all variations of the CLI output (quoted values, optional fields, nested hierarchies). - New templates include both set and delete command generation. - compval/getval paths match the argspec structure. # ── Cliconf plugin ───────────────────────────────────────────────── - - path: 'plugins/cliconf/vyos.py' + - path: "plugins/cliconf/vyos.py" instructions: | Low-level CLI abstraction for VyOS. Handles configure mode, commit, diff, command execution. Changes here affect all modules. Verify: - edit_config() enters configure mode and commits correctly. - get_diff() returns accurate before/after config diffs. - Error handling catches VyOS-specific error patterns (commit failures, invalid commands). - __rpc__ list matches actually implemented methods. # ── Terminal plugin ──────────────────────────────────────────────── - - path: 'plugins/terminal/vyos.py' + - path: "plugins/terminal/vyos.py" instructions: | Terminal prompt detection and initialization. Changes affect connection reliability. Verify regex patterns against actual VyOS prompt formats (configure mode, operational mode, different shell variants). Do not remove existing patterns without testing against all supported VyOS versions. # ── Action plugin ────────────────────────────────────────────────── - - path: 'plugins/action/vyos.py' + - path: "plugins/action/vyos.py" instructions: | Auto-proxies all modules to the device. Must validate network_cli connection type. Symlinks from each module name point here. Keep minimal — logic belongs in config classes, not the action plugin. # ── Changelog fragments ──────────────────────────────────────────── - - path: 'changelogs/fragments/*.{yaml,yml}' + - path: "changelogs/fragments/*.{yaml,yml}" instructions: | Changelog fragments for ansible-changelog. Valid top-level keys: major_changes, minor_changes, breaking_changes, deprecated_features, removed_features, security_fixes, bugfixes, known_issues, doc_changes, trivial. release_summary is a prelude section (one per release). Fragment filename should be descriptive (e.g., fix-bgp-neighbor-timers.yml). Use `trivial` for tooling/housekeeping. Entries should be complete sentences. # ── CI workflows ─────────────────────────────────────────────────── - - path: '.github/workflows/**' + - path: ".github/workflows/**" instructions: | CI pipeline: tests.yml (main CI with changelog, build, lint, sanity, unit jobs), codecoverage.yml, release.yml (Galaxy + Automation Hub publish), check_label.yaml, cla-check.yml. Changes to release.yml or ah_token_refresh.yml affect publishing credentials — review with extra care. Do not remove the `all_green` aggregation job from tests.yml. # ── Unit tests ───────────────────────────────────────────────────── - - path: 'tests/unit/**' + - path: "tests/unit/**" instructions: | Unit tests use pytest + unittest.TestCase via TestVyosModule base class. Key patterns: - All test classes inherit TestVyosModule (from vyos_module.py). - setUp() creates and starts mock patches; tearDown() stops them. - execute_module(failed, changed, commands, sort) is the primary assertion method. - load_fixtures() is overridden per test class to wire mock return values. - Fixture files (.cfg) go in tests/unit/modules/network/vyos/fixtures/. - Use load_fixture(name) to read fixtures — never inline raw config strings. - set_module_args(dict(...)) configures module input before execution. Style: black line-length=100, assertions via self.assertEqual / self.assertIn / execute_module kwargs. pytest-xdist runs tests in parallel (-n 2). # ── Test fixtures ────────────────────────────────────────────────── - - path: 'tests/unit/modules/network/vyos/fixtures/**' + - path: "tests/unit/modules/network/vyos/fixtures/**" instructions: | Raw VyOS CLI output files (.cfg). These are loaded by load_fixture() and cached in memory. Format is VyOS `set ...` configuration syntax or show command output. Fixture filenames follow the pattern: vyos_{module}_config.cfg (base) or vyos_{module}_config_v14.cfg (VyOS 1.4+). New fixtures must be syntactically valid VyOS config. Do not add JSON fixtures unless the test explicitly requires JSON parsing. # ── Collection metadata ──────────────────────────────────────────── - - path: 'galaxy.yml' + - path: "galaxy.yml" instructions: | Collection metadata. namespace=vyos, name=vyos. Version bumps must be coordinated with release process. Dependency on ansible.netcommon>=2.5.1 is required. Do not add unnecessary dependencies. - - path: 'meta/runtime.yml' + - path: "meta/runtime.yml" instructions: | Module redirects and tombstones. Adding a new module requires a redirect entry (short name → FQCN). Tombstoned modules (logging, vyos_logging) must not be un-tombstoned. requires_ansible must stay >=2.15.0 unless explicitly bumping minimum version. - knowledge_base: jira: # `auto` activates Jira context lookups when this repo lives on an # org with an Atlassian OAuth grant attached (VyOS-Networks); on the # public vyos source it self-disables. usage: auto project_keys: - VD diff --git a/AGENTS.md b/AGENTS.md index f14e1246..b3a16f79 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,39 +1,46 @@ # AGENTS.md ## Project purpose + The official Ansible Collection for managing VyOS network appliances (`vyos.vyos` namespace). Provides modules, plugins, action handlers, terminal plugins, and resource modules for BGP, OSPF, firewall, interfaces, NTP, etc. ## Tech stack + - Ansible Collection (Galaxy). Python control-plane code under `plugins/`. - `galaxy.yml` declares `namespace: vyos`, `name: vyos`, `version: 6.0.0`, dep `ansible.netcommon >= 2.5.1`, license_file `LICENSE` (GPL-3.0). - Test stack: `pytest` + `tox-ansible.ini`; lint via flake8, isort, black (line-length 100), pre-commit, ansible-lint. - Runtime deps: `paramiko`, `scp` (`requirements.txt`); `bindep.txt` for system deps. ## Build / test / run + - Build: `ansible-galaxy collection build` produces a `vyos-vyos-.tar.gz`. - Install local dev: `ansible-galaxy collection install . --force`. - Test (unit): `ansible-test units` (matches `unit-galaxy` CI job; requires collection installed under `~/.ansible/collections/`). Fast local alternative: `source .venv/bin/activate && PYTHONPATH=".collections" python -m pytest tests/unit` (matches `unit-source` CI path; config in `pyproject.toml`). CI (`.github/workflows/tests.yml`) runs the changelog / build-import / ansible-lint / sanity / unit-galaxy / unit-source jobs; integration tests live under `tests/integration/` but are not yet wired into CI. Per `README.md`, the collection targets VyOS 1.3.8 / 1.4.1 / 1.5-rolling (no version matrix in the workflow itself). ## Repository layout + - `plugins/{action,cliconf,doc_fragments,filter,inventory,module_utils,modules,terminal}/` — collection content. - `tests/` — sanity, unit, integration directories. CI (`.github/workflows/tests.yml`) runs sanity + unit-galaxy + unit-source (plus changelog / build-import / ansible-lint); integration is not yet wired into CI. - `docs/` — generated module docs. - `meta/`, `changelogs/`, `CHANGELOG.rst` — Galaxy + release metadata. - `pyproject.toml` (black/pytest config), `.flake8`, `.isort.cfg`, `.ansible-lint`, `.pre-commit-config.yaml`. - `.github/workflows/` — `tests.yml`, `release.yml`, `codecoverage.yml`, `cla-check.yml`, `ah_token_refresh.yml`, `check_label.yaml`. ## Cross-repo context + - Consumed by Ansible users running playbooks against VyOS routers built by `vyos/vyos-build`. - The `vyos.vyos` collection talks to VyOS via `network_cli` connections; supports the same train branches (`rolling`, `circinus`, `sagitta`, `equuleus`). ## Conventions + - Commit headline: `T12345: description` (Phorge ID at https://vyos.dev mandatory). No workflow enforces PR title format in this repo. - Every PR must include exactly one changelog fragment under `changelogs/fragments/`; use `doc_changes` for documentation-only updates, or `trivial` for tooling / housekeeping changes. - Default branch `main` (not `current` — this repo predates the rename convention). - Issues tracked at https://vyos.dev (see `galaxy.yml`). - Codecov + CodeRabbit configured (`codecov.yml`, `.coderabbit.yaml`). ## Notes for future contributors + - Galaxy versioning is independent of VyOS train versioning — bump in `galaxy.yml` per release. - Tested matrix is in README; expand only after smoketesting against real images. - `PR408_README.md` plus `pr408-diagram.png` document a non-trivial historical refactor; read before touching resource-module structure. diff --git a/docs/vyos.vyos.vyos_bgp_global_module.rst b/docs/vyos.vyos.vyos_bgp_global_module.rst index ecf44968..e83a147d 100644 --- a/docs/vyos.vyos.vyos_bgp_global_module.rst +++ b/docs/vyos.vyos.vyos_bgp_global_module.rst @@ -1,2431 +1,2431 @@ .. _vyos.vyos.vyos_bgp_global_module: ************************* vyos.vyos.vyos_bgp_global ************************* **BGP global resource module** Version added: 1.0.0 .. contents:: :local: :depth: 1 Synopsis -------- - This module manages BGP global configuration of interfaces on devices running VYOS. - Tested against VyOS 1.3.8, 1.4.2, the upcoming 1.5, and the rolling release of spring 2025 - The provided examples of commands are valid for VyOS 1.4+ Parameters ---------- .. raw:: html
Parameter Choices/Defaults Comments
config
dictionary
A dict of BGP global configuration for interfaces.
as_number
integer
AS number.
bgp_params
dictionary
BGP parameters
always_compare_med
boolean
    Choices:
  • no
  • yes
Always compare MEDs from different neighbors
bestpath
dictionary
Default bestpath selection mechanism
as_path
string
    Choices:
  • confed
  • ignore
AS-path attribute comparison parameters
compare_routerid
boolean
    Choices:
  • no
  • yes
Compare the router-id for identical EBGP paths
med
string
    Choices:
  • confed
  • missing-as-worst
MED attribute comparison parameters
cluster_id
string
Route-reflector cluster-id
confederation
list / elements=dictionary
AS confederation parameters
identifier
integer
Confederation AS identifier
peers
integer
Peer ASs in the BGP confederation
dampening
dictionary
Enable route-flap dampening
half_life
integer
Half-life penalty in seconds
max_suppress_time
integer
Maximum duration to suppress a stable route
re_use
integer
Time to start reusing a route
start_suppress_time
integer
When to start suppressing a route
default
dictionary
BGP defaults
local_pref
integer
Default local preference
no_ipv4_unicast
boolean
    Choices:
  • no
  • yes
Deactivate IPv4 unicast for a peer by default Deprecated: Unavailable after 1.4
deterministic_med
boolean
    Choices:
  • no
  • yes
Compare MEDs between different peers in the same AS
disable_network_import_check
boolean
    Choices:
  • no
  • yes
Disable IGP route check for network statements
distance
list / elements=dictionary
Administrative distances for BGP routes
prefix
integer
Administrative distance for a specific BGP prefix
type
string
    Choices:
  • external
  • internal
  • local
Type of route
value
integer
distance
enforce_first_as
boolean
    Choices:
  • no
  • yes
Require first AS in the path to match peer's AS
graceful_restart
integer
Maximum time to hold onto restarting peer's stale paths
log_neighbor_changes
boolean
    Choices:
  • no
  • yes
Log neighbor up/down changes and reset reason
no_client_to_client_reflection
boolean
    Choices:
  • no
  • yes
Disable client to client route reflection
no_fast_external_failover
boolean
    Choices:
  • no
  • yes
Disable immediate session reset if peer's connected link goes down
router_id
string
BGP router-id
scan_time
integer
BGP route scanner interval
neighbor
list / elements=dictionary
BGP neighbor
address
string
BGP neighbor address (v4/v6).
advertisement_interval
integer
Minimum interval for sending routing updates.
capability
dictionary
Advertise capabilities to this neighbor.
dynamic
boolean
    Choices:
  • no
  • yes
Advertise dynamic capability to this neighbor.
extended_nexthop
boolean
    Choices:
  • no
  • yes
Advertise extended nexthop capability to this neighbor.
default_originate
string
Send default route to this neighbor
description
string
Description of the neighbor
disable_capability_negotiation
boolean
    Choices:
  • no
  • yes
Disbale capability negotiation with the neighbor
disable_connected_check
boolean
    Choices:
  • no
  • yes
Disable check to see if EBGP peer's address is a connected route.
disable_send_community
string
    Choices:
  • extended
  • standard
Disable sending community attributes to this neighbor.
ebgp_multihop
integer
-
Allow this EBGP neighbor to not be on a directly connected network. Specify the number hops.
+
Allow this EBGP neighbor to not be on a directly connected network. Specify the number of hops.
local_as
integer
local as number not to be prepended to updates from EBGP peers
override_capability
boolean
    Choices:
  • no
  • yes
Ignore capability negotiation with specified neighbor.
passive
boolean
    Choices:
  • no
  • yes
Do not initiate a session with this neighbor
password
string
BGP MD5 password
peer_group
boolean
    Choices:
  • no
  • yes
True if all the configs under this neighbor key is for peer group template.
peer_group_name
string
IPv4 peer group for this peer
port
integer
Neighbor's BGP port
remote_as
integer
Neighbor BGP AS number
shutdown
boolean
    Choices:
  • no
  • yes
Administratively shut down neighbor
solo
boolean
    Choices:
  • no
  • yes
Do not send back prefixes learned from the neighbor
strict_capability_match
boolean
    Choices:
  • no
  • yes
Enable strict capability negotiation
timers
dictionary
Neighbor timers
connect
integer
BGP connect timer for this neighbor.
holdtime
integer
BGP hold timer for this neighbor
keepalive
integer
BGP keepalive interval for this neighbor
ttl_security
integer
Number of the maximum number of hops to the BGP peer
update_source
string
Source IP of routing updates
timers
dictionary
BGP protocol timers
holdtime
integer
Hold time interval
keepalive
integer
Keepalive interval
running_config
string
This option is used only with state parsed.
The value of this option should be the output received from the EOS device by executing the command show running-config | section bgp.
The state parsed reads the configuration from running_config option and transforms it into Ansible structured data as per the resource module's argspec and the value is then returned in the parsed key within the result.
state
string
    Choices:
  • deleted
  • merged ←
  • purged
  • replaced
  • gathered
  • rendered
  • parsed
The state the configuration should be left in.
State purged removes all the BGP configurations from the target device. Use caution with this state.('delete protocols bgp <x>')
State deleted only removes BGP attributes that this modules manages and does not negate the BGP process completely. Thereby, preserving address-family related configurations under BGP context.
Running states deleted and replaced will result in an error if there are address-family configuration lines present under neighbor context that is is to be removed. Please use the vyos.vyos.vyos_bgp_address_family module for prior cleanup.
Refer to examples for more details.

Examples -------- .. code-block:: yaml # Using merged # Before state # vyos@vyos:~$ show configuration commands | match "set protocols bgp" # vyos@vyos:~$ - name: Merge provided configuration with device configuration vyos.vyos.vyos_bgp_global: config: as_number: "65536" aggregate_address: - prefix: "203.0.113.0/24" as_set: true - prefix: "192.0.2.0/24" summary_only: true network: - address: "192.1.13.0/24" backdoor: true redistribute: - protocol: "kernel" metric: 45 - protocol: "connected" route_map: "map01" maximum_paths: - path: "ebgp" count: 20 - path: "ibgp" count: 55 timers: keepalive: 35 bgp_params: bestpath: as_path: "confed" compare_routerid: true default: no_ipv4_unicast: true router_id: "192.1.2.9" confederation: - peers: 20 - peers: 55 - identifier: 66 neighbor: - address: "192.0.2.25" disable_connected_check: true timers: holdtime: 30 keepalive: 10 - address: "203.0.113.5" attribute_unchanged: as_path: true med: true ebgp_multihop: 2 remote_as: 101 update_source: "192.0.2.25" - address: "5001::64" maximum_prefix: 34 distribute_list: - acl: 20 action: "export" - acl: 40 action: "import" state: merged # After State # vyos@vyos:~$ show configuration commands | match "set protocols bgp" # set protocols bgp system-as 65536 # set protocols bgp aggregate-address 192.0.2.0/24 'summary-only' # set protocols bgp aggregate-address 203.0.113.0/24 'as-set' # set protocols bgp maximum-paths ebgp '20' # set protocols bgp maximum-paths ibgp '55' # set protocols bgp neighbor 192.0.2.25 'disable-connected-check' # set protocols bgp neighbor 192.0.2.25 timers holdtime '30' # set protocols bgp neighbor 192.0.2.25 timers keepalive '10' # set protocols bgp neighbor 203.0.113.5 attribute-unchanged 'as-path' # set protocols bgp neighbor 203.0.113.5 attribute-unchanged 'med' # set protocols bgp neighbor 203.0.113.5 attribute-unchanged 'next-hop' # set protocols bgp neighbor 203.0.113.5 ebgp-multihop '2' # set protocols bgp neighbor 203.0.113.5 remote-as '101' # set protocols bgp neighbor 203.0.113.5 update-source '192.0.2.25' # set protocols bgp neighbor 5001::64 distribute-list export '20' # set protocols bgp neighbor 5001::64 distribute-list import '40' # set protocols bgp neighbor 5001::64 maximum-prefix '34' # set protocols bgp network 192.1.13.0/24 'backdoor' # set protocols bgp parameters bestpath as-path 'confed' # set protocols bgp parameters bestpath 'compare-routerid' # set protocols bgp parameters confederation identifier '66' # set protocols bgp parameters confederation peers '20' # set protocols bgp parameters confederation peers '55' # set protocols bgp parameters default 'no-ipv4-unicast' # set protocols bgp parameters router-id '192.1.2.9' # set protocols bgp redistribute connected route-map 'map01' # set protocols bgp redistribute kernel metric '45' # set protocols bgp timers keepalive '35' # vyos@vyos:~$ # # # Module Execution: # # "after": { # "aggregate_address": [ # { # "prefix": "192.0.2.0/24", # "summary_only": true # }, # { # "prefix": "203.0.113.0/24", # "as_set": true # } # ], # "as_number": 65536, # "bgp_params": { # "bestpath": { # "as_path": "confed", # "compare_routerid": true # }, # "confederation": [ # { # "identifier": 66 # }, # { # "peers": 20 # }, # { # "peers": 55 # } # ], # "default": { # "no_ipv4_unicast": true # }, # "router_id": "192.1.2.9" # }, # "maximum_paths": [ # { # "count": 20, # "path": "ebgp" # }, # { # "count": 55, # "path": "ibgp" # } # ], # "neighbor": [ # { # "address": "192.0.2.25", # "disable_connected_check": true, # "timers": { # "holdtime": 30, # "keepalive": 10 # } # }, # { # "address": "203.0.113.5", # "attribute_unchanged": { # "as_path": true, # "med": true, # "next_hop": true # }, # "ebgp_multihop": 2, # "remote_as": 101, # "update_source": "192.0.2.25" # }, # { # "address": "5001::64", # "distribute_list": [ # { # "acl": 20, # "action": "export" # }, # { # "acl": 40, # "action": "import" # } # ], # "maximum_prefix": 34 # } # ], # "network": [ # { # "address": "192.1.13.0/24", # "backdoor": true # } # ], # "redistribute": [ # { # "protocol": "connected", # "route_map": "map01" # }, # { # "metric": 45, # "protocol": "kernel" # } # ], # "timers": { # "keepalive": 35 # } # }, # "before": {}, # "changed": true, # "commands": [ # "set protocols bgp neighbor 192.0.2.25 disable-connected-check", # "set protocols bgp neighbor 192.0.2.25 timers holdtime 30", # "set protocols bgp neighbor 192.0.2.25 timers keepalive 10", # "set protocols bgp neighbor 203.0.113.5 attribute-unchanged as-path", # "set protocols bgp neighbor 203.0.113.5 attribute-unchanged med", # "set protocols bgp neighbor 203.0.113.5 attribute-unchanged next-hop", # "set protocols bgp neighbor 203.0.113.5 ebgp-multihop 2", # "set protocols bgp neighbor 203.0.113.5 remote-as 101", # "set protocols bgp neighbor 203.0.113.5 update-source 192.0.2.25", # "set protocols bgp neighbor 5001::64 maximum-prefix 34", # "set protocols bgp neighbor 5001::64 distribute-list export 20", # "set protocols bgp neighbor 5001::64 distribute-list import 40", # "set protocols bgp redistribute kernel metric 45", # "set protocols bgp redistribute connected route-map map01", # "set protocols bgp network 192.1.13.0/24 backdoor", # "set protocols bgp aggregate-address 203.0.113.0/24 as-set", # "set protocols bgp aggregate-address 192.0.2.0/24 summary-only", # "set protocols bgp parameters bestpath as-path confed", # "set protocols bgp parameters bestpath compare-routerid", # "set protocols bgp parameters default no-ipv4-unicast", # "set protocols bgp parameters router-id 192.1.2.9", # "set protocols bgp parameters confederation peers 20", # "set protocols bgp parameters confederation peers 55", # "set protocols bgp parameters confederation identifier 66", # "set protocols bgp maximum-paths ebgp 20", # "set protocols bgp maximum-paths ibgp 55", # "set protocols bgp timers keepalive 35" # ], # Using replaced: # -------------- # Before state: # vyos@vyos:~$ show configuration commands | match "set protocols bgp" # set protocols bgp system-as 65536 # set protocols bgp aggregate-address 192.0.2.0/24 'summary-only' # set protocols bgp aggregate-address 203.0.113.0/24 'as-set' # set protocols bgp maximum-paths ebgp '20' # set protocols bgp maximum-paths ibgp '55' # set protocols bgp neighbor 192.0.2.25 'disable-connected-check' # set protocols bgp neighbor 192.0.2.25 timers holdtime '30' # set protocols bgp neighbor 192.0.2.25 timers keepalive '10' # set protocols bgp neighbor 203.0.113.5 attribute-unchanged 'as-path' # set protocols bgp neighbor 203.0.113.5 attribute-unchanged 'med' # set protocols bgp neighbor 203.0.113.5 attribute-unchanged 'next-hop' # set protocols bgp neighbor 203.0.113.5 ebgp-multihop '2' # set protocols bgp neighbor 203.0.113.5 remote-as '101' # set protocols bgp neighbor 203.0.113.5 update-source '192.0.2.25' # set protocols bgp neighbor 5001::64 distribute-list export '20' # set protocols bgp neighbor 5001::64 distribute-list import '40' # set protocols bgp neighbor 5001::64 maximum-prefix '34' # set protocols bgp network 192.1.13.0/24 'backdoor' # set protocols bgp parameters bestpath as-path 'confed' # set protocols bgp parameters bestpath 'compare-routerid' # set protocols bgp parameters confederation identifier '66' # set protocols bgp parameters confederation peers '20' # set protocols bgp parameters confederation peers '55' # set protocols bgp parameters default 'no-ipv4-unicast' # set protocols bgp parameters router-id '192.1.2.9' # set protocols bgp redistribute connected route-map 'map01' # set protocols bgp redistribute kernel metric '45' # set protocols bgp timers keepalive '35' # vyos@vyos:~$ - name: Replace vyos.vyos.vyos_bgp_global: config: as_number: "65536" network: - address: "203.0.113.0/24" route_map: map01 redistribute: - protocol: "static" route_map: "map01" neighbor: - address: "192.0.2.40" advertisement_interval: 72 capability: orf: "receive" bgp_params: bestpath: as_path: "confed" state: replaced # After state: # vyos@vyos:~$ show configuration commands | match "set protocols bgp" # set protocols bgp system-as 65536 # set protocols bgp neighbor 192.0.2.40 advertisement-interval '72' # set protocols bgp neighbor 192.0.2.40 capability orf prefix-list 'receive' # set protocols bgp network 203.0.113.0/24 route-map 'map01' # set protocols bgp parameters bestpath as-path 'confed' # set protocols bgp redistribute static route-map 'map01' # vyos@vyos:~$ # # # Module Execution: # # "after": { # "as_number": 65536, # "bgp_params": { # "bestpath": { # "as_path": "confed" # } # }, # "neighbor": [ # { # "address": "192.0.2.40", # "advertisement_interval": 72, # "capability": { # "orf": "receive" # } # } # ], # "network": [ # { # "address": "203.0.113.0/24", # "route_map": "map01" # } # ], # "redistribute": [ # { # "protocol": "static", # "route_map": "map01" # } # ] # }, # "before": { # "aggregate_address": [ # { # "prefix": "192.0.2.0/24", # "summary_only": true # }, # { # "prefix": "203.0.113.0/24", # "as_set": true # } # ], # "as_number": 65536, # "bgp_params": { # "bestpath": { # "as_path": "confed", # "compare_routerid": true # }, # "confederation": [ # { # "identifier": 66 # }, # { # "peers": 20 # }, # { # "peers": 55 # } # ], # "default": { # "no_ipv4_unicast": true # }, # "router_id": "192.1.2.9" # }, # "maximum_paths": [ # { # "count": 20, # "path": "ebgp" # }, # { # "count": 55, # "path": "ibgp" # } # ], # "neighbor": [ # { # "address": "192.0.2.25", # "disable_connected_check": true, # "timers": { # "holdtime": 30, # "keepalive": 10 # } # }, # { # "address": "203.0.113.5", # "attribute_unchanged": { # "as_path": true, # "med": true, # "next_hop": true # }, # "ebgp_multihop": 2, # "remote_as": 101, # "update_source": "192.0.2.25" # }, # { # "address": "5001::64", # "distribute_list": [ # { # "acl": 20, # "action": "export" # }, # { # "acl": 40, # "action": "import" # } # ], # "maximum_prefix": 34 # } # ], # "network": [ # { # "address": "192.1.13.0/24", # "backdoor": true # } # ], # "redistribute": [ # { # "protocol": "connected", # "route_map": "map01" # }, # { # "metric": 45, # "protocol": "kernel" # } # ], # "timers": { # "keepalive": 35 # } # }, # "changed": true, # "commands": [ # "delete protocols bgp timers", # "delete protocols bgp maximum-paths ", # "delete protocols bgp maximum-paths ", # "delete protocols bgp parameters router-id 192.1.2.9", # "delete protocols bgp parameters default", # "delete protocols bgp parameters confederation", # "delete protocols bgp parameters bestpath compare-routerid", # "delete protocols bgp aggregate-address", # "delete protocols bgp network 192.1.13.0/24", # "delete protocols bgp redistribute kernel", # "delete protocols bgp redistribute kernel", # "delete protocols bgp redistribute connected", # "delete protocols bgp redistribute connected", # "delete protocols bgp neighbor 5001::64", # "delete protocols bgp neighbor 203.0.113.5", # "delete protocols bgp neighbor 192.0.2.25", # "set protocols bgp neighbor 192.0.2.40 advertisement-interval 72", # "set protocols bgp neighbor 192.0.2.40 capability orf prefix-list receive", # "set protocols bgp redistribute static route-map map01", # "set protocols bgp network 203.0.113.0/24 route-map map01" # ], # Using deleted: # ------------- # Before state: # vyos@vyos:~$ show configuration commands | match "set protocols bgp" # set protocols bgp system-as 65536 # set protocols bgp neighbor 192.0.2.40 advertisement-interval '72' # set protocols bgp neighbor 192.0.2.40 capability orf prefix-list 'receive' # set protocols bgp network 203.0.113.0/24 route-map 'map01' # set protocols bgp parameters bestpath as-path 'confed' # set protocols bgp redistribute static route-map 'map01' # vyos@vyos:~$ - name: Delete configuration vyos.vyos.vyos_bgp_global: config: as_number: "65536" state: deleted # After state: # vyos@vyos:~$ show configuration commands | match "set protocols bgp" # set protocols bgp '65536' # vyos@vyos:~$ # # # Module Execution: # # "after": { # "as_number": 65536 # }, # "before": { # "as_number": 65536, # "bgp_params": { # "bestpath": { # "as_path": "confed" # } # }, # "neighbor": [ # { # "address": "192.0.2.40", # "advertisement_interval": 72, # "capability": { # "orf": "receive" # } # } # ], # "network": [ # { # "address": "203.0.113.0/24", # "route_map": "map01" # } # ], # "redistribute": [ # { # "protocol": "static", # "route_map": "map01" # } # ] # }, # "changed": true, # "commands": [ # "delete protocols bgp neighbor 192.0.2.40", # "delete protocols bgp redistribute", # "delete protocols bgp network", # "delete protocols bgp parameters" # ], # Using purged: # Before state: # vyos@vyos:~$ show configuration commands | match "set protocols bgp" # set protocols bgp system-as 65536 # set protocols bgp aggregate-address 192.0.2.0/24 'summary-only' # set protocols bgp aggregate-address 203.0.113.0/24 'as-set' # set protocols bgp maximum-paths ebgp '20' # set protocols bgp maximum-paths ibgp '55' # set protocols bgp neighbor 192.0.2.25 'disable-connected-check' # set protocols bgp neighbor 192.0.2.25 timers holdtime '30' # set protocols bgp neighbor 192.0.2.25 timers keepalive '10' # set protocols bgp neighbor 203.0.113.5 attribute-unchanged 'as-path' # set protocols bgp neighbor 203.0.113.5 attribute-unchanged 'med' # set protocols bgp neighbor 203.0.113.5 attribute-unchanged 'next-hop' # set protocols bgp neighbor 203.0.113.5 ebgp-multihop '2' # set protocols bgp neighbor 203.0.113.5 remote-as '101' # set protocols bgp neighbor 203.0.113.5 update-source '192.0.2.25' # set protocols bgp neighbor 5001::64 distribute-list export '20' # set protocols bgp neighbor 5001::64 distribute-list import '40' # set protocols bgp neighbor 5001::64 maximum-prefix '34' # set protocols bgp network 192.1.13.0/24 'backdoor' # set protocols bgp parameters bestpath as-path 'confed' # set protocols bgp parameters bestpath 'compare-routerid' # set protocols bgp parameters confederation identifier '66' # set protocols bgp parameters confederation peers '20' # set protocols bgp parameters confederation peers '55' # set protocols bgp parameters default 'no-ipv4-unicast' # set protocols bgp parameters router-id '192.1.2.9' # set protocols bgp redistribute connected route-map 'map01' # set protocols bgp redistribute kernel metric '45' # set protocols bgp timers keepalive '35' # vyos@vyos:~$ - name: Purge configuration vyos.vyos.vyos_bgp_global: config: as_number: "65536" state: purged # After state: # vyos@vyos:~$ show configuration commands | match "set protocols bgp" # vyos@vyos:~$ # # Module Execution: # # "after": {}, # "before": { # "aggregate_address": [ # { # "prefix": "192.0.2.0/24", # "summary_only": true # }, # { # "prefix": "203.0.113.0/24", # "as_set": true # } # ], # "as_number": 65536, # "bgp_params": { # "bestpath": { # "as_path": "confed", # "compare_routerid": true # }, # "confederation": [ # { # "identifier": 66 # }, # { # "peers": 20 # }, # { # "peers": 55 # } # ], # "default": { # "no_ipv4_unicast": true # }, # "router_id": "192.1.2.9" # }, # "maximum_paths": [ # { # "count": 20, # "path": "ebgp" # }, # { # "count": 55, # "path": "ibgp" # } # ], # "neighbor": [ # { # "address": "192.0.2.25", # "disable_connected_check": true, # "timers": { # "holdtime": 30, # "keepalive": 10 # } # }, # { # "address": "203.0.113.5", # "attribute_unchanged": { # "as_path": true, # "med": true, # "next_hop": true # }, # "ebgp_multihop": 2, # "remote_as": 101, # "update_source": "192.0.2.25" # }, # { # "address": "5001::64", # "distribute_list": [ # { # "acl": 20, # "action": "export" # }, # { # "acl": 40, # "action": "import" # } # ], # "maximum_prefix": 34 # } # ], # "network": [ # { # "address": "192.1.13.0/24", # "backdoor": true # } # ], # "redistribute": [ # { # "protocol": "connected", # "route_map": "map01" # }, # { # "metric": 45, # "protocol": "kernel" # } # ], # "timers": { # "keepalive": 35 # } # }, # "changed": true, # "commands": [ # "delete protocols bgp 65536" # ], # Deleted in presence of address family under neighbors: # Before state: # vyos@vyos:~$ show configuration commands | match "set protocols bgp" # set protocols bgp system-as 65536 # set protocols bgp neighbor 192.0.2.43 advertisement-interval '72' # set protocols bgp neighbor 192.0.2.43 capability 'dynamic' # set protocols bgp neighbor 192.0.2.43 'disable-connected-check' # set protocols bgp neighbor 192.0.2.43 timers holdtime '30' # set protocols bgp neighbor 192.0.2.43 timers keepalive '10' # set protocols bgp neighbor 203.0.113.0 address-family 'ipv6-unicast' # set protocols bgp neighbor 203.0.113.0 capability orf prefix-list 'receive' # set protocols bgp network 203.0.113.0/24 route-map 'map01' # set protocols bgp parameters 'always-compare-med' # set protocols bgp parameters bestpath as-path 'confed' # set protocols bgp parameters bestpath 'compare-routerid' # set protocols bgp parameters dampening half-life '33' # set protocols bgp parameters dampening max-suppress-time '20' # set protocols bgp parameters dampening re-use '60' # set protocols bgp parameters dampening start-suppress-time '5' # set protocols bgp parameters default 'no-ipv4-unicast' # set protocols bgp parameters distance global external '66' # set protocols bgp parameters distance global internal '20' # set protocols bgp parameters distance global local '10' # set protocols bgp redistribute static route-map 'map01' # vyos@vyos:~$ ^C # vyos@vyos:~$ - name: Delete configuration vyos.vyos.vyos_bgp_global: config: as_number: "65536" state: deleted # Module Execution: # # "changed": false, # "invocation": { # "module_args": { # "config": { # "aggregate_address": null, # "as_number": 65536, # "bgp_params": null, # "maximum_paths": null, # "neighbor": null, # "network": null, # "redistribute": null, # "timers": null # }, # "running_config": null, # "state": "deleted" # } # }, # "msg": "Use the _bgp_address_family module to delete the address_family under neighbor 203.0.113.0, before replacing/deleting the neighbor." # } # using gathered: # -------------- # Before state: # vyos@vyos:~$ show configuration commands | match "set protocols bgp" # set protocols bgp system-as 65536 # set protocols bgp neighbor 192.0.2.43 advertisement-interval '72' # set protocols bgp neighbor 192.0.2.43 capability 'dynamic' # set protocols bgp neighbor 192.0.2.43 'disable-connected-check' # set protocols bgp neighbor 192.0.2.43 timers holdtime '30' # set protocols bgp neighbor 192.0.2.43 timers keepalive '10' # set protocols bgp neighbor 203.0.113.0 address-family 'ipv6-unicast' # set protocols bgp neighbor 203.0.113.0 capability orf prefix-list 'receive' # set protocols bgp network 203.0.113.0/24 route-map 'map01' # set protocols bgp parameters 'always-compare-med' # set protocols bgp parameters bestpath as-path 'confed' # set protocols bgp parameters bestpath 'compare-routerid' # set protocols bgp parameters dampening half-life '33' # set protocols bgp parameters dampening max-suppress-time '20' # set protocols bgp parameters dampening re-use '60' # set protocols bgp parameters dampening start-suppress-time '5' # set protocols bgp parameters default 'no-ipv4-unicast' # set protocols bgp parameters distance global external '66' # set protocols bgp parameters distance global internal '20' # set protocols bgp parameters distance global local '10' # set protocols bgp redistribute static route-map 'map01' # vyos@vyos:~$ ^C - name: gather configs vyos.vyos.vyos_bgp_global: state: gathered # Module Execution: # "gathered": { # "as_number": 65536, # "bgp_params": { # "always_compare_med": true, # "bestpath": { # "as_path": "confed", # "compare_routerid": true # }, # "default": { # "no_ipv4_unicast": true # }, # "distance": [ # { # "type": "external", # "value": 66 # }, # { # "type": "internal", # "value": 20 # }, # { # "type": "local", # "value": 10 # } # ] # }, # "neighbor": [ # { # "address": "192.0.2.43", # "advertisement_interval": 72, # "capability": { # "dynamic": true # }, # "disable_connected_check": true, # "timers": { # "holdtime": 30, # "keepalive": 10 # } # }, # { # "address": "203.0.113.0", # "capability": { # "orf": "receive" # } # } # ], # "network": [ # { # "address": "203.0.113.0/24", # "route_map": "map01" # } # ], # "redistribute": [ # { # "protocol": "static", # "route_map": "map01" # } # ] # }, # # Using parsed: # ------------ # parsed.cfg # set protocols bgp neighbor 192.0.2.43 advertisement-interval '72' # set protocols bgp neighbor 192.0.2.43 capability 'dynamic' # set protocols bgp neighbor 192.0.2.43 'disable-connected-check' # set protocols bgp neighbor 192.0.2.43 timers holdtime '30' # set protocols bgp neighbor 192.0.2.43 timers keepalive '10' # set protocols bgp neighbor 203.0.113.0 address-family 'ipv6-unicast' # set protocols bgp neighbor 203.0.113.0 capability orf prefix-list 'receive' # set protocols bgp network 203.0.113.0/24 route-map 'map01' # set protocols bgp parameters 'always-compare-med' # set protocols bgp parameters bestpath as-path 'confed' # set protocols bgp parameters bestpath 'compare-routerid' # set protocols bgp parameters dampening half-life '33' # set protocols bgp parameters dampening max-suppress-time '20' # set protocols bgp parameters dampening re-use '60' # set protocols bgp parameters dampening start-suppress-time '5' # set protocols bgp parameters default 'no-ipv4-unicast' # set protocols bgp parameters distance global external '66' # set protocols bgp parameters distance global internal '20' # set protocols bgp parameters distance global local '10' # set protocols bgp redistribute static route-map 'map01' - name: parse configs vyos.vyos.vyos_bgp_global: running_config: "{{ lookup('file', './parsed.cfg') }}" state: parsed tags: - parsed # Module execution: # "parsed": { # "as_number": 65536, # "bgp_params": { # "always_compare_med": true, # "bestpath": { # "as_path": "confed", # "compare_routerid": true # }, # "default": { # "no_ipv4_unicast": true # }, # "distance": [ # { # "type": "external", # "value": 66 # }, # { # "type": "internal", # "value": 20 # }, # { # "type": "local", # "value": 10 # } # ] # }, # "neighbor": [ # { # "address": "192.0.2.43", # "advertisement_interval": 72, # "capability": { # "dynamic": true # }, # "disable_connected_check": true, # "timers": { # "holdtime": 30, # "keepalive": 10 # } # }, # { # "address": "203.0.113.0", # "capability": { # "orf": "receive" # } # } # ], # "network": [ # { # "address": "203.0.113.0/24", # "route_map": "map01" # } # ], # "redistribute": [ # { # "protocol": "static", # "route_map": "map01" # } # ] # } # # Using rendered: # -------------- - name: Render vyos.vyos.vyos_bgp_global: config: as_number: "65536" network: - address: "203.0.113.0/24" route_map: map01 redistribute: - protocol: "static" route_map: "map01" bgp_params: always_compare_med: true dampening: start_suppress_time: 5 max_suppress_time: 20 half_life: 33 re_use: 60 distance: - type: "internal" value: 20 - type: "local" value: 10 - type: "external" value: 66 bestpath: as_path: "confed" compare_routerid: true default: no_ipv4_unicast: true neighbor: - address: "192.0.2.43" disable_connected_check: true advertisement_interval: 72 capability: dynamic: true timers: holdtime: 30 keepalive: 10 - address: "203.0.113.0" capability: orf: "receive" state: rendered # Module Execution: # "rendered": [ # "set protocols bgp neighbor 192.0.2.43 disable-connected-check", # "set protocols bgp neighbor 192.0.2.43 advertisement-interval 72", # "set protocols bgp neighbor 192.0.2.43 capability dynamic", # "set protocols bgp neighbor 192.0.2.43 timers holdtime 30", # "set protocols bgp neighbor 192.0.2.43 timers keepalive 10", # "set protocols bgp neighbor 203.0.113.0 capability orf prefix-list receive", # "set protocols bgp redistribute static route-map map01", # "set protocols bgp network 203.0.113.0/24 route-map map01", # "set protocols bgp parameters always-compare-med", # "set protocols bgp parameters dampening half-life 33", # "set protocols bgp parameters dampening max-suppress-time 20", # "set protocols bgp parameters dampening re-use 60", # "set protocols bgp parameters dampening start-suppress-time 5", # "set protocols bgp parameters distance global internal 20", # "set protocols bgp parameters distance global local 10", # "set protocols bgp parameters distance global external 66", # "set protocols bgp parameters bestpath as-path confed", # "set protocols bgp parameters bestpath compare-routerid", # "set protocols bgp parameters default no-ipv4-unicast" # ] Return Values ------------- Common return values are documented `here `_, the following are the fields unique to this module: .. raw:: html
Key Returned Description
after
dictionary
when changed
The resulting configuration after module execution.

Sample:
This output will always be in the same format as the module argspec.
before
dictionary
when state is merged, replaced, overridden, deleted or purged
The configuration prior to the module execution.

Sample:
This output will always be in the same format as the module argspec.
commands
list
when state is merged, replaced, overridden, deleted or purged
The set of commands pushed to the remote device.

Sample:
['set protocols bgp redistribute static route-map map01', 'set protocols bgp network 203.0.113.0/24 route-map map01', 'set protocols bgp parameters always-compare-med']
gathered
list
when state is gathered
Facts about the network resource gathered from the remote device as structured data.

Sample:
This output will always be in the same format as the module argspec.
parsed
list
when state is parsed
The device native config provided in running_config option parsed into structured data as per module argspec.

Sample:
This output will always be in the same format as the module argspec.
rendered
list
when state is rendered
The provided configuration in the task rendered in device-native format (offline).

Sample:
['set protocols bgp redistribute static route-map map01', 'set protocols bgp network 203.0.113.0/24 route-map map01', 'set protocols bgp parameters always-compare-med']


Status ------ Authors ~~~~~~~ - Gomathi Selvi Srinivasan (@GomathiselviS) diff --git a/docs/vyos.vyos.vyos_config_module.rst b/docs/vyos.vyos.vyos_config_module.rst index e2be25b9..c8a858e2 100644 --- a/docs/vyos.vyos.vyos_config_module.rst +++ b/docs/vyos.vyos.vyos_config_module.rst @@ -1,437 +1,477 @@ .. _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 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.
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.
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.
+
+ replace + +
+ boolean +
+ 		+
    Choices: +
  • no ←
    • +
  • yes
    • +
+ 		+
The replace argument will replace the entire config, instead of merging it with the base config that is already present. This only works in match is in line mode. For backwards compatibility default is false.
+
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: 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/plugins/cliconf/vyos.py b/plugins/cliconf/vyos.py index 2281e14d..e4831469 100644 --- a/plugins/cliconf/vyos.py +++ b/plugins/cliconf/vyos.py @@ -1,380 +1,387 @@ # (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_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 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) + 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=False, ): 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_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") 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") if diff_match == "none": diff["config_diff"] = list(candidate_commands) 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"): match = False for rline in running_commands: if match_cmd(item, rline): match = True if not match: 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) if diff_replace: for line in running.splitlines(): - line = line.replace("'", "\"") + line = line.replace("'", '"') match = False for cline in candidate_commands: if match_cmd(line, cline): match = True if not match: line = re.sub(r"set", "delete", line) updates.append(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_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") + def match_cmd(cmd1, cmd2): cmd1 = re.sub("['\"]", "", cmd1) cmd2 = re.sub("['\"]", "", cmd2) if cmd1 == cmd2: return True else: return False