diff options
20 files changed, 461 insertions, 95 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/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 399f2ef5..a1672aa7 100644 --- a/docs/configuration/container/index.rst +++ b/docs/configuration/container/index.rst @@ -168,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/interfaces/wireless.rst b/docs/configuration/interfaces/wireless.rst index b7188f44..d93e983e 100644 --- a/docs/configuration/interfaces/wireless.rst +++ b/docs/configuration/interfaces/wireless.rst @@ -36,14 +36,19 @@ Common interface configuration :var0: wireless :var1: wlan0 -Wireless options -================ +System Wide configuration +========================= -.. cfgcmd:: set interfaces wireless <interface> channel <number> +.. cfgcmd:: set system wireless country-code <cc> - 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. - On 6GHz (802.11 ax) channels range from 1 to 233. + 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 + channels and transmit power. + + .. note:: This option is mandatory in Access-Point mode. + +Wireless options +================ .. cfgcmd:: set system wireless country-code <cc> @@ -53,6 +58,12 @@ Wireless options .. note:: This option is mandatory in Access-Point mode. +.. 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. + On 6GHz (802.11 ax) channels range from 1 to 233. + .. 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 3edc4283..9cb49a7f 100644 --- a/docs/configuration/loadbalancing/reverse-proxy.rst +++ b/docs/configuration/loadbalancing/reverse-proxy.rst @@ -161,8 +161,34 @@ Backend Set custom HTTP headers to be included in all responses using the backend -HTTP health check -^^^^^^^^^^^^^^^^^ +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 +----------- + For web application providing information about their state HTTP health checks can be used to determine their availability. @@ -185,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 -------- - -Global parameters - -.. cfgcmd:: set load-balancing reverse-proxy global-parameters max-connections - <num> - - Limit maximum number of connections +TCP checks +---------- -.. cfgcmd:: set load-balancing reverse-proxy global-parameters ssl-bind-ciphers - <ciphers> +Health checks can also be configured for TCP mode backends. You can configure +protocol aware checks for a range of Layer 7 protocols: - Limit allowed cipher algorithms used during SSL/TLS handshake +.. cfgcmd:: set load-balancing reverse-proxy backend <name> health-check <protocol> -.. cfgcmd:: set load-balancing reverse-proxy global-parameters tls-version-min - <version> + Available health check protocols: + * ``ldap`` LDAP protocol check. + * ``redis`` Redis protocol check. + * ``mysql`` MySQL protocol check. + * ``pgsql`` PostgreSQL protocol check. + * ``smtp`` SMTP protocol check. - 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 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/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``. diff --git a/requirements.txt b/requirements.txt index 08a1fd15..d604873c 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,4 +1,4 @@ -urllib3==2.1.0 +urllib3==2.2.2 Sphinx==7.2.6 sphinx-rtd-theme==2.0.0 sphinx-autobuild==2021.3.14 |
