summaryrefslogtreecommitdiff
path: root/docs/configuration
diff options
context:
space:
mode:
Diffstat (limited to 'docs/configuration')
-rw-r--r--docs/configuration/firewall/groups.rst281
-rw-r--r--docs/configuration/firewall/ipv4.rst21
-rw-r--r--docs/configuration/firewall/ipv6.rst21
3 files changed, 292 insertions, 31 deletions
diff --git a/docs/configuration/firewall/groups.rst b/docs/configuration/firewall/groups.rst
index aee68793..6111650a 100644
--- a/docs/configuration/firewall/groups.rst
+++ b/docs/configuration/firewall/groups.rst
@@ -21,9 +21,9 @@ 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 |
+.. cfgcmd:: set firewall group address-group <name> address [address |
address range]
-.. cfgcmd:: set firewall group ipv6-address-group <name> address <address>
+.. cfgcmd:: set firewall group ipv6-address-group <name> address <address>
Define a IPv4 or a IPv6 address group
@@ -33,8 +33,8 @@ defined.
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>
+.. 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
@@ -46,8 +46,8 @@ 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>
+.. 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.
@@ -57,8 +57,8 @@ recommended.
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>
+.. 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.
@@ -67,7 +67,7 @@ Interface Groups
An **interface group** represents a collection of interfaces.
-.. cfgcmd:: set firewall group interface-group <name> interface <text>
+.. cfgcmd:: set firewall group interface-group <name> interface <text>
Define an interface group. Wildcard are accepted too.
@@ -76,7 +76,7 @@ An **interface group** represents a collection of interfaces.
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>
+.. cfgcmd:: set firewall group interface-group <name> description <text>
Provide an interface group description
@@ -110,7 +110,7 @@ MAC Groups
A **mac group** represents a collection of mac addresses.
-.. cfgcmd:: set firewall group mac-group <name> mac-address <mac-address>
+.. cfgcmd:: set firewall group mac-group <name> mac-address <mac-address>
Define a mac group.
@@ -128,7 +128,7 @@ Domain Groups
A **domain group** represents a collection of domains.
-.. cfgcmd:: set firewall group domain-group <name> address <domain>
+.. cfgcmd:: set firewall group domain-group <name> address <domain>
Define a domain group.
@@ -140,10 +140,108 @@ A **domain group** represents a collection of domains.
Provide a domain group description.
+Dynamic Groups
+==============
+
+Firewall dynamic groups are different from all the groups defined previously
+because, not only they can be used as source/destination in firewall rules,
+but members of these groups are not defined statically using vyos
+configuration.
+
+Instead, members of these groups are added dynamically using firewall
+rules.
+
+Defining Dynamic Address Groups
+-------------------------------
+
+Dynamic address group is supported by both IPv4 and IPv6 families.
+Commands used to define dynamic IPv4|IPv6 address groups are:
+
+.. 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
+------------------------------------------
+
+Once dynamic firewall groups are defined, they should be used in firewall
+rules in order to dynamically add elements to it.
+
+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>
+
+Also, specific timeout can be defined per rule. In case rule gets a hit,
+source or destinatination address will be added to the group, and this
+element will remain in the group until timeout expires. If no timeout
+is defined, then the element will remain in the group until next reboot,
+or until a new commit that changes firewall configuration is done.
+
+.. 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:
+
+.. code-block:: 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
+-----------------------------
+
+As any other firewall group, dynamic firewall groups can be used in firewall
+rules as matching options. For example:
+
+.. code-block:: 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
+===============
+
As said before, once firewall groups are created, they can be referenced
either in firewall, nat, nat66 and/or policy-route rules.
@@ -166,12 +264,12 @@ 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 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 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
@@ -181,30 +279,151 @@ And next, some configuration example where groups are used:
set policy route PBR rule 201 protocol tcp
set policy route PBR rule 201 set table 15
+Port knocking example
+=====================
+
+Using dynamic firewall groups, we can secure access to the router, or any other
+device if needed, by using the technique of port knocking.
+
+A 4 step port knocking example is shown next:
+
+ .. 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 members of firewall groups:
+
+ .. code-block:: 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, in order to get ssh access to the router, user
+needs to:
+
+1. Generate a new TCP connection with destination port 9990. As shown next,
+a new entry was added to dynamic firewall group **PN_01**
+
+ .. code-block:: 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. Generate a new TCP connection with destination port 9991. As shown next,
+a new entry was added to dynamic firewall group **PN_02**
+
+ .. code-block:: 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. Generate a new TCP connection with destination port 9992. As shown next,
+a new entry was added to dynamic firewall group **ALLOWED**
+
+ .. code-block:: 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 user can connect through ssh to the router (assuming ssh is configured).
+
**************
Operation-mode
**************
+.. opcmd:: show firewall group
.. opcmd:: show firewall group <name>
- Overview of defined groups. You see the type, the members, and where the
- group is used.
+ Overview of defined groups. You see the firewall group name, type,
+ references (where the group is used), members, timeout and expiration (last
+ two only present in dynamic firewall groups).
+
+Here is an example of such command:
.. code-block:: none
- vyos@ZBF-15-CLean:~$ show firewall group
+ vyos@vyos:~$ 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:~$
+ 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:~$ \ No newline at end of file
diff --git a/docs/configuration/firewall/ipv4.rst b/docs/configuration/firewall/ipv4.rst
index b5a087a7..2fe877bb 100644
--- a/docs/configuration/firewall/ipv4.rst
+++ b/docs/configuration/firewall/ipv4.rst
@@ -516,6 +516,27 @@ geoip) to keep database and rules updated.
criteria.
.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
+ source group dynamic-address-group <name | !name>
+.. cfgcmd:: set firewall ipv4 input filter rule <1-999999>
+ source group dynamic-address-group <name | !name>
+.. cfgcmd:: set firewall ipv4 output filter rule <1-999999>
+ source group dynamic-address-group <name | !name>
+.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999>
+ source group dynamic-address-group <name | !name>
+
+.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
+ destination group dynamic-address-group <name | !name>
+.. cfgcmd:: set firewall ipv4 input filter rule <1-999999>
+ destination group dynamic-address-group <name | !name>
+.. cfgcmd:: set firewall ipv4 output filter rule <1-999999>
+ destination group dynamic-address-group <name | !name>
+.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999>
+ destination group dynamic-address-group <name | !name>
+
+ Use a specific dynamic-address-group. Prepend character ``!`` for inverted
+ matching criteria.
+
+.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999>
source group network-group <name | !name>
.. cfgcmd:: set firewall ipv4 input filter rule <1-999999>
source group network-group <name | !name>
diff --git a/docs/configuration/firewall/ipv6.rst b/docs/configuration/firewall/ipv6.rst
index 6f343323..29cbe097 100644
--- a/docs/configuration/firewall/ipv6.rst
+++ b/docs/configuration/firewall/ipv6.rst
@@ -526,6 +526,27 @@ geoip) to keep database and rules updated.
criteria.
.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999>
+ source group dynamic-address-group <name | !name>
+.. cfgcmd:: set firewall ipv6 input filter rule <1-999999>
+ source group dynamic-address-group <name | !name>
+.. cfgcmd:: set firewall ipv6 output filter rule <1-999999>
+ source group dynamic-address-group <name | !name>
+.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999>
+ source group dynamic-address-group <name | !name>
+
+.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999>
+ destination group dynamic-address-group <name | !name>
+.. cfgcmd:: set firewall ipv6 input filter rule <1-999999>
+ destination group dynamic-address-group <name | !name>
+.. cfgcmd:: set firewall ipv6 output filter rule <1-999999>
+ destination group dynamic-address-group <name | !name>
+.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999>
+ destination group dynamic-address-group <name | !name>
+
+ Use a specific dynamic-address-group. Prepend character ``!`` for inverted
+ matching criteria.
+
+.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999>
source group network-group <name | !name>
.. cfgcmd:: set firewall ipv6 input filter rule <1-999999>
source group network-group <name | !name>