quick-start: initial pass of netfilter firewall configuration intro

1 files changed, 155 insertions, 37 deletions

diff --git a/docs/quick-start.rst b/docs/quick-start.rst
index d14a43ca..2f428fe9 100644
--- a/docs/quick-start.rst
+++ b/docs/quick-start.rst
@@ -118,7 +118,6 @@ network via IP masquerade.
   set nat source rule 100 source address '192.168.0.0/24'
   set nat source rule 100 translation address masquerade
 
-
 Firewall
 ########
 
@@ -126,57 +125,177 @@ Firewall
    found on all vyos instalations. Documentation for most of the new firewall CLI
    can be found in the :ref:`firewall` chapter. The legacy firewall is still available
    for versions before 1.4-rolling-202308040557 and can be found in the
-   :ref:`firewall-legacy` chapter. The examples in this section still use the
-   legacy firewall configuration options.
+   :ref:`firewall-legacy` chapter. The examples in this section use the
+   new configuration.
+
+Configure Firewall Groups
+-------------------------
+
+To make firewall configuration easier, we can create groups of interfaces,
+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
+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.
+
+.. code-block:: none
 
-Add a set of firewall policies for our outside/WAN interface.
+  set firewall group interface-group WAN interface eth0
+  set firewall group interface-group LAN interface eth1
+  set firewall group network-group NET-INSIDE-v4 network '192.168.0.0/24'
 
-This configuration creates a proper stateful firewall that blocks all traffic
-which was not initiated from the internal/LAN side first.
+Stateful Packet Filtering
+-------------------------
+
+Using the new firewall structure, we can create a common chain for stateful
+connection filtering of multiple interfaces (or multiple netfilter hooks on one
+interface). Those individual chains can then jump to the common chain for
+stateful connection filtering, returning to the original chain for further
+rule processing if no action is taken on the packet:
 
 .. code-block:: none
 
-  set firewall name OUTSIDE-IN default-action 'drop'
-  set firewall name OUTSIDE-IN rule 10 action 'accept'
-  set firewall name OUTSIDE-IN rule 10 state established 'enable'
-  set firewall name OUTSIDE-IN rule 10 state related 'enable'
+  # Create a new chain for stateful connection filtering that
+  # will return to the original chain if no action is taken
+  set firewall ipv4 name CONN_FILTER default-action 'return'
 
-  set firewall name OUTSIDE-LOCAL default-action 'drop'
-  set firewall name OUTSIDE-LOCAL rule 10 action 'accept'
-  set firewall name OUTSIDE-LOCAL rule 10 state established 'enable'
-  set firewall name OUTSIDE-LOCAL rule 10 state related 'enable'
-  set firewall name OUTSIDE-LOCAL rule 20 action 'accept'
-  set firewall name OUTSIDE-LOCAL rule 20 icmp type-name 'echo-request'
-  set firewall name OUTSIDE-LOCAL rule 20 protocol 'icmp'
-  set firewall name OUTSIDE-LOCAL rule 20 state new 'enable'
+  # Allow established and related traffic
+  set firewall ipv4 name CONN_FILTER rule 10 action 'accept'
+  set firewall ipv4 name CONN_FILTER rule 10 state established 'enable'
+  set firewall ipv4 name CONN_FILTER rule 10 state related 'enable'
 
-If you wanted to enable SSH access to your firewall from the outside/WAN
-interface, you could create some additional rules to allow that kind of
-traffic.
+  # Drop invalid traffic
+  set firewall ipv4 name CONN_FILTER rule 20 action 'drop'
+  set firewall ipv4 name CONN_FILTER rule 20 state invalid 'enable'
 
-These rules allow SSH traffic and rate limit it to 4 requests per minute. This
-blocks brute-forcing attempts:
+Then, we can jump to the common chain from both the `forward` and `input` hooks
+as the first filtering rule in the respective chains:
 
 .. code-block:: none
 
-  set firewall name OUTSIDE-LOCAL rule 30 action 'drop'
-  set firewall name OUTSIDE-LOCAL rule 30 destination port '22'
-  set firewall name OUTSIDE-LOCAL rule 30 protocol 'tcp'
-  set firewall name OUTSIDE-LOCAL rule 30 recent count '4'
-  set firewall name OUTSIDE-LOCAL rule 30 recent time 'minute'
-  set firewall name OUTSIDE-LOCAL rule 30 state new 'enable'
+  # Add a filter for the `forward` hook that sends all packets to CONN_FILTER
+  set firewall ipv4 forward filter rule 10 action 'jump'
+  set firewall ipv4 forward filter rule 10 jump-target CONN_FILTER
 
-  set firewall name OUTSIDE-LOCAL rule 31 action 'accept'
-  set firewall name OUTSIDE-LOCAL rule 31 destination port '22'
-  set firewall name OUTSIDE-LOCAL rule 31 protocol 'tcp'
-  set firewall name OUTSIDE-LOCAL rule 31 state new 'enable'
+  # Add a filter for the `input` hook that sends all packets to that same chain
+  set firewall ipv4 input filter rule 10 action 'jump'
+  set firewall ipv4 input filter rule 10 jump-target CONN_FILTER
 
-Apply the firewall policies:
+Alternatively, you can take the more traditional approach of creating rules on
+each hook's chain for stateful connection filtering:
 
 .. code-block:: none
 
-  set firewall interface eth0 in name 'OUTSIDE-IN'
-  set firewall interface eth0 local name 'OUTSIDE-LOCAL'
+  set firewall ipv4 forward filter rule 5 action 'accept'
+  set firewall ipv4 forward filter rule 5 state established 'enable'
+  set firewall ipv4 forward filter rule 5 state related 'enable'
+  set firewall ipv4 forward filter rule 10 action 'drop'
+  set firewall ipv4 forward filter rule 10 state invalid 'enable'
+
+  set firewall ipv4 input filter rule 5 action 'accept'
+  set firewall ipv4 input filter rule 5 state established 'enable'
+  set firewall ipv4 input filter rule 5 state related 'enable'
+  set firewall ipv4 input filter rule 10 action 'drop'
+  set firewall ipv4 input filter rule 10 state invalid 'enable'
+
+Block Incoming Traffic
+----------------------
+
+Now that we have configured stateful connection filtering to allow traffic from
+established and related connections, we can block all other incoming traffic
+addressed to our local network.
+
+Create a new chain (`OUTSIDE-IN`) which will drop all traffic that is not
+explicity allowed at some point in the chain. Then, we can jump to that chain
+from the `forward` hook when traffic is coming from the `WAN` interface group
+and is addressed to our local network.
+
+.. code-block:: none
+
+  set firewall ipv4 name OUTSIDE-IN default-action 'drop'
+
+  set firewall ipv4 forward filter rule 100 action jump
+  set firewall ipv4 forward filter rule 100 jump-target OUTSIDE-IN
+  set firewall ipv4 forward filter rule 100 inbound-interface interface-group WAN
+  set firewall ipv4 forward filter rule 100 destination group network-group NET-INSIDE-v4
+
+We should also block all traffic destinated to the router itself that isn't
+explicitly allowed at some point in the chain for the `input` hook. As
+we've already configured stateful packet filtering above, we only need to
+set the default action to `drop`:
+
+.. code-block:: none
+
+  set firewall ipv4 input filter default-action 'drop'
+
+Configure Management Access
+---------------------------
+
+We can now configure access to the router itself, allowing SSH
+access from the inside/LAN network and rate limiting SSH access from the
+outside/WAN network.
+
+First, create a new dedicated chain (`VyOS_MANAGEMENT`) for management
+access, which returns to the parent chain if no action is taken. Add a rule
+to accept traffic from the `LAN` interface group:
+
+.. code-block:: none
+
+  set firewall ipv4 name VyOS_MANAGEMENT default-action 'return'
+
+Configure a rule on the `input` hook filter to jump to the `VyOS_MANAGEMENT`
+chain when new connections are addressed to port 22 (SSH) on the router itself:
+
+.. code-block:: none
+
+  set firewall ipv4 input filter rule 20 action jump
+  set firewall ipv4 input filter rule 20 jump-target VyOS_MANAGEMENT
+  set firewall ipv4 input filter rule 20 destination port 22
+  set firewall ipv4 input filter rule 20 protocol tcp
+
+Finally, configure the `VyOS_MANAGEMENT` chain to accept connection from the
+`LAN` interface group while limiting requests coming from the `WAN` interface
+group to 4 per minute:
+
+.. code-block:: none
+
+  set firewall ipv4 name VyOS_MANAGEMENT rule 15 action 'accept'
+  set firewall ipv4 name VyOS_MANAGEMENT rule 15 inbound-interface interface-group 'LAN'
+
+  set firewall ipv4 name VyOS_MANAGEMENT rule 20 action 'drop'
+  set firewall ipv4 name VyOS_MANAGEMENT rule 20 recent count 4
+  set firewall ipv4 name VyOS_MANAGEMENT rule 20 recent time minute
+  set firewall ipv4 name VyOS_MANAGEMENT rule 20 state new enable
+  set firewall ipv4 name VyOS_MANAGEMENT rule 20 inbound-interface interface-group 'WAN'
+
+  set firewall ipv4 name VyOS_MANAGEMENT rule 21 action 'accept'
+  set firewall ipv4 name VyOS_MANAGEMENT rule 21 state new enable
+  set firewall ipv4 name VyOS_MANAGEMENT rule 21 inbound-interface interface-group 'WAN'
+
+Allow Access to Services
+------------------------
+
+We can now configure access to the services running on this router, allowing
+all connections coming from localhost:
+
+.. code-block:: none
+
+  set firewall ipv4 input filter rule 30 action 'accept'
+  set firewall ipv4 input filter rule 30 source address 127.0.0.0/8
+
+Finally, we can allow access to the DNS recursor we configured earlier,
+accepting traffic bound for port 53 from all hosts on the `NET-INSIDE-v4`
+network:
+
+.. code-block:: none
+
+  set firewall ipv4 input filter rule 40 action 'accept'
+  set firewall ipv4 input filter rule 40 destination port '53'
+  set firewall ipv4 input filter rule 40 protocol 'tcp_udp'
+  set firewall ipv4 input filter rule 40 source group network-group NET-INSIDE-v4
 
 Commit changes, save the configuration, and exit configuration mode:
 
@@ -189,7 +308,6 @@ Commit changes, save the configuration, and exit configuration mode:
   vyos@vyos# exit
   vyos@vyos$
 
-
 Hardening
 #########