summaryrefslogtreecommitdiff
path: root/docs/configuration/firewall/groups.rst
diff options
context:
space:
mode:
authorNicolas Fort <nicolasfort1988@gmail.com>2023-11-08 13:21:51 -0300
committerNicolas Fort <nicolasfort1988@gmail.com>2023-11-08 13:51:47 -0300
commitb6c3c7f40a5d4399244e97d9e575db78389e660c (patch)
treea51fff1e098c071cec56c0e09560c0fa3ef7cd69 /docs/configuration/firewall/groups.rst
parentece28ce8097f4835ff2e6fb55bc6ca13f0d1ffc0 (diff)
downloadvyos-documentation-b6c3c7f40a5d4399244e97d9e575db78389e660c.tar.gz
vyos-documentation-b6c3c7f40a5d4399244e97d9e575db78389e660c.zip
Firewall Update: improve documentation and split file for better experience while reading. Add brief notes regarding Flowtables and Bridge firewall, leaving a note that those documents are still under development. New explanation for Netfilter based firewall, which includes new diagrams.
Diffstat (limited to 'docs/configuration/firewall/groups.rst')
-rw-r--r--docs/configuration/firewall/groups.rst210
1 files changed, 210 insertions, 0 deletions
diff --git a/docs/configuration/firewall/groups.rst b/docs/configuration/firewall/groups.rst
new file mode 100644
index 00000000..aee68793
--- /dev/null
+++ b/docs/configuration/firewall/groups.rst
@@ -0,0 +1,210 @@
+:lastproofread: 2023-11-08
+
+.. _firewall-groups-configuration:
+
+###############
+Firewall groups
+###############
+
+*************
+Configuration
+*************
+
+Firewall groups represent collections of IP addresses, networks, ports,
+mac addresses, domains or interfaces. Once created, a group can be referenced
+by firewall, nat and policy route rules as either a source or destination
+matcher, and/or as inbound/outbound in the case of interface group.
+
+Address Groups
+==============
+
+In an **address group** a single IP address or IP address ranges are
+defined.
+
+.. cfgcmd:: set firewall group address-group <name> address [address |
+ address range]
+.. cfgcmd:: set firewall group ipv6-address-group <name> address <address>
+
+ Define a IPv4 or a 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 a IPv4 or IPv6 address group description
+
+Network Groups
+==============
+
+While **network groups** accept IP networks in CIDR notation, specific
+IP addresses can be added as a 32-bit prefix. If you foresee the need
+to add a mix of addresses and networks, the network group is
+recommended.
+
+.. cfgcmd:: set firewall group network-group <name> network <CIDR>
+.. cfgcmd:: set firewall group ipv6-network-group <name> network <CIDR>
+
+ Define a 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 are accepted too.
+
+.. code-block:: 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. Port
+groups can be referenced for either TCP or UDP. It is recommended that
+TCP and UDP groups are created separately to avoid accidentally
+filtering unnecessary ports. Ranges of ports can be specified 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. e.g.: 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.
+
+.. code-block:: 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.
+
+.. code-block:: none
+
+ set firewall group domain-group DOM address example.com
+
+.. cfgcmd:: set firewall group domain-group <name> description <text>
+
+ Provide a domain group description.
+
+********
+Examples
+********
+
+As said before, once firewall groups are created, they can be referenced
+either in firewall, nat, nat66 and/or policy-route rules.
+
+Here is an example were multiple groups are created:
+
+ .. 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:
+
+ .. code-block:: none
+
+ set firewall ipv4 input filter rule 10 action accept
+ set firewall ipv4 input filter rule 10 inbound-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
+
+**************
+Operation-mode
+**************
+
+.. opcmd:: show firewall group <name>
+
+ Overview of defined groups. You see the type, the members, and where the
+ group is used.
+
+ .. code-block:: none
+
+ vyos@ZBF-15-CLean:~$ show firewall group
+ Firewall Groups
+
+ Name Type References Members
+ ------------ ------------------ ---------------------- ----------------
+ SERVERS address_group nat-destination-101 198.51.100.101
+ 198.51.100.102
+ LAN interface_group ipv4-input-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
+ nat-destination-101 5000-5010
+ http
+ vyos@ZBF-15-CLean:~$