From 7a6b5e4f3a7a021cfa75faa7bf833741dfc09cff Mon Sep 17 00:00:00 2001 From: omnom62 <75066712+omnom62@users.noreply.github.com> Date: Sat, 22 Aug 2026 01:36:21 +1000 Subject: T8989: wave3 user, bgp_global, bgp_address_family, facts, firewall_global * T8989: vyos_user module * T8989: Wave 3 vyos_user module with integration and unit tests * T8989: Wave 3 vyos_bgp_global module with integration and unit tests * T8989: Wave 3 vyos_bgp_address_family module with integration and unit tests * T8989: Add overridden integration tests for vyos_bgp_global and vyos_bgp_address_family * T8989: vyos_facts * T8989: Add vyos_facts integration and unit tests with fixtures * T8989: vyos_firewall_global module * T8989: vyos_firewall_global module with integration and unit tests * T8989: vyos_firewall_rules module * T8989: vyos_firewall_rules module with integration and unit tests * T8989: vyos_firewall_interfaces module * T8989: vyos_firewall_interfaces module * T8989: vyos_firewall_interfaces UAT & SIT * T8989: vyos_firewall_interfaces UAT & SIT --- docs/vyos.rest.vyos_bgp_address_family_module.rst | 1024 ++++++++++++++++++++ docs/vyos.rest.vyos_bgp_global_module.rst | 876 +++++++++++++++++ docs/vyos.rest.vyos_facts_module.rst | 296 ++++++ docs/vyos.rest.vyos_firewall_global_module.rst | 642 ++++++++++++ docs/vyos.rest.vyos_firewall_interfaces_module.rst | 632 ++++++++++++ docs/vyos.rest.vyos_firewall_rules_module.rst | 725 ++++++++++++++ docs/vyos.rest.vyos_user_module.rst | 393 ++++++++ 7 files changed, 4588 insertions(+) create mode 100644 docs/vyos.rest.vyos_bgp_address_family_module.rst create mode 100644 docs/vyos.rest.vyos_bgp_global_module.rst create mode 100644 docs/vyos.rest.vyos_facts_module.rst create mode 100644 docs/vyos.rest.vyos_firewall_global_module.rst create mode 100644 docs/vyos.rest.vyos_firewall_interfaces_module.rst create mode 100644 docs/vyos.rest.vyos_firewall_rules_module.rst create mode 100644 docs/vyos.rest.vyos_user_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 new file mode 100644 index 0000000..d9d45d7 --- /dev/null +++ b/docs/vyos.rest.vyos_bgp_address_family_module.rst @@ -0,0 +1,1024 @@ +.. _vyos.rest.vyos_bgp_address_family_module: + + +********************************* +vyos.rest.vyos_bgp_address_family +********************************* + +**Manage BGP address-family configuration on VyOS devices using REST API** + + +Version added: 1.0.0 + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Manages BGP address-family configuration on VyOS devices via the REST API. +- Covers global address-family (networks, redistribution) and per-neighbor address-family settings. +- BGP must be configured first using :ref:`vyos.rest.vyos_bgp_global `. +- Uses REST API (``connection=httpapi``) instead of CLI. + + + + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterChoices/DefaultsComments
+
+ config + +
+ dictionary +
+ 		+ +
BGP address-family configuration.
+
+
+ address_family + +
+ list + / elements=dictionary +
+ 		+ +
Global BGP address-family settings.
+
+
+ afi + +
+ string + / required +
+ 		+
    Choices: +
  • ipv4
    • +
  • ipv6
    • +
+ 		+
Address family identifier.
+
+
+ networks + +
+ list + / elements=dictionary +
+ 		+ +
Networks to advertise.
+
+
+ backdoor + +
+ boolean +
+ 		+
    Choices: +
  • no
    • +
  • yes
    • +
+ 		+
Network backdoor.
+
+
+ prefix + +
+ string + / required +
+ 		+ +
Network prefix.
+
+
+ route_map + +
+ string +
+ 		+ +
Route map to apply.
+
+
+ redistribute + +
+ list + / elements=dictionary +
+ 		+ +
Redistribute routes from other protocols.
+
+
+ metric + +
+ integer +
+ 		+ +
Metric for redistributed routes.
+
+
+ protocol + +
+ string + / required +
+ 		+
    Choices: +
  • connected
    • +
  • kernel
    • +
  • ospf
    • +
  • ospfv3
    • +
  • rip
    • +
  • ripng
    • +
  • static
    • +
+ 		+
Protocol to redistribute.
+
+
+ route_map + +
+ string +
+ 		+ +
Route map to apply.
+
+
+ as_number + +
+ integer + / required +
+ 		+ +
BGP autonomous system number (required for context).
+
+
+ neighbors + +
+ list + / elements=dictionary +
+ 		+ +
Per-neighbor address-family settings.
+
+
+ address_family + +
+ list + / elements=dictionary +
+ 		+ +
Address-family settings for this neighbor.
+
+
+ afi + +
+ string + / required +
+ 		+
    Choices: +
  • ipv4
    • +
  • ipv6
    • +
+ 		+
Address family identifier.
+
+
+ allowas_in + +
+ integer +
+ 		+ +
Accept as-path with my AS present.
+
+
+ attribute_unchanged + +
+ dictionary +
+ 		+ +
BGP attributes to leave unchanged.
+
+
+ as_path + +
+ boolean +
+ 		+
    Choices: +
  • no
    • +
  • yes
    • +
+ 		+
Leave as-path unchanged.
+
+
+ med + +
+ boolean +
+ 		+
    Choices: +
  • no
    • +
  • yes
    • +
+ 		+
Leave MED unchanged.
+
+
+ next_hop + +
+ boolean +
+ 		+
    Choices: +
  • no
    • +
  • yes
    • +
+ 		+
Leave next-hop unchanged.
+
+
+ capability + +
+ dictionary +
+ 		+ +
Advertise capability to the peer.
+
+
+ orf + +
+ string +
+ 		+
    Choices: +
  • receive
    • +
  • send
    • +
+ 		+
ORF capability.
+
+
+ default_originate + +
+ boolean +
+ 		+
    Choices: +
  • no
    • +
  • yes
    • +
+ 		+
Send default route to neighbor.
+
+
+ distribute_list + +
+ dictionary +
+ 		+ +
Filter updates using access-list.
+
+
+ export + +
+ integer +
+ 		+ +
Access-list to filter outbound updates.
+
+
+ import + +
+ integer +
+ 		+ +
Access-list to filter inbound updates.
+
+
+ maximum_prefix + +
+ integer +
+ 		+ +
Maximum number of prefixes to accept.
+
+
+ nexthop_self + +
+ boolean +
+ 		+
    Choices: +
  • no
    • +
  • yes
    • +
+ 		+
Set next-hop to self.
+
+
+ prefix_list + +
+ dictionary +
+ 		+ +
Filter updates using prefix-list.
+
+
+ export + +
+ string +
+ 		+ +
Prefix-list to filter outbound updates.
+
+
+ import + +
+ string +
+ 		+ +
Prefix-list to filter inbound updates.
+
+
+ route_map + +
+ dictionary +
+ 		+ +
Route map to apply.
+
+
+ export + +
+ string +
+ 		+ +
Route map for outbound updates.
+
+
+ import + +
+ string +
+ 		+ +
Route map for inbound updates.
+
+
+ route_reflector_client + +
+ boolean +
+ 		+
    Choices: +
  • no
    • +
  • yes
    • +
+ 		+
Configure as route reflector client.
+
+
+ route_server_client + +
+ boolean +
+ 		+
    Choices: +
  • no
    • +
  • yes
    • +
+ 		+
Configure as route server client.
+
+
+ soft_reconfiguration + +
+ boolean +
+ 		+
    Choices: +
  • no
    • +
  • yes
    • +
+ 		+
Enable soft reconfiguration inbound.
+
+
+ unsuppress_map + +
+ string +
+ 		+ +
Route-map to selectively unsuppress suppressed routes.
+
+
+ weight + +
+ integer +
+ 		+ +
Default weight for routes from this neighbor.
+
+
+ neighbor_address + +
+ string + / required +
+ 		+ +
Neighbor IP address.
+
+
+ state + +
+ string +
+ 		+
    Choices: +
  • merged ←
    • +
  • replaced
    • +
  • deleted
    • +
  • gathered
    • +
+ 		+
Desired state of the BGP address-family configuration.
+
merged adds or updates without removing existing config.
+
replaced replaces the entire BGP address-family configuration.
+
deleted removes BGP address-family configuration.
+
gathered returns current configuration as structured data.
+
+
+ + +Notes +----- + +.. note:: + - Requires ``ansible_connection=httpapi`` with the VyOS httpapi plugin. + - ``ansible_network_os`` must be set to ``vyos.rest.vyos``. + - BGP must be configured first using :ref:`vyos.rest.vyos_bgp_global `. + + + +Examples +-------- + +.. code-block:: yaml + + - name: Merge BGP address-family configuration + vyos.rest.vyos_bgp_address_family: + config: + as_number: 65000 + address_family: + - afi: ipv4 + networks: + - prefix: 192.0.2.0/24 + redistribute: + - protocol: connected + metric: 10 + neighbors: + - neighbor_address: 192.0.2.1 + address_family: + - afi: ipv4 + soft_reconfiguration: true + nexthop_self: true + - afi: ipv6 + soft_reconfiguration: true + state: merged + + - name: Delete all BGP address-family configuration + vyos.rest.vyos_bgp_address_family: + config: + as_number: 65000 + state: deleted + + - name: Gather BGP address-family configuration + vyos.rest.vyos_bgp_address_family: + 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 +
BGP address-family configuration after this module ran.
+
+
+
+ before + +
+ dictionary +
+ 		always +
BGP address-family configuration before this module ran.
+
+
+
+ commands + +
+ list +
+ 		always +
List of API command tuples sent to the device.
+
+
+
+ gathered + +
+ dictionary +
+ 		when state is gathered +
Current BGP address-family configuration as structured data.
+
+
+
+ response + +
+ dictionary +
+ 		when changes are applied +
Raw API response.
+
+
+
+ saved + +
+ boolean +
+ 		when changes are applied +
Whether the config was saved after changes.
+
+
+

+ + +Status +------ + + +Authors +~~~~~~~ + +- VyOS Community (@vyos) diff --git a/docs/vyos.rest.vyos_bgp_global_module.rst b/docs/vyos.rest.vyos_bgp_global_module.rst new file mode 100644 index 0000000..01bcefe --- /dev/null +++ b/docs/vyos.rest.vyos_bgp_global_module.rst @@ -0,0 +1,876 @@ +.. _vyos.rest.vyos_bgp_global_module: + + +************************* +vyos.rest.vyos_bgp_global +************************* + +**Manage BGP global configuration on VyOS devices using REST API** + + +Version added: 1.0.0 + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Manages BGP global configuration on VyOS devices via the REST API. +- Covers system AS, parameters, neighbors, and peer-groups. +- For per-neighbor address-family configuration use :ref:`vyos.rest.vyos_bgp_address_family `. +- Uses REST API (``connection=httpapi``) instead of CLI. + + + + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterChoices/DefaultsComments
+
+ config + +
+ dictionary +
+ 		+ +
BGP global configuration.
+
+
+ as_number + +
+ integer + / required +
+ 		+ +
BGP autonomous system number.
+
+
+ neighbors + +
+ list + / elements=dictionary +
+ 		+ +
BGP neighbors.
+
+
+ description + +
+ string +
+ 		+ +
Neighbor description.
+
+
+ disable_connected_check + +
+ boolean +
+ 		+
    Choices: +
  • no
    • +
  • yes
    • +
+ 		+
Disable connected route check.
+
+
+ ebgp_multihop + +
+ integer +
+ 		+ +
EBGP multihop TTL.
+
+
+ local_as + +
+ integer +
+ 		+ +
Local AS number.
+
+
+ neighbor_address + +
+ string + / required +
+ 		+ +
Neighbor IP address.
+
+
+ password + +
+ string +
+ 		+ +
MD5 password for neighbor.
+
+
+ peer_group + +
+ string +
+ 		+ +
Peer group name.
+
+
+ remote_as + +
+ integer +
+ 		+ +
Neighbor AS number.
+
+
+ shutdown + +
+ boolean +
+ 		+
    Choices: +
  • no
    • +
  • yes
    • +
+ 		+
Shutdown neighbor.
+
+
+ timers + +
+ dictionary +
+ 		+ +
Neighbor timers.
+
+
+ holdtime + +
+ integer +
+ 		+ +
Hold time in seconds.
+
+
+ keepalive + +
+ integer +
+ 		+ +
Keepalive interval in seconds.
+
+
+ update_source + +
+ string +
+ 		+ +
Source interface/IP for updates.
+
+
+ parameters + +
+ dictionary +
+ 		+ +
BGP global parameters.
+
+
+ bestpath + +
+ dictionary +
+ 		+ +
BGP bestpath parameters.
+
+
+ as_path + +
+ string +
+ 		+
    Choices: +
  • confed
    • +
  • ignore
    • +
  • multipath-relax
    • +
+ 		+
AS-path attribute comparison.
+
+
+ confederation + +
+ dictionary +
+ 		+ +
AS confederation parameters.
+
+
+ identifier + +
+ integer +
+ 		+ +
Confederation AS identifier.
+
+
+ peers + +
+ list + / elements=integer +
+ 		+ +
Peer ASs in confederation.
+
+
+ graceful_restart + +
+ boolean +
+ 		+
    Choices: +
  • no
    • +
  • yes
    • +
+ 		+
Enable graceful restart.
+
+
+ log_neighbor_changes + +
+ boolean +
+ 		+
    Choices: +
  • no
    • +
  • yes
    • +
+ 		+
Log neighbor up/down changes.
+
+
+ no_ipv4_unicast + +
+ boolean +
+ 		+
    Choices: +
  • no
    • +
  • yes
    • +
+ 		+
Disable IPv4 unicast default.
+
+
+ router_id + +
+ string +
+ 		+ +
BGP router ID.
+
+
+ peer_groups + +
+ list + / elements=dictionary +
+ 		+ +
BGP peer groups.
+
+
+ description + +
+ string +
+ 		+ +
Peer group description.
+
+
+ ebgp_multihop + +
+ integer +
+ 		+ +
EBGP multihop TTL.
+
+
+ password + +
+ string +
+ 		+ +
MD5 password.
+
+
+ peer_group + +
+ string + / required +
+ 		+ +
Peer group name.
+
+
+ remote_as + +
+ integer +
+ 		+ +
Peer group AS number.
+
+
+ timers + +
+ dictionary +
+ 		+ +
Peer group timers.
+
+
+ holdtime + +
+ integer +
+ 		+ +
Hold time in seconds.
+
+
+ keepalive + +
+ integer +
+ 		+ +
Keepalive interval in seconds.
+
+
+ update_source + +
+ string +
+ 		+ +
Source interface/IP for updates.
+
+
+ state + +
+ string +
+ 		+
    Choices: +
  • merged ←
    • +
  • replaced
    • +
  • deleted
    • +
  • gathered
    • +
+ 		+
Desired state of the BGP global configuration.
+
merged adds or updates without removing existing config.
+
replaced replaces the entire BGP configuration.
+
deleted removes BGP configuration.
+
gathered returns current configuration as structured data.
+
+
+ + +Notes +----- + +.. note:: + - Requires ``ansible_connection=httpapi`` with the VyOS httpapi plugin. + - ``ansible_network_os`` must be set to ``vyos.rest.vyos``. + - BGP system-as must be defined before any other BGP configuration. + + + +Examples +-------- + +.. code-block:: yaml + + - name: Merge BGP global configuration + vyos.rest.vyos_bgp_global: + config: + as_number: 65000 + parameters: + router_id: 192.0.1.1 + neighbors: + - neighbor_address: 192.0.2.1 + remote_as: 65001 + description: peer1 + timers: + holdtime: 30 + keepalive: 10 + peer_groups: + - peer_group: PG1 + remote_as: 65002 + state: merged + + - name: Delete BGP configuration + vyos.rest.vyos_bgp_global: + state: deleted + + - name: Gather BGP global configuration + vyos.rest.vyos_bgp_global: + 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 +
BGP configuration after this module ran.
+
+
+
+ before + +
+ dictionary +
+ 		always +
BGP configuration before this module ran.
+
+
+
+ commands + +
+ list +
+ 		always +
List of API command tuples sent to the device.
+
+
+
+ gathered + +
+ dictionary +
+ 		when state is gathered +
Current BGP configuration as structured data.
+
+
+
+ response + +
+ dictionary +
+ 		when changes are applied +
Raw API response.
+
+
+
+ saved + +
+ boolean +
+ 		when changes are applied +
Whether the config was saved after changes.
+
+
+

+ + +Status +------ + + +Authors +~~~~~~~ + +- VyOS Community (@vyos) diff --git a/docs/vyos.rest.vyos_facts_module.rst b/docs/vyos.rest.vyos_facts_module.rst new file mode 100644 index 0000000..d5c6a89 --- /dev/null +++ b/docs/vyos.rest.vyos_facts_module.rst @@ -0,0 +1,296 @@ +.. _vyos.rest.vyos_facts_module: + + +******************** +vyos.rest.vyos_facts +******************** + +**Get facts about VyOS devices using REST API** + + +Version added: 1.0.0 + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Collects facts from VyOS devices via the REST API. +- Returns structured facts under the ``ansible_facts`` key. +- Uses REST API (``connection=httpapi``) instead of CLI. + + + + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + +
ParameterChoices/DefaultsComments
+
+ gather_network_resources + +
+ list + / elements=string +
+ 		+ +
When supplied, this argument will restrict the facts collected to a given subset. Possible values include the resource module names.
+
This argument is not currently used.
+
+
+ gather_subset + +
+ list + / elements=string +
+ 		+ Default:
["default"]
+ 		+
When supplied, this argument will restrict the facts collected to a given subset. Possible values for this argument include all, default, config, interfaces, hostname, users, bgp, ospf, ntp, snmp and logging.
+
Specify a list of values to include a larger subset. Use the exclamation mark (!) before a value to exclude it. Values all and default cannot be combined with each other or with negation.
+
+
+ + +Notes +----- + +.. note:: + - Requires ``ansible_connection=httpapi`` with the VyOS httpapi plugin. + - ``ansible_network_os`` must be set to ``vyos.rest.vyos``. + - Only configuration facts are available via the REST API. Operational state (interface counters, BGP neighbors) is not supported. + + + +Examples +-------- + +.. code-block:: yaml + + - name: Gather all facts + vyos.rest.vyos_facts: + gather_subset: all + + - name: Gather default facts + vyos.rest.vyos_facts: + + - name: Gather interface and hostname facts only + vyos.rest.vyos_facts: + gather_subset: + - interfaces + - hostname + + - name: Gather all except config + vyos.rest.vyos_facts: + gather_subset: + - all + - '!config' + + +Returned Facts +-------------- +Facts returned by this module are added/updated in the ``hostvars`` host facts and can be referenced by name just like any other host fact. They do not need to be registered in order to use them. + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FactReturnedDescription
+
+ vyos_bgp + +
+ dictionary +
+ 		+
BGP configuration. +
+
+
+
+ vyos_config + +
+ dictionary +
+ 		+
Full device configuration as structured data. +
+
+
+
+ vyos_hostname + +
+ string +
+ 		+
Device hostname. +
+
+
+
+ vyos_interfaces + +
+ dictionary +
+ 		+
Interface configuration. +
+
+
+
+ vyos_logging + +
+ dictionary +
+ 		+
Logging configuration. +
+
+
+
+ vyos_ntp + +
+ dictionary +
+ 		+
NTP configuration. +
+
+
+
+ vyos_ospf + +
+ dictionary +
+ 		+
OSPFv2 configuration. +
+
+
+
+ vyos_ospfv3 + +
+ dictionary +
+ 		+
OSPFv3 configuration. +
+
+
+
+ vyos_snmp + +
+ dictionary +
+ 		+
SNMP configuration. +
+
+
+
+ vyos_users + +
+ list +
+ 		+
User accounts (without passwords). +
+
+
+

+ + + +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 new file mode 100644 index 0000000..d90c96a --- /dev/null +++ b/docs/vyos.rest.vyos_firewall_global_module.rst @@ -0,0 +1,642 @@ +.. _vyos.rest.vyos_firewall_global_module: + + +****************************** +vyos.rest.vyos_firewall_global +****************************** + +**Manage global firewall configuration on VyOS devices using REST API** + + +Version added: 1.0.0 + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Manages global firewall group configuration on VyOS devices via the REST API. +- Covers address-groups, network-groups, port-groups, interface-groups, and IPv6 network-groups. +- Uses REST API (``connection=httpapi``) instead of CLI. + + + + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterChoices/DefaultsComments
+
+ config + +
+ dictionary +
+ 		+ +
Global firewall configuration.
+
+
+ group + +
+ dictionary +
+ 		+ +
Firewall groups.
+
+
+ address_group + +
+ list + / elements=dictionary +
+ 		+ +
IPv4 address groups.
+
+
+ address + +
+ list + / elements=string +
+ 		+ +
IP addresses or ranges in the group.
+
+
+ description + +
+ string +
+ 		+ +
Group description.
+
+
+ name + +
+ string + / required +
+ 		+ +
Group name.
+
+
+ interface_group + +
+ list + / elements=dictionary +
+ 		+ +
Interface groups.
+
+
+ description + +
+ string +
+ 		+ +
Group description.
+
+
+ interface + +
+ list + / elements=string +
+ 		+ +
Interfaces in the group.
+
+
+ name + +
+ string + / required +
+ 		+ +
Group name.
+
+
+ ipv6_network_group + +
+ list + / elements=dictionary +
+ 		+ +
IPv6 network groups.
+
+
+ description + +
+ string +
+ 		+ +
Group description.
+
+
+ name + +
+ string + / required +
+ 		+ +
Group name.
+
+
+ network + +
+ list + / elements=string +
+ 		+ +
IPv6 network prefixes in the group.
+
+
+ network_group + +
+ list + / elements=dictionary +
+ 		+ +
IPv4 network groups.
+
+
+ description + +
+ string +
+ 		+ +
Group description.
+
+
+ name + +
+ string + / required +
+ 		+ +
Group name.
+
+
+ network + +
+ list + / elements=string +
+ 		+ +
Network prefixes in the group.
+
+
+ port_group + +
+ list + / elements=dictionary +
+ 		+ +
Port groups.
+
+
+ description + +
+ string +
+ 		+ +
Group description.
+
+
+ name + +
+ string + / required +
+ 		+ +
Group name.
+
+
+ port + +
+ list + / elements=string +
+ 		+ +
Ports or port ranges in the group.
+
+
+ state + +
+ string +
+ 		+
    Choices: +
  • merged ←
    • +
  • replaced
    • +
  • deleted
    • +
  • gathered
    • +
+ 		+
Desired state of the firewall global configuration.
+
merged adds or updates without removing existing config.
+
replaced replaces the entire firewall global configuration.
+
deleted removes firewall global configuration.
+
gathered returns current configuration as structured data.
+
+
+ + +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: Merge firewall global configuration + vyos.rest.vyos_firewall_global: + config: + group: + address_group: + - name: SERVERS + description: Web servers + address: + - 192.168.1.10 + - 192.168.1.11 + network_group: + - name: LAN + network: + - 192.168.0.0/16 + port_group: + - name: WEB-PORTS + port: + - "80" + - "443" + interface_group: + - name: LAN-IFACES + interface: + - eth1 + - eth2 + ipv6_network_group: + - name: IPV6-LAN + network: + - "2001:db8::/32" + state: merged + + - name: Delete all firewall global configuration + vyos.rest.vyos_firewall_global: + state: deleted + + - name: Gather firewall global configuration + vyos.rest.vyos_firewall_global: + 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 +
Firewall global configuration after this module ran.
+
+
+
+ before + +
+ dictionary +
+ 		always +
Firewall global configuration before this module ran.
+
+
+
+ commands + +
+ list +
+ 		always +
List of API command tuples sent to the device.
+
+
+
+ gathered + +
+ dictionary +
+ 		when state is gathered +
Current firewall global configuration as structured data.
+
+
+
+ response + +
+ dictionary +
+ 		when changes are applied +
Raw API response.
+
+
+
+ saved + +
+ boolean +
+ 		when changes are applied +
Whether the config was saved after changes.
+
+
+

+ + +Status +------ + + +Authors +~~~~~~~ + +- VyOS Community (@vyos) diff --git a/docs/vyos.rest.vyos_firewall_interfaces_module.rst b/docs/vyos.rest.vyos_firewall_interfaces_module.rst new file mode 100644 index 0000000..56effe1 --- /dev/null +++ b/docs/vyos.rest.vyos_firewall_interfaces_module.rst @@ -0,0 +1,632 @@ +.. _vyos.rest.vyos_firewall_interfaces_module: + + +********************************** +vyos.rest.vyos_firewall_interfaces +********************************** + +**Manage firewall hook filters on VyOS devices using REST API** + + +Version added: 1.0.0 + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Manages firewall hook filter configuration on VyOS devices via the REST API. +- In VyOS 1.5+, firewall hook filters (input/output/forward) replace the per-interface firewall assignments used in VyOS 1.4. +- Hook filters apply globally to all traffic traversing that hook point. +- Uses REST API (``connection=httpapi``) instead of CLI. + + + + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterChoices/DefaultsComments
+
+ config + +
+ list + / elements=dictionary +
+ 		+ +
Firewall hook filter configuration.
+
+
+ afi + +
+ string + / required +
+ 		+
    Choices: +
  • ipv4
    • +
  • ipv6
    • +
+ 		+
Address family.
+
+
+ hooks + +
+ list + / elements=dictionary +
+ 		+ +
Hook filter configurations for this address family.
+
+
+ default_action + +
+ string +
+ 		+
    Choices: +
  • accept
    • +
  • drop
    • +
  • reject
    • +
+ 		+
Default action when no rule matches.
+
+
+ description + +
+ string +
+ 		+ +
Filter description.
+
+
+ hook + +
+ string + / required +
+ 		+
    Choices: +
  • input
    • +
  • output
    • +
  • forward
    • +
+ 		+
Netfilter hook point.
+
+
+ rules + +
+ list + / elements=dictionary +
+ 		+ +
Rules in this hook filter.
+
+
+ action + +
+ string +
+ 		+
    Choices: +
  • accept
    • +
  • drop
    • +
  • reject
    • +
  • return
    • +
  • queue
    • +
  • continue
    • +
+ 		+
Rule action.
+
+
+ description + +
+ string +
+ 		+ +
Rule description.
+
+
+ destination + +
+ dictionary +
+ 		+ +
Destination match criteria.
+
+
+ address + +
+ string +
+ 		+ +
Destination IP address or prefix.
+
+
+ port + +
+ string +
+ 		+ +
Destination port or range.
+
+
+ disable + +
+ boolean +
+ 		+
    Choices: +
  • no
    • +
  • yes
    • +
+ 		+
Disable this rule.
+
+
+ log + +
+ boolean +
+ 		+
    Choices: +
  • no
    • +
  • yes
    • +
+ 		+
Enable logging.
+
+
+ number + +
+ integer + / required +
+ 		+ +
Rule number.
+
+
+ protocol + +
+ string +
+ 		+ +
Protocol to match.
+
+
+ source + +
+ dictionary +
+ 		+ +
Source match criteria.
+
+
+ address + +
+ string +
+ 		+ +
Source IP address or prefix.
+
+
+ port + +
+ string +
+ 		+ +
Source port or range.
+
+
+ state + +
+ string +
+ 		+
    Choices: +
  • established
    • +
  • invalid
    • +
  • new
    • +
  • related
    • +
+ 		+
Connection state to match.
+
+
+ state + +
+ string +
+ 		+
    Choices: +
  • merged ←
    • +
  • replaced
    • +
  • overridden
    • +
  • deleted
    • +
  • gathered
    • +
+ 		+
Desired state of the firewall hook filter configuration.
+
merged adds or updates without removing existing config.
+
replaced replaces hook filter config for named hooks in config.
+
overridden replaces all firewall hook filter config.
+
deleted removes firewall hook filter config.
+
gathered returns current configuration as structured data.
+
+
+ + +Notes +----- + +.. note:: + - Requires ``ansible_connection=httpapi`` with the VyOS httpapi plugin. + - ``ansible_network_os`` must be set to ``vyos.rest.vyos``. + - In VyOS 1.5+, hook filters apply globally rather than per-interface. Use named rule sets (:ref:`vyos.rest.vyos_firewall_rules `) for more granular per-traffic control. + + + +Examples +-------- + +.. code-block:: yaml + + - name: Merge firewall hook filter configuration + vyos.rest.vyos_firewall_interfaces: + config: + - afi: ipv4 + hooks: + - hook: input + default_action: accept + rules: + - number: 10 + action: accept + state: established + - number: 20 + action: drop + state: invalid + - hook: forward + default_action: accept + - hook: output + default_action: accept + - afi: ipv6 + hooks: + - hook: input + default_action: accept + state: merged + + - name: Delete all firewall hook filter configuration + vyos.rest.vyos_firewall_interfaces: + state: deleted + + - name: Gather firewall hook filter configuration + vyos.rest.vyos_firewall_interfaces: + 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 +
Firewall hook filter configuration after this module ran.
+
+
+
+ before + +
+ list +
+ 		always +
Firewall hook filter configuration before this module ran.
+
+
+
+ commands + +
+ list +
+ 		always +
List of API command tuples sent to the device.
+
+
+
+ gathered + +
+ list +
+ 		when state is gathered +
Current firewall hook filter configuration as structured data.
+
+
+
+ response + +
+ dictionary +
+ 		when changes are applied +
Raw API response.
+
+
+
+ saved + +
+ boolean +
+ 		when changes are applied +
Whether the config was saved after changes.
+
+
+

+ + +Status +------ + + +Authors +~~~~~~~ + +- VyOS Community (@vyos) diff --git a/docs/vyos.rest.vyos_firewall_rules_module.rst b/docs/vyos.rest.vyos_firewall_rules_module.rst new file mode 100644 index 0000000..b0e32c8 --- /dev/null +++ b/docs/vyos.rest.vyos_firewall_rules_module.rst @@ -0,0 +1,725 @@ +.. _vyos.rest.vyos_firewall_rules_module: + + +***************************** +vyos.rest.vyos_firewall_rules +***************************** + +**Manage firewall rule sets on VyOS devices using REST API** + + +Version added: 1.0.0 + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Manages named firewall rule sets on VyOS devices via the REST API. +- Supports both IPv4 (``ipv4``) and IPv6 (``ipv6``) rule sets. +- Uses REST API (``connection=httpapi``) instead of CLI. +- In VyOS 1.5+, firewall uses named rule sets under ``firewall.ipv4.name`` and ``firewall.ipv6.name``. + + + + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterChoices/DefaultsComments
+
+ config + +
+ list + / elements=dictionary +
+ 		+ +
Firewall rule set configuration.
+
+
+ afi + +
+ string + / required +
+ 		+
    Choices: +
  • ipv4
    • +
  • ipv6
    • +
+ 		+
Address family.
+
+
+ rule_sets + +
+ list + / elements=dictionary +
+ 		+ +
Named rule sets for this address family.
+
+
+ default_action + +
+ string +
+ 		+
    Choices: +
  • accept
    • +
  • drop
    • +
  • reject
    • +
+ 		+
Default action when no rule matches.
+
+
+ description + +
+ string +
+ 		+ +
Rule set description.
+
+
+ name + +
+ string + / required +
+ 		+ +
Rule set name.
+
+
+ rules + +
+ list + / elements=dictionary +
+ 		+ +
Firewall rules in this rule set.
+
+
+ action + +
+ string +
+ 		+
    Choices: +
  • accept
    • +
  • drop
    • +
  • reject
    • +
  • return
    • +
  • queue
    • +
  • continue
    • +
+ 		+
Rule action.
+
+
+ description + +
+ string +
+ 		+ +
Rule description.
+
+
+ destination + +
+ dictionary +
+ 		+ +
Destination match criteria.
+
+
+ address + +
+ string +
+ 		+ +
Destination IP address or prefix.
+
+
+ group + +
+ string +
+ 		+ +
Destination group name.
+
+
+ port + +
+ string +
+ 		+ +
Destination port or range.
+
+
+ disable + +
+ boolean +
+ 		+
    Choices: +
  • no
    • +
  • yes
    • +
+ 		+
Disable this rule.
+
+
+ icmp + +
+ dictionary +
+ 		+ +
ICMP type/code to match.
+
+
+ code + +
+ integer +
+ 		+ +
ICMP code.
+
+
+ type + +
+ integer +
+ 		+ +
ICMP type.
+
+
+ log + +
+ boolean +
+ 		+
    Choices: +
  • no
    • +
  • yes
    • +
+ 		+
Enable logging for this rule.
+
+
+ number + +
+ integer + / required +
+ 		+ +
Rule number.
+
+
+ protocol + +
+ string +
+ 		+ +
Protocol to match.
+
+
+ source + +
+ dictionary +
+ 		+ +
Source match criteria.
+
+
+ address + +
+ string +
+ 		+ +
Source IP address or prefix.
+
+
+ group + +
+ string +
+ 		+ +
Source group name.
+
+
+ port + +
+ string +
+ 		+ +
Source port or range.
+
+
+ state + +
+ string +
+ 		+
    Choices: +
  • established
    • +
  • invalid
    • +
  • new
    • +
  • related
    • +
+ 		+
Connection state to match.
+
+
+ state + +
+ string +
+ 		+
    Choices: +
  • merged ←
    • +
  • replaced
    • +
  • overridden
    • +
  • deleted
    • +
  • gathered
    • +
+ 		+
Desired state of the firewall rules configuration.
+
merged adds or updates without removing existing config.
+
replaced replaces rule sets for named rule sets in config.
+
overridden replaces all firewall rule sets.
+
deleted removes firewall rule sets.
+
gathered returns current configuration as structured data.
+
+
+ + +Notes +----- + +.. note:: + - 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. + + + +Examples +-------- + +.. code-block:: yaml + + - name: Merge firewall rules + vyos.rest.vyos_firewall_rules: + config: + - afi: ipv4 + rule_sets: + - name: RULE-SET1 + default_action: drop + rules: + - number: 10 + action: accept + protocol: tcp + source: + address: 192.168.1.0/24 + destination: + port: "80" + - number: 20 + action: drop + state: invalid + - afi: ipv6 + rule_sets: + - name: RULE-SET6 + default_action: accept + rules: + - number: 10 + action: accept + state: merged + + - name: Delete all firewall rules + vyos.rest.vyos_firewall_rules: + state: deleted + + - name: Gather firewall rules + vyos.rest.vyos_firewall_rules: + 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 +
Firewall rules configuration after this module ran.
+
+
+
+ before + +
+ list +
+ 		always +
Firewall rules configuration before this module ran.
+
+
+
+ commands + +
+ list +
+ 		always +
List of API command tuples sent to the device.
+
+
+
+ gathered + +
+ list +
+ 		when state is gathered +
Current firewall rules configuration as structured data.
+
+
+
+ response + +
+ dictionary +
+ 		when changes are applied +
Raw API response.
+
+
+
+ saved + +
+ boolean +
+ 		when changes are applied +
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 new file mode 100644 index 0000000..1ad08f4 --- /dev/null +++ b/docs/vyos.rest.vyos_user_module.rst @@ -0,0 +1,393 @@ +.. _vyos.rest.vyos_user_module: + + +******************* +vyos.rest.vyos_user +******************* + +**Manage user accounts on VyOS devices using REST API** + + +Version added: 1.0.0 + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Manages local user accounts on VyOS devices via the REST API. +- Uses REST API (``connection=httpapi``) instead of CLI. +- Passwords are write-only. Once set, they cannot be read back in plaintext. +- Use ``update_password=on_create`` to avoid resetting passwords on every run. + + + + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterChoices/DefaultsComments
+
+ state + +
+ string +
+ 		+
    Choices: +
  • present ←
    • +
  • absent
    • +
  • gathered
    • +
+ 		+
present ensures users exist with the specified configuration.
+
absent removes specified users.
+
gathered returns current user configuration as structured data.
+
+
+ users + +
+ list + / elements=dictionary +
+ 		+ +
List of user definitions.
+
+
+ full_name + +
+ string +
+ 		+ +
Full name of the user.
+
+
+ name + +
+ string + / required +
+ 		+ +
Username.
+
+
+ password + +
+ string +
+ 		+ +
Plaintext password. Write-only — hashed on device immediately.
+
+
+ public_keys + +
+ list + / elements=dictionary +
+ 		+ +
SSH public keys for the user.
+
+
+ key + +
+ string + / required +
+ 		+ +
Base64-encoded public key.
+
+
+ name + +
+ string + / required +
+ 		+ +
Key identifier/name.
+
+
+ type + +
+ string + / required +
+ 		+
    Choices: +
  • ssh-dss
    • +
  • ssh-rsa
    • +
  • ecdsa-sha2-nistp256
    • +
  • ecdsa-sha2-nistp384
    • +
  • ecdsa-sha2-nistp521
    • +
  • ssh-ed25519
    • +
+ 		+
Key type.
+
+
+ update_password + +
+ string +
+ 		+
    Choices: +
  • always ←
    • +
  • on_create
    • +
+ 		+
Control when password is updated.
+
always updates the password on every run (default).
+
on_create only sets the password when the user is first created.
+
+
+ + +Notes +----- + +.. note:: + - Requires ``ansible_connection=httpapi`` with the VyOS httpapi plugin. + - ``ansible_network_os`` must be set to ``vyos.rest.vyos``. + - The ``vyos`` user cannot be deleted as it is required for API access. + - Passwords are hashed immediately by VyOS and cannot be read back. + + + +Examples +-------- + +.. code-block:: yaml + + - name: Create user + vyos.rest.vyos_user: + users: + - name: alice + full_name: Alice Smith + password: securepassword + update_password: on_create + state: present + + - name: Add SSH public key + vyos.rest.vyos_user: + users: + - name: alice + public_keys: + - name: alice-laptop + type: ssh-rsa + key: AAAAB3NzaC1yc2EAAAADAQABAAAB... + state: present + + - name: Delete user + vyos.rest.vyos_user: + users: + - name: alice + state: absent + + - name: Gather all users + vyos.rest.vyos_user: + 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 +
User configuration after this module ran.
+
+
+
+ before + +
+ list +
+ 		always +
User configuration before this module ran.
+
+
+
+ commands + +
+ list +
+ 		always +
List of API command tuples sent to the device.
+
+
+
+ gathered + +
+ list +
+ 		when state is gathered +
Current user configuration as structured data.
+
+
+
+ response + +
+ dictionary +
+ 		when changes are applied +
Raw API response.
+
+
+
+ saved + +
+ boolean +
+ 		when changes are applied +
Whether the config was saved after changes.
+
+
+

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