From 45dc95873fd906c582fbbd5e6ca3838caf867399 Mon Sep 17 00:00:00 2001 From: omnom62 Date: Mon, 6 Jul 2026 14:54:12 +1000 Subject: T8989: wave4 vyos_command, dict_op refactor * T8989: vyos_command module * T8989: vyos_command module UAT and SIT * T8989: vyos_command changelog * T8989: vyos_command linter * T8989: vyos_config module * T8989: vyos_config module changelog * T8989: Wave 4 vyos_config module with integration and unit tests * T8323: vyos_system module * T8332: vyos_system SIT and UAT * T8323: vyos_vlan module * T8323: vyos_vlan module * T8323: vyos_vlan module SIT and UAT * T8323: vyos_system module * T8989: Wave 4 vyos_vlan reworked with dict_op engine * T8989: Fix dict_op single-value string list handling, add vyos_system integration tests * T8989: logging_global refactor * T8989: migrate ntp_global, logging_global, firewall_global to dict_op engine * T8989: vyos_nat module for REST API collection * T8989: vyos_nat module for REST API collection, linter fixes * T8989: vyos_ha module for REST API collection * T8989: vyos_ha module for REST API collection * T8989: vyos_ha module sanity and linter fixes * T8989: vyos_ha module sanity and linter fixes * T8989: vyos_ha module linter fixes * T8989: vyos.rest AI comment fixes * T8323: vyos_nat AI comment fixes * T8989 ai fixes * T8989: vyos_bgp_address_family dict_op * T8989: vyos_bgp_address_family vyos_bgp_global dict_op * T8989: dict_op refactor for firewall_*, nat, user * T8989: dict_op refactor for firewall_*, nat, user * T8989: dict_op refactor for ntp_global, ha * T8989: snmp_server dict_op refactor * T8989: snmp_server dict_op refactor * T8989: route_map dict_op refactor --- docs/vyos.rest.vyos_bgp_address_family_module.rst | 4 +- docs/vyos.rest.vyos_bgp_global_module.rst | 4 +- docs/vyos.rest.vyos_command_module.rst | 252 +++ docs/vyos.rest.vyos_config_module.rst | 228 +++ docs/vyos.rest.vyos_firewall_global_module.rst | 4 +- docs/vyos.rest.vyos_firewall_interfaces_module.rst | 4 +- docs/vyos.rest.vyos_firewall_rules_module.rst | 5 +- docs/vyos.rest.vyos_ha_module.rst | 1668 ++++++++++++++++++++ docs/vyos.rest.vyos_logging_global_module.rst | 239 +-- docs/vyos.rest.vyos_nat_module.rst | 208 +++ docs/vyos.rest.vyos_ntp_global_module.rst | 50 +- docs/vyos.rest.vyos_route_maps_module.rst | 960 ++++++++++- docs/vyos.rest.vyos_snmp_server_module.rst | 12 +- docs/vyos.rest.vyos_system_module.rst | 254 +++ docs/vyos.rest.vyos_user_module.rst | 4 +- docs/vyos.rest.vyos_vlan_module.rst | 303 ++++ 16 files changed, 3864 insertions(+), 335 deletions(-) create mode 100644 docs/vyos.rest.vyos_command_module.rst create mode 100644 docs/vyos.rest.vyos_config_module.rst create mode 100644 docs/vyos.rest.vyos_ha_module.rst create mode 100644 docs/vyos.rest.vyos_nat_module.rst create mode 100644 docs/vyos.rest.vyos_system_module.rst create mode 100644 docs/vyos.rest.vyos_vlan_module.rst (limited to 'docs') diff --git a/docs/vyos.rest.vyos_bgp_address_family_module.rst b/docs/vyos.rest.vyos_bgp_address_family_module.rst index d9d45d7..f55fa15 100644 --- a/docs/vyos.rest.vyos_bgp_address_family_module.rst +++ b/docs/vyos.rest.vyos_bgp_address_family_module.rst @@ -989,7 +989,7 @@ Common return values are documented `here dictionary - when changes are applied + always
Raw API response.

@@ -1004,7 +1004,7 @@ Common return values are documented `here boolean - when changes are applied + when changed
Whether the config was saved after changes.

diff --git a/docs/vyos.rest.vyos_bgp_global_module.rst b/docs/vyos.rest.vyos_bgp_global_module.rst index 01bcefe..db5a759 100644 --- a/docs/vyos.rest.vyos_bgp_global_module.rst +++ b/docs/vyos.rest.vyos_bgp_global_module.rst @@ -841,7 +841,7 @@ Common return values are documented `here dictionary - when changes are applied + always
Raw API response.

@@ -856,7 +856,7 @@ Common return values are documented `here boolean - when changes are applied + when changed
Whether the config was saved after changes.

diff --git a/docs/vyos.rest.vyos_command_module.rst b/docs/vyos.rest.vyos_command_module.rst new file mode 100644 index 0000000..7075ec6 --- /dev/null +++ b/docs/vyos.rest.vyos_command_module.rst @@ -0,0 +1,252 @@ +.. _vyos.rest.vyos_command_module: + + +********************** +vyos.rest.vyos_command +********************** + +**Run show commands on VyOS devices using REST API** + + +Version added: 1.0.0 + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Sends show commands to VyOS devices via the REST API ``/show`` endpoint and returns the output. +- Equivalent to ``vyos_command`` in the CLI collection but uses the REST API. +- Uses REST API (``connection=httpapi``) instead of CLI. + + + + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterChoices/DefaultsComments
+
+ commands + +
+ list + / elements=raw + / required +
+ 		+ +
List of show commands to run on the device.
+
Each command is a list of path elements passed to the /show endpoint.
+
Commands may be specified as a string (space-separated) or a list.
+
+
+ interval + +
+ integer +
+ 		+ Default:
1
+ 		+
Configures the interval in seconds to wait between retries of the command.
+
+
+ match + +
+ string +
+ 		+
    Choices: +
  • any
    • +
  • all ←
    • +
+ 		+
The match argument is used in conjunction with the wait_for argument to specify the match policy.
+
+
+ retries + +
+ integer +
+ 		+ Default:
10
+ 		+
Specifies the number of retries a command should be run before it is considered failed.
+
+
+ wait_for + +
+ list + / elements=string +
+ 		+ +
Specifies what to evaluate from the output of the command and what conditionals to apply. This argument will cause the task to wait for a particular conditional to be true before moving forward.
+

aliases: waitfor
+
+
+ + +Notes +----- + +.. note:: + - Requires ``ansible_connection=httpapi`` with the VyOS httpapi plugin. + - ``ansible_network_os`` must be set to ``vyos.rest.vyos``. + - Only ``show`` commands are supported via the REST API. + - Commands are passed as path lists to the ``/show`` endpoint. + + + +Examples +-------- + +.. code-block:: yaml + + - name: Run show version + vyos.rest.vyos_command: + commands: + - - version + register: result + + - name: Run multiple show commands + vyos.rest.vyos_command: + commands: + - - interfaces + - - ip + - route + - - system + - uptime + register: result + + - name: Run show commands as strings + vyos.rest.vyos_command: + commands: + - "interfaces" + - "ip route" + - "version" + register: result + + - name: Wait for BGP to establish + vyos.rest.vyos_command: + commands: + - - ip + - bgp + - summary + wait_for: + - result[0] contains Established + retries: 10 + interval: 5 + + + +Return Values +------------- +Common return values are documented `here `_, the following are the fields unique to this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + +
KeyReturnedDescription
+
+ failed_conditions + +
+ list +
+ 		failed +
List of conditions that failed.
+
+
+
+ stdout + +
+ list +
+ 		always +
List of output from each command.
+
+
Sample:
+
['VyOS 1.5.0\n...', 'Interface IP Address\n...']
+
+
+ stdout_lines + +
+ list +
+ 		always +
List of output split into lines for each command.
+
+
+

+ + +Status +------ + + +Authors +~~~~~~~ + +- VyOS Community (@vyos) diff --git a/docs/vyos.rest.vyos_config_module.rst b/docs/vyos.rest.vyos_config_module.rst new file mode 100644 index 0000000..9753ba3 --- /dev/null +++ b/docs/vyos.rest.vyos_config_module.rst @@ -0,0 +1,228 @@ +.. _vyos.rest.vyos_config_module: + + +********************* +vyos.rest.vyos_config +********************* + +**Manage VyOS configuration using REST API** + + +Version added: 1.0.0 + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Manages VyOS device configuration via the REST API. +- Accepts configuration commands in CLI ``set``/``delete`` string format and applies them via the REST ``/configure`` endpoint. +- Uses REST API (``connection=httpapi``) instead of CLI. + + + + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterChoices/DefaultsComments
+
+ lines + +
+ list + / elements=string +
+ 		+ +
Ordered list of set or delete commands to apply.
+
Commands should be in standard VyOS CLI format, e.g. set system host-name router1 or delete protocols bgp.
+
+
+ match + +
+ string +
+ 		+
    Choices: +
  • line ←
    • +
  • none
    • +
+ 		+
Controls how commands are matched against the running configuration.
+
line checks each command against the running config and only applies commands that would change the configuration.
+
none applies all commands without checking the running config.
+
+
+ save + +
+ boolean +
+ 		+
    Choices: +
  • no ←
    • +
  • yes
    • +
+ 		+
Save the configuration to disk after applying changes.
+
+
+ src + +
+ path +
+ 		+ +
Path to a file containing set/delete commands, one per line.
+
Blank lines and lines starting with # are ignored.
+
Mutually exclusive with lines.
+
+
+ + +Notes +----- + +.. note:: + - Requires ``ansible_connection=httpapi`` with the VyOS httpapi plugin. + - ``ansible_network_os`` must be set to ``vyos.rest.vyos``. + - Unlike the CLI collection's ``vyos_config``, this module does not support ``backup``, ``confirm``, or ``comment`` options as these are CLI-specific. + - Commands are parsed from CLI string format into REST API path arrays. + + + +Examples +-------- + +.. code-block:: yaml + + - name: Apply configuration lines + vyos.rest.vyos_config: + lines: + - set system host-name router1 + - set system domain-name example.com + - set interfaces ethernet eth0 description "WAN" + save: true + + - name: Delete configuration + vyos.rest.vyos_config: + lines: + - delete protocols bgp + save: true + + - name: Apply config from file + vyos.rest.vyos_config: + src: /tmp/vyos_config.txt + match: none + save: true + + - name: Always apply without matching + vyos.rest.vyos_config: + lines: + - set system host-name router1 + match: none + + + +Return Values +------------- +Common return values are documented `here `_, the following are the fields unique to this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + +
KeyReturnedDescription
+
+ commands + +
+ list +
+ 		always +
List of commands applied to the device.
+
+
+
+ response + +
+ dictionary +
+ 		always +
Raw API response from the device.
+
+
+
+ saved + +
+ boolean +
+ 		when save is true and changes were made +
Whether the configuration was saved to disk.
+
+
+

+ + +Status +------ + + +Authors +~~~~~~~ + +- VyOS Community (@vyos) diff --git a/docs/vyos.rest.vyos_firewall_global_module.rst b/docs/vyos.rest.vyos_firewall_global_module.rst index d90c96a..ff119a8 100644 --- a/docs/vyos.rest.vyos_firewall_global_module.rst +++ b/docs/vyos.rest.vyos_firewall_global_module.rst @@ -607,7 +607,7 @@ Common return values are documented `here dictionary - when changes are applied + always
Raw API response.

@@ -622,7 +622,7 @@ Common return values are documented `here boolean - when changes are applied + when changed
Whether the config was saved after changes.

diff --git a/docs/vyos.rest.vyos_firewall_interfaces_module.rst b/docs/vyos.rest.vyos_firewall_interfaces_module.rst index 56effe1..9ec4a3b 100644 --- a/docs/vyos.rest.vyos_firewall_interfaces_module.rst +++ b/docs/vyos.rest.vyos_firewall_interfaces_module.rst @@ -597,7 +597,7 @@ Common return values are documented `here dictionary - when changes are applied + always
Raw API response.

@@ -612,7 +612,7 @@ Common return values are documented `here boolean - when changes are applied + when changed
Whether the config was saved after changes.

diff --git a/docs/vyos.rest.vyos_firewall_rules_module.rst b/docs/vyos.rest.vyos_firewall_rules_module.rst index b0e32c8..1f316fd 100644 --- a/docs/vyos.rest.vyos_firewall_rules_module.rst +++ b/docs/vyos.rest.vyos_firewall_rules_module.rst @@ -564,6 +564,7 @@ Notes - Requires ``ansible_connection=httpapi`` with the VyOS httpapi plugin. - ``ansible_network_os`` must be set to ``vyos.rest.vyos``. - Rule sets are identified by AFI and name. Deleting a rule set removes all its rules. + - The ``group`` suboption can only reference an address-group. VyOS also supports network-group/port-group/domain-group references, which this module can read back (via ``gathered``) if already configured by other means, but cannot create -- the argspec has no group-type discriminator. @@ -690,7 +691,7 @@ Common return values are documented `here dictionary - when changes are applied + always
Raw API response.

@@ -705,7 +706,7 @@ Common return values are documented `here boolean - when changes are applied + when changed
Whether the config was saved after changes.

diff --git a/docs/vyos.rest.vyos_ha_module.rst b/docs/vyos.rest.vyos_ha_module.rst new file mode 100644 index 0000000..68370cf --- /dev/null +++ b/docs/vyos.rest.vyos_ha_module.rst @@ -0,0 +1,1668 @@ +.. _vyos.rest.vyos_ha_module: + + +***************** +vyos.rest.vyos_ha +***************** + +**Manage VRRP and load balancer configuration on VyOS via REST API** + + +Version added: 1.0.0 + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Manages VRRP groups, global VRRP parameters, sync-groups, virtual servers, and LVS real servers on VyOS devices via the REST API. +- Uses REST API (``connection=httpapi``) instead of CLI. +- Targets VyOS 1.4+. + + + + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterChoices/DefaultsComments
+
+ config + +
+ dictionary +
+ 		+ +
High-availability configuration.
+
+
+ disable + +
+ boolean +
+ 		+
    Choices: +
  • no ←
    • +
  • yes
    • +
+ 		+
Disable all high-availability configuration.
+
+
+ virtual_servers + +
+ list + / elements=dictionary +
+ 		+ +
List of load balancer virtual server definitions.
+
+
+ address + +
+ string +
+ 		+ +
Address.
+
+
+ algorithm + +
+ string +
+ 		+ +
Algorithm.
+
+
+ delay_loop + +
+ integer +
+ 		+ +
Delay loop.
+
+
+ forward_method + +
+ string +
+ 		+
    Choices: +
  • direct
    • +
  • nat
    • +
+ 		+
Forward method.
+
+
+ fwmark + +
+ integer +
+ 		+ +
Fwmark.
+
+
+ name + +
+ string + / required +
+ 		+ +
Name.
+
+
+ persistence_timeout + +
+ integer +
+ 		+ +
Persistence timeout.
+
+
+ port + +
+ integer +
+ 		+ +
Port.
+
+
+ protocol + +
+ string +
+ 		+
    Choices: +
  • tcp
    • +
  • udp
    • +
+ 		+
Protocol.
+
+
+ real_server + +
+ list + / elements=dictionary +
+ 		+ +
Real server.
+
+
+ address + +
+ string + / required +
+ 		+ +
Address.
+
+
+ connection_timeout + +
+ integer +
+ 		+ +
Connection timeout.
+
+
+ health_check_script + +
+ string +
+ 		+ +
Health check script.
+
+
+ port + +
+ integer +
+ 		+ +
Port.
+
+
+ vrrp + +
+ dictionary +
+ 		+ +
VRRP configuration.
+
+
+ global_parameters + +
+ dictionary +
+ 		+ +
Global parameters.
+
+
+ garp + +
+ dictionary +
+ 		+ +
Garp.
+
+
+ interval + +
+ integer +
+ 		+ +
Interval.
+
+
+ master_delay + +
+ integer +
+ 		+ +
Master delay.
+
+
+ master_refresh + +
+ integer +
+ 		+ +
Master refresh.
+
+
+ master_refresh_repeat + +
+ integer +
+ 		+ +
Master refresh repeat.
+
+
+ master_repeat + +
+ integer +
+ 		+ +
Master repeat.
+
+
+ startup_delay + +
+ integer +
+ 		+ +
Startup delay.
+
+
+ version + +
+ string +
+ 		+ +
Version.
+
+
+ groups + +
+ list + / elements=dictionary +
+ 		+ +
Groups.
+
+
+ address + +
+ list + / elements=string +
+ 		+ +
Address.
+
+
+ advertise_interval + +
+ integer +
+ 		+ +
Advertise interval.
+
+
+ authentication + +
+ dictionary +
+ 		+ +
Authentication.
+
+
+ password + +
+ string +
+ 		+ +
Password.
+
+
+ type + +
+ string +
+ 		+ +
Type.
+
+
+ description + +
+ string +
+ 		+ +
Description.
+
+
+ disable + +
+ boolean +
+ 		+
    Choices: +
  • no ←
    • +
  • yes
    • +
+ 		+
Disable.
+
+
+ excluded_address + +
+ list + / elements=string +
+ 		+ +
Excluded address.
+
+
+ garp + +
+ dictionary +
+ 		+ +
Garp.
+
+
+ interval + +
+ integer +
+ 		+ +
Interval.
+
+
+ master_delay + +
+ integer +
+ 		+ +
Master delay.
+
+
+ master_refresh + +
+ integer +
+ 		+ +
Master refresh.
+
+
+ master_refresh_repeat + +
+ integer +
+ 		+ +
Master refresh repeat.
+
+
+ master_repeat + +
+ integer +
+ 		+ +
Master repeat.
+
+
+ health_check + +
+ dictionary +
+ 		+ +
Health check.
+
+
+ failure_count + +
+ integer +
+ 		+ +
Failure count.
+
+
+ interval + +
+ integer +
+ 		+ +
Interval.
+
+
+ ping + +
+ string +
+ 		+ +
Ping.
+
+
+ script + +
+ string +
+ 		+ +
Script.
+
+
+ hello_source_address + +
+ string +
+ 		+ +
Hello source address.
+
+
+ interface + +
+ string +
+ 		+ +
Interface.
+
+
+ name + +
+ string + / required +
+ 		+ +
Name.
+
+
+ no_preempt + +
+ boolean +
+ 		+
    Choices: +
  • no ←
    • +
  • yes
    • +
+ 		+
No preempt.
+
+
+ peer_address + +
+ string +
+ 		+ +
Peer address.
+
+
+ preempt_delay + +
+ integer +
+ 		+ +
Preempt delay.
+
+
+ priority + +
+ integer +
+ 		+ +
Priority.
+
+
+ rfc3768_compatibility + +
+ boolean +
+ 		+
    Choices: +
  • no ←
    • +
  • yes
    • +
+ 		+
Rfc3768 compatibility.
+
+
+ track + +
+ dictionary +
+ 		+ +
Track.
+
+
+ exclude_vrrp_interface + +
+ boolean +
+ 		+
    Choices: +
  • no
    • +
  • yes
    • +
+ 		+
Exclude vrrp interface.
+
+
+ interface + +
+ list + / elements=string +
+ 		+ +
Interface.
+
+
+ transition_script + +
+ dictionary +
+ 		+ +
Transition script.
+
+
+ backup + +
+ string +
+ 		+ +
Backup.
+
+
+ fault + +
+ string +
+ 		+ +
Fault.
+
+
+ master + +
+ string +
+ 		+ +
Master.
+
+
+ stop + +
+ string +
+ 		+ +
Stop.
+
+
+ vrid + +
+ integer +
+ 		+ +
Vrid.
+
+
+ snmp + +
+ string +
+ 		+
    Choices: +
  • enabled
    • +
  • disabled
    • +
+ 		+
Snmp.
+
+
+ sync_groups + +
+ list + / elements=dictionary +
+ 		+ +
Sync groups.
+
+
+ health_check + +
+ dictionary +
+ 		+ +
Health check.
+
+
+ failure_count + +
+ integer +
+ 		+ +
Failure count.
+
+
+ interval + +
+ integer +
+ 		+ +
Interval.
+
+
+ ping + +
+ string +
+ 		+ +
Ping.
+
+
+ script + +
+ string +
+ 		+ +
Script.
+
+
+ member + +
+ list + / elements=string +
+ 		+ +
Member.
+
+
+ name + +
+ string + / required +
+ 		+ +
Name.
+
+
+ transition_script + +
+ dictionary +
+ 		+ +
Transition script.
+
+
+ backup + +
+ string +
+ 		+ +
Backup.
+
+
+ fault + +
+ string +
+ 		+ +
Fault.
+
+
+ master + +
+ string +
+ 		+ +
Master.
+
+
+ stop + +
+ string +
+ 		+ +
Stop.
+
+
+ state + +
+ string +
+ 		+
    Choices: +
  • merged ←
    • +
  • replaced
    • +
  • overridden
    • +
  • deleted
    • +
  • gathered
    • +
+ 		+
Desired end state of the configuration.
+
+
+ + + + +Examples +-------- + +.. code-block:: yaml + + - name: Merge VRRP configuration + vyos.rest.vyos_ha: + config: + vrrp: + global_parameters: + startup_delay: 30 + groups: + - name: g1 + interface: eth0 + vrid: 20 + priority: 100 + address: + - 192.168.1.100/24 + sync_groups: + - name: sg1 + member: [g1] + snmp: enabled + state: merged + + - name: Delete all HA configuration + vyos.rest.vyos_ha: + state: deleted + + - name: Gather current HA configuration + vyos.rest.vyos_ha: + state: gathered + + + +Return Values +------------- +Common return values are documented `here `_, the following are the fields unique to this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyReturnedDescription
+
+ after + +
+ dictionary +
+ 		when changed +
HA configuration after this module ran.
+
+
+
+ before + +
+ dictionary +
+ 		always +
HA configuration before this module ran.
+
+
+
+ commands + +
+ list +
+ 		always +
List of API commands sent to the device.
+
+
+
+ gathered + +
+ dictionary +
+ 		when state is gathered +
Current HA configuration as structured data.
+
+
+
+ saved + +
+ boolean +
+ 		when changed +
Whether the config was saved after changes.
+
+
+

+ + +Status +------ + + +Authors +~~~~~~~ + +- Evgeny Molotkov (@omnom62) diff --git a/docs/vyos.rest.vyos_logging_global_module.rst b/docs/vyos.rest.vyos_logging_global_module.rst index da5572e..b529dd0 100644 --- a/docs/vyos.rest.vyos_logging_global_module.rst +++ b/docs/vyos.rest.vyos_logging_global_module.rst @@ -18,7 +18,7 @@ Version added: 1.0.0 Synopsis -------- - Manages syslog (logging) configuration on VyOS devices via the REST API. -- Supports console, file, host, user, and global logging targets with per-target facility and severity configuration. +- Targets VyOS 1.5+ syslog schema under ``system syslog``. - Uses REST API (``connection=httpapi``) instead of CLI. @@ -122,150 +122,6 @@ Parameters - - - -
- files - -
- list - / elements=dictionary -
- - - - -
Logging to local files.
- - - - - - -
- archive - -
- dictionary -
- - - - -
Log file archive/rotation settings.
- - - - - - - -
- file_num - -
- integer -
- - - - -
Number of archived log files to keep.
- - - - - - - -
- size - -
- integer -
- - - - -
Maximum size of log file in kilobytes before rotation.
- - - - - - - -
- facilities - -
- list - / elements=dictionary -
- - - - -
List of syslog facilities to log to this file.
- - - - - - - -
- facility - -
- string -
- - - - -
Syslog facility name.
- - - - - - - -
- severity - -
- string -
- - - - -
Minimum severity level to log.
- - - - - - - -
- path - -
- string -
- - - - -
Path to the log file on the device.
- - - @@ -279,66 +135,12 @@ Parameters -
Global syslog parameters (maps to system syslog global).
- - - - - - -
- archive - -
- dictionary -
- - - - -
Global log archive/rotation settings.
+
Global syslog parameters (maps to system syslog local on device).
- - -
- file_num - -
- integer -
- - - - -
Number of archived log files to keep.
- - - - - - - -
- size - -
- integer -
- - - - -
Maximum size of log file in kilobytes before rotation.
- - - - - -
facilities @@ -351,7 +153,7 @@ Parameters -
List of syslog facilities for global logging.
+
List of syslog facilities for local logging.
@@ -444,7 +246,7 @@ Parameters -
Logging to remote syslog hosts.
+
Logging to remote syslog hosts (maps to system syslog remote).
@@ -663,21 +465,6 @@ Parameters - - -
- running_config - -
- string -
- - - - -
Used only with state parsed.
- -
@@ -694,8 +481,6 @@ Parameters
  • overridden
  • deleted
  • gathered
    • -
  • rendered
    • -
  • parsed
    • @@ -720,30 +505,18 @@ Examples facilities: - facility: local7 severity: err - files: - - path: logFile - archive: - file_num: 2 - facilities: - - facility: local6 - severity: emerg hosts: - hostname: 172.16.0.1 - port: 223 + port: 514 facilities: - facility: local7 severity: all - - facility: all - protocol: udp users: - username: vyos facilities: - facility: local7 severity: debug global_params: - archive: - file_num: 2 - size: 111 facilities: - facility: cron severity: debug @@ -842,7 +615,7 @@ Common return values are documented `here dictionary - when changes are applied + when changed
    Result of save_config after applying changes.

    diff --git a/docs/vyos.rest.vyos_nat_module.rst b/docs/vyos.rest.vyos_nat_module.rst new file mode 100644 index 0000000..1200416 --- /dev/null +++ b/docs/vyos.rest.vyos_nat_module.rst @@ -0,0 +1,208 @@ +.. _vyos.rest.vyos_nat_module: + + +****************** +vyos.rest.vyos_nat +****************** + +**Manage NAT configuration on VyOS devices using REST API** + + +Version added: 1.0.0 + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Manages NAT configuration on VyOS devices via the REST API. +- Supports source, destination, static, CGNAT, NAT64, and NAT66. +- Uses REST API (``connection=httpapi``) instead of CLI. +- Targets VyOS 1.5+. + + + + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + +
    ParameterChoices/DefaultsComments
    +
    + config + +
    + dictionary +
    +     		+ +
    NAT configuration.
    +
    +
    + state + +
    + string +
    +     		+
      Choices: +
    • merged ←
      • +
    • replaced
      • +
    • overridden
      • +
    • deleted
      • +
    • gathered
      • +
    +     		+
    The desired state of the NAT configuration.
    +
    +
    + + + + +Examples +-------- + +.. code-block:: yaml + + - name: Merge source NAT rule + vyos.rest.vyos_nat: + config: + nat: + source: + rule: + - id: 100 + outbound_interface: + name: eth0 + translation: + address: masquerade + state: merged + + - name: Delete all NAT + vyos.rest.vyos_nat: + state: deleted + + - name: Gather NAT configuration + vyos.rest.vyos_nat: + state: gathered + + + +Return Values +------------- +Common return values are documented `here `_, the following are the fields unique to this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    KeyReturnedDescription
    +
    + after + +
    + dictionary +
    +     		when changed +
    NAT configuration after this module ran.
    +
    +
    +
    + before + +
    + dictionary +
    +     		always +
    NAT configuration before this module ran.
    +
    +
    +
    + commands + +
    + list +
    +     		always +
    List of API commands sent to the device.
    +
    +
    +
    + gathered + +
    + dictionary +
    +     		when state is gathered +
    Current NAT configuration as structured data.
    +
    +
    +
    + saved + +
    + boolean +
    +     		when changed +
    Whether the config was saved after changes.
    +
    +
    +

    + + +Status +------ + + +Authors +~~~~~~~ + +- Evgeny Molotkov (@omnom62) diff --git a/docs/vyos.rest.vyos_ntp_global_module.rst b/docs/vyos.rest.vyos_ntp_global_module.rst index 9643d5a..ba209a8 100644 --- a/docs/vyos.rest.vyos_ntp_global_module.rst +++ b/docs/vyos.rest.vyos_ntp_global_module.rst @@ -152,22 +152,6 @@ Parameters - - -
    - running_config - -
    - string -
    - - - - -
    Used only with state parsed.
    -
    Provide the output of show configuration commands | grep ntp.
    - -
    @@ -184,8 +168,6 @@ Parameters
  • overridden
  • deleted
  • gathered
    • -
  • rendered
    • -
  • parsed
    • @@ -311,36 +293,6 @@ Common return values are documented `here - - -
    - parsed - -
    - dictionary -
    - - when state is parsed - -
    Structured data parsed from running_config.
    -
    - - - - -
    - rendered - -
    - list -
    - - when state is rendered - -
    CLI commands generated for the provided config (offline).
    -
    - -
    @@ -350,7 +302,7 @@ Common return values are documented `here boolean - when changes are applied + when changed
    Whether the config was saved after changes.

    diff --git a/docs/vyos.rest.vyos_route_maps_module.rst b/docs/vyos.rest.vyos_route_maps_module.rst index 4fc0801..675b0af 100644 --- a/docs/vyos.rest.vyos_route_maps_module.rst +++ b/docs/vyos.rest.vyos_route_maps_module.rst @@ -19,6 +19,7 @@ Synopsis -------- - Manages route maps on VyOS via the REST API. - Uses REST API (``connection=httpapi``) instead of CLI. +- Covers the commonly used match/set fields (as documented below). VyOS's route-map schema is considerably larger than this (EVPN attributes, extended communities, RPKI matching, on-match goto/next, route-source, source-peer, source-vrf, and more) -- those are not modeled by this module and are a real, documented limitation, not an oversight. @@ -30,49 +31,705 @@ Parameters - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - + + + + + + + + + + + + + + + + + + + + - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - - + - + @@ -421,6 +421,7 @@ Parameters
    string + / required
    @@ -1014,7 +1015,7 @@ Parameters @@ -1026,6 +1027,7 @@ Parameters
    string + / required
    @@ -1220,7 +1222,7 @@ Common return values are documented `here boolean - + - + - +
    ParameterParameter Choices/Defaults Comments
    +
    + config + +
    + list + / elements=dictionary +
    +     		+ +
    List of route-map configurations.
    +
    +
    + entries + +
    + list + / elements=dictionary +
    +     		+ +
    Route map rules.
    +
    +
    + action + +
    + string +
    +     		+
      Choices: +
    • permit
      • +
    • deny
      • +
    +     		+
    Permit or deny.
    +
    +
    + call + +
    + string +
    +     		+ +
    Call another route map.
    +
    +
    + continue_sequence + +
    + integer +
    +     		+ +
    Continue at a different sequence number.
    +
    +
    + description + +
    + string +
    +     		+ +
    Rule description.
    +
    +
    + match + +
    + dictionary +
    +     		+ +
    Match conditions.
    +
    +
    + interface + +
    + string +
    +     		+ +
    Interface to match.
    +
    +
    + ip + +
    + dictionary +
    +     		+ +
    IPv4 next-hop match parameters.
    +
    +
    + nexthop_address + +
    + string +
    +     		+ +
    IPv4 next-hop address to match.
    +
    +
    + nexthop_prefix_list + +
    + string +
    +     		+ +
    IPv4 next-hop prefix-list to match.
    +
    +
    + ipv6 + +
    + dictionary +
    +     		+ +
    IPv6 next-hop match parameters.
    +
    +
    + nexthop_address + +
    + string +
    +     		+ +
    IPv6 next-hop address to match.
    +
    +
    + metric + +
    + integer +
    +     		+ +
    Metric of route to match.
    +
    +
    + origin + +
    + string +
    +     		+
      Choices: +
    • egp
      • +
    • igp
      • +
    • incomplete
      • +
    +     		+
    BGP origin code to match.
    +
    +
    + peer + +
    + string +
    +     		+ +
    Peer address to match.
    +
    +
    + prefix_list + +
    + string +
    +     		+ +
    IPv4 prefix-list to match.
    +
    +
    + prefix_list6 + +
    + string +
    +     		+ +
    IPv6 prefix-list to match.
    +
    +
    + protocol + +
    + string +
    +     		+
      Choices: +
    • babel
      • +
    • bgp
      • +
    • connected
      • +
    • isis
      • +
    • kernel
      • +
    • ospf
      • +
    • ospfv3
      • +
    • rip
      • +
    • ripng
      • +
    • static
      • +
    • table
      • +
    • vnc
      • +
    +     		+
    Match protocol via which the route was learnt.
    +
    +
    + sequence + +
    + integer + / required +
    +     		+ +
    Rule sequence number (1-65535).
    +
    - config + set + +
    + dictionary +
    +     		+ +
    Route parameters to set.
    +
    +
    + aggregator + +
    + dictionary +
    +     		+ +
    BGP aggregator attribute.
    +
    +
    + as_ + +
    + integer +
    +     		+ +
    AS number of an aggregation.
    +

    aliases: as
    +
    +
    + ip + +
    + string +
    +     		+ +
    IP address of an aggregation.
    +
    +
    + as_path_exclude + +
    + string +
    +     		+ +
    AS number(s) to remove from the as-path attribute.
    +
    +
    + as_path_prepend + +
    + string +
    +     		+ +
    AS number(s) to prepend to the as-path attribute.
    +
    +
    + as_path_prepend_last_as + +
    + integer +
    +     		+ +
    Number of times to prepend the last AS number in the as-path.
    +
    +
    + atomic_aggregate + +
    + boolean +
    +     		+
      Choices: +
    • no
      • +
    • yes
      • +
    +     		+
    Set the BGP atomic aggregate attribute.
    +
    +
    + community + +
    + dictionary +
    +     		+ +
    BGP community attribute.
    +
    +
    + add + +
    + list + / elements=string +
    +     		+ +
    Communities to add to a prefix.
    +
    +
    + delete + +
    + string +
    +     		+ +
    Remove communities defined in a list from a prefix.
    +
    +
    + none + +
    + boolean +
    +     		+
      Choices: +
    • no
      • +
    • yes
      • +
    +     		+
    Completely remove the communities attribute from a prefix.
    +
    +
    + replace + +
    + list + / elements=string +
    +     		+ +
    Communities to set for a prefix.
    +
    +
    + distance
    - list - / elements=dictionary + integer
    		-
    List of route-map configurations.
    +
    Locally significant administrative distance.
    - entries + ip_next_hop
    - list - / elements=dictionary + string
    		-
    Route map rules.
    +
    IPv4 next-hop address to set.
    +
    +
    + ipv6_next_hop + +
    + dictionary +
    +     		+ +
    IPv6 next-hop to set.
    - action + global
    string @@ -81,15 +738,17 @@ Parameters
    		-
    Permit or deny.
    +
    Nexthop IPv6 global address.
    - call + local
    string @@ -98,49 +757,63 @@ Parameters
    		-
    Call another route map.
    +
    Nexthop IPv6 local address.
    - continue_sequence + peer_address
    - integer + boolean
    		+
      Choices: +
    • no
      • +
    • yes
      • +
    		-
    Continue at a different sequence number.
    +
    Use the peer address (BGP only) as the nexthop.
    - description + prefer_global
    - string + boolean
    		+
      Choices: +
    • no
      • +
    • yes
      • +
    		-
    Rule description.
    +
    Prefer the global address as the nexthop.
    +
    - match + large_community
    dictionary @@ -149,48 +822,264 @@ Parameters
    		-
    Match conditions (passed through to VyOS API).
    +
    BGP large community attribute.
    +
    +
    + add + +
    + list + / elements=string +
    +     		+ +
    Large communities to add to a prefix.
    - sequence + delete
    - integer - / required + string
    		-
    Rule sequence number (1-65535).
    +
    Remove large communities defined in a list from a prefix.
    - set + none
    - dictionary + boolean +
    +     		+
      Choices: +
    • no
      • +
    • yes
      • +
    +     		+
    Completely remove the large-community attribute from a prefix.
    +
    +
    + replace + +
    + list + / elements=string
    		-
    Route parameters to set (passed through to VyOS API).
    +
    Large communities to set for a prefix.
    +
    + local_preference + +
    + integer +
    +     		+ +
    BGP local preference.
    +
    +
    + metric + +
    + integer +
    +     		+ +
    Metric of route.
    +
    +
    + metric_type + +
    + string +
    +     		+ +
    Metric type.
    +
    +
    + origin + +
    + string +
    +     		+
      Choices: +
    • egp
      • +
    • igp
      • +
    • incomplete
      • +
    +     		+
    BGP origin code to set.
    +
    +
    + originator_id + +
    + string +
    +     		+ +
    BGP originator ID.
    +
    +
    + src + +
    + string +
    +     		+ +
    Source address for route.
    +
    +
    + table + +
    + integer +
    +     		+ +
    Non-main kernel routing table.
    +
    +
    + tag + +
    + integer +
    +     		+ +
    Route tag value.
    +
    +
    + weight + +
    + integer +
    +     		+ +
    BGP weight.
    +
    route_map @@ -207,7 +1096,7 @@ Parameters
    +
    state @@ -243,7 +1132,6 @@ Notes .. note:: - Requires ``ansible_connection=httpapi`` with the VyOS httpapi plugin. - ``ansible_network_os`` must be set to ``vyos.rest.vyos``. - - Input validation is delegated to the VyOS API. @@ -262,10 +1150,10 @@ Examples match: peer: 192.0.2.32 set: - metric: "5" + metric: 5 as_path_exclude: "111" aggregator: - as: 100 + as_: 100 state: merged - name: Delete all route maps @@ -365,7 +1253,7 @@ Common return values are documented `here dictionary     		when changes are appliedalways
    Raw API response.

    @@ -380,7 +1268,7 @@ Common return values are documented `here boolean     		when changes are appliedwhen changed
    Whether the config was saved after changes.

    diff --git a/docs/vyos.rest.vyos_snmp_server_module.rst b/docs/vyos.rest.vyos_snmp_server_module.rst index 29a64c6..d183f88 100644 --- a/docs/vyos.rest.vyos_snmp_server_module.rst +++ b/docs/vyos.rest.vyos_snmp_server_module.rst @@ -257,7 +257,7 @@ Parameters     		-
    Register a subtree for SMUX-based processing.
    +
    Register a subtree for SMUX-based processing. The device supports multiple values here; this module manages a single value only.
    @@ -907,7 +908,7 @@ Parameters -
    SNMPv3 view configuration.
    +
    SNMPv3 view configuration. The device supports multiple OIDs (each with its own exclude/mask) per view; this module manages a single OID entry per view only.
    -
    SNMP trap target.
    +
    SNMP (v2) trap target. The device supports multiple trap targets; this module manages a single one only.
    @@ -1192,7 +1194,7 @@ Common return values are documented `here always -
    List of API command dicts sent to the device.
    +
    List of API command tuples sent to the device.
    when changes are appliedwhen changed
    Whether the config was saved after changes.

    diff --git a/docs/vyos.rest.vyos_system_module.rst b/docs/vyos.rest.vyos_system_module.rst new file mode 100644 index 0000000..0aa5f4f --- /dev/null +++ b/docs/vyos.rest.vyos_system_module.rst @@ -0,0 +1,254 @@ +.. _vyos.rest.vyos_system_module: + + +********************* +vyos.rest.vyos_system +********************* + +**Manage system settings on VyOS devices using REST API** + + +Version added: 1.0.0 + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Manages basic system settings on VyOS devices via the REST API. +- Uses REST API (``connection=httpapi``) instead of CLI. + + + + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    ParameterChoices/DefaultsComments
    +
    + domain_name + +
    + string +
    +     		+ +
    Device domain name.
    +
    +
    + domain_search + +
    + list + / elements=string +
    +     		+ +
    List of domain search suffixes.
    +
    +
    + host_name + +
    + string +
    +     		+ +
    Device hostname.
    +
    +
    + name_server + +
    + list + / elements=string +
    +     		+ +
    List of DNS name servers.
    +

    aliases: name_servers
    +
    +
    + state + +
    + string +
    +     		+
      Choices: +
    • present ←
      • +
    • absent
      • +
    +     		+
    present applies the configuration.
    +
    absent removes the configuration.
    +
    +
    + + +Notes +----- + +.. note:: + - Requires ``ansible_connection=httpapi`` with the VyOS httpapi plugin. + - ``ansible_network_os`` must be set to ``vyos.rest.vyos``. + + + +Examples +-------- + +.. code-block:: yaml + + - name: Configure hostname and domain + vyos.rest.vyos_system: + host_name: router1 + domain_name: example.com + name_server: + - 8.8.8.8 + - 8.8.4.4 + state: present + + - name: Remove domain name and name servers + vyos.rest.vyos_system: + domain_name: example.com + name_server: + - 8.8.8.8 + state: absent + + + +Return Values +------------- +Common return values are documented `here `_, the following are the fields unique to this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    KeyReturnedDescription
    +
    + after + +
    + dictionary +
    +     		when changed +
    Module-owned system configuration after this module ran.
    +
    +
    +
    + before + +
    + dictionary +
    +     		always +
    Module-owned system configuration before this module ran.
    +
    +
    +
    + commands + +
    + list +
    +     		always +
    List of API command tuples sent to the device.
    +
    +
    +
    + response + +
    + dictionary +
    +     		always +
    Raw API response.
    +
    +
    +
    + saved + +
    + boolean +
    +     		when changed +
    Whether the config was saved after changes.
    +
    +
    +

    + + +Status +------ + + +Authors +~~~~~~~ + +- VyOS Community (@vyos) diff --git a/docs/vyos.rest.vyos_user_module.rst b/docs/vyos.rest.vyos_user_module.rst index 1ad08f4..8cf2cda 100644 --- a/docs/vyos.rest.vyos_user_module.rst +++ b/docs/vyos.rest.vyos_user_module.rst @@ -358,7 +358,7 @@ Common return values are documented `here dictionary     		when changes are appliedalways
    Raw API response.

    @@ -373,7 +373,7 @@ Common return values are documented `here boolean     		when changes are appliedwhen changed
    Whether the config was saved after changes.

    diff --git a/docs/vyos.rest.vyos_vlan_module.rst b/docs/vyos.rest.vyos_vlan_module.rst new file mode 100644 index 0000000..06ca1ab --- /dev/null +++ b/docs/vyos.rest.vyos_vlan_module.rst @@ -0,0 +1,303 @@ +.. _vyos.rest.vyos_vlan_module: + + +******************* +vyos.rest.vyos_vlan +******************* + +**Manage VLAN (vif) configuration on VyOS devices using REST API** + + +Version added: 1.0.0 + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Manages VLAN sub-interface configuration on VyOS Ethernet interfaces via the REST API. +- Uses REST API (``connection=httpapi``) instead of CLI. + + + + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    ParameterChoices/DefaultsComments
    +
    + config + +
    + list + / elements=dictionary +
    +     		+ +
    List of VLAN configurations.
    +
    +
    + address + +
    + string +
    +     		+ +
    IP address for the VLAN interface.
    +
    +
    + description + +
    + string +
    +     		+ +
    VLAN description.
    +
    +
    + interfaces + +
    + list + / elements=string + / required +
    +     		+ +
    List of Ethernet interfaces to configure this VLAN on.
    +
    +
    + vlan_id + +
    + integer + / required +
    +     		+ +
    VLAN ID (0-4094).
    +
    +
    + state + +
    + string +
    +     		+
      Choices: +
    • present ←
      • +
    • absent
      • +
    • gathered
      • +
    +     		+
    present creates or updates VLANs.
    +
    absent removes VLANs.
    +
    gathered returns current VLAN configuration.
    +
    +
    + + +Notes +----- + +.. note:: + - Requires ``ansible_connection=httpapi`` with the VyOS httpapi plugin. + - ``ansible_network_os`` must be set to ``vyos.rest.vyos``. + + + +Examples +-------- + +.. code-block:: yaml + + - name: Configure VLANs + vyos.rest.vyos_vlan: + config: + - vlan_id: 10 + description: VLAN10 + address: 192.168.10.1/24 + interfaces: + - eth1 + - vlan_id: 20 + description: VLAN20 + interfaces: + - eth1 + - eth2 + state: present + + - name: Remove a VLAN + vyos.rest.vyos_vlan: + config: + - vlan_id: 10 + interfaces: + - eth1 + state: absent + + - name: Gather VLAN configuration + vyos.rest.vyos_vlan: + state: gathered + + + +Return Values +------------- +Common return values are documented `here `_, the following are the fields unique to this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    KeyReturnedDescription
    +
    + after + +
    + list +
    +     		when changed +
    VLAN configuration after this module ran.
    +
    +
    +
    + before + +
    + list +
    +     		always +
    VLAN configuration before this module ran.
    +
    +
    +
    + commands + +
    + list +
    +     		always +
    List of API command tuples sent to the device.
    +
    +
    +
    + gathered + +
    + list +
    +     		when state is gathered +
    Current VLAN configuration as structured data.
    +
    +
    +
    + response + +
    + dictionary +
    +     		always +
    Raw API response.
    +
    +
    +
    + saved + +
    + boolean +
    +     		when changed +
    Whether the config was saved after changes.
    +
    +
    +

    + + +Status +------ + + +Authors +~~~~~~~ + +- VyOS Community (@vyos) -- cgit v1.2.3