diff options
Diffstat (limited to 'docs/configuration')
43 files changed, 761 insertions, 249 deletions
diff --git a/docs/configuration/container/index.rst b/docs/configuration/container/index.rst index e63ac2c9..e5a470bc 100644 --- a/docs/configuration/container/index.rst +++ b/docs/configuration/container/index.rst @@ -117,7 +117,7 @@ Configuration Add a host device to the container. -.. cfgcmd:: set container name <name> cap-add <text> +.. cfgcmd:: set container name <name> capability <text> Set container capabilities or permissions. @@ -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 5d9190d6..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 ...``. @@ -163,7 +163,7 @@ Zone-based firewall zone -With zone-based firewalls a new concept was implemented, in addtion to the +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 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/bridge.rst b/docs/configuration/interfaces/bridge.rst index ddc293cc..e69a6e26 100644 --- a/docs/configuration/interfaces/bridge.rst +++ b/docs/configuration/interfaces/bridge.rst @@ -127,15 +127,24 @@ Enable VLAN-Aware Bridge .. cfgcmd:: set interfaces bridge <interface> enable-vlan - To activate the VLAN aware bridge, you must activate this setting to use VLAN + To activate the VLAN aware bridge, you must activate this setting to use VLAN settings for the bridge +.. cfgcmd:: set interfaces bridge <interface> protocol <802.1ad|802.1q> + + Define used ethertype of bridge interface. + + Ethertype ``0x8100`` is used for ``802.1q`` and ethertype ``0x88a8`` is used + for ``802.1ad``. + + The default is ``802.1q``. + VLAN Options ------------ .. note:: It is not valid to use the `vif 1` option for VLAN aware bridges - because VLAN aware bridges assume that all unlabeled packets belong to - the default VLAN 1 member and that the VLAN ID of the bridge's parent + because VLAN aware bridges assume that all unlabeled packets belong to + the default VLAN 1 member and that the VLAN ID of the bridge's parent interface is always 1 .. cmdinclude:: /_include/interface-vlan-8021q.txt @@ -149,9 +158,9 @@ VLAN Options 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 - + Example: Set `eth0` member port to be native VLAN 2 - + .. code-block:: none set interfaces bridge br1 member interface eth0 native-vlan 2 @@ -162,17 +171,17 @@ VLAN Options Allows specific VLAN IDs to pass through the bridge member interface. This can either be an individual VLAN id or a range of VLAN ids delimited by a hyphen. - + Example: Set `eth0` member port to be allowed VLAN 4 - + .. code-block:: none - + set interfaces bridge br1 member interface eth0 allowed-vlan 4 - + Example: Set `eth0` member port to be allowed VLAN 6-8 - + .. code-block:: none - + set interfaces bridge br1 member interface eth0 allowed-vlan 6-8 Port Mirror (SPAN) @@ -265,17 +274,17 @@ This results in the active configuration: Using the operation mode command to view Bridge Information =========================================================== -.. opcmd:: show bridge +.. opcmd:: show bridge The `show bridge` operational command can be used to display configured bridges: .. code-block:: none - vyos@vyos:~$ show bridge - 3: eth1: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 master br0 state forwarding - priority 32 cost 100 - 4: eth2: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 master br0 state forwarding + vyos@vyos:~$ show bridge + 3: eth1: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 master br0 state forwarding + priority 32 cost 100 + 4: eth2: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 master br0 state forwarding priority 32 cost 100 .. opcmd:: show bridge <name> fdb @@ -304,11 +313,11 @@ Using the operation mode command to view Bridge Information 33:33:00:00:00:6a dev br0 self permanent 01:00:5e:00:00:01 dev br0 self permanent 33:33:ff:00:00:00 dev br0 self permanent - + .. opcmd:: show bridge <name> mdb - Show bridge `<name>` mdb displays the current multicast group membership - table.The table is populated by IGMP and MLD snooping in the bridge driver + Show bridge `<name>` mdb displays the current multicast group membership + table.The table is populated by IGMP and MLD snooping in the bridge driver automatically. .. code-block:: none 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/interfaces/loopback.rst b/docs/configuration/interfaces/loopback.rst index 8e983abb..b5fbdf83 100644 --- a/docs/configuration/interfaces/loopback.rst +++ b/docs/configuration/interfaces/loopback.rst @@ -14,7 +14,7 @@ services on your local machine. you need multiple interfaces, please use the :ref:`dummy-interface` interface type. -.. hint:: A lookback interface is always up, thus it could be used for +.. hint:: A loopback interface is always up, thus it could be used for management traffic or as source/destination for and :abbr:`IGP (Interior Gateway Protocol)` like :ref:`routing-bgp` so your internal BGP link is not dependent on physical link states and multiple routes can be chosen to the diff --git a/docs/configuration/interfaces/openvpn.rst b/docs/configuration/interfaces/openvpn.rst index d92ac080..8cf579de 100644 --- a/docs/configuration/interfaces/openvpn.rst +++ b/docs/configuration/interfaces/openvpn.rst @@ -547,7 +547,7 @@ example: openvpn-option "--plugin /usr/lib/openvpn/openvpn-auth-ldap.so /config/auth/ldap-auth.config" openvpn-option "--push redirect-gateway" openvpn-option --duplicate-cn - openvpn-option --client-cert-not-required + openvpn-option "--verify-client-cert none" openvpn-option --comp-lzo openvpn-option --persist-key openvpn-option --persist-tun diff --git a/docs/configuration/loadbalancing/reverse-proxy.rst b/docs/configuration/loadbalancing/reverse-proxy.rst index 19ef3773..970e084e 100644 --- a/docs/configuration/loadbalancing/reverse-proxy.rst +++ b/docs/configuration/loadbalancing/reverse-proxy.rst @@ -43,7 +43,7 @@ Service .. cfgcmd:: set load-balancing reverse-proxy service <name> ssl certificate <name> - Set SSL certeficate <name> for service <name> + Set SSL certificate <name> for service <name> Rules @@ -97,8 +97,8 @@ Backend .. cfgcmd:: set load-balancing reverse-proxy backend <name> balance <balance> - Load-balancing algorithms to be used for distributind requests among the - vailable servers + Load-balancing algorithms to be used for distributed requests among the + available servers Balance algorithms: * ``source-address`` Distributes requests based on the source IP address @@ -144,9 +144,49 @@ Backend Send a Proxy Protocol version 2 header (binary format) +.. 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> -Gloabal +.. cfgcmd:: set load-balancing reverse-proxy backend <name> ssl no-verify + + 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 ------- Global parameters @@ -207,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 @@ -243,12 +284,12 @@ to the backend ``bk-api-02`` Terminate SSL ------------- -The following configuration reverse-proxy terminate SSL. +The following configuration terminates SSL on the router. -The ``http`` service is lestens on port 80 and force redirects from HTTP to +The ``http`` service is listens on port 80 and force redirects from HTTP to HTTPS. -The ``https`` service listens on port 443 with backend `bk-default` to +The ``https`` service listens on port 443 with backend ``bk-default`` to handle HTTPS traffic. It uses certificate named ``cert`` for SSL termination. Rule 10 matches requests with the exact URL path ``/.well-known/xxx`` @@ -287,3 +328,61 @@ 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 +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. + +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`` + + +.. code-block:: none + + set load-balancing reverse-proxy service https backend 'bk-bridge-ssl' + set load-balancing reverse-proxy service https description 'listen on 443 port' + 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 backend bk-bridge-ssl description 'SSL backend' + set load-balancing reverse-proxy backend bk-bridge-ssl mode 'http' + set load-balancing reverse-proxy backend bk-bridge-ssl ssl ca-certificate '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-map.rst b/docs/configuration/policy/route-map.rst index 07cfcf02..ccc4cef0 100644 --- a/docs/configuration/policy/route-map.rst +++ b/docs/configuration/policy/route-map.rst @@ -197,12 +197,15 @@ Route Map BGP aggregator attribute: AS number or IP address of an aggregation. .. cfgcmd:: set policy route-map <text> rule <1-65535> set as-path exclude - <text> + <1-4294967295 | all> Drop AS-NUMBER from the BGP AS path. + If ``all`` is specified, remove all AS numbers from the AS_PATH of the BGP + path's NLRI. + .. cfgcmd:: set policy route-map <text> rule <1-65535> set as-path prepend - <text> + <1-4294967295> Prepend the given string of AS numbers to the AS_PATH of the BGP path's NLRI. @@ -233,11 +236,11 @@ Route Map .. cfgcmd:: set policy route-map <text> rule <1-65535> set large-community <add|replace> <GA:LDP1:LDP2> - Add or replace BGP large-community attribute in format + Add or replace BGP large-community attribute in format ``<0-4294967295:0-4294967295:0-4294967295>`` .. cfgcmd:: set policy route-map <text> rule <1-65535> set large-community none - + Delete all BGP large-communities .. cfgcmd:: set policy route-map <text> rule <1-65535> set large-community delete @@ -375,11 +378,3 @@ List of well-known communities * ``accept-own-nexthop`` - Well-known communities value accept-own-nexthop 0xFFFF0008 * ``blackhole`` - Well-known communities value BLACKHOLE 0xFFFF029A * ``no-peer`` - Well-known communities value NOPEER 0xFFFFFF04 - - - - - - - - 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/failover.rst b/docs/configuration/protocols/failover.rst index daeb65f4..8088e104 100644 --- a/docs/configuration/protocols/failover.rst +++ b/docs/configuration/protocols/failover.rst @@ -2,10 +2,10 @@ Failover ######## -Failover routes are manually configured routes, but they install +Failover routes are manually configured routes, but they only install to the routing table if the health-check target is alive. If the target is not alive the route is removed from the routing table -until the target will be available. +until the target becomes available. *************** Failover Routes 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/protocols/rpki.rst b/docs/configuration/protocols/rpki.rst index aeb2941b..17557884 100644 --- a/docs/configuration/protocols/rpki.rst +++ b/docs/configuration/protocols/rpki.rst @@ -11,20 +11,19 @@ RPKI -- `tweet by EvilMog`_, 2020-02-21 -:abbr:`RPKI (Resource Public Key Infrastructure)` is a framework :abbr:`PKI -(Public Key Infrastructure)` designed to secure the Internet routing -infrastructure. It associates BGP route announcements with the correct -originating :abbr:`ASN (Autonomus System Number)` which BGP routers can then -use to check each route against the corresponding :abbr:`ROA (Route Origin -Authorisation)` for validity. RPKI is described in :rfc:`6480`. +:abbr:`RPKI (Resource Public Key Infrastructure)` is a framework designed to +secure the Internet routing infrastructure. It associates BGP route +announcements with the correct originating :abbr:`ASN (Autonomus System +Number)` which BGP routers can then use to check each route against the +corresponding :abbr:`ROA (Route Origin Authorisation)` for validity. RPKI is +described in :rfc:`6480`. A BGP-speaking router like VyOS can retrieve ROA information from RPKI "Relying Party software" (often just called an "RPKI server" or "RPKI validator") by using :abbr:`RTR (RPKI to Router)` protocol. There are several open source implementations to choose from, such as NLNetLabs' Routinator_ -(written in Rust), Cloudflare's GoRTR_ and OctoRPKI_ (written in Go), and -RIPE NCC's RPKI Validator_ (written in Java). The RTR protocol is described -in :rfc:`8210`. +(written in Rust), OpenBSD's rpki-client_ (written in C), and StayRTR_ (written +in Go). The RTR protocol is described in :rfc:`8210`. .. tip:: If you are new to these routing security technologies then there is an @@ -38,10 +37,9 @@ in :rfc:`8210`. Getting started *************** -First you will need to deploy an RPKI validator for your routers to use. The -RIPE NCC helpfully provide `some instructions`_ to get you started with -several different options. Once your server is running you can start -validating announcements. +First you will need to deploy an RPKI validator for your routers to use. NLnet +Labs provides a collection of software_ you can compare and settle on one. +Once your server is running you can start validating announcements. Imported prefixes during the validation may have values: @@ -56,16 +54,16 @@ Imported prefixes during the validation may have values: untrustworthy route announcements. notfound - No ROA exists which covers that prefix. Unfortunately this is the case - for about 80% of the IPv4 prefixes which were announced to the :abbr:`DFZ - (default-free zone)` at the start of 2020 + No ROA exists which covers that prefix. Unfortunately this is the case for + about 40%-50% of the prefixes which were announced to the :abbr:`DFZ + (default-free zone)` at the start of 2024. .. note:: If you are responsible for the global addresses assigned to your network, please make sure that your prefixes have ROAs associated with them to avoid being `notfound` by RPKI. For most ASNs this will involve publishing ROAs via your :abbr:`RIR (Regional Internet Registry)` (RIPE - NCC, APNIC, ARIN, LACNIC or AFRINIC), and is something you are encouraged + NCC, APNIC, ARIN, LACNIC, or AFRINIC), and is something you are encouraged to do whenever you plan to announce addresses into the DFZ. Particularly large networks may wish to run their own RPKI certificate @@ -140,11 +138,13 @@ Configuration SSH === -Connections to the RPKI caching server can not only be established by HTTP/TLS -but you can also rely on a secure SSH session to the server. To enable SSH, -first you need to create an SSH client keypair using ``generate ssh -client-key /config/auth/id_rsa_rpki``. Once your key is created you can setup -the connection. +Connections to the RPKI caching server can not only be established by TCP using +the RTR protocol but you can also rely on a secure SSH session to the server. +This provides transport integrity and confidentiality and it is a good idea if +your validation software supports it. To enable SSH, first you need to create +an SSH client keypair using ``generate ssh client-key +/config/auth/id_rsa_rpki``. Once your key is created you can setup the +connection. .. cfgcmd:: set protocols rpki cache <address> ssh username <user> @@ -191,20 +191,21 @@ filter we reject prefixes with the state `invalid`, and set a higher set policy route-map ROUTES-IN rule 30 match rpki 'invalid' Once your routers are configured to reject RPKI-invalid prefixes, you can -test whether the configuration is working correctly using the `RIPE Labs RPKI -Test`_ experimental tool. +test whether the configuration is working correctly using Cloudflare's test_ +website. Keep in mind that in order for this to work, you need to have no +default routes or anything else that would still send traffic to RPKI-invalid +destinations. .. stop_vyoslinter .. _tweet by EvilMog: https://twitter.com/Evil_Mog/status/1230924170508169216 .. _Routinator: https://www.nlnetlabs.nl/projects/rpki/routinator/ -.. _GoRTR: https://github.com/cloudflare/gortr -.. _OctoRPKI: https://github.com/cloudflare/cfrpki#octorpki -.. _Validator: https://www.ripe.net/manage-ips-and-asns/resource-management/rpki/tools-and-resources -.. _some instructions: https://labs.ripe.net/Members/tashi_phuntsho_3/how-to-install-an-rpki-validator .. _Krill: https://www.nlnetlabs.nl/projects/rpki/krill/ -.. _RIPE Labs RPKI Test: https://sg-pub.ripe.net/jasper/rpki-web-test/ .. _excellent guide to RPKI: https://rpki.readthedocs.io/ .. _help and operational guidance: https://rpki.readthedocs.io/en/latest/about/help.html +.. _rpki-client: https://www.rpki-client.org/ +.. _StayRTR: https://github.com/bgp/stayrtr/ +.. _software: https://rpki.readthedocs.io/en/latest/ops/tools.html#relying-party-software +.. _test: https://isbgpsafeyet.com/ .. start_vyoslinter 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/conntrack-sync.rst b/docs/configuration/service/conntrack-sync.rst index d43f2385..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` @@ -102,6 +102,11 @@ Configuration Disable connection logging via Syslog. +.. cfgcmd:: set service conntrack-sync startup-resync + + Order conntrackd to request a complete conntrack table resync against + the other node at startup. + ********* Operation ********* @@ -199,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/dhcp-server.rst b/docs/configuration/service/dhcp-server.rst index 6813d2c0..50e9ee7e 100644 --- a/docs/configuration/service/dhcp-server.rst +++ b/docs/configuration/service/dhcp-server.rst @@ -49,10 +49,26 @@ Configuration Inform client that the DNS server can be found at `<address>`. This is the configuration parameter for the entire shared network definition. - All subnets will inherit this configuration item if not specified locally. - + All subnets will inherit this configuration item if not specified locally. Multiple DNS servers can be defined. +.. cfgcmd:: set service dhcp-server shared-network-name <name> option + vendor-option <option-name> + + This configuration parameter lets you specify a vendor-option for the + entire shared network definition. All subnets will inherit this + configuration item if not specified locally. An example for Ubiquiti is + shown below: + +**Example:** + +Pass address of Unifi controller at ``172.16.100.1`` to all clients of ``NET1`` + +.. code-block:: none + + set service dhcp-server shared-network-name 'NET1' option vendor-option + ubiquiti '172.16.100.1' + .. cfgcmd:: set service dhcp-server listen-address <address> This configuration parameter lets the DHCP server to listen for DHCP @@ -132,28 +148,62 @@ Individual Client Subnet request where no full FQDN is passed. This option can be given multiple times if you need multiple search domains (DHCP Option 119). -Failover --------- +.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet> + option vendor-option <option-name> + + This configuration parameter lets you specify a vendor-option for the + subnet specified within the shared network definition. An example for + Ubiquiti is shown below: + +**Example:** + +Create ``172.18.201.0/24`` as a subnet within ``NET1`` and pass address of +Unifi controller at ``172.16.100.1`` to clients of that subnet. + +.. code-block:: none + + set service dhcp-server shared-network-name 'NET1' subnet + '172.18.201.0/24' option vendor-option ubiquiti '172.16.100.1' + + +High Availability +----------------- -VyOS provides support for DHCP failover. DHCP failover must be configured -explicitly by the following statements. +VyOS provides High Availability support for DHCP server. DHCP High +Availability can act in two different modes: -.. cfgcmd:: set service dhcp-server failover source-address <address> +* **Active-active**: both DHCP servers will respond to DHCP requests. If + ``mode`` is not defined, this is the default behavior. - Local IP `<address>` used when communicating to the failover peer. +* **Active-passive**: only ``primary`` server will respond to DHCP requests. + If this server goes offline, then ``secondary`` server will take place. -.. cfgcmd:: set service dhcp-server failover remote <address> +DHCP High Availability must be configured explicitly by the following +statements on both servers: - Remote peer IP `<address>` of the second DHCP server in this failover +.. cfgcmd:: set service dhcp-server high-availability mode [active-active + | active-passive] + + Define operation mode of High Availability feature. Default value if command + is not specified is `active-active` + +.. cfgcmd:: set service dhcp-server high-availability source-address <address> + + Local IP `<address>` used when communicating to the HA peer. + +.. cfgcmd:: set service dhcp-server high-availability remote <address> + + Remote peer IP `<address>` of the second DHCP server in this HA cluster. -.. cfgcmd:: set service dhcp-server failover name <name> +.. cfgcmd:: set service dhcp-server high-availability name <name> A generic `<name>` referencing this sync service. .. note:: `<name>` must be identical on both sides! -.. cfgcmd:: set service dhcp-server failover status <primary | secondary> +.. cfgcmd:: set service dhcp-server high-availability status <primary + | secondary> The primary and secondary statements determines whether the server is primary or secondary. @@ -162,12 +212,12 @@ explicitly by the following statements. their lease tables in sync, they must be able to reach each other on TCP port 647. If you have firewall rules in effect, adjust them accordingly. - .. hint:: The dialogue between failover partners is neither encrypted nor + .. hint:: The dialogue between HA partners is neither encrypted nor authenticated. Since most DHCP servers exist within an organisation's own secure Intranet, this would be an unnecessary overhead. However, if you - have DHCP failover peers whose communications traverse insecure networks, + have DHCP HA peers whose communications traverse insecure networks, then we recommend that you consider the use of VPN tunneling between them - to ensure that the failover partnership is immune to disruption + to ensure that the HA partnership is immune to disruption (accidental or otherwise) via third parties. Static mappings @@ -371,12 +421,13 @@ Please see the :ref:`dhcp-dns-quick-start` configuration. .. _dhcp-server:v4_example_failover: -Failover --------- +High Availability +----------------- -Configuration of a DHCP failover pair +Configuration of a DHCP HA pair: -* Setup DHCP failover for network 192.0.2.0/24 +* Setup DHCP HA for network 192.0.2.0/24 +* Use active-active HA mode. * Default gateway and DNS server is at `192.0.2.254` * The primary DHCP server uses address `192.168.189.252` * The secondary DHCP server uses address `192.168.189.253` @@ -398,19 +449,21 @@ Common configuration, valid for both primary and secondary node. .. code-block:: none - set service dhcp-server failover source-address '192.168.189.252' - set service dhcp-server failover name 'NET-VYOS' - set service dhcp-server failover remote '192.168.189.253' - set service dhcp-server failover status 'primary' + set service dhcp-server high-availability mode 'active-active' + set service dhcp-server high-availability source-address '192.168.189.252' + set service dhcp-server high-availability name 'NET-VYOS' + set service dhcp-server high-availability remote '192.168.189.253' + set service dhcp-server high-availability status 'primary' **Secondary** .. code-block:: none - set service dhcp-server failover source-address '192.168.189.253' - set service dhcp-server failover name 'NET-VYOS' - set service dhcp-server failover remote '192.168.189.252' - set service dhcp-server failover status 'secondary' + set service dhcp-server high-availability mode 'active-active' + set service dhcp-server high-availability source-address '192.168.189.253' + set service dhcp-server high-availability name 'NET-VYOS' + set service dhcp-server high-availability remote '192.168.189.252' + set service dhcp-server high-availability status 'secondary' .. _dhcp-server:v4_example_raw: diff --git a/docs/configuration/service/dns.rst b/docs/configuration/service/dns.rst index c6deb179..365e7885 100644 --- a/docs/configuration/service/dns.rst +++ b/docs/configuration/service/dns.rst @@ -143,6 +143,100 @@ avoid being tracked by the provider of your upstream DNS server. 168.192.in-addr.arpa, 16-31.172.in-addr.arpa, which enabling upstream DNS server(s) to be used for reverse lookups of these zones. +Authoritative zones +------------------- + +The VyOS DNS forwarder can also be configured to host authoritative records for a domain. + +.. cfgcmd:: set service dns forwarding authoritative-domain <domain-name> disable + + Disable hosting authoritative zone for `<domain-name>` without deleting from + configuration. + +.. cfgcmd:: set service dns forwarding authoritative-domain <domain-name> records <type> + <name> disable + + Disable specific record without deleting it from configuration. + +.. cfgcmd:: set service dns forwarding authoritative-domain <domain-name> records <type> + <name> ttl <seconds> + + Set the :abbr:`TTL (Time-to-live)` for the record in seconds. Default is 300 seconds. + +Record types +^^^^^^^^^^^^ + +Below are a list of record types available to be configured within VyOS. Some records +support special `<name>` keywords: + +* ``@`` Use @ as record name to set the record for the root domain. + +* ``any`` Use any as record name to configure the record as a wildcard. + +.. cfgcmd:: set service dns forwarding authoritative-domain <domain-name> records + a <name> address <x.x.x.x> + + Set an :abbr:`A (Address)` record. Supports ``@`` and ``any`` keywords. + +.. cfgcmd:: set service dns forwarding authoritative-domain <domain-name> records + aaaa <name> address <h:h:h:h:h:h:h:h> + + Set an :abbr:`AAAA (IPv6 Address)` record. Supports ``@`` and ``any`` keywords. + +.. cfgcmd:: set service dns forwarding authoritative-domain <domain-name> records + cname <name> target <target-domain-name> + + Set an :abbr:`CNAME (Canonical name)` record. Supports ``@`` keyword. + +.. cfgcmd:: set service dns forwarding authoritative-domain <domain-name> records + naptr <name> rule <rule-number> <option> <value> + + Set an :abbr:`NAPTR (Naming authority pointer)` record. Supports ``@`` keyword. + NAPTR records support the following options: + + * **lookup-a** A Flag. + + * **lookup-srv** S flag. + + * **order** Rule order. Requires `<value>`. + + * **preference** Rule preference. Requires `<value>`. Defaults to 0 if not set. + + * **protocol-specific** P flag. + + * **regexp** Regular expression. Requires `<value>`. + + * **replacement** Replacement DNS name. + + * **resolve-uri** U flag. + + * **service** Service type. Requires `<value>`. + +.. cfgcmd:: set service dns forwarding authoritative-domain <domain-name> records + ns <name> target <target-name> + + Set an :abbr:`NS (Nameserver)` record. + +.. cfgcmd:: set service dns forwarding authoritative-domain <domain-name> records + ptr <name> target <target-name> + + Set an :abbr:`PTR (Pointer record)` record. Supports ``@`` keyword. + +.. cfgcmd:: set service dns forwarding authoritative-domain <domain-name> records + spf <name> value <value> + + Set an :abbr:`SPF (Sender policy framework)` record. Supports ``@`` keyword. + +.. cfgcmd:: set service dns forwarding authoritative-domain <domain-name> records + srv <name> entry <entry-number> [hostname | port | priority | weight] <value> + + Set an :abbr:`SRV (Service)` record. Supports ``@`` keyword. + +.. cfgcmd:: set service dns forwarding authoritative-domain <domain-name> records + txt <name> value <value> + + Set an :abbr:`TXT (Text)` record. Supports ``@`` keyword. + Example ======= @@ -208,7 +302,7 @@ one involves a third party service, like DynDNS.com or any other such service provider. This method uses HTTP requests to transmit the new IP address. You can configure both in VyOS. -.. _dns:dynmaic_config: +.. _dns:dynamic_config: Configuration ============= @@ -254,7 +348,7 @@ Configuration Specify interval in seconds to wait between Dynamic DNS updates. The default is 300 seconds. -.. _dns:dynmaic_example: +.. _dns:dynamic_example: Example ^^^^^^^ 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/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 f179153a..8f984b10 100644 --- a/docs/configuration/service/router-advert.rst +++ b/docs/configuration/service/router-advert.rst @@ -13,6 +13,7 @@ Supported interface types: * bonding * bridge * ethernet + * geneve * l2tpv3 * openvpn * pseudo-ethernet @@ -22,9 +23,9 @@ Supported interface types: * wireless * wwan - -Enabling Advertisments -~~~~~~~~~~~~~~~~~~~~~~~ +************* +Configuration +************* .. cfgcmd:: set service router-advert interface <interface> ... @@ -37,7 +38,7 @@ Enabling Advertisments "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" @@ -50,7 +51,7 @@ Enabling Advertisments Advertising a Prefix -'''''''''''''''''''' +-------------------- .. cfgcmd:: set service router-advert interface <interface> prefix <prefix/mask> @@ -73,30 +74,48 @@ Advertising a Prefix .. start_vyoslinter +Advertising a NAT64 Prefix +-------------------------- + +.. cfgcmd:: set service router-advert interface <interface> nat64prefix <prefix/mask> + + Enable PREF64 option as outlined in :rfc:`8781`. + + NAT64 prefix mask must be one of: /32, /40, /48, /56, /64 or 96. + + .. note:: The well known NAT64 prefix is ``64:ff9b::/96`` + +.. stop_vyoslinter + +.. csv-table:: + :header: "VyOS Field", "Description" + :widths: 10,30 + + "valid-lifetime","Time in seconds that the prefix will remain valid (default: 65528 seconds)" + +.. start_vyoslinter + Disabling Advertisements -~~~~~~~~~~~~~~~~~~~~~~~~ +------------------------ To disable advertisements without deleting the configuration: .. cfgcmd:: set service router-advert interface <interface> no-send-advert -Example Configuration -~~~~~~~~~~~~~~~~~~~~~ + +******* +Example +******* + +Your LAN connected on eth0 uses prefix ``2001:db8:beef:2::/64`` with the router +beeing ``2001:db8:beef:2::1`` .. code-block:: none - interface eth0.2 { - default-preference high - hop-limit 64 - interval { - max 600 - } - name-server 2001:db8::1 - name-server 2001:db8::2 - other-config-flag - prefix 2001:db8:beef:2::/64 { - valid-lifetime 2592000 - } - reachable-time 0 - retrans-timer 0 - } + set interfaces ethernet eth0 address 2001:db8:beef:2::1/64 + + set service router-advert interface eth0 default-preference 'high' + set service router-advert interface eth0 name-server '2001:db8::1' + set service router-advert interface eth0 name-server '2001:db8::2' + set service router-advert interface eth0 other-config-flag + set service router-advert interface eth0 prefix 2001:db8:beef:2::/64 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 |