vyos/vyos-documentation
1
0
Fork 0
mirror of https://github.com/vyos/vyos-documentation.git synced 2025-12-16 10:32:02 +01:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #1063 from NickAnderegg/overview-nftables-translation

Browse Source 
quick-start: update firewall tutorials to reflect nftables-based firewall commands
This commit is contained in:
Robert Göhler 2023-09-13 20:46:17 +02:00 committed by GitHub
commit 9688bca70d
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 204 additions and 60 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
docs/configuration/firewall/general-legacy.rst
View File

@ -424,11 +424,13 @@ There are a lot of matching criteria against which the package can be tested.
An arbitrary netmask can be applied to mask addresses to only match against An arbitrary netmask can be applied to mask addresses to only match against
a specific portion. This is particularly useful with IPv6 and a zone-based a specific portion. This is particularly useful with IPv6 and a zone-based
firewall as rules will remain valid if the IPv6 prefix changes and the host firewall as rules will remain valid if the IPv6 prefix changes and the host
portion of systems IPv6 address is static (for example, with SLAAC or `tokenised IPv6 addresses portion of systems IPv6 address is static (for example, with SLAAC or
<https://datatracker.ietf.org/doc/id/draft-chown-6man-tokenised-ipv6-identifiers-02.txt>`_) `tokenised IPv6 addresses
<https://datatracker.ietf.org/doc/id/draft-chown-6man-tokenised-ipv6-identifiers-02.txt>`_).
This functions for both individual addresses and address groups. This functions for both individual addresses and address groups.
.. stop_vyoslinter
.. code-block:: none .. code-block:: none
# Match any IPv6 address with the suffix ::0000:0000:0000:beef # Match any IPv6 address with the suffix ::0000:0000:0000:beef
@ -442,6 +444,7 @@ There are a lot of matching criteria against which the package can be tested.
set firewall group ipv6-address-group WEBSERVERS address ::2000 set firewall group ipv6-address-group WEBSERVERS address ::2000
set firewall name WAN-LAN-v6 rule 200 source group address-group WEBSERVERS set firewall name WAN-LAN-v6 rule 200 source group address-group WEBSERVERS
set firewall name WAN-LAN-v6 rule 200 source address-mask ::ffff:ffff:ffff:ffff set firewall name WAN-LAN-v6 rule 200 source address-mask ::ffff:ffff:ffff:ffff
.. start_vyoslinter
.. cfgcmd:: set firewall name <name> rule <1-999999> source fqdn <fqdn> .. cfgcmd:: set firewall name <name> rule <1-999999> source fqdn <fqdn>
.. cfgcmd:: set firewall name <name> rule <1-999999> destination fqdn <fqdn> .. cfgcmd:: set firewall name <name> rule <1-999999> destination fqdn <fqdn>
@ -1048,4 +1051,4 @@ Update geoip database
.. opcmd:: update geoip .. opcmd:: update geoip
Command used to update GeoIP database and firewall sets. Command used to update GeoIP database and firewall sets.

253
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 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 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 provide a :ref:`nat` gateway for a device with two network interfaces
(`eth0` and `eth1`). (``eth0`` and ``eth1``).
.. _quick-start-configuration-mode: .. _quick-start-configuration-mode:
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
To configure VyOS, you will need to enter configuration mode, resulting in the a ``$``. To configure VyOS, you will need to enter configuration mode, resulting
command prompt displaying a `#`, as demonstrated below: in the command prompt displaying a ``#``, as demonstrated below:
.. code-block:: none .. code-block:: none
@ -43,10 +43,10 @@ the following command:
Interface Configuration 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. address via DHCP.
* Your internal/LAN interface will be `eth1`. It will use a static IP address * Your internal/LAN interface will be ``eth1``. It will use a static IP address
of `192.168.0.1/24`. of ``192.168.0.1/24``.
After switching to :ref:`quick-start-configuration-mode` issue the following After switching to :ref:`quick-start-configuration-mode` issue the following
commands: 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 your internal/LAN network, where VyOS will act as the default gateway and
DNS server. DNS server.
* The default gateway and DNS recursor address will be `192.168.0.1/24` * 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 address range ``192.168.0.2/24 - 192.168.0.8/24`` will be reserved for
static assignments static assignments
* DHCP clients will be assigned IP addresses within the range of * 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) * DHCP leases will hold for one day (86400 seconds)
* VyOS will serve as a full DNS recursor, replacing the need to utilize Google, * 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) Cloudflare, or other public DNS servers (which is good for privacy)
@ -118,68 +118,210 @@ network via IP masquerade.
set nat source rule 100 source address '192.168.0.0/24' set nat source rule 100 source address '192.168.0.0/24'
set nat source rule 100 translation address masquerade set nat source rule 100 translation address masquerade
Firewall Firewall
######## ########
.. note:: Starting from VyOS 1.4-rolling-202308040557, a new firewall A new firewall structure—which uses the ``nftables`` backend, rather
structure can be found on all vyos instalations. Documentation for most than ``iptables``—is available on all installations starting from
of the new firewall CLI can be found in the `firewall VyOS ``1.4-rolling-202308040557``. The firewall supports creation of distinct,
<https://docs.vyos.io/en/latest/configuration/firewall/general.html>`_ interlinked chains for each `Netfilter hook
chapter. The legacy firewall is still available for versions before <https://wiki.nftables.org/wiki-nftables/index.php/Netfilter_hooks>`_
1.4-rolling-202308040557 and can be found in the :ref:`firewall-legacy` and allows for more granular control over the packet filtering process.
chapter. The examples in this section use the new firewall configuration
commands.
Add a set of firewall policies for our outside/WAN interface. .. 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.
This configuration creates a proper stateful firewall that blocks all traffic The firewall begins with the base ``filter`` tables you define for each of the
which was not initiated from the internal/LAN side first. ``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 .. code-block:: none
set firewall ipv4 forward filter default-action 'drop' set firewall group interface-group WAN interface eth0
set firewall ipv4 forward filter rule 10 action 'accept' set firewall group interface-group LAN interface eth1
set firewall ipv4 forward filter rule 10 state established 'enable' set firewall group network-group NET-INSIDE-v4 network '192.168.0.0/24'
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 interface-name 'eth1'
set firewall ipv4 forward filter rule 30 action 'accept'
set firewall ipv4 input filter default-action drop Configure Stateful Packet Filtering
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' With the new firewall structure, we have have a lot of flexibility in how we
set firewall ipv4 input filter rule 20 action 'drop' group and order our rules, as shown by the two alternative approaches below.
set firewall ipv4 input filter rule 20 state invalid 'enable'
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 'enable'
set firewall ipv4 name CONN_FILTER rule 10 state related 'enable'
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 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 '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'
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 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
------------------------
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 action 'accept'
set firewall ipv4 input filter rule 30 icmp type-name 'echo-request' 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 protocol 'icmp'
set firewall ipv4 input filter rule 30 state new 'enable' set firewall ipv4 input filter rule 30 state new 'enable'
If you wanted to enable SSH access to your firewall from the outside/WAN set firewall ipv4 input filter rule 40 action 'accept'
interface, you could create some additional rules to allow that kind of set firewall ipv4 input filter rule 40 destination port '53'
traffic. 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 Finally, we can now configure access to the services running on this router,
blocks brute-forcing attempts: allowing all connections coming from localhost:
.. code-block:: none .. code-block:: none
set firewall ipv4 input filter rule 40 action 'drop' set firewall ipv4 input filter rule 50 action 'accept'
set firewall ipv4 input filter rule 40 inbound-interface interface-name 'eth0' set firewall ipv4 input filter rule 50 source address 127.0.0.0/8
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'
Commit changes, save the configuration, and exit configuration mode: Commit changes, save the configuration, and exit configuration mode:
@ -192,14 +334,13 @@ Commit changes, save the configuration, and exit configuration mode:
vyos@vyos# exit vyos@vyos# exit
vyos@vyos$ vyos@vyos$
Hardening Hardening
######### #########
Especially if you are allowing SSH remote access from the outside/WAN Especially if you are allowing SSH remote access from the outside/WAN
interface, there are a few additional configuration steps that should be taken. 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 .. code-block:: none