diff options
| -rw-r--r-- | README.md | 18 | ||||
| -rw-r--r-- | docs/configuration/firewall/groups.rst | 281 | ||||
| -rw-r--r-- | docs/configuration/firewall/ipv4.rst | 21 | ||||
| -rw-r--r-- | docs/configuration/firewall/ipv6.rst | 21 |
4 files changed, 301 insertions, 40 deletions
@@ -90,12 +90,14 @@ If the `vyos/vyos-documentation` container could not be found locally it will be automatically fetched from Dockerhub. ```bash -$ docker run --rm -it -v "$(pwd)":/vyos -w /vyos/docs \ - -e GOSU_UID=$(id -u) -e GOSU_GID=$(id -g) vyos/vyos-documentation make html +$ git clone https://github.com/vyos/vyos-documentation.git -# sphinx autobuild -$ docker run --rm -it -p 8000:8000 -v "$(pwd)":/vyos -w /vyos/docs -e \ - GOSU_UID=$(id -u) -e GOSU_GID=$(id -g) vyos/vyos-documentation make livehtml +$ cd vyos-documentation + +$ docker run --rm -it -v "$(pwd)":/vyos -w /vyos/docs -e GOSU_UID=$(id -u) -e GOSU_GID=$(id -g) vyos/vyos-documentation make html + +# For sphinx autobuild +$ docker run --rm -it -p 8000:8000 -v "$(pwd)":/vyos -w /vyos/docs -e GOSU_UID=$(id -u) -e GOSU_GID=$(id -g) vyos/vyos-documentation make livehtml ``` ### Test the docs @@ -103,13 +105,11 @@ $ docker run --rm -it -p 8000:8000 -v "$(pwd)":/vyos -w /vyos/docs -e \ To test all files, run: ```bash -$ docker run --rm -it -v "$(pwd)":/vyos -w /vyos/docs \ - -e GOSU_UID=$(id -u) -e GOSU_GID=$(id -g) vyos/vyos-documentation vale . +$ docker run --rm -it -v "$(pwd)":/vyos -w /vyos/docs -e GOSU_UID=$(id -u) -e GOSU_GID=$(id -g) vyos/vyos-documentation vale . ``` to test a specific file (e.g. `quick-start.rst`) ```bash -$ docker run --rm -it -v "$(pwd)":/vyos -w /vyos/docs -e GOSU_UID=$(id -u) \ - -e GOSU_GID=$(id -g) vyos/vyos-documentation vale quick-start.rst +$ docker run --rm -it -v "$(pwd)":/vyos -w /vyos/docs -e GOSU_UID=$(id -u) -e GOSU_GID=$(id -g) vyos/vyos-documentation vale quick-start.rst ``` 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 a9459f00..e19ae1bd 100644 --- a/docs/configuration/firewall/ipv4.rst +++ b/docs/configuration/firewall/ipv4.rst @@ -539,6 +539,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 4b695f74..28b57e72 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> |