Update quick-start from master branch (excluding 1.5 specific DHCP changes)

1 files changed, 199 insertions, 63 deletions

diff --git a/docs/quick-start.rst b/docs/quick-start.rst
index 7a22d9de..c8bb3f04 100644
--- a/docs/quick-start.rst
+++ b/docs/quick-start.rst
@@ -7,16 +7,16 @@ Quick Start
 This chapter will guide you on how to get up to speed quickly using your new
 VyOS system. It will show you a very basic configuration example that will
 provide a :ref:`nat` gateway for a device with two network interfaces
-(`eth0` and `eth1`).
+(``eth0`` and ``eth1``).
 
 .. _quick-start-configuration-mode:
 
 Configuration Mode
 ##################
 
-By default, VyOS is in operational mode, and the command prompt displays a `$`.
-To configure VyOS, you will need to enter configuration mode, resulting in the
-command prompt displaying a `#`, as demonstrated below:
+By default, VyOS is in operational mode, and the command prompt displays
+a ``$``. To configure VyOS, you will need to enter configuration mode, resulting
+in the command prompt displaying a ``#``, as demonstrated below:
 
 .. code-block:: none
 
@@ -43,10 +43,10 @@ the following command:
 Interface Configuration
 #######################
 
-* Your outside/WAN interface will be `eth0`. It will receive its interface
+* Your outside/WAN interface will be ``eth0``. It will receive its interface
   address via DHCP.
-* Your internal/LAN interface will be `eth1`. It will use a static IP address
-  of `192.168.0.1/24`.
+* Your internal/LAN interface will be ``eth1``. It will use a static IP address
+  of ``192.168.0.1/24``.
 
 After switching to :ref:`quick-start-configuration-mode` issue the following
 commands:
@@ -81,11 +81,11 @@ The following settings will configure DHCP and DNS services on
 your internal/LAN network, where VyOS will act as the default gateway and
 DNS server.
 
-* The default gateway and DNS recursor address will be `192.168.0.1/24`
-* The address range `192.168.0.2/24 - 192.168.0.8/24` will be reserved for
+* The default gateway and DNS recursor address will be ``192.168.0.1/24``
+* The address range ``192.168.0.2/24 - 192.168.0.8/24`` will be reserved for
   static assignments
 * DHCP clients will be assigned IP addresses within the range of
-  `192.168.0.9 - 192.168.0.254` and have a domain name of `internal-network`
+  ``192.168.0.9 - 192.168.0.254`` and have a domain name of ``internal-network``
 * DHCP leases will hold for one day (86400 seconds)
 * VyOS will serve as a full DNS recursor, replacing the need to utilize Google,
   Cloudflare, or other public DNS servers (which is good for privacy)
@@ -118,68 +118,205 @@ 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
 ########
 
-.. note:: Starting from VyOS 1.4-rolling-202308040557, a new firewall
-   structure can be found on all vyos instalations. Documentation for most
-   of the new firewall CLI can be found in the `firewall
-   <https://docs.vyos.io/en/latest/configuration/firewall/general.html>`_
-   chapter. The legacy firewall is still available for versions before
-   1.4-rolling-202308040557 and can be found in the :ref:`legacy-firewall`
-   chapter. The examples in this section use the new firewall configuration
-   commands.
-
-Add a set of firewall policies for our outside/WAN interface.
-
-This configuration creates a proper stateful firewall that blocks all traffic
-which was not initiated from the internal/LAN side first.
-
-.. code-block:: none
-
-  set firewall ipv4 forward filter default-action 'drop'
-  set firewall ipv4 forward filter rule 10 action 'accept'
-  set firewall ipv4 forward filter rule 10 state established 'enable'
-  set firewall ipv4 forward filter rule 10 state related 'enable'
-  set firewall ipv4 forward filter rule 20 action 'drop'
-  set firewall ipv4 forward filter rule 20 state invalid 'enable'
-  set firewall ipv4 forward filter rule 30 inbound-interface name 'eth1'
-  set firewall ipv4 forward filter rule 30 action 'accept'
-
-  set firewall ipv4 input filter default-action drop
-  set firewall ipv4 input filter rule 10 action 'accept'
-  set firewall ipv4 input filter rule 10 state established 'enable'
-  set firewall ipv4 input filter rule 10 state related 'enable'
-  set firewall ipv4 input filter rule 20 action 'drop'
-  set firewall ipv4 input filter rule 20 state invalid 'enable'
+A new firewall structure—which uses the ``nftables`` backend, rather
+than ``iptables``—is available on all installations starting from
+VyOS ``1.4-rolling-202308040557``. The firewall supports creation of distinct,
+interlinked chains for each `Netfilter hook
+<https://wiki.nftables.org/wiki-nftables/index.php/Netfilter_hooks>`_
+and allows for more granular control over the packet filtering process.
+
+The firewall begins with the base ``filter`` tables you define for each of the
+``forward``, ``input``, and ``output`` Netfiter hooks. Each of these tables is
+populated with rules that are processed in order and can jump to other chains
+for more granular filtering.
+
+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
+
+  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'
+
+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.
+
+Option 1: Common Chain
+^^^^^^^^^^^^^^^^^^^^^^
+
+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.
+
+The chain we will create is called ``CONN_FILTER`` and has three rules:
+
+- A default action of ``return``, which returns the packet back to the original
+  chain if no action is taken.
+- A rule to ``accept`` packets from established and related connections.
+- A rule to ``drop`` packets from invalid connections.
+
+.. code-block:: none
+
+  set firewall ipv4 name CONN_FILTER default-action 'return'
+
+  set firewall ipv4 name CONN_FILTER rule 10 action 'accept'
+  set firewall ipv4 name CONN_FILTER rule 10 state established 
+  set firewall ipv4 name CONN_FILTER rule 10 state related 
+
+  set firewall ipv4 name CONN_FILTER rule 20 action 'drop'
+  set firewall ipv4 name CONN_FILTER rule 20 state invalid 
+
+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 ipv4 forward filter rule 10 action 'jump'
+  set firewall ipv4 forward filter rule 10 jump-target CONN_FILTER
+
+  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
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+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:
+
+.. code-block:: none
+
+  set firewall ipv4 forward filter rule 5 action 'accept'
+  set firewall ipv4 forward filter rule 5 state established 
+  set firewall ipv4 forward filter rule 5 state related 
+  set firewall ipv4 forward filter rule 10 action 'drop'
+  set firewall ipv4 forward filter rule 10 state invalid 
+
+  set firewall ipv4 input filter rule 5 action 'accept'
+  set firewall ipv4 input filter rule 5 state established 
+  set firewall ipv4 input filter rule 5 state related 
+  set firewall ipv4 input filter rule 10 action 'drop'
+  set firewall ipv4 input filter rule 10 state invalid 
+
+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 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'
+
+Allow 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 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 
+  set firewall ipv4 name VyOS_MANAGEMENT rule 20 inbound-interface group 'WAN'
+
+  set firewall ipv4 name VyOS_MANAGEMENT rule 21 action 'accept'
+  set firewall ipv4 name VyOS_MANAGEMENT rule 21 state new 
+  set firewall ipv4 name VyOS_MANAGEMENT rule 21 inbound-interface group 'WAN'
+
+Allow Access to Services
+------------------------
+
+Here we're allowing the router to respond to pings. Then, 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 30 action 'accept'
   set firewall ipv4 input filter rule 30 icmp type-name 'echo-request'
   set firewall ipv4 input filter rule 30 protocol 'icmp'
-  set firewall ipv4 input filter rule 30 state new 'enable'
+  set firewall ipv4 input filter rule 30 state new 
 
-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.
+  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
 
-These rules allow SSH traffic and rate limit it to 4 requests per minute. This
-blocks brute-forcing attempts:
+Finally, 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 40 action 'drop'
-  set firewall ipv4 input filter rule 40 inbound-interface name 'eth0'
-  set firewall ipv4 input filter rule 40 destination port '22'
-  set firewall ipv4 input filter rule 40 protocol 'tcp'
-  set firewall ipv4 input filter rule 40 recent count '4'
-  set firewall ipv4 input filter rule 40 recent time 'minute'
-  set firewall ipv4 input filter rule 40 state new 'enable'
-
-  set firewall ipv4 input filter rule 41 action 'accept'
-  set firewall ipv4 input filter rule 41 destination port '22'
-  set firewall ipv4 input filter rule 41 protocol 'tcp'
-  set firewall ipv4 input filter rule 41 state new 'enable'
-
+  set firewall ipv4 input filter rule 50 action 'accept'
+  set firewall ipv4 input filter rule 50 source address 127.0.0.0/8
 
 Commit changes, save the configuration, and exit configuration mode:
 
@@ -192,14 +329,13 @@ Commit changes, save the configuration, and exit configuration mode:
   vyos@vyos# exit
   vyos@vyos$
 
-
 Hardening
 #########
 
 Especially if you are allowing SSH remote access from the outside/WAN
 interface, there are a few additional configuration steps that should be taken.
 
-Replace the default `vyos` system user:
+Replace the default ``vyos`` system user:
 
 .. code-block:: none