summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorNick Anderegg <nick@anderegg.io>2023-09-10 20:20:13 -0400
committerNick Anderegg <nick@anderegg.io>2023-09-12 20:55:59 -0400
commit5a57f5968dc45df162f8643a2f575db39087fac9 (patch)
tree1a69757099493d253f4fb945d82114f715c668b4
parent31f741269dc4a6b2afa6c6cf4ad2c3d746e4953c (diff)
downloadvyos-documentation-5a57f5968dc45df162f8643a2f575db39087fac9.tar.gz
vyos-documentation-5a57f5968dc45df162f8643a2f575db39087fac9.zip
quick-start: add clarifying context to nftables config examples
-rw-r--r--docs/quick-start.rst110
1 files changed, 66 insertions, 44 deletions
diff --git a/docs/quick-start.rst b/docs/quick-start.rst
index 2f428fe9..3a149c78 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 `$`.
+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:
+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)
@@ -121,13 +121,24 @@ network via IP 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 :ref:`firewall` chapter. The legacy firewall is still available
- for versions before 1.4-rolling-202308040557 and can be found in the
+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.
+
+.. note:: 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 use the
new configuration.
+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
-------------------------
@@ -136,10 +147,10 @@ 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
+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.
+``NET-INSIDE-v4``, that contains our internal subnet.
.. code-block:: none
@@ -147,45 +158,56 @@ connected to our internal network. Additionally, we will create a network group,
set firewall group interface-group LAN interface eth1
set firewall group network-group NET-INSIDE-v4 network '192.168.0.0/24'
-Stateful Packet Filtering
--------------------------
+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.
-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:
+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 is 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
- # 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'
- # 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'
- # Drop invalid traffic
set firewall ipv4 name CONN_FILTER rule 20 action 'drop'
set firewall ipv4 name CONN_FILTER rule 20 state invalid 'enable'
-Then, we can jump to the common chain from both the `forward` and `input` hooks
+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
- # 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
- # 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
-Alternatively, you can take the more traditional approach of creating rules on
-each hook's chain for stateful connection filtering:
+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
@@ -208,9 +230,9 @@ 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
+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
+from the ``forward`` hook when traffic is coming from the ``WAN`` interface group
and is addressed to our local network.
.. code-block:: none
@@ -223,30 +245,30 @@ and is addressed to our local network.
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
+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`:
+set the default action to ``drop``:
.. code-block:: none
set firewall ipv4 input filter default-action 'drop'
-Configure Management Access
+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
+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:
+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`
+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
@@ -256,8 +278,8 @@ chain when new connections are addressed to port 22 (SSH) on the router itself:
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
+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
@@ -287,7 +309,7 @@ all connections coming from localhost:
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`
+accepting traffic bound for port 53 from all hosts on the ``NET-INSIDE-v4``
network:
.. code-block:: none
@@ -314,7 +336,7 @@ 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