diff options
| -rw-r--r-- | docs/quick-start.rst | 262 |
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 |