vyos/vyos-documentation
1
0
Fork 0
mirror of https://github.com/vyos/vyos-documentation.git synced 2025-10-26 08:41:46 +01:00
Code Issues Packages Projects Releases Wiki Activity

quick-start: add clarifying context to nftables config examples

Browse Source
This commit is contained in:
Nick Anderegg 2023-09-10 20:20:13 -04:00
parent 31f741269d
commit 5a57f5968d
1 changed files with 66 additions and 44 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

110
docs/quick-start.rst
View File

@ -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
-----------------------------------
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:
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 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