diff options
Diffstat (limited to 'docs/configuration')
43 files changed, 1309 insertions, 256 deletions
diff --git a/docs/configuration/container/index.rst b/docs/configuration/container/index.rst index 988b425b..4dacc6f4 100644 --- a/docs/configuration/container/index.rst +++ b/docs/configuration/container/index.rst @@ -21,19 +21,43 @@ Configuration If a registry is not specified, Docker.io will be used as the container registry unless an alternative registry is specified using - **set container registry <name>** or the registry is included in the image name + **set container registry <name>** or the registry is included + in the image name .. code-block:: none set container name mysql-server image quay.io/mysql:8.0 +.. cfgcmd:: set container name <name> entrypoint <entrypoint> + + Override the default entrypoint from the image for a container. + +.. cfgcmd:: set container name <name> command <command> + + Override the default command from the image for a container. + +.. cfgcmd:: set container name <name> arguments <arguments> + + Set the command arguments for a container. + +.. cfgcmd:: set container name <name> host-name <hostname> + + Set the host name for a container. + +.. cfgcmd:: set container name <name> allow-host-pid + + The container and the host share the same process namespace. + This means that processes running on the host are visible inside the + container, and processes inside the container are visible on the host. + + The command translates to "--pid host" when the container is created. + .. cfgcmd:: set container name <name> allow-host-networks Allow host networking in a container. The network stack of the container is not isolated from the host and will use the host IP. - The following commands translate to "--net host" when the container - is created + The command translates to "--net host" when the container is created. .. note:: **allow-host-networks** cannot be used with **network** @@ -47,7 +71,8 @@ Configuration Optionally set a specific static IPv4 or IPv6 address for the container. This address must be within the named network prefix. - .. note:: The first IP in the container network is reserved by the engine and cannot be used + .. note:: The first IP in the container network is reserved by the + engine and cannot be used .. cfgcmd:: set container name <name> description <text> @@ -103,8 +128,10 @@ Configuration Set the restart behavior of the container. - **no**: Do not restart containers on exit - - **on-failure**: Restart containers when they exit with a non-zero exit code, retrying indefinitely (default) - - **always**: Restart containers when they exit, regardless of status, retrying indefinitely + - **on-failure**: Restart containers when they exit with a non-zero + exit code, retrying indefinitely (default) + - **always**: Restart containers when they exit, regardless of status, + retrying indefinitely .. cfgcmd:: set container name <name> memory <MB> @@ -122,12 +149,18 @@ Configuration Set container capabilities or permissions. - **net-admin**: Network operations (interface, firewall, routing tables) - - **net-bind-service**: Bind a socket to privileged ports (port numbers less than 1024) + - **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> label <label> value <value> + + Add metadata label for this container. + .. cfgcmd:: set container name <name> disable Disable a container. @@ -145,8 +178,8 @@ Container Networks .. cfgcmd:: set container network <name> prefix <ipv4|ipv6> - Define IPv4 or IPv6 prefix for a given network name. Only one IPv4 and - one IPv6 prefix can be used per network name. + Define IPv4 and/or IPv6 prefix for a given network name. + Both IPv4 and IPv6 can be used in parallel. .. cfgcmd:: set container network <name> vrf <nme> @@ -216,7 +249,8 @@ Example Configuration ********************* For the sake of demonstration, `example #1 in the official documentation - <https://www.zabbix.com/documentation/current/manual/installation/containers>`_ + <https://www.zabbix.com/documentation/current/manual/ + installation/containers>`_ to the declarative VyOS CLI syntax. .. code-block:: none 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..e8a5f2e8 100644 --- a/docs/configuration/firewall/flowtables.rst +++ b/docs/configuration/firewall/flowtables.rst @@ -17,7 +17,8 @@ can be done regarding flowtables. .. cfgcmd:: set firewall flowtables ... -From main structure defined in :doc:`Firewall Overview</configuration/firewall/index>` +From main structure defined in +:doc:`Firewall Overview</configuration/firewall/index>` in this section you can find detailed information only for the next part of the general structure: @@ -99,20 +100,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 +153,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/groups.rst b/docs/configuration/firewall/groups.rst index aee68793..6111650a 100644 --- a/docs/configuration/firewall/groups.rst +++ b/docs/configuration/firewall/groups.rst @@ -21,9 +21,9 @@ Address Groups In an **address group** a single IP address or IP address ranges are defined. -.. cfgcmd:: set firewall group address-group <name> address [address | +.. cfgcmd:: set firewall group address-group <name> address [address | address range] -.. cfgcmd:: set firewall group ipv6-address-group <name> address <address> +.. cfgcmd:: set firewall group ipv6-address-group <name> address <address> Define a IPv4 or a IPv6 address group @@ -33,8 +33,8 @@ defined. set firewall group address-group ADR-INSIDE-v4 address 10.0.0.1-10.0.0.8 set firewall group ipv6-address-group ADR-INSIDE-v6 address 2001:db8::1 -.. cfgcmd:: set firewall group address-group <name> description <text> -.. cfgcmd:: set firewall group ipv6-address-group <name> description <text> +.. cfgcmd:: set firewall group address-group <name> description <text> +.. cfgcmd:: set firewall group ipv6-address-group <name> description <text> Provide a IPv4 or IPv6 address group description @@ -46,8 +46,8 @@ IP addresses can be added as a 32-bit prefix. If you foresee the need to add a mix of addresses and networks, the network group is recommended. -.. cfgcmd:: set firewall group network-group <name> network <CIDR> -.. cfgcmd:: set firewall group ipv6-network-group <name> network <CIDR> +.. cfgcmd:: set firewall group network-group <name> network <CIDR> +.. cfgcmd:: set firewall group ipv6-network-group <name> network <CIDR> Define a IPv4 or IPv6 Network group. @@ -57,8 +57,8 @@ recommended. set firewall group network-group NET-INSIDE-v4 network 192.168.1.0/24 set firewall group ipv6-network-group NET-INSIDE-v6 network 2001:db8::/64 -.. cfgcmd:: set firewall group network-group <name> description <text> -.. cfgcmd:: set firewall group ipv6-network-group <name> description <text> +.. cfgcmd:: set firewall group network-group <name> description <text> +.. cfgcmd:: set firewall group ipv6-network-group <name> description <text> Provide an IPv4 or IPv6 network group description. @@ -67,7 +67,7 @@ Interface Groups An **interface group** represents a collection of interfaces. -.. cfgcmd:: set firewall group interface-group <name> interface <text> +.. cfgcmd:: set firewall group interface-group <name> interface <text> Define an interface group. Wildcard are accepted too. @@ -76,7 +76,7 @@ An **interface group** represents a collection of interfaces. set firewall group interface-group LAN interface bond1001 set firewall group interface-group LAN interface eth3* -.. cfgcmd:: set firewall group interface-group <name> description <text> +.. cfgcmd:: set firewall group interface-group <name> description <text> Provide an interface group description @@ -110,7 +110,7 @@ MAC Groups A **mac group** represents a collection of mac addresses. -.. cfgcmd:: set firewall group mac-group <name> mac-address <mac-address> +.. cfgcmd:: set firewall group mac-group <name> mac-address <mac-address> Define a mac group. @@ -128,7 +128,7 @@ Domain Groups A **domain group** represents a collection of domains. -.. cfgcmd:: set firewall group domain-group <name> address <domain> +.. cfgcmd:: set firewall group domain-group <name> address <domain> Define a domain group. @@ -140,10 +140,108 @@ A **domain group** represents a collection of domains. Provide a domain group description. +Dynamic Groups +============== + +Firewall dynamic groups are different from all the groups defined previously +because, not only they can be used as source/destination in firewall rules, +but members of these groups are not defined statically using vyos +configuration. + +Instead, members of these groups are added dynamically using firewall +rules. + +Defining Dynamic Address Groups +------------------------------- + +Dynamic address group is supported by both IPv4 and IPv6 families. +Commands used to define dynamic IPv4|IPv6 address groups are: + +.. cfgcmd:: set firewall group dynamic-group address-group <name> +.. cfgcmd:: set firewall group dynamic-group ipv6-address-group <name> + +Add description to firewall groups: + +.. cfgcmd:: set firewall group dynamic-group address-group <name> + description <text> +.. cfgcmd:: set firewall group dynamic-group ipv6-address-group <name> + description <text> + +Adding elements to Dynamic Firewall Groups +------------------------------------------ + +Once dynamic firewall groups are defined, they should be used in firewall +rules in order to dynamically add elements to it. + +Commands used for this task are: + +* Add destination IP address of the connection to a dynamic address group: + +.. cfgcmd:: set firewall ipv4 [forward | input | output] filter rule + <1-999999> add-address-to-group destination-address address-group <name> +.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> add-address-to-group + destination-address address-group <name> +.. cfgcmd:: set firewall ipv6 [forward | input | output] filter rule + <1-999999> add-address-to-group destination-address address-group <name> +.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> add-address-to-group + destination-address address-group <name> + +* Add source IP address of the connection to a dynamic address group: + +.. cfgcmd:: set firewall ipv4 [forward | input | output] filter rule + <1-999999> add-address-to-group source-address address-group <name> +.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> add-address-to-group + source-address address-group <name> +.. cfgcmd:: set firewall ipv6 [forward | input | output] filter rule + <1-999999> add-address-to-group source-address address-group <name> +.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> add-address-to-group + source-address address-group <name> + +Also, specific timeout can be defined per rule. In case rule gets a hit, +source or destinatination address will be added to the group, and this +element will remain in the group until timeout expires. If no timeout +is defined, then the element will remain in the group until next reboot, +or until a new commit that changes firewall configuration is done. + +.. cfgcmd:: set firewall ipv4 [forward | input | output] filter rule + <1-999999> add-address-to-group [destination-address | source-address] + timeout <timeout> +.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> add-address-to-group + [destination-address | source-address] timeout <timeout> +.. cfgcmd:: set firewall ipv6 [forward | input | output] filter rule + <1-999999> add-address-to-group [destination-address | source-address] + timeout <timeout> +.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> add-address-to-group + [destination-address | source-address] timeout <timeout> + +Timeout can be defined using seconds, minutes, hours or days: + +.. code-block:: none + + set firewall ipv6 name FOO rule 10 add-address-to-group source-address timeout + Possible completions: + <number>s Timeout value in seconds + <number>m Timeout value in minutes + <number>h Timeout value in hours + <number>d Timeout value in days + +Using Dynamic Firewall Groups +----------------------------- + +As any other firewall group, dynamic firewall groups can be used in firewall +rules as matching options. For example: + +.. code-block:: none + set firewall ipv4 input filter rule 10 source group dynamic-address-group FOO + set firewall ipv4 input filter rule 10 destination group dynamic-address-group BAR + ******** Examples ******** +General example +=============== + As said before, once firewall groups are created, they can be referenced either in firewall, nat, nat66 and/or policy-route rules. @@ -166,12 +264,12 @@ And next, some configuration example where groups are used: .. code-block:: none - set firewall ipv4 input filter rule 10 action accept - set firewall ipv4 input filter rule 10 inbound-interface group !LAN + set firewall ipv4 output filter rule 10 action accept + set firewall ipv4 output filter rule 10 outbound-interface group !LAN set firewall ipv4 forward filter rule 20 action accept set firewall ipv4 forward filter rule 20 source group network-group TRUSTEDv4 set firewall ipv6 input filter rule 10 action accept - set firewall ipv6 input filter rule 10 source-group network-group TRUSTEDv6 + set firewall ipv6 input filter rule 10 source group network-group TRUSTEDv6 set nat destination rule 101 inbound-interface group LAN set nat destination rule 101 destination group address-group SERVERS set nat destination rule 101 protocol tcp @@ -181,30 +279,151 @@ And next, some configuration example where groups are used: set policy route PBR rule 201 protocol tcp set policy route PBR rule 201 set table 15 +Port knocking example +===================== + +Using dynamic firewall groups, we can secure access to the router, or any other +device if needed, by using the technique of port knocking. + +A 4 step port knocking example is shown next: + + .. code-block:: none + + set firewall global-options state-policy established action 'accept' + set firewall global-options state-policy invalid action 'drop' + set firewall global-options state-policy related action 'accept' + set firewall group dynamic-group address-group ALLOWED + set firewall group dynamic-group address-group PN_01 + set firewall group dynamic-group address-group PN_02 + set firewall ipv4 input filter default-action 'drop' + set firewall ipv4 input filter rule 5 action 'accept' + set firewall ipv4 input filter rule 5 protocol 'icmp' + set firewall ipv4 input filter rule 10 action 'drop' + set firewall ipv4 input filter rule 10 add-address-to-group source-address address-group 'PN_01' + set firewall ipv4 input filter rule 10 add-address-to-group source-address timeout '2m' + set firewall ipv4 input filter rule 10 description 'Port_nock 01' + set firewall ipv4 input filter rule 10 destination port '9990' + set firewall ipv4 input filter rule 10 protocol 'tcp' + set firewall ipv4 input filter rule 20 action 'drop' + set firewall ipv4 input filter rule 20 add-address-to-group source-address address-group 'PN_02' + set firewall ipv4 input filter rule 20 add-address-to-group source-address timeout '3m' + set firewall ipv4 input filter rule 20 description 'Port_nock 02' + set firewall ipv4 input filter rule 20 destination port '9991' + set firewall ipv4 input filter rule 20 protocol 'tcp' + set firewall ipv4 input filter rule 20 source group dynamic-address-group 'PN_01' + set firewall ipv4 input filter rule 30 action 'drop' + set firewall ipv4 input filter rule 30 add-address-to-group source-address address-group 'ALLOWED' + set firewall ipv4 input filter rule 30 add-address-to-group source-address timeout '2h' + set firewall ipv4 input filter rule 30 description 'Port_nock 03' + set firewall ipv4 input filter rule 30 destination port '9992' + set firewall ipv4 input filter rule 30 protocol 'tcp' + set firewall ipv4 input filter rule 30 source group dynamic-address-group 'PN_02' + set firewall ipv4 input filter rule 99 action 'accept' + set firewall ipv4 input filter rule 99 description 'Port_nock 04 - Allow ssh' + set firewall ipv4 input filter rule 99 destination port '22' + set firewall ipv4 input filter rule 99 protocol 'tcp' + set firewall ipv4 input filter rule 99 source group dynamic-address-group 'ALLOWED' + +Before testing, we can check members of firewall groups: + + .. code-block:: none + + vyos@vyos# run show firewall group + Firewall Groups + + Name Type References Members Timeout Expires + ------- ---------------------- -------------------- ------------- --------- --------- + ALLOWED address_group(dynamic) ipv4-input-filter-30 N/D N/D N/D + PN_01 address_group(dynamic) ipv4-input-filter-10 N/D N/D N/D + PN_02 address_group(dynamic) ipv4-input-filter-20 N/D N/D N/D + [edit] + vyos@vyos# + +With this configuration, in order to get ssh access to the router, user +needs to: + +1. Generate a new TCP connection with destination port 9990. As shown next, +a new entry was added to dynamic firewall group **PN_01** + + .. code-block:: none + + vyos@vyos# run show firewall group + Firewall Groups + + Name Type References Members Timeout Expires + ------- ---------------------- -------------------- ------------- --------- --------- + ALLOWED address_group(dynamic) ipv4-input-filter-30 N/D N/D N/D + PN_01 address_group(dynamic) ipv4-input-filter-10 192.168.89.31 120 119 + PN_02 address_group(dynamic) ipv4-input-filter-20 N/D N/D N/D + [edit] + vyos@vyos# + +2. Generate a new TCP connection with destination port 9991. As shown next, +a new entry was added to dynamic firewall group **PN_02** + + .. code-block:: none + + vyos@vyos# run show firewall group + Firewall Groups + + Name Type References Members Timeout Expires + ------- ---------------------- -------------------- ------------- --------- --------- + ALLOWED address_group(dynamic) ipv4-input-filter-30 N/D N/D N/D + PN_01 address_group(dynamic) ipv4-input-filter-10 192.168.89.31 120 106 + PN_02 address_group(dynamic) ipv4-input-filter-20 192.168.89.31 180 179 + [edit] + vyos@vyos# + +3. Generate a new TCP connection with destination port 9992. As shown next, +a new entry was added to dynamic firewall group **ALLOWED** + + .. code-block:: none + + vyos@vyos# run show firewall group + Firewall Groups + + Name Type References Members Timeout Expires + ------- ---------------------- -------------------- ------------- --------- --------- + ALLOWED address_group(dynamic) ipv4-input-filter-30 192.168.89.31 7200 7199 + PN_01 address_group(dynamic) ipv4-input-filter-10 192.168.89.31 120 89 + PN_02 address_group(dynamic) ipv4-input-filter-20 192.168.89.31 180 170 + [edit] + vyos@vyos# + +4. Now user can connect through ssh to the router (assuming ssh is configured). + ************** Operation-mode ************** +.. opcmd:: show firewall group .. opcmd:: show firewall group <name> - Overview of defined groups. You see the type, the members, and where the - group is used. + Overview of defined groups. You see the firewall group name, type, + references (where the group is used), members, timeout and expiration (last + two only present in dynamic firewall groups). + +Here is an example of such command: .. code-block:: none - vyos@ZBF-15-CLean:~$ show firewall group + vyos@vyos:~$ show firewall group Firewall Groups - Name Type References Members - ------------ ------------------ ---------------------- ---------------- - SERVERS address_group nat-destination-101 198.51.100.101 - 198.51.100.102 - LAN interface_group ipv4-input-filter-10 bon0 - nat-destination-101 eth2.2001 - TRUSTEDv6 ipv6_network_group ipv6-input-filter-10 2001:db8::/64 - TRUSTEDv4 network_group ipv4-forward-filter-20 192.0.2.0/30 - 203.0.113.128/25 - PORT-SERVERS port_group route-PBR-201 443 - nat-destination-101 5000-5010 - http - vyos@ZBF-15-CLean:~$ + Name Type References Members Timeout Expires + ------------ ---------------------- ---------------------- ---------------- --------- --------- + SERVERS address_group nat-destination-101 198.51.100.101 + 198.51.100.102 + ALLOWED address_group(dynamic) ipv4-input-filter-30 192.168.77.39 7200 7174 + PN_01 address_group(dynamic) ipv4-input-filter-10 192.168.0.245 120 112 + 192.168.77.39 120 85 + PN_02 address_group(dynamic) ipv4-input-filter-20 192.168.77.39 180 151 + LAN interface_group ipv4-output-filter-10 bon0 + nat-destination-101 eth2.2001 + TRUSTEDv6 ipv6_network_group ipv6-input-filter-10 2001:db8::/64 + TRUSTEDv4 network_group ipv4-forward-filter-20 192.0.2.0/30 + 203.0.113.128/25 + PORT-SERVERS port_group route-PBR-201 443 + route-PBR-201 5000-5010 + nat-destination-101 http + vyos@vyos:~$
\ No newline at end of file diff --git a/docs/configuration/firewall/index.rst b/docs/configuration/firewall/index.rst index 44e0cd20..1d904901 100644 --- a/docs/configuration/firewall/index.rst +++ b/docs/configuration/firewall/index.rst @@ -24,7 +24,7 @@ firewall are covered below: where the packet was received is part of a bridge, or not. If the interface where the packet was received isn't part of a bridge, then -packetis processed at the **IP Layer**: +packet is processed at the **IP Layer**: * **Prerouting**: several actions can be done in this stage, and currently these actions are defined in different parts in VyOS configuration. Order @@ -65,7 +65,7 @@ packetis processed at the **IP Layer**: * **Output**: stage where traffic that originates from the router itself can be filtered and controlled. Bear in mind that this traffic can be a new connection originated by a internal process running on VyOS router, - such as NTP, or a response to traffic received externaly through + such as NTP, or a response to traffic received externally through **input** (for example response to an ssh login attempt to the router). This includes ipv4 and ipv6 filtering rules, defined in: @@ -84,7 +84,7 @@ If the interface where the packet was received is part of a bridge, then the packet is processed at the **Bridge Layer**, which contains a basic setup for bridge filtering: - * **Forward (Bridge)**: stage where traffic that is trespasing through the + * **Forward (Bridge)**: stage where traffic that is trespassing through the bridge is filtered and controlled: * ``set firewall bridge forward filter ...``. diff --git a/docs/configuration/firewall/ipv4.rst b/docs/configuration/firewall/ipv4.rst index ff739418..f7f98dc7 100644 --- a/docs/configuration/firewall/ipv4.rst +++ b/docs/configuration/firewall/ipv4.rst @@ -11,12 +11,13 @@ 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 ... -From main structure defined in :doc:`Firewall Overview</configuration/firewall/index>` +From main structure defined in +:doc:`Firewall Overview</configuration/firewall/index>` in this section you can find detailed information only for the next part of the general structure: @@ -41,12 +42,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 +65,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 +185,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 +207,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. @@ -539,6 +540,27 @@ geoip) to keep database and rules updated. criteria. .. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + source group dynamic-address-group <name | !name> +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + source group dynamic-address-group <name | !name> +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + source group dynamic-address-group <name | !name> +.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> + source group dynamic-address-group <name | !name> + +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + destination group dynamic-address-group <name | !name> +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + destination group dynamic-address-group <name | !name> +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + destination group dynamic-address-group <name | !name> +.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> + destination group dynamic-address-group <name | !name> + + Use a specific dynamic-address-group. Prepend character ``!`` for inverted + matching criteria. + +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> source group network-group <name | !name> .. cfgcmd:: set firewall ipv4 input filter rule <1-999999> source group network-group <name | !name> @@ -683,9 +705,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 +717,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 +726,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 +738,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] @@ -843,13 +865,13 @@ geoip) to keep database and rules updated. set firewall ipv4 input filter rule 13 tcp flags not 'fin' .. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> - state [established | invalid | new | related] [enable | disable] + state [established | invalid | new | related] .. cfgcmd:: set firewall ipv4 input filter rule <1-999999> - state [established | invalid | new | related] [enable | disable] + state [established | invalid | new | related] .. cfgcmd:: set firewall ipv4 output filter rule <1-999999> - state [established | invalid | new | related] [enable | disable] + state [established | invalid | new | related] .. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> - state [established | invalid | new | related] [enable | disable] + state [established | invalid | new | related] Match against the state of a packet. @@ -934,13 +956,17 @@ Synproxy ******** Synproxy connections -.. cfgcmd:: set firewall ipv4 [input | forward] filter rule <1-999999> action synproxy -.. cfgcmd:: set firewall ipv4 [input | forward] filter rule <1-999999> protocol tcp -.. cfgcmd:: set firewall ipv4 [input | forward] filter rule <1-999999> synproxy tcp mss <501-65535> +.. cfgcmd:: set firewall ipv4 [input | forward] filter rule <1-999999> + action synproxy +.. cfgcmd:: set firewall ipv4 [input | forward] filter rule <1-999999> + protocol tcp +.. cfgcmd:: set firewall ipv4 [input | forward] filter rule <1-999999> + synproxy tcp mss <501-65535> Set TCP-MSS (maximum segment size) for the connection -.. cfgcmd:: set firewall ipv4 [input | forward] filter rule <1-999999> synproxy tcp window-scale <1-14> +.. cfgcmd:: set firewall ipv4 [input | forward] filter rule <1-999999> + synproxy tcp window-scale <1-14> Set the window scale factor for TCP window scaling @@ -964,12 +990,12 @@ Requirements to enable synproxy: set firewall global-options syn-cookies 'enable' set firewall ipv4 input filter rule 10 action 'synproxy' set firewall ipv4 input filter rule 10 destination port '8080' - set firewall ipv4 input filter rule 10 inbound-interface interface-name 'eth1' + set firewall ipv4 input filter rule 10 inbound-interface name 'eth1' set firewall ipv4 input filter rule 10 protocol 'tcp' set firewall ipv4 input filter rule 10 synproxy tcp mss '1460' set firewall ipv4 input filter rule 10 synproxy tcp window-scale '7' set firewall ipv4 input filter rule 1000 action 'drop' - set firewall ipv4 input filter rule 1000 state invalid 'enable' + set firewall ipv4 input filter rule 1000 state invalid *********************** @@ -1146,8 +1172,8 @@ Show Firewall log .. opcmd:: show log firewall ipv4 name <name> rule <rule> Show the logs of all firewall; show all ipv4 firewall logs; show all logs - for particular hook; show all logs for particular hook and priority; show all logs - for particular custom chain; show logs for specific Rule-Set. + for particular hook; show all logs for particular hook and priority; + show all logs for particular custom chain; show logs for specific Rule-Set. Example Partial Config ====================== diff --git a/docs/configuration/firewall/ipv6.rst b/docs/configuration/firewall/ipv6.rst index 0aa8a137..cbf18a7d 100644 --- a/docs/configuration/firewall/ipv6.rst +++ b/docs/configuration/firewall/ipv6.rst @@ -11,12 +11,13 @@ 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 ... -From main structure defined in :doc:`Firewall Overview</configuration/firewall/index>` +From main structure defined in +:doc:`Firewall Overview</configuration/firewall/index>` in this section you can find detailed information only for the next part of the general structure: @@ -41,12 +42,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 +65,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 +185,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 +207,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. @@ -373,10 +374,12 @@ There are a lot of matching criteria against which the packet can be tested. remain valid if the IPv6 prefix changes and the host portion of systems IPv6 address is static (for example, with SLAAC or `tokenised IPv6 addresses - <https://datatracker.ietf.org/doc/id/draft-chown-6man-tokenised-ipv6-identifiers-02.txt>`_) + <https://datatracker.ietf.org + /doc/id/draft-chown-6man-tokenised-ipv6-identifiers-02.txt>`_) This functions for both individual addresses and address groups. + .. stop_vyoslinter .. code-block:: none # Match any IPv6 address with the suffix ::0000:0000:0000:beef @@ -388,6 +391,8 @@ There are a lot of matching criteria against which the packet can be tested. set firewall ipv6 forward filter rule 200 source group address-group WEBSERVERS set firewall ipv6 forward filter rule 200 source address-mask ::ffff:ffff:ffff:ffff + .. start_vyoslinter + .. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> source fqdn <fqdn> .. cfgcmd:: set firewall ipv6 input filter rule <1-999999> @@ -526,6 +531,27 @@ geoip) to keep database and rules updated. criteria. .. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + source group dynamic-address-group <name | !name> +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + source group dynamic-address-group <name | !name> +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + source group dynamic-address-group <name | !name> +.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> + source group dynamic-address-group <name | !name> + +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + destination group dynamic-address-group <name | !name> +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + destination group dynamic-address-group <name | !name> +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + destination group dynamic-address-group <name | !name> +.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> + destination group dynamic-address-group <name | !name> + + Use a specific dynamic-address-group. Prepend character ``!`` for inverted + matching criteria. + +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> source group network-group <name | !name> .. cfgcmd:: set firewall ipv6 input filter rule <1-999999> source group network-group <name | !name> @@ -670,9 +696,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 +708,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 +717,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 +729,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] @@ -829,13 +855,13 @@ geoip) to keep database and rules updated. set firewall ipv6 input filter rule 13 tcp flags not 'fin' .. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> - state [established | invalid | new | related] [enable | disable] + state [established | invalid | new | related] .. cfgcmd:: set firewall ipv6 input filter rule <1-999999> - state [established | invalid | new | related] [enable | disable] + state [established | invalid | new | related] .. cfgcmd:: set firewall ipv6 output filter rule <1-999999> - state [established | invalid | new | related] [enable | disable] + state [established | invalid | new | related] .. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> - state [established | invalid | new | related] [enable | disable] + state [established | invalid | new | related] Match against the state of a packet. @@ -920,13 +946,17 @@ Synproxy ******** Synproxy connections -.. cfgcmd:: set firewall ipv6 [input | forward] filter rule <1-999999> action synproxy -.. cfgcmd:: set firewall ipv6 [input | forward] filter rule <1-999999> protocol tcp -.. cfgcmd:: set firewall ipv6 [input | forward] filter rule <1-999999> synproxy tcp mss <501-65535> +.. cfgcmd:: set firewall ipv6 [input | forward] filter rule <1-999999> + action synproxy +.. cfgcmd:: set firewall ipv6 [input | forward] filter rule <1-999999> + protocol tcp +.. cfgcmd:: set firewall ipv6 [input | forward] filter rule <1-999999> + synproxy tcp mss <501-65535> Set TCP-MSS (maximum segment size) for the connection -.. cfgcmd:: set firewall ipv6 [input | forward] filter rule <1-999999> synproxy tcp window-scale <1-14> +.. cfgcmd:: set firewall ipv6 [input | forward] filter rule <1-999999> + synproxy tcp window-scale <1-14> Set the window scale factor for TCP window scaling @@ -950,12 +980,12 @@ Requirements to enable synproxy: set firewall global-options syn-cookies 'enable' set firewall ipv6 input filter rule 10 action 'synproxy' set firewall ipv6 input filter rule 10 destination port '8080' - set firewall ipv6 input filter rule 10 inbound-interface interface-name 'eth1' + set firewall ipv6 input filter rule 10 inbound-interface name 'eth1' set firewall ipv6 input filter rule 10 protocol 'tcp' set firewall ipv6 input filter rule 10 synproxy tcp mss '1460' set firewall ipv6 input filter rule 10 synproxy tcp window-scale '7' set firewall ipv6 input filter rule 1000 action 'drop' - set firewall ipv6 input filter rule 1000 state invalid 'enable' + set firewall ipv6 input filter rule 1000 state invalid *********************** Operation-mode Firewall @@ -1146,8 +1176,8 @@ Show Firewall log .. opcmd:: show log firewall ipv6 name <name> rule <rule> Show the logs of all firewall; show all ipv6 firewall logs; show all logs - for particular hook; show all logs for particular hook and priority; show all logs - for particular custom chain; show logs for specific Rule-Set. + for particular hook; show all logs for particular hook and priority; + show all logs for particular custom chain; show logs for specific Rule-Set. Example Partial Config ====================== @@ -1177,7 +1207,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/bonding.rst b/docs/configuration/interfaces/bonding.rst index 3c8ebd0d..27f1bbed 100644 --- a/docs/configuration/interfaces/bonding.rst +++ b/docs/configuration/interfaces/bonding.rst @@ -156,6 +156,11 @@ Bond options The default value is slow. +.. cfgcmd:: set interfaces bonding <interface> system-mac <mac address> + + This option allow to specifies the 802.3ad system MAC address.You can set a + random mac-address that can be used for these LACPDU exchanges. + .. cfgcmd:: set interfaces bonding <interface> hash-policy <policy> * **layer2** - Uses XOR of hardware MAC addresses and packet type ID field @@ -286,6 +291,54 @@ Port Mirror (SPAN) :var1: bond1 :var2: eth3 +EVPN Multihoming +---------------- + +All-Active Multihoming is used for redundancy and load sharing. Servers are +attached to two or more PEs and the links are bonded (link-aggregation). +This group of server links is referred to as an :abbr:`ES (Ethernet Segment)`. + +An Ethernet Segment can be configured by specifying a system-MAC and a local +discriminator or a complete ESINAME against the bond interface on the PE. + +.. cfgcmd:: set interfaces bonding <interface> evpn es-id <<1-16777215|10-byte ID> +.. cfgcmd:: set interfaces bonding <interface> evpn es-sys-mac <xx:xx:xx:xx:xx:xx> + + The sys-mac and local discriminator are used for generating a 10-byte, Type-3 + Ethernet Segment ID. ESINAME is a 10-byte, Type-0 Ethernet Segment ID - + "00:AA:BB:CC:DD:EE:FF:GG:HH:II". + + Type-1 (EAD-per-ES and EAD-per-EVI) routes are used to advertise the locally + attached ESs and to learn off remote ESs in the network. Local Type-2/MAC-IP + routes are also advertised with a destination ESI allowing for MAC-IP syncing + between Ethernet Segment peers. Reference: RFC 7432, RFC 8365 + + EVPN-MH is intended as a replacement for MLAG or Anycast VTEPs. In multihoming + each PE has an unique VTEP address which requires the introduction of a new + dataplane construct, MAC-ECMP. Here a MAC/FDB entry can point to a list of + remote PEs/VTEPs. + +.. cfgcmd:: set interfaces bonding <interface> evpn es-df-pref <1-65535> + + Type-4 (ESR) routes are used for Designated Forwarder (DF) election. + DFs forward BUM traffic received via the overlay network. This + implementation uses a preference based DF election specified by + draft-ietf-bess-evpn-pref-df. + + The DF preference is configurable per-ES. + + BUM traffic is rxed via the overlay by all PEs attached to a server but + only the DF can forward the de-capsulated traffic to the access port. + To accommodate that non-DF filters are installed in the dataplane to drop + the traffic. + + Similarly traffic received from ES peers via the overlay cannot be forwarded + to the server. This is split-horizon-filtering with local bias. + +.. cmdinclude:: /_include/interface-evpn-uplink.txt + :var0: bonding + :var1: bond0 + ******* Example ******* @@ -590,4 +643,3 @@ Operation Partner Churn State: churned Actor Churned Count: 1 Partner Churned Count: 1 - diff --git a/docs/configuration/interfaces/ethernet.rst b/docs/configuration/interfaces/ethernet.rst index bbf52112..dd524035 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) ---------------------- @@ -102,6 +118,14 @@ Authentication (EAPoL) :var0: ethernet :var1: eth0 +EVPN Multihoming +---------------- + +Uplink/Core tracking. + +.. cmdinclude:: /_include/interface-evpn-uplink.txt + :var0: ethernet + :var1: eth0 VLAN ==== @@ -273,4 +297,3 @@ Operation Date code : 0506xx .. stop_vyoslinter - diff --git a/docs/configuration/interfaces/openvpn.rst b/docs/configuration/interfaces/openvpn.rst index 8cf579de..f51dfa94 100644 --- a/docs/configuration/interfaces/openvpn.rst +++ b/docs/configuration/interfaces/openvpn.rst @@ -652,6 +652,88 @@ Will add ``push "keepalive 1 10"`` to the generated OpenVPN config file. quotes. This is done through a hack on our config generator. You can pass quotes using the ``"`` statement. +*************************** +Multi-factor Authentication +*************************** + +VyOS supports multi-factor authentication (MFA) or two-factor authentication +using Time-based One-Time Password (TOTP). Compatible with Google Authenticator +software token, other software tokens. + +MFA TOTP options +================ + +.. cfgcmd:: set interfaces openvpn <interface> server mfa totp challenge <enable | disable> + + If set to enable, openvpn-otp will expect password as result of challenge/ + response protocol. + +.. cfgcmd:: set interfaces openvpn <interface> server mfa totp digits <1-65535> + + Configure number of digits to use for totp hash (default: 6) + +.. cfgcmd:: set interfaces openvpn <interface> server mfa totp drift <1-65535> + + Configure time drift in seconds (default: 0) + +.. cfgcmd:: set interfaces openvpn <interface> server mfa totp slop <1-65535> + + Configure maximum allowed clock slop in seconds (default: 180) + +.. cfgcmd:: set interfaces openvpn <interface> server mfa totp step <1-65535> + + Configure step value for totp in seconds (default: 30) + +Example +======= + +.. code-block:: none + + set interfaces openvpn vtun20 encryption cipher 'aes256' + set interfaces openvpn vtun20 hash 'sha512' + set interfaces openvpn vtun20 mode 'server' + set interfaces openvpn vtun20 persistent-tunnel + set interfaces openvpn vtun20 server client user1 + set interfaces openvpn vtun20 server mfa totp challenge 'disable' + set interfaces openvpn vtun20 server subnet '10.10.2.0/24' + set interfaces openvpn vtun20 server topology 'subnet' + set interfaces openvpn vtun20 tls ca-certificate 'openvpn_vtun20' + set interfaces openvpn vtun20 tls certificate 'openvpn_vtun20' + set interfaces openvpn vtun20 tls dh-params 'dh-pem' + +For every client in the openvpn server configuration a totp secret is created. +To display the authentication information, use the command: + +.. cfgcmd:: show interfaces openvpn <interface> user <username> mfa <qrcode|secret|uri> + +An example: + +.. code-block:: none + + vyos@vyos:~$ sh interfaces openvpn vtun20 user user1 mfa qrcode + █████████████████████████████████████ + █████████████████████████████████████ + ████ ▄▄▄▄▄ █▀▄▀ ▀▀▄▀ ▀▀▄ █ ▄▄▄▄▄ ████ + ████ █ █ █▀▀▄ █▀▀▀█▀██ █ █ █ ████ + ████ █▄▄▄█ █▀█ ▄ █▀▀ █▄▄▄█ █▄▄▄█ ████ + ████▄▄▄▄▄▄▄█▄█ █ █ ▀ █▄▀▄█▄▄▄▄▄▄▄████ + ████▄▄ ▄ █▄▄ ▄▀▄█▄ ▄▀▄█ ▄▄▀ ▀▄█ ▀████ + ████ ▀██▄▄▄█▄ ██ █▄▄▄▄ █▄▀█ █ █▀█████ + ████ ▄█▀▀▄▄ ▄█▀ ▀▄ ▄▄▀▄█▀▀▀ ▄▄▀████ + ████▄█ ▀▄▄▄▀ ▀ ▄█ ▄ █▄█▀ █▀ █▀█████ + ████▀█▀ ▀ ▄█▀▄▀▀█▄██▄█▀▀ ▀ ▀ ▄█▀████ + ████ ██▄▄▀▄▄█ ██ ▀█ ▄█ ▀▄█ █▀██▀████ + ████▄███▄█▄█ ▀█▄ ██▄▄▄█▀ ▄▄▄ █ ▀ ████ + ████ ▄▄▄▄▄ █▄█▀▄ ▀▄ ▀█▀ █▄█ ██▀█████ + ████ █ █ █ ▄█▀█▀▀▄ ▄▀▀▄▄▄▄▄▄ ████ + ████ █▄▄▄█ █ ▄ ▀ █▄▄▄██▄▀█▄▀▄█▄ █████ + ████▄▄▄▄▄▄▄█▄██▄█▄▄▄▄▄█▄█▄█▄██▄██████ + █████████████████████████████████████ + █████████████████████████████████████ + +Use the QR code to add the user account in Google authenticator application and +on client side, use the OTP number as password. + ********************************** OpenVPN Data Channel Offload (DCO) diff --git a/docs/configuration/loadbalancing/reverse-proxy.rst b/docs/configuration/loadbalancing/reverse-proxy.rst index 3d462821..044d2044 100644 --- a/docs/configuration/loadbalancing/reverse-proxy.rst +++ b/docs/configuration/loadbalancing/reverse-proxy.rst @@ -45,6 +45,11 @@ Service Set SSL certificate <name> for service <name> +.. cfgcmd:: set load-balancing reverse-proxy service <name> + http-response-headers <header-name> value <header-value> + + Set custom HTTP headers to be included in all responses + Rules ^^^^^ @@ -144,7 +149,8 @@ Backend Send a Proxy Protocol version 2 header (binary format) -.. cfgcmd:: set load-balancing reverse-proxy backend <name> ssl ca-certificate <ca-certificate> +.. cfgcmd:: set load-balancing reverse-proxy backend <name> ssl + ca-certificate <ca-certificate> Configure requests to the backend server to use SSL encryption and authenticate backend against <ca-certificate> @@ -154,6 +160,42 @@ Backend Configure requests to the backend server to use SSL encryption without validating server certificate +.. cfgcmd:: set load-balancing reverse-proxy backend <name> + http-response-headers <header-name> value <header-value> + + Set custom HTTP headers to be included in all responses using the backend + + +HTTP health check +^^^^^^^^^^^^^^^^^ +For web application providing information about their state HTTP health +checks can be used to determine their availability. + +.. cfgcmd:: set load-balancing reverse-proxy backend <name> http-check + + Enables HTTP health checks using OPTION HTTP requests against '/' and + expecting a successful response code in the 200-399 range. + +.. cfgcmd:: set load-balancing reverse-proxy backend <name> http-check + method <method> + + Sets the HTTP method to be used, can be either: option, get, post, put + +.. cfgcmd:: set load-balancing reverse-proxy backend <name> http-check + uri <path> + + Sets the endpoint to be used for health checks + +.. cfgcmd:: set load-balancing reverse-proxy backend <name> http-check + expect <condition> + + Sets the expected result condition for considering a server healthy. + Some possible examples are: + * ``status 200`` Expecting a 200 response code + * ``status 200-399`` Expecting a non-failure response code + * ``string success`` Expecting the string `success` in the response body + + Global ------- @@ -215,6 +257,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 @@ -258,6 +301,7 @@ HTTPS. The ``https`` service listens on port 443 with backend ``bk-default`` to handle HTTPS traffic. It uses certificate named ``cert`` for SSL termination. +HSTS header is set with a 1-year expiry, to tell browsers to always use SSL for site. Rule 10 matches requests with the exact URL path ``/.well-known/xxx`` and redirects to location ``/certs/``. @@ -280,6 +324,7 @@ connection limit of 4000 and a minimum TLS version of 1.3. set load-balancing reverse-proxy service https mode 'http' set load-balancing reverse-proxy service https port '443' set load-balancing reverse-proxy service https ssl certificate 'cert' + set load-balancing reverse-proxy service https http-response-headers Strict-Transport-Security value 'max-age=31536000' set load-balancing reverse-proxy service https rule 10 url-path exact '/.well-known/xxx' set load-balancing reverse-proxy service https rule 10 set redirect-location '/certs/' @@ -295,20 +340,22 @@ connection limit of 4000 and a minimum TLS version of 1.3. set load-balancing reverse-proxy global-parameters max-connections '4000' set load-balancing reverse-proxy global-parameters tls-version-min '1.3' + SSL Bridging ------------- -The following configuration terminates incoming HTTPS traffic on the router, then re-encrypts the traffic and sends -to the backend server via HTTPS. This is useful if encryption is required for both legs, but you do not want to +The following configuration terminates incoming HTTPS traffic on the router, +then re-encrypts the traffic and sends to the backend server via HTTPS. +This is useful if encryption is required for both legs, but you do not want to install publicly trusted certificates on each backend server. -Backend service certificates are checked against the certificate authority specified in the configuration, which -could be an internal CA. +Backend service certificates are checked against the certificate authority +specified in the configuration, which could be an internal CA. The ``https`` service listens on port 443 with backend ``bk-bridge-ssl`` to handle HTTPS traffic. It uses certificate named ``cert`` for SSL termination. -The ``bk-bridge-ssl`` backend connects to sr01 server on port 443 via HTTPS and checks backend -server has a valid certificate trusted by CA ``cacert`` +The ``bk-bridge-ssl`` backend connects to sr01 server on port 443 via HTTPS +and checks backend server has a valid certificate trusted by CA ``cacert`` .. code-block:: none @@ -325,3 +372,29 @@ server has a valid certificate trusted by CA ``cacert`` set load-balancing reverse-proxy backend bk-bridge-ssl server sr01 address '192.0.2.23' set load-balancing reverse-proxy backend bk-bridge-ssl server sr01 port '443' + +Balancing with HTTP health checks +--------------------------------- + +This configuration enables HTTP health checks on backend servers. + +.. code-block:: none + + set load-balancing reverse-proxy service my-tcp-api backend 'bk-01' + set load-balancing reverse-proxy service my-tcp-api mode 'tcp' + set load-balancing reverse-proxy service my-tcp-api port '8888' + + set load-balancing reverse-proxy backend bk-01 balance 'round-robin' + set load-balancing reverse-proxy backend bk-01 mode 'tcp' + + set load-balancing reverse-proxy backend bk-01 http-check method 'get' + set load-balancing reverse-proxy backend bk-01 http-check uri '/health' + set load-balancing reverse-proxy backend bk-01 http-check expect 'status 200' + + set load-balancing reverse-proxy backend bk-01 server srv01 address '192.0.2.11' + set load-balancing reverse-proxy backend bk-01 server srv01 port '8881' + set load-balancing reverse-proxy backend bk-01 server srv01 check + set load-balancing reverse-proxy backend bk-01 server srv02 address '192.0.2.12' + set load-balancing reverse-proxy backend bk-01 server srv02 port '8882' + set load-balancing reverse-proxy backend bk-01 server srv02 check + diff --git a/docs/configuration/nat/cgnat.rst b/docs/configuration/nat/cgnat.rst new file mode 100644 index 00000000..70916318 --- /dev/null +++ b/docs/configuration/nat/cgnat.rst @@ -0,0 +1,143 @@ +.. _cgnat: + +##### +CGNAT +##### + +:abbr:`CGNAT (Carrier-Grade Network Address Translation)` , also known as +Large-Scale NAT (LSN), is a type of network address translation used by +Internet Service Providers (ISPs) to enable multiple private IP addresses to +share a single public IP address. This technique helps to conserve the limited +IPv4 address space. +The 100.64.0.0/10 address block is reserved for use in carrier-grade NAT + +Overview +======== + +CGNAT works by placing a NAT device within the ISP's network. This device +translates private IP addresses from customer networks to a limited pool of +public IP addresses assigned to the ISP. This allows many customers to share a +smaller number of public IP addresses. + +Not all :rfc:`6888` requirements are implemented in CGNAT. + +Implemented the following :rfc:`6888` requirements: + +- REQ 2: A CGN must have a default "IP address pooling" behavior of "Paired". + CGN must use the same external IP address mapping for all sessions associated + with the same internal IP address, be they TCP, UDP, ICMP, something else, + or a mix of different protocols. +- REQ 3: The CGN function should not have any limitations on the size or the + contiguity of the external address pool. +- REQ 4: A CGN must support limiting the number of external ports (or, + equivalently, "identifiers" for ICMP) that are assigned per subscriber + +Advantages of CGNAT +------------------- + +- **IPv4 Address Conservation**: CGNAT helps mitigate the exhaustion of IPv4 addresses by allowing multiple customers to share a single public IP address. +- **Scalability**: ISPs can support more customers without needing a proportional increase in public IP addresses. +- **Cost-Effective**: Reduces the cost associated with acquiring additional public IPv4 addresses. + +Considerations +-------------- + +- **Traceability Issues**: Since multiple users share the same public IP address, tracking individual users for security and legal purposes can be challenging. +- **Performance Overheads**: The translation process can introduce latency and potential performance bottlenecks, especially under high load. +- **Application Compatibility**: Some applications and protocols may not work well with CGNAT due to their reliance on unique public IP addresses. +- **Port Allocation Limits**: Each public IP address has a limited number of ports, which can be exhausted, affecting the ability to establish new connections. +- **Port Control Protocol**: PCP is not implemented. + +Port calculation +================ + +When implementing CGNAT, ensuring that there are enough ports allocated per subscriber is critical. Below is a summary based on RFC 6888. + +1. **Total Ports Available**: + + - Total Ports: 65536 (0 to 65535) + - Reserved Ports: Assume 1024 ports are reserved for well-known services and administrative purposes. + - Usable Ports: 65536 - 1024 = 64512 + +2. **Estimate Ports Needed per Subscriber**: + + - Example: A household might need 1000 ports to ensure smooth operation for multiple devices and applications. + +3. **Calculate the Number of Subscribers per Public IP**: + + - Usable Ports / Ports per Subscriber + - 64512 / 1000 ≈ 64 subscribers per public IP + + +Configuration +============= + +.. cfgcmd:: set nat cgnat pool external <pool-name> external-port-range <port-range> + + Set an external port-range for the external pool, the default range is + 1024-65535. Multiple entries can be added to the same pool. + +.. cfgcmd:: set nat cgnat pool external <pool-name> external-port-range per-user-limit port <num> + + Set external source port limits that will be allocated to each subscriber + individually. The default value is 2000. + +.. cfgcmd:: set nat cgnat pool external <pool-name> range [address | address range | network] + + Set the range of external IP addresses for the CGNAT pool. + +.. cfgcmd:: set nat cgnat pool internal <pool-name> range [address range | network] + + Set the range of internal IP addresses for the CGNAT pool. + +.. cfgcmd:: set nat cgnat pool rule <num> source pool <internal-pool-name> + + Set the rule for the source pool. + +.. cfgcmd:: set nat cgnat pool rule <num> translation pool <external-pool-name> + + Set the rule for the translation pool. + + + +Configuration Examples +====================== + +Single external address +----------------------- + +Example of setting up a basic CGNAT configuration: +In the following example, we define an external pool named `ext-1` with one external IP address + + +Each subscriber will be allocated a maximum of 2000 ports from the external pool. + +.. code-block:: none + + set nat cgnat pool external ext1 external-port-range '1024-65535' + set nat cgnat pool external ext1 per-user-limit port '2000' + set nat cgnat pool external ext1 range '192.0.2.222/32' + set nat cgnat pool internal int1 range '100.64.0.0/28' + set nat cgnat rule 10 source pool 'int1' + set nat cgnat rule 10 translation pool 'ext1' + +Multiple external addresses +--------------------------- + +.. code-block:: none + + set nat cgnat pool external ext1 external-port-range '1024-65535' + set nat cgnat pool external ext1 per-user-limit port '8000' + set nat cgnat pool external ext1 range '192.0.2.1-192.0.2.2' + set nat cgnat pool external ext1 range '203.0.113.253-203.0.113.254' + set nat cgnat pool internal int1 range '100.64.0.1-100.64.0.32' + set nat cgnat rule 10 source pool 'int1' + set nat cgnat rule 10 translation pool 'ext1' + + + +Further Reading +=============== + +- :rfc:`6598` - IANA-Reserved IPv4 Prefix for Shared Address Space +- :rfc:`6888` - Requirements for CGNAT
\ No newline at end of file diff --git a/docs/configuration/nat/index.rst b/docs/configuration/nat/index.rst index 6556b7f9..2ecacc72 100644 --- a/docs/configuration/nat/index.rst +++ b/docs/configuration/nat/index.rst @@ -11,3 +11,4 @@ NAT nat44 nat64 nat66 + cgnat diff --git a/docs/configuration/nat/nat44.rst b/docs/configuration/nat/nat44.rst index 98b230a9..68854c16 100644 --- a/docs/configuration/nat/nat44.rst +++ b/docs/configuration/nat/nat44.rst @@ -668,10 +668,10 @@ We will use source and destination address for hash generation. set nat destination rule 10 destination port 80 set nat destination rule 10 load-balance hash source-address set nat destination rule 10 load-balance hash destination-address - set nat destination rule 10 laod-balance backend 198.51.100.101 weight 30 - set nat destination rule 10 laod-balance backend 198.51.100.102 weight 20 - set nat destination rule 10 laod-balance backend 198.51.100.103 weight 15 - set nat destination rule 10 laod-balance backend 198.51.100.104 weight 35 + set nat destination rule 10 load-balance backend 198.51.100.101 weight 30 + set nat destination rule 10 load-balance backend 198.51.100.102 weight 20 + set nat destination rule 10 load-balance backend 198.51.100.103 weight 15 + set nat destination rule 10 load-balance backend 198.51.100.104 weight 35 Second scenario: apply source NAT for all outgoing connections from LAN 10.0.0.0/8, using 3 public addresses and equal distribution. diff --git a/docs/configuration/pki/index.rst b/docs/configuration/pki/index.rst index 8fd6fbe8..0ead198f 100644 --- a/docs/configuration/pki/index.rst +++ b/docs/configuration/pki/index.rst @@ -8,7 +8,7 @@ PKI ### -VyOS 1.4 changed the way in how encrytion keys or certificates are stored on the +VyOS 1.4 changed the way in how encryption keys or certificates are stored on the system. In the pre VyOS 1.4 era, certificates got stored under /config and every service referenced a file. That made copying a running configuration from system A to system B a bit harder, as you had to copy the files and their permissions @@ -120,12 +120,12 @@ OpenVPN .. opcmd:: generate pki openvpn shared-secret - Genearate a new OpenVPN shared secret. The generated secret is the output to + Generate a new OpenVPN shared secret. The generated secret is the output to the console. .. opcmd:: generate pki openvpn shared-secret install <name> - Genearate a new OpenVPN shared secret. The generated secret is the output to + Generate a new OpenVPN shared secret. The generated secret is the output to the console. .. include:: pki_cli_import_help.txt @@ -163,7 +163,7 @@ WireGuard the output from op-mode into configuration mode. ``peer`` is used for the VyOS CLI command to identify the WireGuard peer where - this secred is to be used. + this secret is to be used. Key usage (CLI) =============== @@ -365,3 +365,124 @@ also to display them. .. opcmd:: renew certbot Manually trigger certificate renewal. This will be done twice a day. + +Examples +======== + +Create a CA chain and leaf certificates +------------------------------------- + +This configuration generates & installs into the VyOS PKI system a root +certificate authority, alongside two intermediary certificate authorities for +client & server certificates. These CAs are then used to generate a server +certificate for the router, and a client certificate for a user. + + +* ``vyos_root_ca`` is the root certificate authority. + +* ``vyos_client_ca`` and ``vyos_server_ca`` are intermediary certificate authorities, + which are signed by the root CA. + +* ``vyos_cert`` is a leaf server certificate used to identify the VyOS router, + signed by the server intermediary CA. + +* ``vyos_example_user`` is a leaf client certificate used to identify a user, + signed by client intermediary CA. + + +First, we create the root certificate authority. + +.. code-block:: none + + [edit] + vyos@vyos# run generate pki ca install vyos_root_ca + Enter private key type: [rsa, dsa, ec] (Default: rsa) rsa + Enter private key bits: (Default: 2048) 2048 + Enter country code: (Default: GB) GB + Enter state: (Default: Some-State) Some-State + Enter locality: (Default: Some-City) Some-City + Enter organization name: (Default: VyOS) VyOS + Enter common name: (Default: vyos.io) VyOS Root CA + Enter how many days certificate will be valid: (Default: 1825) 1825 + Note: If you plan to use the generated key on this router, do not encrypt the private key. + Do you want to encrypt the private key with a passphrase? [y/N] n + 2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. + +Secondly, we create the intermediary certificate authorities, which are used to +sign the leaf certificates. + +.. code-block:: none + + [edit] + vyos@vyos# run generate pki ca sign vyos_root_ca install vyos_server_ca + Do you already have a certificate request? [y/N] n + Enter private key type: [rsa, dsa, ec] (Default: rsa) rsa + Enter private key bits: (Default: 2048) 2048 + Enter country code: (Default: GB) GB + Enter state: (Default: Some-State) Some-State + Enter locality: (Default: Some-City) Some-City + Enter organization name: (Default: VyOS) VyOS + Enter common name: (Default: vyos.io) VyOS Intermediary Server CA + Enter how many days certificate will be valid: (Default: 1825) 1095 + Note: If you plan to use the generated key on this router, do not encrypt the private key. + Do you want to encrypt the private key with a passphrase? [y/N] n + 2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. + + + [edit] + vyos@vyos# run generate pki ca sign vyos_root_ca install vyos_client_ca + Do you already have a certificate request? [y/N] n + Enter private key type: [rsa, dsa, ec] (Default: rsa) rsa + Enter private key bits: (Default: 2048) 2048 + Enter country code: (Default: GB) GB + Enter state: (Default: Some-State) Some-State + Enter locality: (Default: Some-City) Some-City + Enter organization name: (Default: VyOS) VyOS + Enter common name: (Default: vyos.io) VyOS Intermediary Client CA + Enter how many days certificate will be valid: (Default: 1825) 1095 + Note: If you plan to use the generated key on this router, do not encrypt the private key. + Do you want to encrypt the private key with a passphrase? [y/N] n + 2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. + +Lastly, we can create the leaf certificates that devices and users will utilise. + +.. code-block:: none + + [edit] + vyos@vyos# run generate pki certificate sign vyos_server_ca install vyos_cert + Do you already have a certificate request? [y/N] n + Enter private key type: [rsa, dsa, ec] (Default: rsa) rsa + Enter private key bits: (Default: 2048) 2048 + Enter country code: (Default: GB) GB + Enter state: (Default: Some-State) Some-State + Enter locality: (Default: Some-City) Some-City + Enter organization name: (Default: VyOS) VyOS + Enter common name: (Default: vyos.io) vyos.net + Do you want to configure Subject Alternative Names? [y/N] y + Enter alternative names in a comma separate list, example: ipv4:1.1.1.1,ipv6:fe80::1,dns:vyos.net + Enter Subject Alternative Names: dns:vyos.net,dns:www.vyos.net + Enter how many days certificate will be valid: (Default: 365) 365 + Enter certificate type: (client, server) (Default: server) server + Note: If you plan to use the generated key on this router, do not encrypt the private key. + Do you want to encrypt the private key with a passphrase? [y/N] n + 2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. + + + [edit] + vyos@vyos# run generate pki certificate sign vyos_client_ca install vyos_example_user + Do you already have a certificate request? [y/N] n + Enter private key type: [rsa, dsa, ec] (Default: rsa) rsa + Enter private key bits: (Default: 2048) 2048 + Enter country code: (Default: GB) GB + Enter state: (Default: Some-State) Some-State + Enter locality: (Default: Some-City) Some-City + Enter organization name: (Default: VyOS) VyOS + Enter common name: (Default: vyos.io) Example User + Do you want to configure Subject Alternative Names? [y/N] y + Enter alternative names in a comma separate list, example: ipv4:1.1.1.1,ipv6:fe80::1,dns:vyos.net,rfc822:user@vyos.net + Enter Subject Alternative Names: rfc822:example.user@vyos.net + Enter how many days certificate will be valid: (Default: 365) 365 + Enter certificate type: (client, server) (Default: server) client + Note: If you plan to use the generated key on this router, do not encrypt the private key. + Do you want to encrypt the private key with a passphrase? [y/N] n + 2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. diff --git a/docs/configuration/policy/route.rst b/docs/configuration/policy/route.rst index 1a85ffc6..45975774 100644 --- a/docs/configuration/policy/route.rst +++ b/docs/configuration/policy/route.rst @@ -19,8 +19,8 @@ from 1 - 999999, at the first match the action of the rule will be executed. Provide a rule-set description. -.. cfgcmd:: set policy route <name> enable-default-log -.. cfgcmd:: set policy route6 <name> enable-default-log +.. cfgcmd:: set policy route <name> default-log +.. cfgcmd:: set policy route6 <name> default-log Option to log packets hitting default-action. @@ -271,4 +271,4 @@ setting a different routing table. .. cfgcmd:: set policy route <name> rule <n> set tcp-mss <500-1460> .. cfgcmd:: set policy route6 <name> rule <n> set tcp-mss <500-1460> - Set packet modifications: Explicitly set TCP Maximum segment size value.
\ No newline at end of file + Set packet modifications: Explicitly set TCP Maximum segment size value. diff --git a/docs/configuration/protocols/isis.rst b/docs/configuration/protocols/isis.rst index 1f779d0a..9b954965 100644 --- a/docs/configuration/protocols/isis.rst +++ b/docs/configuration/protocols/isis.rst @@ -12,7 +12,7 @@ interior gateway protocol (IGP) which is described in ISO10589, algorithm to create a database of the network’s topology, and from that database to determine the best (that is, lowest cost) path to a destination. The intermediate systems (the name for routers) exchange topology -information with their directly conencted neighbors. IS-IS runs directly on +information with their directly connected neighbors. IS-IS runs directly on the data link layer (Layer 2). IS-IS addresses are called :abbr:`NETs (Network Entity Titles)` and can be 8 to 20 bytes long, but are generally 10 bytes long. The tree database that is created with IS-IS is @@ -39,7 +39,7 @@ occur within IS-IS when it comes to said duplication. .. cfgcmd:: set protocols isis net <network-entity-title> - This commad sets network entity title (NET) provided in ISO format. + This command sets network entity title (NET) provided in ISO format. Here is an example :abbr:`NET (Network Entity Title)` value: @@ -52,9 +52,9 @@ occur within IS-IS when it comes to said duplication. * :abbr:`AFI (Address family authority identifier)` - ``49`` The AFI value 49 is what IS-IS uses for private addressing. - * Area identifier: ``0001`` IS-IS area number (numberical area ``1``) + * Area identifier: ``0001`` IS-IS area number (numerical area ``1``) - * System identifier: ``1921.6800.1002`` - for system idetifiers we recommend + * System identifier: ``1921.6800.1002`` - for system identifiers we recommend to use IP address or MAC address of the router itself. The way to construct this is to keep all of the zeroes of the router IP address, and then change the periods from being every three numbers to every four numbers. The diff --git a/docs/configuration/service/broadcast-relay.rst b/docs/configuration/service/broadcast-relay.rst index b6e2bed7..f64bb208 100644 --- a/docs/configuration/service/broadcast-relay.rst +++ b/docs/configuration/service/broadcast-relay.rst @@ -20,7 +20,7 @@ Configuration .. cfgcmd:: set service broadcast-relay id <n> description <description> A description can be added for each and every unique relay ID. This is - useful to distinguish between multiple different ports/appliactions. + useful to distinguish between multiple different ports/applications. .. cfgcmd:: set service broadcast-relay id <n> interface <interface> @@ -35,7 +35,7 @@ Configuration .. cfgcmd:: set service broadcast-relay id <n> port <port> - The UDP port number used by your apllication. It is mandatory for this kind + The UDP port number used by your application. It is mandatory for this kind of operation. .. cfgcmd:: set service broadcast-relay id <n> disable diff --git a/docs/configuration/service/config-sync.rst b/docs/configuration/service/config-sync.rst new file mode 100644 index 00000000..d0449a78 --- /dev/null +++ b/docs/configuration/service/config-sync.rst @@ -0,0 +1,114 @@ +.. _config-sync: + +########### +Config Sync +########### + +Configuration synchronization (config sync) is a feature of VyOS that +permits synchronization of the configuration of one VyOS router to +another in a network. + +The main benefit to configuration synchronization is that it eliminates having +to manually replicate configuration changes made on the primary router to the +secondary (replica) router. + +The writing of the configuration to the secondary router is performed through +the VyOS HTTP API. The user can specify which portion(s) of the configuration will +be synchronized and the mode to use - whether to replace or add. + +To prevent issues with divergent configurations between the pair of routers, +synchronization is strictly unidirectional from primary to replica. Both +routers should be online and run the same version of VyOS. + +Configuration +------------- + +.. cfgcmd:: set service config-sync secondary + <address|key|timeout|port> + + Specify the address, API key, timeout and port of the secondary router. + You need to enable and configure the HTTP API service on the secondary + router for config sync to operate. + +.. cfgcmd:: set service config-sync section <section> + + Specify the section of the configuration to synchronize. If more than one + section is to be synchronized, repeat the command to add additional + sections as required. + +.. cfgcmd:: set service config-sync mode <load|set> + + Two options are available for `mode`: either `load` and replace or `set` + the configuration section. + +.. code-block:: none + + Supported options for <section> include: + firewall + interfaces <interface> + nat + nat66 + pki + policy + protocols <protocol> + qos <interface|policy> + service <service> + system <conntrack| + flow-accounting|option|sflow|static-host-mapping|sysctl|time-zone> + vpn + vrf + +Example +------- +* Synchronize the time-zone and OSPF configuration from Router A to Router B +* The address of Router B is 10.0.20.112 and the port used is 8443 + +Configure the HTTP API service on Router B + +.. code-block:: none + + set service https listen-address '10.0.20.112' + set service https port '8443' + set service https api keys id KID key 'foo' + +Configure the config-sync service on Router A + +.. code-block:: none + + set service config-sync mode 'load' + set service config-sync secondary address '10.0.20.112' + set service config-sync secondary port '8443' + set service config-sync secondary key 'foo' + set service config-sync section protocols 'ospf' + set service config-sync section system 'time-zone' + +Make config-sync relevant changes to Router A's configuration + +.. code-block:: none + + vyos@vyos-A# set system time-zone 'America/Los_Angeles' + vyos@vyos-A# commit + INFO:vyos_config_sync:Config synchronization: Mode=load, + Secondary=10.0.20.112 + vyos@vyos-A# save + + vyos@vyos-A# set protocols ospf area 0 network '10.0.48.0/30' + vyos@vyos-A# commit + INFO:vyos_config_sync:Config synchronization: Mode=load, + Secondary=10.0.20.112 + yos@vyos-A# save + +Verify configuration changes have been replicated to Router B + +.. code-block:: none + + vyos@vyos-B:~$ show configuration commands | match time-zone + set system time-zone 'America/Los_Angeles' + + vyos@vyos-B:~$ show configuration commands | match ospf + set protocols ospf area 0 network '10.0.48.0/30' + +Known issues +------------ +Configuration resynchronization. With the current implementation of `service +config-sync`, the secondary node must be online. diff --git a/docs/configuration/service/conntrack-sync.rst b/docs/configuration/service/conntrack-sync.rst index db23c92f..232db1a8 100644 --- a/docs/configuration/service/conntrack-sync.rst +++ b/docs/configuration/service/conntrack-sync.rst @@ -29,7 +29,7 @@ will be mandatorily defragmented. It is possible to use either Multicast or Unicast to sync conntrack traffic. Most examples below show Multicast, but unicast can be specified by using the -"peer" keywork after the specificed interface, as in the following example: +"peer" keywork after the specified interface, as in the following example: :cfgcmd:`set service conntrack-sync interface eth0 peer 192.168.0.250` @@ -204,7 +204,7 @@ Now configure conntrack-sync service on ``router1`` **and** ``router2`` .. code-block:: none - set high-availablilty vrrp group internal virtual-address ... etc ... + set high-availability vrrp group internal virtual-address ... etc ... set high-availability vrrp sync-group syncgrp member 'internal' set service conntrack-sync accept-protocol 'tcp' set service conntrack-sync accept-protocol 'udp' diff --git a/docs/configuration/service/https.rst b/docs/configuration/service/https.rst index 973c5355..af397456 100644 --- a/docs/configuration/service/https.rst +++ b/docs/configuration/service/https.rst @@ -53,7 +53,11 @@ Configuration .. cfgcmd:: set service https vrf <name> - Start Webserver in given VRF. + Start Webserver in given VRF. + +.. cfgcmd:: set service https request-body-size-limit <size> + + Set the maximum request body size in megabytes. Default is 1MB. API === @@ -70,7 +74,36 @@ API .. cfgcmd:: set service https api strict - Enforce strict path checking + Enforce strict path checking. + +.. cfgcmd:: set service https api cors allow-origin <origin> + + Allow cross-origin requests from `<origin>`. + +GraphQL +======= + +.. cfgcmd:: set service https api graphql introspection + + Enable GraphQL Schema introspection. + +.. note:: Do not leave introspection enabled in production, it is a security risk. + +.. cfgcmd:: set service https api graphql authentication type <key | token> + + Set the authentication type for GraphQL, default option is key. Available options are: + + * ``key`` use API keys configured in ``service https api keys`` + + * ``token`` use JWT tokens. + +.. cfgcmd:: set service https api graphql authentication expiration + + Set the lifetime for JWT tokens in seconds. Default is 3600 seconds. + +.. cfgcmd:: set service https api graphql authentication secret-length + + Set the byte length of the JWT secret. Default is 32. ********************* Example Configuration diff --git a/docs/configuration/service/ids.rst b/docs/configuration/service/ids.rst index 3e508d50..8a64467f 100644 --- a/docs/configuration/service/ids.rst +++ b/docs/configuration/service/ids.rst @@ -33,7 +33,7 @@ Configuration Configure direction for processing traffic. .. cfgcmd:: set service ids ddos-protection exclude-network <x.x.x.x/x> -.. cfgcmd:: set service ids ddos-protection exlude-network <h:h:h:h:h:h:h:h/x> +.. cfgcmd:: set service ids ddos-protection exclude-network <h:h:h:h:h:h:h:h/x> Specify IPv4 and/or IPv6 networks which are going to be excluded. @@ -56,7 +56,7 @@ Configuration .. cfgcmd:: set service ids ddos-protection sflow port <1-65535> - Configure port number to be used for sflow conection. Default port is 6343. + Configure port number to be used for sflow connection. Default port is 6343. .. cfgcmd:: set service ids ddos-protection threshold general [fps | mbps | pps] <0-4294967294> @@ -96,7 +96,7 @@ In this simplified scenario, main things to be considered are: * Interface **eth0** used to connect to upstream. Since we are analyzing attacks to and from our internal network, two types -of attacks can be identified, and differents actions are needed: +of attacks can be identified, and different actions are needed: * External attack: an attack from the internet towards an internal IP is identify. In this case, all connections towards such IP will be diff --git a/docs/configuration/service/index.rst b/docs/configuration/service/index.rst index 56ce55eb..abb77ef4 100644 --- a/docs/configuration/service/index.rst +++ b/docs/configuration/service/index.rst @@ -8,6 +8,7 @@ Service :includehidden: broadcast-relay + config-sync conntrack-sync console-server dhcp-relay diff --git a/docs/configuration/service/ipoe-server.rst b/docs/configuration/service/ipoe-server.rst index 64048552..ef06bcd5 100644 --- a/docs/configuration/service/ipoe-server.rst +++ b/docs/configuration/service/ipoe-server.rst @@ -26,13 +26,13 @@ functionality as PPPoE, but in a less robust manner. Configuring IPoE Server *********************** -IPoE can be configure on different interfaces, it will depend on each specific -situation which interface will provide IPoE to clients. The clients mac address +IPoE can be configured on different interfaces, it will depend on each specific +situation which interface will provide IPoE to clients. The client's mac address and the incoming interface is being used as control parameter, to authenticate a client. The example configuration below will assign an IP to the client on the incoming -interface eth2 with the client mac address 08:00:27:2f:d8:06. Other DHCP +interface eth1 with the client mac address 00:50:79:66:68:00. Other DHCP discovery requests will be ignored, unless the client mac has been enabled in the configuration. @@ -85,12 +85,11 @@ the configuration. .. cfgcmd:: set service ipoe-server interface <interface> mode <l2 | l3> - Set authentication backend. The configured authentication backend is used - for all queries. + Specifies the client connectivity mode. * **l2**: It means that clients are on same network where interface is.**(default)** - * **local**: It means that client are behind some router. + * **l3**: It means that client are behind some router. .. cfgcmd:: set service ipoe-server interface <interface> network <shared | vlan> @@ -279,7 +278,7 @@ IPv6 .. code-block:: none set service ipoe-server client-ipv6-pool IPv6-POOL delegate '2001:db8:8003::/48' delegation-prefix '56' - set service ipoe-server client-ipv6-pool IPV6-POOL prefix '2001:db8:8002::/48' mask '64' + set service ipoe-server client-ipv6-pool IPv6-POOL prefix '2001:db8:8002::/48' mask '64' set service ipoe-server default-ipv6-pool IPv6-POOL ********* @@ -434,7 +433,7 @@ Toubleshooting .. code-block:: none - vyos@vyos:~$sudo journalctl -u accel-ppp@ipoe -b 0 + vyos@vyos:~$ show log ipoe-server Feb 27 14:29:27 vyos accel-ipoe[2262]: eth1.100:: recv [DHCPv4 Discover xid=55df9228 chaddr=0c:98:bd:b8:00:01 <Message-Type Discover> <Request-IP 192.168.0.3> <Host-Name vyos> <Request-List Subnet,Broadcast,Router,DNS,Classless-Route,Domain-Name,MTU>] Feb 27 14:29:27 vyos accel-ipoe[2262]: eth1.100:eth1.100: eth1.100: authentication succeeded @@ -447,4 +446,4 @@ Toubleshooting .. include:: /_include/common-references.txt .. _dictionary: https://github.com/accel-ppp/accel-ppp/blob/master/accel-pppd/radius/dict/dictionary.rfc6911 -.. _`ACCEL-PPP attribute`: https://github.com/accel-ppp/accel-ppp/blob/master/accel-pppd/radius/dict/dictionary.accel
\ No newline at end of file +.. _`ACCEL-PPP attribute`: https://github.com/accel-ppp/accel-ppp/blob/master/accel-pppd/radius/dict/dictionary.accel diff --git a/docs/configuration/service/ntp.rst b/docs/configuration/service/ntp.rst index e7ee392b..266376cf 100644 --- a/docs/configuration/service/ntp.rst +++ b/docs/configuration/service/ntp.rst @@ -46,9 +46,9 @@ Configuration There are 3 default NTP server set. You are able to change them. - * ``0.pool.ntp.org`` - * ``1.pool.ntp.org`` - * ``2.pool.ntp.org`` + * ``time1.vyos.net`` + * ``time2.vyos.net`` + * ``time3.vyos.net`` .. cfgcmd:: set service ntp server <address> <noselect | nts | pool | prefer> @@ -85,7 +85,7 @@ Configuration .. cfgcmd:: set service ntp leap-second [ignore|smear|system|timezone] - Define how to handle leaf-seonds. + Define how to handle leap-seconds. * `ignore`: No correction is applied to the clock for the leap second. The clock will be corrected later in normal operation when new measurements are diff --git a/docs/configuration/service/pppoe-server.rst b/docs/configuration/service/pppoe-server.rst index 99b3fbb5..6d818c70 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 @@ -49,7 +48,8 @@ Configuring PPPoE Server Create `<user>` for local authentication on this system. The users password will be set to `<pass>`. -.. cfgcmd:: set service pppoe-server client-ip-pool <POOL-NAME> range <x.x.x.x-x.x.x.x | x.x.x.x/x> +.. cfgcmd:: set service pppoe-server client-ip-pool <POOL-NAME> + range <x.x.x.x-x.x.x.x | x.x.x.x/x> Use this command to define the first IP address of a pool of addresses to be given to pppoe clients. If notation ``x.x.x.x-x.x.x.x``, @@ -85,7 +85,8 @@ accounts again. set service pppoe-server authentication mode radius -.. cfgcmd:: set service pppoe-server authentication radius server <server> key <secret> +.. cfgcmd:: set service pppoe-server authentication radius + server <server> key <secret> Configure RADIUS `<server>` and its required shared `<secret>` for communicating with the RADIUS server. @@ -109,7 +110,8 @@ If you are using OSPF as IGP, always the closest interface connected to the RADIUS server is used. With VyOS 1.2 you can bind all outgoing RADIUS requests to a single source IP e.g. the loopback interface. -.. cfgcmd:: set service pppoe-server authentication radius source-address <address> +.. cfgcmd:: set service pppoe-server authentication radius + source-address <address> Source IPv4 address used in all RADIUS server queires. @@ -119,57 +121,70 @@ to a single source IP e.g. the loopback interface. RADIUS advanced options ======================= -.. cfgcmd:: set service pppoe-server authentication radius server <server> port <port> +.. cfgcmd:: set service pppoe-server authentication radius + server <server> port <port> Configure RADIUS `<server>` and its required port for authentication requests. -.. cfgcmd:: set service pppoe-server authentication radius server <server> fail-time <time> +.. cfgcmd:: set service pppoe-server authentication radius + server <server> fail-time <time> Mark RADIUS server as offline for this given `<time>` in seconds. -.. cfgcmd:: set service pppoe-server authentication radius server <server> disable +.. cfgcmd:: set service pppoe-server authentication radius + server <server> disable Temporary disable this RADIUS server. -.. cfgcmd:: set service pppoe-server authentication radius acct-timeout <timeout> +.. cfgcmd:: set service pppoe-server authentication radius + acct-timeout <timeout> Timeout to wait reply for Interim-Update packets. (default 3 seconds) -.. cfgcmd:: set service pppoe-server authentication radius dynamic-author server <address> +.. cfgcmd:: set service pppoe-server authentication radius + dynamic-author server <address> Specifies IP address for Dynamic Authorization Extension server (DM/CoA) -.. cfgcmd:: set service pppoe-server authentication radius dynamic-author port <port> +.. cfgcmd:: set service pppoe-server authentication radius + dynamic-author port <port> Port for Dynamic Authorization Extension server (DM/CoA) -.. cfgcmd:: set service pppoe-server authentication radius dynamic-author key <secret> +.. cfgcmd:: set service pppoe-server authentication radius dynamic-author + key <secret> Secret for Dynamic Authorization Extension server (DM/CoA) -.. cfgcmd:: set service pppoe-server authentication radius max-try <number> +.. cfgcmd:: set service pppoe-server authentication radius + max-try <number> Maximum number of tries to send Access-Request/Accounting-Request queries -.. cfgcmd:: set service pppoe-server authentication radius timeout <timeout> +.. cfgcmd:: set service pppoe-server authentication radius + timeout <timeout> Timeout to wait response from server (seconds) -.. cfgcmd:: set service pppoe-server authentication radius nas-identifier <identifier> +.. cfgcmd:: set service pppoe-server authentication radius + nas-identifier <identifier> Value to send to RADIUS server in NAS-Identifier attribute and to be matched in DM/CoA requests. -.. cfgcmd:: set service pppoe-server authentication radius nas-ip-address <address> +.. cfgcmd:: set service pppoe-server authentication radius + nas-ip-address <address> Value to send to RADIUS server in NAS-IP-Address attribute and to be matched in DM/CoA requests. Also DM/CoA server will bind to that address. -.. cfgcmd:: set service pppoe-server authentication radius source-address <address> +.. cfgcmd:: set service pppoe-server authentication radius + source-address <address> Source IPv4 address used in all RADIUS server queires. -.. cfgcmd:: set service pppoe-server authentication radius rate-limit attribute <attribute> +.. cfgcmd:: set service pppoe-server authentication radius + rate-limit attribute <attribute> Specifies which RADIUS server attribute contains the rate limit information. The default attribute is ``Filter-Id``. @@ -177,11 +192,13 @@ RADIUS advanced options .. note:: If you set a custom RADIUS attribute you must define it on both dictionaries at RADIUS server and client. -.. cfgcmd:: set service pppoe-server authentication radius rate-limit enable +.. cfgcmd:: set service pppoe-server authentication radius + rate-limit enable Enables bandwidth shaping via RADIUS. -.. cfgcmd:: set service pppoe-server authentication radius rate-limit vendor +.. cfgcmd:: set service pppoe-server authentication radius + rate-limit vendor Specifies the vendor dictionary, dictionary needs to be in /usr/share/accel-ppp/radius. @@ -193,25 +210,27 @@ Allocation clients ip addresses by RADIUS ========================================= If the RADIUS server sends the attribute ``Framed-IP-Address`` then this IP -address will be allocated to the client and the option ``default-pool`` within the CLI -config is being ignored. +address will be allocated to the client and the option ``default-pool`` +within the CLI config is being ignored. -If the RADIUS server sends the attribute ``Framed-Pool``, IP address will be allocated -from a predefined IP pool whose name equals the attribute value. +If the RADIUS server sends the attribute ``Framed-Pool``, IP address will +be allocated from a predefined IP pool whose name equals the attribute value. -If the RADIUS server sends the attribute ``Stateful-IPv6-Address-Pool``, IPv6 address -will be allocated from a predefined IPv6 pool ``prefix`` whose name equals the attribute value. +If the RADIUS server sends the attribute ``Stateful-IPv6-Address-Pool``, +IPv6 address will be allocated from a predefined IPv6 pool ``prefix`` +whose name equals the attribute value. -If the RADIUS server sends the attribute ``Delegated-IPv6-Prefix-Pool``, IPv6 -delegation pefix will be allocated from a predefined IPv6 pool ``delegate`` +If the RADIUS server sends the attribute ``Delegated-IPv6-Prefix-Pool``, +IPv6 delegation pefix will be allocated from a predefined IPv6 pool ``delegate`` whose name equals the attribute value. -.. note:: ``Stateful-IPv6-Address-Pool`` and ``Delegated-IPv6-Prefix-Pool`` are defined in - RFC6911. If they are not defined in your RADIUS server, add new dictionary_. +.. note:: ``Stateful-IPv6-Address-Pool`` and ``Delegated-IPv6-Prefix-Pool`` + are defined in RFC6911. If they are not defined in your RADIUS server, + add new dictionary_. -User interface can be put to VRF context via RADIUS Access-Accept packet, or change -it via RADIUS CoA. ``Accel-VRF-Name`` is used from these purposes. It is custom `ACCEL-PPP attribute`_. -Define it in your RADIUS server. +User interface can be put to VRF context via RADIUS Access-Accept packet, +or change it via RADIUS CoA. ``Accel-VRF-Name`` is used from these purposes. +It is custom `ACCEL-PPP attribute`_. Define it in your RADIUS server. Renaming clients interfaces by RADIUS ===================================== @@ -256,13 +275,13 @@ attributes. For Local Users =============== -.. cfgcmd:: set service pppoe-server authentication local-users username <user> rate-limit - download <bandwidth> +.. cfgcmd:: set service pppoe-server authentication local-users username + <user> rate-limit download <bandwidth> Download bandwidth limit in kbit/s for `<user>`. -.. cfgcmd:: set service pppoe-server authentication local-users username <user> rate-limit - upload <bandwidth> +.. cfgcmd:: set service pppoe-server authentication local-users username + <user> rate-limit upload <bandwidth> Upload bandwidth limit in kbit/s for `<user>`. @@ -340,7 +359,8 @@ other servers. Last command says that this PPPoE server can serve only IPv6 **** -.. cfgcmd:: set service pppoe-server ppp-options ipv6 <require | prefer | allow | deny> +.. cfgcmd:: set service pppoe-server ppp-options + ipv6 <require | prefer | allow | deny> Specifies IPv6 negotiation preference. @@ -349,16 +369,16 @@ IPv6 * **allow** - Negotiate IPv6 only if client requests * **deny** - Do not negotiate IPv6 (default value) -.. cfgcmd:: set service pppoe-server client-ipv6-pool <IPv6-POOL-NAME> prefix <address> - mask <number-of-bits> +.. cfgcmd:: set service pppoe-server client-ipv6-pool <IPv6-POOL-NAME> + prefix <address> mask <number-of-bits> Use this comand to set the IPv6 address pool from which an PPPoE client will get an IPv6 prefix of your defined length (mask) to terminate the PPPoE endpoint at their side. The mask length can be set from 48 to 128 bit long, the default value is 64. -.. cfgcmd:: set service pppoe-server client-ipv6-pool <IPv6-POOL-NAME> delegate <address> - delegation-prefix <number-of-bits> +.. cfgcmd:: set service pppoe-server client-ipv6-pool <IPv6-POOL-NAME> + delegate <address> delegation-prefix <number-of-bits> Use this command to configure DHCPv6 Prefix Delegation (RFC3633) on PPPoE. You will have to set your IPv6 pool and the length of the @@ -374,7 +394,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 @@ -383,7 +403,8 @@ IPv6 Advanced Options Accept peer interface identifier. By default is not defined. -.. cfgcmd:: set service pppoe-server ppp-options ipv6-interface-id <random | x:x:x:x> +.. cfgcmd:: set service pppoe-server ppp-options ipv6-interface-id + <random | x:x:x:x> Specifies fixed or random interface identifier for IPv6. By default is fixed. @@ -391,7 +412,8 @@ IPv6 Advanced Options * **random** - Random interface identifier for IPv6 * **x:x:x:x** - Specify interface identifier for IPv6 -.. cfgcmd:: set service pppoe-server ppp-options ipv6-interface-id <random | x:x:x:x> +.. cfgcmd:: set service pppoe-server ppp-options ipv6-interface-id + <random | x:x:x:x> Specifies peer interface identifier for IPv6. By default is fixed. @@ -427,12 +449,13 @@ Advanced Options Authentication Advanced Options =============================== -.. cfgcmd:: set service pppoe-server authentication local-users username <user> disable +.. cfgcmd:: set service pppoe-server authentication local-users + username <user> disable Disable `<user>` account. -.. cfgcmd:: set service pppoe-server authentication local-users username <user> static-ip - <address> +.. cfgcmd:: set service pppoe-server authentication local-users + username <user> static-ip <address> Assign static IP address to `<user>` account. @@ -445,7 +468,8 @@ Authentication Advanced Options Client IP Pool Advanced Options =============================== -.. cfgcmd:: set service pppoe-server client-ip-pool <POOL-NAME> next-pool <NEXT-POOL-NAME> +.. cfgcmd:: set service pppoe-server client-ip-pool <POOL-NAME> + next-pool <NEXT-POOL-NAME> Use this command to define the next address pool name. @@ -465,7 +489,8 @@ PPP Advanced Options This should reduce kernel-level interface creation/deletion rate lack. Default value is **0**. -.. cfgcmd:: set service pppoe-server ppp-options ipv4 <require | prefer | allow | deny> +.. cfgcmd:: set service pppoe-server ppp-options ipv4 + <require | prefer | allow | deny> Specifies IPv4 negotiation preference. @@ -653,5 +678,7 @@ a /56 subnet for the clients internal use. ppp0 | test | 192.168.0.1 | 2001:db8:8002:0:200::/64 | 2001:db8:8003::1/56 | 00:53:00:12:42:eb | | active | 00:00:49 | 875 B | 2.1 KiB .. 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 +.. _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 diff --git a/docs/configuration/service/router-advert.rst b/docs/configuration/service/router-advert.rst index ca558b6a..8f984b10 100644 --- a/docs/configuration/service/router-advert.rst +++ b/docs/configuration/service/router-advert.rst @@ -38,7 +38,7 @@ Configuration "Cur Hop Limit", "hop-limit", "Hop count field of the outgoing RA packets" """Managed address configuration"" flag", "managed-flag", "Tell hosts to use the administered stateful protocol (i.e. DHCP) for autoconfiguration" """Other configuration"" flag", "other-config-flag", "Tell hosts to use the administered (stateful) protocol (i.e. DHCP) for autoconfiguration of other (non-address) information" - "MTU","link-mtu","Link MTU value placed in RAs, exluded in RAs if unset" + "MTU","link-mtu","Link MTU value placed in RAs, excluded in RAs if unset" "Router Lifetime","default-lifetime","Lifetime associated with the default router in units of seconds" "Reachable Time","reachable-time","Time, in milliseconds, that a node assumes a neighbor is reachable after having received a reachability confirmation" "Retransmit Timer","retrans-timer","Time in milliseconds between retransmitted Neighbor Solicitation messages" diff --git a/docs/configuration/service/salt-minion.rst b/docs/configuration/service/salt-minion.rst index aa747c36..8638246b 100644 --- a/docs/configuration/service/salt-minion.rst +++ b/docs/configuration/service/salt-minion.rst @@ -17,7 +17,7 @@ Requirements ************ To use the Salt-Minion, a running Salt-Master is required. You can find more -in the `Salt Poject Documentaion +in the `Salt Project Documentation <https://docs.saltproject.io/en/latest/contents.html>`_ ************* diff --git a/docs/configuration/system/conntrack.rst b/docs/configuration/system/conntrack.rst index 6ed5fef7..1401e02e 100644 --- a/docs/configuration/system/conntrack.rst +++ b/docs/configuration/system/conntrack.rst @@ -94,7 +94,7 @@ states. .. cfgcmd:: set system conntrack timeout udp stream <1-21474836> :defaultvalue: - Set the timeout in secounds for a protocol or state. + Set the timeout in seconds for a protocol or state. You can also define custom timeout values to apply to a specific subset of connections, based on a packet and flow selector. To do this, you need to @@ -172,7 +172,7 @@ create a rule defining the packet and flow selector. .. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999> protocol udp unreplied <1-21474836> - Set the timeout in secounds for a protocol or state in a custom rule. + Set the timeout in seconds for a protocol or state in a custom rule. Conntrack ignore rules ====================== diff --git a/docs/configuration/system/flow-accounting.rst b/docs/configuration/system/flow-accounting.rst index 8d46b178..30d6fc4d 100644 --- a/docs/configuration/system/flow-accounting.rst +++ b/docs/configuration/system/flow-accounting.rst @@ -50,7 +50,7 @@ interface, the interface must be configured for flow accounting. Configure and enable collection of flow information for the interface identified by `<interface>`. - You can configure multiple interfaces which whould participate in flow + You can configure multiple interfaces which would participate in flow accounting. .. note:: Will be recorded only packets/flows on **incoming** direction in diff --git a/docs/configuration/system/host-name.rst b/docs/configuration/system/host-name.rst index d062fc62..4d1567bf 100644 --- a/docs/configuration/system/host-name.rst +++ b/docs/configuration/system/host-name.rst @@ -65,4 +65,4 @@ This section shows how to statically map an IP address to a hostname for local Thus the address configured as :cfgcmd:`set system static-host-mapping host-name <hostname> inet <address>` can be reached via multiple names. - Multiple aliases can pe specified per host-name. + Multiple aliases can be specified per host-name. diff --git a/docs/configuration/system/ip.rst b/docs/configuration/system/ip.rst index 279630e2..a422388f 100644 --- a/docs/configuration/system/ip.rst +++ b/docs/configuration/system/ip.rst @@ -30,7 +30,7 @@ System configuration commands Zebra/Kernel route filtering ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Zebra supports prefix-lists and Route Mapss to match routes received from +Zebra supports prefix-lists and Route Maps to match routes received from other FRR components. The permit/deny facilities provided by these commands can be used to filter which routes zebra will install in the kernel. @@ -48,7 +48,7 @@ Nexthop Tracking Nexthop tracking resolve nexthops via the default route by default. This is enabled by default for a traditional profile of FRR which we use. It and can be disabled if -you do not wan't to e.g. allow BGP to peer across the default route. +you do not want to e.g. allow BGP to peer across the default route. .. cfgcmd:: set system ip nht no-resolve-via-default diff --git a/docs/configuration/system/ipv6.rst b/docs/configuration/system/ipv6.rst index d8d3c4c9..cde7a2aa 100644 --- a/docs/configuration/system/ipv6.rst +++ b/docs/configuration/system/ipv6.rst @@ -26,7 +26,7 @@ System configuration commands Zebra/Kernel route filtering ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Zebra supports prefix-lists and Route Mapss to match routes received from +Zebra supports prefix-lists and Route Maps to match routes received from other FRR components. The permit/deny facilities provided by these commands can be used to filter which routes zebra will install in the kernel. @@ -44,7 +44,7 @@ Nexthop Tracking Nexthop tracking resolve nexthops via the default route by default. This is enabled by default for a traditional profile of FRR which we use. It and can be disabled if -you do not wan't to e.g. allow BGP to peer across the default route. +you do not want to e.g. allow BGP to peer across the default route. .. cfgcmd:: set system ipv6 nht no-resolve-via-default diff --git a/docs/configuration/system/option.rst b/docs/configuration/system/option.rst index 02c889dd..44c66186 100644 --- a/docs/configuration/system/option.rst +++ b/docs/configuration/system/option.rst @@ -88,7 +88,7 @@ Keyboard Layout *************** When starting a VyOS live system (the installation CD) the configured keyboard -layout defaults to US. As this might not suite everyones use case you can adjust +layout defaults to US. As this might not suite everyone's use case you can adjust the used keyboard layout on the system console. .. cfgcmd:: set system option keyboard-layout <us | fr | de | fi | no | dk> diff --git a/docs/configuration/system/sflow.rst b/docs/configuration/system/sflow.rst index c2cf5a80..0c8bf03b 100644 --- a/docs/configuration/system/sflow.rst +++ b/docs/configuration/system/sflow.rst @@ -29,7 +29,7 @@ Configuration Configure and enable collection of flow information for the interface identified by <interface>. - You can configure multiple interfaces which whould participate in sflow accounting. + You can configure multiple interfaces which would participate in sflow accounting. .. cfgcmd:: set system sflow polling <sec> diff --git a/docs/configuration/system/syslog.rst b/docs/configuration/system/syslog.rst index 8755d905..cc7ac676 100644 --- a/docs/configuration/system/syslog.rst +++ b/docs/configuration/system/syslog.rst @@ -45,7 +45,7 @@ Custom File .. cfgcmd:: set system syslog file <filename> archive file <number> - Syslog uses logrotate to rotate logiles after a number of gives bytes. + Syslog uses logrotate to rotate logfiles after a number of gives bytes. We keep as many as `<number>` rotated file before they are deleted on the system. @@ -200,7 +200,7 @@ Display Logs .. opcmd:: show log [all | authorization | cluster | conntrack-sync | ...] Display log files of given category on the console. Use tab completion to get - a list of available categories. Thos categories could be: all, authorization, + a list of available categories. Those categories could be: all, authorization, cluster, conntrack-sync, dhcp, directory, dns, file, firewall, https, image lldp, nat, openvpn, snmp, tail, vpn, vrrp diff --git a/docs/configuration/system/task-scheduler.rst b/docs/configuration/system/task-scheduler.rst index 382da39f..4a754ba3 100644 --- a/docs/configuration/system/task-scheduler.rst +++ b/docs/configuration/system/task-scheduler.rst @@ -7,7 +7,7 @@ Task Scheduler The task scheduler allows you to execute tasks on a given schedule. It makes use of UNIX cron_. -.. note:: All scripts excecuted this way are executed as root user - this may +.. note:: All scripts executed this way are executed as root user - this may be dangerous. Together with :ref:`command-scripting` this can be used for automating (re-)configuration. diff --git a/docs/configuration/trafficpolicy/index.rst b/docs/configuration/trafficpolicy/index.rst index 3463592f..f99c2a66 100644 --- a/docs/configuration/trafficpolicy/index.rst +++ b/docs/configuration/trafficpolicy/index.rst @@ -368,7 +368,7 @@ are to be sent, they could get dropped when trying to get enqueued at the tail. This can happen if the queue has still not been able to release enough packets from its head. -This is the policy that requieres the lowest resources for the same +This is the policy that requires the lowest resources for the same amount of traffic. But **very likely you do not need it as you cannot get much from it. Sometimes it is used just to enable logging.** @@ -504,7 +504,7 @@ and increase `interval` to something around 150 ms. the number of sub-queues (default: 1024) into which packets are classified. -.. cfgcmd:: set qos policy fq-codel <policy name> interval <miliseconds> +.. cfgcmd:: set qos policy fq-codel <policy name> interval <milliseconds> Use this command to configure an fq-codel policy, set its name and the time period used by the control loop of CoDel to detect when a @@ -518,7 +518,7 @@ and increase `interval` to something around 150 ms. define a hard limit on the real queue size. When this limit is reached, new packets are dropped (default: 10240 packets). -.. cfgcmd:: set qos policy fq-codel <policy-name> target <miliseconds> +.. cfgcmd:: set qos policy fq-codel <policy-name> target <milliseconds> Use this command to configure an fq-codel policy, set its name, and define the acceptable minimum standing/persistent queue delay. This @@ -710,7 +710,7 @@ continuously, packets from lower priority classes will only be transmitted after traffic volume from higher priority classes decreases. -.. note:: In Priority Queue we do not define clases with a meaningless +.. note:: In Priority Queue we do not define classes with a meaningless class ID number but with a class priority number (1-7). The lower the number, the higher the priority. @@ -912,7 +912,7 @@ In principle, values must be Rate Control ------------ -| **Queueing discipline:** Tocken Bucket Filter. +| **Queueing discipline:** Token Bucket Filter. | **Applies to:** Outbound traffic. Rate-Control is a classless policy that limits the packet flow to a set @@ -1145,6 +1145,74 @@ A simple example of Shaper using priorities. set qos policy shaper MY-HTB default priority '7' set qos policy shaper MY-HTB default queue-type 'fair-queue' +.. _CAKE: + +CAKE +------ + +| **Queueing discipline:** Deficit mode. +| **Applies to:** Outbound traffic. + +`Common Applications Kept Enhanced`_ (CAKE) is a comprehensive queue management +system, implemented as a queue discipline (qdisc) for the Linux kernel. It is +designed to replace and improve upon the complex hierarchy of simple qdiscs +presently required to effectively tackle the bufferbloat problem at the network +edge. + +.. cfgcmd:: set qos policy cake <text> bandwidth <value> + + Set the shaper bandwidth, either as an explicit bitrate or a percentage + of the interface bandwidth. + +.. cfgcmd:: set qos policy cake <text> description + + Set a description for the shaper. + +.. cfgcmd:: set qos policy cake <text> flow-isolation blind + + Disables flow isolation, all traffic passes through a single queue. + +.. cfgcmd:: set qos policy cake <text> flow-isolation dst-host + + Flows are defined only by destination address. + +.. cfgcmd:: set qos policy cake <text> flow-isolation dual-dst-host + + Flows are defined by the 5-tuple. Fairness is applied first over destination + addresses, then over individual flows. + +.. cfgcmd:: set qos policy cake <text> flow-isolation dual-src-host + + Flows are defined by the 5-tuple. Fairness is applied first over source + addresses, then over individual flows. + +.. cfgcmd:: set qos policy cake <text> flow-isolation flow + + Flows are defined by the entire 5-tuple (source IP address, source port, + destination IP address, destination port, transport protocol). + +.. cfgcmd:: set qos policy cake <text> flow-isolation host + + Flows are defined by source-destination host pairs. + +.. cfgcmd:: set qos policy cake <text> flow-isolation nat + + Perform NAT lookup before applying flow-isolation rules. + +.. cfgcmd:: set qos policy cake <text> flow-isolation src-host + + Flows are defined only by source address. + +.. cfgcmd:: set qos policy cake <text> flow-isolation triple-isolate + + **(Default)** Flows are defined by the 5-tuple, fairness is applied over source and + destination addresses and also over individual flows. + +.. cfgcmd:: set qos policy cake <text> rtt + + Defines the round-trip time used for active queue management (AQM) in + milliseconds. The default value is 100. + Applying a traffic policy ========================= @@ -1220,5 +1288,6 @@ That is how it is possible to do the so-called "ingress shaping". .. _tocken bucket: https://en.wikipedia.org/wiki/Token_bucket .. _HFSC: https://en.wikipedia.org/wiki/Hierarchical_fair-service_curve .. _Intermediate Functional Block: https://www.linuxfoundation.org/collaborate/workgroups/networking/ifb +.. _Common Applications Kept Enhanced: https://www.bufferbloat.net/projects/codel/wiki/Cake/ .. start_vyoslinter diff --git a/docs/configuration/vpn/l2tp.rst b/docs/configuration/vpn/l2tp.rst index f0c60ec1..b64c91a9 100644 --- a/docs/configuration/vpn/l2tp.rst +++ b/docs/configuration/vpn/l2tp.rst @@ -318,7 +318,7 @@ IPv6 set vpn l2tp remote-access ppp-options ipv6 allow set vpn l2tp remote-access client-ipv6-pool IPv6-POOL delegate '2001:db8:8003::/48' delegation-prefix '56' - set vpn l2tp remote-access client-ipv6-pool IPV6-POOL prefix '2001:db8:8002::/48' mask '64' + set vpn l2tp remote-access client-ipv6-pool IPv6-POOL prefix '2001:db8:8002::/48' mask '64' set vpn l2tp remote-access default-ipv6-pool IPv6-POOL IPv6 Advanced Options diff --git a/docs/configuration/vpn/pptp.rst b/docs/configuration/vpn/pptp.rst index 2a5e7731..5220929f 100644 --- a/docs/configuration/vpn/pptp.rst +++ b/docs/configuration/vpn/pptp.rst @@ -242,7 +242,7 @@ IPv6 set vpn pptp remote-access ppp-options ipv6 allow set vpn pptp remote-access client-ipv6-pool IPv6-POOL delegate '2001:db8:8003::/48' delegation-prefix '56' - set vpn pptp remote-access client-ipv6-pool IPV6-POOL prefix '2001:db8:8002::/48' mask '64' + set vpn pptp remote-access client-ipv6-pool IPv6-POOL prefix '2001:db8:8002::/48' mask '64' set vpn pptp remote-access default-ipv6-pool IPv6-POOL IPv6 Advanced Options diff --git a/docs/configuration/vpn/sstp.rst b/docs/configuration/vpn/sstp.rst index 3749eb7b..cd064162 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 @@ -471,6 +471,11 @@ Global Advanced options Windows Internet Name Service (WINS) servers propagated to client +.. cfgcmd:: set vpn sstp host-name <hostname> + + If this option is given, only SSTP connections to the specified host + and with the same TLS SNI will be allowed. + *********************** Configuring SSTP client *********************** 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 |