diff options
Diffstat (limited to 'docs')
48 files changed, 1040 insertions, 464 deletions
diff --git a/docs/_include/interface-ip.txt b/docs/_include/interface-ip.txt index 6359aceb..5163edd8 100644 --- a/docs/_include/interface-ip.txt +++ b/docs/_include/interface-ip.txt @@ -82,7 +82,7 @@ .. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }} {{ var5 }} {{ var6 }} ip enable-arp-accept - Define behavior for gratuitous ARP frames who's IP is not already present in + Define behavior for gratuitous ARP frames whose IP is not already present in the ARP table. If configured create new entries in the ARP table. Both replies and requests type gratuitous arp will trigger the ARP table to be diff --git a/docs/_include/interface-mac.txt b/docs/_include/interface-mac.txt index 03aa6106..9c8c7de5 100644 --- a/docs/_include/interface-mac.txt +++ b/docs/_include/interface-mac.txt @@ -8,4 +8,4 @@ .. code-block:: none - set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} mac '00:01:02:03:04:05'
\ No newline at end of file + set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} mac '00:53:01:02:03:04'
\ No newline at end of file diff --git a/docs/_include/interface-mirror.txt b/docs/_include/interface-mirror.txt index 66d63248..26594984 100644 --- a/docs/_include/interface-mirror.txt +++ b/docs/_include/interface-mirror.txt @@ -1,6 +1,6 @@ SPAN port mirroring can copy the inbound/outbound traffic of the interface to the specified interface, usually the interface can be connected to some special -equipment, such as behavior control system, intrusion detection system and +equipment, such as a behavior control system, intrusion detection system or traffic collector, and can copy all related traffic from this port. The benefit of mirroring the traffic is that the application is isolated from the source traffic and so application processing does not affect the traffic diff --git a/docs/_locale/de/automation.pot b/docs/_locale/de/automation.pot index acd55638..480bfa35 100644 --- a/docs/_locale/de/automation.pot +++ b/docs/_locale/de/automation.pot @@ -781,8 +781,8 @@ msgid "If command ends in a value, it must be inside single quotes." msgstr "If command ends in a value, it must be inside single quotes." #: ../../automation/cloud-init.rst:253 -msgid "If no networking configuration is provided, then dhcp client is going to be enabled on first interface. Bare in mind that this configuration will be inyected at an OS level, so don't expect to find dhcp client configuration on vyos cli. Because of this behavior, in next example lab we will disable dhcp-client configuration on eth0." -msgstr "If no networking configuration is provided, then dhcp client is going to be enabled on first interface. Bare in mind that this configuration will be inyected at an OS level, so don't expect to find dhcp client configuration on vyos cli. Because of this behavior, in next example lab we will disable dhcp-client configuration on eth0." +msgid "If no networking configuration is provided, then dhcp client is going to be enabled on first interface. Bear in mind that this configuration will be injected at an OS level, so don't expect to find dhcp client configuration on vyos cli. Because of this behavior, in next example lab we will disable dhcp-client configuration on eth0." +msgstr "If no networking configuration is provided, then dhcp client is going to be enabled on first interface. Bear in mind that this configuration will be injected at an OS level, so don't expect to find dhcp client configuration on vyos cli. Because of this behavior, in next example lab we will disable dhcp-client configuration on eth0." #: ../../automation/cloud-init.rst:228 msgid "If you encounter problems, verify that the cloud-config document contains valid YAML. Online resources such as https://www.yamllint.com/ provide a simple tool for validating YAML." diff --git a/docs/_locale/de/configuration.pot b/docs/_locale/de/configuration.pot index f0ae9a1d..dc70be5a 100644 --- a/docs/_locale/de/configuration.pot +++ b/docs/_locale/de/configuration.pot @@ -391,8 +391,8 @@ msgid "**Origin check**" msgstr "**Origin check**" #: ../../configuration/firewall/index.rst:64 -msgid "**Output**: stage where traffic that is originated by the router itself can be filtered and controlled. Bare in mind that this traffic can be a new connection originted by a internal process running on VyOS router, such as NTP, or can be a response to traffic received externaly through **inputt** (for example response to an ssh login attempt to the router). This includes ipv4 and ipv6 filtering rules, defined in:" -msgstr "**Output**: stage where traffic that is originated by the router itself can be filtered and controlled. Bare in mind that this traffic can be a new connection originted by a internal process running on VyOS router, such as NTP, or can be a response to traffic received externaly through **inputt** (for example response to an ssh login attempt to the router). This includes ipv4 and ipv6 filtering rules, defined in:" +msgid "**Output**: stage where traffic that is originated by the router itself can be filtered and controlled. Bear in mind that this traffic can be a new connection originted by a internal process running on VyOS router, such as NTP, or can be a response to traffic received externaly through **inputt** (for example response to an ssh login attempt to the router). This includes ipv4 and ipv6 filtering rules, defined in:" +msgstr "**Output**: stage where traffic that is originated by the router itself can be filtered and controlled. Bear in mind that this traffic can be a new connection originted by a internal process running on VyOS router, such as NTP, or can be a response to traffic received externaly through **inputt** (for example response to an ssh login attempt to the router). This includes ipv4 and ipv6 filtering rules, defined in:" #: ../../configuration/firewall/index.rst:65 msgid "**Output**: stage where traffic that originates from the router itself can be filtered and controlled. Bear in mind that this traffic can be a new connection originated by a internal process running on VyOS router, such as NTP, or a response to traffic received externaly through **input** (for example response to an ssh login attempt to the router). This includes ipv4 and ipv6 filtering rules, defined in:" diff --git a/docs/_locale/es/automation.pot b/docs/_locale/es/automation.pot index 1bef6c23..c98faa2f 100644 --- a/docs/_locale/es/automation.pot +++ b/docs/_locale/es/automation.pot @@ -781,7 +781,7 @@ msgid "If command ends in a value, it must be inside single quotes." msgstr "Si el comando termina en un valor, debe estar entre comillas simples." #: ../../automation/cloud-init.rst:253 -msgid "If no networking configuration is provided, then dhcp client is going to be enabled on first interface. Bare in mind that this configuration will be inyected at an OS level, so don't expect to find dhcp client configuration on vyos cli. Because of this behavior, in next example lab we will disable dhcp-client configuration on eth0." +msgid "If no networking configuration is provided, then dhcp client is going to be enabled on first interface. Bear in mind that this configuration will be injected at an OS level, so don't expect to find dhcp client configuration on vyos cli. Because of this behavior, in next example lab we will disable dhcp-client configuration on eth0." msgstr "Si no se proporciona una configuración de red, el cliente dhcp se habilitará en la primera interfaz. Tenga en cuenta que esta configuración se inyectará a nivel del sistema operativo, así que no espere encontrar la configuración del cliente dhcp en vyos cli. Debido a este comportamiento, en el siguiente laboratorio de ejemplo, deshabilitaremos la configuración de dhcp-client en eth0." #: ../../automation/cloud-init.rst:228 diff --git a/docs/_locale/es/configuration.pot b/docs/_locale/es/configuration.pot index b7b3a78a..821ecc6a 100644 --- a/docs/_locale/es/configuration.pot +++ b/docs/_locale/es/configuration.pot @@ -391,8 +391,8 @@ msgid "**Origin check**" msgstr "**Comprobación de origen**" #: ../../configuration/firewall/index.rst:64 -msgid "**Output**: stage where traffic that is originated by the router itself can be filtered and controlled. Bare in mind that this traffic can be a new connection originted by a internal process running on VyOS router, such as NTP, or can be a response to traffic received externaly through **inputt** (for example response to an ssh login attempt to the router). This includes ipv4 and ipv6 filtering rules, defined in:" -msgstr "**Output**: stage where traffic that is originated by the router itself can be filtered and controlled. Bare in mind that this traffic can be a new connection originted by a internal process running on VyOS router, such as NTP, or can be a response to traffic received externaly through **inputt** (for example response to an ssh login attempt to the router). This includes ipv4 and ipv6 filtering rules, defined in:" +msgid "**Output**: stage where traffic that is originated by the router itself can be filtered and controlled. Bear in mind that this traffic can be a new connection originted by a internal process running on VyOS router, such as NTP, or can be a response to traffic received externaly through **inputt** (for example response to an ssh login attempt to the router). This includes ipv4 and ipv6 filtering rules, defined in:" +msgstr "**Output**: stage where traffic that is originated by the router itself can be filtered and controlled. Bear in mind that this traffic can be a new connection originted by a internal process running on VyOS router, such as NTP, or can be a response to traffic received externaly through **inputt** (for example response to an ssh login attempt to the router). This includes ipv4 and ipv6 filtering rules, defined in:" #: ../../configuration/firewall/index.rst:65 msgid "**Output**: stage where traffic that originates from the router itself can be filtered and controlled. Bear in mind that this traffic can be a new connection originated by a internal process running on VyOS router, such as NTP, or a response to traffic received externaly through **input** (for example response to an ssh login attempt to the router). This includes ipv4 and ipv6 filtering rules, defined in:" diff --git a/docs/_locale/ja/automation.pot b/docs/_locale/ja/automation.pot index 741a317b..42bcff7a 100644 --- a/docs/_locale/ja/automation.pot +++ b/docs/_locale/ja/automation.pot @@ -239,7 +239,7 @@ msgstr "2.5 Type the commands :" #: ../../automation/terraform/terraformAZ.rst:44 msgid "2.6 Type the commands :" -msgstr "2.6 Type the commands :" +msgstr "2.6 Type the commands :in" #: ../../automation/terraform/terraformAWS.rst:31 msgid "2 Create a key pair_ and download your .pem key" @@ -781,8 +781,8 @@ msgid "If command ends in a value, it must be inside single quotes." msgstr "If command ends in a value, it must be inside single quotes." #: ../../automation/cloud-init.rst:253 -msgid "If no networking configuration is provided, then dhcp client is going to be enabled on first interface. Bare in mind that this configuration will be inyected at an OS level, so don't expect to find dhcp client configuration on vyos cli. Because of this behavior, in next example lab we will disable dhcp-client configuration on eth0." -msgstr "If no networking configuration is provided, then dhcp client is going to be enabled on first interface. Bare in mind that this configuration will be inyected at an OS level, so don't expect to find dhcp client configuration on vyos cli. Because of this behavior, in next example lab we will disable dhcp-client configuration on eth0." +msgid "If no networking configuration is provided, then dhcp client is going to be enabled on first interface. Bear in mind that this configuration will be injected at an OS level, so don't expect to find dhcp client configuration on vyos cli. Because of this behavior, in next example lab we will disable dhcp-client configuration on eth0." +msgstr "If no networking configuration is provided, then dhcp client is going to be enabled on first interface. Bear in mind that this configuration will be injected at an OS level, so don't expect to find dhcp client configuration on vyos cli. Because of this behavior, in next example lab we will disable dhcp-client configuration on eth0." #: ../../automation/cloud-init.rst:228 msgid "If you encounter problems, verify that the cloud-config document contains valid YAML. Online resources such as https://www.yamllint.com/ provide a simple tool for validating YAML." diff --git a/docs/_locale/ja/configuration.pot b/docs/_locale/ja/configuration.pot index 3518562b..19d6802f 100644 --- a/docs/_locale/ja/configuration.pot +++ b/docs/_locale/ja/configuration.pot @@ -391,8 +391,8 @@ msgid "**Origin check**" msgstr "**Origin check**" #: ../../configuration/firewall/index.rst:64 -msgid "**Output**: stage where traffic that is originated by the router itself can be filtered and controlled. Bare in mind that this traffic can be a new connection originted by a internal process running on VyOS router, such as NTP, or can be a response to traffic received externaly through **inputt** (for example response to an ssh login attempt to the router). This includes ipv4 and ipv6 filtering rules, defined in:" -msgstr "**Output**: stage where traffic that is originated by the router itself can be filtered and controlled. Bare in mind that this traffic can be a new connection originted by a internal process running on VyOS router, such as NTP, or can be a response to traffic received externaly through **inputt** (for example response to an ssh login attempt to the router). This includes ipv4 and ipv6 filtering rules, defined in:" +msgid "**Output**: stage where traffic that is originated by the router itself can be filtered and controlled. Bear in mind that this traffic can be a new connection originted by a internal process running on VyOS router, such as NTP, or can be a response to traffic received externaly through **inputt** (for example response to an ssh login attempt to the router). This includes ipv4 and ipv6 filtering rules, defined in:" +msgstr "**Output**: stage where traffic that is originated by the router itself can be filtered and controlled. Bear in mind that this traffic can be a new connection originted by a internal process running on VyOS router, such as NTP, or can be a response to traffic received externaly through **inputt** (for example response to an ssh login attempt to the router). This includes ipv4 and ipv6 filtering rules, defined in:" #: ../../configuration/firewall/index.rst:65 msgid "**Output**: stage where traffic that originates from the router itself can be filtered and controlled. Bear in mind that this traffic can be a new connection originated by a internal process running on VyOS router, such as NTP, or a response to traffic received externaly through **input** (for example response to an ssh login attempt to the router). This includes ipv4 and ipv6 filtering rules, defined in:" diff --git a/docs/_locale/pt/automation.pot b/docs/_locale/pt/automation.pot index 6494fae3..198dea36 100644 --- a/docs/_locale/pt/automation.pot +++ b/docs/_locale/pt/automation.pot @@ -781,8 +781,8 @@ msgid "If command ends in a value, it must be inside single quotes." msgstr "If command ends in a value, it must be inside single quotes." #: ../../automation/cloud-init.rst:253 -msgid "If no networking configuration is provided, then dhcp client is going to be enabled on first interface. Bare in mind that this configuration will be inyected at an OS level, so don't expect to find dhcp client configuration on vyos cli. Because of this behavior, in next example lab we will disable dhcp-client configuration on eth0." -msgstr "If no networking configuration is provided, then dhcp client is going to be enabled on first interface. Bare in mind that this configuration will be inyected at an OS level, so don't expect to find dhcp client configuration on vyos cli. Because of this behavior, in next example lab we will disable dhcp-client configuration on eth0." +msgid "If no networking configuration is provided, then dhcp client is going to be enabled on first interface. Bear in mind that this configuration will be injected at an OS level, so don't expect to find dhcp client configuration on vyos cli. Because of this behavior, in next example lab we will disable dhcp-client configuration on eth0." +msgstr "If no networking configuration is provided, then dhcp client is going to be enabled on first interface. Bear in mind that this configuration will be injected at an OS level, so don't expect to find dhcp client configuration on vyos cli. Because of this behavior, in next example lab we will disable dhcp-client configuration on eth0." #: ../../automation/cloud-init.rst:228 msgid "If you encounter problems, verify that the cloud-config document contains valid YAML. Online resources such as https://www.yamllint.com/ provide a simple tool for validating YAML." diff --git a/docs/_locale/pt/configuration.pot b/docs/_locale/pt/configuration.pot index 098a9f01..f73095f6 100644 --- a/docs/_locale/pt/configuration.pot +++ b/docs/_locale/pt/configuration.pot @@ -391,8 +391,8 @@ msgid "**Origin check**" msgstr "**Origin check**" #: ../../configuration/firewall/index.rst:64 -msgid "**Output**: stage where traffic that is originated by the router itself can be filtered and controlled. Bare in mind that this traffic can be a new connection originted by a internal process running on VyOS router, such as NTP, or can be a response to traffic received externaly through **inputt** (for example response to an ssh login attempt to the router). This includes ipv4 and ipv6 filtering rules, defined in:" -msgstr "**Output**: stage where traffic that is originated by the router itself can be filtered and controlled. Bare in mind that this traffic can be a new connection originted by a internal process running on VyOS router, such as NTP, or can be a response to traffic received externaly through **inputt** (for example response to an ssh login attempt to the router). This includes ipv4 and ipv6 filtering rules, defined in:" +msgid "**Output**: stage where traffic that is originated by the router itself can be filtered and controlled. Bear in mind that this traffic can be a new connection originted by a internal process running on VyOS router, such as NTP, or can be a response to traffic received externaly through **inputt** (for example response to an ssh login attempt to the router). This includes ipv4 and ipv6 filtering rules, defined in:" +msgstr "**Output**: stage where traffic that is originated by the router itself can be filtered and controlled. Bear in mind that this traffic can be a new connection originted by a internal process running on VyOS router, such as NTP, or can be a response to traffic received externaly through **inputt** (for example response to an ssh login attempt to the router). This includes ipv4 and ipv6 filtering rules, defined in:" #: ../../configuration/firewall/index.rst:65 msgid "**Output**: stage where traffic that originates from the router itself can be filtered and controlled. Bear in mind that this traffic can be a new connection originated by a internal process running on VyOS router, such as NTP, or a response to traffic received externaly through **input** (for example response to an ssh login attempt to the router). This includes ipv4 and ipv6 filtering rules, defined in:" diff --git a/docs/_locale/uk/automation.pot b/docs/_locale/uk/automation.pot index 96148754..e8f049f7 100644 --- a/docs/_locale/uk/automation.pot +++ b/docs/_locale/uk/automation.pot @@ -781,7 +781,7 @@ msgid "If command ends in a value, it must be inside single quotes." msgstr "Якщо команда закінчується значенням, воно має бути в одинарних лапках." #: ../../automation/cloud-init.rst:253 -msgid "If no networking configuration is provided, then dhcp client is going to be enabled on first interface. Bare in mind that this configuration will be inyected at an OS level, so don't expect to find dhcp client configuration on vyos cli. Because of this behavior, in next example lab we will disable dhcp-client configuration on eth0." +msgid "If no networking configuration is provided, then dhcp client is going to be enabled on first interface. Bear in mind that this configuration will be injected at an OS level, so don't expect to find dhcp client configuration on vyos cli. Because of this behavior, in next example lab we will disable dhcp-client configuration on eth0." msgstr "Якщо конфігурація мережі не надається, клієнт dhcp буде ввімкнено на першому інтерфейсі. Майте на увазі, що цю конфігурацію буде введено на рівні ОС, тому не очікуйте знайти конфігурацію клієнта dhcp у vyos cli. Через таку поведінку в наступному прикладі лабораторної роботи ми вимкнемо конфігурацію dhcp-клієнта на eth0." #: ../../automation/cloud-init.rst:228 diff --git a/docs/_locale/uk/configuration.pot b/docs/_locale/uk/configuration.pot index 3f9e7bd2..5195191f 100644 --- a/docs/_locale/uk/configuration.pot +++ b/docs/_locale/uk/configuration.pot @@ -391,8 +391,8 @@ msgid "**Origin check**" msgstr "**Перевірка походження**" #: ../../configuration/firewall/index.rst:64 -msgid "**Output**: stage where traffic that is originated by the router itself can be filtered and controlled. Bare in mind that this traffic can be a new connection originted by a internal process running on VyOS router, such as NTP, or can be a response to traffic received externaly through **inputt** (for example response to an ssh login attempt to the router). This includes ipv4 and ipv6 filtering rules, defined in:" -msgstr "**Output**: stage where traffic that is originated by the router itself can be filtered and controlled. Bare in mind that this traffic can be a new connection originted by a internal process running on VyOS router, such as NTP, or can be a response to traffic received externaly through **inputt** (for example response to an ssh login attempt to the router). This includes ipv4 and ipv6 filtering rules, defined in:" +msgid "**Output**: stage where traffic that is originated by the router itself can be filtered and controlled. Bear in mind that this traffic can be a new connection originted by a internal process running on VyOS router, such as NTP, or can be a response to traffic received externaly through **inputt** (for example response to an ssh login attempt to the router). This includes ipv4 and ipv6 filtering rules, defined in:" +msgstr "**Output**: stage where traffic that is originated by the router itself can be filtered and controlled. Bear in mind that this traffic can be a new connection originted by a internal process running on VyOS router, such as NTP, or can be a response to traffic received externaly through **inputt** (for example response to an ssh login attempt to the router). This includes ipv4 and ipv6 filtering rules, defined in:" #: ../../configuration/firewall/index.rst:65 msgid "**Output**: stage where traffic that originates from the router itself can be filtered and controlled. Bear in mind that this traffic can be a new connection originated by a internal process running on VyOS router, such as NTP, or a response to traffic received externaly through **input** (for example response to an ssh login attempt to the router). This includes ipv4 and ipv6 filtering rules, defined in:" 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/automation/cloud-init.rst b/docs/automation/cloud-init.rst index 0b9ee207..f2ecaa77 100644 --- a/docs/automation/cloud-init.rst +++ b/docs/automation/cloud-init.rst @@ -1,4 +1,4 @@ -:lastproofread: 2021-07-12 +:lastproofread: 2024-07-03 .. _cloud-init: @@ -251,8 +251,8 @@ Most important keys that needs to be considered: * Networking configurations shouldn't be passed in user-data file. * If no networking configuration is provided, then dhcp client is going to be - enabled on first interface. Bare in mind that this configuration will be - inyected at an OS level, so don't expect to find dhcp client configuration + enabled on first interface. Bear in mind that this configuration will be + injected at an OS level, so don't expect to find dhcp client configuration on vyos cli. Because of this behavior, in next example lab we will disable dhcp-client configuration on eth0. 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..8be82e1b 100644 --- a/docs/configuration/container/index.rst +++ b/docs/configuration/container/index.rst @@ -1,10 +1,10 @@ -:lastproofread: 2022-06-10 +:lastproofread: 2024-07-03 ######### Container ######### -The VyOS container implementation is based on `Podman<https://podman.io/>` as +The VyOS container implementation is based on `Podman <https://podman.io/>`_ as a deamonless container engine. ************* @@ -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/bridge.rst b/docs/configuration/firewall/bridge.rst index f84fd456..2e3d3634 100644 --- a/docs/configuration/firewall/bridge.rst +++ b/docs/configuration/firewall/bridge.rst @@ -1,4 +1,4 @@ -:lastproofread: 2023-11-08 +:lastproofread: 2024-07-03 .. _firewall-configuration: @@ -12,13 +12,13 @@ Bridge Firewall Configuration Overview ******** -In this section there's useful information of all firewall configuration that -can be done regarding bridge, and appropriate op-mode commands. +In this section there's useful information on all firewall configuration that +can be done regarding bridges, and appropriate op-mode commands. Configuration commands covered in this section: .. cfgcmd:: set firewall bridge ... -From main structure defined in :doc:`Firewall Overview</configuration/firewall/index>` +From the main structure defined in :doc:`Firewall Overview</configuration/firewall/index>` in this section you can find detailed information only for the next part of the general structure: @@ -41,7 +41,7 @@ For traffic that needs to be forwarded internally by the bridge, base chain is is **forward**, and it's base command for filtering is ``set firewall bridge forward filter ...``, which happens in stage 4, highlighted with red color. -Custom bridge firewall chains can be create with command ``set firewall bridge +Custom bridge firewall chains can be created with the command ``set firewall bridge name <name> ...``. In order to use such custom chain, a rule with action jump, and the appropriate target should be defined in a base chain. @@ -55,9 +55,9 @@ and the appropriate target should be defined in a base chain. Bridge Rules ************ -For firewall filtering, firewall rules needs to be created. Each rule is +For firewall filtering, firewall rules need to be created. Each rule is numbered, has an action to apply if the rule is matched, and the ability -to specify multiple criteria matchers. Data packets go through the rules +to specify multiple matching criteria. Data packets go through the rules from 1 - 999999, so order is crucial. At the first match the action of the rule will be executed. @@ -65,7 +65,7 @@ Actions ======= If a rule is defined, then an action must be defined for it. This tells the -firewall what to do if all criteria matchers defined for such rule do match. +firewall what to do if all matching criterea in the rule are met. In firewall bridge rules, the action can be: @@ -101,7 +101,7 @@ In firewall bridge rules, the action can be: queue <0-65535> To be used only when action is set to ``queue``. Use this command to specify - queue target to use. Queue range is also supported. + the queue target to use. Queue range is also supported. .. cfgcmd:: set firewall bridge forward filter rule <1-999999> queue-options bypass @@ -121,7 +121,7 @@ In firewall bridge rules, the action can be: distribute packets between several queues. Also, **default-action** is an action that takes place whenever a packet does -not match any rule in it's chain. For base chains, possible options for +not match any rule in its' chain. For base chains, possible options for **default-action** are **accept** or **drop**. .. cfgcmd:: set firewall bridge forward filter default-action @@ -129,10 +129,10 @@ not match any rule in it's chain. For base chains, possible options for .. cfgcmd:: set firewall bridge name <name> default-action [accept | continue | drop | jump | queue | return] - This set the default action of the rule-set if no rule matched a packet - criteria. If default-action is set to ``jump``, then + This sets the default action of the rule-set if a packet does not match + any of the rules in that chain. If default-action is set to ``jump``, then ``default-jump-target`` is also needed. Note that for base chains, default - action can only be set to ``accept`` or ``drop``, while on custom chain, + action can only be set to ``accept`` or ``drop``, while on custom chains more actions are available. .. cfgcmd:: set firewall bridge name <name> default-jump-target <text> @@ -141,9 +141,9 @@ not match any rule in it's chain. For base chains, possible options for command to specify jump target for default rule. .. note:: **Important note about default-actions:** - If default action for any base chain is not defined, then the default - action is set to **accept** for that chain. For custom chains, if default - action is not defined, then the default-action is set to **drop**. + If the default action for any base chain is not defined, then the default + action is set to **accept** for that chain. For custom chains, if the + default action is not defined, then the default-action is set to **drop**. Firewall Logs ============= @@ -155,7 +155,7 @@ log options can be defined. .. cfgcmd:: set firewall bridge name <name> rule <1-999999> log Enable logging for the matched packet. If this configuration command is not - present, then log is not enabled. + present, then the log is not enabled. .. cfgcmd:: set firewall bridge forward filter default-log .. cfgcmd:: set firewall bridge name <name> default-log @@ -170,14 +170,15 @@ log options can be defined. log-options level [emerg | alert | crit | err | warn | notice | info | debug] - Define log-level. Only applicable if rule log is enable. + Define log-level. Only applicable if rule log is enabled. .. cfgcmd:: set firewall bridge forward filter rule <1-999999> log-options group <0-65535> .. cfgcmd:: set firewall bridge name <name> rule <1-999999> log-options group <0-65535> - Define log group to send message to. Only applicable if rule log is enable. + Define the log group to send messages to. Only applicable if rule log is + enabled. .. cfgcmd:: set firewall bridge forward filter rule <1-999999> log-options snapshot-length <0-9000> @@ -185,15 +186,16 @@ log options can be defined. log-options snapshot-length <0-9000> Define length of packet payload to include in netlink message. Only - applicable if rule log is enable and log group is defined. + applicable if rule log is enabled and the log group is defined. .. cfgcmd:: set firewall bridge forward filter rule <1-999999> log-options queue-threshold <0-65535> .. cfgcmd:: set firewall bridge name <name> rule <1-999999> log-options queue-threshold <0-65535> - Define number of packets to queue inside the kernel before sending them to - userspace. Only applicable if rule log is enable and log group is defined. + Define the number of packets to queue inside the kernel before sending them + to userspace. Only applicable if rule log is enabled and the log group is + defined. Firewall Description ==================== @@ -207,7 +209,7 @@ For reference, a description can be defined for every defined custom chain. Rule Status =========== -When defining a rule, it is enable by default. In some cases, it is useful to +When defining a rule, it is enabled by default. In some cases, it is useful to just disable the rule, rather than removing it. .. cfgcmd:: set firewall bridge forward filter rule <1-999999> disable diff --git a/docs/configuration/firewall/flowtables.rst b/docs/configuration/firewall/flowtables.rst index e8a5f2e8..915bf39d 100644 --- a/docs/configuration/firewall/flowtables.rst +++ b/docs/configuration/firewall/flowtables.rst @@ -1,4 +1,4 @@ -:lastproofread: 2023-12-26 +:lastproofread: 2024-07-02 .. _firewall-flowtables-configuration: @@ -12,12 +12,12 @@ Flowtables Firewall Configuration Overview ******** -In this section there's useful information of all firewall configuration that +In this section there's useful information on all firewall configuration that can be done regarding flowtables. .. cfgcmd:: set firewall flowtables ... -From main structure defined in +From the main structure defined in :doc:`Firewall Overview</configuration/firewall/index>` in this section you can find detailed information only for the next part of the general structure: @@ -30,7 +30,7 @@ of the general structure: + ... -Flowtables allows you to define a fastpath through the flowtable datapath. +Flowtables allow you to define a fastpath through the flowtable datapath. The flowtable supports for the layer 3 IPv4 and IPv6 and the layer 4 TCP and UDP protocols. @@ -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 @@ -107,10 +107,10 @@ Things to be considered in this setup: * Minimum firewall ruleset is provided, which includes some filtering rules, and appropriate rules for using flowtable offload capabilities. -As described, first packet will be evaluated by all the firewall path, so +As described, the first packet will be evaluated by the firewall path, so a desired connection should be explicitly accepted. Same thing should be taken into account for traffic in reverse order. In most cases state policies are -used in order to accept connection in reverse patch. +used in order to accept a connection in the reverse path. We will only accept traffic coming from interface eth0, protocol tcp and destination port 1122. All other traffic trespassing the router should be @@ -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. Firstly, a 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. @@ -151,22 +151,22 @@ Analysis on what happens for desired connection: 3. Rule 110 is hit, so connection is accepted. - 4. Once answer from server 192.0.2.100 is seen in opposite direction, + 4. Once an answer from server 192.0.2.100 is seen in opposite direction, connection state will be triggered to **established**, so this reply is accepted in rule 20. - 5. Second packet for this connection is received by the router. Since + 5. The second packet for this connection is received by the router. Since 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 - and will use the **Fast Path**. + 6. All the following packets will skip the traditional path, will be + offloaded and use the **Fast Path**. Checks ------ -It's time to check conntrack table, to see if any connection was accepted, -and if was properly offloaded +It's time to check the conntrack table, to see if any connections were accepted, +and if it was properly offloaded .. code-block:: none diff --git a/docs/configuration/firewall/global-options.rst b/docs/configuration/firewall/global-options.rst index b3f311aa..87fb755d 100644 --- a/docs/configuration/firewall/global-options.rst +++ b/docs/configuration/firewall/global-options.rst @@ -1,4 +1,4 @@ -:lastproofread: 2023-12-26 +:lastproofread: 2024-07-03 .. _firewall-global-options-configuration: @@ -25,7 +25,7 @@ Configuration .. cfgcmd:: set firewall global-options all-ping [enable | disable] By default, when VyOS receives an ICMP echo request packet destined for - itself, it will answer with an ICMP echo reply, unless you avoid it + itself, it will answer with an ICMP echo reply, unless you prevent it through its firewall. With the firewall you can set rules to accept, drop or reject ICMP in, @@ -55,7 +55,7 @@ Configuration .. cfgcmd:: set firewall global-options broadcast-ping [enable | disable] - This setting enable or disable the response of icmp broadcast + This setting enables or disables the response to icmp broadcast messages. The following system parameter will be altered: * ``net.ipv4.icmp_echo_ignore_broadcasts`` @@ -63,8 +63,8 @@ Configuration .. cfgcmd:: set firewall global-options ip-src-route [enable | disable] .. cfgcmd:: set firewall global-options ipv6-src-route [enable | disable] - This setting handle if VyOS accept packets with a source route - option. The following system parameter will be altered: + This setting handles if VyOS accepts packets with a source route + option. The following system parameters will be altered: * ``net.ipv4.conf.all.accept_source_route`` * ``net.ipv6.conf.all.accept_source_route`` @@ -73,22 +73,22 @@ Configuration .. cfgcmd:: set firewall global-options ipv6-receive-redirects [enable | disable] - enable or disable of ICMPv4 or ICMPv6 redirect messages accepted - by VyOS. The following system parameter will be altered: + Enable or disable ICMPv4 or ICMPv6 redirect messages being accepted by + VyOS. The following system parameters will be altered: * ``net.ipv4.conf.all.accept_redirects`` * ``net.ipv6.conf.all.accept_redirects`` .. cfgcmd:: set firewall global-options send-redirects [enable | disable] - enable or disable ICMPv4 redirect messages send by VyOS + Enable or disable ICMPv4 redirect messages being sent by VyOS The following system parameter will be altered: * ``net.ipv4.conf.all.send_redirects`` .. cfgcmd:: set firewall global-options log-martians [enable | disable] - enable or disable the logging of martian IPv4 packets. + Enable or disable the logging of martian IPv4 packets. The following system parameter will be altered: * ``net.ipv4.conf.all.log_martians`` @@ -103,7 +103,7 @@ Configuration .. cfgcmd:: set firewall global-options syn-cookies [enable | disable] - Enable or Disable if VyOS use IPv4 TCP SYN Cookies. + Enable or disable if VyOS uses IPv4 TCP SYN Cookies. The following system parameter will be altered: * ``net.ipv4.tcp_syncookies`` @@ -111,7 +111,7 @@ Configuration .. cfgcmd:: set firewall global-options twa-hazards-protection [enable | disable] - Enable or Disable VyOS to be :rfc:`1337` conform. + Enable or Disable VyOS to be :rfc:`1337` conformant. The following system parameter will be altered: * ``net.ipv4.tcp_rfc1337`` @@ -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/groups.rst b/docs/configuration/firewall/groups.rst index 6111650a..fa32b98e 100644 --- a/docs/configuration/firewall/groups.rst +++ b/docs/configuration/firewall/groups.rst @@ -1,4 +1,4 @@ -:lastproofread: 2023-11-08 +:lastproofread: 2024-07-03 .. _firewall-groups-configuration: @@ -18,8 +18,7 @@ matcher, and/or as inbound/outbound in the case of interface group. Address Groups ============== -In an **address group** a single IP address or IP address ranges are -defined. +In an **address group** a single IP address or IP address range is defined. .. cfgcmd:: set firewall group address-group <name> address [address | address range] @@ -43,7 +42,7 @@ Network Groups While **network groups** accept IP networks in CIDR notation, specific IP addresses can be added as a 32-bit prefix. If you foresee the need -to add a mix of addresses and networks, the network group is +to add a mix of addresses and networks, then a network group is recommended. .. cfgcmd:: set firewall group network-group <name> network <CIDR> @@ -197,9 +196,9 @@ Commands used for this task are: .. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> add-address-to-group source-address address-group <name> -Also, specific timeout can be defined per rule. In case rule gets a hit, -source or destinatination address will be added to the group, and this -element will remain in the group until timeout expires. If no timeout +Also, specific timeouts can be defined per rule. In case rule gets a hit, +a source or destinatination address will be added to the group, and this +element will remain in the group until the timeout expires. If no timeout is defined, then the element will remain in the group until next reboot, or until a new commit that changes firewall configuration is done. @@ -324,7 +323,7 @@ A 4 step port knocking example is shown next: set firewall ipv4 input filter rule 99 protocol 'tcp' set firewall ipv4 input filter rule 99 source group dynamic-address-group 'ALLOWED' -Before testing, we can check members of firewall groups: +Before testing, we can check the members of firewall groups: .. code-block:: none @@ -339,7 +338,7 @@ Before testing, we can check members of firewall groups: [edit] vyos@vyos# -With this configuration, in order to get ssh access to the router, user +With this configuration, in order to get ssh access to the router, the user needs to: 1. Generate a new TCP connection with destination port 9990. As shown next, @@ -390,7 +389,7 @@ a new entry was added to dynamic firewall group **ALLOWED** [edit] vyos@vyos# -4. Now user can connect through ssh to the router (assuming ssh is configured). +4. Now the user can connect through ssh to the router (assuming ssh is configured). ************** Operation-mode diff --git a/docs/configuration/firewall/index.rst b/docs/configuration/firewall/index.rst index 1d904901..58e3463b 100644 --- a/docs/configuration/firewall/index.rst +++ b/docs/configuration/firewall/index.rst @@ -1,4 +1,4 @@ -:lastproofread: 2023-11-23 +:lastproofread: 2024-07-03 ######## Firewall @@ -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 + the firewall configuration. There are several actions that can be done in + this stage, and currently these actions are also defined in different + parts of the VyOS configuration. Order is important, and the 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] ...``. @@ -41,9 +50,9 @@ packet is processed at the **IP Layer**: * **Destination NAT**: rules defined under ``set [nat | nat66] destination...``. - * **Destination is the router?**: choose appropriate path based on + * **Destination is the router?**: choose an appropriate path based on destination IP address. Transit forward continues to **forward**, - while traffic that destination IP address is configured on the router + while traffic where the destination IP address is configured on the router continues to **input**. * **Input**: stage where traffic destined for the router itself can be @@ -64,14 +73,16 @@ packet is processed at the **IP Layer**: * **Output**: stage where traffic that originates from the router itself can be filtered and controlled. Bear in mind that this traffic can be a - new connection originated by a internal process running on VyOS router, + new connection originated by a internal process running on the 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 @@ -164,10 +181,10 @@ Zone-based firewall zone With zone-based firewalls a new concept was implemented, in addition to the -standard in and out traffic flows, a local flow was added. This local was for -traffic originating and destined to the router itself. Which means additional -rules were required to secure the firewall itself from the network, in -addition to the existing inbound and outbound rules from the traditional +standard in and out traffic flows, a local flow was added. This local flow was +for traffic originating and destined to the router itself. Which means that +additional rules were required to secure the firewall itself from the network, +in addition to the existing inbound and outbound rules from the traditional concept above. To configure VyOS with the diff --git a/docs/configuration/firewall/ipv4.rst b/docs/configuration/firewall/ipv4.rst index f7f98dc7..abae31a5 100644 --- a/docs/configuration/firewall/ipv4.rst +++ b/docs/configuration/firewall/ipv4.rst @@ -1,4 +1,4 @@ -:lastproofread: 2023-11-08 +:lastproofread: 2024-07-03 .. _firewall-ipv4-configuration: @@ -10,13 +10,13 @@ IPv4 Firewall Configuration Overview ******** -In this section there's useful information of all firewall configuration that +In this section there's useful information on all firewall configuration that can be done regarding IPv4, and appropriate op-mode commands. Configuration commands covered in this section: .. cfgcmd:: set firewall ipv4 ... -From main structure defined in +From the main structure defined in :doc:`Firewall Overview</configuration/firewall/index>` in this section you can find detailed information only for the next part of the general structure: @@ -31,37 +31,60 @@ of the general structure: + filter - output + filter + + raw + - prerouting + + raw - name + custom_name -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: +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, the 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, -highlighted with red color. +The base firewall chain to configure filtering rules for transit traffic +is ``set firewall ipv4 forward filter ...``, which happens in stage 5, +highlighted in the color red. -For traffic towards the router itself, base chain is **input**, while traffic -originated by the router, base chain is **output**. +For traffic towards the router itself, the base chain is **input**, while +traffic originated by the router has the base chain **output**. A new simplified packet flow diagram is shown next, which shows the path for traffic destined to the router itself, and traffic generated by the 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 +The 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 ...`` +And the base chain for traffic generated by the router is ``set firewall ipv4 +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 - action is set to **accept** for that chain. For custom chains, if default - action is not defined, then the default-action is set to **drop** + If a default action for any base chain is not defined, then the default + action is set to **accept** for that chain. For custom chains, if the + default action is not defined, then the default-action is set to **drop** Custom firewall chains can be created, with commands ``set firewall ipv4 name <name> ...``. In order to use @@ -72,9 +95,9 @@ should be defined in a base chain. Firewall - IPv4 Rules ********************* -For firewall filtering, firewall rules needs to be created. Each rule is +For firewall filtering, firewall rules need to be created. Each rule is numbered, has an action to apply if the rule is matched, and the ability -to specify multiple criteria matchers. Data packets go through the rules +to specify multiple matching criteria. Data packets go through the rules from 1 - 999999, so order is crucial. At the first match the action of the rule will be executed. @@ -82,7 +105,7 @@ Actions ======= If a rule is defined, then an action must be defined for it. This tells the -firewall what to do if all criteria matchers defined for such rule do match. +firewall what to do if all of the criteria defined for that rule match. The action can be : @@ -112,8 +135,8 @@ The action can be : .. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> action [accept | continue | drop | jump | queue | reject | return] - This required setting defines the action of the current rule. If action is - set to jump, then jump-target is also needed. + This required setting defines the action of the current rule. If the action + is set to jump, then a jump-target is also needed. .. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> jump-target <text> @@ -125,7 +148,7 @@ The action can be : jump-target <text> To be used only when action is set to ``jump``. Use this command to specify - jump target. + the jump target. .. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> queue <0-65535> @@ -137,7 +160,7 @@ The action can be : queue <0-65535> To be used only when action is set to ``queue``. Use this command to specify - queue target to use. Queue range is also supported. + the queue target to use. Queue range is also supported. .. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> queue-options bypass @@ -148,7 +171,7 @@ The action can be : .. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> queue-options bypass - To be used only when action is set to ``queue``. Use this command to let + To be used only when action is set to ``queue``. Use this command to let the packet go through firewall when no userspace software is connected to the queue. @@ -177,21 +200,21 @@ not match any rule in it's chain. For base chains, possible options for .. cfgcmd:: set firewall ipv4 name <name> default-action [accept | drop | jump | queue | reject | return] - This set the default action of the rule-set if no rule matched a packet - criteria. If default-action is set to ``jump``, then - ``default-jump-target`` is also needed. Note that for base chains, default - action can only be set to ``accept`` or ``drop``, while on custom chain, - more actions are available. + This sets the default action of the rule-set if a packet does not match the + criteria of any rule. If default-action is set to ``jump``, then + ``default-jump-target`` is also needed. Note that for base chains, the + default action can only be set to ``accept`` or ``drop``, while on custom + chains, more actions are available. .. cfgcmd:: set firewall ipv4 name <name> default-jump-target <text> To be used only when ``default-action`` is set to ``jump``. Use this - command to specify jump target for default rule. + command to specify the jump target for the default rule. .. note:: **Important note about default-actions:** - If default action for any base chain is not defined, then the default - action is set to **accept** for that chain. For custom chains, if default - action is not defined, then the default-action is set to **drop**. + If the default action for any base chain is not defined, then the default + action is set to **accept** for that chain. For custom chains if a default + action is not defined then the default-action is set to **drop**. Firewall Logs ============= @@ -205,7 +228,7 @@ log options can be defined. .. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> log Enable logging for the matched packet. If this configuration command is not - present, then log is not enabled. + present, then the log is not enabled. .. cfgcmd:: set firewall ipv4 forward filter default-log .. cfgcmd:: set firewall ipv4 input filter default-log @@ -228,7 +251,7 @@ log options can be defined. log-options level [emerg | alert | crit | err | warn | notice | info | debug] - Define log-level. Only applicable if rule log is enable. + Define log-level. Only applicable if rule log is enabled. .. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> log-options group <0-65535> @@ -239,7 +262,8 @@ log options can be defined. .. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> log-options group <0-65535> - Define log group to send message to. Only applicable if rule log is enable. + Define the log group to send messages to. Only applicable if rule log is + enabled. .. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> log-options snapshot-length <0-9000> @@ -250,8 +274,8 @@ log options can be defined. .. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> log-options snapshot-length <0-9000> - Define length of packet payload to include in netlink message. Only - applicable if rule log is enable and log group is defined. + Define the length of packet payload to include in a netlink message. Only + applicable if rule log is enabled and log group is defined. .. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> log-options queue-threshold <0-65535> @@ -262,8 +286,8 @@ log options can be defined. .. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> log-options queue-threshold <0-65535> - Define number of packets to queue inside the kernel before sending them to - userspace. Only applicable if rule log is enable and log group is defined. + Define the number of packets to queue inside the kernel before sending them + to userspace. Only applicable if rule log is enabled and log group is defined. Firewall Description ==================== @@ -288,7 +312,7 @@ every defined custom chain. Rule Status =========== -When defining a rule, it is enable by default. In some cases, it is useful to +When defining a rule, it is enabled by default. In some cases, it is useful to just disable the rule, rather than removing it. .. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> disable @@ -312,7 +336,7 @@ There are a lot of matching criteria against which the packet can be tested. .. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> connection-status nat [destination | source] - Match criteria based on nat connection status. + Match based on nat connection status. .. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> connection-mark <1-2147483647> @@ -323,7 +347,7 @@ There are a lot of matching criteria against which the packet can be tested. .. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> connection-mark <1-2147483647> - Match criteria based on connection mark. + Match based on connection mark. .. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> conntrack-helper <module> @@ -422,8 +446,8 @@ There are a lot of matching criteria against which the packet can be tested. .. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> destination fqdn <fqdn> - Specify a Fully Qualified Domain Name as source/destination matcher. Ensure - router is able to resolve such dns query. + Specify a Fully Qualified Domain Name as source/destination to match. Ensure + that the router is able to resolve this dns query. .. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> source geoip country-code <country> @@ -480,14 +504,13 @@ geoip) to keep database and rules updated. .. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> source mac-address <mac-address> - Only in the source criteria, you can specify a mac-address. + You can only specify a source mac-address to match. .. code-block:: none set firewall ipv4 input filter rule 100 source mac-address 00:53:00:11:22:33 set firewall ipv4 input filter rule 101 source mac-address !00:53:00:aa:12:34 - .. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> source port [1-65535 | portname | start-end] .. cfgcmd:: set firewall ipv4 input filter rule <1-999999> @@ -506,8 +529,7 @@ geoip) to keep database and rules updated. .. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> destination port [1-65535 | portname | start-end] - A port can be set with a port number or a name which is here - defined: ``/etc/services``. + A port can be set by number or name as defined in ``/etc/services``. .. code-block:: none @@ -536,8 +558,8 @@ geoip) to keep database and rules updated. .. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> destination group address-group <name | !name> - Use a specific address-group. Prepend character ``!`` for inverted matching - criteria. + Use a specific address-group. Prepending the character ``!`` to invert the + criteria to match is also supported. .. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> source group dynamic-address-group <name | !name> @@ -557,8 +579,8 @@ geoip) to keep database and rules updated. .. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> destination group dynamic-address-group <name | !name> - Use a specific dynamic-address-group. Prepend character ``!`` for inverted - matching criteria. + Use a specific dynamic-address-group. Prepending the character ``!`` to + invert the criteria to match is also supported. .. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> source group network-group <name | !name> @@ -578,8 +600,8 @@ geoip) to keep database and rules updated. .. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> destination group network-group <name | !name> - Use a specific network-group. Prepend character ``!`` for inverted matching - criteria. + Use a specific network-group. Prepending the character ``!`` to invert the + criteria to match is also supported. .. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> source group port-group <name | !name> @@ -599,8 +621,8 @@ geoip) to keep database and rules updated. .. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> destination group port-group <name | !name> - Use a specific port-group. Prepend character ``!`` for inverted matching - criteria. + Use a specific port-group. Prepending the character ``!`` to invert the + criteria to match is also supported. .. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> source group domain-group <name | !name> @@ -620,8 +642,8 @@ geoip) to keep database and rules updated. .. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> destination group domain-group <name | !name> - Use a specific domain-group. Prepend character ``!`` for inverted matching - criteria. + Use a specific domain-group. Prepending the character ``!`` to invert the + criteria to match is also supported. .. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> source group mac-group <name | !name> @@ -641,8 +663,8 @@ geoip) to keep database and rules updated. .. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> destination group mac-group <name | !name> - Use a specific mac-group. Prepend character ``!`` for inverted matching - criteria. + Use a specific mac-group. Prepending the character ``!`` to invert the + criteria to match is also supported. .. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> dscp [0-63 | start-end] @@ -673,7 +695,7 @@ geoip) to keep database and rules updated. .. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> fragment [match-frag | match-non-frag] - Match based on fragment criteria. + Match based on fragmentation. .. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> icmp [code | type] <0-255> @@ -695,7 +717,7 @@ geoip) to keep database and rules updated. .. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> icmp type-name <text> - Match based on icmp type-name criteria. Use tab for information + Match based on icmp type-name. Use tab for information about what **type-name** criteria are supported. .. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> @@ -706,8 +728,12 @@ geoip) to keep database and rules updated. inbound-interface name <iface> Match based on inbound interface. Wildcard ``*`` can be used. - For example: ``eth2*``. Prepending character ``!`` for inverted matching - criteria is also supported. For example ``!eth2`` + For example: ``eth2*``. Prepending the character ``!`` to invert the + criteria to match is also supported. For example ``!eth2`` + +.. note:: If an interface is attached to a non-default vrf, when using + **inbound-interface**, the 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> @@ -716,8 +742,8 @@ geoip) to keep database and rules updated. .. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> inbound-interface group <iface_group> - Match based on inbound interface group. Prepending character ``!`` for - inverted matching criteria is also supported. For example ``!IFACE_GROUP`` + Match based on the inbound interface group. Prepending the character ``!`` + to invert the criteria to match is also supported. For example ``!IFACE_GROUP`` .. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> outbound-interface name <iface> @@ -727,8 +753,12 @@ geoip) to keep database and rules updated. outbound-interface name <iface> Match based on outbound interface. Wildcard ``*`` can be used. - For example: ``eth2*``. Prepending character ``!`` for inverted matching - criteria is also supported. For example ``!eth2`` + For example: ``eth2*``. Prepending the character ``!`` to invert the + criteria to match is also supported. For example ``!eth2`` + +.. note:: If an interface is attached to a non-default vrf, when using + **outbound-interface**, the 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> @@ -737,8 +767,8 @@ geoip) to keep database and rules updated. .. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> outbound-interface group <iface_group> - Match based on outbound interface group. Prepending character ``!`` for - inverted matching criteria is also supported. For example ``!IFACE_GROUP`` + Match based on outbound interface group. Prepending the character ``!`` to + invert the criteria to match is also supported. For example ``!IFACE_GROUP`` .. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> ipsec [match-ipsec | match-none] @@ -749,7 +779,7 @@ geoip) to keep database and rules updated. .. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> ipsec [match-ipsec | match-none] - Match based on ipsec criteria. + Match based on ipsec. .. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> limit burst <0-4294967295> @@ -792,7 +822,7 @@ geoip) to keep database and rules updated. .. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> packet-length-exclude <text> - Match based on packet length criteria. Multiple values from 1 to 65535 + Match based on the packet length. Multiple values from 1 to 65535 and ranges are supported. .. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> @@ -804,7 +834,7 @@ geoip) to keep database and rules updated. .. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> packet-type [broadcast | host | multicast | other] - Match based on packet type criteria. + Match based on the packet type. .. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> protocol [<text> | <0-255> | all | tcp_udp] @@ -815,10 +845,9 @@ geoip) to keep database and rules updated. .. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> protocol [<text> | <0-255> | all | tcp_udp] - Match a protocol criteria. A protocol number or a name which is here - defined: ``/etc/protocols``. + Match based on protocol number or name as defined in ``/etc/protocols``. Special names are ``all`` for all protocols and ``tcp_udp`` for tcp and udp - based packets. The ``!`` negate the selected protocol. + based packets. The ``!`` negates the selected protocol. .. code-block:: none @@ -843,7 +872,7 @@ geoip) to keep database and rules updated. .. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> recent time [second | minute | hour] - Match bases on recently seen sources. + Match based on recently seen sources. .. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> tcp flags [not] <text> @@ -927,8 +956,8 @@ geoip) to keep database and rules updated. .. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> ttl <eq | gt | lt> <0-255> - Match time to live parameter, where 'eq' stands for 'equal'; 'gt' stands for - 'greater than', and 'lt' stands for 'less than'. + Match the time to live parameter, where 'eq' stands for 'equal'; 'gt' stands + for 'greater than', and 'lt' stands for 'less than'. .. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> recent count <1-255> @@ -963,7 +992,7 @@ Synproxy connections .. cfgcmd:: set firewall ipv4 [input | forward] filter rule <1-999999> synproxy tcp mss <501-65535> - Set TCP-MSS (maximum segment size) for the connection + Set the TCP-MSS (maximum segment size) for the connection .. cfgcmd:: set firewall ipv4 [input | forward] filter rule <1-999999> synproxy tcp window-scale <1-14> @@ -997,7 +1026,6 @@ Requirements to enable synproxy: set firewall ipv4 input filter rule 1000 action 'drop' set firewall ipv4 input filter rule 1000 state invalid - *********************** Operation-mode Firewall *********************** @@ -1007,7 +1035,7 @@ Rule-set overview .. opcmd:: show firewall - This will show you a basic firewall overview, for all ruleset, and not + This will show you a basic firewall overview, for all rule-sets, and not only for ipv4 .. code-block:: none diff --git a/docs/configuration/firewall/ipv6.rst b/docs/configuration/firewall/ipv6.rst index cbf18a7d..5f526dac 100644 --- a/docs/configuration/firewall/ipv6.rst +++ b/docs/configuration/firewall/ipv6.rst @@ -1,4 +1,4 @@ -:lastproofread: 2023-11-08 +:lastproofread: 2024-07-03 .. _firewall-ipv6-configuration: @@ -10,13 +10,13 @@ IPv6 Firewall Configuration Overview ******** -In this section there's useful information of all firewall configuration that +In this section there's useful information on all firewall configuration that can be done regarding IPv6, and appropriate op-mode commands. Configuration commands covered in this section: .. cfgcmd:: set firewall ipv6 ... -From main structure defined in +From the main structure defined in :doc:`Firewall Overview</configuration/firewall/index>` in this section you can find detailed information only for the next part of the general structure: @@ -31,37 +31,60 @@ of the general structure: + filter - output + filter + + raw + - prerouting + + raw - name + custom_name -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: +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, the 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, -highlighted with red color. +The base firewall chain to configure filtering rules for transit traffic +is ``set firewall ipv6 forward filter ...``, which happens in stage 5, +highlighted in the color red. -For traffic towards the router itself, base chain is **input**, while traffic -originated by the router, base chain is **output**. +For traffic towards the router itself, the base chain is **input**, while +traffic originated by the router has the base chain **output**. A new simplified packet flow diagram is shown next, which shows the path for traffic destined to the router itself, and traffic generated by the 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 +The 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 ...`` +And the base chain for traffic generated by the router is ``set firewall ipv6 +output ...``, 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 - action is set to **accept** for that chain. For custom chains, if default - action is not defined, then the default-action is set to **drop** + If a default action for any base chain is not defined, then the default + action is set to **accept** for that chain. For custom chains, if the + default action is not defined, then the default-action is set to **drop** Custom firewall chains can be created, with commands ``set firewall ipv6 name <name> ...``. In order to use @@ -72,9 +95,9 @@ should be defined in a base chain. Firewall - IPv6 Rules ****************************** -For firewall filtering, firewall rules needs to be created. Each rule is +For firewall filtering, firewall rules need to be created. Each rule is numbered, has an action to apply if the rule is matched, and the ability -to specify multiple criteria matchers. Data packets go through the rules +to specify multiple matching criteria. Data packets go through the rules from 1 - 999999, so order is crucial. At the first match the action of the rule will be executed. @@ -82,7 +105,7 @@ Actions ======= If a rule is defined, then an action must be defined for it. This tells the -firewall what to do if all criteria matchers defined for such rule do match. +firewall what to do if all of the criteria defined for that rule match. The action can be : @@ -112,8 +135,8 @@ The action can be : .. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> action [accept | continue | drop | jump | queue | reject | return] - This required setting defines the action of the current rule. If action is - set to jump, then jump-target is also needed. + This required setting defines the action of the current rule. If the action + is set to jump, then a jump-target is also needed. .. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> jump-target <text> @@ -125,7 +148,7 @@ The action can be : jump-target <text> To be used only when action is set to ``jump``. Use this command to specify - jump target. + the jump target. .. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> queue <0-65535> @@ -137,7 +160,7 @@ The action can be : queue <0-65535> To be used only when action is set to ``queue``. Use this command to specify - queue target to use. Queue range is also supported. + the queue target to use. Queue range is also supported. .. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> queue-options bypass @@ -148,7 +171,7 @@ The action can be : .. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> queue-options bypass - To be used only when action is set to ``queue``. Use this command to let + To be used only when action is set to ``queue``. Use this command to let the packet go through firewall when no userspace software is connected to the queue. @@ -177,21 +200,21 @@ not match any rule in it's chain. For base chains, possible options for .. cfgcmd:: set firewall ipv6 name <name> default-action [accept | drop | jump | queue | reject | return] - This set the default action of the rule-set if no rule matched a packet - criteria. If default-action is set to ``jump``, then - ``default-jump-target`` is also needed. Note that for base chains, default - action can only be set to ``accept`` or ``drop``, while on custom chain, - more actions are available. + This sets the default action of the rule-set if a packet does not match the + criteria of any rule. If default-action is set to ``jump``, then + ``default-jump-target`` is also needed. Note that for base chains, the + default action can only be set to ``accept`` or ``drop``, while on custom + chains, more actions are available. .. cfgcmd:: set firewall ipv6 name <name> default-jump-target <text> To be used only when ``default-action`` is set to ``jump``. Use this - command to specify jump target for default rule. + command to specify the jump target for the default rule. .. note:: **Important note about default-actions:** - If default action for any base chain is not defined, then the default - action is set to **accept** for that chain. For custom chains, if default - action is not defined, then the default-action is set to **drop**. + If the default action for any base chain is not defined, then the default + action is set to **accept** for that chain. For custom chains if a default + action is not defined then the default-action is set to **drop**. Firewall Logs ============= @@ -205,7 +228,7 @@ log options can be defined. .. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> log Enable logging for the matched packet. If this configuration command is not - present, then log is not enabled. + present, then the log is not enabled. .. cfgcmd:: set firewall ipv6 forward filter default-log .. cfgcmd:: set firewall ipv6 input filter default-log @@ -228,7 +251,7 @@ log options can be defined. log-options level [emerg | alert | crit | err | warn | notice | info | debug] - Define log-level. Only applicable if rule log is enable. + Define log-level. Only applicable if rule log is enabled. .. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> log-options group <0-65535> @@ -239,7 +262,8 @@ log options can be defined. .. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> log-options group <0-65535> - Define log group to send message to. Only applicable if rule log is enable. + Define the log group to send messages to. Only applicable if rule log is + enabled. .. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> log-options snapshot-length <0-9000> @@ -250,8 +274,8 @@ log options can be defined. .. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> log-options snapshot-length <0-9000> - Define length of packet payload to include in netlink message. Only - applicable if rule log is enable and log group is defined. + Define the length of packet payload to include in a netlink message. Only + applicable if rule log is enabled and log group is defined. .. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> log-options queue-threshold <0-65535> @@ -262,8 +286,8 @@ log options can be defined. .. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> log-options queue-threshold <0-65535> - Define number of packets to queue inside the kernel before sending them to - userspace. Only applicable if rule log is enable and log group is defined. + Define the number of packets to queue inside the kernel before sending them + to userspace. Only applicable if rule log is enabled and log group is defined. Firewall Description ==================== @@ -288,7 +312,7 @@ every defined custom chain. Rule Status =========== -When defining a rule, it is enable by default. In some cases, it is useful to +When defining a rule, it is enabled by default. In some cases, it is useful to just disable the rule, rather than removing it. .. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> disable @@ -312,7 +336,7 @@ There are a lot of matching criteria against which the packet can be tested. .. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> connection-status nat [destination | source] - Match criteria based on nat connection status. + Match based on nat connection status. .. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> connection-mark <1-2147483647> @@ -323,7 +347,7 @@ There are a lot of matching criteria against which the packet can be tested. .. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> connection-mark <1-2147483647> - Match criteria based on connection mark. + Match based on connection mark. .. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> source address [address | addressrange | CIDR] @@ -343,9 +367,8 @@ There are a lot of matching criteria against which the packet can be tested. .. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> destination address [address | addressrange | CIDR] - Match criteria based on source and/or destination address. This is similar - to the network groups part, but here you are able to negate the matching - addresses. + Match based on source and/or destination address. This is similar to the + network groups part, but here you are able to negate the matching addresses. .. code-block:: none @@ -410,8 +433,8 @@ There are a lot of matching criteria against which the packet can be tested. .. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> destination fqdn <fqdn> - Specify a Fully Qualified Domain Name as source/destination matcher. Ensure - router is able to resolve such dns query. + Specify a Fully Qualified Domain Name as source/destination to match. Ensure + that the router is able to resolve this dns query. .. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> source geoip country-code <country> @@ -468,7 +491,7 @@ geoip) to keep database and rules updated. .. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> source mac-address <mac-address> - Only in the source criteria, you can specify a mac-address. + You can only specify a source mac-address to match. .. code-block:: none @@ -493,8 +516,7 @@ geoip) to keep database and rules updated. .. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> destination port [1-65535 | portname | start-end] - A port can be set with a port number or a name which is here - defined: ``/etc/services``. + A port can be set by number or name as defined in ``/etc/services``. .. code-block:: none @@ -527,8 +549,8 @@ geoip) to keep database and rules updated. .. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> destination group address-group <name | !name> - Use a specific address-group. Prepend character ``!`` for inverted matching - criteria. + Use a specific address-group. Prepending the character ``!`` to invert the + criteria to match is also supported. .. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> source group dynamic-address-group <name | !name> @@ -548,8 +570,8 @@ geoip) to keep database and rules updated. .. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> destination group dynamic-address-group <name | !name> - Use a specific dynamic-address-group. Prepend character ``!`` for inverted - matching criteria. + Use a specific dynamic-address-group. Prepending the character ``!`` to + invert the criteria to match is also supported. .. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> source group network-group <name | !name> @@ -569,8 +591,8 @@ geoip) to keep database and rules updated. .. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> destination group network-group <name | !name> - Use a specific network-group. Prepend character ``!`` for inverted matching - criteria. + Use a specific network-group. Prepending the character ``!`` to invert the + criteria to match is also supported. .. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> source group port-group <name | !name> @@ -590,8 +612,8 @@ geoip) to keep database and rules updated. .. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> destination group port-group <name | !name> - Use a specific port-group. Prepend character ``!`` for inverted matching - criteria. + Use a specific port-group. Prepending the character ``!`` to invert the + criteria to match is also supported. .. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> source group domain-group <name | !name> @@ -611,8 +633,8 @@ geoip) to keep database and rules updated. .. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> destination group domain-group <name | !name> - Use a specific domain-group. Prepend character ``!`` for inverted matching - criteria. + Use a specific domain-group. Prepending the character ``!`` to invert the + criteria to match is also supported. .. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> source group mac-group <name | !name> @@ -632,8 +654,8 @@ geoip) to keep database and rules updated. .. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> destination group mac-group <name | !name> - Use a specific mac-group. Prepend character ``!`` for inverted matching - criteria. + Use a specific mac-group. Prepending the character ``!`` to invert the + criteria to match is also supported. .. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> dscp [0-63 | start-end] @@ -664,7 +686,7 @@ geoip) to keep database and rules updated. .. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> fragment [match-frag | match-non-frag] - Match based on fragment criteria. + Match based on fragmentation. .. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> icmpv6 [code | type] <0-255> @@ -686,7 +708,7 @@ geoip) to keep database and rules updated. .. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> icmpv6 type-name <text> - Match based on icmpv6 type-name criteria. Use tab for information + Match based on icmpv6 type-name. Use tab for information about what **type-name** criteria are supported. .. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> @@ -697,8 +719,12 @@ geoip) to keep database and rules updated. inbound-interface name <iface> Match based on inbound interface. Wildcard ``*`` can be used. - For example: ``eth2*``. Prepending character ``!`` for inverted matching - criteria is also supported. For example ``!eth2`` + For example: ``eth2*``. Prepending the character ``!`` to invert the + criteria to match is also supported. For example ``!eth2`` + +.. note:: If an interface is attached to a non-default vrf, when using + **inbound-interface**, the 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> @@ -707,8 +733,8 @@ geoip) to keep database and rules updated. .. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> inbound-interface group <iface_group> - Match based on inbound interface group. Prepending character ``!`` for - inverted matching criteria is also supported. For example ``!IFACE_GROUP`` + Match based on the inbound interface group. Prepending the character ``!`` + to invert the criteria to match is also supported. For example ``!IFACE_GROUP`` .. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> outbound-interface name <iface> @@ -718,8 +744,12 @@ geoip) to keep database and rules updated. outbound-interface name <iface> Match based on outbound interface. Wildcard ``*`` can be used. - For example: ``eth2*``. Prepending character ``!`` for inverted matching - criteria is also supported. For example ``!eth2`` + For example: ``eth2*``. Prepending the character ``!`` to invert the + criteria to match is also supported. For example ``!eth2`` + +.. note:: If an interface is attached to a non-default vrf, when using + **outbound-interface**, the 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> @@ -728,8 +758,8 @@ geoip) to keep database and rules updated. .. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> outbound-interface group <iface_group> - Match based on outbound interface group. Prepending character ``!`` for - inverted matching criteria is also supported. For example ``!IFACE_GROUP`` + Match based on outbound interface group. Prepending the character ``!`` to + invert the criteria to match is also supported. For example ``!IFACE_GROUP`` .. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> ipsec [match-ipsec | match-none] @@ -740,7 +770,7 @@ geoip) to keep database and rules updated. .. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> ipsec [match-ipsec | match-none] - Match based on ipsec criteria. + Match based on ipsec. .. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> limit burst <0-4294967295> @@ -783,7 +813,7 @@ geoip) to keep database and rules updated. .. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> packet-length-exclude <text> - Match based on packet length criteria. Multiple values from 1 to 65535 + Match based on the packet length. Multiple values from 1 to 65535 and ranges are supported. .. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> @@ -795,7 +825,7 @@ geoip) to keep database and rules updated. .. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> packet-type [broadcast | host | multicast | other] - Match based on packet type criteria. + Match based on the packet type. .. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> protocol [<text> | <0-255> | all | tcp_udp] @@ -806,10 +836,9 @@ geoip) to keep database and rules updated. .. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> protocol [<text> | <0-255> | all | tcp_udp] - Match a protocol criteria. A protocol number or a name which is here - defined: ``/etc/protocols``. + Match based on protocol number or name as defined in ``/etc/protocols``. Special names are ``all`` for all protocols and ``tcp_udp`` for tcp and udp - based packets. The ``!`` negate the selected protocol. + based packets. The ``!`` negates the selected protocol. .. code-block:: none @@ -917,7 +946,7 @@ geoip) to keep database and rules updated. .. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> hop-limit <eq | gt | lt> <0-255> - Match hop-limit parameter, where 'eq' stands for 'equal'; 'gt' stands for + Match the hop-limit parameter, where 'eq' stands for 'equal'; 'gt' stands for 'greater than', and 'lt' stands for 'less than'. .. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> @@ -953,7 +982,7 @@ Synproxy connections .. cfgcmd:: set firewall ipv6 [input | forward] filter rule <1-999999> synproxy tcp mss <501-65535> - Set TCP-MSS (maximum segment size) for the connection + Set the TCP-MSS (maximum segment size) for the connection .. cfgcmd:: set firewall ipv6 [input | forward] filter rule <1-999999> synproxy tcp window-scale <1-14> @@ -996,7 +1025,8 @@ Rule-set overview .. opcmd:: show firewall - This will show you a basic firewall overview + This will show you a basic firewall overview, for all rule-sets, and not + only for ipv6 .. code-block:: none diff --git a/docs/configuration/firewall/zone.rst b/docs/configuration/firewall/zone.rst index f71ad8c1..73ce0a4d 100644 --- a/docs/configuration/firewall/zone.rst +++ b/docs/configuration/firewall/zone.rst @@ -1,4 +1,4 @@ -:lastproofread: 2023-11-01 +:lastproofread: 2024-07-03 .. _firewall-zone: @@ -11,9 +11,9 @@ Overview ******** .. note:: Starting from VyOS 1.4-rolling-202308040557, a new firewall - structure can be found on all VyOS installations. Zone based firewall was - removed in that version, but re introduced in VyOS 1.4 and 1.5. All - versions built after 2023-10-22 has this feature. + structure can be found on all VyOS installations. The Zone based firewall + was removed in that version, but re introduced in VyOS 1.4 and 1.5. All + versions built after 2023-10-22 have this feature. Documentation for most of the new firewall CLI can be found in the `firewall <https://docs.vyos.io/en/latest/configuration/firewall/general.html>`_ @@ -22,13 +22,13 @@ Overview :doc:`legacy firewall configuration </configuration/firewall/general-legacy>` chapter. -In this section there's useful information of all firewall configuration that -is needed for zone-based firewall. +In this section there's useful information on all firewall configuration that +is needed for the zone-based firewall. Configuration commands covered in this section: .. cfgcmd:: set firewall zone ... -From main structure defined in +From the main structure defined in :doc:`Firewall Overview</configuration/firewall/index>` in this section you can find detailed information only for the next part of the general structure: @@ -53,7 +53,7 @@ Key Points: interface can be assigned to only a single zone. * All traffic to and from an interface within a zone is permitted. * All traffic between zones is affected by existing policies -* Traffic cannot flow between zone member interface and any interface that is +* Traffic cannot flow between a zone member interface and any interface that is not a zone member. * You need 2 separate firewalls to define traffic: one for each direction. @@ -129,7 +129,7 @@ Operation-mode .. opcmd:: show firewall zone-policy - This will show you a basic summary of zones configuration. + This will show you a basic summary of the zone configuration. .. code-block:: none 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/bridge.rst b/docs/configuration/interfaces/bridge.rst index e69a6e26..5e79107b 100644 --- a/docs/configuration/interfaces/bridge.rst +++ b/docs/configuration/interfaces/bridge.rst @@ -1,4 +1,4 @@ -:lastproofread: 2021-06-30 +:lastproofread: 2024-07-04 .. _bridge-interface: @@ -155,9 +155,8 @@ VLAN Options native-vlan <vlan-id> Set the native VLAN ID flag of the interface. When a data packet without a - VLAN tag enters the port, the data packet will be forced to add a tag of a - specific vlan id. When the vlan id flag flows out, the tag of the vlan id - will be stripped + VLAN tag enters the port, the data packet will have a specific vlan id added + to it. When the packet flows out, the native vlan tag will be stripped. Example: Set `eth0` member port to be native VLAN 2 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/geneve.rst b/docs/configuration/interfaces/geneve.rst index bf8b0920..a0a46a95 100644 --- a/docs/configuration/interfaces/geneve.rst +++ b/docs/configuration/interfaces/geneve.rst @@ -16,7 +16,7 @@ entirely. GENEVE is designed to support network virtualization use cases, where tunnels are typically established to act as a backplane between the virtual switches residing in hypervisors, physical switches, or middleboxes or other appliances. -An arbitrary IP network can be used as an underlay although Clos networks - A +An arbitrary IP network can be used as an underlay through Clos networks - A technique for composing network fabrics larger than a single switch while maintaining non-blocking bandwidth across connection points. ECMP is used to divide traffic across the multiple links and switches that constitute the @@ -41,9 +41,33 @@ Configuration Common interface configuration ============================== -.. cmdinclude:: /_include/interface-common-without-dhcp.txt - :var0: geneve - :var1: gnv0 +.. cmdinclude:: /_include/interface-address.txt + :var0: geneve + :var1: gnv0 + +.. cmdinclude:: /_include/interface-description.txt + :var0: geneve + :var1: gnv0 + +.. cmdinclude:: /_include/interface-disable.txt + :var0: geneve + :var1: gnv0 + +.. cmdinclude:: /_include/interface-mac.txt + :var0: geneve + :var1: gnv0 + +.. cmdinclude:: /_include/interface-mtu.txt + :var0: geneve + :var1: gnv0 + +.. cmdinclude:: /_include/interface-ip.txt + :var0: geneve + :var1: gnv0 + +.. cmdinclude:: /_include/interface-ipv6.txt + :var0: geneve + :var1: gnv0 GENEVE options ============== diff --git a/docs/configuration/interfaces/openvpn.rst b/docs/configuration/interfaces/openvpn.rst index f51dfa94..1dfe1fc5 100644 --- a/docs/configuration/interfaces/openvpn.rst +++ b/docs/configuration/interfaces/openvpn.rst @@ -1,4 +1,4 @@ -:lastproofread: 2021-07-05 +:lastproofread: 2024-07-04 .. _openvpn: @@ -9,8 +9,8 @@ OpenVPN Traditionally hardware routers implement IPsec exclusively due to relative ease of implementing it in hardware and insufficient CPU power for doing encryption in software. Since VyOS is a software router, this is less of a -concern. OpenVPN has been widely used on UNIX platform for a long time and is -a popular option for remote access VPN, though it's also capable of +concern. OpenVPN has been widely used on the UNIX platform for a long time and +is a popular option for remote access VPN, though it's also capable of site-to-site connections. Advantages of OpenVPN are: @@ -45,14 +45,15 @@ remains a relatively obscure feature, and many router appliances still don't support it. However, it's very useful for quickly setting up tunnels between routers. -As of VyOS 1.4, OpenVPN site-to-site mode can use either pre-shared keys or x.509 certificates. +As of VyOS 1.4, OpenVPN site-to-site mode can use either pre-shared keys or +x.509 certificates. -The pre-shared key mode is deprecated and will be removed from future OpenVPN versions, -so VyOS will have to remove support for that option as well. The reason is that using pre-shared keys -is significantly less secure than using TLS. +The pre-shared key mode is deprecated and will be removed from future OpenVPN +versions, so VyOS will have to remove support for that option as well. The +reason is that using pre-shared keys is significantly less secure than using TLS. -We'll configure OpenVPN using self-signed certificates, and then discuss the legacy -pre-shared key mode. +We'll configure OpenVPN using self-signed certificates, and then discuss the +legacy pre-shared key mode. In both cases, we will use the following settings: @@ -168,10 +169,11 @@ Remote Configuration: Pre-shared keys =============== -Until VyOS 1.4, the only option for site-to-site OpenVPN without PKI was to use pre-shared keys. -That option is still available but it is deprecated and will be removed in the future. -However, if you need to set up a tunnel to an older VyOS version or a system with older OpenVPN, -you need to still need to know how to use it. +Until VyOS 1.4, the only option for site-to-site OpenVPN without PKI was to use +pre-shared keys. That option is still available but it is deprecated and will +be removed in the future. However, if you need to set up a tunnel to an older +VyOS version or a system with older OpenVPN, you need to still need to know how +to use it. First, you need to generate a key by running ``run generate pki openvpn shared-secret install <name>`` from configuration mode. You can use any name, we will use ``s2s``. @@ -311,11 +313,11 @@ not come up. Firewall policy can also be applied to the tunnel interface for `local`, `in`, and `out` directions and functions identically to ethernet interfaces. -If making use of multiple tunnels, OpenVPN must have a way to distinguish -between different tunnels aside from the pre-shared-key. This is either by -referencing IP address or port number. One option is to dedicate a public IP -to each tunnel. Another option is to dedicate a port number to each tunnel -(e.g. 1195,1196,1197...). +If you're making use of multiple tunnels, OpenVPN must have a way to +distinguish between different tunnels aside from the pre-shared-key. This is +done either by referencing IP addresses or port numbers. One option is to +dedicate a public IP to each tunnel. Another option is to dedicate a port +number to each tunnel (e.g. 1195,1196,1197...). OpenVPN status can be verified using the `show openvpn` operational commands. See the built-in help for a complete list of options. @@ -327,7 +329,7 @@ Server Multi-client server is the most popular OpenVPN mode on routers. It always uses x.509 authentication and therefore requires a PKI setup. Refer this topic :ref:`configuration/pki/index:pki` to generate a CA certificate, -a server certificate and key, a certificate revocation list, a Diffie-Hellman +a server certificate and key, a certificate revocation list, and a Diffie-Hellman key exchange parameters file. You do not need client certificates and keys for the server setup. @@ -340,14 +342,14 @@ all client subnets belong to 10.23.0.0/20. All clients need access to the 192.168.0.0/16 network. First we need to specify the basic settings. 1194/UDP is the default. The -``persistent-tunnel`` option is recommended, it prevents the TUN/TAP device from -closing on connection resets or daemon reloads. +``persistent-tunnel`` option is recommended, as it prevents the TUN/TAP device +from closing on connection resets or daemon reloads. .. note:: Using **openvpn-option -reneg-sec** can be tricky. This option is - used to renegotiate data channel after n seconds. When used at both server - and client, the lower value will trigger the renegotiation. If you set it to - 0 on one side of the connection (to disable it), the chosen value on the - other side will determine when the renegotiation will occur. + used to renegotiate data channel after n seconds. When used on both the + server and client, the lower value will trigger the renegotiation. If you + set it to 0 on one side of the connection (to disable it), the chosen value + on the other side will determine when the renegotiation will occur. .. code-block:: none @@ -357,7 +359,7 @@ closing on connection resets or daemon reloads. set interfaces openvpn vtun10 protocol udp Then we need to generate, add and specify the names of the cryptographic materials. -Each of the install command should be applied to the configuration and commited +Each of the install commands should be applied to the configuration and commited before using under the openvpn interface configuration. .. code-block:: none @@ -392,7 +394,7 @@ installing that route on clients. set interfaces openvpn vtun10 server push-route 192.168.0.0/16 set interfaces openvpn vtun10 server subnet 10.23.1.0/24 -Since it's a HQ and branch offices setup, we will want all clients to have +Since it's a HQ with branch offices setup, we will want all clients to have fixed addresses and we will route traffic to specific subnets through them. We need configuration for each client to achieve this. @@ -413,9 +415,9 @@ internally, so we need to create a route to the 10.23.0.0/20 network ourselves: set protocols static route 10.23.0.0/20 interface vtun10 Additionally, each client needs a copy of ca cert and its own client key and -cert files. The files are plaintext so they may be copied either manually from the CLI. -Client key and cert files should be signed with the proper ca cert and generated on the -server side. +cert files. The files are plaintext so they may be copied manually from the CLI. +Client key and cert files should be signed with the proper ca cert and generated +on the server side. HQ's router requires the following steps to generate crypto materials for the Branch 1: @@ -570,12 +572,12 @@ example: Client ****** -VyOS can not only act as an OpenVPN site-to-site or server for multiple clients. -You can indeed also configure any VyOS OpenVPN interface as an OpenVPN client -connecting to a VyOS OpenVPN server or any other OpenVPN server. +VyOS can not only act as an OpenVPN site-to-site or server for multiple clients +but you can also configure any VyOS OpenVPN interface as an OpenVPN client that +connects to a VyOS OpenVPN server or any other OpenVPN server. -Given the following example we have one VyOS router acting as OpenVPN server -and another VyOS router acting as OpenVPN client. The server also pushes a +Given the following example we have one VyOS router acting as an OpenVPN server +and another VyOS router acting as an OpenVPN client. The server also pushes a static client IP address to the OpenVPN client. Remember, clients are identified using their CN attribute in the SSL certificate. @@ -637,17 +639,23 @@ benefit from it (see :ref:`issues_features`). If you are a hacker or want to try on your own we support passing raw OpenVPN options to OpenVPN. -.. cfgcmd:: set interfaces openvpn vtun10 openvpn-option 'persistent-key' +.. cfgcmd:: set interfaces openvpn vtun10 openvpn-option 'persist-key' -Will add ``persistent-key`` at the end of the generated OpenVPN configuration. +Will add ``persist-key`` to the generated OpenVPN configuration. Please use this only as last resort - things might break and OpenVPN won't start if you pass invalid options/syntax. .. cfgcmd:: set interfaces openvpn vtun10 openvpn-option - 'push "keepalive 1 10"' + 'push keepalive 10 60' Will add ``push "keepalive 1 10"`` to the generated OpenVPN config file. +.. cfgcmd:: set interfaces openvpn vtun10 openvpn-option + 'route-up "/config/auth/tun_up.sh arg1"' + +Will add ``route-up "/config/auth/tun_up.sh arg1"`` to the generated OpenVPN +config file. The path and arguments need to be single- or double-quoted. + .. note:: Sometimes option lines in the generated OpenVPN configuration require quotes. This is done through a hack on our config generator. You can pass quotes using the ``"`` statement. @@ -748,7 +756,7 @@ between kernel and user space for encryption and packet handling. As a result, the processing of each packet becomes more efficient, potentially leveraging hardware encryption offloading support available in the kernel. -.. note:: OpenVPN DCO is not full OpenVPN features supported , is currently +.. note:: OpenVPN DCO is not a fully supported OpenVPN feature, and is currently considered experimental. Furthermore, there are certain OpenVPN features and use cases that remain incompatible with DCO. To get a comprehensive understanding of the limitations associated with DCO, refer to the list of @@ -764,9 +772,9 @@ DCO support is a per-tunnel option and it is not automatically enabled by default for new or upgraded tunnels. Existing tunnels will continue to function as they have in the past. -DCO can be enabled for both new and existing tunnels,VyOS adds an option in each -tunnel configuration where we can enable this function .The current best -practice is to create a new tunnel with DCO to minimize the chance of problems +DCO can be enabled for both new and existing tunnels. VyOS adds an option in +each tunnel configuration where we can enable this function. The current best +practice is to create a new tunnel with DCO to minimize the chance of problems with existing clients. .. cfgcmd:: set interfaces openvpn <name> offload dco diff --git a/docs/configuration/interfaces/vxlan.rst b/docs/configuration/interfaces/vxlan.rst index af00fdec..39901f53 100644 --- a/docs/configuration/interfaces/vxlan.rst +++ b/docs/configuration/interfaces/vxlan.rst @@ -1,4 +1,4 @@ -:lastproofread: 2023-01-26 +:lastproofread: 2024-07-04 .. _vxlan-interface: @@ -103,8 +103,8 @@ Unicast .. cfgcmd:: set interfaces vxlan <interface> remote <address> - IPv4/IPv6 remote address of the VXLAN tunnel. Alternative to multicast, the - remote IPv4/IPv6 address can set directly. + IPv4/IPv6 remote address of the VXLAN tunnel. An alternative to multicast, + the remote IPv4/IPv6 address can be set directly. Multicast ^^^^^^^^^ @@ -117,7 +117,7 @@ Multicast .. cfgcmd:: set interfaces vxlan <interface> group <address> - Multicast group address for VXLAN interface. VXLAN tunnels can be built + Multicast group address for the VXLAN interface. VXLAN tunnels can be built either via Multicast or via Unicast. Both IPv4 and IPv6 multicast is possible. @@ -132,7 +132,7 @@ the same broadcast domain. Let's assume PC4 on Leaf2 wants to ping PC5 on Leaf3. Instead of setting Leaf3 as our remote end manually, Leaf2 encapsulates the packet into a UDP-packet and -sends it to its designated multicast-address via Spine1. When Spine1 receives +sends it to its' designated multicast-address via Spine1. When Spine1 receives this packet it forwards it to all other leaves who has joined the same multicast-group, in this case Leaf3. When Leaf3 receives the packet it forwards it, while at the same time learning that PC4 is reachable behind Leaf2, because @@ -188,8 +188,8 @@ Example The setup is this: Leaf2 - Spine1 - Leaf3 -Spine1 is a Cisco IOS router running version 15.4, Leaf2 and Leaf3 is each a -VyOS router running 1.2. +Spine1 is a Cisco IOS router running version 15.4, Leaf2 and Leaf3 are each +VyOS routers running 1.2. This topology was built using GNS3. @@ -282,8 +282,8 @@ traffic from. set interfaces vxlan vxlan242 source-interface 'eth0' set interfaces vxlan vxlan242 vni '242' -As you can see, Leaf2 and Leaf3 configuration is almost identical. There are -lots of commands above, I'll try to into more detail below, command +As you can see, the Leaf2 and Leaf3 configurations are almost identical. There +are lots of commands above, I'll try to go into more detail below. Command descriptions are placed under the command boxes: .. code-block:: none @@ -339,7 +339,7 @@ that behavior is available using the above command. Unicast VXLAN ============= -Alternative to multicast, the remote IPv4 address of the VXLAN tunnel can be +Alternatively to multicast, the remote IPv4 address of the VXLAN tunnel can be set directly. Let's change the Multicast example from above: .. code-block:: none diff --git a/docs/configuration/interfaces/wireguard.rst b/docs/configuration/interfaces/wireguard.rst index 885720e1..db2ff2c7 100644 --- a/docs/configuration/interfaces/wireguard.rst +++ b/docs/configuration/interfaces/wireguard.rst @@ -1,4 +1,4 @@ -:lastproofread: 2023-01-26 +:lastproofread: 2024-07-04 .. _wireguard: @@ -30,7 +30,7 @@ Generate Keypair .. opcmd:: generate pki wireguard key-pair - It generates the keypair, which includes the public and private parts. + Generates the keypair, which includes the public and private parts. The key is not stored on the system - only a keypair is generated. .. code-block:: none @@ -41,7 +41,7 @@ Generate Keypair .. opcmd:: generate pki wireguard key-pair install interface <interface> - Generates a keypair, which includes the public and private parts, and build + Generates a keypair, which includes the public and private parts, and builds a configuration command to install this key to ``interface``. .. code-block:: none @@ -101,8 +101,8 @@ Optional .. opcmd:: generate pki wireguard preshared-key install interface <interface> peer <peer> An additional layer of symmetric-key crypto can be used on top of the - asymmetric crypto. This command automatically creates for you the required - CLI command to install this PSK for a given peer. + asymmetric crypto. This command automatically creates the required CLI + command to install this PSK for a given peer. This is optional. @@ -409,7 +409,7 @@ the VyOS CLI. connect to ``interface`` on this router. The public key from the specified interface is automatically extracted and embedded into the configuration. - The command also generates a configuration snipped which can be copy/pasted + The command also generates a configuration snippet which can be copy/pasted into the VyOS CLI if needed. The supplied ``<name>`` on the CLI will become the peer name in the snippet. diff --git a/docs/configuration/interfaces/wireless.rst b/docs/configuration/interfaces/wireless.rst index df153763..695866a0 100644 --- a/docs/configuration/interfaces/wireless.rst +++ b/docs/configuration/interfaces/wireless.rst @@ -1,4 +1,4 @@ -:lastproofread: 2023-01-26 +:lastproofread: 2024-07-04 .. _wireless-interface: @@ -6,20 +6,20 @@ WLAN/WIFI - Wireless LAN ######################## -:abbr:`WLAN (Wireless LAN)` interface provide 802.11 (a/b/g/n/ac) wireless -support (commonly referred to as Wi-Fi) by means of compatible hardware. If your -hardware supports it, VyOS supports multiple logical wireless interfaces per -physical device. +The :abbr:`WLAN (Wireless LAN)` interface provides 802.11 (a/b/g/n/ac) wireless +support (commonly referred to as Wi-Fi) by means of compatible hardware. If +your hardware supports it, VyOS supports multiple logical wireless interfaces +per physical device. There are three modes of operation for a wireless interface: -* :abbr:`WAP (Wireless Access-Point)` provides network access to connecting +* :abbr:`WAP (Wireless Access-Point)` mode provides network access to connecting stations if the physical hardware supports acting as a WAP -* A station acts as a Wi-Fi client accessing the network through an available +* Station mode acts as a Wi-Fi client accessing the network through an available WAP -* Monitor, the system passively monitors any kind of wireless traffic +* Monitor mode lets the system passively monitor wireless traffic If the system detects an unconfigured wireless device, it will be automatically added the configuration tree, specifying any detected settings (for example, @@ -36,26 +36,38 @@ 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 + 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. -.. cfgcmd:: set interfaces wireless <interface> country-code <cc> + .. note:: This option is mandatory in Access-Point mode. + +Wireless options +================ + +.. 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 + to indicate country in which the box is operating. This can limit available channels and transmit power. .. 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 - full SSID, i.e., require stations to know SSID. + full SSID, i.e., require stations to know the SSID. .. cfgcmd:: set interfaces wireless <interface> expunge-failing-stations @@ -84,7 +96,16 @@ Wireless options Management Frame Protection (MFP) according to IEEE 802.11w -.. cfgcmd:: set interfaces wireless <interface> mode <a | b | g | n | ac> + .. note:: :abbr:`MFP (Management Frame Protection)` is required for WPA3. + +.. cfgcmd:: set interfaces wireless <interface> enable-bf-protection + + Beacon Protection: management frame protection for Beacon frames. + + .. note:: This option requires :abbr:`MFP (Management Frame Protection)` + to be enabled. + +.. cfgcmd:: set interfaces wireless <interface> mode <a | b | g | n | ac | ax> Operation mode of wireless radio. @@ -93,6 +114,9 @@ Wireless options * ``g`` - 802.11g - 54 Mbits/sec (default) * ``n`` - 802.11n - 600 Mbits/sec * ``ac`` - 802.11ac - 1300 Mbits/sec + * ``ax`` - 802.11ax - exceeds 1GBit/sec + + .. note:: In VyOS, 802.11ax is only implemented for 6GHz as of yet. .. cfgcmd:: set interfaces wireless <interface> physical-device <device> @@ -102,10 +126,12 @@ Wireless options .. cfgcmd:: set interfaces wireless <interface> reduce-transmit-power <number> - Add Power Constraint element to Beacon and Probe Response frames. + Adds the Power Constraint information element to Beacon and Probe Response + frames. - This option adds Power Constraint element when applicable and Country element - is added. Power Constraint element is required by Transmit Power Control. + This option adds the Power Constraint information element when applicable + and the Country information element is configured. The Power Constraint + element is required by Transmit Power Control. Valid values are 0..255. @@ -131,7 +157,9 @@ PPDU .. cfgcmd:: set interfaces wireless <interface> capabilities require-ht -.. cfgcmd:: set interfaces wireless <interface> capabilities require-hvt +.. cfgcmd:: set interfaces wireless <interface> capabilities require-vht + +.. cfgcmd:: set interfaces wireless <interface> capabilities require-he HT (High Throughput) capabilities (802.11n) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -149,6 +177,7 @@ HT (High Throughput) capabilities (802.11n) Supported channel width set. + * ``ht20`` - 20 MHz channel width * ``ht40-`` - Both 20 MHz and 40 MHz with secondary channel below the primary channel * ``ht40+`` - Both 20 MHz and 40 MHz with secondary channel above the primary @@ -234,10 +263,14 @@ VHT (Very High Throughput) capabilities (802.11ac) Beamforming capabilities: - * ``single-user-beamformer`` - Support for operation as single user beamformer - * ``single-user-beamformee`` - Support for operation as single user beamformee - * ``multi-user-beamformer`` - Support for operation as single user beamformer - * ``multi-user-beamformee`` - Support for operation as single user beamformer + * ``single-user-beamformer`` - Support for operation as + single user beamformer + * ``single-user-beamformee`` - Support for operation as + single user beamformee + * ``multi-user-beamformer`` - Support for operation as + multi user beamformer + * ``multi-user-beamformee`` - Support for operation as + multi user beamformee .. cfgcmd:: set interfaces wireless <interface> capabilities vht center-channel-freq <freq-1 | freq-2> <number> @@ -262,7 +295,8 @@ VHT (Very High Throughput) capabilities (802.11ac) Enable LDPC (Low Density Parity Check) coding capability -.. cfgcmd:: set interfaces wireless <interface> capabilities vht link-adaptation +.. cfgcmd:: set interfaces wireless <interface> + capabilities vht link-adaptation VHT link adaptation capabilities @@ -274,7 +308,8 @@ VHT (Very High Throughput) capabilities (802.11ac) .. cfgcmd:: set interfaces wireless <interface> capabilities vht max-mpdu-exp <value> - Set the maximum length of A-MPDU pre-EOF padding that the station can receive + Set the maximum length of A-MPDU pre-EOF padding that the station can + receive .. cfgcmd:: set interfaces wireless <interface> capabilities vht short-gi <80 | 160> @@ -297,6 +332,58 @@ VHT (Very High Throughput) capabilities (802.11ac) Station supports receiving VHT variant HT Control field +HE (High Efficiency) capabilities (802.11ax) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. cfgcmd:: set interfaces wireless <interface> + capabilities he antenna-pattern-fixed + + Tell the AP that antenna positions are fixed and will not change + during the lifetime of an association. + +.. cfgcmd:: set interfaces wireless <interface> capabilities he beamform + <single-user-beamformer | single-user-beamformee | multi-user-beamformer> + + Beamforming capabilities: + + * ``single-user-beamformer`` - Support for operation as + single user beamformer + * ``single-user-beamformee`` - Support for operation as + single user beamformee + * ``multi-user-beamformer`` - Support for operation as single + user beamformer + +.. cfgcmd:: set interfaces wireless <interface> + capabilities he bss-color <number> + + BSS coloring helps to prevent channel jamming when multiple APs use + the same channels. + + Valid values are 1..63 + +.. cfgcmd:: set interfaces wireless <interface> capabilities he + center-channel-freq <freq-1 | freq-2> <number> + + HE operating channel center frequency - center freq 1 + (for use with 80, 80+80 and 160 modes) + + HE operating channel center frequency - center freq 2 + (for use with the 80+80 mode) + + <number> must be within 1..233. For 80 MHz channels it should be + channel + 6 and for 160 MHz channels, it should be channel + 14. + +.. cfgcmd:: set interfaces wireless <interface> + capabilities he channel-set-width <number> + + <number> must be one of: + + * ``131`` - 20 MHz channel width + * ``132`` - 40 MHz channel width + * ``133`` - 80 MHz channel width + * ``134`` - 160 MHz channel width + * ``135`` - 80+80 MHz channel width + Wireless options (Station/Client) ================================= @@ -306,9 +393,9 @@ default physical device (``phy0``) is used. .. code-block:: none + set system wireless country-code de set interfaces wireless wlan0 type station set interfaces wireless wlan0 address dhcp - set interfaces wireless wlan0 country-code de set interfaces wireless wlan0 ssid Test set interfaces wireless wlan0 security wpa passphrase '12345678' @@ -316,11 +403,14 @@ Resulting in .. code-block:: none + system { + wireless { + country-code de + } + } interfaces { - [...] wireless wlan0 { address dhcp - country-code de security { wpa { passphrase "12345678" @@ -333,13 +423,13 @@ Resulting in Security ======== -:abbr:`WPA (Wi-Fi Protected Access)` and WPA2 Enterprise in combination with -802.1x based authentication can be used to authenticate users or computers -in a domain. +:abbr:`WPA (Wi-Fi Protected Access)`, WPA2 Enterprise and WPA3 Enterprise in +combination with 802.1x based authentication can be used to authenticate +users or computers in a domain. The wireless client (supplicant) authenticates against the RADIUS server (authentication server) using an :abbr:`EAP (Extensible Authentication -Protocol)` method configured on the RADIUS server. The WAP (also referred +Protocol)` method configured on the RADIUS server. The WAP (also referred to as authenticator) role is to send all authentication messages between the supplicant and the configured authentication server, thus the RADIUS server is responsible for authenticating the users. @@ -353,10 +443,11 @@ The WAP in this example has the following characteristics: * Wireless channel ``1`` * RADIUS server at ``192.168.3.10`` with shared-secret ``VyOSPassword`` +.. stop_vyoslinter .. code-block:: none + set system wireless country-code de set interfaces wireless wlan0 address '192.168.2.1/24' - set interfaces wireless wlan0 country-code de set interfaces wireless wlan0 type access-point set interfaces wireless wlan0 channel 1 set interfaces wireless wlan0 mode n @@ -366,15 +457,21 @@ The WAP in this example has the following characteristics: set interfaces wireless wlan0 security wpa radius server 192.168.3.10 key 'VyOSPassword' set interfaces wireless wlan0 security wpa radius server 192.168.3.10 port 1812 +.. start_vyoslinter + Resulting in .. code-block:: none + system { + wireless { + country-code de + } + } interfaces { [...] wireless wlan0 { address 192.168.2.1/24 - country-code de channel 1 mode n security { @@ -431,6 +528,7 @@ about all wireless interfaces. Use this command to view operational status and details wireless-specific information about all wireless interfaces. +.. stop_vyoslinter .. code-block:: none vyos@vyos:~$ show interfaces wireless detail @@ -458,11 +556,14 @@ information about all wireless interfaces. TX: bytes packets errors dropped carrier collisions 183413 5430 0 0 0 0 +.. start_vyoslinter + .. opcmd:: show interfaces wireless <wlanX> This command shows both status and statistics on the specified wireless interface. The wireless interface identifier can range from wlan0 to wlan999. +.. stop_vyoslinter .. code-block:: none vyos@vyos:~$ show interfaces wireless wlan0 @@ -478,6 +579,8 @@ interface. The wireless interface identifier can range from wlan0 to wlan999. TX: bytes packets errors dropped carrier collisions 83413 430 0 0 0 0 +.. start_vyoslinter + .. opcmd:: show interfaces wireless <wlanX> brief @@ -554,6 +657,7 @@ The WAP in this example has the following characteristics: .. code-block:: none + set system wireless country-code de set interfaces wireless wlan0 address '192.168.2.1/24' set interfaces wireless wlan0 type access-point set interfaces wireless wlan0 channel 1 @@ -562,18 +666,21 @@ The WAP in this example has the following characteristics: set interfaces wireless wlan0 security wpa mode wpa2 set interfaces wireless wlan0 security wpa cipher CCMP set interfaces wireless wlan0 security wpa passphrase '12345678' - set interfaces wireless wlan0 country-code de Resulting in .. code-block:: none + system { + wireless { + country-code de + } + } interfaces { [...] wireless wlan0 { address 192.168.2.1/24 channel 1 - country-code de mode n security { wpa { @@ -608,8 +715,8 @@ still put this card into AP mode using the following configuration: .. stop_vyoslinter .. code-block:: none + set system wireless country-code 'us' set interfaces wireless wlan0 channel '1' - set interfaces wireless wlan0 country-code 'us' set interfaces wireless wlan0 mode 'n' set interfaces wireless wlan0 physical-device 'phy0' set interfaces wireless wlan0 ssid 'VyOS' diff --git a/docs/configuration/interfaces/wwan.rst b/docs/configuration/interfaces/wwan.rst index 98890158..00f927bb 100644 --- a/docs/configuration/interfaces/wwan.rst +++ b/docs/configuration/interfaces/wwan.rst @@ -1,4 +1,4 @@ -:lastproofread: 2023-01-27 +:lastproofread: 2024-07-04 .. _wwan-interface: @@ -320,11 +320,11 @@ The following hardware modules have been tested successfully in an Firmware Update *************** -All available WWAN cards have a build in, reprogrammable firmware. Most of the -vendors provide a regular update to the firmware used in the baseband chip. +All available WWAN cards have a built-in, reprogrammable firmware. Most vendors +provide regular updates to firmware used in the baseband chip. -As VyOS makes use of the QMI interface to connect to the WWAN modem cards, also -the firmware can be reprogrammed. +As VyOS makes use of the QMI interface to connect to the WWAN modem cards, the +firmware can be reprogrammed. To update the firmware, VyOS also ships the `qmi-firmware-update` binary. To upgrade the firmware of an e.g. Sierra Wireless MC7710 module to the firmware 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/service/ssh.rst b/docs/configuration/service/ssh.rst index efdbc651..d3ca51b5 100644 --- a/docs/configuration/service/ssh.rst +++ b/docs/configuration/service/ssh.rst @@ -109,6 +109,25 @@ Configuration Specify name of the :abbr:`VRF (Virtual Routing and Forwarding)` instance. +.. cfgcmd:: set service ssh pubkey-accepted-algorithm <name> + + Specifies the signature algorithms that will be accepted for public key + authentication + + List of supported algorithms: ``ssh-ed25519``, + ``ssh-ed25519-cert-v01@openssh.com``, ``sk-ssh-ed25519@openssh.com``, + ``sk-ssh-ed25519-cert-v01@openssh.com``, ``ecdsa-sha2-nistp256``, + ``ecdsa-sha2-nistp256-cert-v01@openssh.com``, ``ecdsa-sha2-nistp384``, + ``ecdsa-sha2-nistp384-cert-v01@openssh.com``, ``ecdsa-sha2-nistp521``, + ``ecdsa-sha2-nistp521-cert-v01@openssh.com``, + ``sk-ecdsa-sha2-nistp256@openssh.com``, + ``sk-ecdsa-sha2-nistp256-cert-v01@openssh.com``, + ``webauthn-sk-ecdsa-sha2-nistp256@openssh.com``, + ``ssh-dss``, ``ssh-dss-cert-v01@openssh.com``, ``ssh-rsa``, + ``ssh-rsa-cert-v01@openssh.com``, ``rsa-sha2-256``, + ``rsa-sha2-256-cert-v01@openssh.com``, ``rsa-sha2-512``, + ``rsa-sha2-512-cert-v01@openssh.com`` + Dynamic-protection ================== Protects host from brute-force attacks against 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/system/login.rst b/docs/configuration/system/login.rst index 09e27c53..452981a9 100644 --- a/docs/configuration/system/login.rst +++ b/docs/configuration/system/login.rst @@ -234,6 +234,12 @@ An example: set system login user otptester authentication otp rate-time '20' set system login user otptester authentication otp window-size '5' +Once a user has 2FA/OTP configured against their account, they must login +using their password with the OTP code appended to it. +For example: If the users password is vyosrocks and the OTP code is 817454 +then they would enter their password as vyosrocks817454 + + RADIUS ====== 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..ea0a4765 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``. @@ -442,7 +450,7 @@ system: * Accel-PPP * Intel NIC drivers -* Inter QAT +* Intel QAT Each of those modules holds a dependency on the kernel version and if you are lucky enough to receive an ISO build error which sounds like: |
