Merge remote-tracking branch 'origin/current' into feat/docs-llms-txt-current

# Conflicts:
#	docs/conf.py

1 files changed, 477 insertions, 0 deletions

diff --git a/docs/configuration/firewall/groups.md b/docs/configuration/firewall/groups.md
new file mode 100644
index 00000000..817f610e
--- /dev/null
+++ b/docs/configuration/firewall/groups.md
@@ -0,0 +1,477 @@
+---
+lastproofread: '2026-03-30'
+---
+
+(firewall-groups-configuration)=
+
+# Firewall groups
+
+## Configuration
+
+Firewall groups represent collections of IP addresses, networks, ports,
+MAC addresses, domains, or interfaces. You can reference a group in firewall,
+NAT, and policy route rules as either a source or destination matcher, and/or
+as inbound or outbound in the case of interface groups.
+
+### Address Groups
+
+An **address group** contains a single IP address or IP address range.
+
+```{cfgcmd} set firewall group address-group \<name\> address [address | address range]
+
+```
+```{cfgcmd} set firewall group ipv6-address-group \<name\> address \<address\>
+
+Define an IPv4 or IPv6 address group.
+
+:::{code-block} none
+set firewall group address-group ADR-INSIDE-v4 address 192.168.0.1
+set firewall group address-group ADR-INSIDE-v4 address 10.0.0.1-10.0.0.8
+set firewall group ipv6-address-group ADR-INSIDE-v6 address 2001:db8::1
+:::
+```
+
+```{cfgcmd} set firewall group address-group \<name\> description \<text\>
+```
+
+```{cfgcmd} set firewall group ipv6-address-group \<name\> description \<text\>
+
+Provide an IPv4 or IPv6 address group description.
+```
+
+### Remote Groups
+
+A **remote-group** uses a URL that hosts a newline-delimited list of IPv4
+and/or IPv6 addresses, CIDRs, and ranges. VyOS pulls this list periodically
+according to the frequency you define in the firewall **resolver-interval**
+and loads matching entries into the group for use in rules. The list is cached
+in persistent storage, so rules continue to function if updates fail.
+
+```{cfgcmd} set firewall group remote-group \<name\> url \<http(s) url\>
+
+Specify a remote list of IPv4 and/or IPv6 addresses, ranges, and CIDRs
+to fetch.
+```
+
+```{cfgcmd} set firewall group remote-group \<name\> description \<text\>
+
+Set a description for a remote group.
+```
+
+The remote list format is flexible. VyOS attempts to parse the first word of
+each line as an entry and skips lines it cannot match. Lines that begin with
+an alphanumeric character but do not match valid IPv4 or IPv6 addresses,
+ranges, or CIDRs are logged to the system log. The following examples show
+acceptable formats that VyOS parses correctly:
+
+```none
+127.0.0.1
+127.0.0.0/24
+127.0.0.1-127.0.0.254
+2001:db8::1
+2001:db8:cafe::/48
+2001:db8:cafe::1-2001:db8:cafe::ffff
+```
+
+### Network Groups
+
+**Network groups** accept IP networks in CIDR notation. You can add specific
+IP addresses as a 32-bit prefix. If you need to add a mix of addresses and
+networks, use a network group.
+
+```{cfgcmd} set firewall group network-group \<name\> network \<CIDR\>
+```
+
+```{cfgcmd} set firewall group ipv6-network-group \<name\> network \<CIDR\>
+
+Define an IPv4 or IPv6 network group.
+
+:::{code-block} none
+set firewall group network-group NET-INSIDE-v4 network 192.168.0.0/24
+set firewall group network-group NET-INSIDE-v4 network 192.168.1.0/24
+set firewall group ipv6-network-group NET-INSIDE-v6 network 2001:db8::/64
+:::
+```
+
+```{cfgcmd} set firewall group network-group \<name\> description \<text\>
+```
+
+```{cfgcmd} set firewall group ipv6-network-group \<name\> description \<text\>
+
+Provide an IPv4 or IPv6 network group description.
+```
+
+### Interface Groups
+
+An **interface group** represents a collection of interfaces.
+
+```{cfgcmd} set firewall group interface-group \<name\> interface \<text\>
+
+Define an interface group.
+Wildcard ``*`` is supported. For example: ``eth3*``.
+Prepend the character ``!`` to invert the criteria. For example: ``!eth2``.
+```
+
+```none
+set firewall group interface-group LAN interface bond1001
+set firewall group interface-group LAN interface eth3*
+```
+
+```{cfgcmd} set firewall group interface-group \<name\> description \<text\>
+
+Provide an interface group description.
+```
+
+### Port Groups
+
+A **port group** represents only port numbers, not the protocol. You can
+reference port groups for either TCP or UDP. Create TCP and UDP groups
+separately to avoid accidentally filtering unnecessary ports. Specify port
+ranges by using `-`.
+
+```{cfgcmd} set firewall group port-group \<name\> port [portname | portnumber | startport-endport]
+
+Define a port group. A port name can be any name defined in
+/etc/services. For example, ``http``.
+
+:::{code-block} none
+set firewall group port-group PORT-TCP-SERVER1 port http
+set firewall group port-group PORT-TCP-SERVER1 port 443
+set firewall group port-group PORT-TCP-SERVER1 port 5000-5010
+:::
+```
+
+```{cfgcmd} set firewall group port-group \<name\> description \<text\>
+
+Provide a port group description.
+```
+
+### MAC Groups
+
+A **mac group** represents a collection of mac addresses.
+
+```{cfgcmd} set firewall group mac-group \<name\> mac-address \<mac-address\>
+
+Define a mac group.
+```
+
+```none
+set firewall group mac-group MAC-G01 mac-address 88:a4:c2:15:b6:4f
+set firewall group mac-group MAC-G01 mac-address 4c:d5:77:c0:19:81
+```
+
+```{cfgcmd} set firewall group mac-group \<name\> description \<text\>
+
+Provide a MAC group description.
+```
+
+### Domain Groups
+
+A **domain group** represents a collection of domains.
+
+```{cfgcmd} set firewall group domain-group \<name\> address \<domain\>
+
+Define a domain group.
+```
+
+```none
+set firewall group domain-group DOM address example.com
+```
+
+```{cfgcmd} set firewall group domain-group \<name\> description \<text\>
+
+Provide a domain group description.
+```
+
+### Dynamic Groups
+
+Firewall dynamic groups differ from other groups because you can use them as
+source/destination in firewall rules, and members are not defined statically
+in VyOS configuration. Instead, firewall rules dynamically add members to
+these groups.
+
+#### Defining Dynamic Address Groups
+
+Dynamic address groups support both IPv4 and IPv6 families. Use these
+commands to define dynamic IPv4 and IPv6 address groups:
+
+```{cfgcmd} set firewall group dynamic-group address-group \<name\>
+```
+
+```{cfgcmd} set firewall group dynamic-group ipv6-address-group \<name\>
+```
+
+Add description to firewall groups:
+
+```{cfgcmd} set firewall group dynamic-group address-group \<name\> description \<text\>
+```
+
+```{cfgcmd} set firewall group dynamic-group ipv6-address-group \<name\> description \<text\>
+```
+
+#### Adding elements to Dynamic Firewall Groups
+
+After you define dynamic firewall groups, use them in firewall rules to
+dynamically add elements to them.
+
+Commands used for this task are:
+- Add destination IP address of the connection to a dynamic address group:
+
+```{cfgcmd} set firewall ipv4 [forward | input | output] filter rule \<1-999999\> add-address-to-group destination-address address-group \<name\>
+```
+
+```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> add-address-to-group destination-address address-group \<name\>
+```
+
+```{cfgcmd} set firewall ipv6 [forward | input | output] filter rule \<1-999999\> add-address-to-group destination-address address-group \<name\>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> add-address-to-group destination-address address-group \<name\>
+```
+
+- Add source IP address of the connection to a dynamic address group:
+
+```{cfgcmd} set firewall ipv4 [forward | input | output] filter rule \<1-999999\> add-address-to-group source-address address-group \<name\>
+```
+
+```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> add-address-to-group source-address address-group \<name\>
+```
+
+```{cfgcmd} set firewall ipv6 [forward | input | output] filter rule \<1-999999\> add-address-to-group source-address address-group \<name\>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> add-address-to-group source-address address-group \<name\>
+```
+
+You can define specific timeouts per rule. When a rule matches, the source or
+destination address is added to the group, and the element remains in the group
+until the timeout expires. If you do not define a timeout, the element remains
+in the group until the next reboot or until you commit firewall configuration
+changes.
+
+```{cfgcmd} set firewall ipv4 [forward | input | output] filter rule \<1-999999\> add-address-to-group [destination-address | source-address] timeout \<timeout\>
+```
+
+```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> add-address-to-group [destination-address | source-address] timeout \<timeout\>
+```
+
+```{cfgcmd} set firewall ipv6 [forward | input | output] filter rule \<1-999999\> add-address-to-group [destination-address | source-address] timeout \<timeout\>
+```
+
+```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> add-address-to-group [destination-address | source-address] timeout \<timeout\>
+```
+
+Timeout can be defined using seconds, minutes, hours or days:
+
+```none
+set firewall ipv6 name FOO rule 10 add-address-to-group source-address timeout
+Possible completions:
+<number>s            Timeout value in seconds
+<number>m            Timeout value in minutes
+<number>h            Timeout value in hours
+<number>d            Timeout value in days
+```
+
+#### Using Dynamic Firewall Groups
+
+Like other firewall groups, you can use dynamic firewall groups in firewall
+rules as matching options. For example:
+
+```none
+set firewall ipv4 input filter rule 10 source group dynamic-address-group FOO
+set firewall ipv4 input filter rule 10 destination group dynamic-address-group BAR
+```
+
+## Examples
+
+### General example
+
+After you create firewall groups, you can reference them in firewall, NAT,
+NAT66, and/or policy-route rules. The following example creates multiple
+groups:
+
+```{eval-rst}
+   .. code-block:: none
+
+      set firewall group address-group SERVERS address 198.51.100.101
+      set firewall group address-group SERVERS address 198.51.100.102
+      set firewall group network-group TRUSTEDv4 network 192.0.2.0/30
+      set firewall group network-group TRUSTEDv4 network 203.0.113.128/25
+      set firewall group ipv6-network-group TRUSTEDv6 network 2001:db8::/64
+      set firewall group interface-group LAN interface eth2.2001
+      set firewall group interface-group LAN interface bon0
+      set firewall group port-group PORT-SERVERS port http
+      set firewall group port-group PORT-SERVERS port 443
+      set firewall group port-group PORT-SERVERS port 5000-5010
+```
+
+And next, some configuration example where groups are used:
+
+```{eval-rst}
+   .. code-block:: none
+
+      set firewall ipv4 output filter rule 10 action accept
+      set firewall ipv4 output filter rule 10 outbound-interface group !LAN
+      set firewall ipv4 forward filter rule 20 action accept
+      set firewall ipv4 forward filter rule 20 source group network-group TRUSTEDv4
+      set firewall ipv6 input filter rule 10 action accept
+      set firewall ipv6 input filter rule 10 source group network-group TRUSTEDv6
+      set nat destination rule 101 inbound-interface group LAN
+      set nat destination rule 101 destination group address-group SERVERS
+      set nat destination rule 101 protocol tcp
+      set nat destination rule 101 destination group port-group PORT-SERVERS
+      set nat destination rule 101 translation address 203.0.113.250
+      set policy route PBR rule 201 destination group port-group PORT-SERVERS
+      set policy route PBR rule 201 protocol tcp
+      set policy route PBR rule 201 set table 15
+```
+
+### Port knocking example
+
+You can use dynamic firewall groups with port knocking to secure access to
+the router or any other device. The following example shows a 4-step port
+knocking configuration:
+
+```{eval-rst}
+   .. code-block:: none
+
+      set firewall global-options state-policy established action 'accept'
+      set firewall global-options state-policy invalid action 'drop'
+      set firewall global-options state-policy related action 'accept'
+      set firewall group dynamic-group address-group ALLOWED
+      set firewall group dynamic-group address-group PN_01
+      set firewall group dynamic-group address-group PN_02
+      set firewall ipv4 input filter default-action 'drop'
+      set firewall ipv4 input filter rule 5 action 'accept'
+      set firewall ipv4 input filter rule 5 protocol 'icmp'
+      set firewall ipv4 input filter rule 10 action 'drop'
+      set firewall ipv4 input filter rule 10 add-address-to-group source-address address-group 'PN_01'
+      set firewall ipv4 input filter rule 10 add-address-to-group source-address timeout '2m'
+      set firewall ipv4 input filter rule 10 description 'Port_nock 01'
+      set firewall ipv4 input filter rule 10 destination port '9990'
+      set firewall ipv4 input filter rule 10 protocol 'tcp'
+      set firewall ipv4 input filter rule 20 action 'drop'
+      set firewall ipv4 input filter rule 20 add-address-to-group source-address address-group 'PN_02'
+      set firewall ipv4 input filter rule 20 add-address-to-group source-address timeout '3m'
+      set firewall ipv4 input filter rule 20 description 'Port_nock 02'
+      set firewall ipv4 input filter rule 20 destination port '9991'
+      set firewall ipv4 input filter rule 20 protocol 'tcp'
+      set firewall ipv4 input filter rule 20 source group dynamic-address-group 'PN_01'
+      set firewall ipv4 input filter rule 30 action 'drop'
+      set firewall ipv4 input filter rule 30 add-address-to-group source-address address-group 'ALLOWED'
+      set firewall ipv4 input filter rule 30 add-address-to-group source-address timeout '2h'
+      set firewall ipv4 input filter rule 30 description 'Port_nock 03'
+      set firewall ipv4 input filter rule 30 destination port '9992'
+      set firewall ipv4 input filter rule 30 protocol 'tcp'
+      set firewall ipv4 input filter rule 30 source group dynamic-address-group 'PN_02'
+      set firewall ipv4 input filter rule 99 action 'accept'
+      set firewall ipv4 input filter rule 99 description 'Port_nock 04 - Allow ssh'
+      set firewall ipv4 input filter rule 99 destination port '22'
+      set firewall ipv4 input filter rule 99 protocol 'tcp'
+      set firewall ipv4 input filter rule 99 source group dynamic-address-group 'ALLOWED'
+```
+
+Before testing, we can check the members of firewall groups:
+
+```none
+vyos@vyos# run show firewall group
+Firewall Groups
+
+Name     Type                    References            Members        Timeout    Expires
+-------  ----------------------  --------------------  -------------  ---------  ---------
+ALLOWED  address_group(dynamic)  ipv4-input-filter-30  N/D            N/D        N/D
+PN_01    address_group(dynamic)  ipv4-input-filter-10  N/D            N/D        N/D
+PN_02    address_group(dynamic)  ipv4-input-filter-20  N/D            N/D        N/D
+[edit]
+vyos@vyos#
+```
+
+With this configuration, to gain SSH access to the router, the user must:
+
+1. Create a new TCP connection to destination port 9990. A new entry is added
+   to dynamic firewall group `PN_01`.
+
+   ```none
+   vyos@vyos# run show firewall group
+   Firewall Groups
+
+   Name     Type                    References            Members        Timeout    Expires
+   -------  ----------------------  --------------------  -------------  ---------  ---------
+   ALLOWED  address_group(dynamic)  ipv4-input-filter-30  N/D            N/D        N/D
+   PN_01    address_group(dynamic)  ipv4-input-filter-10  192.168.89.31  120        119
+   PN_02    address_group(dynamic)  ipv4-input-filter-20  N/D            N/D        N/D
+   [edit]
+   vyos@vyos#
+   ```
+
+2. Create a new TCP connection to destination port 9991. A new entry is added
+   to dynamic firewall group `PN_02`.
+
+   ```none
+   vyos@vyos# run show firewall group
+   Firewall Groups
+
+   Name     Type                    References            Members        Timeout    Expires
+   -------  ----------------------  --------------------  -------------  ---------  ---------
+   ALLOWED  address_group(dynamic)  ipv4-input-filter-30  N/D            N/D        N/D
+   PN_01    address_group(dynamic)  ipv4-input-filter-10  192.168.89.31  120        106
+   PN_02    address_group(dynamic)  ipv4-input-filter-20  192.168.89.31  180        179
+   [edit]
+   vyos@vyos#
+   ```
+
+3. Create a new TCP connection to destination port 9992. A new entry is added
+   to dynamic firewall group `ALLOWED`.
+
+   ```none
+   vyos@vyos# run show firewall group
+   Firewall Groups
+
+   Name     Type                    References            Members        Timeout    Expires
+   -------  ----------------------  --------------------  -------------  ---------  ---------
+   ALLOWED  address_group(dynamic)  ipv4-input-filter-30  192.168.89.31       7200       7199
+   PN_01    address_group(dynamic)  ipv4-input-filter-10  192.168.89.31        120         89
+   PN_02    address_group(dynamic)  ipv4-input-filter-20  192.168.89.31        180        170
+   [edit]
+   vyos@vyos#
+   ```
+
+4. Now you can connect via SSH to the router (assuming SSH is
+   configured).
+
+## Operation-mode
+
+```{opcmd} show firewall group
+```
+
+```{opcmd} show firewall group \<name\>
+
+Display an overview of defined groups, including the firewall group name,
+type, references (where the group is used), members, timeout, and
+expiration (the last two only apply to dynamic firewall groups).
+```
+
+Here is an example of such command:
+
+```none
+vyos@vyos:~$ show firewall group
+Firewall Groups
+
+Name          Type                    References              Members             Timeout    Expires
+------------  ----------------------  ----------------------  ----------------  ---------  ---------
+SERVERS       address_group           nat-destination-101     198.51.100.101
+                                                              198.51.100.102
+ALLOWED       address_group(dynamic)  ipv4-input-filter-30    192.168.77.39          7200       7174
+PN_01         address_group(dynamic)  ipv4-input-filter-10    192.168.0.245           120        112
+                                                              192.168.77.39           120         85
+PN_02         address_group(dynamic)  ipv4-input-filter-20    192.168.77.39           180        151
+LAN           interface_group         ipv4-output-filter-10   bon0
+                                      nat-destination-101     eth2.2001
+TRUSTEDv6     ipv6_network_group      ipv6-input-filter-10    2001:db8::/64
+TRUSTEDv4     network_group           ipv4-forward-filter-20  192.0.2.0/30
+                                                              203.0.113.128/25
+PORT-SERVERS  port_group              route-PBR-201           443
+                                      route-PBR-201           5000-5010
+                                      nat-destination-101     http
+vyos@vyos:~$
+```