From 6e545b86f8e87f26e7a2b83e3dbec13c0f494dc8 Mon Sep 17 00:00:00 2001 From: Nicolas Fort Date: Tue, 5 Dec 2023 16:22:24 -0300 Subject: Firewall: update firewall bridge docs, and general diagram. Add minor fix to ipv4 firewall doc, and update ipv6 --- docs/configuration/firewall/bridge.rst | 361 ++++++++++++++++++++++++++++++++- docs/configuration/firewall/ipv4.rst | 52 ++++- docs/configuration/firewall/ipv6.rst | 130 +++++++----- 3 files changed, 482 insertions(+), 61 deletions(-) (limited to 'docs/configuration/firewall') diff --git a/docs/configuration/firewall/bridge.rst b/docs/configuration/firewall/bridge.rst index 4a0dc3bb..9fb019c5 100644 --- a/docs/configuration/firewall/bridge.rst +++ b/docs/configuration/firewall/bridge.rst @@ -39,4 +39,363 @@ for this layer is shown next: For traffic that needs to be forwared internally by the bridge, base chain is is **forward**, and it's base command for filtering is ``set firewall bridge -forward filter ...`` +forward filter ...``, which happens in stage 4, highlightened with red color. + +Custom bridge firewall chains can be create with command ``set firewall bridge +name ...``. In order to use such custom chain, a rule with action jump, +and the appropiate target should be defined in a base chain. + +.. note:: **Layer 3 bridge**: + When an IP address is assigned to the bridge interface, and if traffic + is sent to the router to this IP (for example using such IP as + default gateway), then rules defined for **bridge firewall** won't + match, and firewall analysis continues at **IP layer**. + +************ +Bridge Rules +************ + +For firewall filtering, firewall rules needs to be created. Each rule is +numbered, has an action to apply if the rule is matched, and the ability +to specify multiple criteria matchers. Data packets go through the rules +from 1 - 999999, so order is crucial. At the first match the action of the +rule will be executed. + +Actions +======= + +If a rule is defined, then an action must be defined for it. This tells the +firewall what to do if all criteria matchers defined for such rule do match. + +In firewall bridge rules, the action can be: + + * ``accept``: accept the packet. + + * ``continue``: continue parsing next rule. + + * ``drop``: drop the packet. + + * ``jump``: jump to another custom chain. + + * ``return``: Return from the current chain and continue at the next rule + of the last chain. + + * ``queue``: Enqueue packet to userspace. + +.. cfgcmd:: set firewall bridge forward filter rule <1-999999> action + [accept | continue | drop | jump | queue | return] +.. cfgcmd:: set firewall bridge name rule <1-999999> action + [accept | continue | drop | jump | queue | return] + + This required setting defines the action of the current rule. If action is + set to jump, then jump-target is also needed. + +.. cfgcmd:: set firewall bridge forward filter rule <1-999999> + jump-target +.. cfgcmd:: set firewall bridge name rule <1-999999> + jump-target + +.. cfgcmd:: set firewall bridge forward filter rule <1-999999> + queue <0-65535> +.. cfgcmd:: set firewall bridge name rule <1-999999> + queue <0-65535> + + To be used only when action is set to ``queue``. Use this command to specify + queue target to use. Queue range is also supported. + +.. cfgcmd:: set firewall bridge forward filter rule <1-999999> + queue-options bypass +.. cfgcmd:: set firewall bridge name rule <1-999999> + queue-options bypass + + To be used only when action is set to ``queue``. Use this command to let + packet go through firewall when no userspace software is connected to the + queue. + +.. cfgcmd:: set firewall bridge forward filter rule <1-999999> + queue-options fanout +.. cfgcmd:: set firewall bridge name rule <1-999999> + queue-options fanout + + To be used only when action is set to ``queue``. Use this command to + distribute packets between several queues. + +Also, **default-action** is an action that takes place whenever a packet does +not match any rule in it's chain. For base chains, possible options for +**default-action** are **accept** or **drop**. + +.. cfgcmd:: set firewall bridge forward filter default-action + [accept | drop] +.. cfgcmd:: set firewall bridge name default-action + [accept | continue | drop | jump | queue | return] + + This set the default action of the rule-set if no rule matched a packet + criteria. If default-action is set to ``jump``, then + ``default-jump-target`` is also needed. Note that for base chains, default + action can only be set to ``accept`` or ``drop``, while on custom chain, + more actions are available. + +.. cfgcmd:: set firewall bridge name default-jump-target + + To be used only when ``defult-action`` is set to ``jump``. Use this + command to specify jump target for default rule. + +.. note:: **Important note about default-actions:** + If default action for any base chain is not defined, then the default + action is set to **accept** for that chain. For custom chains, if default + action is not defined, then the default-action is set to **drop**. + +Firewall Logs +============= + +Logging can be enable for every single firewall rule. If enabled, other +log options can be defined. + +.. cfgcmd:: set firewall bridge forward filter rule <1-999999> log +.. cfgcmd:: set firewall bridge name rule <1-999999> log + + Enable logging for the matched packet. If this configuration command is not + present, then log is not enabled. + +.. cfgcmd:: set firewall bridge forward filter enable-default-log +.. cfgcmd:: set firewall bridge name enable-default-log + + Use this command to enable the logging of the default action on + the specified chain. + +.. cfgcmd:: set firewall bridge forward filter rule <1-999999> + log-options level [emerg | alert | crit | err | warn | notice + | info | debug] +.. cfgcmd:: set firewall bridge name rule <1-999999> + log-options level [emerg | alert | crit | err | warn | notice + | info | debug] + + Define log-level. Only applicable if rule log is enable. + +.. cfgcmd:: set firewall bridge forward filter rule <1-999999> + log-options group <0-65535> +.. cfgcmd:: set firewall bridge name rule <1-999999> + log-options group <0-65535> + + Define log group to send message to. Only applicable if rule log is enable. + +.. cfgcmd:: set firewall bridge forward filter rule <1-999999> + log-options snapshot-length <0-9000> +.. cfgcmd:: set firewall bridge name rule <1-999999> + log-options snapshot-length <0-9000> + + Define length of packet payload to include in netlink message. Only + applicable if rule log is enable and log group is defined. + +.. cfgcmd:: set firewall bridge forward filter rule <1-999999> + log-options queue-threshold <0-65535> +.. cfgcmd:: set firewall bridge name rule <1-999999> + log-options queue-threshold <0-65535> + + Define number of packets to queue inside the kernel before sending them to + userspace. Only applicable if rule log is enable and log group is defined. + +Firewall Description +==================== + +For reference, a description can be defined for every defined custom chain. + +.. cfgcmd:: set firewall bridge name description + + Provide a rule-set description to a custom firewall chain. + +Rule Status +=========== + +When defining a rule, it is enable by default. In some cases, it is useful to +just disable the rule, rather than removing it. + +.. cfgcmd:: set firewall bridge forward filter rule <1-999999> disable +.. cfgcmd:: set firewall bridge name rule <1-999999> disable + + Command for disabling a rule but keep it in the configuration. + +Matching criteria +================= + +There are a lot of matching criteria against which the packet can be tested. + +.. cfgcmd:: set firewall bridge forward filter rule <1-999999> + destination mac-address +.. cfgcmd:: set firewall bridge name rule <1-999999> + destination mac-address +.. cfgcmd:: set firewall bridge forward filter rule <1-999999> + source mac-address +.. cfgcmd:: set firewall bridge name rule <1-999999> + source mac-address + + Match criteria based on source and/or destination mac-address. + +.. cfgcmd:: set firewall bridge forward filter rule <1-999999> + inbound-interface name +.. cfgcmd:: set firewall bridge name rule <1-999999> + inbound-interface name + + Match based on inbound interface. Wilcard ``*`` can be used. + For example: ``eth2*``. Prepending character ``!`` for inverted matching + criteria is also supportd. For example ``!eth2`` + +.. cfgcmd:: set firewall bridge forward filter rule <1-999999> + inbound-interface group +.. cfgcmd:: set firewall bridge name rule <1-999999> + inbound-interface group + + Match based on inbound interface group. Prepending character ``!`` for + inverted matching criteria is also supportd. For example ``!IFACE_GROUP`` + +.. cfgcmd:: set firewall bridge forward filter rule <1-999999> + outbound-interface name +.. cfgcmd:: set firewall bridge name rule <1-999999> + outbound-interface name + + Match based on outbound interface. Wilcard ``*`` can be used. + For example: ``eth2*``. Prepending character ``!`` for inverted matching + criteria is also supportd. For example ``!eth2`` + +.. cfgcmd:: set firewall bridge forward filter rule <1-999999> + outbound-interface group +.. cfgcmd:: set firewall bridge name rule <1-999999> + outbound-interface group + + Match based on outbound interface group. Prepending character ``!`` for + inverted matching criteria is also supportd. For example ``!IFACE_GROUP`` + +.. cfgcmd:: set firewall bridge forward filter rule <1-999999> + vlan id <0-4096> +.. cfgcmd:: set firewall bridge name rule <1-999999> + vlan id <0-4096> + + Match based on vlan ID. Range is also supported. + +.. cfgcmd:: set firewall bridge forward filter rule <1-999999> + vlan priority <0-7> +.. cfgcmd:: set firewall bridge name rule <1-999999> + vlan priority <0-7> + + Match based on vlan priority(pcp). Range is also supported. + +*********************** +Operation-mode Firewall +*********************** + +Rule-set overview +================= + +In this section you can find all useful firewall op-mode commands. + +General commands for firewall configuration, counter and statiscits: + +.. opcmd:: show firewall +.. opcmd:: show firewall summary +.. opcmd:: show firewall statistics + +And, to print only bridge firewall information: + +.. opcmd:: show firewall bridge +.. opcmd:: show firewall bridge forward filter +.. opcmd:: show firewall bridge forward filter rule +.. opcmd:: show firewall bridge name +.. opcmd:: show firewall bridge name rule + +Show Firewall log +================= + +.. opcmd:: show log firewall +.. opcmd:: show log firewall bridge +.. opcmd:: show log firewall bridge forward +.. opcmd:: show log firewall bridge forward filter +.. opcmd:: show log firewall bridge name +.. opcmd:: show log firewall bridge forward filter rule +.. opcmd:: show log firewall bridge name rule + + Show the logs of all firewall; show all bridge firewall logs; show all logs + for forward hook; show all logs for forward hook and priority filter; show + all logs for particular custom chain; show logs for specific Rule-Set. + +Example +======= + +Configuration example: + +.. code-block:: none + + set firewall bridge forward filter default-action 'drop' + set firewall bridge forward filter enable-default-log + set firewall bridge forward filter rule 10 action 'continue' + set firewall bridge forward filter rule 10 inbound-interface name 'eth2' + set firewall bridge forward filter rule 10 vlan id '22' + set firewall bridge forward filter rule 20 action 'drop' + set firewall bridge forward filter rule 20 inbound-interface group 'TRUNK-RIGHT' + set firewall bridge forward filter rule 20 vlan id '60' + set firewall bridge forward filter rule 30 action 'jump' + set firewall bridge forward filter rule 30 jump-target 'TEST' + set firewall bridge forward filter rule 30 outbound-interface name '!eth1' + set firewall bridge forward filter rule 35 action 'accept' + set firewall bridge forward filter rule 35 vlan id '11' + set firewall bridge forward filter rule 40 action 'continue' + set firewall bridge forward filter rule 40 destination mac-address '66:55:44:33:22:11' + set firewall bridge forward filter rule 40 source mac-address '11:22:33:44:55:66' + set firewall bridge name TEST default-action 'accept' + set firewall bridge name TEST enable-default-log + set firewall bridge name TEST rule 10 action 'continue' + set firewall bridge name TEST rule 10 log + set firewall bridge name TEST rule 10 vlan priority '0' + +And op-mode commands: + +.. code-block:: none + + vyos@BRI:~$ show firewall bridge + Rulesets bridge Information + + --------------------------------- + bridge Firewall "forward filter" + + Rule Action Protocol Packets Bytes Conditions + ------- -------- ---------- --------- ------- --------------------------------------------------------------------- + 10 continue all 0 0 iifname "eth2" vlan id 22 continue + 20 drop all 0 0 iifname @I_TRUNK-RIGHT vlan id 60 + 30 jump all 2130 170688 oifname != "eth1" jump NAME_TEST + 35 accept all 2080 168616 vlan id 11 accept + 40 continue all 0 0 ether daddr 66:55:44:33:22:11 ether saddr 11:22:33:44:55:66 continue + default drop all 0 0 + + --------------------------------- + bridge Firewall "name TEST" + + Rule Action Protocol Packets Bytes Conditions + ------- -------- ---------- --------- ------- -------------------------------------------------- + 10 continue all 2130 170688 vlan pcp 0 prefix "[bri-NAM-TEST-10-C]" continue + default accept all 2130 170688 + + vyos@BRI:~$ + vyos@BRI:~$ show firewall bridge name TEST + Ruleset Information + + --------------------------------- + bridge Firewall "name TEST" + + Rule Action Protocol Packets Bytes Conditions + ------- -------- ---------- --------- ------- -------------------------------------------------- + 10 continue all 2130 170688 vlan pcp 0 prefix "[bri-NAM-TEST-10-C]" continue + default accept all 2130 170688 + + vyos@BRI:~$ + +Inspect logs: + +.. code-block:: none + + vyos@BRI:~$ show log firewall bridge + Dec 05 14:37:47 kernel: [bri-NAM-TEST-10-C]IN=eth1 OUT=eth2 ARP HTYPE=1 PTYPE=0x0800 OPCODE=1 MACSRC=50:00:00:04:00:00 IPSRC=10.11.11.101 MACDST=00:00:00:00:00:00 IPDST=10.11.11.102 + Dec 05 14:37:48 kernel: [bri-NAM-TEST-10-C]IN=eth1 OUT=eth2 ARP HTYPE=1 PTYPE=0x0800 OPCODE=1 MACSRC=50:00:00:04:00:00 IPSRC=10.11.11.101 MACDST=00:00:00:00:00:00 IPDST=10.11.11.102 + Dec 05 14:37:49 kernel: [bri-NAM-TEST-10-C]IN=eth1 OUT=eth2 ARP HTYPE=1 PTYPE=0x0800 OPCODE=1 MACSRC=50:00:00:04:00:00 IPSRC=10.11.11.101 MACDST=00:00:00:00:00:00 IPDST=10.11.11.102 + ... + vyos@BRI:~$ show log firewall bridge forward filter + Dec 05 14:42:22 kernel: [bri-FWD-filter-default-D]IN=eth2 OUT=eth1 MAC=33:33:00:00:00:16:50:00:00:06:00:00:86:dd SRC=0000:0000:0000:0000:0000:0000:0000:0000 DST=ff02:0000:0000:0000:0000:0000:0000:0016 LEN=96 TC=0 HOPLIMIT=1 FLOWLBL=0 PROTO=ICMPv6 TYPE=143 CODE=0 + Dec 05 14:42:22 kernel: [bri-FWD-filter-default-D]IN=eth2 OUT=eth1 MAC=33:33:00:00:00:16:50:00:00:06:00:00:86:dd SRC=0000:0000:0000:0000:0000:0000:0000:0000 DST=ff02:0000:0000:0000:0000:0000:0000:0016 LEN=96 TC=0 HOPLIMIT=1 FLOWLBL=0 PROTO=ICMPv6 TYPE=143 CODE=0 diff --git a/docs/configuration/firewall/ipv4.rst b/docs/configuration/firewall/ipv4.rst index 3fd365e1..9a683d22 100644 --- a/docs/configuration/firewall/ipv4.rst +++ b/docs/configuration/firewall/ipv4.rst @@ -123,9 +123,46 @@ The action can be : .. cfgcmd:: set firewall ipv4 name rule <1-999999> jump-target - To be used only when action is set to jump. Use this command to specify + To be used only when action is set to ``jump``. Use this command to specify jump target. +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + queue <0-65535> +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + queue <0-65535> +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + queue <0-65535> +.. cfgcmd:: set firewall ipv4 name rule <1-999999> + queue <0-65535> + + To be used only when action is set to ``queue``. Use this command to specify + queue target to use. Queue range is also supported. + +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + queue-options bypass +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + queue-options bypass +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + queue-options bypass +.. cfgcmd:: set firewall ipv4 name rule <1-999999> + queue-options bypass + + To be used only when action is set to ``queue``. Use this command to let + packet go through firewall when no userspace software is connected to the + queue. + +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + queue-options fanout +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + queue-options fanout +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + queue-options fanout +.. cfgcmd:: set firewall ipv4 name rule <1-999999> + queue-options fanout + + To be used only when action is set to ``queue``. Use this command to + distribute packets between several queues. + Also, **default-action** is an action that takes place whenever a packet does not match any rule in it's chain. For base chains, possible options for **default-action** are **accept** or **drop**. @@ -140,7 +177,7 @@ not match any rule in it's chain. For base chains, possible options for [accept | drop | jump | queue | reject | return] This set the default action of the rule-set if no rule matched a packet - criteria. If defacult-action is set to ``jump``, then + criteria. If default-action is set to ``jump``, then ``default-jump-target`` is also needed. Note that for base chains, default action can only be set to ``accept`` or ``drop``, while on custom chain, more actions are available. @@ -153,7 +190,7 @@ not match any rule in it's chain. For base chains, possible options for .. note:: **Important note about default-actions:** If default action for any base chain is not defined, then the default action is set to **accept** for that chain. For custom chains, if default - action is not defined, then the default-action is set to **drop** + action is not defined, then the default-action is set to **drop**. Firewall Logs ============= @@ -162,15 +199,12 @@ Logging can be enable for every single firewall rule. If enabled, other log options can be defined. .. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> log - [disable | enable] .. cfgcmd:: set firewall ipv4 input filter rule <1-999999> log - [disable | enable] .. cfgcmd:: set firewall ipv4 output filter rule <1-999999> log - [disable | enable] .. cfgcmd:: set firewall ipv4 name rule <1-999999> log - [disable | enable] - Enable or disable logging for the matched packet. + Enable logging for the matched packet. If this configuration command is not + present, then log is not enabled. .. cfgcmd:: set firewall ipv4 forward filter enable-default-log .. cfgcmd:: set firewall ipv4 input filter enable-default-log @@ -266,7 +300,7 @@ just disable the rule, rather than removing it. Matching criteria ================= -There are a lot of matching criteria against which the package can be tested. +There are a lot of matching criteria against which the packet can be tested. .. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> connection-status nat [destination | source] diff --git a/docs/configuration/firewall/ipv6.rst b/docs/configuration/firewall/ipv6.rst index 83a5f694..0aa8a137 100644 --- a/docs/configuration/firewall/ipv6.rst +++ b/docs/configuration/firewall/ipv6.rst @@ -123,9 +123,46 @@ The action can be : .. cfgcmd:: set firewall ipv6 name rule <1-999999> jump-target - To be used only when action is set to jump. Use this command to specify + To be used only when action is set to ``jump``. Use this command to specify jump target. +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + queue <0-65535> +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + queue <0-65535> +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + queue <0-65535> +.. cfgcmd:: set firewall ipv6 name rule <1-999999> + queue <0-65535> + + To be used only when action is set to ``queue``. Use this command to specify + queue target to use. Queue range is also supported. + +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + queue-options bypass +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + queue-options bypass +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + queue-options bypass +.. cfgcmd:: set firewall ipv6 name rule <1-999999> + queue-options bypass + + To be used only when action is set to ``queue``. Use this command to let + packet go through firewall when no userspace software is connected to the + queue. + +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + queue-options fanout +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + queue-options fanout +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + queue-options fanout +.. cfgcmd:: set firewall ipv6 name rule <1-999999> + queue-options fanout + + To be used only when action is set to ``queue``. Use this command to + distribute packets between several queues. + Also, **default-action** is an action that takes place whenever a packet does not match any rule in it's chain. For base chains, possible options for **default-action** are **accept** or **drop**. @@ -140,7 +177,7 @@ not match any rule in it's chain. For base chains, possible options for [accept | drop | jump | queue | reject | return] This set the default action of the rule-set if no rule matched a packet - criteria. If defacult-action is set to ``jump``, then + criteria. If default-action is set to ``jump``, then ``default-jump-target`` is also needed. Note that for base chains, default action can only be set to ``accept`` or ``drop``, while on custom chain, more actions are available. @@ -153,7 +190,7 @@ not match any rule in it's chain. For base chains, possible options for .. note:: **Important note about default-actions:** If default action for any base chain is not defined, then the default action is set to **accept** for that chain. For custom chains, if default - action is not defined, then the default-action is set to **drop** + action is not defined, then the default-action is set to **drop**. Firewall Logs ============= @@ -162,15 +199,12 @@ Logging can be enable for every single firewall rule. If enabled, other log options can be defined. .. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> log - [disable | enable] .. cfgcmd:: set firewall ipv6 input filter rule <1-999999> log - [disable | enable] .. cfgcmd:: set firewall ipv6 output filter rule <1-999999> log - [disable | enable] .. cfgcmd:: set firewall ipv6 name rule <1-999999> log - [disable | enable] - Enable or disable logging for the matched packet. + Enable logging for the matched packet. If this configuration command is not + present, then log is not enabled. .. cfgcmd:: set firewall ipv6 forward filter enable-default-log .. cfgcmd:: set firewall ipv6 input filter enable-default-log @@ -266,7 +300,7 @@ just disable the rule, rather than removing it. Matching criteria ================= -There are a lot of matching criteria against which the package can be tested. +There are a lot of matching criteria against which the packet can be tested. .. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> connection-status nat [destination | source] @@ -936,7 +970,7 @@ Rule-set overview .. code-block:: none - vyos@vyos:~$ show firewall + vyos@vyos:~$ show firewall Rulesets Information --------------------------------- @@ -999,7 +1033,7 @@ Rule-set overview .. code-block:: none - vyos@vyos:~$ show firewall summary + vyos@vyos:~$ show firewall summary Ruleset Summary IPv6 Ruleset: @@ -1049,29 +1083,30 @@ Rule-set overview .. opcmd:: show firewall ipv6 [forward | input | output] filter -.. opcmd:: show firewall ipv4 name - .. opcmd:: show firewall ipv6 ipv6-name This command will give an overview of a single rule-set. .. code-block:: none - vyos@vyos:~$ show firewall ipv4 input filter + vyos@vyos:~$ show firewall ipv6 input filter Ruleset Information --------------------------------- - IPv4 Firewall "input filter" + ipv6 Firewall "input filter" Rule Action Protocol Packets Bytes Conditions - ------- -------- ---------- --------- ------- ----------------------------------------- - 5 jump all 0 0 iifname "eth2" jump NAME_VyOS_MANAGEMENT - default accept all + ------- -------- ---------- --------- ------- ------------------------------------------------------------------------------ + 10 jump all 13 1456 iifname "eth1" jump NAME6_INP-ETH1 + 20 accept ipv6-icmp 10 1112 meta l4proto ipv6-icmp iifname "eth0" prefix "[ipv6-INP-filter-20-A]" accept + default accept all 14 1584 + + vyos@vyos:~$ .. opcmd:: show firewall ipv6 [forward | input | output] filter rule <1-999999> -.. opcmd:: show firewall ipv4 name rule <1-999999> +.. opcmd:: show firewall ipv6 name rule <1-999999> .. opcmd:: show firewall ipv6 ipv6-name rule <1-999999> @@ -1084,7 +1119,7 @@ Rule-set overview .. code-block:: none - vyos@vyos:~$ show firewall group LAN + vyos@vyos:~$ show firewall group LAN Firewall Groups Name Type References Members @@ -1119,45 +1154,38 @@ Example Partial Config .. code-block:: none - firewall { - group { - network-group BAD-NETWORKS { - network 198.51.100.0/24 - network 203.0.113.0/24 - } - network-group GOOD-NETWORKS { - network 192.0.2.0/24 - } - port-group BAD-PORTS { - port 65535 - } - } - ipv4 { - forward { - filter { - default-action accept - rule 5 { - action accept - source { - group { - network-group GOOD-NETWORKS + firewall { + ipv6 { + input { + filter { + rule 10 { + action jump + inbound-interface { + name eth1 } + jump-target INP-ETH1 } - } - rule 10 { - action drop - description "Bad Networks" - protocol all - source { - group { - network-group BAD-NETWORKS + rule 20 { + action accept + inbound-interface { + name eth0 } + log + protocol ipv6-icmp } } } + name INP-ETH1 { + default-action drop + enable-default-log + rule 10 { + action accept + protocol tcp_udp + } + } } } - } + Update geoip database ===================== -- cgit v1.2.3 From 0c5e77aea59cbb50af527c59770584d232c97f52 Mon Sep 17 00:00:00 2001 From: Nicolas Fort Date: Tue, 26 Dec 2023 08:55:02 -0300 Subject: Add configuration commands and brief example of firewall Flowtables. Also re-add commands for firewall state policies, which now can eb found under section --- docs/configuration/firewall/flowtables.rst | 140 ++++++++++++++++++++++++- docs/configuration/firewall/global-options.rst | 34 +++++- 2 files changed, 170 insertions(+), 4 deletions(-) (limited to 'docs/configuration/firewall') diff --git a/docs/configuration/firewall/flowtables.rst b/docs/configuration/firewall/flowtables.rst index 8b44a9b9..bc7b9212 100644 --- a/docs/configuration/firewall/flowtables.rst +++ b/docs/configuration/firewall/flowtables.rst @@ -1,4 +1,4 @@ -:lastproofread: 2023-11-08 +:lastproofread: 2023-12-26 .. _firewall-flowtables-configuration: @@ -13,7 +13,7 @@ Overview ******** In this section there's useful information of all firewall configuration that -can be done regarding flowtables +can be done regarding flowtables. .. cfgcmd:: set firewall flowtables ... @@ -50,3 +50,139 @@ flowtable (flowtable miss), the packet follows the classic IP forwarding path. .. note:: **Flowtable Reference:** https://docs.kernel.org/networking/nf_flowtable.html + + +*********************** +Flowtable Configuration +*********************** + +In order to use flowtables, the minimal configuration needed includes: + + * Create flowtable: create flowtable, which includes the interfaces + that are going to be used by the flowtable. + + * Create firewall rule: create a firewall rule, setting action to + ``offload`` and using desired flowtable for ``offload-target``. + +Creating a flow table: + +.. cfgcmd:: set firewall flowtable interface + + Define interfaces to be used in the flowtable. + +.. cfgcmd:: set firewall flowtable description + +Provide a description to the flow table. + +.. cfgcmd:: set firewall flowtable offload + + + Define type of offload to be used by the flowtable: ``hardware`` or + ``software``. By default, ``software`` offload is used. + +.. note:: **Hardware offload:** should be supported by the NICs used. + +Creating rules for using flow tables: + +.. cfgcmd:: set firewall [ipv4 | ipv4] forward filter rule <1-999999> + action offload + + Create firewall rule in forward chain, and set action to ``offload``. + +.. cfgcmd:: set firewall [ipv4 | ipv4] forward filter rule <1-999999> + offload-target + + Create firewall rule in forward chain, and define which flowtbale + should be used. Only applicable if action is ``offload``. + +********************* +Configuration Example +********************* + +Things to be considred in this setup: + + * Two interfaces are going to be used in the flowtables: eth0 and eth1 + + * Minumum firewall ruleset is provided, which includes some filtering rules, + and appropiate rules for using flowtable offload capabilities. + +As described, first packet will be evaluated by all the firewall path, so +desired connection should be explicitely accepted. Same thing should be taken +into account for traffic in reverse order. In most cases state policies are +used in order to accept connection in reverse patch. + +We will only accept traffic comming from interface eth0, protocol tcp and +destination port 1122. All other traffic traspassing the router should be +blocked. + +Commands +-------- + +.. code-block:: none + + set firewall flowtable FT01 interface 'eth0' + set firewall flowtable FT01 interface 'eth1' + set firewall ipv4 forward filter default-action 'drop' + set firewall ipv4 forward filter rule 10 action 'offload' + set firewall ipv4 forward filter rule 10 offload-target 'FT01' + set firewall ipv4 forward filter rule 10 state 'established' + set firewall ipv4 forward filter rule 10 state 'related' + set firewall ipv4 forward filter rule 20 action 'accept' + set firewall ipv4 forward filter rule 20 state 'established' + set firewall ipv4 forward filter rule 20 state 'related' + set firewall ipv4 forward filter rule 110 action 'accept' + set firewall ipv4 forward filter rule 110 destination address '192.0.2.100' + set firewall ipv4 forward filter rule 110 destination port '1122' + set firewall ipv4 forward filter rule 110 inbound-interface name 'eth0' + set firewall ipv4 forward filter rule 110 protocol 'tcp' + +Explanation +----------- + +Analysis on what happens for desired connection: + + 1. First packet is received on eht0, with destination address 192.0.2.100, + protocol tcp and destination port 1122. Assume such destination address is + reachable through interface eth1. + + 2. Since this is the first packet, connection status of this connection, + so far is **new**. So neither rule 10 nor 20 are valid. + + 3. Rule 110 is hit, so connection is accepted. + + 4. Once answer from server 192.0.2.100 is seen in opposite direction, + connection state will be triggered to **established**, so this reply is + accepted in rule 10. + + 5. Second packet for this connection is received by the router. Since + connection state is **established**, then rule 10 is hit, and a new entry + in the flowtable FT01 is added for this connection. + + 6. All subsecuent packets will skip traditional path, and will be offloaded + and will use the **Fast Path**. + +Checks +------ + +It's time to check conntrack table, to see if any connection was accepted, +and if was properly offloaded + +.. code-block:: none + + vyos@FlowTables:~$ show firewall ipv4 forward filter + Ruleset Information + + --------------------------------- + ipv4 Firewall "forward filter" + + Rule Action Protocol Packets Bytes Conditions + ------- -------- ---------- --------- ------- ---------------------------------------------------------------- + 10 offload all 8 468 ct state { established, related } flow add @VYOS_FLOWTABLE_FT01 + 20 accept all 8 468 ct state { established, related } accept + 110 accept tcp 2 120 ip daddr 192.0.2.100 tcp dport 1122 iifname "eth0" accept + default drop all 7 420 + + vyos@FlowTables:~$ sudo conntrack -L | grep tcp + conntrack v1.4.6 (conntrack-tools): 5 flow entries have been shown. + tcp 6 src=198.51.100.100 dst=192.0.2.100 sport=41676 dport=1122 src=192.0.2.100 dst=198.51.100.100 sport=1122 dport=41676 [OFFLOAD] mark=0 use=2 + vyos@FlowTables:~$ diff --git a/docs/configuration/firewall/global-options.rst b/docs/configuration/firewall/global-options.rst index 316e0802..455e530b 100644 --- a/docs/configuration/firewall/global-options.rst +++ b/docs/configuration/firewall/global-options.rst @@ -1,4 +1,4 @@ -:lastproofread: 2023-11-07 +:lastproofread: 2023-12-026 .. _firewall-global-options-configuration: @@ -114,4 +114,34 @@ Configuration Enable or Disable VyOS to be :rfc:`1337` conform. The following system parameter will be altered: - * ``net.ipv4.tcp_rfc1337`` \ No newline at end of file + * ``net.ipv4.tcp_rfc1337`` + +.. cfgcmd:: set firewall global-options state-policy established action + [accept | drop | reject] + +.. cfgcmd:: set firewall global-options state-policy established log + +.. cfgcmd:: set firewall global-options state-policy established log-level + [emerg | alert | crit | err | warn | notice | info | debug] + + Set the global setting for an established connection. + +.. cfgcmd:: set firewall global-options state-policy invalid action + [accept | drop | reject] + +.. cfgcmd:: set firewall global-options state-policy invalid log + +.. cfgcmd:: set firewall global-options state-policy invalid log-level + [emerg | alert | crit | err | warn | notice | info | debug] + + Set the global setting for invalid packets. + +.. cfgcmd:: set firewall global-options state-policy related action + [accept | drop | reject] + +.. cfgcmd:: set firewall global-options state-policy related log + +.. cfgcmd:: set firewall global-options state-policy related log-level + [emerg | alert | crit | err | warn | notice | info | debug] + + Set the global setting for related connections. -- cgit v1.2.3 From 0893ca769b1796d2d61dc26a0c0c13d1eda56f5e Mon Sep 17 00:00:00 2001 From: Nicolas Fort Date: Wed, 27 Dec 2023 06:52:57 -0300 Subject: dhcp-server: update docs for op-mode command --- docs/configuration/firewall/global-options.rst | 2 +- docs/configuration/service/dhcp-server.rst | 34 ++++++++++++++++++++++---- 2 files changed, 30 insertions(+), 6 deletions(-) (limited to 'docs/configuration/firewall') diff --git a/docs/configuration/firewall/global-options.rst b/docs/configuration/firewall/global-options.rst index 455e530b..b3f311aa 100644 --- a/docs/configuration/firewall/global-options.rst +++ b/docs/configuration/firewall/global-options.rst @@ -1,4 +1,4 @@ -:lastproofread: 2023-12-026 +:lastproofread: 2023-12-26 .. _firewall-global-options-configuration: diff --git a/docs/configuration/service/dhcp-server.rst b/docs/configuration/service/dhcp-server.rst index b5b12a5b..0cc10feb 100644 --- a/docs/configuration/service/dhcp-server.rst +++ b/docs/configuration/service/dhcp-server.rst @@ -549,18 +549,43 @@ Operation Mode .. code-block:: none vyos@vyos:~$ show dhcp server leases - IP address Hardware address State Lease start Lease expiration Remaining Pool Hostname - -------------- ------------------ ------- ------------------- ------------------- ---------- ----------- --------- - 192.0.2.104 00:53:01:dd:ee:ff active 2019/12/05 14:24:23 2019/12/06 02:24:23 6:05:35 dhcpexample test1 - 192.0.2.115 00:53:01:ae:af:bf active 2019/12/05 18:02:37 2019/12/06 06:02:37 9:43:49 dhcpexample test2 + IP Address MAC address State Lease start Lease expiration Remaining Pool Hostname Origin + -------------- ----------------- ------- ------------------- ------------------- ----------- -------- ---------- -------- + 192.168.11.134 00:50:79:66:68:09 active 2023/11/29 09:51:05 2023/11/29 10:21:05 0:24:10 LAN VPCS1 local + 192.168.11.133 50:00:00:06:00:00 active 2023/11/29 09:51:38 2023/11/29 10:21:38 0:24:43 LAN VYOS-6 local + 10.11.11.108 50:00:00:05:00:00 active 2023/11/29 09:51:43 2023/11/29 10:21:43 0:24:48 VIF-1001 VYOS5 local + 192.168.11.135 00:50:79:66:68:07 active 2023/11/29 09:55:16 2023/11/29 09:59:16 0:02:21 remote + vyos@vyos:~$ .. hint:: Static mappings aren't shown. To show all states, use ``show dhcp server leases state all``. +.. opcmd:: show dhcp server leases origin [local | remote] + + Show statuses of all active leases granted by local (this server) or + remote (failover server): + +.. code-block:: none + + vyos@vyos:~$ show dhcp server leases origin remote + IP Address MAC address State Lease start Lease expiration Remaining Pool Hostname Origin + -------------- ----------------- ------- ------------------- ------------------- ----------- -------- ---------- -------- + 192.168.11.135 00:50:79:66:68:07 active 2023/11/29 09:55:16 2023/11/29 09:59:16 0:02:21 remote + vyos@vyos:~$ + .. opcmd:: show dhcp server leases pool Show only leases in the specified pool. +.. code-block:: none + + vyos@vyos:~$ show dhcp server leases pool LAN + IP Address MAC address State Lease start Lease expiration Remaining Pool Hostname Origin + -------------- ----------------- ------- ------------------- ------------------- ----------- ------ ---------- -------- + 192.168.11.134 00:50:79:66:68:09 active 2023/11/29 09:51:05 2023/11/29 10:21:05 0:23:55 LAN VPCS1 local + 192.168.11.133 50:00:00:06:00:00 active 2023/11/29 09:51:38 2023/11/29 10:21:38 0:24:28 LAN VYOS-6 local + vyos@vyos:~$ + .. opcmd:: show dhcp server leases sort Sort the output by the specified key. Possible keys: ip, hardware_address, @@ -572,7 +597,6 @@ Operation Mode free, expired, released, abandoned, reset, backup (default = active) - *********** IPv6 server *********** -- cgit v1.2.3 From e39d7d8990dd0f107b328258ecf67e3e4a1b179e Mon Sep 17 00:00:00 2001 From: Giggum <152240782+Giggum@users.noreply.github.com> Date: Fri, 5 Jan 2024 00:29:03 -0500 Subject: docs: fix to improve readability and correct typos. --- docs/configuration/firewall/index.rst | 40 +++++++++++++++++------------------ 1 file changed, 20 insertions(+), 20 deletions(-) (limited to 'docs/configuration/firewall') diff --git a/docs/configuration/firewall/index.rst b/docs/configuration/firewall/index.rst index 3887e26a..bdfc2069 100644 --- a/docs/configuration/firewall/index.rst +++ b/docs/configuration/firewall/index.rst @@ -5,30 +5,30 @@ Firewall ######## With VyOS being based on top of Linux and its kernel, the Netfilter project -created the iptables and now the successor nftables for the Linux kernel to +created iptables and its successor nftables for the Linux kernel to work directly on the data flows. This now extends the concept of zone-based security to allow for manipulating the data at multiple stages once accepted by the network interface and the driver before being handed off to the -destination (e.g. a web server OR another device). +destination (e.g., a web server OR another device). -A simplified traffic flow, based on Netfilter packet flow, is shown next, in +A simplified traffic flow diagram, based on Netfilter packet flow, is shown next, in order to have a full view and understanding of how packets are processed, and -what possible paths can take. +what possible paths traffic can take. .. figure:: /_static/images/firewall-gral-packet-flow.png -Main notes regarding this packet flow and terminology used in VyOS firewall: +Main points regarding this packet flow and terminology used in VyOS firewall are below: - * **Bridge Port?**: choose appropiate path based on if interface were the + * **Bridge Port?**: choose appropriate path based on whether interface where the packet was received is part of a bridge, or not. -If interface were the packet was received isn't part of a bridge, then packet +If interface where the packet was received isn't part of a bridge, then packet is processed at the **IP Layer**: * **Prerouting**: several actions can be done in this stage, and currently - these actions are defined in different parts in vyos configuration. Order + these actions are defined in different parts in VyOS configuration. Order is important, and all these actions are performed before any actions - define under ``firewall`` section. Relevant configuration that acts in + defined under ``firewall`` section. Relevant configuration that acts in this stage are: * **Conntrack Ignore**: rules defined under ``set system conntrack ignore @@ -40,12 +40,12 @@ is processed at the **IP Layer**: * **Destination NAT**: rules defined under ``set [nat | nat66] destination...``. - * **Destination is the router?**: choose appropiate path based on - destination IP address. Transit forward continunes to **forward**, + * **Destination is the router?**: choose appropriate path based on + destination IP address. Transit forward continues to **forward**, while traffic that destination IP address is configured on the router continues to **input**. - * **Input**: stage where traffic destinated to the router itself can be + * **Input**: stage where traffic destined for the router itself can be filtered and controlled. This is where all rules for securing the router should take place. This includes ipv4 and ipv6 filtering rules, defined in: @@ -61,10 +61,10 @@ is processed at the **IP Layer**: * ``set firewall ipv6 forward filter ...``. - * **Output**: stage where traffic that is originated by the router itself - can be filtered and controlled. Bare in mind that this traffic can be a - new connection originted by a internal process running on VyOS router, - such as NTP, or can be a response to traffic received externaly through + * **Output**: stage where traffic that originates from the router itself + can be filtered and controlled. Bear in mind that this traffic can be a + new connection originated by a internal process running on VyOS router, + such as NTP, or a response to traffic received externaly through **inputt** (for example response to an ssh login attempt to the router). This includes ipv4 and ipv6 filtering rules, defined in: @@ -79,11 +79,11 @@ is processed at the **IP Layer**: * **Source NAT**: rules defined under ``set [nat | nat66] destination...``. -If interface were the packet was received is part of a bridge, then packet -is processed at the **Bridge Layer**, which contains a ver basic setup where -for bridge filtering: +If interface where the packet was received is part of a bridge, then packet +is processed at the **Bridge Layer**, which contains a basic setup for +bridge filtering: - * **Forward (Bridge)**: stage where traffic that is trasspasing through the + * **Forward (Bridge)**: stage where traffic that is trespasing through the bridge is filtered and controlled: * ``set firewall bridge forward filter ...``. -- cgit v1.2.3 From 7132481c92e169348ac3f6750be8ce45c2f2b5dd Mon Sep 17 00:00:00 2001 From: Giggum <152240782+Giggum@users.noreply.github.com> Date: Fri, 5 Jan 2024 22:40:42 -0500 Subject: fix to add more fixes on top of previous pull request --- docs/configuration/firewall/index.rst | 35 +++---- docs/configuration/firewall/index.rst~ | 179 +++++++++++++++++++++++++++++++++ 2 files changed, 197 insertions(+), 17 deletions(-) create mode 100644 docs/configuration/firewall/index.rst~ (limited to 'docs/configuration/firewall') diff --git a/docs/configuration/firewall/index.rst b/docs/configuration/firewall/index.rst index bdfc2069..74d5bc20 100644 --- a/docs/configuration/firewall/index.rst +++ b/docs/configuration/firewall/index.rst @@ -4,26 +4,27 @@ Firewall ######## -With VyOS being based on top of Linux and its kernel, the Netfilter project +As VyOS is based on Linux it leverages its firewall. The Netfilter project created iptables and its successor nftables for the Linux kernel to -work directly on the data flows. This now extends the concept of zone-based -security to allow for manipulating the data at multiple stages once accepted -by the network interface and the driver before being handed off to the -destination (e.g., a web server OR another device). +work directly on packet data flows. This now extends the concept of +zone-based security to allow for manipulating the data at multiple stages once +accepted by the network interface and the driver before being handed off to +the destination (e.g., a web server OR another device). -A simplified traffic flow diagram, based on Netfilter packet flow, is shown next, in -order to have a full view and understanding of how packets are processed, and -what possible paths traffic can take. +A simplified traffic flow diagram, based on Netfilter packet flow, is shown +next, in order to have a full view and understanding of how packets are +processed, and what possible paths traffic can take. .. figure:: /_static/images/firewall-gral-packet-flow.png -Main points regarding this packet flow and terminology used in VyOS firewall are below: +The main points regarding this packet flow and terminology used in VyOS +firewall are covered below: - * **Bridge Port?**: choose appropriate path based on whether interface where the - packet was received is part of a bridge, or not. + * **Bridge Port?**: choose appropriate path based on whether interface + where the packet was received is part of a bridge, or not. -If interface where the packet was received isn't part of a bridge, then packet -is processed at the **IP Layer**: +If the interface where the packet was received isn't part of a bridge, then +packetis processed at the **IP Layer**: * **Prerouting**: several actions can be done in this stage, and currently these actions are defined in different parts in VyOS configuration. Order @@ -79,8 +80,8 @@ is processed at the **IP Layer**: * **Source NAT**: rules defined under ``set [nat | nat66] destination...``. -If interface where the packet was received is part of a bridge, then packet -is processed at the **Bridge Layer**, which contains a basic setup for +If the interface where the packet was received is part of a bridge, then +packetis processed at the **Bridge Layer**, which contains a basic setup for bridge filtering: * **Forward (Bridge)**: stage where traffic that is trespasing through the @@ -88,7 +89,7 @@ bridge filtering: * ``set firewall bridge forward filter ...``. -Main structure VyOS firewall cli is shown next: +The main structure VyOS firewall cli is shown next: .. code-block:: none @@ -134,7 +135,7 @@ Main structure VyOS firewall cli is shown next: - custom_zone_name + ... -Please, refer to appropiate section for more information about firewall +Please, refer to appropriate section for more information about firewall configuration: .. toctree:: diff --git a/docs/configuration/firewall/index.rst~ b/docs/configuration/firewall/index.rst~ new file mode 100644 index 00000000..bdfc2069 --- /dev/null +++ b/docs/configuration/firewall/index.rst~ @@ -0,0 +1,179 @@ +:lastproofread: 2023-11-23 + +######## +Firewall +######## + +With VyOS being based on top of Linux and its kernel, the Netfilter project +created iptables and its successor nftables for the Linux kernel to +work directly on the data flows. This now extends the concept of zone-based +security to allow for manipulating the data at multiple stages once accepted +by the network interface and the driver before being handed off to the +destination (e.g., a web server OR another device). + +A simplified traffic flow diagram, based on Netfilter packet flow, is shown next, in +order to have a full view and understanding of how packets are processed, and +what possible paths traffic can take. + +.. figure:: /_static/images/firewall-gral-packet-flow.png + +Main points regarding this packet flow and terminology used in VyOS firewall are below: + + * **Bridge Port?**: choose appropriate path based on whether interface where the + packet was received is part of a bridge, or not. + +If interface where the packet was received isn't part of a bridge, then packet +is processed at the **IP Layer**: + + * **Prerouting**: several actions can be done in this stage, and currently + these actions are defined in different parts in VyOS configuration. Order + is important, and all these actions are performed before any actions + defined under ``firewall`` section. Relevant configuration that acts in + this stage are: + + * **Conntrack Ignore**: rules defined under ``set system conntrack ignore + [ipv4 | ipv6] ...``. + + * **Policy Route**: rules defined under ``set policy [route | route6] + ...``. + + * **Destination NAT**: rules defined under ``set [nat | nat66] + destination...``. + + * **Destination is the router?**: choose appropriate path based on + destination IP address. Transit forward continues to **forward**, + while traffic that destination IP address is configured on the router + continues to **input**. + + * **Input**: stage where traffic destined for the router itself can be + filtered and controlled. This is where all rules for securing the router + should take place. This includes ipv4 and ipv6 filtering rules, defined + in: + + * ``set firewall ipv4 input filter ...``. + + * ``set firewall ipv6 input filter ...``. + + * **Forward**: stage where transit traffic can be filtered and controlled. + This includes ipv4 and ipv6 filtering rules, defined in: + + * ``set firewall ipv4 forward filter ...``. + + * ``set firewall ipv6 forward filter ...``. + + * **Output**: stage where traffic that originates from the router itself + can be filtered and controlled. Bear in mind that this traffic can be a + new connection originated by a internal process running on VyOS router, + such as NTP, or a response to traffic received externaly through + **inputt** (for example response to an ssh login attempt to the router). + This includes ipv4 and ipv6 filtering rules, defined in: + + * ``set firewall ipv4 input filter ...``. + + * ``set firewall ipv6 output filter ...``. + + * **Postrouting**: as in **Prerouting**, several actions defined in + different parts of VyOS configuration are performed in this + stage. This includes: + + * **Source NAT**: rules defined under ``set [nat | nat66] + destination...``. + +If interface where the packet was received is part of a bridge, then packet +is processed at the **Bridge Layer**, which contains a basic setup for +bridge filtering: + + * **Forward (Bridge)**: stage where traffic that is trespasing through the + bridge is filtered and controlled: + + * ``set firewall bridge forward filter ...``. + +Main structure VyOS firewall cli is shown next: + +.. code-block:: none + + - set firewall + * bridge + - forward + + filter + * flowtable + - custom_flow_table + + ... + * global-options + + all-ping + + broadcast-ping + + ... + * group + - address-group + - ipv6-address-group + - network-group + - ipv6-network-group + - interface-group + - mac-group + - port-group + - domain-group + * ipv4 + - forward + + filter + - input + + filter + - output + + filter + - name + + custom_name + * ipv6 + - forward + + filter + - input + + filter + - output + + filter + - ipv6-name + + custom_name + * zone + - custom_zone_name + + ... + +Please, refer to appropiate section for more information about firewall +configuration: + +.. toctree:: + :maxdepth: 1 + :includehidden: + + global-options + groups + bridge + ipv4 + ipv6 + flowtables + +.. note:: **For more information** + of Netfilter hooks and Linux networking packet flows can be + found in `Netfilter-Hooks + `_ + + +Zone-based firewall +^^^^^^^^^^^^^^^^^^^ +.. toctree:: + :maxdepth: 1 + :includehidden: + + zone + +With zone-based firewalls a new concept was implemented, in addtion to the +standard in and out traffic flows, a local flow was added. This local was for +traffic originating and destined to the router itself. Which means additional +rules were required to secure the firewall itself from the network, in +addition to the existing inbound and outbound rules from the traditional +concept above. + +To configure VyOS with the +:doc:`zone-based firewall configuration ` + +As the example image below shows, the device now needs rules to allow/block +traffic to or from the services running on the device that have open +connections on that interface. + +.. figure:: /_static/images/firewall-zonebased.png -- cgit v1.2.3 From dfa516d63e38eadc5e57dd143b17022c6ff2c092 Mon Sep 17 00:00:00 2001 From: Robert Göhler Date: Mon, 8 Jan 2024 21:23:37 +0100 Subject: Delete docs/configuration/firewall/index.rst~ --- docs/configuration/firewall/index.rst~ | 179 --------------------------------- 1 file changed, 179 deletions(-) delete mode 100644 docs/configuration/firewall/index.rst~ (limited to 'docs/configuration/firewall') diff --git a/docs/configuration/firewall/index.rst~ b/docs/configuration/firewall/index.rst~ deleted file mode 100644 index bdfc2069..00000000 --- a/docs/configuration/firewall/index.rst~ +++ /dev/null @@ -1,179 +0,0 @@ -:lastproofread: 2023-11-23 - -######## -Firewall -######## - -With VyOS being based on top of Linux and its kernel, the Netfilter project -created iptables and its successor nftables for the Linux kernel to -work directly on the data flows. This now extends the concept of zone-based -security to allow for manipulating the data at multiple stages once accepted -by the network interface and the driver before being handed off to the -destination (e.g., a web server OR another device). - -A simplified traffic flow diagram, based on Netfilter packet flow, is shown next, in -order to have a full view and understanding of how packets are processed, and -what possible paths traffic can take. - -.. figure:: /_static/images/firewall-gral-packet-flow.png - -Main points regarding this packet flow and terminology used in VyOS firewall are below: - - * **Bridge Port?**: choose appropriate path based on whether interface where the - packet was received is part of a bridge, or not. - -If interface where the packet was received isn't part of a bridge, then packet -is processed at the **IP Layer**: - - * **Prerouting**: several actions can be done in this stage, and currently - these actions are defined in different parts in VyOS configuration. Order - is important, and all these actions are performed before any actions - defined under ``firewall`` section. Relevant configuration that acts in - this stage are: - - * **Conntrack Ignore**: rules defined under ``set system conntrack ignore - [ipv4 | ipv6] ...``. - - * **Policy Route**: rules defined under ``set policy [route | route6] - ...``. - - * **Destination NAT**: rules defined under ``set [nat | nat66] - destination...``. - - * **Destination is the router?**: choose appropriate path based on - destination IP address. Transit forward continues to **forward**, - while traffic that destination IP address is configured on the router - continues to **input**. - - * **Input**: stage where traffic destined for the router itself can be - filtered and controlled. This is where all rules for securing the router - should take place. This includes ipv4 and ipv6 filtering rules, defined - in: - - * ``set firewall ipv4 input filter ...``. - - * ``set firewall ipv6 input filter ...``. - - * **Forward**: stage where transit traffic can be filtered and controlled. - This includes ipv4 and ipv6 filtering rules, defined in: - - * ``set firewall ipv4 forward filter ...``. - - * ``set firewall ipv6 forward filter ...``. - - * **Output**: stage where traffic that originates from the router itself - can be filtered and controlled. Bear in mind that this traffic can be a - new connection originated by a internal process running on VyOS router, - such as NTP, or a response to traffic received externaly through - **inputt** (for example response to an ssh login attempt to the router). - This includes ipv4 and ipv6 filtering rules, defined in: - - * ``set firewall ipv4 input filter ...``. - - * ``set firewall ipv6 output filter ...``. - - * **Postrouting**: as in **Prerouting**, several actions defined in - different parts of VyOS configuration are performed in this - stage. This includes: - - * **Source NAT**: rules defined under ``set [nat | nat66] - destination...``. - -If interface where the packet was received is part of a bridge, then packet -is processed at the **Bridge Layer**, which contains a basic setup for -bridge filtering: - - * **Forward (Bridge)**: stage where traffic that is trespasing through the - bridge is filtered and controlled: - - * ``set firewall bridge forward filter ...``. - -Main structure VyOS firewall cli is shown next: - -.. code-block:: none - - - set firewall - * bridge - - forward - + filter - * flowtable - - custom_flow_table - + ... - * global-options - + all-ping - + broadcast-ping - + ... - * group - - address-group - - ipv6-address-group - - network-group - - ipv6-network-group - - interface-group - - mac-group - - port-group - - domain-group - * ipv4 - - forward - + filter - - input - + filter - - output - + filter - - name - + custom_name - * ipv6 - - forward - + filter - - input - + filter - - output - + filter - - ipv6-name - + custom_name - * zone - - custom_zone_name - + ... - -Please, refer to appropiate section for more information about firewall -configuration: - -.. toctree:: - :maxdepth: 1 - :includehidden: - - global-options - groups - bridge - ipv4 - ipv6 - flowtables - -.. note:: **For more information** - of Netfilter hooks and Linux networking packet flows can be - found in `Netfilter-Hooks - `_ - - -Zone-based firewall -^^^^^^^^^^^^^^^^^^^ -.. toctree:: - :maxdepth: 1 - :includehidden: - - zone - -With zone-based firewalls a new concept was implemented, in addtion to the -standard in and out traffic flows, a local flow was added. This local was for -traffic originating and destined to the router itself. Which means additional -rules were required to secure the firewall itself from the network, in -addition to the existing inbound and outbound rules from the traditional -concept above. - -To configure VyOS with the -:doc:`zone-based firewall configuration ` - -As the example image below shows, the device now needs rules to allow/block -traffic to or from the services running on the device that have open -connections on that interface. - -.. figure:: /_static/images/firewall-zonebased.png -- cgit v1.2.3 From 85ef13b14fa37b8780f6e6c8220bc54366c72741 Mon Sep 17 00:00:00 2001 From: Nicolas Fort Date: Thu, 11 Jan 2024 09:46:26 -0300 Subject: Add opmode commands for firewall zones, and add global state-policies in quick-start --- docs/configuration/firewall/zone.rst | 38 ++++++++++++++++++++++++++++++++++++ docs/quick-start.rst | 31 +++++++++++++++++++++-------- 2 files changed, 61 insertions(+), 8 deletions(-) (limited to 'docs/configuration/firewall') diff --git a/docs/configuration/firewall/zone.rst b/docs/configuration/firewall/zone.rst index 1ab9c630..059b029d 100644 --- a/docs/configuration/firewall/zone.rst +++ b/docs/configuration/firewall/zone.rst @@ -123,3 +123,41 @@ written from the perspective of: *Source Zone*-to->*Destination Zone* set firewall zone DMZ from LAN firewall name LANv4-to-DMZv4 set firewall zone LAN from DMZ firewall name DMZv4-to-LANv4 +************** +Operation-mode +************** + +.. opcmd:: show firewall zone-policy + + This will show you a basic summary of zones configuration. + + .. code-block:: none + + vyos@vyos:~$ show firewall zone-policy + Zone Interfaces From Zone Firewall IPv4 Firewall IPv6 + ------ ------------ ----------- --------------- --------------- + LAN eth1 WAN WAN_to_LAN + eth2 + LOCAL LOCAL LAN LAN_to_LOCAL + WAN WAN_to_LOCAL WAN_to_LOCAL_v6 + WAN eth3 LAN LAN_to_WAN + eth0 LOCAL LOCAL_to_WAN + vyos@vyos:~$ + +.. opcmd:: show firewall zone-policy zone + + This will show you a basic summary of a particular zone. + + .. code-block:: none + + vyos@vyos:~$ show firewall zone-policy zone WAN + Zone Interfaces From Zone Firewall IPv4 Firewall IPv6 + ------ ------------ ----------- --------------- --------------- + WAN eth3 LAN LAN_to_WAN + eth0 LOCAL LOCAL_to_WAN + vyos@vyos:~$ show firewall zone-policy zone LOCAL + Zone Interfaces From Zone Firewall IPv4 Firewall IPv6 + ------ ------------ ----------- --------------- --------------- + LOCAL LOCAL LAN LAN_to_LOCAL + WAN WAN_to_LOCAL WAN_to_LOCAL_v6 + vyos@vyos:~$ diff --git a/docs/quick-start.rst b/docs/quick-start.rst index c8bb3f04..bbd7ab77 100644 --- a/docs/quick-start.rst +++ b/docs/quick-start.rst @@ -141,7 +141,7 @@ networks, addresses, ports, and domains that describe different parts of our network. We can then use them for filtering within our firewall rulesets, allowing for more concise and readable configuration. -In this case, we will create two interface groups—a ``WAN`` group for our +In this case, we will create two interface groups — a ``WAN`` group for our interfaces connected to the public internet and a ``LAN`` group for the interfaces connected to our internal network. Additionally, we will create a network group, ``NET-INSIDE-v4``, that contains our internal subnet. @@ -156,10 +156,26 @@ Configure Stateful Packet Filtering ----------------------------------- With the new firewall structure, we have have a lot of flexibility in how we -group and order our rules, as shown by the two alternative approaches below. +group and order our rules, as shown by the three alternative approaches below. -Option 1: Common Chain -^^^^^^^^^^^^^^^^^^^^^^ +Option 1: Global State Policies +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Using options defined in ``set firewall global-options state-policy``, state +policy rules that applies for both IPv4 and IPv6 are created. These global +state policies also applies for all traffic that passes through the router +(transit) and for traffic originated/destinated to/from the router itself, and +will be avaluated before any other rule defined in the firewall. + +Most installations would choose this option, and will contain: + +.. code-block:: none + + set firewall global-options state-policy established action accept + set firewall global-options state-policy related action accept + set firewall global-options state-policy invalid action drop + +Option 2: Common/Custom Chain +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ We can create a common chain for stateful connection filtering of multiple interfaces (or multiple netfilter hooks on one interface). Those individual @@ -196,12 +212,11 @@ hooks as the first filtering rule in the respective chains: set firewall ipv4 input filter rule 10 action 'jump' set firewall ipv4 input filter rule 10 jump-target CONN_FILTER -Option 2: Per-Hook Chain +Option 3: Per-Hook Chain ^^^^^^^^^^^^^^^^^^^^^^^^ -Alternatively, instead of configuring the ``CONN_FILTER`` chain described above, -you can take the more traditional stateful connection filtering approach by -creating rules on each hook's chain: +Alternatively, you can take the more traditional stateful connection +filtering approach by creating rules on each base hook's chain: .. code-block:: none -- cgit v1.2.3