diff options
Diffstat (limited to 'docs/configuration')
37 files changed, 545 insertions, 132 deletions
diff --git a/docs/configuration/container/index.rst b/docs/configuration/container/index.rst index 988b425b..e5a470bc 100644 --- a/docs/configuration/container/index.rst +++ b/docs/configuration/container/index.rst @@ -125,7 +125,7 @@ Configuration - **net-bind-service**: Bind a socket to privileged ports (port numbers less than 1024) - **net-raw**: Permission to create raw network sockets - **setpcap**: Capability sets (from bounded or inherited set) - - **sys-admin**: Administation operations (quotactl, mount, sethostname, setdomainame) + - **sys-admin**: Administration operations (quotactl, mount, sethostname, setdomainame) - **sys-time**: Permission to set system clock .. cfgcmd:: set container name <name> disable diff --git a/docs/configuration/firewall/bridge.rst b/docs/configuration/firewall/bridge.rst index 9fb019c5..f84fd456 100644 --- a/docs/configuration/firewall/bridge.rst +++ b/docs/configuration/firewall/bridge.rst @@ -13,7 +13,7 @@ Overview ******** In this section there's useful information of all firewall configuration that -can be done regarding bridge, and appropiate op-mode commands. +can be done regarding bridge, and appropriate op-mode commands. Configuration commands covered in this section: .. cfgcmd:: set firewall bridge ... @@ -37,13 +37,13 @@ for this layer is shown next: .. figure:: /_static/images/firewall-bridge-packet-flow.png -For traffic that needs to be forwared internally by the bridge, base chain is +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, highlightened with red color. +forward filter ...``, which happens in stage 4, highlighted with red color. Custom bridge firewall chains can be create with command ``set firewall bridge name <name> ...``. In order to use such custom chain, a rule with action jump, -and the appropiate target should be defined in a base chain. +and the appropriate target should be defined in a base chain. .. note:: **Layer 3 bridge**: When an IP address is assigned to the bridge interface, and if traffic @@ -137,7 +137,7 @@ not match any rule in it's chain. For base chains, possible options for .. cfgcmd:: set firewall bridge name <name> default-jump-target <text> - To be used only when ``defult-action`` is set to ``jump``. Use this + To be used only when ``default-action`` is set to ``jump``. Use this command to specify jump target for default rule. .. note:: **Important note about default-actions:** @@ -157,8 +157,8 @@ log options can be defined. Enable logging for the matched packet. If this configuration command is not present, then log is not enabled. -.. cfgcmd:: set firewall bridge forward filter enable-default-log -.. cfgcmd:: set firewall bridge name <name> enable-default-log +.. cfgcmd:: set firewall bridge forward filter default-log +.. cfgcmd:: set firewall bridge name <name> default-log Use this command to enable the logging of the default action on the specified chain. @@ -236,9 +236,9 @@ There are a lot of matching criteria against which the packet can be tested. .. cfgcmd:: set firewall bridge name <name> rule <1-999999> inbound-interface name <iface> - Match based on inbound interface. Wilcard ``*`` can be used. + Match based on inbound interface. Wildcard ``*`` can be used. For example: ``eth2*``. Prepending character ``!`` for inverted matching - criteria is also supportd. For example ``!eth2`` + criteria is also supported. For example ``!eth2`` .. cfgcmd:: set firewall bridge forward filter rule <1-999999> inbound-interface group <iface_group> @@ -246,16 +246,16 @@ There are a lot of matching criteria against which the packet can be tested. inbound-interface group <iface_group> Match based on inbound interface group. Prepending character ``!`` for - inverted matching criteria is also supportd. For example ``!IFACE_GROUP`` + inverted matching criteria is also supported. For example ``!IFACE_GROUP`` .. cfgcmd:: set firewall bridge forward filter rule <1-999999> outbound-interface name <iface> .. cfgcmd:: set firewall bridge name <name> rule <1-999999> outbound-interface name <iface> - Match based on outbound interface. Wilcard ``*`` can be used. + Match based on outbound interface. Wildcard ``*`` can be used. For example: ``eth2*``. Prepending character ``!`` for inverted matching - criteria is also supportd. For example ``!eth2`` + criteria is also supported. For example ``!eth2`` .. cfgcmd:: set firewall bridge forward filter rule <1-999999> outbound-interface group <iface_group> @@ -263,7 +263,7 @@ There are a lot of matching criteria against which the packet can be tested. outbound-interface group <iface_group> Match based on outbound interface group. Prepending character ``!`` for - inverted matching criteria is also supportd. For example ``!IFACE_GROUP`` + inverted matching criteria is also supported. For example ``!IFACE_GROUP`` .. cfgcmd:: set firewall bridge forward filter rule <1-999999> vlan id <0-4096> @@ -288,7 +288,7 @@ Rule-set overview In this section you can find all useful firewall op-mode commands. -General commands for firewall configuration, counter and statiscits: +General commands for firewall configuration, counter and statistics: .. opcmd:: show firewall .. opcmd:: show firewall summary @@ -325,7 +325,7 @@ Configuration example: .. code-block:: none set firewall bridge forward filter default-action 'drop' - set firewall bridge forward filter enable-default-log + set firewall bridge forward filter default-log set firewall bridge forward filter rule 10 action 'continue' set firewall bridge forward filter rule 10 inbound-interface name 'eth2' set firewall bridge forward filter rule 10 vlan id '22' @@ -341,7 +341,7 @@ Configuration example: set firewall bridge forward filter rule 40 destination mac-address '66:55:44:33:22:11' set firewall bridge forward filter rule 40 source mac-address '11:22:33:44:55:66' set firewall bridge name TEST default-action 'accept' - set firewall bridge name TEST enable-default-log + set firewall bridge name TEST default-log set firewall bridge name TEST rule 10 action 'continue' set firewall bridge name TEST rule 10 log set firewall bridge name TEST rule 10 vlan priority '0' diff --git a/docs/configuration/firewall/flowtables.rst b/docs/configuration/firewall/flowtables.rst index bc7b9212..adecb26a 100644 --- a/docs/configuration/firewall/flowtables.rst +++ b/docs/configuration/firewall/flowtables.rst @@ -99,20 +99,20 @@ Creating rules for using flow tables: Configuration Example ********************* -Things to be considred in this setup: +Things to be considered in this setup: * Two interfaces are going to be used in the flowtables: eth0 and eth1 - * Minumum firewall ruleset is provided, which includes some filtering rules, - and appropiate rules for using flowtable offload capabilities. + * 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 -desired connection should be explicitely accepted. Same thing should be taken +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. -We will only accept traffic comming from interface eth0, protocol tcp and -destination port 1122. All other traffic traspassing the router should be +We will only accept traffic coming from interface eth0, protocol tcp and +destination port 1122. All other traffic trespassing the router should be blocked. Commands @@ -152,7 +152,7 @@ Analysis on what happens for desired connection: 4. Once 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 10. + accepted in rule 20. 5. Second packet for this connection is received by the router. Since connection state is **established**, then rule 10 is hit, and a new entry diff --git a/docs/configuration/firewall/index.rst b/docs/configuration/firewall/index.rst index 44e0cd20..1d904901 100644 --- a/docs/configuration/firewall/index.rst +++ b/docs/configuration/firewall/index.rst @@ -24,7 +24,7 @@ firewall are covered below: where the packet was received is part of a bridge, or not. If the interface where the packet was received isn't part of a bridge, then -packetis processed at the **IP Layer**: +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 @@ -65,7 +65,7 @@ packetis 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, - such as NTP, or a response to traffic received externaly through + 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: @@ -84,7 +84,7 @@ If the interface where the packet was received is part of a bridge, then the packet is processed at the **Bridge Layer**, which contains a basic setup for bridge filtering: - * **Forward (Bridge)**: stage where traffic that is trespasing through the + * **Forward (Bridge)**: stage where traffic that is trespassing through the bridge is filtered and controlled: * ``set firewall bridge forward filter ...``. diff --git a/docs/configuration/firewall/ipv4.rst b/docs/configuration/firewall/ipv4.rst index ff739418..a9459f00 100644 --- a/docs/configuration/firewall/ipv4.rst +++ b/docs/configuration/firewall/ipv4.rst @@ -11,7 +11,7 @@ Overview ******** In this section there's useful information of all firewall configuration that -can be done regarding IPv4, and appropiate op-mode commands. +can be done regarding IPv4, and appropriate op-mode commands. Configuration commands covered in this section: .. cfgcmd:: set firewall ipv4 ... @@ -41,12 +41,12 @@ next: Where firewall base chain to configure firewall filtering rules for transit traffic is ``set firewall ipv4 forward filter ...``, which happens in stage 5, -highlightened with red color. +highlighted with red color. For traffic towards the router itself, base chain is **input**, while traffic originated by the router, base chain is **output**. A new simplified packet flow diagram is shown next, which shows the path -for traffic destinated to the router itself, and traffic generated by the +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 @@ -64,7 +64,7 @@ output filter ...`` Custom firewall chains can be created, with commands ``set firewall ipv4 name <name> ...``. In order to use -such custom chain, a rule with **action jump**, and the appropiate **target** +such custom chain, a rule with **action jump**, and the appropriate **target** should be defined in a base chain. ********************* @@ -184,7 +184,7 @@ not match any rule in it's chain. For base chains, possible options for .. cfgcmd:: set firewall ipv4 name <name> default-jump-target <text> - To be used only when ``defult-action`` is set to ``jump``. Use this + To be used only when ``default-action`` is set to ``jump``. Use this command to specify jump target for default rule. .. note:: **Important note about default-actions:** @@ -206,10 +206,10 @@ log options can be defined. Enable logging for the matched packet. If this configuration command is not present, then log is not enabled. -.. cfgcmd:: set firewall ipv4 forward filter enable-default-log -.. cfgcmd:: set firewall ipv4 input filter enable-default-log -.. cfgcmd:: set firewall ipv4 output filter enable-default-log -.. cfgcmd:: set firewall ipv4 name <name> enable-default-log +.. cfgcmd:: set firewall ipv4 forward filter default-log +.. cfgcmd:: set firewall ipv4 input filter default-log +.. cfgcmd:: set firewall ipv4 output filter default-log +.. cfgcmd:: set firewall ipv4 name <name> default-log Use this command to enable the logging of the default action on the specified chain. @@ -683,9 +683,9 @@ geoip) to keep database and rules updated. .. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> inbound-interface name <iface> - Match based on inbound interface. Wilcard ``*`` can be used. + Match based on inbound interface. Wildcard ``*`` can be used. For example: ``eth2*``. Prepending character ``!`` for inverted matching - criteria is also supportd. For example ``!eth2`` + criteria is also supported. For example ``!eth2`` .. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> inbound-interface group <iface_group> @@ -695,7 +695,7 @@ geoip) to keep database and rules updated. inbound-interface group <iface_group> Match based on inbound interface group. Prepending character ``!`` for - inverted matching criteria is also supportd. For example ``!IFACE_GROUP`` + inverted matching criteria is also supported. For example ``!IFACE_GROUP`` .. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> outbound-interface name <iface> @@ -704,9 +704,9 @@ geoip) to keep database and rules updated. .. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> outbound-interface name <iface> - Match based on outbound interface. Wilcard ``*`` can be used. + Match based on outbound interface. Wildcard ``*`` can be used. For example: ``eth2*``. Prepending character ``!`` for inverted matching - criteria is also supportd. For example ``!eth2`` + criteria is also supported. For example ``!eth2`` .. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> outbound-interface group <iface_group> @@ -716,7 +716,7 @@ geoip) to keep database and rules updated. outbound-interface group <iface_group> Match based on outbound interface group. Prepending character ``!`` for - inverted matching criteria is also supportd. For example ``!IFACE_GROUP`` + inverted matching criteria is also supported. For example ``!IFACE_GROUP`` .. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> ipsec [match-ipsec | match-none] diff --git a/docs/configuration/firewall/ipv6.rst b/docs/configuration/firewall/ipv6.rst index 0aa8a137..4b695f74 100644 --- a/docs/configuration/firewall/ipv6.rst +++ b/docs/configuration/firewall/ipv6.rst @@ -11,7 +11,7 @@ Overview ******** In this section there's useful information of all firewall configuration that -can be done regarding IPv6, and appropiate op-mode commands. +can be done regarding IPv6, and appropriate op-mode commands. Configuration commands covered in this section: .. cfgcmd:: set firewall ipv6 ... @@ -41,12 +41,12 @@ next: Where firewall base chain to configure firewall filtering rules for transit traffic is ``set firewall ipv6 forward filter ...``, which happens in stage 5, -highlightened with red color. +highlighted with red color. For traffic towards the router itself, base chain is **input**, while traffic originated by the router, base chain is **output**. A new simplified packet flow diagram is shown next, which shows the path -for traffic destinated to the router itself, and traffic generated by the +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 @@ -64,7 +64,7 @@ output filter ...`` Custom firewall chains can be created, with commands ``set firewall ipv6 name <name> ...``. In order to use -such custom chain, a rule with **action jump**, and the appropiate **target** +such custom chain, a rule with **action jump**, and the appropriate **target** should be defined in a base chain. ****************************** @@ -184,7 +184,7 @@ not match any rule in it's chain. For base chains, possible options for .. cfgcmd:: set firewall ipv6 name <name> default-jump-target <text> - To be used only when ``defult-action`` is set to ``jump``. Use this + To be used only when ``default-action`` is set to ``jump``. Use this command to specify jump target for default rule. .. note:: **Important note about default-actions:** @@ -206,10 +206,10 @@ log options can be defined. Enable logging for the matched packet. If this configuration command is not present, then log is not enabled. -.. cfgcmd:: set firewall ipv6 forward filter enable-default-log -.. cfgcmd:: set firewall ipv6 input filter enable-default-log -.. cfgcmd:: set firewall ipv6 output filter enable-default-log -.. cfgcmd:: set firewall ipv6 name <name> enable-default-log +.. cfgcmd:: set firewall ipv6 forward filter default-log +.. cfgcmd:: set firewall ipv6 input filter default-log +.. cfgcmd:: set firewall ipv6 output filter default-log +.. cfgcmd:: set firewall ipv6 name <name> default-log Use this command to enable the logging of the default action on the specified chain. @@ -670,9 +670,9 @@ geoip) to keep database and rules updated. .. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> inbound-interface name <iface> - Match based on inbound interface. Wilcard ``*`` can be used. + Match based on inbound interface. Wildcard ``*`` can be used. For example: ``eth2*``. Prepending character ``!`` for inverted matching - criteria is also supportd. For example ``!eth2`` + criteria is also supported. For example ``!eth2`` .. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> inbound-interface group <iface_group> @@ -682,7 +682,7 @@ geoip) to keep database and rules updated. inbound-interface group <iface_group> Match based on inbound interface group. Prepending character ``!`` for - inverted matching criteria is also supportd. For example ``!IFACE_GROUP`` + inverted matching criteria is also supported. For example ``!IFACE_GROUP`` .. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> outbound-interface name <iface> @@ -691,9 +691,9 @@ geoip) to keep database and rules updated. .. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> outbound-interface name <iface> - Match based on outbound interface. Wilcard ``*`` can be used. + Match based on outbound interface. Wildcard ``*`` can be used. For example: ``eth2*``. Prepending character ``!`` for inverted matching - criteria is also supportd. For example ``!eth2`` + criteria is also supported. For example ``!eth2`` .. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> outbound-interface group <iface_group> @@ -703,7 +703,7 @@ geoip) to keep database and rules updated. outbound-interface group <iface_group> Match based on outbound interface group. Prepending character ``!`` for - inverted matching criteria is also supportd. For example ``!IFACE_GROUP`` + inverted matching criteria is also supported. For example ``!IFACE_GROUP`` .. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> ipsec [match-ipsec | match-none] @@ -1177,7 +1177,7 @@ Example Partial Config } name INP-ETH1 { default-action drop - enable-default-log + default-log rule 10 { action accept protocol tcp_udp diff --git a/docs/configuration/firewall/zone.rst b/docs/configuration/firewall/zone.rst index 059b029d..f71ad8c1 100644 --- a/docs/configuration/firewall/zone.rst +++ b/docs/configuration/firewall/zone.rst @@ -11,7 +11,7 @@ Overview ******** .. note:: Starting from VyOS 1.4-rolling-202308040557, a new firewall - structure can be found on all vyos instalations. Zone based firewall was + 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. Documentation for most of the new firewall CLI can be diff --git a/docs/configuration/interfaces/ethernet.rst b/docs/configuration/interfaces/ethernet.rst index bbf52112..a1151fd4 100644 --- a/docs/configuration/interfaces/ethernet.rst +++ b/docs/configuration/interfaces/ethernet.rst @@ -61,6 +61,22 @@ Offloading Enable different types of hardware offloading on the given NIC. + :abbr:`LRO (Large Receive Offload)` is a technique designed to boost the + efficiency of how your computer's network interface card (NIC) processes + incoming network traffic. Typically, network data arrives in smaller chunks + called packets. Processing each packet individually consumes CPU (central + processing unit) resources. Lots of small packets can lead to a performance + bottleneck. Instead of handing the CPU each packet as it comes in, LRO + instructs the NIC to combine multiple incoming packets into a single, larger + packet. This larger packet is then passed to the CPU for processing. + + .. note:: Under some circumstances, LRO is known to modify the packet headers + of forwarded traffic, which breaks the end-to-end principle of computer + networking. LRO is also only able to offload TCP segments encapsulated in + IPv4 packets. Due to these limitations, it is recommended to use GRO + (Generic Receive Offload) where possible. More information on the + limitations of LRO can be found here: https://lwn.net/Articles/358910/ + :abbr:`GSO (Generic Segmentation Offload)` is a pure software offload that is meant to deal with cases where device drivers cannot perform the offloads described above. What occurs in GSO is that a given skbuff will have its data @@ -87,13 +103,13 @@ Offloading placing the packet on the desired CPU's backlog queue and waking up the CPU for processing. RPS has some advantages over RSS: - - it can be used with any NIC, - - software filters can easily be added to hash over new protocols, - - it does not increase hardware device interrupt rate (although it does - introduce inter-processor interrupts (IPIs)). + - it can be used with any NIC + - software filters can easily be added to hash over new protocols + - it does not increase hardware device interrupt rate, although it does + introduce inter-processor interrupts (IPIs) - .. note:: In order to use TSO/LRO with VMXNET3 adaters one must also enable - the SG offloading option. + .. note:: In order to use TSO/LRO with VMXNET3 adapters, the SG offloading + option must also be enabled. Authentication (EAPoL) ---------------------- diff --git a/docs/configuration/loadbalancing/reverse-proxy.rst b/docs/configuration/loadbalancing/reverse-proxy.rst index 3d462821..970e084e 100644 --- a/docs/configuration/loadbalancing/reverse-proxy.rst +++ b/docs/configuration/loadbalancing/reverse-proxy.rst @@ -144,7 +144,8 @@ Backend Send a Proxy Protocol version 2 header (binary format) -.. cfgcmd:: set load-balancing reverse-proxy backend <name> ssl ca-certificate <ca-certificate> +.. cfgcmd:: set load-balancing reverse-proxy backend <name> ssl + ca-certificate <ca-certificate> Configure requests to the backend server to use SSL encryption and authenticate backend against <ca-certificate> @@ -154,6 +155,37 @@ Backend Configure requests to the backend server to use SSL encryption without validating server certificate + +HTTP health check +^^^^^^^^^^^^^^^^^ +For web application providing information about their state HTTP health +checks can be used to determine their availability. + +.. cfgcmd:: set load-balancing reverse-proxy backend <name> http-check + + Enables HTTP health checks using OPTION HTTP requests against '/' and + expecting a successful response code in the 200-399 range. + +.. cfgcmd:: set load-balancing reverse-proxy backend <name> http-check + method <method> + + Sets the HTTP method to be used, can be either: option, get, post, put + +.. cfgcmd:: set load-balancing reverse-proxy backend <name> http-check + uri <path> + + Sets the endpoint to be used for health checks + +.. cfgcmd:: set load-balancing reverse-proxy backend <name> http-check + 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 ------- @@ -215,6 +247,7 @@ servers (srv01 and srv02) using the round-robin load-balancing algorithm. set load-balancing reverse-proxy backend bk-01 server srv02 address '192.0.2.12' set load-balancing reverse-proxy backend bk-01 server srv02 port '8882' + Balancing based on domain name ------------------------------ The following configuration demonstrates how to use VyOS @@ -295,20 +328,22 @@ connection limit of 4000 and a minimum TLS version of 1.3. set load-balancing reverse-proxy global-parameters max-connections '4000' set load-balancing reverse-proxy global-parameters tls-version-min '1.3' + SSL Bridging ------------- -The following configuration terminates incoming HTTPS traffic on the router, then re-encrypts the traffic and sends -to the backend server via HTTPS. This is useful if encryption is required for both legs, but you do not want to +The following configuration terminates incoming HTTPS traffic on the router, +then re-encrypts the traffic and sends to the backend server via HTTPS. +This is useful if encryption is required for both legs, but you do not want to install publicly trusted certificates on each backend server. -Backend service certificates are checked against the certificate authority specified in the configuration, which -could be an internal CA. +Backend service certificates are checked against the certificate authority +specified in the configuration, which could be an internal CA. The ``https`` service listens on port 443 with backend ``bk-bridge-ssl`` to handle HTTPS traffic. It uses certificate named ``cert`` for SSL termination. -The ``bk-bridge-ssl`` backend connects to sr01 server on port 443 via HTTPS and checks backend -server has a valid certificate trusted by CA ``cacert`` +The ``bk-bridge-ssl`` backend connects to sr01 server on port 443 via HTTPS +and checks backend server has a valid certificate trusted by CA ``cacert`` .. code-block:: none @@ -325,3 +360,29 @@ server has a valid certificate trusted by CA ``cacert`` set load-balancing reverse-proxy backend bk-bridge-ssl server sr01 address '192.0.2.23' set load-balancing reverse-proxy backend bk-bridge-ssl server sr01 port '443' + +Balancing with HTTP health checks +--------------------------------- + +This configuration enables HTTP health checks on backend servers. + +.. code-block:: none + + set load-balancing reverse-proxy service my-tcp-api backend 'bk-01' + set load-balancing reverse-proxy service my-tcp-api mode 'tcp' + set load-balancing reverse-proxy service my-tcp-api port '8888' + + set load-balancing reverse-proxy backend bk-01 balance 'round-robin' + set load-balancing reverse-proxy backend bk-01 mode 'tcp' + + set load-balancing reverse-proxy backend bk-01 http-check method 'get' + set load-balancing reverse-proxy backend bk-01 http-check uri '/health' + set load-balancing reverse-proxy backend bk-01 http-check expect 'status 200' + + set load-balancing reverse-proxy backend bk-01 server srv01 address '192.0.2.11' + set load-balancing reverse-proxy backend bk-01 server srv01 port '8881' + set load-balancing reverse-proxy backend bk-01 server srv01 check + set load-balancing reverse-proxy backend bk-01 server srv02 address '192.0.2.12' + set load-balancing reverse-proxy backend bk-01 server srv02 port '8882' + set load-balancing reverse-proxy backend bk-01 server srv02 check + diff --git a/docs/configuration/pki/index.rst b/docs/configuration/pki/index.rst index 8fd6fbe8..0ead198f 100644 --- a/docs/configuration/pki/index.rst +++ b/docs/configuration/pki/index.rst @@ -8,7 +8,7 @@ PKI ### -VyOS 1.4 changed the way in how encrytion keys or certificates are stored on the +VyOS 1.4 changed the way in how encryption keys or certificates are stored on the system. In the pre VyOS 1.4 era, certificates got stored under /config and every service referenced a file. That made copying a running configuration from system A to system B a bit harder, as you had to copy the files and their permissions @@ -120,12 +120,12 @@ OpenVPN .. opcmd:: generate pki openvpn shared-secret - Genearate a new OpenVPN shared secret. The generated secret is the output to + Generate a new OpenVPN shared secret. The generated secret is the output to the console. .. opcmd:: generate pki openvpn shared-secret install <name> - Genearate a new OpenVPN shared secret. The generated secret is the output to + Generate a new OpenVPN shared secret. The generated secret is the output to the console. .. include:: pki_cli_import_help.txt @@ -163,7 +163,7 @@ WireGuard the output from op-mode into configuration mode. ``peer`` is used for the VyOS CLI command to identify the WireGuard peer where - this secred is to be used. + this secret is to be used. Key usage (CLI) =============== @@ -365,3 +365,124 @@ also to display them. .. opcmd:: renew certbot Manually trigger certificate renewal. This will be done twice a day. + +Examples +======== + +Create a CA chain and leaf certificates +------------------------------------- + +This configuration generates & installs into the VyOS PKI system a root +certificate authority, alongside two intermediary certificate authorities for +client & server certificates. These CAs are then used to generate a server +certificate for the router, and a client certificate for a user. + + +* ``vyos_root_ca`` is the root certificate authority. + +* ``vyos_client_ca`` and ``vyos_server_ca`` are intermediary certificate authorities, + which are signed by the root CA. + +* ``vyos_cert`` is a leaf server certificate used to identify the VyOS router, + signed by the server intermediary CA. + +* ``vyos_example_user`` is a leaf client certificate used to identify a user, + signed by client intermediary CA. + + +First, we create the root certificate authority. + +.. code-block:: none + + [edit] + vyos@vyos# run generate pki ca install vyos_root_ca + Enter private key type: [rsa, dsa, ec] (Default: rsa) rsa + Enter private key bits: (Default: 2048) 2048 + Enter country code: (Default: GB) GB + Enter state: (Default: Some-State) Some-State + Enter locality: (Default: Some-City) Some-City + Enter organization name: (Default: VyOS) VyOS + Enter common name: (Default: vyos.io) VyOS Root CA + Enter how many days certificate will be valid: (Default: 1825) 1825 + Note: If you plan to use the generated key on this router, do not encrypt the private key. + Do you want to encrypt the private key with a passphrase? [y/N] n + 2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. + +Secondly, we create the intermediary certificate authorities, which are used to +sign the leaf certificates. + +.. code-block:: none + + [edit] + vyos@vyos# run generate pki ca sign vyos_root_ca install vyos_server_ca + Do you already have a certificate request? [y/N] n + Enter private key type: [rsa, dsa, ec] (Default: rsa) rsa + Enter private key bits: (Default: 2048) 2048 + Enter country code: (Default: GB) GB + Enter state: (Default: Some-State) Some-State + Enter locality: (Default: Some-City) Some-City + Enter organization name: (Default: VyOS) VyOS + Enter common name: (Default: vyos.io) VyOS Intermediary Server CA + Enter how many days certificate will be valid: (Default: 1825) 1095 + Note: If you plan to use the generated key on this router, do not encrypt the private key. + Do you want to encrypt the private key with a passphrase? [y/N] n + 2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. + + + [edit] + vyos@vyos# run generate pki ca sign vyos_root_ca install vyos_client_ca + Do you already have a certificate request? [y/N] n + Enter private key type: [rsa, dsa, ec] (Default: rsa) rsa + Enter private key bits: (Default: 2048) 2048 + Enter country code: (Default: GB) GB + Enter state: (Default: Some-State) Some-State + Enter locality: (Default: Some-City) Some-City + Enter organization name: (Default: VyOS) VyOS + Enter common name: (Default: vyos.io) VyOS Intermediary Client CA + Enter how many days certificate will be valid: (Default: 1825) 1095 + Note: If you plan to use the generated key on this router, do not encrypt the private key. + Do you want to encrypt the private key with a passphrase? [y/N] n + 2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. + +Lastly, we can create the leaf certificates that devices and users will utilise. + +.. code-block:: none + + [edit] + vyos@vyos# run generate pki certificate sign vyos_server_ca install vyos_cert + Do you already have a certificate request? [y/N] n + Enter private key type: [rsa, dsa, ec] (Default: rsa) rsa + Enter private key bits: (Default: 2048) 2048 + Enter country code: (Default: GB) GB + Enter state: (Default: Some-State) Some-State + Enter locality: (Default: Some-City) Some-City + Enter organization name: (Default: VyOS) VyOS + Enter common name: (Default: vyos.io) vyos.net + Do you want to configure Subject Alternative Names? [y/N] y + Enter alternative names in a comma separate list, example: ipv4:1.1.1.1,ipv6:fe80::1,dns:vyos.net + Enter Subject Alternative Names: dns:vyos.net,dns:www.vyos.net + Enter how many days certificate will be valid: (Default: 365) 365 + Enter certificate type: (client, server) (Default: server) server + Note: If you plan to use the generated key on this router, do not encrypt the private key. + Do you want to encrypt the private key with a passphrase? [y/N] n + 2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. + + + [edit] + vyos@vyos# run generate pki certificate sign vyos_client_ca install vyos_example_user + Do you already have a certificate request? [y/N] n + Enter private key type: [rsa, dsa, ec] (Default: rsa) rsa + Enter private key bits: (Default: 2048) 2048 + Enter country code: (Default: GB) GB + Enter state: (Default: Some-State) Some-State + Enter locality: (Default: Some-City) Some-City + Enter organization name: (Default: VyOS) VyOS + Enter common name: (Default: vyos.io) Example User + Do you want to configure Subject Alternative Names? [y/N] y + Enter alternative names in a comma separate list, example: ipv4:1.1.1.1,ipv6:fe80::1,dns:vyos.net,rfc822:user@vyos.net + Enter Subject Alternative Names: rfc822:example.user@vyos.net + Enter how many days certificate will be valid: (Default: 365) 365 + Enter certificate type: (client, server) (Default: server) client + Note: If you plan to use the generated key on this router, do not encrypt the private key. + Do you want to encrypt the private key with a passphrase? [y/N] n + 2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. diff --git a/docs/configuration/policy/route.rst b/docs/configuration/policy/route.rst index 1a85ffc6..45975774 100644 --- a/docs/configuration/policy/route.rst +++ b/docs/configuration/policy/route.rst @@ -19,8 +19,8 @@ from 1 - 999999, at the first match the action of the rule will be executed. Provide a rule-set description. -.. cfgcmd:: set policy route <name> enable-default-log -.. cfgcmd:: set policy route6 <name> enable-default-log +.. cfgcmd:: set policy route <name> default-log +.. cfgcmd:: set policy route6 <name> default-log Option to log packets hitting default-action. @@ -271,4 +271,4 @@ setting a different routing table. .. cfgcmd:: set policy route <name> rule <n> set tcp-mss <500-1460> .. cfgcmd:: set policy route6 <name> rule <n> set tcp-mss <500-1460> - Set packet modifications: Explicitly set TCP Maximum segment size value.
\ No newline at end of file + Set packet modifications: Explicitly set TCP Maximum segment size value. diff --git a/docs/configuration/protocols/isis.rst b/docs/configuration/protocols/isis.rst index 1f779d0a..9b954965 100644 --- a/docs/configuration/protocols/isis.rst +++ b/docs/configuration/protocols/isis.rst @@ -12,7 +12,7 @@ interior gateway protocol (IGP) which is described in ISO10589, algorithm to create a database of the network’s topology, and from that database to determine the best (that is, lowest cost) path to a destination. The intermediate systems (the name for routers) exchange topology -information with their directly conencted neighbors. IS-IS runs directly on +information with their directly connected neighbors. IS-IS runs directly on the data link layer (Layer 2). IS-IS addresses are called :abbr:`NETs (Network Entity Titles)` and can be 8 to 20 bytes long, but are generally 10 bytes long. The tree database that is created with IS-IS is @@ -39,7 +39,7 @@ occur within IS-IS when it comes to said duplication. .. cfgcmd:: set protocols isis net <network-entity-title> - This commad sets network entity title (NET) provided in ISO format. + This command sets network entity title (NET) provided in ISO format. Here is an example :abbr:`NET (Network Entity Title)` value: @@ -52,9 +52,9 @@ occur within IS-IS when it comes to said duplication. * :abbr:`AFI (Address family authority identifier)` - ``49`` The AFI value 49 is what IS-IS uses for private addressing. - * Area identifier: ``0001`` IS-IS area number (numberical area ``1``) + * Area identifier: ``0001`` IS-IS area number (numerical area ``1``) - * System identifier: ``1921.6800.1002`` - for system idetifiers we recommend + * System identifier: ``1921.6800.1002`` - for system identifiers we recommend to use IP address or MAC address of the router itself. The way to construct this is to keep all of the zeroes of the router IP address, and then change the periods from being every three numbers to every four numbers. The diff --git a/docs/configuration/service/broadcast-relay.rst b/docs/configuration/service/broadcast-relay.rst index b6e2bed7..f64bb208 100644 --- a/docs/configuration/service/broadcast-relay.rst +++ b/docs/configuration/service/broadcast-relay.rst @@ -20,7 +20,7 @@ Configuration .. cfgcmd:: set service broadcast-relay id <n> description <description> A description can be added for each and every unique relay ID. This is - useful to distinguish between multiple different ports/appliactions. + useful to distinguish between multiple different ports/applications. .. cfgcmd:: set service broadcast-relay id <n> interface <interface> @@ -35,7 +35,7 @@ Configuration .. cfgcmd:: set service broadcast-relay id <n> port <port> - The UDP port number used by your apllication. It is mandatory for this kind + The UDP port number used by your application. It is mandatory for this kind of operation. .. cfgcmd:: set service broadcast-relay id <n> disable diff --git a/docs/configuration/service/config-sync.rst b/docs/configuration/service/config-sync.rst new file mode 100644 index 00000000..d0449a78 --- /dev/null +++ b/docs/configuration/service/config-sync.rst @@ -0,0 +1,114 @@ +.. _config-sync: + +########### +Config Sync +########### + +Configuration synchronization (config sync) is a feature of VyOS that +permits synchronization of the configuration of one VyOS router to +another in a network. + +The main benefit to configuration synchronization is that it eliminates having +to manually replicate configuration changes made on the primary router to the +secondary (replica) router. + +The writing of the configuration to the secondary router is performed through +the VyOS HTTP API. The user can specify which portion(s) of the configuration will +be synchronized and the mode to use - whether to replace or add. + +To prevent issues with divergent configurations between the pair of routers, +synchronization is strictly unidirectional from primary to replica. Both +routers should be online and run the same version of VyOS. + +Configuration +------------- + +.. cfgcmd:: set service config-sync secondary + <address|key|timeout|port> + + Specify the address, API key, timeout and port of the secondary router. + You need to enable and configure the HTTP API service on the secondary + router for config sync to operate. + +.. cfgcmd:: set service config-sync section <section> + + Specify the section of the configuration to synchronize. If more than one + section is to be synchronized, repeat the command to add additional + sections as required. + +.. cfgcmd:: set service config-sync mode <load|set> + + Two options are available for `mode`: either `load` and replace or `set` + the configuration section. + +.. code-block:: none + + Supported options for <section> include: + firewall + interfaces <interface> + nat + nat66 + pki + policy + protocols <protocol> + qos <interface|policy> + service <service> + system <conntrack| + flow-accounting|option|sflow|static-host-mapping|sysctl|time-zone> + vpn + vrf + +Example +------- +* Synchronize the time-zone and OSPF configuration from Router A to Router B +* The address of Router B is 10.0.20.112 and the port used is 8443 + +Configure the HTTP API service on Router B + +.. code-block:: none + + set service https listen-address '10.0.20.112' + set service https port '8443' + set service https api keys id KID key 'foo' + +Configure the config-sync service on Router A + +.. code-block:: none + + set service config-sync mode 'load' + set service config-sync secondary address '10.0.20.112' + set service config-sync secondary port '8443' + set service config-sync secondary key 'foo' + set service config-sync section protocols 'ospf' + set service config-sync section system 'time-zone' + +Make config-sync relevant changes to Router A's configuration + +.. code-block:: none + + vyos@vyos-A# set system time-zone 'America/Los_Angeles' + vyos@vyos-A# commit + INFO:vyos_config_sync:Config synchronization: Mode=load, + Secondary=10.0.20.112 + vyos@vyos-A# save + + vyos@vyos-A# set protocols ospf area 0 network '10.0.48.0/30' + vyos@vyos-A# commit + INFO:vyos_config_sync:Config synchronization: Mode=load, + Secondary=10.0.20.112 + yos@vyos-A# save + +Verify configuration changes have been replicated to Router B + +.. code-block:: none + + vyos@vyos-B:~$ show configuration commands | match time-zone + set system time-zone 'America/Los_Angeles' + + vyos@vyos-B:~$ show configuration commands | match ospf + set protocols ospf area 0 network '10.0.48.0/30' + +Known issues +------------ +Configuration resynchronization. With the current implementation of `service +config-sync`, the secondary node must be online. diff --git a/docs/configuration/service/conntrack-sync.rst b/docs/configuration/service/conntrack-sync.rst index db23c92f..232db1a8 100644 --- a/docs/configuration/service/conntrack-sync.rst +++ b/docs/configuration/service/conntrack-sync.rst @@ -29,7 +29,7 @@ will be mandatorily defragmented. It is possible to use either Multicast or Unicast to sync conntrack traffic. Most examples below show Multicast, but unicast can be specified by using the -"peer" keywork after the specificed interface, as in the following example: +"peer" keywork after the specified interface, as in the following example: :cfgcmd:`set service conntrack-sync interface eth0 peer 192.168.0.250` @@ -204,7 +204,7 @@ Now configure conntrack-sync service on ``router1`` **and** ``router2`` .. code-block:: none - set high-availablilty vrrp group internal virtual-address ... etc ... + set high-availability vrrp group internal virtual-address ... etc ... set high-availability vrrp sync-group syncgrp member 'internal' set service conntrack-sync accept-protocol 'tcp' set service conntrack-sync accept-protocol 'udp' diff --git a/docs/configuration/service/https.rst b/docs/configuration/service/https.rst index 973c5355..af397456 100644 --- a/docs/configuration/service/https.rst +++ b/docs/configuration/service/https.rst @@ -53,7 +53,11 @@ Configuration .. cfgcmd:: set service https vrf <name> - Start Webserver in given VRF. + Start Webserver in given VRF. + +.. cfgcmd:: set service https request-body-size-limit <size> + + Set the maximum request body size in megabytes. Default is 1MB. API === @@ -70,7 +74,36 @@ API .. cfgcmd:: set service https api strict - Enforce strict path checking + Enforce strict path checking. + +.. cfgcmd:: set service https api cors allow-origin <origin> + + Allow cross-origin requests from `<origin>`. + +GraphQL +======= + +.. cfgcmd:: set service https api graphql introspection + + Enable GraphQL Schema introspection. + +.. note:: Do not leave introspection enabled in production, it is a security risk. + +.. cfgcmd:: set service https api graphql authentication type <key | token> + + Set the authentication type for GraphQL, default option is key. Available options are: + + * ``key`` use API keys configured in ``service https api keys`` + + * ``token`` use JWT tokens. + +.. cfgcmd:: set service https api graphql authentication expiration + + Set the lifetime for JWT tokens in seconds. Default is 3600 seconds. + +.. cfgcmd:: set service https api graphql authentication secret-length + + Set the byte length of the JWT secret. Default is 32. ********************* Example Configuration diff --git a/docs/configuration/service/ids.rst b/docs/configuration/service/ids.rst index 3e508d50..8a64467f 100644 --- a/docs/configuration/service/ids.rst +++ b/docs/configuration/service/ids.rst @@ -33,7 +33,7 @@ Configuration Configure direction for processing traffic. .. cfgcmd:: set service ids ddos-protection exclude-network <x.x.x.x/x> -.. cfgcmd:: set service ids ddos-protection exlude-network <h:h:h:h:h:h:h:h/x> +.. cfgcmd:: set service ids ddos-protection exclude-network <h:h:h:h:h:h:h:h/x> Specify IPv4 and/or IPv6 networks which are going to be excluded. @@ -56,7 +56,7 @@ Configuration .. cfgcmd:: set service ids ddos-protection sflow port <1-65535> - Configure port number to be used for sflow conection. Default port is 6343. + Configure port number to be used for sflow connection. Default port is 6343. .. cfgcmd:: set service ids ddos-protection threshold general [fps | mbps | pps] <0-4294967294> @@ -96,7 +96,7 @@ In this simplified scenario, main things to be considered are: * Interface **eth0** used to connect to upstream. Since we are analyzing attacks to and from our internal network, two types -of attacks can be identified, and differents actions are needed: +of attacks can be identified, and different actions are needed: * External attack: an attack from the internet towards an internal IP is identify. In this case, all connections towards such IP will be diff --git a/docs/configuration/service/index.rst b/docs/configuration/service/index.rst index 56ce55eb..abb77ef4 100644 --- a/docs/configuration/service/index.rst +++ b/docs/configuration/service/index.rst @@ -8,6 +8,7 @@ Service :includehidden: broadcast-relay + config-sync conntrack-sync console-server dhcp-relay diff --git a/docs/configuration/service/ipoe-server.rst b/docs/configuration/service/ipoe-server.rst index 64048552..ef06bcd5 100644 --- a/docs/configuration/service/ipoe-server.rst +++ b/docs/configuration/service/ipoe-server.rst @@ -26,13 +26,13 @@ functionality as PPPoE, but in a less robust manner. Configuring IPoE Server *********************** -IPoE can be configure on different interfaces, it will depend on each specific -situation which interface will provide IPoE to clients. The clients mac address +IPoE can be configured on different interfaces, it will depend on each specific +situation which interface will provide IPoE to clients. The client's mac address and the incoming interface is being used as control parameter, to authenticate a client. The example configuration below will assign an IP to the client on the incoming -interface eth2 with the client mac address 08:00:27:2f:d8:06. Other DHCP +interface eth1 with the client mac address 00:50:79:66:68:00. Other DHCP discovery requests will be ignored, unless the client mac has been enabled in the configuration. @@ -85,12 +85,11 @@ the configuration. .. cfgcmd:: set service ipoe-server interface <interface> mode <l2 | l3> - Set authentication backend. The configured authentication backend is used - for all queries. + Specifies the client connectivity mode. * **l2**: It means that clients are on same network where interface is.**(default)** - * **local**: It means that client are behind some router. + * **l3**: It means that client are behind some router. .. cfgcmd:: set service ipoe-server interface <interface> network <shared | vlan> @@ -279,7 +278,7 @@ IPv6 .. code-block:: none set service ipoe-server client-ipv6-pool IPv6-POOL delegate '2001:db8:8003::/48' delegation-prefix '56' - set service ipoe-server client-ipv6-pool IPV6-POOL prefix '2001:db8:8002::/48' mask '64' + set service ipoe-server client-ipv6-pool IPv6-POOL prefix '2001:db8:8002::/48' mask '64' set service ipoe-server default-ipv6-pool IPv6-POOL ********* @@ -434,7 +433,7 @@ Toubleshooting .. code-block:: none - vyos@vyos:~$sudo journalctl -u accel-ppp@ipoe -b 0 + vyos@vyos:~$ show log ipoe-server Feb 27 14:29:27 vyos accel-ipoe[2262]: eth1.100:: recv [DHCPv4 Discover xid=55df9228 chaddr=0c:98:bd:b8:00:01 <Message-Type Discover> <Request-IP 192.168.0.3> <Host-Name vyos> <Request-List Subnet,Broadcast,Router,DNS,Classless-Route,Domain-Name,MTU>] Feb 27 14:29:27 vyos accel-ipoe[2262]: eth1.100:eth1.100: eth1.100: authentication succeeded @@ -447,4 +446,4 @@ Toubleshooting .. include:: /_include/common-references.txt .. _dictionary: https://github.com/accel-ppp/accel-ppp/blob/master/accel-pppd/radius/dict/dictionary.rfc6911 -.. _`ACCEL-PPP attribute`: https://github.com/accel-ppp/accel-ppp/blob/master/accel-pppd/radius/dict/dictionary.accel
\ No newline at end of file +.. _`ACCEL-PPP attribute`: https://github.com/accel-ppp/accel-ppp/blob/master/accel-pppd/radius/dict/dictionary.accel diff --git a/docs/configuration/service/ntp.rst b/docs/configuration/service/ntp.rst index e7ee392b..266376cf 100644 --- a/docs/configuration/service/ntp.rst +++ b/docs/configuration/service/ntp.rst @@ -46,9 +46,9 @@ Configuration There are 3 default NTP server set. You are able to change them. - * ``0.pool.ntp.org`` - * ``1.pool.ntp.org`` - * ``2.pool.ntp.org`` + * ``time1.vyos.net`` + * ``time2.vyos.net`` + * ``time3.vyos.net`` .. cfgcmd:: set service ntp server <address> <noselect | nts | pool | prefer> @@ -85,7 +85,7 @@ Configuration .. cfgcmd:: set service ntp leap-second [ignore|smear|system|timezone] - Define how to handle leaf-seonds. + Define how to handle leap-seconds. * `ignore`: No correction is applied to the clock for the leap second. The clock will be corrected later in normal operation when new measurements are diff --git a/docs/configuration/service/pppoe-server.rst b/docs/configuration/service/pppoe-server.rst index 99b3fbb5..d9a16036 100644 --- a/docs/configuration/service/pppoe-server.rst +++ b/docs/configuration/service/pppoe-server.rst @@ -24,7 +24,6 @@ Configuring PPPoE Server set service pppoe-server authentication local-users username test password 'test' set service pppoe-server client-ip-pool PPPOE-POOL range 192.168.255.2-192.168.255.254 set service pppoe-server default-pool 'PPPOE-POOL' - set service pppoe-server outside-address 192.0.2.2 set service pppoe-server gateway-address 192.168.255.1 set service pppoe-server interface eth0 @@ -374,7 +373,7 @@ IPv6 set service pppoe-server ppp-options ipv6 allow set service pppoe-server client-ipv6-pool IPv6-POOL delegate '2001:db8:8003::/48' delegation-prefix '56' - set service pppoe-server client-ipv6-pool IPV6-POOL prefix '2001:db8:8002::/48' mask '64' + set service pppoe-server client-ipv6-pool IPv6-POOL prefix '2001:db8:8002::/48' mask '64' set service pppoe-server default-ipv6-pool IPv6-POOL IPv6 Advanced Options diff --git a/docs/configuration/service/router-advert.rst b/docs/configuration/service/router-advert.rst index ca558b6a..8f984b10 100644 --- a/docs/configuration/service/router-advert.rst +++ b/docs/configuration/service/router-advert.rst @@ -38,7 +38,7 @@ Configuration "Cur Hop Limit", "hop-limit", "Hop count field of the outgoing RA packets" """Managed address configuration"" flag", "managed-flag", "Tell hosts to use the administered stateful protocol (i.e. DHCP) for autoconfiguration" """Other configuration"" flag", "other-config-flag", "Tell hosts to use the administered (stateful) protocol (i.e. DHCP) for autoconfiguration of other (non-address) information" - "MTU","link-mtu","Link MTU value placed in RAs, exluded in RAs if unset" + "MTU","link-mtu","Link MTU value placed in RAs, excluded in RAs if unset" "Router Lifetime","default-lifetime","Lifetime associated with the default router in units of seconds" "Reachable Time","reachable-time","Time, in milliseconds, that a node assumes a neighbor is reachable after having received a reachability confirmation" "Retransmit Timer","retrans-timer","Time in milliseconds between retransmitted Neighbor Solicitation messages" diff --git a/docs/configuration/service/salt-minion.rst b/docs/configuration/service/salt-minion.rst index aa747c36..8638246b 100644 --- a/docs/configuration/service/salt-minion.rst +++ b/docs/configuration/service/salt-minion.rst @@ -17,7 +17,7 @@ Requirements ************ To use the Salt-Minion, a running Salt-Master is required. You can find more -in the `Salt Poject Documentaion +in the `Salt Project Documentation <https://docs.saltproject.io/en/latest/contents.html>`_ ************* diff --git a/docs/configuration/system/conntrack.rst b/docs/configuration/system/conntrack.rst index 6ed5fef7..1401e02e 100644 --- a/docs/configuration/system/conntrack.rst +++ b/docs/configuration/system/conntrack.rst @@ -94,7 +94,7 @@ states. .. cfgcmd:: set system conntrack timeout udp stream <1-21474836> :defaultvalue: - Set the timeout in secounds for a protocol or state. + Set the timeout in seconds for a protocol or state. You can also 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 @@ -172,7 +172,7 @@ create a rule defining the packet and flow selector. .. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999> protocol udp unreplied <1-21474836> - Set the timeout in secounds for a protocol or state in a custom rule. + Set the timeout in seconds for a protocol or state in a custom rule. Conntrack ignore rules ====================== diff --git a/docs/configuration/system/flow-accounting.rst b/docs/configuration/system/flow-accounting.rst index 8d46b178..30d6fc4d 100644 --- a/docs/configuration/system/flow-accounting.rst +++ b/docs/configuration/system/flow-accounting.rst @@ -50,7 +50,7 @@ interface, the interface must be configured for flow accounting. Configure and enable collection of flow information for the interface identified by `<interface>`. - You can configure multiple interfaces which whould participate in flow + You can configure multiple interfaces which would participate in flow accounting. .. note:: Will be recorded only packets/flows on **incoming** direction in diff --git a/docs/configuration/system/host-name.rst b/docs/configuration/system/host-name.rst index d062fc62..4d1567bf 100644 --- a/docs/configuration/system/host-name.rst +++ b/docs/configuration/system/host-name.rst @@ -65,4 +65,4 @@ This section shows how to statically map an IP address to a hostname for local Thus the address configured as :cfgcmd:`set system static-host-mapping host-name <hostname> inet <address>` can be reached via multiple names. - Multiple aliases can pe specified per host-name. + Multiple aliases can be specified per host-name. diff --git a/docs/configuration/system/ip.rst b/docs/configuration/system/ip.rst index 279630e2..a422388f 100644 --- a/docs/configuration/system/ip.rst +++ b/docs/configuration/system/ip.rst @@ -30,7 +30,7 @@ System configuration commands Zebra/Kernel route filtering ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Zebra supports prefix-lists and Route Mapss to match routes received from +Zebra supports prefix-lists and Route Maps to match routes received from other FRR components. The permit/deny facilities provided by these commands can be used to filter which routes zebra will install in the kernel. @@ -48,7 +48,7 @@ Nexthop Tracking Nexthop tracking resolve nexthops via the default route by default. This is enabled by default for a traditional profile of FRR which we use. It and can be disabled if -you do not wan't to e.g. allow BGP to peer across the default route. +you do not want to e.g. allow BGP to peer across the default route. .. cfgcmd:: set system ip nht no-resolve-via-default diff --git a/docs/configuration/system/ipv6.rst b/docs/configuration/system/ipv6.rst index d8d3c4c9..cde7a2aa 100644 --- a/docs/configuration/system/ipv6.rst +++ b/docs/configuration/system/ipv6.rst @@ -26,7 +26,7 @@ System configuration commands Zebra/Kernel route filtering ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Zebra supports prefix-lists and Route Mapss to match routes received from +Zebra supports prefix-lists and Route Maps to match routes received from other FRR components. The permit/deny facilities provided by these commands can be used to filter which routes zebra will install in the kernel. @@ -44,7 +44,7 @@ Nexthop Tracking Nexthop tracking resolve nexthops via the default route by default. This is enabled by default for a traditional profile of FRR which we use. It and can be disabled if -you do not wan't to e.g. allow BGP to peer across the default route. +you do not want to e.g. allow BGP to peer across the default route. .. cfgcmd:: set system ipv6 nht no-resolve-via-default diff --git a/docs/configuration/system/option.rst b/docs/configuration/system/option.rst index 02c889dd..44c66186 100644 --- a/docs/configuration/system/option.rst +++ b/docs/configuration/system/option.rst @@ -88,7 +88,7 @@ Keyboard Layout *************** When starting a VyOS live system (the installation CD) the configured keyboard -layout defaults to US. As this might not suite everyones use case you can adjust +layout defaults to US. As this might not suite everyone's use case you can adjust the used keyboard layout on the system console. .. cfgcmd:: set system option keyboard-layout <us | fr | de | fi | no | dk> diff --git a/docs/configuration/system/sflow.rst b/docs/configuration/system/sflow.rst index c2cf5a80..0c8bf03b 100644 --- a/docs/configuration/system/sflow.rst +++ b/docs/configuration/system/sflow.rst @@ -29,7 +29,7 @@ Configuration Configure and enable collection of flow information for the interface identified by <interface>. - You can configure multiple interfaces which whould participate in sflow accounting. + You can configure multiple interfaces which would participate in sflow accounting. .. cfgcmd:: set system sflow polling <sec> diff --git a/docs/configuration/system/syslog.rst b/docs/configuration/system/syslog.rst index 8755d905..cc7ac676 100644 --- a/docs/configuration/system/syslog.rst +++ b/docs/configuration/system/syslog.rst @@ -45,7 +45,7 @@ Custom File .. cfgcmd:: set system syslog file <filename> archive file <number> - Syslog uses logrotate to rotate logiles after a number of gives bytes. + Syslog uses logrotate to rotate logfiles after a number of gives bytes. We keep as many as `<number>` rotated file before they are deleted on the system. @@ -200,7 +200,7 @@ Display Logs .. opcmd:: show log [all | authorization | cluster | conntrack-sync | ...] Display log files of given category on the console. Use tab completion to get - a list of available categories. Thos categories could be: all, authorization, + a list of available categories. Those categories could be: all, authorization, cluster, conntrack-sync, dhcp, directory, dns, file, firewall, https, image lldp, nat, openvpn, snmp, tail, vpn, vrrp diff --git a/docs/configuration/system/task-scheduler.rst b/docs/configuration/system/task-scheduler.rst index 382da39f..4a754ba3 100644 --- a/docs/configuration/system/task-scheduler.rst +++ b/docs/configuration/system/task-scheduler.rst @@ -7,7 +7,7 @@ Task Scheduler The task scheduler allows you to execute tasks on a given schedule. It makes use of UNIX cron_. -.. note:: All scripts excecuted this way are executed as root user - this may +.. note:: All scripts executed this way are executed as root user - this may be dangerous. Together with :ref:`command-scripting` this can be used for automating (re-)configuration. diff --git a/docs/configuration/trafficpolicy/index.rst b/docs/configuration/trafficpolicy/index.rst index 3463592f..f99c2a66 100644 --- a/docs/configuration/trafficpolicy/index.rst +++ b/docs/configuration/trafficpolicy/index.rst @@ -368,7 +368,7 @@ are to be sent, they could get dropped when trying to get enqueued at the tail. This can happen if the queue has still not been able to release enough packets from its head. -This is the policy that requieres the lowest resources for the same +This is the policy that requires the lowest resources for the same amount of traffic. But **very likely you do not need it as you cannot get much from it. Sometimes it is used just to enable logging.** @@ -504,7 +504,7 @@ and increase `interval` to something around 150 ms. the number of sub-queues (default: 1024) into which packets are classified. -.. cfgcmd:: set qos policy fq-codel <policy name> interval <miliseconds> +.. cfgcmd:: set qos policy fq-codel <policy name> interval <milliseconds> Use this command to configure an fq-codel policy, set its name and the time period used by the control loop of CoDel to detect when a @@ -518,7 +518,7 @@ and increase `interval` to something around 150 ms. define a hard limit on the real queue size. When this limit is reached, new packets are dropped (default: 10240 packets). -.. cfgcmd:: set qos policy fq-codel <policy-name> target <miliseconds> +.. cfgcmd:: set qos policy fq-codel <policy-name> target <milliseconds> Use this command to configure an fq-codel policy, set its name, and define the acceptable minimum standing/persistent queue delay. This @@ -710,7 +710,7 @@ continuously, packets from lower priority classes will only be transmitted after traffic volume from higher priority classes decreases. -.. note:: In Priority Queue we do not define clases with a meaningless +.. note:: In Priority Queue we do not define classes with a meaningless class ID number but with a class priority number (1-7). The lower the number, the higher the priority. @@ -912,7 +912,7 @@ In principle, values must be Rate Control ------------ -| **Queueing discipline:** Tocken Bucket Filter. +| **Queueing discipline:** Token Bucket Filter. | **Applies to:** Outbound traffic. Rate-Control is a classless policy that limits the packet flow to a set @@ -1145,6 +1145,74 @@ A simple example of Shaper using priorities. set qos policy shaper MY-HTB default priority '7' set qos policy shaper MY-HTB default queue-type 'fair-queue' +.. _CAKE: + +CAKE +------ + +| **Queueing discipline:** Deficit mode. +| **Applies to:** Outbound traffic. + +`Common Applications Kept Enhanced`_ (CAKE) is a comprehensive queue management +system, implemented as a queue discipline (qdisc) for the Linux kernel. It is +designed to replace and improve upon the complex hierarchy of simple qdiscs +presently required to effectively tackle the bufferbloat problem at the network +edge. + +.. cfgcmd:: set qos policy cake <text> bandwidth <value> + + Set the shaper bandwidth, either as an explicit bitrate or a percentage + of the interface bandwidth. + +.. cfgcmd:: set qos policy cake <text> description + + Set a description for the shaper. + +.. cfgcmd:: set qos policy cake <text> flow-isolation blind + + Disables flow isolation, all traffic passes through a single queue. + +.. cfgcmd:: set qos policy cake <text> flow-isolation dst-host + + Flows are defined only by destination address. + +.. cfgcmd:: set qos policy cake <text> flow-isolation dual-dst-host + + Flows are defined by the 5-tuple. Fairness is applied first over destination + addresses, then over individual flows. + +.. cfgcmd:: set qos policy cake <text> flow-isolation dual-src-host + + Flows are defined by the 5-tuple. Fairness is applied first over source + addresses, then over individual flows. + +.. cfgcmd:: set qos policy cake <text> flow-isolation flow + + Flows are defined by the entire 5-tuple (source IP address, source port, + destination IP address, destination port, transport protocol). + +.. cfgcmd:: set qos policy cake <text> flow-isolation host + + Flows are defined by source-destination host pairs. + +.. cfgcmd:: set qos policy cake <text> flow-isolation nat + + Perform NAT lookup before applying flow-isolation rules. + +.. cfgcmd:: set qos policy cake <text> flow-isolation src-host + + Flows are defined only by source address. + +.. cfgcmd:: set qos policy cake <text> flow-isolation triple-isolate + + **(Default)** Flows are defined by the 5-tuple, fairness is applied over source and + destination addresses and also over individual flows. + +.. cfgcmd:: set qos policy cake <text> rtt + + Defines the round-trip time used for active queue management (AQM) in + milliseconds. The default value is 100. + Applying a traffic policy ========================= @@ -1220,5 +1288,6 @@ That is how it is possible to do the so-called "ingress shaping". .. _tocken bucket: https://en.wikipedia.org/wiki/Token_bucket .. _HFSC: https://en.wikipedia.org/wiki/Hierarchical_fair-service_curve .. _Intermediate Functional Block: https://www.linuxfoundation.org/collaborate/workgroups/networking/ifb +.. _Common Applications Kept Enhanced: https://www.bufferbloat.net/projects/codel/wiki/Cake/ .. start_vyoslinter diff --git a/docs/configuration/vpn/l2tp.rst b/docs/configuration/vpn/l2tp.rst index f0c60ec1..b64c91a9 100644 --- a/docs/configuration/vpn/l2tp.rst +++ b/docs/configuration/vpn/l2tp.rst @@ -318,7 +318,7 @@ IPv6 set vpn l2tp remote-access ppp-options ipv6 allow set vpn l2tp remote-access client-ipv6-pool IPv6-POOL delegate '2001:db8:8003::/48' delegation-prefix '56' - set vpn l2tp remote-access client-ipv6-pool IPV6-POOL prefix '2001:db8:8002::/48' mask '64' + set vpn l2tp remote-access client-ipv6-pool IPv6-POOL prefix '2001:db8:8002::/48' mask '64' set vpn l2tp remote-access default-ipv6-pool IPv6-POOL IPv6 Advanced Options diff --git a/docs/configuration/vpn/pptp.rst b/docs/configuration/vpn/pptp.rst index 2a5e7731..5220929f 100644 --- a/docs/configuration/vpn/pptp.rst +++ b/docs/configuration/vpn/pptp.rst @@ -242,7 +242,7 @@ IPv6 set vpn pptp remote-access ppp-options ipv6 allow set vpn pptp remote-access client-ipv6-pool IPv6-POOL delegate '2001:db8:8003::/48' delegation-prefix '56' - set vpn pptp remote-access client-ipv6-pool IPV6-POOL prefix '2001:db8:8002::/48' mask '64' + set vpn pptp remote-access client-ipv6-pool IPv6-POOL prefix '2001:db8:8002::/48' mask '64' set vpn pptp remote-access default-ipv6-pool IPv6-POOL IPv6 Advanced Options diff --git a/docs/configuration/vpn/sstp.rst b/docs/configuration/vpn/sstp.rst index 3749eb7b..cc942ee5 100644 --- a/docs/configuration/vpn/sstp.rst +++ b/docs/configuration/vpn/sstp.rst @@ -276,7 +276,7 @@ IPv6 set vpn sstp ppp-options ipv6 allow set vpn sstp client-ipv6-pool IPv6-POOL delegate '2001:db8:8003::/48' delegation-prefix '56' - set vpn sstp client-ipv6-pool IPV6-POOL prefix '2001:db8:8002::/48' mask '64' + set vpn sstp client-ipv6-pool IPv6-POOL prefix '2001:db8:8002::/48' mask '64' set vpn sstp default-ipv6-pool IPv6-POOL IPv6 Advanced Options diff --git a/docs/configuration/vrf/index.rst b/docs/configuration/vrf/index.rst index 67eba886..0d6b895f 100644 --- a/docs/configuration/vrf/index.rst +++ b/docs/configuration/vrf/index.rst @@ -43,7 +43,7 @@ then enslaved to a VRF device. Zebra/Kernel route filtering ---------------------------- -Zebra supports prefix-lists and Route Mapss to match routes received from +Zebra supports prefix-lists and Route Maps to match routes received from other FRR components. The permit/deny facilities provided by these commands can be used to filter which routes zebra will install in the kernel. @@ -72,7 +72,7 @@ Nexthop Tracking Nexthop tracking resolve nexthops via the default route by default. This is enabled by default for a traditional profile of FRR which we use. It and can be disabled if -you do not wan't to e.g. allow BGP to peer across the default route. +you do not want to e.g. allow BGP to peer across the default route. .. cfgcmd:: set vrf name <name> ip nht no-resolve-via-default |