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_firewall_rules_module.rst | 725 ++++++++++++++++++++++++++ 1 file changed, 725 insertions(+) create mode 100644 docs/vyos.rest.vyos_firewall_rules_module.rst (limited to 'docs/vyos.rest.vyos_firewall_rules_module.rst') 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) -- cgit v1.2.3