diff options
Diffstat (limited to 'docs')
23 files changed, 523 insertions, 104 deletions
diff --git a/docs/_static/images/firewall-and-vrf-blueprints.png b/docs/_static/images/firewall-and-vrf-blueprints.png Binary files differnew file mode 100644 index 00000000..8c3bf9f2 --- /dev/null +++ b/docs/_static/images/firewall-and-vrf-blueprints.png diff --git a/docs/_static/images/firewall-fwd-packet-flow.png b/docs/_static/images/firewall-fwd-packet-flow.png Binary files differindex e4bc2adc..1ca213e8 100644 --- a/docs/_static/images/firewall-fwd-packet-flow.png +++ b/docs/_static/images/firewall-fwd-packet-flow.png diff --git a/docs/_static/images/firewall-input-packet-flow.png b/docs/_static/images/firewall-input-packet-flow.png Binary files differindex 1c53c34a..20d356bd 100644 --- a/docs/_static/images/firewall-input-packet-flow.png +++ b/docs/_static/images/firewall-input-packet-flow.png diff --git a/docs/cli.rst b/docs/cli.rst index 79501c66..c1a9d14c 100644 --- a/docs/cli.rst +++ b/docs/cli.rst @@ -857,7 +857,7 @@ to :cfgcmd:`commit`. You will have to set the commit-archive location. TFTP, FTP, SCP and SFTP servers are supported. Every time a :cfgcmd:`commit` is successful the ``config.boot`` file will be copied to the defined destination(s). The filename used on the remote host will -be ``config.boot-hostname.YYYYMMDD_HHMMSS``. +be ``config.boot-hostname.YYYYMMDD_HHMMSS``. .. cfgcmd:: set system config-management commit-archive location <URI> @@ -877,6 +877,9 @@ be ``config.boot-hostname.YYYYMMDD_HHMMSS``. .. note:: The number of revisions don't affect the commit-archive. + .. note:: When using Git as destination for the commit archive the + ``source-address`` CLI option has no effect. + .. note:: You may find VyOS not allowing the secure connection because it cannot verify the legitimacy of the remote server. You can use the workaround below to quickly add the remote host's SSH diff --git a/docs/configexamples/firewall.rst b/docs/configexamples/firewall.rst new file mode 100644 index 00000000..e0a4ca55 --- /dev/null +++ b/docs/configexamples/firewall.rst @@ -0,0 +1,12 @@ +:lastproofread: 2024-06-14 + +Firewall Examples +================= + +This section contains examples of firewall configurations for various deployments. + +.. toctree:: + :maxdepth: 2 + + fwall-and-vrf + zone-policy diff --git a/docs/configexamples/fwall-and-vrf.rst b/docs/configexamples/fwall-and-vrf.rst new file mode 100644 index 00000000..38663a18 --- /dev/null +++ b/docs/configexamples/fwall-and-vrf.rst @@ -0,0 +1,121 @@ +VRF and firewall example +------------------------ + +Scenario and requirements +^^^^^^^^^^^^^^^^^^^^^^^^^ + +This example shows how to configure a VyOS router with VRFs and firewall rules. + +Diagram used in this example: + +.. image:: /_static/images/firewall-and-vrf-blueprints.png + :width: 80% + :align: center + :alt: Network Topology Diagram + +As exposed in the diagram, there are four VRFs. These VRFs are ``MGMT``, +``WAN``, ``LAN`` and ``PROD``, and their requirements are: + +* VRF MGMT: + * Allow connections to LAN and PROD. + * Deny connections to internet(WAN). + * Allow connections to the router. +* VRF LAN: + * Allow connections to PROD. + * Allow connections to internet(WAN). +* VRF PROD: + * Only accepts connections. +* VRF WAN: + * Allow connection to PROD. + +Configuration +^^^^^^^^^^^^^ + +First, we need to configure the interfaces and VRFs: + +.. code-block:: none + + set interfaces ethernet eth1 address '10.100.100.1/24' + set interfaces ethernet eth1 vrf 'MGMT' + set interfaces ethernet eth2 vif 150 address '10.150.150.1/24' + set interfaces ethernet eth2 vif 150 vrf 'LAN' + set interfaces ethernet eth2 vif 160 address '10.160.160.1/24' + set interfaces ethernet eth2 vif 160 vrf 'LAN' + set interfaces ethernet eth2 vif 3500 address '172.16.20.1/24' + set interfaces ethernet eth2 vif 3500 vrf 'PROD' + set interfaces loopback lo + set interfaces pppoe pppoe0 authentication password 'p4ssw0rd' + set interfaces pppoe pppoe0 authentication username 'vyos' + set interfaces pppoe pppoe0 source-interface 'eth0' + set interfaces pppoe pppoe0 vrf 'WAN' + set vrf bind-to-all + set vrf name LAN protocols static route 0.0.0.0/0 interface pppoe0 vrf 'WAN' + set vrf name LAN protocols static route 10.100.100.0/24 interface eth1 vrf 'MGMT' + set vrf name LAN protocols static route 172.16.20.0/24 interface eth2.3500 vrf 'PROD' + set vrf name LAN table '103' + set vrf name MGMT protocols static route 10.150.150.0/24 interface eth2.150 vrf 'LAN' + set vrf name MGMT protocols static route 10.160.160.0/24 interface eth2.160 vrf 'LAN' + set vrf name MGMT protocols static route 172.16.20.0/24 interface eth2.3500 vrf 'PROD' + set vrf name MGMT table '102' + set vrf name PROD protocols static route 0.0.0.0/0 interface pppoe0 vrf 'WAN' + set vrf name PROD protocols static route 10.100.100.0/24 interface eth1 vrf 'MGMT' + set vrf name PROD protocols static route 10.150.150.0/24 interface eth2.150 vrf 'LAN' + set vrf name PROD protocols static route 10.160.160.0/24 interface eth2.160 vrf 'LAN' + set vrf name PROD table '104' + set vrf name WAN protocols static route 10.150.150.0/24 interface eth2.150 vrf 'LAN' + set vrf name WAN protocols static route 10.160.160.0/24 interface eth2.160 vrf 'LAN' + set vrf name WAN protocols static route 172.16.20.0/24 interface eth2.3500 vrf 'PROD' + set vrf name WAN table '101' + +And before firewall rules are shown, we need to pay attention how to configure +and match interfaces and VRFs. In case where an interface is assigned to a +non-default VRF, if we want to use inbound-interface or outbound-interface in +firewall rules, we need to: + +* For **inbound-interface**: use the interface name with the VRF name, like + ``MGMT`` or ``LAN``. +* For **outbound-interface**: use the interface name, like ``eth0``, ``vtun0``, + ``eth2*`` or similar. + +Next, we need to configure the firewall rules. First we will define all rules +for transit traffic between VRFs. + +.. code-block:: none + + set firewall ipv4 forward filter default-action 'drop' + set firewall ipv4 forward filter default-log + set firewall ipv4 forward filter rule 10 action 'accept' + set firewall ipv4 forward filter rule 10 description 'MGMT - Allow to LAN and PROD' + set firewall ipv4 forward filter rule 10 inbound-interface name 'MGMT' + set firewall ipv4 forward filter rule 10 outbound-interface name 'eth2*' + set firewall ipv4 forward filter rule 99 action 'drop' + set firewall ipv4 forward filter rule 99 description 'MGMT - Drop all going to mgmt' + set firewall ipv4 forward filter rule 99 outbound-interface name 'eth1' + set firewall ipv4 forward filter rule 120 action 'accept' + set firewall ipv4 forward filter rule 120 description 'LAN - Allow to PROD' + set firewall ipv4 forward filter rule 120 inbound-interface name 'LAN' + set firewall ipv4 forward filter rule 120 outbound-interface name 'eth2.3500' + set firewall ipv4 forward filter rule 130 action 'accept' + set firewall ipv4 forward filter rule 130 description 'LAN - Allow internet' + set firewall ipv4 forward filter rule 130 inbound-interface name 'LAN' + set firewall ipv4 forward filter rule 130 outbound-interface name 'pppoe0' + +Also, we are adding global state policies, in order to allow established and +related traffic, in order not to drop valid responses: + +.. code-block:: none + + set firewall global-options state-policy established action 'accept' + set firewall global-options state-policy invalid action 'drop' + set firewall global-options state-policy related action 'accept' + +And finally, we need to allow input connections to the router itself only from +vrf MGMT: + +.. code-block:: none + + set firewall ipv4 input filter default-action 'drop' + set firewall ipv4 input filter default-log + set firewall ipv4 input filter rule 10 action 'accept' + set firewall ipv4 input filter rule 10 description 'MGMT - Allow input' + set firewall ipv4 input filter rule 10 inbound-interface name 'MGMT'
\ No newline at end of file diff --git a/docs/configexamples/index.rst b/docs/configexamples/index.rst index d5973eb2..11dee806 100644 --- a/docs/configexamples/index.rst +++ b/docs/configexamples/index.rst @@ -8,7 +8,7 @@ This chapter contains various configuration examples: .. toctree:: :maxdepth: 2 - zone-policy + firewall bgp-ipv6-unnumbered ospf-unnumbered azure-vpn-bgp diff --git a/docs/configexamples/zone-policy.rst b/docs/configexamples/zone-policy.rst index 95648e7a..d0101ebf 100644 --- a/docs/configexamples/zone-policy.rst +++ b/docs/configexamples/zone-policy.rst @@ -1,20 +1,10 @@ -:lastproofread: 2021-06-29 +:lastproofread: 2024-06-14 .. _examples-zone-policy: Zone-Policy example ------------------- -.. note:: Starting from VyOS 1.4-rolling-202308040557, a new firewall - structure can be found on all vyos installations, and zone based firewall is - no longer supported. 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:`firewall-legacy` - chapter. The examples in this section use the legacy firewall configuration - commands, since this feature has been removed in earlier releases. - .. note:: In :vytask:`T2199` the syntax of the zone configuration was changed. The zone configuration moved from ``zone-policy zone <name>`` to ``firewall zone <name>``. @@ -428,4 +418,3 @@ Something like: address ip.of.tunnel.broker } } - diff --git a/docs/configuration/container/index.rst b/docs/configuration/container/index.rst index 4dacc6f4..a1672aa7 100644 --- a/docs/configuration/container/index.rst +++ b/docs/configuration/container/index.rst @@ -133,6 +133,17 @@ Configuration - **always**: Restart containers when they exit, regardless of status, retrying indefinitely +.. cfgcmd:: set container name <name> cpu-quota <num> + + This specifies the number of CPU resources the container can use. + + Default is 0 for unlimited. + For example, 1.25 limits the container to use up to 1.25 cores + worth of CPU time. + This can be a decimal number with up to three decimal places. + + The command translates to "--cpus=<num>" when the container is created. + .. cfgcmd:: set container name <name> memory <MB> Constrain the memory available to the container. @@ -157,6 +168,17 @@ Configuration setdomainame) - **sys-time**: Permission to set system clock +.. cfgcmd:: set container name <name> sysctl parameter <parameter> value <value> + + Set container sysctl values. + + The subset of possible parameters are: + + - Kernel Parameters: kernel.msgmax, kernel.msgmnb, kernel.msgmni, kernel.sem, + kernel.shmall, kernel.shmmax, kernel.shmmni, kernel.shm_rmid_forced + - Parameters beginning with fs.mqueue.* + - Parameters beginning with net.* (only if user-defined network is used) + .. cfgcmd:: set container name <name> label <label> value <value> Add metadata label for this container. diff --git a/docs/configuration/firewall/flowtables.rst b/docs/configuration/firewall/flowtables.rst index e8a5f2e8..ae95a85f 100644 --- a/docs/configuration/firewall/flowtables.rst +++ b/docs/configuration/firewall/flowtables.rst @@ -1,4 +1,4 @@ -:lastproofread: 2023-12-26 +:lastproofread: 2024-06-20 .. _firewall-flowtables-configuration: @@ -85,12 +85,12 @@ Provide a description to the flow table. Creating rules for using flow tables: -.. cfgcmd:: set firewall [ipv4 | ipv4] forward filter rule <1-999999> +.. cfgcmd:: set firewall [ipv4 | ipv6] forward filter rule <1-999999> action offload Create firewall rule in forward chain, and set action to ``offload``. -.. cfgcmd:: set firewall [ipv4 | ipv4] forward filter rule <1-999999> +.. cfgcmd:: set firewall [ipv4 | ipv6] forward filter rule <1-999999> offload-target <flowtable> Create firewall rule in forward chain, and define which flowtbale @@ -142,7 +142,7 @@ Explanation Analysis on what happens for desired connection: - 1. First packet is received on eht0, with destination address 192.0.2.100, + 1. First packet is received on eth0, with destination address 192.0.2.100, protocol tcp and destination port 1122. Assume such destination address is reachable through interface eth1. @@ -159,7 +159,7 @@ Analysis on what happens for desired connection: connection state is **established**, then rule 10 is hit, and a new entry in the flowtable FT01 is added for this connection. - 6. All subsecuent packets will skip traditional path, and will be offloaded + 6. All the following packets will skip traditional path, and will be offloaded and will use the **Fast Path**. Checks diff --git a/docs/configuration/firewall/global-options.rst b/docs/configuration/firewall/global-options.rst index b3f311aa..7c52045e 100644 --- a/docs/configuration/firewall/global-options.rst +++ b/docs/configuration/firewall/global-options.rst @@ -145,3 +145,35 @@ Configuration [emerg | alert | crit | err | warn | notice | info | debug] Set the global setting for related connections. + +VyOS supports setting timeouts for connections according to the +connection type. You can set timeout values for generic connections, for ICMP +connections, UDP connections, or for TCP connections in a number of different +states. + +.. cfgcmd:: set firewall global-options timeout icmp <1-21474836> + :defaultvalue: +.. cfgcmd:: set firewall global-options timeout other <1-21474836> + :defaultvalue: +.. cfgcmd:: set firewall global-options timeout tcp close <1-21474836> + :defaultvalue: +.. cfgcmd:: set firewall global-options timeout tcp close-wait <1-21474836> + :defaultvalue: +.. cfgcmd:: set firewall global-options timeout tcp established <1-21474836> + :defaultvalue: +.. cfgcmd:: set firewall global-options timeout tcp fin-wait <1-21474836> + :defaultvalue: +.. cfgcmd:: set firewall global-options timeout tcp last-ack <1-21474836> + :defaultvalue: +.. cfgcmd:: set firewall global-options timeout tcp syn-recv <1-21474836> + :defaultvalue: +.. cfgcmd:: set firewall global-options timeout tcp syn-sent <1-21474836> + :defaultvalue: +.. cfgcmd:: set firewall global-options timeout tcp time-wait <1-21474836> + :defaultvalue: +.. cfgcmd:: set firewall global-options timeout udp other <1-21474836> + :defaultvalue: +.. cfgcmd:: set firewall global-options timeout udp stream <1-21474836> + :defaultvalue: + + Set the timeout in seconds for a protocol or state.
\ No newline at end of file diff --git a/docs/configuration/firewall/index.rst b/docs/configuration/firewall/index.rst index 1d904901..daf5f116 100644 --- a/docs/configuration/firewall/index.rst +++ b/docs/configuration/firewall/index.rst @@ -26,14 +26,23 @@ firewall are covered below: If the interface where the packet was received isn't part of a bridge, then packet is processed at the **IP Layer**: - * **Prerouting**: several actions can be done in this stage, and currently - these actions are defined in different parts in VyOS configuration. Order - is important, and all these actions are performed before any actions - defined under ``firewall`` section. Relevant configuration that acts in - this stage are: + * **Prerouting**: All packets that are received by the router + are processed in this stage, regardless of the destination of the packet. + Starting from vyos-1.5-rolling-202406120020, a new section was added to + firewall configuration. There are several actions that can be done in this + stage, and currently these actions are also defined in different parts in + VyOS configuration. Order is important, and relevant configuration that + acts in this stage are: + + * **Firewall prerouting**: rules defined under ``set firewall [ipv4 | + ipv6] prerouting raw...``. All rules defined in this section are + processed before connection tracking subsystem. * **Conntrack Ignore**: rules defined under ``set system conntrack ignore - [ipv4 | ipv6] ...``. + [ipv4 | ipv6] ...``. Starting from vyos-1.5-rolling-202406120020, + configuration done in this section can be done in ``firewall [ipv4 | + ipv6] prerouting ...``. For compatibility reasons, this feature is + still present, but it will be removed in the future. * **Policy Route**: rules defined under ``set policy [route | route6] ...``. @@ -67,11 +76,13 @@ packet is processed at the **IP Layer**: new connection originated by a internal process running on VyOS router, such as NTP, or a response to traffic received externally through **input** (for example response to an ssh login attempt to the router). - This includes ipv4 and ipv6 filtering rules, defined in: + This includes ipv4 and ipv6 rules, and two different sections are present: - * ``set firewall ipv4 output filter ...``. + * **Output Prerouting**: ``set firewall [ipv4 | ipv6] output filter ...``. + As described in **Prerouting**, rules defined in this section are + processed before connection tracking subsystem. - * ``set firewall ipv6 output filter ...``. + * **Output Filter**: ``set firewall [ipv4 | ipv6] output filter ...``. * **Postrouting**: as in **Prerouting**, several actions defined in different parts of VyOS configuration are performed in this @@ -120,6 +131,9 @@ The main structure of the VyOS firewall CLI is shown next: + filter - output + filter + + raw + - prerouting + + raw - name + custom_name * ipv6 @@ -129,6 +143,9 @@ The main structure of the VyOS firewall CLI is shown next: + filter - output + filter + + raw + - prerouting + + raw - ipv6-name + custom_name * zone diff --git a/docs/configuration/firewall/ipv4.rst b/docs/configuration/firewall/ipv4.rst index f7f98dc7..39370c86 100644 --- a/docs/configuration/firewall/ipv4.rst +++ b/docs/configuration/firewall/ipv4.rst @@ -31,17 +31,34 @@ of the general structure: + filter - output + filter + + raw + - prerouting + + raw - name + custom_name +First, all traffic is received by the router, and it is processed in the +**prerouting** section. + +This stage includes: + + * **Firewall Prerouting**: commands found under ``set firewall ipv4 + prerouting raw ...`` + * :doc:`Conntrack Ignore</configuration/system/conntrack>`: ``set system + conntrack ignore ipv4...`` + * :doc:`Policy Route</configuration/policy/route>`: commands found under + ``set policy route ...`` + * :doc:`Destination NAT</configuration/nat/nat44>`: commands found under + ``set nat destination ...`` + For transit traffic, which is received by the router and forwarded, base chain is **forward**. A simplified packet flow diagram for transit traffic is shown next: .. figure:: /_static/images/firewall-fwd-packet-flow.png -Where firewall base chain to configure firewall filtering rules for transit -traffic is ``set firewall ipv4 forward filter ...``, which happens in stage 5, +Firewall base chain to configure firewall filtering rules for transit traffic +is ``set firewall ipv4 forward filter ...``, which happens in stage 5, highlighted with red color. For traffic towards the router itself, base chain is **input**, while traffic @@ -52,11 +69,17 @@ router (starting from circle number 6): .. figure:: /_static/images/firewall-input-packet-flow.png -Base chain is for traffic toward the router is ``set firewall ipv4 input +Base chain for traffic towards the router is ``set firewall ipv4 input filter ...`` And base chain for traffic generated by the router is ``set firewall ipv4 -output filter ...`` +output ...``, where two sub-chains are available: **filter** and **raw**: + +* **Output Prerouting**: ``set firewall ipv4 output raw ...``. + As described in **Prerouting**, rules defined in this section are + processed before connection tracking subsystem. +* **Output Filter**: ``set firewall ipv4 output filter ...``. Rules defined + in this section are processed after connection tracking subsystem. .. note:: **Important note about default-actions:** If default action for any base chain is not defined, then the default @@ -709,6 +732,10 @@ geoip) to keep database and rules updated. For example: ``eth2*``. Prepending character ``!`` for inverted matching criteria is also supported. For example ``!eth2`` +.. note:: If an interface is attached to a non-default vrf, when using + **inbound-interface**, vrf name must be used. For example ``set firewall + ipv4 forward filter rule 10 inbound-interface name MGMT`` + .. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> inbound-interface group <iface_group> .. cfgcmd:: set firewall ipv4 input filter rule <1-999999> @@ -730,6 +757,10 @@ geoip) to keep database and rules updated. For example: ``eth2*``. Prepending character ``!`` for inverted matching criteria is also supported. For example ``!eth2`` +.. note:: If an interface is attached to a non-default vrf, when using + **outbound-interface**, real interface name must be used. For example + ``set firewall ipv4 forward filter rule 10 outbound-interface name eth0`` + .. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> outbound-interface group <iface_group> .. cfgcmd:: set firewall ipv4 output filter rule <1-999999> diff --git a/docs/configuration/firewall/ipv6.rst b/docs/configuration/firewall/ipv6.rst index cbf18a7d..511fd51f 100644 --- a/docs/configuration/firewall/ipv6.rst +++ b/docs/configuration/firewall/ipv6.rst @@ -31,17 +31,34 @@ of the general structure: + filter - output + filter + + raw + - prerouting + + raw - name + custom_name +First, all traffic is received by the router, and it is processed in the +**prerouting** section. + +This stage includes: + + * **Firewall Prerouting**: commands found under ``set firewall ipv6 + prerouting raw ...`` + * :doc:`Conntrack Ignore</configuration/system/conntrack>`: ``set system + conntrack ignore ipv6...`` + * :doc:`Policy Route</configuration/policy/route>`: commands found under + ``set policy route6 ...`` + * :doc:`Destination NAT</configuration/nat/nat44>`: commands found under + ``set nat66 destination ...`` + For transit traffic, which is received by the router and forwarded, base chain is **forward**. A simplified packet flow diagram for transit traffic is shown next: .. figure:: /_static/images/firewall-fwd-packet-flow.png -Where firewall base chain to configure firewall filtering rules for transit -traffic is ``set firewall ipv6 forward filter ...``, which happens in stage 5, +Firewall base chain to configure firewall filtering rules for transit traffic +is ``set firewall ipv6 forward filter ...``, which happens in stage 5, highlighted with red color. For traffic towards the router itself, base chain is **input**, while traffic @@ -52,11 +69,17 @@ router (starting from circle number 6): .. figure:: /_static/images/firewall-input-packet-flow.png -Base chain is for traffic toward the router is ``set firewall ipv6 input +Base chain for traffic towards the router is ``set firewall ipv6 input filter ...`` And base chain for traffic generated by the router is ``set firewall ipv6 -output filter ...`` +output filter ...``, where two sub-chains are available: **filter** and **raw**: + +* **Output Prerouting**: ``set firewall ipv6 output raw ...``. + As described in **Prerouting**, rules defined in this section are + processed before connection tracking subsystem. +* **Output Filter**: ``set firewall ipv6 output filter ...``. Rules defined + in this section are processed after connection tracking subsystem. .. note:: **Important note about default-actions:** If default action for any base chain is not defined, then the default @@ -700,6 +723,10 @@ geoip) to keep database and rules updated. For example: ``eth2*``. Prepending character ``!`` for inverted matching criteria is also supported. For example ``!eth2`` +.. note:: If an interface is attached to a non-default vrf, when using + **inbound-interface**, vrf name must be used. For example ``set firewall + ipv6 forward filter rule 10 inbound-interface name MGMT`` + .. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> inbound-interface group <iface_group> .. cfgcmd:: set firewall ipv6 input filter rule <1-999999> @@ -721,6 +748,10 @@ geoip) to keep database and rules updated. For example: ``eth2*``. Prepending character ``!`` for inverted matching criteria is also supported. For example ``!eth2`` +.. note:: If an interface is attached to a non-default vrf, when using + **outbound-interface**, real interface name must be used. For example + ``set firewall ipv6 forward filter rule 10 outbound-interface name eth0`` + .. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> outbound-interface group <iface_group> .. cfgcmd:: set firewall ipv6 output filter rule <1-999999> diff --git a/docs/configuration/highavailability/index.rst b/docs/configuration/highavailability/index.rst index 9158ac1d..93d01364 100644 --- a/docs/configuration/highavailability/index.rst +++ b/docs/configuration/highavailability/index.rst @@ -220,6 +220,10 @@ Verification inet 172.25.0.247/16 scope global eth0v10 valid_lft forever preferred_lft forever +.. warning:: RFC 3768 creates a virtual interface. If you want to apply + the destination NAT rule to the traffic sent to the virtual MAC, set + the created virtual interface as `inbound-interface`. + Global options -------------- diff --git a/docs/configuration/interfaces/ethernet.rst b/docs/configuration/interfaces/ethernet.rst index dd524035..30a13b5b 100644 --- a/docs/configuration/interfaces/ethernet.rst +++ b/docs/configuration/interfaces/ethernet.rst @@ -52,6 +52,14 @@ Ethernet options VyOS default will be `auto`. +.. cfgcmd:: set interface ethernet <interface> ring-buffer rx <value> +.. cfgcmd:: set interface ethernet <interface> ring-buffer tx <value> + + Configures the ring buffer size of the interface. + + The supported values for a specific interface can be obtained + with: `ethtool -g <interface>` + Offloading ---------- @@ -295,5 +303,3 @@ Operation BR margin, min : 0% Vendor SN : FNS092xxxxx Date code : 0506xx - -.. stop_vyoslinter diff --git a/docs/configuration/interfaces/wireless.rst b/docs/configuration/interfaces/wireless.rst index df153763..8a45111e 100644 --- a/docs/configuration/interfaces/wireless.rst +++ b/docs/configuration/interfaces/wireless.rst @@ -36,15 +36,10 @@ Common interface configuration :var0: wireless :var1: wlan0 -Wireless options -================ - -.. cfgcmd:: set interfaces wireless <interface> channel <number> +System Wide configuration +========================= - Channel number (IEEE 802.11), for 2.4Ghz (802.11 b/g/n) channels range from - 1-14. On 5Ghz (802.11 a/h/j/n/ac) channels available are 0, 34 to 173 - -.. cfgcmd:: set interfaces wireless <interface> country-code <cc> +.. cfgcmd:: set system wireless country-code <cc> Country code (ISO/IEC 3166-1). Used to set regulatory domain. Set as needed to indicate country in which device is operating. This can limit available @@ -52,6 +47,14 @@ Wireless options .. note:: This option is mandatory in Access-Point mode. +Wireless options +================ + +.. cfgcmd:: set interfaces wireless <interface> channel <number> + + Channel number (IEEE 802.11), for 2.4Ghz (802.11 b/g/n) channels range from + 1-14. On 5Ghz (802.11 a/h/j/n/ac) channels available are 0, 34 to 173 + .. cfgcmd:: set interfaces wireless <interface> disable-broadcast-ssid Send empty SSID in beacons and ignore probe request frames that do not specify diff --git a/docs/configuration/loadbalancing/reverse-proxy.rst b/docs/configuration/loadbalancing/reverse-proxy.rst index 970e084e..9cb49a7f 100644 --- a/docs/configuration/loadbalancing/reverse-proxy.rst +++ b/docs/configuration/loadbalancing/reverse-proxy.rst @@ -45,6 +45,11 @@ Service Set SSL certificate <name> for service <name> +.. cfgcmd:: set load-balancing reverse-proxy service <name> + http-response-headers <header-name> value <header-value> + + Set custom HTTP headers to be included in all responses + Rules ^^^^^ @@ -113,11 +118,6 @@ Backend Configure backend `<name>` mode TCP or HTTP -.. cfgcmd:: set load-balancing reverse-proxy backend <name> parameters - http-check - - Enable layer 7 HTTP health check - .. cfgcmd:: set load-balancing reverse-proxy backend <name> server <name> address <x.x.x.x> @@ -155,9 +155,40 @@ Backend Configure requests to the backend server to use SSL encryption without validating server certificate +.. cfgcmd:: set load-balancing reverse-proxy backend <name> + http-response-headers <header-name> value <header-value> + + Set custom HTTP headers to be included in all responses using the backend + + +Global +------- + +Global parameters + +.. cfgcmd:: set load-balancing reverse-proxy global-parameters max-connections + <num> + + Limit maximum number of connections + +.. cfgcmd:: set load-balancing reverse-proxy global-parameters ssl-bind-ciphers + <ciphers> + + Limit allowed cipher algorithms used during SSL/TLS handshake + +.. cfgcmd:: set load-balancing reverse-proxy global-parameters tls-version-min + <version> + + Specify the minimum required TLS version 1.2 or 1.3 + + +Health checks +============= + + +HTTP checks +----------- -HTTP health check -^^^^^^^^^^^^^^^^^ For web application providing information about their state HTTP health checks can be used to determine their availability. @@ -180,31 +211,32 @@ checks can be used to determine their availability. expect <condition> Sets the expected result condition for considering a server healthy. + Some possible examples are: * ``status 200`` Expecting a 200 response code * ``status 200-399`` Expecting a non-failure response code * ``string success`` Expecting the string `success` in the response body -Global -------- +TCP checks +---------- -Global parameters +Health checks can also be configured for TCP mode backends. You can configure +protocol aware checks for a range of Layer 7 protocols: -.. cfgcmd:: set load-balancing reverse-proxy global-parameters max-connections - <num> - - Limit maximum number of connections +.. cfgcmd:: set load-balancing reverse-proxy backend <name> health-check <protocol> -.. cfgcmd:: set load-balancing reverse-proxy global-parameters ssl-bind-ciphers - <ciphers> + Available health check protocols: + * ``ldap`` LDAP protocol check. + * ``redis`` Redis protocol check. + * ``mysql`` MySQL protocol check. + * ``pgsql`` PostgreSQL protocol check. + * ``smtp`` SMTP protocol check. - Limit allowed cipher algorithms used during SSL/TLS handshake - -.. cfgcmd:: set load-balancing reverse-proxy global-parameters tls-version-min - <version> - - Specify the minimum required TLS version 1.2 or 1.3 +.. note:: If you specify a server to be checked but do not configure a + protocol, a basic TCP health check will be attempted. A server shall be + deemed online if it responses to a connection attempt with a valid + ``SYN/ACK`` packet. Redirect HTTP to HTTPS @@ -291,6 +323,7 @@ HTTPS. The ``https`` service listens on port 443 with backend ``bk-default`` to handle HTTPS traffic. It uses certificate named ``cert`` for SSL termination. +HSTS header is set with a 1-year expiry, to tell browsers to always use SSL for site. Rule 10 matches requests with the exact URL path ``/.well-known/xxx`` and redirects to location ``/certs/``. @@ -313,6 +346,7 @@ connection limit of 4000 and a minimum TLS version of 1.3. set load-balancing reverse-proxy service https mode 'http' set load-balancing reverse-proxy service https port '443' set load-balancing reverse-proxy service https ssl certificate 'cert' + set load-balancing reverse-proxy service https http-response-headers Strict-Transport-Security value 'max-age=31536000' set load-balancing reverse-proxy service https rule 10 url-path exact '/.well-known/xxx' set load-balancing reverse-proxy service https rule 10 set redirect-location '/certs/' diff --git a/docs/configuration/nat/cgnat.rst b/docs/configuration/nat/cgnat.rst index 70916318..7fc5e03b 100644 --- a/docs/configuration/nat/cgnat.rst +++ b/docs/configuration/nat/cgnat.rst @@ -82,9 +82,10 @@ Configuration Set external source port limits that will be allocated to each subscriber individually. The default value is 2000. -.. cfgcmd:: set nat cgnat pool external <pool-name> range [address | address range | network] +.. cfgcmd:: set nat cgnat pool external <pool-name> range [address | address range | network] [seq] Set the range of external IP addresses for the CGNAT pool. + The sequence is optional; if set, a lower value means higher priority. .. cfgcmd:: set nat cgnat pool internal <pool-name> range [address range | network] @@ -98,6 +99,9 @@ Configuration Set the rule for the translation pool. +.. cfgcmd:: set nat cgnat log-allocation + + Enable logging of IP address and ports allocations. Configuration Examples @@ -134,6 +138,55 @@ Multiple external addresses set nat cgnat rule 10 source pool 'int1' set nat cgnat rule 10 translation pool 'ext1' +External address sequences +----------------------------------- + +.. code-block:: none + + set nat cgnat pool external ext-01 per-user-limit port '16000' + set nat cgnat pool external ext-01 range 203.0.113.1/32 seq '10' + set nat cgnat pool external ext-01 range 192.0.2.1/32 seq '20' + set nat cgnat pool internal int-01 range '100.64.0.0/29' + set nat cgnat rule 10 source pool 'int-01' + set nat cgnat rule 10 translation pool 'ext-01' + + +Operation commands +================== + +.. opcmd:: show nat cgnat allocation + + Show address and port allocations + +.. opcmd:: show nat cgnat allocation external-address <address> + + Show all allocations for an external IP address + +.. opcmd:: show nat cgnat allocation internal-address <address> + + Show all allocations for an internal IP address + +Show CGNAT allocations +---------------------- + +.. code-block:: none + + vyos@vyos:~$ show nat cgnat allocation + Internal IP External IP Port range + ------------- ------------- ------------ + 100.64.0.0 203.0.113.1 1024-17023 + 100.64.0.1 203.0.113.1 17024-33023 + 100.64.0.2 203.0.113.1 33024-49023 + 100.64.0.3 203.0.113.1 49024-65023 + 100.64.0.4 192.0.2.1 1024-17023 + 100.64.0.5 192.0.2.1 17024-33023 + 100.64.0.6 192.0.2.1 33024-49023 + 100.64.0.7 192.0.2.1 49024-65023 + + vyos@vyos:~$ show nat cgnat allocation internal-address 100.64.0.4 + Internal IP External IP Port range + ------------- ------------- ------------ + 100.64.0.4 192.0.2.1 1024-17023 Further Reading diff --git a/docs/configuration/service/monitoring.rst b/docs/configuration/service/monitoring.rst index 245af067..10b4dee2 100644 --- a/docs/configuration/service/monitoring.rst +++ b/docs/configuration/service/monitoring.rst @@ -130,6 +130,36 @@ and logs from your routers. Remote URL +Loki +==== + +Telegraf can be used to send logs to Loki using tags as labels. + +.. cfgcmd:: set service monitoring telegraf loki port <port> + + Remote Loki port + + Default is 3100 + +.. cfgcmd:: set service monitoring telegraf loki url <url> + + Remote Loki url + +.. cfgcmd:: set service monitoring telegraf loki authentication username <username> +.. cfgcmd:: set service monitoring telegraf loki authentication password <password> + + HTTP basic authentication. + + If either is set both must be set. + +.. cfgcmd:: set service monitoring telegraf loki metric-name-label <label> + + Label to use for the metric name when sending metrics. + + If set to an empty string, the label will not be added. + This is NOT recommended, as it makes it impossible to differentiate + between multiple metrics. + Example ======= diff --git a/docs/configuration/system/conntrack.rst b/docs/configuration/system/conntrack.rst index 1401e02e..6d551575 100644 --- a/docs/configuration/system/conntrack.rst +++ b/docs/configuration/system/conntrack.rst @@ -64,39 +64,7 @@ Configure Contrack Timeouts ================= -VyOS supports setting timeouts for connections according to the -connection type. You can set timeout values for generic connections, for ICMP -connections, UDP connections, or for TCP connections in a number of different -states. - -.. cfgcmd:: set system conntrack timeout icmp <1-21474836> - :defaultvalue: -.. cfgcmd:: set system conntrack timeout other <1-21474836> - :defaultvalue: -.. cfgcmd:: set system conntrack timeout tcp close <1-21474836> - :defaultvalue: -.. cfgcmd:: set system conntrack timeout tcp close-wait <1-21474836> - :defaultvalue: -.. cfgcmd:: set system conntrack timeout tcp established <1-21474836> - :defaultvalue: -.. cfgcmd:: set system conntrack timeout tcp fin-wait <1-21474836> - :defaultvalue: -.. cfgcmd:: set system conntrack timeout tcp last-ack <1-21474836> - :defaultvalue: -.. cfgcmd:: set system conntrack timeout tcp syn-recv <1-21474836> - :defaultvalue: -.. cfgcmd:: set system conntrack timeout tcp syn-sent <1-21474836> - :defaultvalue: -.. cfgcmd:: set system conntrack timeout tcp time-wait <1-21474836> - :defaultvalue: -.. cfgcmd:: set system conntrack timeout udp other <1-21474836> - :defaultvalue: -.. cfgcmd:: set system conntrack timeout udp stream <1-21474836> - :defaultvalue: - - Set the timeout in seconds for a protocol or state. - -You can also define custom timeout values to apply to a specific subset of +You can define custom timeout values to apply to a specific subset of connections, based on a packet and flow selector. To do this, you need to create a rule defining the packet and flow selector. @@ -177,6 +145,11 @@ create a rule defining the packet and flow selector. Conntrack ignore rules ====================== +.. note:: **Important note about conntrack ignore rules:** + Starting from vyos-1.5-rolling-202406120020, ignore rules can be defined in + ``set firewall [ipv4 | ipv6] prerouting raw ...``. It's expected that in + the future the conntrack ignore rules will be removed. + Customized ignore rules, based on a packet and flow selector. .. cfgcmd:: set system conntrack ignore [ipv4 | ipv6] rule <1-999999> diff --git a/docs/configuration/trafficpolicy/index.rst b/docs/configuration/trafficpolicy/index.rst index f99c2a66..5414ce77 100644 --- a/docs/configuration/trafficpolicy/index.rst +++ b/docs/configuration/trafficpolicy/index.rst @@ -212,6 +212,56 @@ You can also write a description for a filter: .. note:: IPv6 TCP filters will only match IPv6 packets with no header extension, see https://en.wikipedia.org/wiki/IPv6_packet#Extension_headers +Traffic Match Group +------------------- +In some case where we need to have an organization of our matching selection, +in order to be more flexible and organize with our filter definition. We can +apply traffic match groups, allowing us to create distinct filter groups within +our policy and define various parameters for each group: + +.. code-block:: none + + set qos traffic-match-group <group_name> match <match_name> + Possible completions: + description Description + > ip Match IP protocol header + > ipv6 Match IPv6 protocol header + mark Match on mark applied by firewall + vif Virtual Local Area Network (VLAN) ID for this match + +inherit matches from another group + +.. code-block:: none + + set qos traffic-match-group <group_name> match-group <match_group_name> + +A match group can contain multiple criteria and inherit them in the same policy. + +For example: + +.. code-block:: none + + set qos traffic-match-group Mission-Critical match AF31 ip dscp 'AF31' + set qos traffic-match-group Mission-Critical match AF32 ip dscp 'AF42' + set qos traffic-match-group Mission-Critical match CS3 ip dscp 'CS3' + set qos traffic-match-group Streaming-Video match AF11 ip dscp 'AF11' + set qos traffic-match-group Streaming-Video match AF41 ip dscp 'AF41' + set qos traffic-match-group Streaming-Video match AF43 ip dscp 'AF43' + set qos policy shaper VyOS-HTB class 10 bandwidth '30%' + set qos policy shaper VyOS-HTB class 10 description 'Multimedia' + set qos policy shaper VyOS-HTB class 10 match CS4 ip dscp 'CS4' + set qos policy shaper VyOS-HTB class 10 match-group 'Streaming-Video' + set qos policy shaper VyOS-HTB class 10 priority '1' + set qos policy shaper VyOS-HTB class 10 queue-type 'fair-queue' + set qos policy shaper VyOS-HTB class 20 description 'MC' + set qos policy shaper VyOS-HTB class 20 match-group 'Mission-Critical' + set qos policy shaper VyOS-HTB class 20 priority '2' + set qos policy shaper VyOS-HTB class 20 queue-type 'fair-queue' + set qos policy shaper VyOS-HTB default bandwidth '20%' + set qos policy shaper VyOS-HTB default queue-type 'fq-codel' + +In this example, we can observe that different DSCP criteria are defined based +on our QoS configuration within the same policy group. Default ------- diff --git a/docs/contributing/build-vyos.rst b/docs/contributing/build-vyos.rst index 16eb8ac7..55be147b 100644 --- a/docs/contributing/build-vyos.rst +++ b/docs/contributing/build-vyos.rst @@ -65,10 +65,14 @@ To start, clone the repository to your local machine: $ ./configure --architecture amd64 --build-by "j.randomhacker@vyos.io" $ sudo make iso - # For VyOS 1.4 (sagitta) and VyOS 1.5 (circinus,current) + # For VyOS 1.4 (sagitta) $ sudo make clean $ sudo ./build-vyos-image iso --architecture amd64 --build-by "j.randomhacker@vyos.io" + # For VyOS 1.5 (circinus,current) + $ sudo make clean + $ sudo ./build-vyos-image generic --architecture amd64 --build-by "j.randomhacker@vyos.io" + For the packages required, you can refer to the ``docker/Dockerfile`` file in the repository_. The ``./build-vyos-image`` script will also warn you if any dependencies are missing. @@ -274,10 +278,14 @@ Start the build: vyos_bld@8153428c7e1f:/vyos$ ./configure --architecture amd64 --build-by "j.randomhacker@vyos.io" vyos_bld@8153428c7e1f:/vyos$ sudo make iso - # For VyOS 1.4 (sagitta) For VyOS 1.5 (circinus,current) + # For VyOS 1.4 (sagitta) vyos_bld@8153428c7e1f:/vyos$ sudo make clean vyos_bld@8153428c7e1f:/vyos$ sudo ./build-vyos-image iso --architecture amd64 --build-by "j.randomhacker@vyos.io" + # For VyOS 1.5 (circinus,current) + vyos_bld@8153428c7e1f:/vyos$ sudo make clean + vyos_bld@8153428c7e1f:/vyos$ sudo ./build-vyos-image generic --architecture amd64 --build-by "j.randomhacker@vyos.io" + When the build is successful, the resulting iso can be found inside the ``build`` directory as ``live-image-[architecture].hybrid.iso``. |
