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