diff options
Diffstat (limited to 'docs/configuration')
76 files changed, 3567 insertions, 1710 deletions
diff --git a/docs/configuration/container/index.rst b/docs/configuration/container/index.rst index ed510477..c23a6184 100644 --- a/docs/configuration/container/index.rst +++ b/docs/configuration/container/index.rst @@ -1,34 +1,19 @@ -:lastproofread: 2021-06-30 - -.. include:: /_include/need_improvement.txt - -.. _container: +:lastproofread: 2022-06-10 ######### Container ######### +The VyOS container implementation is based on `Podman<https://podman.io/>` as +a deamonless container engine. + ************* Configuration ************* -.. cfgcmd:: set container <name> - - Set a named container. - -.. cfgcmd:: set container network <networkname> - - Creates a named container network - -.. cfgcmd:: set container registry <name> - - Adds registry to list of unqualified-search-registries. By default, for any - image that does not include the registry in the image name, Vyos will use - docker.io as the container registry. - -.. cfgcmd:: set container <name> image +.. cfgcmd:: set container name <name> image - Sets the image name in the hub registry + Sets the image name in the hub registry .. code-block:: none @@ -42,7 +27,7 @@ Configuration set container name mysql-server image quay.io/mysql:8.0 -.. cfgcmd:: set container <name> allow-host-networks +.. 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. @@ -50,50 +35,52 @@ Configuration The following commands translate to "--net host" when the container is created - .. note:: **allow-host-networks** cannot be used with **network** + .. note:: **allow-host-networks** cannot be used with **network** -.. cfgcmd:: set container <name> description <text> +.. cfgcmd:: set container name <name> network <networkname> - Sets the container description + Attaches user-defined network to a container. + Only one network must be specified and must already exist. -.. cfgcmd:: set container <name> environment '<key>' value '<value>' +.. cfgcmd:: set container name <name> network <networkname> address <address> - Add custom environment variables. - Multiple environment variables are allowed. - The following commands translate to "-e key=value" when the container - is created. + Optionally set a specific static IPv4 or IPv6 address for the container. + This address must be within the named network prefix. - .. code-block:: none + .. note:: The first IP in the container network is reserved by the engine and cannot be used - set container name mysql-server environment 'MYSQL_DATABASE' value 'zabbix' - set container name mysql-server environment 'MYSQL_USER' value 'zabbix' - set container name mysql-server environment 'MYSQL_PASSWORD' value 'zabbix_pwd' - set container name mysql-server environment 'MYSQL_ROOT_PASSWORD' value 'root_pwd' +.. cfgcmd:: set container name <name> description <text> -.. cfgcmd:: set container <name> network <networkname> + Set a container description - Attaches user-defined network to a container. - Only one network must be specified and must already exist. +.. cfgcmd:: set container name <name> environment <key> value <value> - Optionally a specific static IPv4 or IPv6 address can be set for - the container. This address must be within the named network. + Add custom environment variables. + Multiple environment variables are allowed. + The following commands translate to "-e key=value" when the container + is created. .. code-block:: none - set container <name> network <networkname> address <address> + set container name mysql-server environment MYSQL_DATABASE value 'zabbix' + set container name mysql-server environment MYSQL_USER value 'zabbix' + set container name mysql-server environment MYSQL_PASSWORD value 'zabbix_pwd' + set container name mysql-server environment MYSQL_ROOT_PASSWORD value 'root_pwd' - .. note:: The first IP in the container network is reserved by the engine and cannot be used +.. cfgcmd:: set container name <name> port <portname> source <portnumber> +.. cfgcmd:: set container name <name> port <portname> destination <portnumber> +.. cfgcmd:: set container name <name> port <portname> protocol <tcp | udp> -.. cfgcmd:: set container <name> port <portname> [source | destination ] <portnumber> - - Publishes a port for the container + Publish a port for the container. .. code-block:: none set container name zabbix-web-nginx-mysql port http source 80 set container name zabbix-web-nginx-mysql port http destination 8080 + set container name zabbix-web-nginx-mysql port http protocol tcp -.. cfgcmd:: set container <name> volume <volumename> [source | destination ] <path> +.. cfgcmd:: set container name <name> volume <volumename> source <path> +.. cfgcmd:: set container name <name> volume <volumename> destination <path> Mount a volume into the container @@ -101,6 +88,89 @@ Configuration set container name coredns volume 'corefile' source /config/coredns/Corefile set container name coredns volume 'corefile' destination /etc/Corefile + +.. cfgcmd:: set container name <name> volume <volumename> mode <ro | rw> + + Volume is either mounted as rw (read-write - default) or ro (read-only) + +.. cfgcmd:: set container name <name> restart [no | on-failure | always] + + 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 + +.. cfgcmd:: set container name <name> memory <MB> + + Constrain the memory available to the container. + + Default is 512 MB. Use 0 MB for unlimited memory. + +.. cfgcmd:: set container name <name> device <devicename> source <path> +.. cfgcmd:: set container name <name> device <devicename> destination <path> + + Add a host device to the container. + +.. cfgcmd:: container name <name> cap-add <text> + + 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-raw**: Permission to create raw network sockets + - **setpcap**: Capability sets (from bounded or inherited set) + - **sys-admin**: Administation operations (quotactl, mount, sethostname, setdomainame) + - **sys-time**: Permission to set system clock + +.. cfgcmd:: set container name <name> disable + + Disable a container. + +.. cfgcmd:: set container network <networkname> + + Creates a named container network + +.. cfgcmd:: set container registry <name> + + Adds registry to list of unqualified-search-registries. By default, for any + image that does not include the registry in the image name, Vyos will use + docker.io as the container registry. + + +****************** +Operation Commands +****************** + +.. opcmd:: add container image <containername> + + Pull a new image for container + +.. opcmd:: show container + + Show the list of all active containers. + +.. opcmd:: show container image + + Show the local container images. + +.. opcmd:: show container log <containername> + + Show logs from a given container + +.. opcmd:: show container network + + Show a list available container networks + +.. opcmd:: restart container <containername> + + Restart a given container + +.. opcmd:: update container image <containername> + + Update container image + + ********************* Example Configuration @@ -150,4 +220,4 @@ Example Configuration set container name zabbix-web-nginx-mysql environment 'MYSQL_ROOT_PASSWORD' value 'root_pwd' set container name zabbix-web-nginx-mysql port http source 80 - set container name zabbix-web-nginx-mysql port http destination 8080
\ No newline at end of file + set container name zabbix-web-nginx-mysql port http destination 8080 diff --git a/docs/configuration/firewall/general.rst b/docs/configuration/firewall/general.rst new file mode 100644 index 00000000..f2e01e03 --- /dev/null +++ b/docs/configuration/firewall/general.rst @@ -0,0 +1,1003 @@ +:lastproofread: 2021-06-29 + +.. _firewall: + +######## +Firewall +######## + +******** +Overview +******** + +VyOS makes use of Linux `netfilter <https://netfilter.org/>`_ for packet +filtering. + +The firewall supports the creation of groups for ports, addresses, and +networks (implemented using netfilter ipset) and the option of interface +or zone based firewall policy. + +.. note:: **Important note on usage of terms:** + The firewall makes use of the terms `in`, `out`, and `local` + for firewall policy. Users experienced with netfilter often confuse + `in` to be a reference to the `INPUT` chain, and `out` the `OUTPUT` + chain from netfilter. This is not the case. These instead indicate + the use of the `FORWARD` chain and either the input or output + interface. The `INPUT` chain, which is used for local traffic to the + OS, is a reference to as `local` with respect to its input interface. + + +*************** +Global settings +*************** + +Some firewall settings are global and have an affect on the whole system. + +.. cfgcmd:: set firewall all-ping [enable | disable] + + By default, when VyOS receives an ICMP echo request packet destined for + itself, it will answer with an ICMP echo reply, unless you avoid it + through its firewall. + + With the firewall you can set rules to accept, drop or reject ICMP in, + out or local traffic. You can also use the general **firewall all-ping** + command. This command affects only to LOCAL (packets destined for your + VyOS system), not to IN or OUT traffic. + + .. note:: **firewall all-ping** affects only to LOCAL and it always + behaves in the most restrictive way + + .. code-block:: none + + set firewall all-ping enable + + When the command above is set, VyOS will answer every ICMP echo request + addressed to itself, but that will only happen if no other rule is + applied dropping or rejecting local echo requests. In case of conflict, + VyOS will not answer ICMP echo requests. + + .. code-block:: none + + set firewall all-ping disable + + When the command above is set, VyOS will answer no ICMP echo request + addressed to itself at all, no matter where it comes from or whether + more specific rules are being applied to accept them. + +.. cfgcmd:: set firewall broadcast-ping [enable | disable] + + This setting enable or disable the response of icmp broadcast + messages. The following system parameter will be altered: + + * ``net.ipv4.icmp_echo_ignore_broadcasts`` + +.. cfgcmd:: set firewall ip-src-route [enable | disable] +.. cfgcmd:: set firewall ipv6-src-route [enable | disable] + + This setting handle if VyOS accept packets with a source route + option. The following system parameter will be altered: + + * ``net.ipv4.conf.all.accept_source_route`` + * ``net.ipv6.conf.all.accept_source_route`` + +.. cfgcmd:: set firewall receive-redirects [enable | disable] +.. cfgcmd:: set firewall ipv6-receive-redirects [enable | disable] + + enable or disable of ICMPv4 or ICMPv6 redirect messages accepted + by VyOS. The following system parameter will be altered: + + * ``net.ipv4.conf.all.accept_redirects`` + * ``net.ipv6.conf.all.accept_redirects`` + +.. cfgcmd:: set firewall send-redirects [enable | disable] + + enable or disable ICMPv4 redirect messages send by VyOS + The following system parameter will be altered: + + * ``net.ipv4.conf.all.send_redirects`` + +.. cfgcmd:: set firewall log-martians [enable | disable] + + enable or disable the logging of martian IPv4 packets. + The following system parameter will be altered: + + * ``net.ipv4.conf.all.log_martians`` + +.. cfgcmd:: set firewall source-validation [strict | loose | disable] + + Set the IPv4 source validation mode. + The following system parameter will be altered: + + * ``net.ipv4.conf.all.rp_filter`` + +.. cfgcmd:: set firewall syn-cookies [enable | disable] + + Enable or Disable if VyOS use IPv4 TCP SYN Cookies. + The following system parameter will be altered: + + * ``net.ipv4.tcp_syncookies`` + +.. cfgcmd:: set firewall twa-hazards-protection [enable | disable] + + Enable or Disable VyOS to be :rfc:`1337` conform. + The following system parameter will be altered: + + * ``net.ipv4.tcp_rfc1337`` + +.. cfgcmd:: set firewall state-policy established action [accept | drop | + reject] + +.. cfgcmd:: set firewall state-policy established log enable + + Set the global setting for an established connection. + +.. cfgcmd:: set firewall state-policy invalid action [accept | drop | reject] + +.. cfgcmd:: set firewall state-policy invalid log enable + + Set the global setting for invalid packets. + +.. cfgcmd:: set firewall state-policy related action [accept | drop | reject] + +.. cfgcmd:: set firewall state-policy related log enable + + Set the global setting for related connections. + + +****** +Groups +****** + +Firewall groups represent collections of IP addresses, networks, ports, +mac addresses or domains. Once created, a group can be referenced by +firewall, nat and policy route rules as either a source or destination +matcher. Members can be added or removed from a group without changes to, +or the need to reload, individual firewall rules. + +Groups need to have unique names. Even though some contain IPv4 +addresses and others contain IPv6 addresses, they still need to have +unique names, so you may want to append "-v4" or "-v6" to your group +names. + + +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 | + address range] +.. cfgcmd:: set firewall group ipv6-address-group <name> address <address> + + Define a IPv4 or a IPv6 address group + + .. code-block:: none + + set firewall group address-group ADR-INSIDE-v4 address 192.168.0.1 + 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> + + Provide a IPv4 or IPv6 address group description + +Network Groups +============== + +While **network groups** accept IP networks in CIDR notation, specific +IP addresses can be added as a 32-bit prefix. If you foresee the need +to add a mix of addresses and networks, the network group is +recommended. + +.. 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. + + .. code-block:: none + + set firewall group network-group NET-INSIDE-v4 network 192.168.0.0/24 + 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> + + Provide a IPv4 or IPv6 network group description. + +Port Groups +=========== + +A **port group** represents only port numbers, not the protocol. Port +groups can be referenced for either TCP or UDP. It is recommended that +TCP and UDP groups are created separately to avoid accidentally +filtering unnecessary ports. Ranges of ports can be specified by using +`-`. + +.. cfgcmd:: set firewall group port-group <name> port + [portname | portnumber | startport-endport] + + Define a port group. A port name can be any name defined in + /etc/services. e.g.: http + + .. code-block:: none + + set firewall group port-group PORT-TCP-SERVER1 port http + set firewall group port-group PORT-TCP-SERVER1 port 443 + set firewall group port-group PORT-TCP-SERVER1 port 5000-5010 + +.. cfgcmd:: set firewall group port-group <name> description <text> + + Provide a port group description. + +MAC Groups +========== + +A **mac group** represents a collection of mac addresses. + +.. cfgcmd:: set firewall group mac-group <name> mac-address <mac-address> + + Define a mac group. + +.. code-block:: none + + set firewall group mac-group MAC-G01 mac-address 88:a4:c2:15:b6:4f + set firewall group mac-group MAC-G01 mac-address 4c:d5:77:c0:19:81 + + +Domain Groups +============= + +A **domain group** represents a collection of domains. + +.. cfgcmd:: set firewall group domain-group <name> address <domain> + + Define a domain group. + +.. code-block:: none + + set firewall group domain-group DOM address example.com + + +********* +Rule-Sets +********* + +A rule-set is a named collection of firewall rules that can be applied +to an interface or a zone. Each rule is numbered, has an action to apply +if the rule is matched, and the ability to specify the criteria to +match. Data packets go through the rules from 1 - 999999, at the first match +the action of the rule will be executed. + +.. cfgcmd:: set firewall name <name> description <text> +.. cfgcmd:: set firewall ipv6-name <name> description <text> + + Provide a rule-set description. + +.. cfgcmd:: set firewall name <name> default-action [accept | drop | jump | + reject | return] +.. cfgcmd:: set firewall ipv6-name <name> default-action [accept | drop | + jump | reject | return] + + This set the default action of the rule-set if no rule matched a packet + criteria. If defacult-action is set to ``jump``, then + ``default-jump-target`` is also needed. + +.. cfgcmd:: set firewall name <name> default-jump-target <text> +.. cfgcmd:: set firewall ipv6-name <name> default-jump-target <text> + + To be used only when ``defult-action`` is set to ``jump``. Use this + command to specify jump target for default rule. + +.. cfgcmd:: set firewall name <name> enable-default-log +.. cfgcmd:: set firewall ipv6-name <name> enable-default-log + + Use this command to enable the logging of the default action. + +.. cfgcmd:: set firewall name <name> rule <1-999999> action [accept | drop | + jump | reject | return] +.. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> action [accept | + drop | jump | reject | return] + + This required setting defines the action of the current rule. If action + is set to ``jump``, then ``jump-target`` is also needed. + +.. cfgcmd:: set firewall name <name> rule <1-999999> jump-target <text> +.. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> jump-target <text> + + To be used only when ``action`` is set to ``jump``. Use this + command to specify jump target. + +.. cfgcmd:: set firewall name <name> rule <1-999999> description <text> +.. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> description <text> + + Provide a description for each rule. + +.. cfgcmd:: set firewall name <name> rule <1-999999> log [disable | enable] +.. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> log [disable | + enable] + + Enable or disable logging for the matched packet. + +.. cfgcmd:: set firewall name <name> rule <1-999999> log-level [emerg | + alert | crit | err | warn | notice | info | debug] +.. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> log-level [emerg | + alert | crit | err | warn | notice | info | debug] + + Define log-level. Only applicable if rule log is enable. + +.. cfgcmd:: set firewall name <name> rule <1-999999> disable +.. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> disable + + If you want to disable a rule but let it in the configuration. + +Matching criteria +================= + +There are a lot of matching criteria against which the package can be tested. + +.. cfgcmd:: set firewall name <name> rule <1-999999> connection-status nat + [destination | source] +.. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> connection-status + nat [destination | source] + + Match criteria based on nat connection status. + +.. cfgcmd:: set firewall name <name> rule <1-999999> connection-mark + <1-2147483647> +.. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> connection-mark + <1-2147483647> + + Match criteria based on connection mark. + +.. cfgcmd:: set firewall name <name> rule <1-999999> source address + [address | addressrange | CIDR] +.. cfgcmd:: set firewall name <name> rule <1-999999> destination address + [address | addressrange | CIDR] +.. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> source address + [address | addressrange | CIDR] +.. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> destination address + [address | addressrange | CIDR] + + This is similar to the network groups part, but here you are able to negate + the matching addresses. + + .. code-block:: none + + set firewall name WAN-IN-v4 rule 100 source address 192.0.2.10-192.0.2.11 + # with a '!' the rule match everything except the specified subnet + set firewall name WAN-IN-v4 rule 101 source address !203.0.113.0/24 + set firewall ipv6-name WAN-IN-v6 rule 100 source address 2001:db8::202 + +.. cfgcmd:: set firewall name <name> rule <1-999999> source address-mask + [address] +.. cfgcmd:: set firewall name <name> rule <1-999999> destination address-mask + [address] +.. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> source address-mask + [address] +.. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> destination + address-mask [address] + + An arbitrary netmask can be applied to mask addresses to only match against + a specific portion. This is particularly useful with IPv6 and a zone-based + firewall as rules will 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>`_) + + This functions for both individual addresses and address groups. + + .. code-block:: none + + # Match any IPv6 address with the suffix ::0000:0000:0000:beef + set firewall ipv6-name WAN-LAN-v6 rule 100 destination address ::beef + set firewall ipv6-name WAN-LAN-v6 rule 100 destination address-mask ::ffff:ffff:ffff:ffff + # Match any IPv4 address with `11` as the 2nd octet and `13` as the forth octet + set firewall name WAN-LAN-v4 rule 100 destination address 0.11.0.13 + set firewall name WAN-LAN-v4 rule 100 destination address-mask 0.255.0.255 + # Address groups + set firewall group ipv6-address-group WEBSERVERS address ::1000 + set firewall group ipv6-address-group WEBSERVERS address ::2000 + set firewall name WAN-LAN-v6 rule 200 source group address-group WEBSERVERS + set firewall name WAN-LAN-v6 rule 200 source address-mask ::ffff:ffff:ffff:ffff + +.. cfgcmd:: set firewall name <name> rule <1-999999> source fqdn <fqdn> +.. cfgcmd:: set firewall name <name> rule <1-999999> destination fqdn <fqdn> +.. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> source fqdn <fqdn> +.. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> destination fqdn + <fqdn> + + Specify a Fully Qualified Domain Name as source/destination matcher. Ensure + router is able to resolve such dns query. + +.. cfgcmd:: set firewall name <name> rule <1-999999> source geoip country-code + <country> +.. cfgcmd:: set firewall name <name> rule <1-999999> source geoip inverse-match +.. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> source geoip + country-code <country> +.. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> source geoip + inverse-match +.. cfgcmd:: set firewall name <name> rule <1-999999> destination geoip + country-code <country> +.. cfgcmd:: set firewall name <name> rule <1-999999> destination geoip + inverse-match +.. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> destination geoip + country-code <country> +.. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> destination geoip + inverse-match + +Match IP addresses based on its geolocation. +More info: `geoip matching +<https://wiki.nftables.org/wiki-nftables/index.php/GeoIP_matching>`_. + +Use inverse-match to match anything except the given country-codes. + +Data is provided by DB-IP.com under CC-BY-4.0 license. Attribution required, +permits redistribution so we can include a database in images(~3MB +compressed). Includes cron script (manually callable by op-mode update +geoip) to keep database and rules updated. + +.. cfgcmd:: set firewall name <name> rule <1-999999> source mac-address + <mac-address> +.. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> source mac-address + <mac-address> + + Only in the source criteria, you can specify a mac-address. + + .. code-block:: none + + set firewall name LAN-IN-v4 rule 100 source mac-address 00:53:00:11:22:33 + set firewall name LAN-IN-v4 rule 101 source mac-address !00:53:00:aa:12:34 + +.. cfgcmd:: set firewall name <name> rule <1-999999> source port + [1-65535 | portname | start-end] +.. cfgcmd:: set firewall name <name> rule <1-999999> destination port + [1-65535 | portname | start-end] +.. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> source port + [1-65535 | portname | start-end] +.. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> destination port + [1-65535 | portname | start-end] + + A port can be set with a port number or a name which is here + defined: ``/etc/services``. + + .. code-block:: none + + set firewall name WAN-IN-v4 rule 10 source port '22' + set firewall name WAN-IN-v4 rule 11 source port '!http' + set firewall name WAN-IN-v4 rule 12 source port 'https' + + Multiple source ports can be specified as a comma-separated list. + The whole list can also be "negated" using ``!``. For example: + + .. code-block:: none + + set firewall ipv6-name WAN-IN-v6 rule 10 source port '!22,https,3333-3338' + +.. cfgcmd:: set firewall name <name> rule <1-999999> source group + address-group <name | !name> +.. cfgcmd:: set firewall name <name> rule <1-999999> destination group + address-group <name | !name> +.. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> source group + address-group <name | !name> +.. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> destination group + address-group <name | !name> + + Use a specific address-group. Prepend character ``!`` for inverted matching + criteria. + +.. cfgcmd:: set firewall name <name> rule <1-999999> source group + network-group <name | !name> +.. cfgcmd:: set firewall name <name> rule <1-999999> destination group + network-group <name | !name> +.. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> source group + network-group <name | !name> +.. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> destination group + network-group <name | !name> + + Use a specific network-group. Prepend character ``!`` for inverted matching + criteria. + +.. cfgcmd:: set firewall name <name> rule <1-999999> source group + port-group <name | !name> +.. cfgcmd:: set firewall name <name> rule <1-999999> destination group + port-group <name | !name> +.. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> source group + port-group <name | !name> +.. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> destination group + port-group <name | !name> + + Use a specific port-group. Prepend character ``!`` for inverted matching + criteria. + +.. cfgcmd:: set firewall name <name> rule <1-999999> source group + domain-group <name | !name> +.. cfgcmd:: set firewall name <name> rule <1-999999> destination group + domain-group <name | !name> +.. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> source group + domain-group <name | !name> +.. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> destination group + domain-group <name | !name> + + Use a specific domain-group. Prepend character ``!`` for inverted matching + criteria. + +.. cfgcmd:: set firewall name <name> rule <1-999999> source group + mac-group <name | !name> +.. cfgcmd:: set firewall name <name> rule <1-999999> destination group + mac-group <name | !name> +.. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> source group + mac-group <name | !name> +.. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> destination group + mac-group <name | !name> + + Use a specific mac-group. Prepend character ``!`` for inverted matching + criteria. + +.. cfgcmd:: set firewall name <name> rule <1-999999> dscp [0-63 | start-end] +.. cfgcmd:: set firewall name <name> rule <1-999999> dscp-exclude [0-63 | + start-end] +.. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> dscp [0-63 | + start-end] +.. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> dscp-exclude [0-63 | + start-end] + + Match based on dscp value. + +.. cfgcmd:: set firewall name <name> rule <1-999999> fragment [match-frag | + match-non-frag] +.. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> fragment [match-frag + | match-non-frag] + + Match based on fragment criteria. + +.. cfgcmd:: set firewall name <name> rule <1-999999> icmp [code | type] + <0-255> +.. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> icmpv6 [code | type] + <0-255> + + Match based on icmp|icmpv6 code and type. + +.. cfgcmd:: set firewall name <name> rule <1-999999> icmp type-name <text> +.. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> icmpv6 type-name + <text> + + Match based on icmp|icmpv6 type-name criteria. Use tab for information + about what **type-name** criteria are supported. + +.. cfgcmd:: set firewall name <name> rule <1-999999> inbound-interface + <iface> +.. cfgcmd:: set firewall name <name> rule <1-999999> outbound-interface + <iface> +.. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> inbound-interface + <iface> +.. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> outbound-interface + <iface> + + Match based on inbound/outbound interface. Wilcard ``*`` can be used. + For example: ``eth2*`` + +.. cfgcmd:: set firewall name <name> rule <1-999999> ipsec [match-ipsec + | match-none] +.. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> ipsec [match-ipsec + | match-none] + + Match based on ipsec criteria. + +.. cfgcmd:: set firewall name <name> rule <1-999999> limit burst + <0-4294967295> +.. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> limit burst + <0-4294967295> + + Match based on the maximum number of packets to allow in excess of rate. + +.. cfgcmd:: set firewall name <name> rule <1-999999> limit rate + <text> +.. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> limit rate + <text> + + Match based on the maximum average rate, specified as **integer/unit**. + For example **5/minutes** + +.. cfgcmd:: set firewall name <name> rule <1-999999> packet-length + <text> +.. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> packet-length + <text> +.. cfgcmd:: set firewall name <name> rule <1-999999> packet-length-exclude + <text> +.. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> packet-length-exclude + <text> + + Match based on packet length criteria. Multiple values from 1 to 65535 + and ranges are supported. + +.. cfgcmd:: set firewall name <name> rule <1-999999> protocol [<text> | + <0-255> | all | tcp_udp] +.. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> protocol [<text> | + <0-255> | all | tcp_udp] + + Match a protocol criteria. A protocol number or a name which is here + defined: ``/etc/protocols``. + Special names are ``all`` for all protocols and ``tcp_udp`` for tcp and udp + based packets. The ``!`` negate the selected protocol. + + .. code-block:: none + + set firewall name WAN-IN-v4 rule 10 protocol tcp_udp + set firewall name WAN-IN-v4 rule 11 protocol !tcp_udp + set firewall ipv6-name WAN-IN-v6 rule 10 protocol tcp + +.. cfgcmd:: set firewall name <name> rule <1-999999> recent count <1-255> +.. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> recent count <1-255> +.. cfgcmd:: set firewall name <name> rule <1-999999> recent time + [second | minute | hour] +.. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> recent time + [second | minute | hour] + + Match bases on recently seen sources. + +.. cfgcmd:: set firewall name <name> rule <1-999999> tcp flags <text> +.. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> tcp flags <text> + + Allowed values fpr TCP flags: ``SYN``, ``ACK``, ``FIN``, ``RST``, ``URG``, + ``PSH``, ``ALL`` When specifying more than one flag, flags should be comma + separated. The ``!`` negate the selected protocol. + + .. code-block:: none + + set firewall name WAN-IN-v4 rule 10 tcp flags 'ACK' + set firewall name WAN-IN-v4 rule 12 tcp flags 'SYN' + set firewall name WAN-IN-v4 rule 13 tcp flags 'SYN,!ACK,!FIN,!RST' + +.. cfgcmd:: set firewall name <name> rule <1-999999> state [established | + invalid | new | related] [enable | disable] +.. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> state [established | + invalid | new | related] [enable | disable] + + Match against the state of a packet. + +.. cfgcmd:: set firewall name <name> rule <1-999999> time startdate <text> +.. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> time startdate <text> +.. cfgcmd:: set firewall name <name> rule <1-999999> time starttime <text> +.. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> time starttime <text> +.. cfgcmd:: set firewall name <name> rule <1-999999> time stopdate <text> +.. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> time stopdate <text> +.. cfgcmd:: set firewall name <name> rule <1-999999> time stoptime <text> +.. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> time stoptime <text> +.. cfgcmd:: set firewall name <name> rule <1-999999> time weekdays <text> +.. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> time weekdays <text> + + Time to match the defined rule. + +.. cfgcmd:: set firewall name <name> rule <1-999999> ttl <eq | gt | lt> <0-255> + + Match time to live parameter, where 'eq' stands for 'equal'; 'gt' stands for + 'greater than', and 'lt' stands for 'less than'. + +.. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> hop-limit <eq | gt | + lt> <0-255> + + Match hop-limit parameter, where 'eq' stands for 'equal'; 'gt' stands for + 'greater than', and 'lt' stands for 'less than'. + +.. cfgcmd:: set firewall name <name> rule <1-999999> recent count <1-255> +.. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> recent count <1-255> +.. cfgcmd:: set firewall name <name> rule <1-999999> recent time <second | + minute | hour> +.. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> recent time <second | + minute | hour> + + Match when 'count' amount of connections are seen within 'time'. These + matching criteria can be used to block brute-force attempts. + +*********************************** +Applying a Rule-Set to an Interface +*********************************** + +A Rule-Set can be applied to every interface: + +* ``in``: Ruleset for forwarded packets on an inbound interface +* ``out``: Ruleset for forwarded packets on an outbound interface +* ``local``: Ruleset for packets destined for this router + +.. cfgcmd:: set firewall interface <interface> [in | out | local] [name | + ipv6-name] <rule-set> + + + Here are some examples for applying a rule-set to an interface + + .. code-block:: none + + set firewall interface eth1.100 in name LANv4-IN + set firewall interface eth1.100 out name LANv4-OUT + set firewall interface bond0 in name LANv4-IN + set firewall interface vtun1 in name LANv4-IN + set firewall interface eth2* in name LANv4-IN + + .. note:: + As you can see in the example here, you can assign the same rule-set to + several interfaces. An interface can only have one rule-set per chain. + + .. note:: + You can use wildcard ``*`` to match a group of interfaces. + +*********************** +Operation-mode Firewall +*********************** + +Rule-set overview +================= + +.. opcmd:: show firewall + + This will show you a basic firewall overview + + .. code-block:: none + + vyos@vyos:~$ show firewall + + ------------------------ + Firewall Global Settings + ------------------------ + + Firewall state-policy for all IPv4 and Ipv6 traffic + + state action log + ----- ------ --- + invalid accept disabled + established accept disabled + related accept disabled + + ----------------------------- + Rulesets Information + ----------------------------- + -------------------------------------------------------------------------- + IPv4 Firewall "DMZv4-1-IN": + + Active on (eth0,IN) + + rule action proto packets bytes + ---- ------ ----- ------- ----- + 10 accept icmp 0 0 + condition - saddr 10.1.0.0/24 daddr 0.0.0.0/0 LOG enabled + + 10000 drop all 0 0 + condition - saddr 0.0.0.0/0 daddr 0.0.0.0/0 LOG enabled + + -------------------------------------------------------------------------- + IPv4 Firewall "DMZv4-1-OUT": + + Active on (eth0,OUT) + + rule action proto packets bytes + ---- ------ ----- ------- ----- + 10 accept tcp_udp 1 60 + condition - saddr 0.0.0.0/0 daddr 0.0.0.0/0 match-DST-PORT-GROUP DMZ-Ports /* + DMZv4-1-OUT-10 */LOG enabled + + 11 accept icmp 1 84 + condition - saddr 0.0.0.0/0 daddr 0.0.0.0/0 /* DMZv4-1-OUT-11 */LOG enabled + + 10000 drop all 6 360 + condition - saddr 0.0.0.0/0 daddr 0.0.0.0/0 LOG enabled + + -------------------------------------------------------------------------- + IPv4 Firewall "LANv4-IN": + + Inactive - Not applied to any interfaces or zones. + + rule action proto packets bytes + ---- ------ ----- ------- ----- + 10 accept all 0 0 + condition - saddr 0.0.0.0/0 daddr 0.0.0.0/0 /* LANv4-IN-10 */ + + 10000 drop all 0 0 + condition - saddr 0.0.0.0/0 daddr 0.0.0.0/0 + +.. opcmd:: show firewall summary + + This will show you a summary of rule-sets and groups + + .. code-block:: none + + vyos@vyos:~$ show firewall summary + + ------------------------ + Firewall Global Settings + ------------------------ + + Firewall state-policy for all IPv4 and Ipv6 traffic + + state action log + ----- ------ --- + invalid accept disabled + related accept disabled + established accept disabled + + ------------------------ + Firewall Rulesets + ------------------------ + + IPv4 name: + + Rule-set name Description References + ------------- ----------- ---------- + DMZv4-1-OUT (eth0,OUT) + DMZv4-1-IN (eth0,IN) + + ------------------------ + Firewall Groups + ------------------------ + + Port Groups: + + Group name Description References + ---------- ----------- ---------- + DMZ-Ports DMZv4-1-OUT-10-destination + + Network Groups: + + Group name Description References + ---------- ----------- ---------- + LANv4 LANv4-IN-10-source, + DMZv4-1-OUT-10-source, + DMZv4-1-OUT-11-source + +.. opcmd:: show firewall statistics + + This will show you a statistic of all rule-sets since the last boot. + +.. opcmd:: show firewall [name | ipv6name] <name> rule <1-999999> + + This command will give an overview of a rule in a single rule-set + +.. opcmd:: show firewall group <name> + + Overview of defined groups. You see the type, the members, and where the + group is used. + + .. code-block:: none + + vyos@vyos:~$ show firewall group DMZ-Ports + Name : DMZ-Ports + Type : port + References : none + Members : + 80 + 443 + 8080 + 8443 + + vyos@vyos:~$ show firewall group LANv4 + Name : LANv4 + Type : network + References : LANv4-IN-10-source + Members : + 10.10.0.0/16 + +.. opcmd:: show firewall [name | ipv6name] <name> + + This command will give an overview of a single rule-set. + +.. opcmd:: show firewall [name | ipv6name] <name> statistics + + This will show you a rule-set statistic since the last boot. + +.. opcmd:: show firewall [name | ipv6name] <name> rule <1-999999> + + This command will give an overview of a rule in a single rule-set. + + +Zone-Policy Overview +==================== + +.. opcmd:: show zone-policy zone <name> + + Use this command to get an overview of a zone. + + .. code-block:: none + + vyos@vyos:~$ show zone-policy zone DMZ + ------------------- + Name: DMZ + + Interfaces: eth0 eth1 + + From Zone: + name firewall + ---- -------- + LAN DMZv4-1-OUT + + +Show Firewall log +================= + +.. opcmd:: show log firewall [name | ipv6name] <name> + + Show the logs of a specific Rule-Set. + +.. note:: + At the moment it not possible to look at the whole firewall log with VyOS + operational commands. All logs will save to ``/var/logs/messages``. + For example: ``grep '10.10.0.10' /var/log/messages`` + + + +Example Partial Config +====================== + +.. code-block:: none + + firewall { + interface eth0 { + in { + name FROM-INTERNET + } + } + all-ping enable + broadcast-ping disable + config-trap disable + group { + network-group BAD-NETWORKS { + network 198.51.100.0/24 + network 203.0.113.0/24 + } + network-group GOOD-NETWORKS { + network 192.0.2.0/24 + } + port-group BAD-PORTS { + port 65535 + } + } + name FROM-INTERNET { + default-action accept + description "From the Internet" + rule 10 { + action accept + description "Authorized Networks" + protocol all + source { + group { + network-group GOOD-NETWORKS + } + } + } + rule 11 { + action drop + description "Bad Networks" + protocol all + source { + group { + network-group BAD-NETWORKS + } + } + } + rule 30 { + action drop + description "BAD PORTS" + destination { + group { + port-group BAD-PORTS + } + } + log enable + protocol all + } + } + } + interfaces { + ethernet eth1 { + address dhcp + description OUTSIDE + duplex auto + } + } + + +Update geoip database +===================== + +.. opcmd:: update geoip + + Command used to update GeoIP database and firewall sets.
\ No newline at end of file diff --git a/docs/configuration/firewall/index.rst b/docs/configuration/firewall/index.rst index c2b47c80..dfafa606 100644 --- a/docs/configuration/firewall/index.rst +++ b/docs/configuration/firewall/index.rst @@ -1,782 +1,10 @@ -:lastproofread: 2021-06-29 - -.. _firewall: - ######## Firewall ######## -******** -Overview -******** - -VyOS makes use of Linux `netfilter <https://netfilter.org/>`_ for packet -filtering. - -The firewall supports the creation of groups for ports, addresses, and -networks (implemented using netfilter ipset) and the option of interface -or zone based firewall policy. - -.. note:: **Important note on usage of terms:** - The firewall makes use of the terms `in`, `out`, and `local` - for firewall policy. Users experienced with netfilter often confuse - `in` to be a reference to the `INPUT` chain, and `out` the `OUTPUT` - chain from netfilter. This is not the case. These instead indicate - the use of the `FORWARD` chain and either the input or output - interface. The `INPUT` chain, which is used for local traffic to the - OS, is a reference to as `local` with respect to its input interface. - - -*************** -Global settings -*************** - -Some firewall settings are global and have an affect on the whole system. - -.. cfgcmd:: set firewall all-ping [enable | disable] - - By default, when VyOS receives an ICMP echo request packet destined for - itself, it will answer with an ICMP echo reply, unless you avoid it - through its firewall. - - With the firewall you can set rules to accept, drop or reject ICMP in, - out or local traffic. You can also use the general **firewall all-ping** - command. This command affects only to LOCAL (packets destined for your - VyOS system), not to IN or OUT traffic. - - .. note:: **firewall all-ping** affects only to LOCAL and it always - behaves in the most restrictive way - - .. code-block:: none - - set firewall all-ping enable - - When the command above is set, VyOS will answer every ICMP echo request - addressed to itself, but that will only happen if no other rule is - applied dropping or rejecting local echo requests. In case of conflict, - VyOS will not answer ICMP echo requests. - - .. code-block:: none - - set firewall all-ping disable - - When the command above is set, VyOS will answer no ICMP echo request - addressed to itself at all, no matter where it comes from or whether - more specific rules are being applied to accept them. - -.. cfgcmd:: set firewall broadcast-ping [enable | disable] - - This setting enable or disable the response of icmp broadcast - messages. The following system parameter will be altered: - - * ``net.ipv4.icmp_echo_ignore_broadcasts`` - -.. cfgcmd:: set firewall ip-src-route [enable | disable] -.. cfgcmd:: set firewall ipv6-src-route [enable | disable] - - This setting handle if VyOS accept packets with a source route - option. The following system parameter will be altered: - - * ``net.ipv4.conf.all.accept_source_route`` - * ``net.ipv6.conf.all.accept_source_route`` - -.. cfgcmd:: set firewall receive-redirects [enable | disable] -.. cfgcmd:: set firewall ipv6-receive-redirects [enable | disable] - - enable or disable of ICMPv4 or ICMPv6 redirect messages accepted - by VyOS. The following system parameter will be altered: - - * ``net.ipv4.conf.all.accept_redirects`` - * ``net.ipv6.conf.all.accept_redirects`` - -.. cfgcmd:: set firewall send-redirects [enable | disable] - - enable or disable ICMPv4 redirect messages send by VyOS - The following system parameter will be altered: - - * ``net.ipv4.conf.all.send_redirects`` - -.. cfgcmd:: set firewall log-martians [enable | disable] - - enable or disable the logging of martian IPv4 packets. - The following system parameter will be altered: - - * ``net.ipv4.conf.all.log_martians`` - -.. cfgcmd:: set firewall source-validation [strict | loose | disable] - - Set the IPv4 source validation mode. - The following system parameter will be altered: - - * ``net.ipv4.conf.all.rp_filter`` - -.. cfgcmd:: set firewall syn-cookies [enable | disable] - - Enable or Disable if VyOS use IPv4 TCP SYN Cookies. - The following system parameter will be altered: - - * ``net.ipv4.tcp_syncookies`` - -.. cfgcmd:: set firewall twa-hazards-protection [enable | disable] - - Enable or Disable VyOS to be :rfc:`1337` conform. - The following system parameter will be altered: - - * ``net.ipv4.tcp_rfc1337`` - -.. cfgcmd:: set firewall state-policy established action [accept | drop | - reject] - -.. cfgcmd:: set firewall state-policy established log enable - - Set the global setting for an established connection. - -.. cfgcmd:: set firewall state-policy invalid action [accept | drop | reject] - -.. cfgcmd:: set firewall state-policy invalid log enable - - Set the global setting for invalid packets. - -.. cfgcmd:: set firewall state-policy related action [accept | drop | reject] - -.. cfgcmd:: set firewall state-policy related log enable - - Set the global setting for related connections. - - -****** -Groups -****** - -Firewall groups represent collections of IP addresses, networks, or -ports. Once created, a group can be referenced by firewall rules as -either a source or destination. Members can be added or removed from a -group without changes to, or the need to reload, individual firewall -rules. - -Groups need to have unique names. Even though some contain IPv4 -addresses and others contain IPv6 addresses, they still need to have -unique names, so you may want to append "-v4" or "-v6" to your group -names. - - -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 | - address range] -.. cfgcmd:: set firewall group ipv6-address-group <name> address <address> - - Define a IPv4 or a IPv6 address group - - .. code-block:: none - - set firewall group address-group ADR-INSIDE-v4 address 192.168.0.1 - 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> - - Provide a IPv4 or IPv6 address group description - - -Network Groups -============== - -While **network groups** accept IP networks in CIDR notation, specific -IP addresses can be added as a 32-bit prefix. If you foresee the need -to add a mix of addresses and networks, the network group is -recommended. - -.. 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. - - .. code-block:: none - - set firewall group network-group NET-INSIDE-v4 network 192.168.0.0/24 - 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> - - Provide a IPv4 or IPv6 network group description. - - -Port Groups -=========== - -A **port group** represents only port numbers, not the protocol. Port -groups can be referenced for either TCP or UDP. It is recommended that -TCP and UDP groups are created separately to avoid accidentally -filtering unnecessary ports. Ranges of ports can be specified by using -`-`. - -.. cfgcmd:: set firewall group port-group <name> port - [portname | portnumber | startport-endport] - - Define a port group. A port name can be any name defined in - /etc/services. e.g.: http - - .. code-block:: none - - set firewall group port-group PORT-TCP-SERVER1 port http - set firewall group port-group PORT-TCP-SERVER1 port 443 - set firewall group port-group PORT-TCP-SERVER1 port 5000-5010 - -.. cfgcmd:: set firewall group port-group <name> description <text> - - Provide a port group description. - - -********* -Rule-Sets -********* - -A rule-set is a named collection of firewall rules that can be applied -to an interface or a zone. Each rule is numbered, has an action to apply -if the rule is matched, and the ability to specify the criteria to -match. Data packets go through the rules from 1 - 999999, at the first match -the action of the rule will be executed. - -.. cfgcmd:: set firewall name <name> description <text> -.. cfgcmd:: set firewall ipv6-name <name> description <text> - - Provide a rule-set description. - -.. cfgcmd:: set firewall name <name> default-action [drop | reject | accept] -.. cfgcmd:: set firewall ipv6-name <name> default-action [drop | reject | - accept] - - This set the default action of the rule-set if no rule matched a packet - criteria. - -.. cfgcmd:: set firewall name <name> enable-default-log -.. cfgcmd:: set firewall ipv6-name <name> enable-default-log - - Use this command to enable the logging of the default action. - -.. cfgcmd:: set firewall name <name> rule <1-999999> action [drop | reject | - accept] -.. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> action [drop | - reject | accept] - - This required setting defines the action of the current rule. - -.. cfgcmd:: set firewall name <name> rule <1-999999> description <text> -.. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> description <text> - - Provide a description for each rule. - -.. cfgcmd:: set firewall name <name> rule <1-999999> log [disable | enable] -.. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> log [disable | - enable] - - Enable or disable logging for the matched packet. - -.. cfgcmd:: set firewall name <name> rule <1-999999> disable -.. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> disable - - If you want to disable a rule but let it in the configuration. - -Matching criteria -================= - -There are a lot of matching criteria against which the package can be tested. - - -.. cfgcmd:: set firewall name <name> rule <1-999999> source address - [address | addressrange | CIDR] -.. cfgcmd:: set firewall name <name> rule <1-999999> destination address - [address | addressrange | CIDR] -.. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> source address - [address | addressrange | CIDR] -.. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> destination address - [address | addressrange | CIDR] - - This is similar to the network groups part, but here you are able to negate - the matching addresses. - - .. code-block:: none - - set firewall name WAN-IN-v4 rule 100 source address 192.0.2.10-192.0.2.11 - # with a '!' the rule match everything except the specified subnet - set firewall name WAN-IN-v4 rule 101 source address !203.0.113.0/24 - set firewall ipv6-name WAN-IN-v6 rule 100 source address 2001:db8::202 - - -.. cfgcmd:: set firewall name <name> rule <1-999999> source mac-address - <mac-address> -.. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> source mac-address - <mac-address> - - Only in the source criteria, you can specify a mac-address. - - .. code-block:: none - - set firewall name LAN-IN-v4 rule 100 source mac-address 00:53:00:11:22:33 - set firewall name LAN-IN-v4 rule 101 source mac-address !00:53:00:aa:12:34 - -.. cfgcmd:: set firewall name <name> rule <1-999999> source port - [1-65535 | portname | start-end] -.. cfgcmd:: set firewall name <name> rule <1-999999> destination port - [1-65535 | portname | start-end] -.. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> source port - [1-65535 | portname | start-end] -.. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> destination port - [1-65535 | portname | start-end] - - A port can be set with a port number or a name which is here - defined: ``/etc/services``. - - .. code-block:: none - - set firewall name WAN-IN-v4 rule 10 source port '22' - set firewall name WAN-IN-v4 rule 11 source port '!http' - set firewall name WAN-IN-v4 rule 12 source port 'https' - - Multiple source ports can be specified as a comma-separated list. - The whole list can also be "negated" using '!'. For example: - - .. code-block:: none - - set firewall ipv6-name WAN-IN-v6 rule 10 source port '!22,https,3333-3338' - -.. cfgcmd:: set firewall name <name> rule <1-999999> source group - address-group <name> -.. cfgcmd:: set firewall name <name> rule <1-999999> destination group - address-group <name> -.. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> source group - address-group <name> -.. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> destination group - address-group <name> - - Use a specific address-group - -.. cfgcmd:: set firewall name <name> rule <1-999999> source group - network-group <name> -.. cfgcmd:: set firewall name <name> rule <1-999999> destination group - network-group <name> -.. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> source group - network-group <name> -.. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> destination group - network-group <name> - - Use a specific network-group - -.. cfgcmd:: set firewall name <name> rule <1-999999> source group - port-group <name> -.. cfgcmd:: set firewall name <name> rule <1-999999> destination group - port-group <name> -.. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> source group - port-group <name> -.. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> destination group - port-group <name> - - Use a specific port-group - -.. cfgcmd:: set firewall name <name> rule <1-999999> protocol [<text> | - <0-255> | all | tcp_udp] -.. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> protocol [<text> | - <0-255> | all | tcp_udp] - - Match a protocol criteria. A protocol number or a name which is here - defined: ``/etc/protocols``. - Special names are ``all`` for all protocols and ``tcp_udp`` for tcp and udp - based packets. The ``!`` negate the selected protocol. - - .. code-block:: none - - set firewall name WAN-IN-v4 rule 10 protocol tcp_udp - set firewall name WAN-IN-v4 rule 11 protocol !tcp_udp - set firewall ipv6-name WAN-IN-v6 rule 10 protocol tcp - -.. cfgcmd:: set firewall name <name> rule <1-999999> tcp flags <text> -.. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> tcp flags <text> - - Allowed values fpr TCP flags: ``SYN``, ``ACK``, ``FIN``, ``RST``, ``URG``, - ``PSH``, ``ALL`` When specifying more than one flag, flags should be comma - separated. The ``!`` negate the selected protocol. - - .. code-block:: none - - set firewall name WAN-IN-v4 rule 10 tcp flags 'ACK' - set firewall name WAN-IN-v4 rule 12 tcp flags 'SYN' - set firewall name WAN-IN-v4 rule 13 tcp flags 'SYN,!ACK,!FIN,!RST' - -.. cfgcmd:: set firewall name <name> rule <1-999999> state [established | - invalid | new | related] [enable | disable] -.. cfgcmd:: set firewall ipv6-name <name> rule <1-999999> state [established | - invalid | new | related] [enable | disable] - - Match against the state of a packet. - - -*********************************** -Applying a Rule-Set to an Interface -*********************************** - -A Rule-Set can be applied to every interface: - -* ``in``: Ruleset for forwarded packets on an inbound interface -* ``out``: Ruleset for forwarded packets on an outbound interface -* ``local``: Ruleset for packets destined for this router - -.. cfgcmd:: set interface ethernet <ethN> firewall [in | out | local] - [name | ipv6-name] <rule-set> - - Here are some examples for applying a rule-set to an interface - - .. code-block:: none - - set interface ethernet eth1 vif 100 firewall in name LANv4-IN - set interface ethernet eth1 vif 100 firewall out name LANv4-OUT - set interface bonding bond0 firewall in name LANv4-IN - set interfaces openvpn vtun1 firewall in name Lanv4-IN - - .. note:: - As you can see in the example here, you can assign the same rule-set to - several interfaces. An interface can only have one rule-set per chain. - - -************************** -Zone-based Firewall Policy -************************** - -As an alternative to applying policy to an interface directly, a -zone-based firewall can be created to simplify configuration when -multiple interfaces belong to the same security zone. Instead of -applying rule-sets to interfaces, they are applied to source -zone-destination zone pairs. - -An basic introduction to zone-based firewalls can be found `here -<https://support.vyos.io/en/kb/articles/a-primer-to-zone-based-firewall>`_, -and an example at :ref:`examples-zone-policy`. - -Define a Zone -============= - -To define a zone setup either one with interfaces or a local zone. - -.. cfgcmd:: set zone-policy zone <name> interface <interfacenames> - - Set interfaces to a zone. A zone can have multiple interfaces. - But an interface can only be a member in one zone. - -.. cfgcmd:: set zone-policy zone <name> local-zone - - Define the zone as a local zone. A local zone has no interfaces and - will be applied to the router itself. - -.. cfgcmd:: set zone-policy zone <name> default-action [drop | reject] - - Change the default-action with this setting. - -.. cfgcmd:: set zone-policy zone <name> description - - Set a meaningful description. - - -Applying a Rule-Set to a Zone -============================= - -Before you are able to apply a rule-set to a zone you have to create the zones -first. - -It helps to think of the syntax as: (see below). The 'rule-set' should be -written from the perspective of: *Source Zone*-to->*Destination Zone* - -.. cfgcmd:: set zone-policy zone <Destination Zone> from <Source Zone> - firewall name <rule-set> - -.. cfgcmd:: set zone-policy zone <name> from <name> firewall name - <rule-set> -.. cfgcmd:: set zone-policy zone <name> from <name> firewall ipv6-name - <rule-set> - - You apply a rule-set always to a zone from an other zone, it is recommended - to create one rule-set for each zone pair. - - .. code-block:: none - - set zone-policy zone DMZ from LAN firewall name LANv4-to-DMZv4 - set zone-policy zone LAN from DMZ firewall name DMZv4-to-LANv4 - - -*********************** -Operation-mode Firewall -*********************** - -Rule-set overview -================= - -.. opcmd:: show firewall - - This will show you a basic firewall overview - - .. code-block:: none - - vyos@vyos:~$ show firewall - - ------------------------ - Firewall Global Settings - ------------------------ - - Firewall state-policy for all IPv4 and Ipv6 traffic - - state action log - ----- ------ --- - invalid accept disabled - established accept disabled - related accept disabled - - ----------------------------- - Rulesets Information - ----------------------------- - -------------------------------------------------------------------------- - IPv4 Firewall "DMZv4-1-IN": - - Active on (eth0,IN) - - rule action proto packets bytes - ---- ------ ----- ------- ----- - 10 accept icmp 0 0 - condition - saddr 10.1.0.0/24 daddr 0.0.0.0/0 LOG enabled - - 10000 drop all 0 0 - condition - saddr 0.0.0.0/0 daddr 0.0.0.0/0 LOG enabled - - -------------------------------------------------------------------------- - IPv4 Firewall "DMZv4-1-OUT": - - Active on (eth0,OUT) - - rule action proto packets bytes - ---- ------ ----- ------- ----- - 10 accept tcp_udp 1 60 - condition - saddr 0.0.0.0/0 daddr 0.0.0.0/0 match-DST-PORT-GROUP DMZ-Ports /* - DMZv4-1-OUT-10 */LOG enabled - - 11 accept icmp 1 84 - condition - saddr 0.0.0.0/0 daddr 0.0.0.0/0 /* DMZv4-1-OUT-11 */LOG enabled - - 10000 drop all 6 360 - condition - saddr 0.0.0.0/0 daddr 0.0.0.0/0 LOG enabled - - -------------------------------------------------------------------------- - IPv4 Firewall "LANv4-IN": - - Inactive - Not applied to any interfaces or zones. - - rule action proto packets bytes - ---- ------ ----- ------- ----- - 10 accept all 0 0 - condition - saddr 0.0.0.0/0 daddr 0.0.0.0/0 /* LANv4-IN-10 */ - - 10000 drop all 0 0 - condition - saddr 0.0.0.0/0 daddr 0.0.0.0/0 - -.. opcmd:: show firewall summary - - This will show you a summary of rule-sets and groups - - .. code-block:: none - - vyos@vyos:~$ show firewall summary - - ------------------------ - Firewall Global Settings - ------------------------ - - Firewall state-policy for all IPv4 and Ipv6 traffic - - state action log - ----- ------ --- - invalid accept disabled - related accept disabled - established accept disabled - - ------------------------ - Firewall Rulesets - ------------------------ - - IPv4 name: - - Rule-set name Description References - ------------- ----------- ---------- - DMZv4-1-OUT (eth0,OUT) - DMZv4-1-IN (eth0,IN) - - ------------------------ - Firewall Groups - ------------------------ - - Port Groups: - - Group name Description References - ---------- ----------- ---------- - DMZ-Ports DMZv4-1-OUT-10-destination - - Network Groups: - - Group name Description References - ---------- ----------- ---------- - LANv4 LANv4-IN-10-source, - DMZv4-1-OUT-10-source, - DMZv4-1-OUT-11-source - -.. opcmd:: show firewall statistics - - This will show you a statistic of all rule-sets since the last boot. - -.. opcmd:: show firewall [name | ipv6name] <name> rule <1-999999> - - This command will give an overview of a rule in a single rule-set - -.. opcmd:: show firewall group <name> - - Overview of defined groups. You see the type, the members, and where the - group is used. - - .. code-block:: none - - vyos@vyos:~$ show firewall group DMZ-Ports - Name : DMZ-Ports - Type : port - References : none - Members : - 80 - 443 - 8080 - 8443 - - vyos@vyos:~$ show firewall group LANv4 - Name : LANv4 - Type : network - References : LANv4-IN-10-source - Members : - 10.10.0.0/16 - -.. opcmd:: show firewall [name | ipv6name] <name> - - This command will give an overview of a single rule-set. - -.. opcmd:: show firewall [name | ipv6name] <name> statistics - - This will show you a rule-set statistic since the last boot. - -.. opcmd:: show firewall [name | ipv6name] <name> rule <1-999999> - - This command will give an overview of a rule in a single rule-set. - - -Zone-Policy Overview -==================== - -.. opcmd:: show zone-policy zone <name> - - Use this command to get an overview of a zone. - - .. code-block:: none - - vyos@vyos:~$ show zone-policy zone DMZ - ------------------- - Name: DMZ - - Interfaces: eth0 eth1 - - From Zone: - name firewall - ---- -------- - LAN DMZv4-1-OUT - - -Show Firewall log -================= - -.. opcmd:: show log firewall [name | ipv6name] <name> - - Show the logs of a specific Rule-Set. - -.. note:: - At the moment it not possible to look at the whole firewall log with VyOS - operational commands. All logs will save to ``/var/logs/messages``. - For example: ``grep '10.10.0.10' /var/log/messages`` - - - -Example Partial Config -====================== - -.. code-block:: none +.. toctree:: + :maxdepth: 1 + :includehidden: - firewall { - all-ping enable - broadcast-ping disable - config-trap disable - group { - network-group BAD-NETWORKS { - network 198.51.100.0/24 - network 203.0.113.0/24 - } - network-group GOOD-NETWORKS { - network 192.0.2.0/24 - } - port-group BAD-PORTS { - port 65535 - } - } - name FROM-INTERNET { - default-action accept - description "From the Internet" - rule 10 { - action accept - description "Authorized Networks" - protocol all - source { - group { - network-group GOOD-NETWORKS - } - } - } - rule 11 { - action drop - description "Bad Networks" - protocol all - source { - group { - network-group BAD-NETWORKS - } - } - } - rule 30 { - action drop - description "BAD PORTS" - destination { - group { - port-group BAD-PORTS - } - } - log enable - protocol all - } - } - } - interfaces { - ethernet eth1 { - address dhcp - description OUTSIDE - duplex auto - firewall { - in { - name FROM-INTERNET - } - } - } - } + general + zone diff --git a/docs/configuration/firewall/zone.rst b/docs/configuration/firewall/zone.rst new file mode 100644 index 00000000..b27e02b9 --- /dev/null +++ b/docs/configuration/firewall/zone.rst @@ -0,0 +1,91 @@ +:lastproofread: 2022-09-14 + +.. _firewall-zone: + +################### +Zone Based Firewall +################### + +In zone-based policy, interfaces are assigned to zones, and inspection policy +is applied to traffic moving between the zones and acted on according to +firewall rules. A Zone is a group of interfaces that have similar functions or +features. It establishes the security borders of a network. A zone defines a +boundary where traffic is subjected to policy restrictions as it crosses to +another region of a network. + +Key Points: + +* A zone must be configured before an interface is assigned to it and an + interface can be assigned to only a single zone. +* All traffic to and from an interface within a zone is permitted. +* All traffic between zones is affected by existing policies +* Traffic cannot flow between zone member interface and any interface that is + not a zone member. +* You need 2 separate firewalls to define traffic: one for each direction. + +.. note:: In :vytask:`T2199` the syntax of the zone configuration was changed. + The zone configuration moved from ``zone-policy zone <name>`` to ``firewall + zone <name>``. + +************* +Configuration +************* + +As an alternative to applying policy to an interface directly, a zone-based +firewall can be created to simplify configuration when multiple interfaces +belong to the same security zone. Instead of applying rule-sets to interfaces, +they are applied to source zone-destination zone pairs. + +An basic introduction to zone-based firewalls can be found `here +<https://support.vyos.io/en/kb/articles/a-primer-to-zone-based-firewall>`_, +and an example at :ref:`examples-zone-policy`. + +Define a Zone +============= + +To define a zone setup either one with interfaces or a local zone. + +.. cfgcmd:: set firewall zone <name> interface <interface> + + Set interfaces to a zone. A zone can have multiple interfaces. + But an interface can only be a member in one zone. + +.. cfgcmd:: set firewall zone <name> local-zone + + Define the zone as a local zone. A local zone has no interfaces and + will be applied to the router itself. + +.. cfgcmd:: set firewall zone <name> default-action [drop | reject] + + Change the default-action with this setting. + +.. cfgcmd:: set firewall zone <name> description + + Set a meaningful description. + +Applying a Rule-Set to a Zone +============================= + +Before you are able to apply a rule-set to a zone you have to create the zones +first. + +It helps to think of the syntax as: (see below). The 'rule-set' should be +written from the perspective of: *Source Zone*-to->*Destination Zone* + +.. cfgcmd:: set firewall zone <Destination Zone> from <Source Zone> + firewall name <rule-set> + +.. cfgcmd:: set firewall zone <name> from <name> firewall name + <rule-set> + +.. cfgcmd:: set firewall zone <name> from <name> firewall ipv6-name + <rule-set> + + You apply a rule-set always to a zone from an other zone, it is recommended + to create one rule-set for each zone pair. + + .. code-block:: none + + set firewall zone DMZ from LAN firewall name LANv4-to-DMZv4 + set firewall zone LAN from DMZ firewall name DMZv4-to-LANv4 + diff --git a/docs/configuration/highavailability/index.rst b/docs/configuration/highavailability/index.rst index 4a279213..9150b1bd 100644 --- a/docs/configuration/highavailability/index.rst +++ b/docs/configuration/highavailability/index.rst @@ -18,9 +18,9 @@ VRRP keepalive packets use multicast, and VRRP setups are limited to a single datalink layer segment. You can setup multiple VRRP groups (also called virtual routers). Virtual routers are identified by a VRID (Virtual Router IDentifier). If you setup multiple groups on the same -interface, their VRIDs must be unique, but it's possible (even if not -recommended for readability reasons) to use duplicate VRIDs on different -interfaces. +interface, their VRIDs must be unique if they use the same address family, +but it's possible (even if not recommended for readability reasons) to use +duplicate VRIDs on different interfaces. Basic setup ----------- @@ -220,6 +220,70 @@ Verification inet 172.25.0.247/16 scope global eth0v10 valid_lft forever preferred_lft forever +Global options +-------------- + +On most scenarios, there's no need to change specific parameters, and using +default configuration is enough. But there are cases were extra configuration +is needed. + +.. cfgcmd:: set high-availability vrrp global-parameters startup_delay <1-600> + +This option specifies a delay in seconds before vrrp instances start up after +keepalived starts. + +Gratuitous ARP +-------------- + +These configuration is not mandatory and in most cases there's no +need to configure it. But if necessary, Gratuitous ARP can be configured in +``global-parameters`` and/or in ``group`` section. + +.. cfgcmd:: set high-availability vrrp global-parameters garp interval + <0.000-1000> + +.. cfgcmd:: set high-availability vrrp group <name> garp interval + <0.000-1000> + +Set delay between gratuitous ARP messages sent on an interface. 0 if not +defined. + +.. cfgcmd:: set high-availability vrrp global-parameters garp master-delay + <1-255> + +.. cfgcmd:: set high-availability vrrp group <name> garp master-delay + <1-255> + +Set delay for second set of gratuitous ARPs after transition to MASTER. 5 if +not defined. + +.. cfgcmd:: set high-availability vrrp global-parameters garp master-refresh + <1-600> + +.. cfgcmd:: set high-availability vrrp group <name> garp master-refresh + <1-600> + +Set minimum time interval for refreshing gratuitous ARPs while MASTER. 0 if +not defined, which means no refreshing. + +.. cfgcmd:: set high-availability vrrp global-parameters garp + master-refresh-repeat <1-600> + +.. cfgcmd:: set high-availability vrrp group <name> garp + master-refresh-repeat <1-600> + +Set number of gratuitous ARP messages to send at a time while MASTER. 1 if not +defined. + +.. cfgcmd:: set high-availability vrrp global-parameters garp master-repeat + <1-600> + +.. cfgcmd:: set high-availability vrrp group <name> garp master-repeat + <1-600> + +Set number of gratuitous ARP messages to send at a time after transition to +MASTER. 5 if not defined. + Scripting --------- diff --git a/docs/configuration/index.rst b/docs/configuration/index.rst index 35b6fa5b..f607d4d7 100644 --- a/docs/configuration/index.rst +++ b/docs/configuration/index.rst @@ -22,4 +22,3 @@ The following structure respresent the cli structure. trafficpolicy/index vpn/index vrf/index - zonepolicy/index diff --git a/docs/configuration/interfaces/bridge.rst b/docs/configuration/interfaces/bridge.rst index ebb2232a..ddc293cc 100644 --- a/docs/configuration/interfaces/bridge.rst +++ b/docs/configuration/interfaces/bridge.rst @@ -78,7 +78,11 @@ Bridge Options .. cfgcmd:: set interfaces bridge <interface> igmp querier - Enable IGMP querier + Enable IGMP and MLD querier. + +.. cfgcmd:: set interfaces bridge <interface> igmp snooping + + Enable IGMP and MLD snooping. .. _stp: diff --git a/docs/configuration/interfaces/dummy.rst b/docs/configuration/interfaces/dummy.rst index 8440feca..945361c2 100644 --- a/docs/configuration/interfaces/dummy.rst +++ b/docs/configuration/interfaces/dummy.rst @@ -1,4 +1,4 @@ -:lastproofread: 2021-06-30 +:lastproofread: 2023-01-20 .. _dummy-interface: @@ -68,7 +68,7 @@ Operation .. code-block:: none - vyos@vyos:~$ show interfaces ethernet eth0 + vyos@vyos:~$ show interfaces dummy dum0 dum0: <BROADCAST,NOARP,UP,LOWER_UP> mtu 1500 qdisc noqueue state UNKNOWN group default qlen 1000 link/ether 26:7c:8e:bc:fc:f5 brd ff:ff:ff:ff:ff:ff inet 172.18.254.201/32 scope global dum0 diff --git a/docs/configuration/interfaces/ethernet.rst b/docs/configuration/interfaces/ethernet.rst index dcc9e529..d5e6279a 100644 --- a/docs/configuration/interfaces/ethernet.rst +++ b/docs/configuration/interfaces/ethernet.rst @@ -1,4 +1,4 @@ -:lastproofread: 2021-06-30 +:lastproofread: 2023-01-20 .. _ethernet-interface: @@ -71,8 +71,8 @@ Ethernet options Offloading ---------- -.. cfgcmd:: set interfaces ethernet <interface> offload <gro | gso | sg | tso | - ufo | rps> +.. cfgcmd:: set interfaces ethernet <interface> offload <gro | gso | lro | rps | + sg | tso> Enable different types of hardware offloading on the given NIC. diff --git a/docs/configuration/interfaces/geneve.rst b/docs/configuration/interfaces/geneve.rst index b13e2ece..bf8b0920 100644 --- a/docs/configuration/interfaces/geneve.rst +++ b/docs/configuration/interfaces/geneve.rst @@ -1,4 +1,4 @@ -:lastproofread: 2021-06-30 +:lastproofread: 2023-01-20 .. _geneve-interface: diff --git a/docs/configuration/interfaces/index.rst b/docs/configuration/interfaces/index.rst index 23792203..0f02d1e3 100644 --- a/docs/configuration/interfaces/index.rst +++ b/docs/configuration/interfaces/index.rst @@ -19,7 +19,9 @@ Interfaces wireguard pppoe pseudo-ethernet + sstp-client tunnel + virtual-ethernet vti vxlan wireless diff --git a/docs/configuration/interfaces/l2tpv3.rst b/docs/configuration/interfaces/l2tpv3.rst index ca0ce2c9..bd5d6862 100644 --- a/docs/configuration/interfaces/l2tpv3.rst +++ b/docs/configuration/interfaces/l2tpv3.rst @@ -1,4 +1,4 @@ -:lastproofread: 2021-06-30 +:lastproofread: 2023-01-20 .. include:: /_include/need_improvement.txt @@ -141,7 +141,7 @@ IPSec: .. code-block:: none - set vpn ipsec ipsec-interfaces <VPN-interface> + set vpn ipsec interface <VPN-interface> set vpn ipsec esp-group test-ESP-1 compression 'disable' set vpn ipsec esp-group test-ESP-1 lifetime '3600' set vpn ipsec esp-group test-ESP-1 mode 'transport' diff --git a/docs/configuration/interfaces/loopback.rst b/docs/configuration/interfaces/loopback.rst index b97aa69c..8e983abb 100644 --- a/docs/configuration/interfaces/loopback.rst +++ b/docs/configuration/interfaces/loopback.rst @@ -1,4 +1,4 @@ -:lastproofread: 2021-06-30 +:lastproofread: 2023-01-20 .. _loopback-interface: diff --git a/docs/configuration/interfaces/macsec.rst b/docs/configuration/interfaces/macsec.rst index 544bd4fc..60877d73 100644 --- a/docs/configuration/interfaces/macsec.rst +++ b/docs/configuration/interfaces/macsec.rst @@ -1,4 +1,4 @@ -:lastproofread: 2021-07-05 +:lastproofread: 2023-01-20 .. _macsec-interface: @@ -53,11 +53,12 @@ individual peers. .. cfgcmd:: set interfaces macsec <interface> security mka cak <key> IEEE 802.1X/MACsec pre-shared key mode. This allows configuring MACsec with - a pre-shared key using a (CAK,CKN) pair. + a pre-shared key using a :abbr:`CAK (MACsec connectivity association key)` and + :abbr:`CKN (MACsec connectivity association name)` pair. .. cfgcmd:: set interfaces macsec <interface> security mka ckn <key> - CAK Name + :abbr:`CKN (MACsec connectivity association name)` key .. cfgcmd:: set interfaces macsec <interface> security mka priority <priority> @@ -80,28 +81,27 @@ Replay protection Operation ********* -.. opcmd:: run generate macsec mka-cak +.. opcmd:: run generate macsec mka cak <gcm-aes-128|gcm-aes-256> - Generate :abbr:`MKA (MACsec Key Agreement protocol)` CAK key + Generate :abbr:`MKA (MACsec Key Agreement protocol)` CAK key 128 or 256 bits. .. code-block:: none - vyos@vyos:~$ generate macsec mka-cak + vyos@vyos:~$ generate macsec mka cak gcm-aes-128 20693b6e08bfa482703a563898c9e3ad +.. opcmd:: run generate macsec mka ckn -.. opcmd:: run generate macsec mka-ckn - - Generate :abbr:`MKA (MACsec Key Agreement protocol)` CAK key + Generate :abbr:`MKA (MACsec Key Agreement protocol)` CAK key. .. code-block:: none - vyos@vyos:~$ generate macsec mka-ckn + vyos@vyos:~$ generate macsec mka ckn 88737efef314ee319b2cbf30210a5f164957d884672c143aefdc0f5f6bc49eb2 .. opcmd:: show interfaces macsec - List all MACsec interfaces + List all MACsec interfaces. .. code-block:: none diff --git a/docs/configuration/interfaces/openvpn.rst b/docs/configuration/interfaces/openvpn.rst index 3fe6b1d4..5850591c 100644 --- a/docs/configuration/interfaces/openvpn.rst +++ b/docs/configuration/interfaces/openvpn.rst @@ -177,7 +177,7 @@ WAN interface and a direction (local). .. code-block:: none - set interfaces ethernet eth0 firewall local name 'OUTSIDE-LOCAL' + set firewall interface eth0 local name 'OUTSIDE-LOCAL' Static Routing: @@ -332,7 +332,7 @@ before using under the openvpn interface configuration. Now we need to specify the server network settings. In all cases we need to specify the subnet for client tunnel endpoints. Since we want clients to access -a specific network behind out router, we will use a push-route option for +a specific network behind our router, we will use a push-route option for installing that route on clients. .. code-block:: none diff --git a/docs/configuration/interfaces/pppoe.rst b/docs/configuration/interfaces/pppoe.rst index e1bb3056..0953e948 100644 --- a/docs/configuration/interfaces/pppoe.rst +++ b/docs/configuration/interfaces/pppoe.rst @@ -1,4 +1,4 @@ -:lastproofread: 2021-07-09 +:lastproofread: 2022-07-27 .. _pppoe-interface: @@ -69,6 +69,10 @@ Common interface configuration :var0: pppoe :var1: pppoe0 +.. cmdinclude:: /_include/interface-mtu.txt + :var0: pppoe + :var1: pppoe0 + .. cmdinclude:: /_include/interface-vrf.txt :var0: pppoe :var1: pppoe0 @@ -126,6 +130,9 @@ PPPoE options set interfaces pppoe pppoe0 no-default-route + .. note:: This command got added in VyOS 1.4 and inverts the logic from the old + ``default-route`` CLI option. + .. cfgcmd:: set interfaces pppoe <interface> default-route-distance <distance> Set the distance for the default gateway sent by the PPPoE server. @@ -152,11 +159,6 @@ PPPoE options Use this command to set the IP address of the local endpoint of a PPPoE session. If it is not set it will be negotiated. -.. cfgcmd:: set interfaces pppoe <interface> mtu <mtu> - - Configure :abbr:`MTU (Maximum Transmission Unit)` on given `<interface>`. It - is the size (in bytes) of the largest ethernet frame sent on this link. - .. cfgcmd:: set interfaces pppoe <interface> no-peer-dns Use this command to not install advertised DNS nameservers into the local @@ -310,11 +312,6 @@ Requirements: If you are switching from a DHCP based ISP like cable then be aware that things like VPN links may need to have their MTU sizes adjusted to work within this limit. -* With the ``default-route`` option set to ``auto``, VyOS will only add the - default gateway you receive from your DSL ISP to the routing table if you - have no other WAN connections. If you wish to use a dual WAN connection, - change the ``default-route`` option to ``force``. You could also install - a static route and set the ``default-route`` option to ``none``. * With the ``name-server`` option set to ``none``, VyOS will ignore the nameservers your ISP sends you and thus you can fully rely on the ones you have configured statically. @@ -322,10 +319,11 @@ Requirements: .. note:: Syntax has changed from VyOS 1.2 (crux) and it will be automatically migrated during an upgrade. +.. note:: A default route is automatically installed once the interface is up. + To change this behavior use the ``no-default-route`` CLI option. + .. code-block:: none - set interfaces pppoe pppoe0 default-route 'auto' - set interfaces pppoe pppoe0 mtu 1492 set interfaces pppoe pppoe0 authentication user 'userid' set interfaces pppoe pppoe0 authentication password 'secret' set interfaces pppoe pppoe0 source-interface 'eth0' @@ -336,9 +334,9 @@ assigning it to the pppoe0 itself as shown here: .. code-block:: none - set interfaces pppoe pppoe0 firewall in name NET-IN - set interfaces pppoe pppoe0 firewall local name NET-LOCAL - set interfaces pppoe pppoe0 firewall out name NET-OUT + set firewall interface pppoe0 in name NET-IN + set firewall interface pppoe0 local name NET-LOCAL + set firewall interface pppoe0 out name NET-OUT VLAN Example ============ @@ -351,8 +349,6 @@ which is the default VLAN for Deutsche Telekom: .. code-block:: none - set interfaces pppoe pppoe0 default-route 'auto' - set interfaces pppoe pppoe0 mtu 1492 set interfaces pppoe pppoe0 authentication user 'userid' set interfaces pppoe pppoe0 authentication password 'secret' set interfaces pppoe pppoe0 source-interface 'eth0.7' diff --git a/docs/configuration/interfaces/pseudo-ethernet.rst b/docs/configuration/interfaces/pseudo-ethernet.rst index b2849772..59b3581c 100644 --- a/docs/configuration/interfaces/pseudo-ethernet.rst +++ b/docs/configuration/interfaces/pseudo-ethernet.rst @@ -1,4 +1,4 @@ -:lastproofread: 2021-07-09 +:lastproofread: 2023-01-26 .. _pseudo-ethernet-interface: diff --git a/docs/configuration/interfaces/sstp-client.rst b/docs/configuration/interfaces/sstp-client.rst new file mode 100644 index 00000000..27eb9c39 --- /dev/null +++ b/docs/configuration/interfaces/sstp-client.rst @@ -0,0 +1,150 @@ +:lastproofread: 2022-12-11 + +.. _sstp-client-interface: + +########### +SSTP Client +########### + +:abbr:`SSTP (Secure Socket Tunneling Protocol)` is a form of :abbr:`VTP (Virtual +Private Network)` tunnel that provides a mechanism to transport PPP traffic +through an SSL/TLS channel. SSL/TLS provides transport-level security with key +negotiation, encryption and traffic integrity checking. The use of SSL/TLS over +TCP port 443 (by default, port can be changed) allows SSTP to pass through +virtually all firewalls and proxy servers except for authenticated web proxies. + +.. note:: VyOS also comes with a build in SSTP server, see :ref:`sstp`. + +************* +Configuration +************* + +Common interface configuration +============================== + +.. cmdinclude:: /_include/interface-description.txt + :var0: sstpc + :var1: sstpc0 + +.. cmdinclude:: /_include/interface-disable.txt + :var0: sstpc + :var1: sstpc0 + +.. cmdinclude:: /_include/interface-mtu.txt + :var0: sstpc + :var1: sstpc0 + +.. cmdinclude:: /_include/interface-vrf.txt + :var0: sstpc + :var1: sstpc0 + +SSTP Client Options +=================== + +.. cfgcmd:: set interfaces sstpc <interface> no-default-route + + Only request an address from the SSTP server but do not install any default + route. + + Example: + + .. code-block:: none + + set interfaces sstpc sstpc0 no-default-route + + .. note:: This command got added in VyOS 1.4 and inverts the logic from the old + ``default-route`` CLI option. + +.. cfgcmd:: set interfaces sstpc <interface> default-route-distance <distance> + + Set the distance for the default gateway sent by the SSTP server. + + Example: + + .. code-block:: none + + set interfaces sstpc sstpc0 default-route-distance 220 + +.. cfgcmd:: set interfaces sstpc <interface> no-peer-dns + + Use this command to not install advertised DNS nameservers into the local + system. + +.. cfgcmd:: set interfaces sstpc <interface> server <address> + + SSTP remote server to connect to. Can be either an IP address or FQDN. + +.. cfgcmd:: set interfaces sstpc <interface> ip adjust-mss <mss | clamp-mss-to-pmtu> + + As Internet wide PMTU discovery rarely works, we sometimes need to clamp our + TCP MSS value to a specific value. This is a field in the TCP options part of + a SYN packet. By setting the MSS value, you are telling the remote side + unequivocally 'do not try to send me packets bigger than this value'. + + .. note:: This command was introduced in VyOS 1.4 - it was previously called: + ``set firewall options interface <name> adjust-mss <value>`` + + .. hint:: MSS value = MTU - 20 (IP header) - 20 (TCP header), resulting in + 1452 bytes on a 1492 byte MTU. + + Instead of a numerical MSS value `clamp-mss-to-pmtu` can be used to + automatically set the proper value. + +.. cfgcmd:: set interfaces sstpc <interface> ip disable-forwarding + + Configure interface-specific Host/Router behaviour. If set, the interface will + switch to host mode and IPv6 forwarding will be disabled on this interface. + +.. cfgcmd:: set interfaces sstpc <interface> ip source-validation <strict | loose | disable> + + Enable policy for source validation by reversed path, as specified in + :rfc:`3704`. Current recommended practice in :rfc:`3704` is to enable strict + mode to prevent IP spoofing from DDos attacks. If using asymmetric routing + or other complicated routing, then loose mode is recommended. + + - strict: Each incoming packet is tested against the FIB and if the interface + is not the best reverse path the packet check will fail. By default failed + packets are discarded. + + - loose: Each incoming packet's source address is also tested against the FIB + and if the source address is not reachable via any interface the packet + check will fail. + + - disable: No source validation + +********* +Operation +********* + +.. opcmd:: show interfaces sstpc <interface> + + Show detailed information on given `<interface>` + + .. code-block:: none + + vyos@vyos:~$ show interfaces sstpc sstpc10 + sstpc10: <POINTOPOINT,MULTICAST,NOARP,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UNKNOWN group default qlen 3 + link/ppp + inet 192.0.2.5 peer 192.0.2.254/32 scope global sstpc10 + valid_lft forever preferred_lft forever + inet6 fe80::fd53:c7ff:fe8b:144f/64 scope link + valid_lft forever preferred_lft forever + + RX: bytes packets errors dropped overrun mcast + 215 9 0 0 0 0 + TX: bytes packets errors dropped carrier collisions + 539 14 0 0 0 0 + + +Connect/Disconnect +================== + +.. opcmd:: disconnect interface <interface> + + Test disconnecting given connection-oriented interface. `<interface>` can be + ``sstpc0`` as the example. + +.. opcmd:: connect interface <interface> + + Test connecting given connection-oriented interface. `<interface>` can be + ``sstpc0`` as the example. diff --git a/docs/configuration/interfaces/tunnel.rst b/docs/configuration/interfaces/tunnel.rst index 6a5fb171..bd7a8460 100644 --- a/docs/configuration/interfaces/tunnel.rst +++ b/docs/configuration/interfaces/tunnel.rst @@ -1,4 +1,4 @@ -:lastproofread: 2021-07-09 +:lastproofread: 2023-01-26 .. _tunnel-interface: @@ -18,7 +18,7 @@ a closer look at the protocols and options currently supported by VyOS. Common interface configuration ------------------------------ -.. cmdinclude:: /_include/interface-common-without-dhcp.txt +.. cmdinclude:: /_include/interface-common-without-dhcp1.txt :var0: tunnel :var1: tun0 diff --git a/docs/configuration/interfaces/virtual-ethernet.rst b/docs/configuration/interfaces/virtual-ethernet.rst new file mode 100644 index 00000000..a6988318 --- /dev/null +++ b/docs/configuration/interfaces/virtual-ethernet.rst @@ -0,0 +1,95 @@ +:lastproofread: 2022-11-25 + +.. _virtual-ethernet: + +################ +Virtual Ethernet +################ + +The veth devices are virtual Ethernet devices. They can act as tunnels between +network namespaces to create a bridge to a physical network device in another +namespace or VRF, but can also be used as standalone network devices. + +.. note:: veth interfaces need to be created in pairs - it's called the peer name + +************* +Configuration +************* + +Common interface configuration +============================== + +.. cmdinclude:: /_include/interface-address-with-dhcp.txt + :var0: virtual-ethernet + :var1: veth0 + +.. cmdinclude:: /_include/interface-description.txt + :var0: virtual-ethernet + :var1: veth0 + +.. cmdinclude:: /_include/interface-disable.txt + :var0: virtual-ethernet + :var1: veth0 + +.. cmdinclude:: /_include/interface-vrf.txt + :var0: virtual-ethernet + :var1: veth0 + +********* +Operation +********* + +.. opcmd:: show interfaces virtual-ethernet + + Show brief interface information. + + .. code-block:: none + + vyos@vyos:~$ show interfaces virtual-ethernet + Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down + Interface IP Address S/L Description + --------- ---------- --- ----------- + veth10 100.64.0.0/31 u/u + veth11 100.64.0.1/31 u/u + +.. opcmd:: show interfaces virtual-ethernet <interface> + + Show detailed information on given `<interface>` + + .. code-block:: none + + vyos@vyos:~$ show interfaces virtual-ethernet veth11 + 10: veth11@veth10: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue master red state UP group default qlen 1000 + link/ether b2:7b:df:47:e9:11 brd ff:ff:ff:ff:ff:ff + inet 100.64.0.1/31 scope global veth11 + valid_lft forever preferred_lft forever + inet6 fe80::b07b:dfff:fe47:e911/64 scope link + valid_lft forever preferred_lft forever + + + RX: bytes packets errors dropped overrun mcast + 0 0 0 0 0 0 + TX: bytes packets errors dropped carrier collisions + 1369707 4267 0 0 0 0 + +******* +Example +******* + +Interconnect the global VRF with vrf "red" using the veth10 <-> veth 11 pair + +.. code-block:: none + + set interfaces virtual-ethernet veth10 address '100.64.0.0/31' + set interfaces virtual-ethernet veth10 peer-name 'veth11' + set interfaces virtual-ethernet veth11 address '100.64.0.1/31' + set interfaces virtual-ethernet veth11 peer-name 'veth10' + set interfaces virtual-ethernet veth11 vrf 'red' + set vrf name red table '1000' + + vyos@vyos:~$ ping 100.64.0.1 + PING 100.64.0.1 (100.64.0.1) 56(84) bytes of data. + 64 bytes from 100.64.0.1: icmp_seq=1 ttl=64 time=0.080 ms + 64 bytes from 100.64.0.1: icmp_seq=2 ttl=64 time=0.119 ms + + diff --git a/docs/configuration/interfaces/vxlan.rst b/docs/configuration/interfaces/vxlan.rst index 7edeafb5..86568686 100644 --- a/docs/configuration/interfaces/vxlan.rst +++ b/docs/configuration/interfaces/vxlan.rst @@ -1,4 +1,4 @@ -:lastproofread: 2021-07-09 +:lastproofread: 2023-01-26 .. _vxlan-interface: diff --git a/docs/configuration/interfaces/wireguard.rst b/docs/configuration/interfaces/wireguard.rst index 93093b5d..18a888df 100644 --- a/docs/configuration/interfaces/wireguard.rst +++ b/docs/configuration/interfaces/wireguard.rst @@ -1,4 +1,4 @@ -:lastproofread: 2021-10-01 +:lastproofread: 2023-01-26 .. _wireguard: @@ -173,6 +173,7 @@ traffic. Associates the previously generated private key to a specific WireGuard interface. The private key can be generate via the command + :opcmd:`generate pki wireguard key-pair`. .. code-block:: none @@ -243,8 +244,8 @@ asymmetric crypto. This is optional. .. code-block:: none - vyos@vyos:~$ generate pki wireguard preshared-key install - rvVDOoc2IYEnV+k5p7TNAmHBMEGTHbPU8Qqg8c/sUqc= + vyos@vyos:~$ generate pki wireguard preshared-key + Pre-shared key: rvVDOoc2IYEnV+k5p7TNAmHBMEGTHbPU8Qqg8c/sUqc= Copy the key, as it is not stored on the local filesystem. Because it is a symmetric key, only you and your peer should have knowledge of diff --git a/docs/configuration/interfaces/wireless.rst b/docs/configuration/interfaces/wireless.rst index b775011f..f45101b5 100644 --- a/docs/configuration/interfaces/wireless.rst +++ b/docs/configuration/interfaces/wireless.rst @@ -1,4 +1,4 @@ -:lastproofread: 2021-07-13 +:lastproofread: 2023-01-26 .. _wireless-interface: @@ -305,7 +305,7 @@ default physical device (``phy0``) is used. set interfaces wireless wlan0 type station set interfaces wireless wlan0 address dhcp set interfaces wireless wlan0 ssid Test - set interfaces wireless wlan0 security wpa + set interfaces wireless wlan0 security wpa passphrase '12345678' Resulting in @@ -590,3 +590,24 @@ To get it to work as an access point with this configuration you will need to set up a DHCP server to work with that network. You can - of course - also bridge the Wireless interface with any configured bridge (:ref:`bridge-interface`) on the system. + +.. _wireless-interface-intel-ax200: + +Intel AX200 +=========== + +The Intel AX200 card does not work out of the box in AP mode, see +https://unix.stackexchange.com/questions/598275/intel-ax200-ap-mode. You can +still put this card into AP mode using the following configuration: + +.. stop_vyoslinter +.. code-block:: none + + set interfaces wireless wlan0 channel '1' + set interfaces wireless wlan0 country-code 'us' + set interfaces wireless wlan0 mode 'n' + set interfaces wireless wlan0 physical-device 'phy0' + set interfaces wireless wlan0 ssid 'VyOS' + set interfaces wireless wlan0 type 'access-point' + +.. start_vyoslinter diff --git a/docs/configuration/interfaces/wwan.rst b/docs/configuration/interfaces/wwan.rst index 0c820471..45b18387 100644 --- a/docs/configuration/interfaces/wwan.rst +++ b/docs/configuration/interfaces/wwan.rst @@ -1,4 +1,4 @@ -:lastproofread: 2021-07-13 +:lastproofread: 2023-01-27 .. _wwan-interface: diff --git a/docs/configuration/loadbalancing/index.rst b/docs/configuration/loadbalancing/index.rst index 3ae85708..18f01347 100644 --- a/docs/configuration/loadbalancing/index.rst +++ b/docs/configuration/loadbalancing/index.rst @@ -1,4 +1,4 @@ -:lastproofread: 2021-07-28 +:lastproofread: 2023-01-27 .. _load-balancing: @@ -13,7 +13,7 @@ the routing table and balances traffic across the configured interfaces, determined by interface health and weight. -In a minimal, configuration the following must be provided: +In a minimal configuration, the following must be provided: * an interface with a nexthop * one rule with a LAN (inbound-interface) and the WAN (interface). @@ -28,6 +28,12 @@ Let's assume we have two DHCP WAN interfaces and one LAN (eth2): set load-balancing wan rule 1 interface eth0 set load-balancing wan rule 1 interface eth1 +.. note:: + + WAN Load Balacing should not be used when dynamic routing protocol is + used/needed. This feature creates customized routing tables and firewall + rules, that makes it incompatible to use with routing protocols. + Balancing Rules --------------- diff --git a/docs/configuration/nat/nat44.rst b/docs/configuration/nat/nat44.rst index 02aa4ece..62964fea 100644 --- a/docs/configuration/nat/nat44.rst +++ b/docs/configuration/nat/nat44.rst @@ -684,7 +684,7 @@ external interface in the image above) set vpn ipsec esp-group my-esp proposal 1 encryption 'aes256' set vpn ipsec esp-group my-esp proposal 1 hash 'sha256' - set vpn ipsec ipsec-interfaces interface 'eth1' + set vpn ipsec interface 'eth1' IPSec VPN Tunnels """"""""""""""""" diff --git a/docs/configuration/pki/index.rst b/docs/configuration/pki/index.rst index b46f821c..e83272f5 100644 --- a/docs/configuration/pki/index.rst +++ b/docs/configuration/pki/index.rst @@ -272,7 +272,7 @@ also to display them. Show only information for specified Certificate Authority. -.. opcmd:: show pki certificates +.. opcmd:: show pki certificate Show a list of installed certificates @@ -285,7 +285,7 @@ also to display them. ac2 Server CN=ac2.vyos.net CN=R3 2021-07-05 07:29:59 2021-10-03 07:29:58 No Yes Yes (R3) rw_server Server CN=VyOS RW CN=VyOS RW CA 2021-07-05 13:48:02 2022-07-05 13:48:02 No Yes Yes (vyos_rw) -.. opcmd:: show pki certificates <name> +.. opcmd:: show pki certificate <name> Show only information for specified certificate. diff --git a/docs/configuration/policy/examples.rst b/docs/configuration/policy/examples.rst index e4c4b9da..7c7b9c46 100644 --- a/docs/configuration/policy/examples.rst +++ b/docs/configuration/policy/examples.rst @@ -8,10 +8,10 @@ BGP Example # Create policy set policy route-map setmet rule 2 action 'permit' - set policy route-map setmet rule 2 set as-path-prepend '2 2 2' + set policy route-map setmet rule 2 set as-path prepend '2 2 2' # Apply policy to BGP - set protocols bgp local-as 1 + set protocols bgp system-as 1 set protocols bgp neighbor 203.0.113.2 address-family ipv4-unicast route-map import 'setmet' set protocols bgp neighbor 203.0.113.2 address-family ipv4-unicast soft-reconfiguration 'inbound' @@ -83,7 +83,7 @@ interface, we use: .. code-block:: none - set interfaces ethernet eth1 policy route FILTER-WEB + set policy route FILTER-WEB interface eth1 ################ Multiple Uplinks @@ -129,8 +129,8 @@ Apply routing policy to **inbound** direction of out VLAN interfaces .. code-block:: none - set interfaces ethernet eth0 vif 10 policy route 'PBR' - set interfaces ethernet eth0 vif 11 policy route 'PBR' + set policy route 'PBR' interface eth0.10 + set policy route 'PBR' interface eth0.11 **OPTIONAL:** Exclude Inter-VLAN traffic (between VLAN10 and VLAN11) @@ -182,3 +182,32 @@ Add multiple source IP in one rule with same priority set policy local-route rule 101 source '203.0.113.253' set policy local-route rule 101 source '198.51.100.0/24' +########################### +Clamp MSS for a specific IP +########################### + +This example shows how to target an MSS clamp (in our example to 1360 bytes) +to a specific destination IP. + +.. code-block:: none + + set policy route IP-MSS-CLAMP rule 10 description 'Clamp TCP session MSS to 1360 for 198.51.100.30' + set policy route IP-MSS-CLAMP rule 10 destination address '198.51.100.30/32' + set policy route IP-MSS-CLAMP rule 10 protocol 'tcp' + set policy route IP-MSS-CLAMP rule 10 set tcp-mss '1360' + set policy route IP-MSS-CLAMP rule 10 tcp flags 'SYN' + +To apply this policy to the correct interface, configure it on the +interface the inbound local host will send through to reach our +destined target host (in our example eth1). + +.. code-block:: none + + set policy route IP-MSS-CLAMP interface eth1 + +You can view that the policy is being correctly (or incorrectly) utilised +with the following command: + +.. code-block:: none + + show policy route statistics diff --git a/docs/configuration/policy/route-map.rst b/docs/configuration/policy/route-map.rst index 792014bc..cc65d50c 100644 --- a/docs/configuration/policy/route-map.rst +++ b/docs/configuration/policy/route-map.rst @@ -69,16 +69,39 @@ Route Map IP address of route to match, based on prefix-list. +.. cfgcmd:: set policy route-map <text> rule <1-65535> match ip address + prefix-len <0-32> + + IP address of route to match, based on specified prefix-length. + Note that this can be used for kernel routes only. + Do not apply to the routes of dynamic routing protocols (e.g. BGP, + RIP, OSFP), as this can lead to unexpected results.. + .. cfgcmd:: set policy route-map <text> rule <1-65535> match ip nexthop access-list <1-2699> IP next-hop of route to match, based on access-list. .. cfgcmd:: set policy route-map <text> rule <1-65535> match ip nexthop + address <x.x.x.x> + + IP next-hop of route to match, based on ip address. + +.. cfgcmd:: set policy route-map <text> rule <1-65535> match ip nexthop + prefix-len <0-32> + + IP next-hop of route to match, based on prefix length. + +.. cfgcmd:: set policy route-map <text> rule <1-65535> match ip nexthop prefix-list <text> IP next-hop of route to match, based on prefix-list. +.. cfgcmd:: set policy route-map <text> rule <1-65535> match ip nexthop + type <blackhole> + + IP next-hop of route to match, based on type. + .. cfgcmd:: set policy route-map <text> rule <1-65535> match ip route-source access-list <1-2699> @@ -99,6 +122,14 @@ Route Map IPv6 address of route to match, based on IPv6 prefix-list. +.. cfgcmd:: set policy route-map <text> rule <1-65535> match ipv6 address + prefix-len <0-128> + + IPv6 address of route to match, based on specified prefix-length. + Note that this can be used for kernel routes only. + Do not apply to the routes of dynamic routing protocols (e.g. BGP, + RIP, OSFP), as this can lead to unexpected results.. + .. cfgcmd:: set policy route-map <text> rule <1-65535> match ipv6 nexthop <h:h:h:h:h:h:h:h> @@ -149,52 +180,82 @@ Route Map BGP aggregator attribute: AS number or IP address of an aggregation. -.. cfgcmd:: set policy route-map <text> rule <1-65535> set as-path-exclude +.. cfgcmd:: set policy route-map <text> rule <1-65535> set as-path exclude <text> - Remove ASN(s) from a BGP AS-path attribute. For example "456 64500 45001". + Drop AS-NUMBER from the BGP AS path. -.. cfgcmd:: set policy route-map <text> rule <1-65535> set as-path-prepend +.. cfgcmd:: set policy route-map <text> rule <1-65535> set as-path prepend <text> - Prepend string for a BGP AS-path attribute. For example "64501 64501". + Prepend the given string of AS numbers to the AS_PATH of the BGP path's NLRI. + +.. cfgcmd:: set policy route-map <text> rule <1-65535> set as-path + prepend-last-as <n> + + Prepend the existing last AS number (the leftmost ASN) to the AS_PATH. .. cfgcmd:: set policy route-map <text> rule <1-65535> set atomic-aggregate BGP atomic aggregate attribute. -.. cfgcmd:: set policy route-map <text> rule <1-65535> set bgp-extcommunity-rt - <aa:nn> +.. cfgcmd:: set policy route-map <text> rule <1-65535> set community + <add|replace> <community> - Set route target value. ExtCommunity in format: asn:value. + Add or replace BGP community attribute in format ``<0-65535:0-65535>`` + or from well-known community list -.. cfgcmd:: set policy route-map <text> rule <1-65535> set comm-list comm-list - <text> +.. cfgcmd:: set policy route-map <text> rule <1-65535> set community none - BGP communities with a community-list. + Delete all BGP communities -.. cfgcmd:: set policy route-map <text> rule <1-65535> set comm-list delete +.. cfgcmd:: set policy route-map <text> rule <1-65535> set community delete + <text> Delete BGP communities matching the community-list. -.. cfgcmd:: set policy route-map <text> rule <1-65535> set community - <aa:bb|local-AS|no-advertise|no-export|internet|additive|none> +.. cfgcmd:: set policy route-map <text> rule <1-65535> set large-community + <add|replace> <GA:LDP1:LDP2> - Set BGP community attribute. + Add or replace BGP large-community attribute in format + ``<0-4294967295:0-4294967295:0-4294967295>`` -.. cfgcmd:: set policy route-map <text> rule <1-65535> set distance <0-255> +.. cfgcmd:: set policy route-map <text> rule <1-65535> set large-community none + + Delete all BGP large-communities - Locally significant administrative distance. +.. cfgcmd:: set policy route-map <text> rule <1-65535> set large-community delete + <text> + + Delete BGP communities matching the large-community-list. + +.. cfgcmd:: set policy route-map <text> rule <1-65535> set extcommunity bandwidth + <1-25600|cumulative|num-multipaths> -.. cfgcmd:: set policy route-map <text> rule <1-65535> set extcommunity-rt + Set extcommunity bandwidth + +.. cfgcmd:: set policy route-map <text> rule <1-65535> set extcommunity bandwidth-non-transitive + + The link bandwidth extended community is encoded as non-transitive + +.. cfgcmd:: set policy route-map <text> rule <1-65535> set extcommunity rt <text> - Set route target value. + Set route target value in format ``<0-65535:0-4294967295>`` or ``<IP:0-65535>``. -.. cfgcmd:: set policy route-map <text> rule <1-65535> set extcommunity-soo +.. cfgcmd:: set policy route-map <text> rule <1-65535> set extcommunity soo <text> - Set site of origin value. + Set site of origin value in format ``<0-65535:0-4294967295>`` or ``<IP:0-65535>``. + +.. cfgcmd:: set policy route-map <text> rule <1-65535> set extcommunity none + + Clear all BGP extcommunities. + +.. cfgcmd:: set policy route-map <text> rule <1-65535> set distance <0-255> + + Locally significant administrative distance. + .. cfgcmd:: set policy route-map <text> rule <1-65535> set ip-next-hop <x.x.x.x> @@ -211,8 +272,8 @@ Route Map peer-address Set the BGP nexthop address to the address of the peer. For an incoming - route-map this means the ip address of our peer is used. For an - outgoing route-map this means the ip address of our self is used to + route-map this means the ip address of our peer is used. For an + outgoing route-map this means the ip address of our self is used to establish the peering with our neighbor. .. cfgcmd:: set policy route-map <text> rule <1-65535> set ipv6-next-hop @@ -224,21 +285,16 @@ Route Map peer-address Set the BGP nexthop address to the address of the peer. For an incoming - route-map this means the ip address of our peer is used. For an - outgoing route-map this means the ip address of our self is used to + route-map this means the ip address of our peer is used. For an + outgoing route-map this means the ip address of our self is used to establish the peering with our neighbor. - + .. cfgcmd:: set policy route-map <text> rule <1-65535> set ipv6-next-hop prefer-global - + For Incoming and Import Route-maps if we receive a v6 global and v6 LL address for the route, then prefer to use the global address as the nexthop. - -.. cfgcmd:: set policy route-map <text> rule <1-65535> set large-community - <text> - - Set BGP large community value. .. cfgcmd:: set policy route-map <text> rule <1-65535> set local-preference <0-4294967295> @@ -283,3 +339,29 @@ Route Map <0-4294967295> Set BGP weight attribute + +List of well-known communities +============================== + * ``local-as`` - Well-known communities value NO_EXPORT_SUBCONFED 0xFFFFFF03 + * ``no-advertise`` - Well-known communities value NO_ADVERTISE 0xFFFFFF02 + * ``no-export`` - Well-known communities value NO_EXPORT 0xFFFFFF01 + * ``internet`` - Well-known communities value 0 + * ``graceful-shutdown`` - Well-known communities value GRACEFUL_SHUTDOWN 0xFFFF0000 + * ``accept-own`` - Well-known communities value ACCEPT_OWN 0xFFFF0001 + * ``route-filter-translated-v4`` - Well-known communities value ROUTE_FILTER_TRANSLATED_v4 0xFFFF0002 + * ``route-filter-v4`` - Well-known communities value ROUTE_FILTER_v4 0xFFFF0003 + * ``route-filter-translated-v6`` - Well-known communities value ROUTE_FILTER_TRANSLATED_v6 0xFFFF0004 + * ``route-filter-v6`` - Well-known communities value ROUTE_FILTER_v6 0xFFFF0005 + * ``llgr-stale`` - Well-known communities value LLGR_STALE 0xFFFF0006 + * ``no-llgr`` - Well-known communities value NO_LLGR 0xFFFF0007 + * ``accept-own-nexthop`` - Well-known communities value accept-own-nexthop 0xFFFF0008 + * ``blackhole`` - Well-known communities value BLACKHOLE 0xFFFF029A + * ``no-peer`` - Well-known communities value NOPEER 0xFFFFFF04 + + + + + + + + diff --git a/docs/configuration/policy/route.rst b/docs/configuration/policy/route.rst index 0aa43232..a6330c57 100644 --- a/docs/configuration/policy/route.rst +++ b/docs/configuration/policy/route.rst @@ -1,43 +1,64 @@ -############ -Route Policy -############ +####################### +Route and Route6 Policy +####################### -Route and IPv6 route policies are defined in this section. This route policies -can then be associated to interfaces. +IPv4 route and IPv6 route policies are defined in this section. These route +policies can then be associated to interfaces. -************* -Configuration -************* +********* +Rule-Sets +********* -Route -===== - -.. cfgcmd:: set policy route <name> - - This command creates a new route policy, identified by <text>. +A rule-set is a named collection of rules that can be applied to an interface. +Each rule is numbered, has an action to apply if the rule is matched, and the +ability to specify the criteria to match. Data packets go through the rules +from 1 - 999999, at the first match the action of the rule will be executed. .. cfgcmd:: set policy route <name> description <text> +.. cfgcmd:: set policy route6 <name> description <text> - Set description for the route policy. + Provide a rule-set description. .. cfgcmd:: set policy route <name> enable-default-log +.. cfgcmd:: set policy route6 <name> enable-default-log Option to log packets hitting default-action. .. cfgcmd:: set policy route <name> rule <n> description <text> +.. cfgcmd:: set policy route6 <name> rule <n> description <text> - Set description for rule in route policy. + Provide a description for each rule. -.. cfgcmd:: set policy route <name> rule <n> action drop +.. cfgcmd:: set policy route <name> rule <n> log <enable|disable> +.. cfgcmd:: set policy route6 <name> rule <n> log <enable|disable> - Set rule action to drop. + Option to enable or disable log matching rule. + +Matching criteria +================= + +There are a lot of matching criteria options available, both for +``policy route`` and ``policy route6``. These options are listed +in this section. + +.. cfgcmd:: set policy route <name> rule <n> connection-mark <1-2147483647> +.. cfgcmd:: set policy route6 <name> rule <n> connection-mark <1-2147483647> + + Set match criteria based on connection mark. +.. cfgcmd:: set policy route <name> rule <n> source address + <match_criteria> .. cfgcmd:: set policy route <name> rule <n> destination address <match_criteria> +.. cfgcmd:: set policy route6 <name> rule <n> source address + <match_criteria> +.. cfgcmd:: set policy route6 <name> rule <n> destination address + <match_criteria> - Set match criteria based on destination address, where <match_criteria> - could be: + Set match criteria based on source or destination ipv4|ipv6 address, where + <match_criteria> could be: +For ipv4: * <x.x.x.x>: IP address to match. * <x.x.x.x/x>: Subnet to match. * <x.x.x.x>-<x.x.x.x>: IP range to match. @@ -45,14 +66,30 @@ Route * !<x.x.x.x/x>: Match everything except the specified subnet. * !<x.x.x.x>-<x.x.x.x>: Match everything except the specified range. +And for ipv6: + * <h:h:h:h:h:h:h:h>: IPv6 address to match. + * <h:h:h:h:h:h:h:h/x>: IPv6 prefix to match. + * <h:h:h:h:h:h:h:h>-<h:h:h:h:h:h:h:h>: IPv6 range to match. + * !<h:h:h:h:h:h:h:h>: Match everything except the specified address. + * !<h:h:h:h:h:h:h:h/x>: Match everything except the specified prefix. + * !<h:h:h:h:h:h:h:h>-<h:h:h:h:h:h:h:h>: Match everything except the + specified range. + +.. cfgcmd:: set policy route <name> rule <n> source group + <address-group|domain-group|mac-group|network-group|port-group> <text> .. cfgcmd:: set policy route <name> rule <n> destination group - <address-group|network-group|port-group> <text> + <address-group|domain-group|mac-group|network-group|port-group> <text> +.. cfgcmd:: set policy route6 <name> rule <n> source group + <address-group|domain-group|mac-group|network-group|port-group> <text> +.. cfgcmd:: set policy route6 <name> rule <n> destination group + <address-group|domain-group|mac-group|network-group|port-group> <text> - Set destination match criteria based on groups, where <text> would be the - group name/identifier. + Set match criteria based on source or destination groups, where <text> + would be the group name/identifier. Prepend character '!' for inverted + matching criteria. -.. cfgcmd:: set policy route <name> rule <n> destination port - <match_criteria> +.. cfgcmd:: set policy route <name> rule <n> destination port <match_criteria> +.. cfgcmd:: set policy route6 <name> rule <n> destination port <match_criteria> Set match criteria based on destination port, where <match_criteria> could be: @@ -66,24 +103,43 @@ Route '!22,telnet,http,123,1001-1005' .. cfgcmd:: set policy route <name> rule <n> disable +.. cfgcmd:: set policy route6 <name> rule <n> disable Option to disable rule. +.. cfgcmd:: set policy route <name> rule <n> dscp <text> +.. cfgcmd:: set policy route6 <name> rule <n> dscp <text> +.. cfgcmd:: set policy route <name> rule <n> dscp-exclude <text> +.. cfgcmd:: set policy route6 <name> rule <n> dscp-exclude <text> + + Match based on dscp value criteria. Multiple values from 0 to 63 + and ranges are supported. + .. cfgcmd:: set policy route <name> rule <n> fragment <match-grag|match-non-frag> +.. cfgcmd:: set policy route6 <name> rule <n> fragment + <match-grag|match-non-frag> Set IP fragment match, where: * match-frag: Second and further fragments of fragmented packets. * match-non-frag: Head fragments or unfragmented packets. -.. cfgcmd:: set policy route <name> rule <n> icmp <code|type|type-name> +.. cfgcmd:: set policy route <name> rule <n> icmp <code | type> +.. cfgcmd:: set policy route6 <name> rule <n> icmpv6 <code | type> - Set ICMP match criterias, based on code and/or types. Types could be - referenced by number or by name. + Match based on icmp|icmpv6 code and type. + +.. cfgcmd:: set policy route <name> rule <n> icmp type-name <text> +.. cfgcmd:: set policy route6 <name> rule <n> icmpv6 type-name <text> + + Match based on icmp|icmpv6 type-name criteria. Use tab for information + about what type-name criteria are supported. .. cfgcmd:: set policy route <name> rule <n> ipsec <match-ipsec|match-none> +.. cfgcmd:: set policy route6 <name> rule <n> ipsec + <match-ipsec|match-none> Set IPSec inbound match criterias, where: @@ -91,88 +147,45 @@ Route * match-none: match inbound non-IPsec packets. .. cfgcmd:: set policy route <name> rule <n> limit burst <0-4294967295> +.. cfgcmd:: set policy route6 <name> rule <n> limit burst <0-4294967295> - Set maximum number of packets to alow in excess of rate + Set maximum number of packets to alow in excess of rate. .. cfgcmd:: set policy route <name> rule <n> limit rate <text> +.. cfgcmd:: set policy route6 <name> rule <n> limit rate <text> Set maximum average matching rate. Format for rate: integer/time_unit, where time_unit could be any one of second, minute, hour or day.For example 1/second implies rule to be matched at an average of once per second. -.. cfgcmd:: set policy route <name> rule <n> log <enable|disable> - - Option to enable or disable log matching rule. - -.. cfgcmd:: set policy route <name> rule <n> log <text> - - Option to log matching rule. - .. cfgcmd:: set policy route <name> rule <n> protocol - <text|0-255|tcp_udp|all|!protocol> + <text | 0-255 | tcp_udp | all > +.. cfgcmd:: set policy route6 <name> rule <n> protocol + <text | 0-255 | tcp_udp | all > - Set protocol to match. Protocol name in /etc/protocols or protocol number, - or "tcp_udp" or "all". Also, protocol could be denied by using !. + Match a protocol criteria. A protocol number or a name which is defined in: + ``/etc/protocols``. Special names are ``all`` for all protocols and + ``tcp_udp`` for tcp and udp based packets. The ``!`` negates the selected + protocol. -.. cfgcmd:: set policy route <name> rule <n> recent <count|time> - <1-255|0-4294967295> +.. cfgcmd:: set policy route <name> rule <n> recent count <1-255> +.. cfgcmd:: set policy route6 <name> rule <n> recent count <1-255> +.. cfgcmd:: set policy route <name> rule <n> recent time <1-4294967295> +.. cfgcmd:: set policy route6 <name> rule <n> recent time <1-4294967295> Set parameters for matching recently seen sources. This match could be used by seeting count (source address seen more than <1-255> times) and/or time (source address seen in the last <0-4294967295> seconds). -.. cfgcmd:: set policy route <name> rule <n> set dscp <0-63> - - Set packet modifications: Packet Differentiated Services Codepoint (DSCP) - -.. cfgcmd:: set policy route <name> rule <n> set mark <1-2147483647> - - Set packet modifications: Packet marking - -.. cfgcmd:: set policy route <name> rule <n> set table <main|1-200> - - Set packet modifications: Routing table to forward packet with. - -.. cfgcmd:: set policy route <name> rule <n> set tcp-mss <500-1460> - - Set packet modifications: Explicitly set TCP Maximum segment size value. - -.. cfgcmd:: set policy route <name> rule <n> source address - <match_criteria> - - Set match criteria based on source address, where <match_criteria> could be: - - * <x.x.x.x>: IP address to match. - * <x.x.x.x/x>: Subnet to match. - * <x.x.x.x>-<x.x.x.x>: IP range to match. - * !<x.x.x.x>: Match everything except the specified address. - * !<x.x.x.x/x>: Match everything except the specified subnet. - * !<x.x.x.x>-<x.x.x.x>: Match everything except the specified range. - -.. cfgcmd:: set policy route <name> rule <n> source group - <address-group|network-group|port-group> <text> - - Set source match criteria based on groups, where <text> would be the group - name/identifier. - -.. cfgcmd:: set policy route <name> rule <n> source port <match_criteria> - - Set match criteria based on source port, where <match_criteria> could be: - - * <port name>: Named port (any name in /etc/services, e.g., http). - * <1-65535>: Numbered port. - * <start>-<end>: Numbered port range (e.g., 1001-1005). - - Multiple source ports can be specified as a comma-separated list. The whole - list can also be "negated" using '!'. For example: - '!22,telnet,http,123,1001-1005' - .. cfgcmd:: set policy route <name> rule <n> state - <established|invalid|new|related> <disable|enable> + <established | invalid | new | related> +.. cfgcmd:: set policy route6 <name> rule <n> state + <established | invalid | new | related> Set match criteria based on session state. .. cfgcmd:: set policy route <name> rule <n> tcp flags <text> +.. cfgcmd:: set policy route6 <name> rule <n> tcp flags <text> Set match criteria based on tcp flags. Allowed values for TCP flags: SYN ACK FIN RST URG PSH ALL. When specifying more than one flag, flags should be @@ -180,241 +193,67 @@ Route packets with the SYN flag set, and the ACK, FIN and RST flags unset. .. cfgcmd:: set policy route <name> rule <n> time monthdays <text> - - Set monthdays to match rule on. Format for monthdays: 2,12,21. - To negate add ! at the front eg. !2,12,21 - +.. cfgcmd:: set policy route6 <name> rule <n> time monthdays <text> .. cfgcmd:: set policy route <name> rule <n> time startdate <text> - - Set date to start matching rule. Format for date: yyyy-mm-dd. To specify - time of date with startdate, append 'T' to date followed by time in 24 hour - notation hh:mm:ss. For eg startdate value of 2009-01-21T13:30:00 refers to - 21st Jan 2009 with time 13:30:00. - +.. cfgcmd:: set policy route6 <name> rule <n> time startdate <text> .. cfgcmd:: set policy route <name> rule <n> time starttime <text> - - Set time of day to start matching rule. Format of time: hh:mm:ss using 24 - hours notation. - +.. cfgcmd:: set policy route6 <name> rule <n> time starttime <text> .. cfgcmd:: set policy route <name> rule <n> time stopdate <text> - - Set date to stop matching rule. Format for date: yyyy-mm-dd. To specify time - of date with stopdate, append 'T' to date followed by time in 24 hour - notation hh:mm:ss. For eg startdate value of 2009-01-21T13:30:00 refers to - 21st Jan 2009 with time 13:30:00. - +.. cfgcmd:: set policy route6 <name> rule <n> time stopdate <text> .. cfgcmd:: set policy route <name> rule <n> time stoptime <text> - - Set time of day to stop matching rule. Format of time: hh:mm:ss using 24 - hours notation. - +.. cfgcmd:: set policy route6 <name> rule <n> time stoptime <text> +.. cfgcmd:: set policy route <name> rule <n> time weekdays <text> +.. cfgcmd:: set policy route6 <name> rule <n> time weekdays <text> .. cfgcmd:: set policy route <name> rule <n> time utc +.. cfgcmd:: set policy route6 <name> rule <n> time utc - Interpret times for startdate, stopdate, starttime and stoptime to be UTC. - -.. cfgcmd:: set policy route <name> rule <n> time weekdays - - Weekdays to match rule on. Format for weekdays: Mon,Thu,Sat. To negate add ! - at the front eg. !Mon,Thu,Sat. + Time to match the defined rule. +.. cfgcmd:: set policy route rule <n> ttl <eq | gt | lt> <0-255> -IPv6 Route -========== + Match time to live parameter, where 'eq' stands for 'equal'; 'gt' stands for + 'greater than', and 'lt' stands for 'less than'. -.. cfgcmd:: set policy route6 <name> +.. cfgcmd:: set policy route6 rule <n> hop-limit <eq | gt | lt> <0-255> - This command creates a new IPv6 route policy, identified by <text>. + Match hop-limit parameter, where 'eq' stands for 'equal'; 'gt' stands for + 'greater than', and 'lt' stands for 'less than'. -.. cfgcmd:: set policy route6 <name> description <text> +Actions +======= - Set description for the IPv6 route policy. - -.. cfgcmd:: set policy route6 <name> enable-default-log - - Option to log packets hitting default-action. +When mathcing all patterns defined in a rule, then different actions can +be made. This includes droping the packet, modifying certain data, or +setting a different routing table. +.. cfgcmd:: set policy route <name> rule <n> action drop .. cfgcmd:: set policy route6 <name> rule <n> action drop Set rule action to drop. -.. cfgcmd:: set policy route6 <name> rule <n> description <text> - - Set description for rule in IPv6 route policy. +.. cfgcmd:: set policy route <name> rule <n> set connection-mark + <1-2147483647> +.. cfgcmd:: set policy route6 <name> rule <n> set connection-mark + <1-2147483647> -.. cfgcmd:: set policy route6 <name> rule <n> destination address - <match_criteria> - - Set match criteria based on destination IPv6 address, where <match_criteria> - could be: - - * <h:h:h:h:h:h:h:h>: IPv6 address to match. - * <h:h:h:h:h:h:h:h/x>: IPv6 prefix to match. - * <h:h:h:h:h:h:h:h>-<h:h:h:h:h:h:h:h>: IPv6 range to match. - * !<h:h:h:h:h:h:h:h>: Match everything except the specified address. - * !<h:h:h:h:h:h:h:h/x>: Match everything except the specified prefix. - * !<h:h:h:h:h:h:h:h>-<h:h:h:h:h:h:h:h>: Match everything except the - specified range. - -.. cfgcmd:: set policy route6 <name> rule <n> destination port <match_criteria> - - Set match criteria based on destination port, where <match_criteria> could - be: - - * <port name>: Named port (any name in /etc/services, e.g., http). - * <1-65535>: Numbered port. - * <start>-<end>: Numbered port range (e.g., 1001-1005). - - Multiple destination ports can be specified as a comma-separated list. The - whole list can also be "negated" using '!'. For example: - '!22,telnet,http,123,1001-1005'. - -.. cfgcmd:: set policy route6 <name> rule <n> disable - - Option to disable rule. - -.. cfgcmd:: set policy route6 <name> rule <n> icmpv6 type <icmpv6_typ> - - Set ICMPv6 match criterias, based on ICMPv6 type/code name. - -.. cfgcmd:: set policy route6 <name> rule <n> ipsec - <match-ipsec|match-none> - - Set IPSec inbound match criterias, where: - - * match-ipsec: match inbound IPsec packets. - * match-none: match inbound non-IPsec packets. - -.. cfgcmd:: set policy route6 <name> rule <n> limit burst - <0-4294967295> - - Set maximum number of packets to alow in excess of rate - -.. cfgcmd:: set policy route6 <name> rule <n> limit rate <text> - - Set maximum average matching rate. Format for rate: integer/time_unit, where - time_unit could be any one of second, minute, hour or day.For example - 1/second implies rule to be matched at an average of once per second. - -.. cfgcmd:: set policy route6 <name> rule <n> log <enable|disable> - - Option to enable or disable log matching rule. - -.. cfgcmd:: set policy route6 <name> rule <n> log <text> - - Option to log matching rule. - -.. cfgcmd:: set policy route6 <name> rule <n> protocol - <text|0-255|tcp_udp|all|!protocol> - - Set IPv6 protocol to match. IPv6 protocol name from /etc/protocols or - protocol number, or "tcp_udp" or "all". Also, protocol could be denied by - using !. - -.. cfgcmd:: set policy route6 <name> rule <n> recent <count|time> - <1-255|0-4294967295> - - Set parameters for matching recently seen sources. This match could be used - by seeting count (source address seen more than <1-255> times) and/or time - (source address seen in the last <0-4294967295> seconds). + Set a specific connection mark. +.. cfgcmd:: set policy route <name> rule <n> set dscp <0-63> .. cfgcmd:: set policy route6 <name> rule <n> set dscp <0-63> Set packet modifications: Packet Differentiated Services Codepoint (DSCP) +.. cfgcmd:: set policy route <name> rule <n> set mark <1-2147483647> .. cfgcmd:: set policy route6 <name> rule <n> set mark <1-2147483647> - Set packet modifications: Packet marking. - -.. cfgcmd:: set policy route6 <name> rule <n> set table <main|1-200> - - Set packet modifications: Routing table to forward packet with. - -.. cfgcmd:: set policy route6 <name> rule <n> set tcp-mss - <pmtu|500-1460> - - Set packet modifications: pmtu option automatically set to Path Maximum - Transfer Unit minus 60 bytes. Otherwise, expliicitly set TCP MSS value from - 500 to 1460. - -.. cfgcmd:: set policy route6 <name> rule <n> source address - <match_criteria> - - Set match criteria based on IPv6 source address, where <match_criteria> - could be: - - * <h:h:h:h:h:h:h:h>: IPv6 address to match - * <h:h:h:h:h:h:h:h/x>: IPv6 prefix to match - * <h:h:h:h:h:h:h:h>-<h:h:h:h:h:h:h:h>: IPv6 range to match - * !<h:h:h:h:h:h:h:h>: Match everything except the specified address - * !<h:h:h:h:h:h:h:h/x>: Match everything except the specified prefix - * !<h:h:h:h:h:h:h:h>-<h:h:h:h:h:h:h:h>: Match everything except the - specified range - -.. cfgcmd:: set policy route6 <name> rule <n> source mac-address - <MAC_address|!MAC_address> - - Set source match criteria based on MAC address. Declare specific MAC address - to match, or match everything except the specified MAC. - -.. cfgcmd:: set policy route6 <name> rule <n> source port - <match_criteria> - - Set match criteria based on source port, where <match_criteria> could be: - - * <port name>: Named port (any name in /etc/services, e.g., http). - * <1-65535>: Numbered port. - * <start>-<end>: Numbered port range (e.g., 1001-1005). - - Multiple source ports can be specified as a comma-separated list. The whole - list can also be "negated" using '!'. For example: - '!22,telnet,http,123,1001-1005'. - -.. cfgcmd:: set policy route6 <name> rule <n> state - <established|invalid|new|related> <disable|enable> - - Set match criteria based on session state. - -.. cfgcmd:: set policy route6 <name> rule <n> tcp flags <text> - - Set match criteria based on tcp flags. Allowed values for TCP flags: SYN ACK - FIN RST URG PSH ALL. When specifying more than one flag, flags should be - comma-separated. For example : value of 'SYN,!ACK,!FIN,!RST' will only match - packets with the SYN flag set, and the ACK, FIN and RST flags unset. + Set a specific packet mark. -.. cfgcmd:: set policy route6 <name> rule <n> time monthdays <text> - - Set monthdays to match rule on. Format for monthdays: 2,12,21. - To negate add ! at the front eg. !2,12,21 - -.. cfgcmd:: set policy route6 <name> rule <n> time startdate <text> +.. cfgcmd:: set policy route <name> rule <n> set table <main | 1-200> +.. cfgcmd:: set policy route6 <name> rule <n> set table <main | 1-200> - Set date to start matching rule. Format for date: yyyy-mm-dd. To specify - time of date with startdate, append 'T' to date followed by time in 24 hour - notation hh:mm:ss. For eg startdate value of 2009-01-21T13:30:00 refers to - 21st Jan 2009 with time 13:30:00. + Set the routing table to forward packet with. -.. cfgcmd:: set policy route6 <name> rule <n> time starttime <text> - - Set time of day to start matching rule. Format of time: hh:mm:ss using 24 - hours notation. - -.. cfgcmd:: set policy route6 <name> rule <n> time stopdate <text> - - Set date to stop matching rule. Format for date: yyyy-mm-dd. To specify time - of date with stopdate, append 'T' to date followed by time in 24 hour - notation hh:mm:ss. For eg startdate value of 2009-01-21T13:30:00 refers to - 21st Jan 2009 with time 13:30:00. - -.. cfgcmd:: set policy route6 <name> rule <n> time stoptime <text> - - Set time of day to stop matching rule. Format of time: hh:mm:ss using 24 - hours notation. - -.. cfgcmd:: set policy route6 <name> rule <n> time utc - - Interpret times for startdate, stopdate, starttime and stoptime to be UTC. - -.. cfgcmd:: set policy route6 <name> rule <n> time weekdays +.. cfgcmd:: set policy route <name> rule <n> set tcp-mss <500-1460> +.. cfgcmd:: set policy route6 <name> rule <n> set tcp-mss <500-1460> - Weekdays to match rule on. Format for weekdays: Mon,Thu,Sat. To negate add ! - at the front eg. !Mon,Thu,Sat. + Set packet modifications: Explicitly set TCP Maximum segment size value.
\ No newline at end of file diff --git a/docs/configuration/protocols/bfd.rst b/docs/configuration/protocols/bfd.rst index dac1bf0f..faec71bc 100644 --- a/docs/configuration/protocols/bfd.rst +++ b/docs/configuration/protocols/bfd.rst @@ -1,4 +1,4 @@ -:lastproofread: 2022-02-05 +:lastproofread: 2023-01-27 .. include:: /_include/need_improvement.txt diff --git a/docs/configuration/protocols/bgp.rst b/docs/configuration/protocols/bgp.rst index 24d81cef..6593730f 100644 --- a/docs/configuration/protocols/bgp.rst +++ b/docs/configuration/protocols/bgp.rst @@ -37,7 +37,7 @@ The :abbr:`ASN (Autonomous System Number)` is one of the essential elements of BGP. BGP is a distance vector routing protocol, and the AS-Path framework provides distance vector metric and loop detection to BGP. -.. cfgcmd:: set protocols bgp local-as <asn> +.. cfgcmd:: set protocols bgp system-as <asn> Set local :abbr:`ASN (Autonomous System Number)` that this router represents. This is a a mandatory option! @@ -174,10 +174,10 @@ The BGP protocol uses the AS number for detecting whether the BGP connection is internal or external. VyOS does not have a special command to start the BGP process. The BGP process starts when the first neighbor is configured. -.. cfgcmd:: set protocols bgp local-as <asn> +.. cfgcmd:: set protocols bgp system-as <asn> Set local autonomous system number that this router represents. This is a - a mandatory option! + mandatory option! Peers Configuration ------------------- @@ -431,7 +431,7 @@ Peer Parameters This command enforces Generalized TTL Security Mechanism (GTSM), as specified in :rfc:`5082`. With this command, only neighbors - that are the specified number of hops away will be allowed to + that are specified number of hops away will be allowed to become neighbors. The number of hops range is 1 to 254. This command is mutually exclusive with :cfgcmd:`ebgp-multihop`. @@ -563,11 +563,6 @@ Common parameters Path (both AS number and AS path length), Origin code, MED, IGP metric. Also, the next hop address for each path must be different. -.. cfgcmd:: set protocols bgp parameters default no-ipv4-unicast - - This command allows the user to specify that IPv4 peering is turned off by - default. - .. cfgcmd:: set protocols bgp parameters log-neighbor-changes This command enable logging neighbor up/down changes and reset reason. @@ -984,7 +979,7 @@ Show .. opcmd:: show ip bgp filter-list <name> - This command displays BGP routes allowed by by the specified AS Path + This command displays BGP routes allowed by the specified AS Path access list. .. opcmd:: show <ip|ipv6> bgp neighbors <address> advertised-routes @@ -1074,7 +1069,7 @@ A simple eBGP configuration: .. code-block:: none - set protocols bgp local-as 65534 + set protocols bgp system-as 65534 set protocols bgp neighbor 192.168.0.2 ebgp-multihop '2' set protocols bgp neighbor 192.168.0.2 remote-as '65535' set protocols bgp neighbor 192.168.0.2 update-source '192.168.0.1' @@ -1085,7 +1080,7 @@ A simple eBGP configuration: .. code-block:: none - set protocols bgp local-as 65535 + set protocols bgp system-as 65535 set protocols bgp neighbor 192.168.0.1 ebgp-multihop '2' set protocols bgp neighbor 192.168.0.1 remote-as '65534' set protocols bgp neighbor 192.168.0.1 update-source '192.168.0.2' @@ -1119,7 +1114,7 @@ A simple BGP configuration via IPv6. .. code-block:: none - set protocols bgp local-as 65534 + set protocols bgp system-as 65534 set protocols bgp neighbor 2001:db8::2 ebgp-multihop '2' set protocols bgp neighbor 2001:db8::2 remote-as '65535' set protocols bgp neighbor 2001:db8::2 update-source '2001:db8::1' @@ -1131,7 +1126,7 @@ A simple BGP configuration via IPv6. .. code-block:: none - set protocols bgp local-as 65535 + set protocols bgp system-as 65535 set protocols bgp neighbor 2001:db8::1 ebgp-multihop '2' set protocols bgp neighbor 2001:db8::1 remote-as '65534' set protocols bgp neighbor 2001:db8::1 update-source '2001:db8::2' @@ -1182,7 +1177,7 @@ Route filter can be applied using a route-map: set policy route-map AS65535-OUT rule 10 match ipv6 address prefix-list 'AS65535-OUT' set policy route-map AS65535-OUT rule 20 action 'permit' - set protocols bgp local-as 65534 + set protocols bgp system-as 65534 set protocols bgp neighbor 2001:db8::2 address-family ipv4-unicast route-map export 'AS65535-OUT' set protocols bgp neighbor 2001:db8::2 address-family ipv4-unicast route-map import 'AS65535-IN' set protocols bgp neighbor 2001:db8::2 address-family ipv6-unicast route-map export 'AS65535-OUT' @@ -1210,7 +1205,7 @@ Route filter can be applied using a route-map: set policy route-map AS65534-OUT rule 10 match ipv6 address prefix-list 'AS65534-OUT' set policy route-map AS65534-OUT rule 20 action 'permit' - set protocols bgp local-as 65535 + set protocols bgp system-as 65535 set protocols bgp neighbor 2001:db8::1 address-family ipv4-unicast route-map export 'AS65534-OUT' set protocols bgp neighbor 2001:db8::1 address-family ipv4-unicast route-map import 'AS65534-IN' set protocols bgp neighbor 2001:db8::1 address-family ipv6-unicast route-map export 'AS65534-OUT' diff --git a/docs/configuration/protocols/failover.rst b/docs/configuration/protocols/failover.rst new file mode 100644 index 00000000..72201ade --- /dev/null +++ b/docs/configuration/protocols/failover.rst @@ -0,0 +1,103 @@ +.. _routing-static: + +######## +Failover +######## + +Failover routes are manually configured routes, but they install +to the routing table if the health-check target is alive. +If the target is not alive the route is removed from the routing table +until the target will be available. + +*************** +Failover Routes +*************** + +.. cfgcmd:: set protocols failover route <subnet> next-hop <address> check + target <target-address> + + Configure next-hop `<address>` and `<target-address>` for an IPv4 static + route. Specify the target + IPv4 address for health checking. + +.. cfgcmd:: set protocols failover route <subnet> next-hop <address> check + timeout <timeout> + + Timeout in seconds between health target checks. + + Range is 1 to 300, default is 10. + +.. cfgcmd:: set protocols failover route <subnet> next-hop <address> check + type <protocol> + + Defines protocols for checking ARP, ICMP, TCP + + Default is ``icmp``. + +.. cfgcmd:: set protocols failover route <subnet> next-hop <address> + interface <interface> + + Next-hop interface for the route + +.. cfgcmd:: set protocols failover route <subnet> next-hop <address> + metric <metric> + + Route metric + + Default 1. + + +******* +Example +******* + +**One gateway:** + +.. code-block:: none + + set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 check target '192.0.2.1' + set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 check timeout '5' + set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 check type 'icmp' + set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 interface 'eth0' + set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 metric '10' + +Show the route + +.. code-block:: none + + vyos@vyos:~$ show ip route 203.0.113.1 + Routing entry for 203.0.113.1/32 + Known via "kernel", distance 0, metric 10, best + Last update 00:00:39 ago + * 192.0.2.1, via eth0 + +**Two gateways and different metrics:** + +.. code-block:: none + + set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 check target '192.0.2.1' + set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 check timeout '5' + set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 check type 'icmp' + set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 interface 'eth0' + set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 metric '10' + + set protocols failover route 203.0.113.1/32 next-hop 198.51.100.1 check target '198.51.100.99' + set protocols failover route 203.0.113.1/32 next-hop 198.51.100.1 check timeout '5' + set protocols failover route 203.0.113.1/32 next-hop 198.51.100.1 check type 'icmp' + set protocols failover route 203.0.113.1/32 next-hop 198.51.100.1 interface 'eth2' + set protocols failover route 203.0.113.1/32 next-hop 198.51.100.1 metric '20' + +Show the route + +.. code-block:: none + + vyos@vyos:~$ show ip route 203.0.113.1 + Routing entry for 203.0.113.1/32 + Known via "kernel", distance 0, metric 10, best + Last update 00:08:06 ago + * 192.0.2.1, via eth0 + + Routing entry for 203.0.113.1/32 + Known via "kernel", distance 0, metric 20 + Last update 00:08:14 ago + * 198.51.100.1, via eth2 diff --git a/docs/configuration/protocols/igmp.rst b/docs/configuration/protocols/igmp.rst index 0c7a470b..d3492632 100644 --- a/docs/configuration/protocols/igmp.rst +++ b/docs/configuration/protocols/igmp.rst @@ -1,4 +1,4 @@ -:lastproofread: 2021-09-30 +:lastproofread: 2023-01-27 .. _multicast: diff --git a/docs/configuration/protocols/index.rst b/docs/configuration/protocols/index.rst index c302d6a9..b7fc6289 100644 --- a/docs/configuration/protocols/index.rst +++ b/docs/configuration/protocols/index.rst @@ -9,6 +9,7 @@ Protocols bfd bgp + failover igmp isis mpls diff --git a/docs/configuration/protocols/isis.rst b/docs/configuration/protocols/isis.rst index 416a42c3..ef9cc960 100644 --- a/docs/configuration/protocols/isis.rst +++ b/docs/configuration/protocols/isis.rst @@ -7,14 +7,18 @@ IS-IS ##### :abbr:`IS-IS (Intermediate System to Intermediate System)` is a link-state -interior gateway routing protocol which is described in ISO10589, -:rfc:`1195`, :rfc:`5308`. Like OSPF, IS-IS runs the Dijkstra shortest-path -first (SPF) algorithm to create a database of the network’s topology and, -from that database, to determine the best (that is, shortest) path to a -destination. The routers exchange topology information with their nearest -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. +interior gateway protocol (IGP) which is described in ISO10589, +:rfc:`1195`, :rfc:`5308`. IS-IS runs the Dijkstra shortest-path first (SPF) +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 +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 +similar to the one that is created with OSPF in that the paths chosen should +be similar. Comparisons to OSPF are inevitable and often are reasonable ones +to make in regards to the way a network will respond with either IGP. ******* General @@ -26,60 +30,76 @@ Configuration Mandatory Settings ------------------ +For IS-IS top operate correctly, one must do the equivalent of a Router ID in +CLNS. This Router ID is called the :abbr:`NET (Network Entity Title)`. This +must be unique for each and every router that is operating in IS-IS. It also +must not be duplicated otherwise the same issues that occur within OSPF will +occur within IS-IS when it comes to said duplication. + + .. cfgcmd:: set protocols isis net <network-entity-title> - This commad also sets network entity title (NET) provided in ISO format. + This commad sets network entity title (NET) provided in ISO format. - For example :abbr:`NET (Network Entity Title)` + Here is an example :abbr:`NET (Network Entity Title)` value: .. code-block:: none 49.0001.1921.6800.1002.00 - The IS-IS address consists of the following parts: + The CLNS address consists of the following parts: * :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 (Area1) + * Area identifier: ``0001`` IS-IS area number (numberical area ``1``) * System identifier: ``1921.6800.1002`` - for system idetifiers we recommend - to use IP address or MAC address of the router itself. + 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 + address that is listed here is ``192.168.1.2``, which if expanded will turn + into ``192.168.001.002``. Then all one has to do is move the dots to have + four numbers instead of three. This gives us ``1921.6800.1002``. - * NET selector: ``00`` Must always be 00, to indicate "this system". + * :abbr:`NET (Network Entity Title)` selector: ``00`` Must always be 00. This + setting indicates "this system" or "local system." .. cfgcmd:: set protocols isis interface <interface> - This command activates ISIS adjacency on this interface. Note that the name - of ISIS instance must be the same as the one used to configure the ISIS - process. + This command enables IS-IS on this interface, and allows for + adjacency to occur. Note that the name of IS-IS instance must be + the same as the one used to configure the IS-IS process. + +IS-IS Global Configuration +-------------------------- .. cfgcmd:: set protocols isis dynamic-hostname - This command enables support for dynamic hostname. Dynamic hostname mapping - determined as described in :rfc:`2763`, Dynamic Hostname Exchange Mechanism - for IS-IS. + This command enables support for dynamic hostname TLV. Dynamic hostname + mapping determined as described in :rfc:`2763`, Dynamic Hostname + Exchange Mechanism for IS-IS. .. cfgcmd:: set protocols isis level <level-1|level-1-2|level-2> - This command defines the ISIS router behavior: + This command defines the IS-IS router behavior: - **level-1** Act as a station router only. - **level-1-2** Act as both a station router and an area router. - **level-2-only** Act as an area router only. + * **level-1** - Act as a station (Level 1) router only. + * **level-1-2** - Act as a station (Level 1) router and area (Level 2) router. + * **level-2-only** - Act as an area (Level 2) router only. .. cfgcmd:: set protocols isis lsp-mtu <size> - This command configures the maximum size of generated LSPs, in bytes. The - size range is 128 to 4352. + This command configures the maximum size of generated + :abbr:`LSPs (Link State PDUs)`, in bytes. The size range is 128 to 4352. .. cfgcmd:: set protocols isis metric-style <narrow|transition|wide> - This command sets old-style (ISO 10589) or new-style packet formats: + This command sets old-style (ISO 10589) or new style packet formats: - **narrow** Use old style of TLVs with narrow metric. - **transition** Send and accept both styles of TLVs during transition. - **wide** Use new style of TLVs to carry wider metric. + * **narrow** - Use old style of TLVs with narrow metric. + * **transition** - Send and accept both styles of TLVs during transition. + * **wide** - Use new style of TLVs to carry wider metric. .. cfgcmd:: set protocols isis purge-originator @@ -117,9 +137,9 @@ Interface Configuration This command specifies circuit type for interface: - * **level-1** Level-1 only adjacencies are formed. - * **level-1-2** Level-1-2 adjacencies are formed - * **level-2-only** Level-2 only adjacencies are formed + * **level-1** - Level-1 only adjacencies are formed. + * **level-1-2** - Level-1-2 adjacencies are formed + * **level-2-only** - Level-2 only adjacencies are formed .. cfgcmd:: set protocols isis interface <interface> hello-interval <seconds> @@ -261,12 +281,87 @@ Timers to IGP events. The process described in :rfc:`8405`. -******* -Example -******* +******** +Examples +******** + +Enable IS-IS +============ + +**Node 1:** + +.. code-block:: none + + set interfaces loopback lo address '192.168.255.255/32' + set interfaces ethernet eth1 address '192.0.2.1/24' + + set protocols isis interface eth1 + set protocols isis interface lo + set protocols isis net '49.0001.1921.6825.5255.00' + +**Node 2:** + +.. code-block:: none + + set interfaces ethernet eth1 address '192.0.2.2/24' + + set interfaces loopback lo address '192.168.255.254/32' + set interfaces ethernet eth1 address '192.0.2.2/24' + + set protocols isis interface eth1 + set protocols isis interface lo + set protocols isis net '49.0001.1921.6825.5254.00' + + + +This gives us the following neighborships, Level 1 and Level 2: + +.. code-block:: none + + Node-1@vyos:~$ show isis neighbor + Area VyOS: + System Id Interface L State Holdtime SNPA + vyos eth1 1 Up 28 0c87.6c09.0001 + vyos eth1 2 Up 28 0c87.6c09.0001 + + Node-2@vyos:~$ show isis neighbor + Area VyOS: + System Id Interface L State Holdtime SNPA + vyos eth1 1 Up 29 0c33.0280.0001 + vyos eth1 2 Up 28 0c33.0280.0001 + + + +Here's the IP routes that are populated. Just the loopback: + +.. code-block:: none + + Node-1@vyos:~$ show ip route isis + Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, + f - OpenFabric, + > - selected route, * - FIB route, q - queued, r - rejected, b - backup + t - trapped, o - offload failure + + I 192.0.2.0/24 [115/20] via 192.0.2.2, eth1 inactive, weight 1, 00:02:22 + I>* 192.168.255.254/32 [115/20] via 192.0.2.2, eth1, weight 1, 00:02:22 + + Node-2@vyos:~$ show ip route isis + Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, + f - OpenFabric, + > - selected route, * - FIB route, q - queued, r - rejected, b - backup + t - trapped, o - offload failure -Simple IS-IS configuration using 2 nodes and redistributing connected -interfaces. + I 192.0.2.0/24 [115/20] via 192.0.2.1, eth1 inactive, weight 1, 00:02:21 + I>* 192.168.255.255/32 [115/20] via 192.0.2.1, eth1, weight 1, 00:02:21 + + + +Enable IS-IS and redistribute routes not natively in IS-IS +========================================================== **Node 1:** @@ -293,11 +388,11 @@ interfaces. set protocols isis interface eth1 set protocols isis net '49.0001.1921.6800.2002.00' -Show ip routes on Node2: +Routes on Node 2: .. code-block:: none - vyos@r2:~$ show ip route isis + Node-2@r2:~$ show ip route isis Codes: K - kernel route, C - connected, S - static, R - RIP, O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, T - Table, v - VNC, V - VNC-Direct, A - Babel, D - SHARP, @@ -305,3 +400,91 @@ Show ip routes on Node2: > - selected route, * - FIB route, q - queued route, r - rejected route I 203.0.113.0/24 [115/10] via 192.0.2.1, eth1, 00:03:42 + + + + +Enable IS-IS with Segment Routing (Experimental) +================================================ + +**Node 1:** + +.. code-block:: none + + set interfaces loopback lo address '192.168.255.255/32' + set interfaces ethernet eth1 address '192.0.2.1/24' + + set protocols isis interface eth1 + set protocols isis interface lo + set protocols isis net '49.0001.1921.6825.5255.00' + set protocols isis segment-routing global-block high-label-value '599' + set protocols isis segment-routing global-block low-label-value '550' + set protocols isis segment-routing prefix 192.168.255.255/32 index value '1' + set protocols isis segment-routing prefix 192.168.255.255/32 index explicit-null + set protocols mpls interface 'eth1' + +**Node 2:** + +.. code-block:: none + + set interfaces loopback lo address '192.168.255.254/32' + set interfaces ethernet eth1 address '192.0.2.2/24' + + set protocols isis interface eth1 + set protocols isis interface lo + set protocols isis net '49.0001.1921.6825.5254.00' + set protocols isis segment-routing global-block high-label-value '599' + set protocols isis segment-routing global-block low-label-value '550' + set protocols isis segment-routing prefix 192.168.255.254/32 index value '2' + set protocols isis segment-routing prefix 192.168.255.254/32 index explicit-null + set protocols mpls interface 'eth1' + + + +This gives us MPLS segment routing enabled and labels for far end loopbacks: + +.. code-block:: none + + Node-1@vyos:~$ show mpls table + Inbound Label Type Nexthop Outbound Label + ---------------------------------------------------------------------- + 552 SR (IS-IS) 192.0.2.2 IPv4 Explicit Null <-- Node-2 loopback learned on Node-1 + 15000 SR (IS-IS) 192.0.2.2 implicit-null + 15001 SR (IS-IS) fe80::e87:6cff:fe09:1 implicit-null + 15002 SR (IS-IS) 192.0.2.2 implicit-null + 15003 SR (IS-IS) fe80::e87:6cff:fe09:1 implicit-null + + Node-2@vyos:~$ show mpls table + Inbound Label Type Nexthop Outbound Label + --------------------------------------------------------------------- + 551 SR (IS-IS) 192.0.2.1 IPv4 Explicit Null <-- Node-1 loopback learned on Node-2 + 15000 SR (IS-IS) 192.0.2.1 implicit-null + 15001 SR (IS-IS) fe80::e33:2ff:fe80:1 implicit-null + 15002 SR (IS-IS) 192.0.2.1 implicit-null + 15003 SR (IS-IS) fe80::e33:2ff:fe80:1 implicit-null + +Here is the routing tables showing the MPLS segment routing label operations: + +.. code-block:: none + + Node-1@vyos:~$ show ip route isis + Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, + f - OpenFabric, + > - selected route, * - FIB route, q - queued, r - rejected, b - backup + t - trapped, o - offload failure + + I 192.0.2.0/24 [115/20] via 192.0.2.2, eth1 inactive, weight 1, 00:07:48 + I>* 192.168.255.254/32 [115/20] via 192.0.2.2, eth1, label IPv4 Explicit Null, weight 1, 00:03:39 + + Node-2@vyos:~$ show ip route isis + Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, + f - OpenFabric, + > - selected route, * - FIB route, q - queued, r - rejected, b - backup + t - trapped, o - offload failure + + I 192.0.2.0/24 [115/20] via 192.0.2.1, eth1 inactive, weight 1, 00:07:46 + I>* 192.168.255.255/32 [115/20] via 192.0.2.1, eth1, label IPv4 Explicit Null, weight 1, 00:03:43 diff --git a/docs/configuration/protocols/mpls.rst b/docs/configuration/protocols/mpls.rst index d1d0cd87..550473d7 100644 --- a/docs/configuration/protocols/mpls.rst +++ b/docs/configuration/protocols/mpls.rst @@ -27,12 +27,14 @@ network transport of data packets. For more information on how MPLS label switching works, please go visit `Wikipedia (MPLS)`_. -.. note:: MPLS support in VyOS is not finished yet, and therefore its - functionality is limited. Currently there is no support for MPLS enabled VPN - services such as L3VPNs, L2VPNs, and mVPNs. RSVP support is also not present - as the underlying routing stack (FRR) does not implement it. Currently VyOS - can be configured as a label switched router (MPLS P router), in both - penultimate and ultimate hop popping operations. +.. note:: MPLS support in VyOS is not finished yet, and therefore its + functionality is limited. Currently there is no support for MPLS enabled VPN + services such as L2VPNs and mVPNs. RSVP support is also not present as the + underlying routing stack (FRR) does not implement it. Currently VyOS + implements LDP as described in RFC 5036; other LDP standard are the + following ones: RFC 6720, RFC 6667, RFC 5919, RFC 5561, RFC 7552, RFC 4447. + Because MPLS is already available (FRR also supports RFC 3031). + Label Distribution Protocol =========================== diff --git a/docs/configuration/protocols/ospf.rst b/docs/configuration/protocols/ospf.rst index e3f9759e..60f9c149 100644 --- a/docs/configuration/protocols/ospf.rst +++ b/docs/configuration/protocols/ospf.rst @@ -43,7 +43,8 @@ starts when the first ospf enabled interface is configured. enable ospf on interface with address 192.168.1.1/23, but it does on interface with address 192.168.1.129/25. - In some cases it may be more convenient to enable OSPF on a per interface/subnet + In some cases it may be more convenient to enable OSPF on a per + interface/subnet basis :cfgcmd:`set protocols ospf interface <interface> area <x.x.x.x | x>` .. cfgcmd:: set protocols ospf auto-cost reference-bandwidth <number> @@ -733,11 +734,85 @@ the "<metric of the router which advertised the link>/<link metric>" format. This command displays LSAs in MaxAge list. -Configuration Example ---------------------- +Examples +-------- -Below you can see a typical configuration using 2 nodes, redistribute loopback -address and the node 1 sending the default route: + +Enable OSPF +^^^^^^^^^^^ + +**Node 1** + +.. code-block:: none + + set interfaces loopback lo address 10.1.1.1/32 + set interfaces ethernet eth0 address 192.168.0.1/24 + set protocols ospf area 0 network 192.168.0.0/24 + set protocols ospf area 0 network 10.1.1.1/32 + set protocols ospf parameters router-id 10.1.1.1 + +**Node 2** + +.. code-block:: none + + set interfaces loopback lo address 10.1.1.2/32 + set interfaces ethernet eth0 address 192.168.0.2/24 + set protocols ospf area 0 network 192.168.0.0/24 + set protocols ospf area 0 network 10.1.1.2/32 + set protocols ospf parameters router-id 10.1.1.2 + + + +Here's the neighbors up: + +.. code-block:: none + + Node-1@vyos:~$ show ip ospf neighbor + + Neighbor ID Pri State Up Time Dead Time Address Interface RXmtL RqstL DBsmL + 10.1.1.2 1 Full/DR 3m43s 36.094s 192.168.0.2 eth0:192.168.0.1 0 0 0 + + + + Node-2@vyos:~$ show ip ospf neighbor + + Neighbor ID Pri State Up Time Dead Time Address Interface RXmtL RqstL DBsmL + 10.1.1.1 1 Full/Backup 3m47s 31.736s 192.168.0.1 eth0:192.168.0.2 0 0 0 + +Here's the routes: + +.. code-block:: none + + Node-1@vyos:~$ show ip route ospf + Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, + f - OpenFabric, + > - selected route, * - FIB route, q - queued, r - rejected, b - backup + t - trapped, o - offload failure + + O 10.1.1.1/32 [110/0] is directly connected, lo, weight 1, 00:00:14 + O>* 10.1.1.2/32 [110/1] via 192.168.0.2, eth0, weight 1, 00:00:07 + O 192.168.0.0/24 [110/1] is directly connected, eth0, weight 1, 00:03:32 + + Node-2@vyos:~$ show ip route ospf + Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, + f - OpenFabric, + > - selected route, * - FIB route, q - queued, r - rejected, b - backup + t - trapped, o - offload failure + + O>* 10.1.1.1/32 [110/1] via 192.168.0.1, eth0, weight 1, 00:00:11 + O 10.1.1.2/32 [110/0] is directly connected, lo, weight 1, 00:00:04 + O 192.168.0.0/24 [110/1] is directly connected, eth0, weight 1, 00:03:18 + + + + + +Enable OSPF with route redistribution of the loopback and default originate: +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ **Node 1** @@ -771,6 +846,89 @@ address and the node 1 sending the default route: set policy route-map CONNECT rule 10 match interface lo +Enable OSPF with Segment Routing (Experimental): +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +**Node 1** + +.. code-block:: none + + set interfaces loopback lo address 10.1.1.1/32 + set interfaces ethernet eth0 address 192.168.0.1/24 + set protocols ospf area 0 network '192.168.0.0/24' + set protocols ospf area 0 network '10.1.1.1/32' + set protocols ospf parameters opaque-lsa + set protocols ospf parameters router-id '10.1.1.1' + set protocols ospf segment-routing global-block high-label-value '1100' + set protocols ospf segment-routing global-block low-label-value '1000' + set protocols ospf segment-routing prefix 10.1.1.1/32 index explicit-null + set protocols ospf segment-routing prefix 10.1.1.1/32 index value '1' + +**Node 2** + +.. code-block:: none + + set interfaces loopback lo address 10.1.1.2/32 + set interfaces ethernet eth0 address 192.168.0.2/24 + set protocols ospf area 0 network '192.168.0.0/24' + set protocols ospf area 0 network '10.1.1.2/32' + set protocols ospf parameters opaque-lsa + set protocols ospf parameters router-id '10.1.1.2' + set protocols ospf segment-routing global-block high-label-value '1100' + set protocols ospf segment-routing global-block low-label-value '1000' + set protocols ospf segment-routing prefix 10.1.1.2/32 index explicit-null + set protocols ospf segment-routing prefix 10.1.1.2/32 index value '2' + + +This gives us MPLS segment routing enabled and labels for far end loopbacks: + +.. code-block:: none + + Node-1@vyos:~$ show mpls table + Inbound Label Type Nexthop Outbound Label + ----------------------------------------------------------- + 1002 SR (OSPF) 192.168.0.2 IPv4 Explicit Null <-- Node-2 loopback learned on Node-1 + 15000 SR (OSPF) 192.168.0.2 implicit-null + 15001 SR (OSPF) 192.168.0.2 implicit-null + + Node-2@vyos:~$ show mpls table + Inbound Label Type Nexthop Outbound Label + ----------------------------------------------------------- + 1001 SR (OSPF) 192.168.0.1 IPv4 Explicit Null <-- Node-1 loopback learned on Node-2 + 15000 SR (OSPF) 192.168.0.1 implicit-null + 15001 SR (OSPF) 192.168.0.1 implicit-null + +Here is the routing tables showing the MPLS segment routing label operations: + +.. code-block:: none + + Node-1@vyos:~$ show ip route ospf + Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, + f - OpenFabric, + > - selected route, * - FIB route, q - queued, r - rejected, b - backup + t - trapped, o - offload failure + + O 10.1.1.1/32 [110/0] is directly connected, lo, weight 1, 00:03:43 + O>* 10.1.1.2/32 [110/1] via 192.168.0.2, eth0, label IPv4 Explicit Null, weight 1, 00:03:32 + O 192.168.0.0/24 [110/1] is directly connected, eth0, weight 1, 00:03:43 + + Node-2@vyos:~$ show ip route ospf + Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, + f - OpenFabric, + > - selected route, * - FIB route, q - queued, r - rejected, b - backup + t - trapped, o - offload failure + + O>* 10.1.1.1/32 [110/1] via 192.168.0.1, eth0, label IPv4 Explicit Null, weight 1, 00:03:36 + O 10.1.1.2/32 [110/0] is directly connected, lo, weight 1, 00:03:51 + O 192.168.0.0/24 [110/1] is directly connected, eth0, weight 1, 00:03:51 + + + + .. _routing-ospfv3: ************* @@ -790,7 +948,7 @@ General VyOS does not have a special command to start the OSPFv3 process. The OSPFv3 process starts when the first ospf enabled interface is configured. -.. cfgcmd:: set protocols ospfv3 area <number> interface <interface> +.. cfgcmd:: set protocols ospfv3 interface <interface> area <number> This command specifies the OSPFv3 enabled interface. This command is also used to enable the OSPF process. The area number can be specified in @@ -987,7 +1145,7 @@ A typical configuration using 2 nodes. .. code-block:: none - set protocols ospfv3 area 0.0.0.0 interface eth1 + set protocols ospfv3 interface eth1 area 0.0.0.0 set protocols ospfv3 area 0.0.0.0 range 2001:db8:1::/64 set protocols ospfv3 parameters router-id 192.168.1.1 set protocols ospfv3 redistribute connected @@ -996,7 +1154,7 @@ A typical configuration using 2 nodes. .. code-block:: none - set protocols ospfv3 area 0.0.0.0 interface eth1 + set protocols ospfv3 interface eth1 area 0.0.0.0 set protocols ospfv3 area 0.0.0.0 range 2001:db8:2::/64 set protocols ospfv3 parameters router-id 192.168.2.1 set protocols ospfv3 redistribute connected @@ -1025,8 +1183,8 @@ Example configuration for WireGuard interfaces: set interfaces wireguard wg01 peer ospf02 pubkey 'ie3...=' set interfaces wireguard wg01 port '12345' set protocols ospfv3 parameters router-id 192.168.1.1 - set protocols ospfv3 area 0.0.0.0 interface 'wg01' - set protocols ospfv3 area 0.0.0.0 interface 'lo' + set protocols ospfv3 interface 'wg01' area 0.0.0.0 + set protocols ospfv3 interface 'lo' area 0.0.0.0 **Node 2** @@ -1040,8 +1198,8 @@ Example configuration for WireGuard interfaces: set interfaces wireguard wg01 peer ospf01 pubkey 'NHI...=' set interfaces wireguard wg01 port '12345' set protocols ospfv3 parameters router-id 192.168.1.2 - set protocols ospfv3 area 0.0.0.0 interface 'wg01' - set protocols ospfv3 area 0.0.0.0 interface 'lo' + set protocols ospfv3 interface 'wg01' area 0.0.0.0 + set protocols ospfv3 interface 'lo' area 0.0.0.0 **Status** diff --git a/docs/configuration/protocols/static.rst b/docs/configuration/protocols/static.rst index da471b86..1ad252e7 100644 --- a/docs/configuration/protocols/static.rst +++ b/docs/configuration/protocols/static.rst @@ -165,16 +165,17 @@ implemented. Configure ********* -.. cfgcmd:: set protocols static arp <address> hwaddr <mac> +.. cfgcmd:: set protocols static arp interface <interface> address <host> + mac <mac> This will configure a static ARP entry always resolving `<address>` to - `<mac>`. + `<mac>` for interface `<interface>`. Example: .. code-block:: none - set protocols static arp 192.0.2.100 hwaddr 00:53:27:de:23:aa + set protocols static arp interface eth0 address 192.0.2.1 mac 01:23:45:67:89:01 ********* diff --git a/docs/configuration/service/broadcast-relay.rst b/docs/configuration/service/broadcast-relay.rst index df48bfd6..b6e2bed7 100644 --- a/docs/configuration/service/broadcast-relay.rst +++ b/docs/configuration/service/broadcast-relay.rst @@ -28,6 +28,11 @@ Configuration want to receive/relay packets on both `eth1` and `eth2` both interfaces need to be added. +.. cfgcmd:: set service broadcast-relay id <n> address <ipv4-address> + + Set the source IP of forwarded packets, otherwise original senders address + is used. + .. cfgcmd:: set service broadcast-relay id <n> port <port> The UDP port number used by your apllication. It is mandatory for this kind diff --git a/docs/configuration/service/conntrack-sync.rst b/docs/configuration/service/conntrack-sync.rst index a7cd7060..468b39d9 100644 --- a/docs/configuration/service/conntrack-sync.rst +++ b/docs/configuration/service/conntrack-sync.rst @@ -37,14 +37,14 @@ Most examples below show Multicast, but unicast can be specified by using the Configuration ************* - .. cfgcmd:: set service conntrack-sync accept-protocol +.. cfgcmd:: set service conntrack-sync accept-protocol Accept only certain protocols: You may want to replicate the state of flows depending on their layer 4 protocol. Protocols are: tcp, sctp, dccp, udp, icmp and ipv6-icmp. - .. cfgcmd:: set service conntrack-sync event-listen-queue-size <size> +.. cfgcmd:: set service conntrack-sync event-listen-queue-size <size> The daemon doubles the size of the netlink event socket buffer size if it detects netlink event message dropping. This clause sets the maximum buffer @@ -52,39 +52,52 @@ Configuration Queue size for listening to local conntrack events in MB. - .. cfgcmd:: set service conntrack-sync expect-sync <all|ftp|h323|nfs|sip|sqlnet> +.. cfgcmd:: set service conntrack-sync expect-sync <all|ftp|h323|nfs|sip|sqlnet> Protocol for which expect entries need to be synchronized. - .. cfgcmd:: set service conntrack-sync failover-mechanism vrrp sync-group <group> +.. cfgcmd:: set service conntrack-sync failover-mechanism vrrp sync-group <group> Failover mechanism to use for conntrack-sync. Only VRRP is supported. Required option. - .. cfgcmd:: set service conntrack-sync ignore-address <x.x.x.x> +.. cfgcmd:: set service conntrack-sync ignore-address <x.x.x.x> IP addresses or networks for which local conntrack entries will not be synced - .. cfgcmd:: set service conntrack-sync interface <name> +.. cfgcmd:: set service conntrack-sync interface <name> Interface to use for syncing conntrack entries. - .. cfgcmd:: set service conntrack-sync mcast-group <x.x.x.x> +.. cfgcmd:: set service conntrack-sync interface <name> port <port> + + Port number used by connection. + +.. cfgcmd:: set service conntrack-sync listen-address <ipv4address> + + Local IPv4 addresses for service to listen on. + +.. cfgcmd:: set service conntrack-sync mcast-group <x.x.x.x> Multicast group to use for syncing conntrack entries. Defaults to 225.0.0.50. - .. cfgcmd:: set service conntrack-sync interface <name> peer <address> +.. cfgcmd:: set service conntrack-sync interface <name> peer <address> Peer to send unicast UDP conntrack sync entires to, if not using Multicast configuration from above above. - .. cfgcmd:: set service conntrack-sync sync-queue-size <size> +.. cfgcmd:: set service conntrack-sync sync-queue-size <size> Queue size for syncing conntrack entries in MB. +.. cfgcmd:: set service conntrack-sync disable-external-cache + + This diable the external cache and directly injects the flow-states into the + in-kernel Connection Tracking System of the backup firewall. + ********* Operation ********* @@ -114,11 +127,11 @@ Operation conntrack is not enabled. To enable conntrack, just create a NAT or a firewall rule. :cfgcmd:`set firewall state-policy established action accept` -.. opcmd:: show conntrack-sync external-cache +.. opcmd:: show conntrack-sync cache external Show connection syncing external cache entries -.. opcmd:: show conntrack-sync internal-cache +.. opcmd:: show conntrack-sync cache internal Show connection syncing internal cache entries diff --git a/docs/configuration/service/console-server.rst b/docs/configuration/service/console-server.rst index dd2f5032..c9ea7f77 100644 --- a/docs/configuration/service/console-server.rst +++ b/docs/configuration/service/console-server.rst @@ -26,25 +26,30 @@ times are used to send a single character, and so dividing the signalling bit-rate by ten results in the overall transmission speed in characters per second. This is also the default setting if none of those options are defined. -.. cfgcmd:: set service console-server <device> data-bits [7 | 8] +.. cfgcmd:: set service console-server device <device> data-bits [7 | 8] Configure either seven or eight data bits. This defaults to eight data bits if left unconfigured. -.. cfgcmd:: set service console-server <device> description <string> +.. cfgcmd:: set service console-server device <device> description <string> A user friendly description identifying the connected peripheral. -.. cfgcmd:: set service console-server <device> parity [even | odd | none] +.. cfgcmd:: set service console-server device <device> alias <string> + + A user friendly alias for this connection. Can be used instead of the + device name when connecting. + +.. cfgcmd:: set service console-server device <device> parity [even | odd | none] Set the parity option for the console. If unset this will default to none. -.. cfgcmd:: set service console-server <device> stop-bits [1 | 2] +.. cfgcmd:: set service console-server device <device> stop-bits [1 | 2] Configure either one or two stop bits. This defaults to one stop bits if left unconfigured. -.. cfgcmd:: set service console-server <device> speed +.. cfgcmd:: set service console-server device <device> speed [ 300 | 1200 | 2400 | 4800 | 9600 | 19200 | 38400 | 57600 | 115200 ] .. note:: USB to serial converters will handle most of their work in software @@ -58,7 +63,7 @@ Each individual configured console-server device can be directly exposed to the outside world. A user can directly connect via SSH to the configured port. -.. cfgcmd:: set service console-server <device> ssh port <port> +.. cfgcmd:: set service console-server device <device> ssh port <port> Accept SSH connections for the given `<device>` on TCP port `<port>`. After successfull authentication the user will be directly dropped to @@ -106,3 +111,10 @@ Operation .. hint:: The sequence ``^Ec?`` translates to: ``Ctrl+E c ?``. To quit the session use: ``Ctrl+E c .`` + + .. hint:: If ``alias`` is set, it can be used instead of the device when + connecting. + +.. opcmd:: show log console-server + + Show the console server log.
\ No newline at end of file diff --git a/docs/configuration/service/dhcp-relay.rst b/docs/configuration/service/dhcp-relay.rst index 5ce22edb..a93c1046 100644 --- a/docs/configuration/service/dhcp-relay.rst +++ b/docs/configuration/service/dhcp-relay.rst @@ -47,7 +47,7 @@ Options DHCP packet size surpasses this value it will be forwarded without appending relay agent information. Range 64...1400, default 576. -.. cfgcmd:: set service dhcp-relay relay-options relay-agents-packet +.. cfgcmd:: set service dhcp-relay relay-options relay-agents-packets <append | discard | forward | replace> Four policies for reforwarding DHCP packets exist: @@ -124,7 +124,7 @@ Configuration Options ------- -.. cfgcmd:: set service dhcpv6-relay max-hop-count 'count' +.. cfgcmd:: set service dhcpv6-relay max-hop-count <count> Set maximum hop count before packets are discarded, default: 10 diff --git a/docs/configuration/service/dhcp-server.rst b/docs/configuration/service/dhcp-server.rst index 75f8b8f0..3f4b7b89 100644 --- a/docs/configuration/service/dhcp-server.rst +++ b/docs/configuration/service/dhcp-server.rst @@ -69,10 +69,17 @@ Configuration respond to the client. The lease will remain abandoned for a minimum of abandon-lease-time seconds (defaults to 24 hours). - If a there are no free addressses but there are abandoned IP addresses, the + If there are no free addresses but there are abandoned IP addresses, the DHCP server will attempt to reclaim an abandoned IP address regardless of the value of abandon-lease-time. +.. cfgcmd:: set service dhcp-server listen-address <address> + + This configuration parameter lets the DHCP server to listen for DHCP + requests sent to the specified address, it is only realistically useful for + a server whose only clients are reached via unicasts, such as via DHCP relay + agents. + Individual Client Subnet ------------------------- @@ -151,7 +158,7 @@ Individual Client Subnet respond to the client. The lease will remain abandoned for a minimum of abandon-lease-time seconds (defaults to 24 hours). - If a there are no free addressses but there are abandoned IP addresses, the + If a there are no free addresses but there are abandoned IP addresses, the DHCP server will attempt to reclaim an abandoned IP address regardless of the value of abandon-lease-time. @@ -225,6 +232,27 @@ inside the subnet definition but can be outside of the range statement. .. hint:: This is the equivalent of the host block in dhcpd.conf of isc-dhcpd. +**Example:** + +* IP address ``192.168.1.100`` shall be statically mapped to client named ``client100`` + +.. code-block:: none + + set service dhcp-server shared-network-name 'NET1' subnet 192.168.1.0/24 static-mapping client1 ip-address 192.168.1.100 + set service dhcp-server shared-network-name 'NET1' subnet 192.168.1.0/24 static-mapping client1 mac-address aa:bb:11:22:33:00 + +The configuration will look as follows: + +.. code-block:: none + + show service dhcp-server shared-network-name NET1 + subnet 192.168.1.0/24 { + static-mapping client1 { + ip-address 192.168.1.100 + mac-address aa:bb:11:22:33:00 + } + } + Options ======= @@ -495,18 +523,6 @@ Operation Mode Show logs from specific `interface` DHCP client process. -.. opcmd:: show log dhcpv6 server - - Show DHCPv6 server daemon log file - -.. opcmd:: show log dhcpv6 client - - Show logs from all DHCPv6 client processes. - -.. opcmd:: show log dhcpv6 client interface <interface> - - Show logs from specific `interface` DHCPv6 client process. - .. opcmd:: restart dhcp server Restart the DHCP server @@ -699,21 +715,14 @@ The configuration will look as follows: .. code-block:: none - show service dhcp-server shared-network-name NET1 - shared-network-name NET1 { - subnet 2001:db8::/64 { - name-server 2001:db8:111::111 - address-range { - start 2001:db8::100 { - stop 2001:db8::199 { - } - } - static-mapping client1 { - ipv6-address 2001:db8::101 - identifier 00:01:00:01:12:34:56:78:aa:bb:cc:dd:ee:ff - } - } - } + show service dhcpv6-server shared-network-name NET1 + subnet 2001:db8::/64 { + static-mapping client1 { + identifier 00:01:00:01:12:34:56:78:aa:bb:cc:dd:ee:ff + ipv6-address 2001:db8::101 + ipv6-prefix 2001:db8:0:101::/64 + } + } .. start_vyoslinter @@ -722,6 +731,18 @@ The configuration will look as follows: Operation Mode ============== +.. opcmd:: show log dhcpv6 server + + Show DHCPv6 server daemon log file + +.. opcmd:: show log dhcpv6 client + + Show logs from all DHCPv6 client processes. + +.. opcmd:: show log dhcpv6 client interface <interface> + + Show logs from specific `interface` DHCPv6 client process. + .. opcmd:: restart dhcpv6 server To restart the DHCPv6 server @@ -732,7 +753,7 @@ Operation Mode .. opcmd:: show dhcpv6 server leases - Show statuses of all assigned leases: + Shows status of all assigned leases: .. code-block:: none diff --git a/docs/configuration/service/dns.rst b/docs/configuration/service/dns.rst index aee207a6..4315b6dc 100644 --- a/docs/configuration/service/dns.rst +++ b/docs/configuration/service/dns.rst @@ -21,6 +21,10 @@ avoid being tracked by the provider of your upstream DNS server. Forward incoming DNS queries to the DNS servers configured under the ``system name-server`` nodes. +.. cfgcmd:: set service dns forwarding dhcp <interface> + + Interfaces whose DHCP client nameservers to forward requests to. + .. cfgcmd:: set service dns forwarding name-server <address> Send all DNS queries to the IPv4/IPv6 DNS server specified under `<address>`. @@ -35,6 +39,15 @@ avoid being tracked by the provider of your upstream DNS server. .. note:: This also works for reverse-lookup zones (``18.172.in-addr.arpa``). +.. cfgcmd:: set service dns forwarding domain <domain-name> addnta + + Add NTA (negative trust anchor) for this domain. This must be set if the + domain does not support DNSSEC. + +.. cfgcmd:: set service dns forwarding domain <domain-name> recursion-desired + + Set the "recursion desired" bit in requests to the upstream nameserver. + .. cfgcmd:: set service dns forwarding allow-from <network> Given the fact that open DNS recursors could be used on DDoS amplification diff --git a/docs/configuration/service/eventhandler.rst b/docs/configuration/service/eventhandler.rst new file mode 100644 index 00000000..15f08239 --- /dev/null +++ b/docs/configuration/service/eventhandler.rst @@ -0,0 +1,127 @@ +.. _event-handler: + +############# +Event Handler +############# + +********************************* +Event Handler Technology Overview +********************************* + +Event handler allows you to execute scripts when a string that matches a regex or a regex with +a service name appears in journald logs. You can pass variables, arguments, and a full matching string to the script. + + +****************************** +How to configure Event Handler +****************************** + + `1. Create an event handler`_ + + `2. Add regex to the script`_ + + `3. Add a full path to the script`_ + + `4. Add optional parameters`_ + +********************************* +Event Handler Configuration Steps +********************************* + +1. Create an event handler +========================== + + .. cfgcmd:: set service event-handler event <event-handler name> + + This is an optional command because the event handler will be automatically created after any of the next commands. + + +2. Add regex to the script +=========================================== + + .. cfgcmd:: set service event-handler event <event-handler name> filter pattern <regex> + + This is a mandatory command. Sets regular expression to match against log string message. + + .. note:: The regular expression matches if and only if the entire string matches the pattern. + + + +3. Add a full path to the script +================================ + + .. cfgcmd:: set service event-handler event <event-handler name> script path <path to script> + + This is a mandatory command. Sets the full path to the script. The script file must be executable. + + + +4. Add optional parameters +========================== + + .. cfgcmd:: set service event-handler event <event-handler name> filter syslog-identifier <sylogid name> + + This is an optional command. Filters log messages by syslog-identifier. + + .. cfgcmd:: set service event-handler event <event-handler name> script environment <env name> value <env value> + + This is an optional command. Adds environment and its value to the script. Use separate commands for each environment. + + One implicit environment exists. + + * ``message``: Full message that has triggered the script. + + .. cfgcmd:: set service event-handler event <event-handler name> script arguments <arguments> + + This is an optional command. Adds arguments to the script. Arguments must be separated by spaces. + + .. note:: We don't recomend to use arguments. Using environments is more preffereble. + + +******* +Example +******* + + Event handler that monitors the state of interface eth0. + + .. code-block:: none + + set service event-handler event INTERFACE_STATE_DOWN filter pattern '.*eth0.*,RUNNING,.*->.*' + set service event-handler event INTERFACE_STATE_DOWN filter syslog-identifier 'netplugd' + set service event-handler event INTERFACE_STATE_DOWN script environment interface_action value 'down' + set service event-handler event INTERFACE_STATE_DOWN script environment interface_name value 'eth2' + set service event-handler event INTERFACE_STATE_DOWN script path '/config/scripts/eventhandler.py' + + Event handler script + + .. code-block:: none + + #!/usr/bin/env python3 + # + # VyOS event-handler script example + from os import environ + import subprocess + from sys import exit + + # Perform actions according to requirements + def process_event() -> None: + # Get variables + message_text = environ.get('message') + interface_name = environ.get('interface_name') + interface_action = environ.get('interface_action') + # Print the message that triggered this script + print(f'Logged message: {message_text}') + # Prepare a command to run + command = f'sudo ip link set {interface_name} {interface_action}'.split() + # Execute a command + subprocess.run(command) + + if __name__ == '__main__': + try: + # Run script actions and exit + process_event() + exit(0) + except Exception as err: + # Exit properly in case if something in the script goes wrong + print(f'Error running script: {err}') + exit(1) diff --git a/docs/configuration/service/https.rst b/docs/configuration/service/https.rst index 22533db5..08b16575 100644 --- a/docs/configuration/service/https.rst +++ b/docs/configuration/service/https.rst @@ -28,6 +28,10 @@ Configuration Set the listen port of the local API, this has no effect on the webserver. The default is port 8080 +.. cfgcmd:: set service https api socket + + Use local socket for API + .. cfgcmd:: set service https api strict Enforce strict path checking @@ -89,4 +93,4 @@ To use this full configuration we asume a public accessible hostname. set service https virtual-host rtr01 listen-address 198.51.100.2 set service https virtual-host rtr01 listen-port 11443 set service https virtual-host rtr01 server-name rtr01.example.com - set service https api-restrict virtual-host rtr01.example.com + set service https api-restrict virtual-host rtr01 diff --git a/docs/configuration/service/index.rst b/docs/configuration/service/index.rst index 11a1a118..1195348f 100644 --- a/docs/configuration/service/index.rst +++ b/docs/configuration/service/index.rst @@ -18,6 +18,7 @@ Service lldp mdns monitoring + ntp pppoe-server router-advert salt-minion @@ -25,3 +26,4 @@ Service ssh tftp-server webproxy + eventhandler diff --git a/docs/configuration/service/ipoe-server.rst b/docs/configuration/service/ipoe-server.rst index d8b9e6b7..e42ab42e 100644 --- a/docs/configuration/service/ipoe-server.rst +++ b/docs/configuration/service/ipoe-server.rst @@ -39,7 +39,7 @@ the configuration. .. code-block:: none - set service ipoe-server authentication interface eth2 mac-address 08:00:27:2f:d8:06 + set service ipoe-server authentication interface eth2 mac 08:00:27:2f:d8:06 set service ipoe-server authentication mode 'local' set service ipoe-server name-server '10.10.1.1' set service ipoe-server name-server '10.10.1.2' @@ -70,7 +70,7 @@ IPv6 DNS addresses are optional. .. code-block:: none - set service ipoe-server authentication interface eth3 mac-address 08:00:27:2F:D8:06 + set service ipoe-server authentication interface eth3 mac 08:00:27:2F:D8:06 set service ipoe-server authentication mode 'local' set service ipoe-server client-ipv6-pool delegate '2001:db8:1::/48' delegation-prefix '56' set service ipoe-server client-ipv6-pool prefix '2001:db8::/48' mask '64' @@ -131,8 +131,8 @@ The rate-limit is set in kbit/sec. .. code-block:: none - set service ipoe-server authentication interface eth2 mac-address 08:00:27:2f:d8:06 rate-limit download '500' - set service ipoe-server authentication interface eth2 mac-address 08:00:27:2f:d8:06 rate-limit upload '500' + set service ipoe-server authentication interface eth2 mac 08:00:27:2f:d8:06 rate-limit download '500' + set service ipoe-server authentication interface eth2 mac 08:00:27:2f:d8:06 rate-limit upload '500' set service ipoe-server authentication mode 'local' set service ipoe-server name-server '10.10.1.1' set service ipoe-server name-server '10.10.1.2' diff --git a/docs/configuration/service/monitoring.rst b/docs/configuration/service/monitoring.rst index 7396f142..755669e1 100644 --- a/docs/configuration/service/monitoring.rst +++ b/docs/configuration/service/monitoring.rst @@ -1,10 +1,111 @@ Monitoring ---------- -Monitoring functionality with ``telegraf`` and ``InfluxDB 2`` is provided. +Azure-data-explorer +=================== +Telegraf output plugin azure-data-explorer_ + +.. cfgcmd:: set service monitoring telegraf azure-data-explorer authentication client-id <client-id> + + Authentication application client-id. + +.. cfgcmd:: set service monitoring telegraf azure-data-explorer authentication client-secret <client-secret> + + Authentication application client-secret. + +.. cfgcmd:: set service monitoring telegraf azure-data-explorer authentication tenant-id <tenant-id> + + Authentication application tenant-id + +.. cfgcmd:: set service monitoring telegraf azure-data-explorer database <name> + + Remote databe name. + +.. cfgcmd:: set service monitoring telegraf azure-data-explorer group-metrics <single-table | table-per-metric> + + Type of metrics grouping when push to Azure Data Explorer. The default is + ``table-per-metric``. + +.. cfgcmd:: set service monitoring telegraf azure-data-explorer table <name> + + Name of the single table Only if set group-metrics single-table. + +.. cfgcmd:: set service monitoring telegraf azure-data-explorer url <url> + + Remote URL. + +Prometheus-client +================= +Telegraf output plugin prometheus-client_ + +.. cfgcmd:: set service monitoring telegraf prometheus-client + + Output plugin Prometheus client + +.. cfgcmd:: set service monitoring telegraf prometheus-client allow-from <prefix> + + Networks allowed to query this server + +.. cfgcmd:: set service monitoring telegraf prometheus-client authentication username <username> + + HTTP basic authentication username + +.. cfgcmd:: set service monitoring telegraf prometheus-client authentication password <password> + + HTTP basic authentication username + +.. cfgcmd:: set service monitoring telegraf prometheus-client listen-address <address> + + Local IP addresses to listen on + +.. cfgcmd:: set service monitoring telegraf prometheus-client metric-version <1 | 2> + + Metris version, the default is ``2`` + +.. cfgcmd:: set service monitoring telegraf prometheus-client port <port> + + Port number used by connection, default is ``9273`` + +Example: + +.. code-block:: none + + set service monitoring telegraf prometheus-client + +.. code-block:: none + + vyos@r14:~$ curl --silent localhost:9273/metrics | egrep -v "#" | grep cpu_usage_system + cpu_usage_system{cpu="cpu-total",host="r14"} 0.20040080160320556 + cpu_usage_system{cpu="cpu0",host="r14"} 0.17182130584191915 + cpu_usage_system{cpu="cpu1",host="r14"} 0.22896393817971655 + +Splunk +====== +Telegraf output plugin splunk_. HTTP Event Collector. + +.. cfgcmd:: set service monitoring telegraf splunk authentication insecure + + Use TLS but skip host validation + +.. cfgcmd:: set service monitoring telegraf splunk authentication token <token> + + Authorization token + +.. cfgcmd:: set service monitoring telegraf splunk authentication url <url> + + Remote URL to Splunk collector + +Example: + +.. code-block:: none + + set service monitoring telegraf splunk authentication insecure + set service monitoring telegraf splunk authentication token 'xxxxf5b8-xxxx-452a-xxxx-43828911xxxx' + set service monitoring telegraf splunk url 'https://192.0.2.10:8088/services/collector' Telegraf ======== +Monitoring functionality with ``telegraf`` and ``InfluxDB 2`` is provided. Telegraf is the open source server agent to help you collect metrics, events and logs from your routers. @@ -43,3 +144,7 @@ An example of a configuration that sends ``telegraf`` metrics to remote set service monitoring telegraf port '8086' set service monitoring telegraf source 'all' set service monitoring telegraf url 'http://r1.influxdb2.local' + +.. _azure-data-explorer: https://github.com/influxdata/telegraf/tree/master/plugins/outputs/azure_data_explorer +.. _prometheus-client: https://github.com/influxdata/telegraf/tree/master/plugins/outputs/prometheus_client +.. _splunk: https://www.splunk.com/en_us/blog/it/splunk-metrics-via-telegraf.html
\ No newline at end of file diff --git a/docs/configuration/system/ntp.rst b/docs/configuration/service/ntp.rst index 223447f5..5b718c4f 100644 --- a/docs/configuration/system/ntp.rst +++ b/docs/configuration/service/ntp.rst @@ -30,10 +30,16 @@ The current protocol is version 4 (NTPv4), which is a proposed standard as documented in :rfc:`5905`. It is backward compatible with version 3, specified in :rfc:`1305`. +.. note:: VyOS 1.4 uses chrony instead of ntpd (see :vytask:`T3008`) which will + no longer accept anonymous NTP requests as in VyOS 1.3. All configurations + will be migrated to keep the anonymous functionality. For new setups if you + have clients using your VyOS installation as NTP server, you must specify + the `allow-client` directive. + Configuration ============= -.. cfgcmd:: set system ntp server <address> +.. cfgcmd:: set service ntp server <address> Configure one or more servers for synchronisation. Server name can be either an IP address or :abbr:`FQDN (Fully Qualified Domain Name)`. @@ -44,7 +50,7 @@ Configuration * ``1.pool.ntp.org`` * ``2.pool.ntp.org`` -.. cfgcmd:: set system ntp server <address> <noselect | pool | preempt | prefer> +.. cfgcmd:: set service ntp server <address> <noselect | pool | prefer> Configure one or more attributes to the given NTP server. @@ -54,24 +60,22 @@ Configuration * ``pool`` mobilizes persistent client mode association with a number of remote servers. - * ``preempt`` a preemptable association is expendable. - * ``prefer`` marks the server as preferred. All other things being equal, this host will be chosen for synchronization among a set of correctly operating hosts. -.. cfgcmd:: set system ntp listen-address <address> +.. cfgcmd:: set service ntp listen-address <address> NTP process will only listen on the specified IP address. You must specify the `<address>` and optionally the permitted clients. Multiple listen addresses can be configured. -.. cfgcmd:: set system ntp allow-clients address <address> +.. cfgcmd:: set service ntp allow-client address <address> List of networks or client addresses permitted to contact this NTP server. - Multiple networks can be configured. + Multiple networks/client IP addresses can be configured. -.. cfgcmd:: set system ntp vrf <name> +.. cfgcmd:: set service ntp vrf <name> Specify name of the :abbr:`VRF (Virtual Routing and Forwarding)` instance. diff --git a/docs/configuration/service/pppoe-server.rst b/docs/configuration/service/pppoe-server.rst index ad99cec0..69e357f3 100644 --- a/docs/configuration/service/pppoe-server.rst +++ b/docs/configuration/service/pppoe-server.rst @@ -1,3 +1,5 @@ +:lastproofread: 2022-09-17 + .. _pppoe-server: ############ @@ -106,10 +108,10 @@ and then configure it. .. cfgcmd:: set service pppoe-server authentication radius server <address> key <secret> - + Use this command to configure the IP address and the shared secret key of your RADIUS server. You can have multiple RADIUS servers - configured if you wish to achieve redundancy. + configured if you wish to achieve redundancy. .. code-block:: none @@ -169,25 +171,24 @@ CoA request. Automatic VLAN Creation ----------------------- -.. cfgcmd:: set service pppoe-server interface <interface> - <vlan-id | vlan range> <text> +.. cfgcmd:: set service pppoe-server interface <interface> vlan <id | range> - VLAN's can be created by accel-ppp on the fly via the use of a Kernel - module named `vlan_mon`, which is monitoring incoming vlans and - creates the necessary VLAN if required and allowed. VyOS supports the - use of either VLAN ID's or entire ranges, both values can be defined - at the same time for an interface. When configured, the PPPoE will - create the necessary VLANs when required. Once the user session has - been cancelled and the VLAN is not needed anymore, VyOS will remove - it again. + VLAN's can be created by Accel-ppp on the fly via the use of a Kernel module + named `vlan_mon`, which is monitoring incoming vlans and creates the + necessary VLAN if required and allowed. VyOS supports the use of either + VLAN ID's or entire ranges, both values can be defined at the same time for + an interface. -.. code-block:: none + When configured, PPPoE will create the necessary VLANs when required. Once + the user session has been cancelled and the VLAN is not needed anymore, VyOS + will remove it again. - set service pppoe-server interface eth3 vlan-id 100 - set service pppoe-server interface eth3 vlan-id 200 - set service pppoe-server interface eth3 vlan-range 500-1000 - set service pppoe-server interface eth3 vlan-range 2000-3000 +.. code-block:: none + set service pppoe-server interface eth3 vlan 100 + set service pppoe-server interface eth3 vlan 200 + set service pppoe-server interface eth3 vlan 500-1000 + set service pppoe-server interface eth3 vlan 2000-3000 Bandwidth Shaping @@ -201,7 +202,7 @@ For Local Users .. cfgcmd:: set service pppoe-server authentication local-users username <name> rate-limit <download | upload> - + Use this command to configure a data-rate limit to PPPOoE clients for traffic download or upload. The rate-limit is set in kbit/sec. diff --git a/docs/configuration/service/router-advert.rst b/docs/configuration/service/router-advert.rst index 36fa600d..eb1a6844 100644 --- a/docs/configuration/service/router-advert.rst +++ b/docs/configuration/service/router-advert.rst @@ -8,7 +8,6 @@ Router Advertisements They are part of what is known as :abbr:`SLAAC (Stateless Address Autoconfiguration)`. - Supported interface types: * bonding @@ -21,7 +20,7 @@ Supported interface types: * vxlan * wireguard * wireless - * wirelessmodem + * wwan Enabling Advertisments @@ -31,7 +30,7 @@ Enabling Advertisments .. stop_vyoslinter -.. csv-table:: +.. csv-table:: :header: "Field", "VyOS Option", "Description" :widths: 10, 10, 20 @@ -61,6 +60,8 @@ Advertising a Prefix :header: "VyOS Field", "Description" :widths: 10,30 + "decrement-lifetime", "Lifetime is decremented by the number of seconds since the last RA - use in conjunction with a DHCPv6-PD prefix" + "deprecate-prefix", "Upon shutdown, this option will deprecate the prefix by announcing it in the shutdown RA" "no-autonomous-flag","Prefix can not be used for stateless address auto-configuration" "no-on-link-flag","Prefix can not be used for on-link determination" "preferred-lifetime","Time in seconds that the prefix will remain preferred (default 4 hours)" diff --git a/docs/configuration/service/ssh.rst b/docs/configuration/service/ssh.rst index ad410a3c..15c2390c 100644 --- a/docs/configuration/service/ssh.rst +++ b/docs/configuration/service/ssh.rst @@ -109,6 +109,38 @@ Configuration Specify name of the :abbr:`VRF (Virtual Routing and Forwarding)` instance. +Dynamic-protection +================== +Protects host from brute-force attacks against +SSH. Log messages are parsed, line-by-line, for recognized patterns. If an +attack, such as several login failures within a few seconds, is detected, the +offending IP is blocked. Offenders are unblocked after a set interval. + +.. cfgcmd:: set service ssh dynamic-protection + + Allow ``ssh`` dynamic-protection. + +.. cfgcmd:: set service ssh dynamic-protection allow-from <address | prefix> + + Whitelist of addresses and networks. Always allow inbound connections from + these systems. + +.. cfgcmd:: set service ssh dynamic-protection block-time <sec> + + Block source IP in seconds. Subsequent blocks increase by a factor of 1.5 + The default is 120. + +.. cfgcmd:: set service ssh dynamic-protection detect-time <sec> + + Remember source IP in seconds before reset their score. The default is 1800. + +.. cfgcmd:: set service ssh dynamic-protection threshold <sec> + + Block source IP when their cumulative attack score exceeds threshold. The + default is 30. + +.. _ssh_operation: + Operation ========= @@ -157,19 +189,19 @@ Operation ``/config/auth/id_rsa_rpki.pub`` will be created. -.. opcmd:: generate public-key-command name <username> path <location> +.. opcmd:: generate public-key-command user <username> path <location> Generate the configuration mode commands to add a public key for :ref:`ssh_key_based_authentication`. ``<location>`` can be a local path or a URL pointing at a remote file. - Supported remote protocols are FTP, HTTP, HTTPS, SCP/SFTP and TFTP. + Supported remote protocols are FTP, FTPS, HTTP, HTTPS, SCP/SFTP and TFTP. Example: .. code-block:: none - alyssa@vyos:~$ generate public-key-command name alyssa path sftp://example.net/home/alyssa/.ssh/id_rsa.pub + alyssa@vyos:~$ generate public-key-command user alyssa path sftp://example.net/home/alyssa/.ssh/id_rsa.pub # To add this key as an embedded key, run the following commands: configure set system login user alyssa authentication public-keys alyssa@example.net key AAA... diff --git a/docs/configuration/service/tftp-server.rst b/docs/configuration/service/tftp-server.rst index 0ca75efe..84acf3d4 100644 --- a/docs/configuration/service/tftp-server.rst +++ b/docs/configuration/service/tftp-server.rst @@ -15,8 +15,8 @@ Configuration .. cfgcmd:: set service tftp-server directory <directory> -Enable TFTP service by specifying the `<directory>` which will be used to serve -files. + Enable TFTP service by specifying the `<directory>` which will be used to serve + files. .. hint:: Choose your ``directory`` location carefully or you will loose the content on image upgrades. Any directory under ``/config`` is save at this @@ -24,9 +24,9 @@ files. .. cfgcmd:: set service tftp-server listen-address <address> -Configure the IPv4 or IPv6 listen address of the TFTP server. Multiple IPv4 and -IPv6 addresses can be given. There will be one TFTP server instances listening -on each IP address. + Configure the IPv4 or IPv6 listen address of the TFTP server. Multiple IPv4 and + IPv6 addresses can be given. There will be one TFTP server instances listening + on each IP address. .. cfgcmd:: set service tftp-server listen-address <address> vrf <name> @@ -40,8 +40,8 @@ Additional option to run TFTP server in the :abbr:`VRF (Virtual Routing and Forw .. cfgcmd:: set service tftp-server allow-upload -Optional, if you want to enable uploads, else TFTP server will act as a -read-only server. + Optional, if you want to enable uploads, else TFTP server will act as a + read-only server. Example ------- diff --git a/docs/configuration/service/webproxy.rst b/docs/configuration/service/webproxy.rst index e8f6423e..a6c5ff0a 100644 --- a/docs/configuration/service/webproxy.rst +++ b/docs/configuration/service/webproxy.rst @@ -137,6 +137,17 @@ Configuration set service webproxy reply-body-max-size 2048 +.. cfgcmd:: set service webproxy safe-ports <port> + + Add new port to Safe-ports acl. Ports included by default in Safe-ports acl: + 21, 70, 80, 210, 280, 443, 488, 591, 777, 873, 1025-65535 + +.. cfgcmd:: set service webproxy ssl-safe-ports <port> + + Add new port to SSL-ports acl. Ports included by default in SSL-ports acl: + 443 + + Authentication ============== diff --git a/docs/configuration/system/acceleration.disable b/docs/configuration/system/acceleration.disable deleted file mode 100644 index b09da38b..00000000 --- a/docs/configuration/system/acceleration.disable +++ /dev/null @@ -1,7 +0,0 @@ -.. _acceleration: - -############ -Acceleration -############ - - diff --git a/docs/configuration/system/acceleration.rst b/docs/configuration/system/acceleration.rst new file mode 100644 index 00000000..62b85c71 --- /dev/null +++ b/docs/configuration/system/acceleration.rst @@ -0,0 +1,146 @@ +.. _acceleration: + +############ +Acceleration +############ + +In this command tree, all hardware acceleration options will be handled. +At the moment only `Intel® QAT`_ is supported + +********** +Intel® QAT +********** + +.. opcmd:: show system acceleration qat + + use this command to check if there is an Intel® QAT supported Processor in + your system. + + .. code-block:: + + vyos@vyos:~$ show system acceleration qat + 01:00.0 Co-processor [0b40]: Intel Corporation Atom Processor C3000 Series QuickAssist Technology [8086:19e2] (rev 11) + + if there is non device the command will show ```No QAT device found``` + +.. cfgcmd:: set system acceleration qat + + if there is a supported device, enable Intel® QAT + +.. opcmd:: show system acceleration qat status + + Check if the Intel® QAT device is up and ready to do the job. + + .. code-block:: + + vyos@vyos:~$ show system acceleration qat status + Checking status of all devices. + There is 1 QAT acceleration device(s) in the system: + qat_dev0 - type: c3xxx, inst_id: 0, node_id: 0, bsf: 0000:01:00.0, #accel: 3 #engines: 6 state: up + +Operation Mode +============== + +.. opcmd:: show system acceleration qat device <device> config + + Show the full config uploaded to the QAT device. + +.. opcmd:: show system acceleration qat device <device> flows + + Get an overview over the encryption counters. + +.. opcmd:: show system acceleration qat interrupts + + Show binded qat device interrupts to certain core. + + +Example +======= + +Let's build a simple VPN between 2 Intel® QAT ready devices. + +Side A: + +.. code-block:: + + set interfaces vti vti1 address '192.168.1.2/24' + set vpn ipsec esp-group MyESPGroup proposal 1 encryption 'aes256' + set vpn ipsec esp-group MyESPGroup proposal 1 hash 'sha256' + set vpn ipsec ike-group MyIKEGroup proposal 1 dh-group '14' + set vpn ipsec ike-group MyIKEGroup proposal 1 encryption 'aes256' + set vpn ipsec ike-group MyIKEGroup proposal 1 hash 'sha256' + set vpn ipsec interface 'eth0' + set vpn ipsec site-to-site peer 10.10.10.1 authentication mode 'pre-shared-secret' + set vpn ipsec site-to-site peer 10.10.10.1 authentication pre-shared-secret 'Qwerty123' + set vpn ipsec site-to-site peer 10.10.10.1 connection-type 'initiate' + set vpn ipsec site-to-site peer 10.10.10.1 default-esp-group 'MyESPGroup' + set vpn ipsec site-to-site peer 10.10.10.1 ike-group 'MyIKEGroup' + set vpn ipsec site-to-site peer 10.10.10.1 local-address '10.10.10.2' + set vpn ipsec site-to-site peer 10.10.10.1 vti bind 'vti1' + +Side B: + +.. code-block:: + + set interfaces vti vti1 address '192.168.1.1/24' + set vpn ipsec esp-group MyESPGroup proposal 1 encryption 'aes256' + set vpn ipsec esp-group MyESPGroup proposal 1 hash 'sha256' + set vpn ipsec ike-group MyIKEGroup proposal 1 dh-group '14' + set vpn ipsec ike-group MyIKEGroup proposal 1 encryption 'aes256' + set vpn ipsec ike-group MyIKEGroup proposal 1 hash 'sha256' + set vpn ipsec interface 'eth0' + set vpn ipsec site-to-site peer 10.10.10.2 authentication mode 'pre-shared-secret' + set vpn ipsec site-to-site peer 10.10.10.2 authentication pre-shared-secret 'Qwerty123' + set vpn ipsec site-to-site peer 10.10.10.2 connection-type 'initiate' + set vpn ipsec site-to-site peer 10.10.10.2 default-esp-group 'MyESPGroup' + set vpn ipsec site-to-site peer 10.10.10.2 ike-group 'MyIKEGroup' + set vpn ipsec site-to-site peer 10.10.10.2 local-address '10.10.10.1' + set vpn ipsec site-to-site peer 10.10.10.2 vti bind 'vti1' + +a bandwidth test over the VPN got these results: + +.. code-block:: + + Connecting to host 192.168.1.2, port 5201 + [ 9] local 192.168.1.1 port 51344 connected to 192.168.1.2 port 5201 + [ ID] Interval Transfer Bitrate Retr Cwnd + [ 9] 0.00-1.01 sec 32.3 MBytes 268 Mbits/sec 0 196 KBytes + [ 9] 1.01-2.03 sec 32.5 MBytes 268 Mbits/sec 0 208 KBytes + [ 9] 2.03-3.03 sec 32.5 MBytes 271 Mbits/sec 0 208 KBytes + [ 9] 3.03-4.04 sec 32.5 MBytes 272 Mbits/sec 0 208 KBytes + [ 9] 4.04-5.00 sec 31.2 MBytes 272 Mbits/sec 0 208 KBytes + [ 9] 5.00-6.01 sec 32.5 MBytes 272 Mbits/sec 0 234 KBytes + [ 9] 6.01-7.04 sec 32.5 MBytes 265 Mbits/sec 0 234 KBytes + [ 9] 7.04-8.04 sec 32.5 MBytes 272 Mbits/sec 0 234 KBytes + [ 9] 8.04-9.04 sec 32.5 MBytes 273 Mbits/sec 0 336 KBytes + [ 9] 9.04-10.00 sec 31.2 MBytes 272 Mbits/sec 0 336 KBytes + - - - - - - - - - - - - - - - - - - - - - - - - - + [ ID] Interval Transfer Bitrate Retr + [ 9] 0.00-10.00 sec 322 MBytes 270 Mbits/sec 0 sender + [ 9] 0.00-10.00 sec 322 MBytes 270 Mbits/sec receiver + +with :cfgcmd:`set system acceleration qat` on both systems the bandwidth +increases. + +.. code-block:: + + Connecting to host 192.168.1.2, port 5201 + [ 9] local 192.168.1.1 port 51340 connected to 192.168.1.2 port 5201 + [ ID] Interval Transfer Bitrate Retr Cwnd + [ 9] 0.00-1.00 sec 97.3 MBytes 817 Mbits/sec 0 1000 KBytes + [ 9] 1.00-2.00 sec 92.5 MBytes 776 Mbits/sec 0 1.07 MBytes + [ 9] 2.00-3.00 sec 92.5 MBytes 776 Mbits/sec 0 820 KBytes + [ 9] 3.00-4.00 sec 92.5 MBytes 776 Mbits/sec 0 899 KBytes + [ 9] 4.00-5.00 sec 91.2 MBytes 765 Mbits/sec 0 972 KBytes + [ 9] 5.00-6.00 sec 92.5 MBytes 776 Mbits/sec 0 1.02 MBytes + [ 9] 6.00-7.00 sec 92.5 MBytes 776 Mbits/sec 0 1.08 MBytes + [ 9] 7.00-8.00 sec 92.5 MBytes 776 Mbits/sec 0 1.14 MBytes + [ 9] 8.00-9.00 sec 91.2 MBytes 765 Mbits/sec 0 915 KBytes + [ 9] 9.00-10.00 sec 92.5 MBytes 776 Mbits/sec 0 1000 KBytes + - - - - - - - - - - - - - - - - - - - - - - - - - + [ ID] Interval Transfer Bitrate Retr + [ 9] 0.00-10.00 sec 927 MBytes 778 Mbits/sec 0 sender + [ 9] 0.00-10.01 sec 925 MBytes 775 Mbits/sec receiver + + +.. _`Intel® QAT`: https://www.intel.com/content/www/us/en/architecture-and-technology/intel-quick-assist-technology-overview.html diff --git a/docs/configuration/system/conntrack.rst b/docs/configuration/system/conntrack.rst index 7f7e4b77..68a4f2b8 100644 --- a/docs/configuration/system/conntrack.rst +++ b/docs/configuration/system/conntrack.rst @@ -1,33 +1,187 @@ -################### -Connection tracking -################### -Modules -------- +######### +Conntrack +######### -.. code-block:: none +VyOS can be configured to track connections using the connection +tracking subsystem. Connection tracking becomes operational once either +stateful firewall or NAT is configured. - conntrack { - modules { - ftp - h323 - nfs - pptp - sip - sqlnet - tftp - } - } +********* +Configure +********* -Enables ``conntrack`` modules. All modules are now disabled by default, while they -used to be enabled in previous versions. Enabling the modules ensures backwards -compatibility — keeping the previous behavior. +.. cfgcmd:: set system conntrack table-size <1-50000000> + :defaultvalue: -In most cases they can be disabled by removing the block of configuration. + The connection tracking table contains one entry for each connection being + tracked by the system. -.. code-block:: none +.. cfgcmd:: set system conntrack expect-table-size <1-50000000> + :defaultvalue: - delete system conntrack modules + The connection tracking expect table contains one entry for each expected + connection related to an existing connection. These are generally used by + “connection tracking helper” modules such as FTP. + The default size of the expect table is 2048 entries. -For some scenarios it is in fact recommended, like in this example: -:ref:`example-high-availability`. +.. cfgcmd:: set system conntrack hash-size <1-50000000> + :defaultvalue: + + Set the size of the hash table. The connection tracking hash table makes + searching the connection tracking table faster. The hash table uses + “buckets” to record entries in the connection tracking table. + +.. cfgcmd:: set system conntrack modules ftp +.. cfgcmd:: set system conntrack modules h323 +.. cfgcmd:: set system conntrack modules nfs +.. cfgcmd:: set system conntrack modules pptp +.. cfgcmd:: set system conntrack modules sip +.. cfgcmd:: set system conntrack modules sqlnet +.. cfgcmd:: set system conntrack modules tftp + + Configure the connection tracking protocol helper modules. + All modules are enable by default. + + | Use `delete system conntrack modules` to deactive all modules. + | Or, for example ftp, `delete system conntrack modules ftp`. + + +Define Conection Timeouts +========================= + +VyOS supports setting timeouts for connections according to the +connection type. You can set timeout values for generic connections, for ICMP +connections, UDP connections, or for TCP connections in a number of different +states. + +.. cfgcmd:: set system conntrack timeout icmp <1-21474836> + :defaultvalue: +.. cfgcmd:: set system conntrack timeout other <1-21474836> + :defaultvalue: +.. cfgcmd:: set system conntrack timeout tcp close <1-21474836> + :defaultvalue: +.. cfgcmd:: set system conntrack timeout tcp close-wait <1-21474836> + :defaultvalue: +.. cfgcmd:: set system conntrack timeout tcp established <1-21474836> + :defaultvalue: +.. cfgcmd:: set system conntrack timeout tcp fin-wait <1-21474836> + :defaultvalue: +.. cfgcmd:: set system conntrack timeout tcp last-ack <1-21474836> + :defaultvalue: +.. cfgcmd:: set system conntrack timeout tcp syn-recv <1-21474836> + :defaultvalue: +.. cfgcmd:: set system conntrack timeout tcp syn-sent <1-21474836> + :defaultvalue: +.. cfgcmd:: set system conntrack timeout tcp time-wait <1-21474836> + :defaultvalue: +.. cfgcmd:: set system conntrack timeout udp other <1-21474836> + :defaultvalue: +.. cfgcmd:: set system conntrack timeout udp stream <1-21474836> + :defaultvalue: + + Set the timeout in secounds 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 +create a rule defining the packet and flow selector. + +.. cfgcmd:: set system conntrack timeout custom rule <1-9999> description <test> + + Set a rule description. + + +.. cfgcmd:: set system conntrack timeout custom rule <1-9999> destination address <ip-address> +.. cfgcmd:: set system conntrack timeout custom rule <1-9999> source address <ip-address> + + set a destination and/or source address. Accepted input: + + .. code-block:: none + + <x.x.x.x> IP address to match + <x.x.x.x/x> Subnet to match + <x.x.x.x>-<x.x.x.x> + IP range to match + !<x.x.x.x> Match everything except the specified address + !<x.x.x.x/x> Match everything except the specified subnet + !<x.x.x.x>-<x.x.x.x> + Match everything except the specified range + +.. cfgcmd:: set system conntrack timeout custom rule <1-9999> destination port <value> +.. cfgcmd:: set system conntrack timeout custom rule <1-9999> source port <value> + + Set a destination and/or source port. Accepted input: + + .. code-block:: none + + <port name> Named port (any name in /etc/services, e.g., http) + <1-65535> Numbered port + <start>-<end> Numbered port range (e.g., 1001-1005) + + Multiple destination ports can be specified as a comma-separated list. + The whole list can also be "negated" using '!'. For example: + `!22,telnet,http,123,1001-1005`` + + + +.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol icmp <1-21474836> +.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol other <1-21474836> +.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol tcp close <1-21474836> +.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol tcp close-wait <1-21474836> +.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol tcp established <1-21474836> +.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol tcp fin-wait <1-21474836> +.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol tcp last-ack <1-21474836> +.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol tcp syn-recv <1-21474836> +.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol tcp syn-sent <1-21474836> +.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol tcp time-wait <1-21474836> +.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol udp other <1-21474836> +.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol udp stream <1-21474836> + + Set the timeout in secounds for a protocol or state in a custom rule. + + +.. cfgcmd:: set system conntrack tcp half-open-connections <1-21474836> + :defaultvalue: + + Set the maximum number of TCP half-open connections. + +.. cfgcmd:: set system conntrack tcp loose <enable | disable> + :defaultvalue: + + Policy to track previously established connections. + +.. cfgcmd:: set system conntrack tcp max-retrans <1-2147483647> + :defaultvalue: + + Set the number of TCP maximum retransmit attempts. + +.. cfgcmd:: set system conntrack ignore rule <1-9999> description <text> +.. cfgcmd:: set system conntrack ignore rule <1-9999> destination address <ip-address> +.. cfgcmd:: set system conntrack ignore rule <1-9999> destination port <port> +.. cfgcmd:: set system conntrack ignore rule <1-9999> inbound-interface <interface> +.. cfgcmd:: set system conntrack ignore rule <1-9999> protocol <protocol> +.. cfgcmd:: set system conntrack ignore rule <1-9999> source address <ip-address> +.. cfgcmd:: set system conntrack ignore rule <1-9999> source port <port> + + Customized ignore rules, based on a packet and flow selector. + +.. cfgcmd:: set system conntrack log icmp destroy +.. cfgcmd:: set system conntrack log icmp new +.. cfgcmd:: set system conntrack log icmp update +.. cfgcmd:: set system conntrack log other destroy +.. cfgcmd:: set system conntrack log other new +.. cfgcmd:: set system conntrack log other update +.. cfgcmd:: set system conntrack log tcp destroy +.. cfgcmd:: set system conntrack log tcp new +.. cfgcmd:: set system conntrack log tcp update close-wait +.. cfgcmd:: set system conntrack log tcp update established +.. cfgcmd:: set system conntrack log tcp update fin-wait +.. cfgcmd:: set system conntrack log tcp update last-ack +.. cfgcmd:: set system conntrack log tcp update syn-received +.. cfgcmd:: set system conntrack log tcp update time-wait +.. cfgcmd:: set system conntrack log udp destroy +.. cfgcmd:: set system conntrack log udp new +.. cfgcmd:: set system conntrack log udp update + + Log the connection tracking events per protocol.
\ No newline at end of file diff --git a/docs/configuration/system/eventhandler.rst b/docs/configuration/system/eventhandler.rst deleted file mode 100644 index 3eab4e2c..00000000 --- a/docs/configuration/system/eventhandler.rst +++ /dev/null @@ -1,51 +0,0 @@ -.. _event-handler: - -Event Handler -------------- - -Event handler allows you to execute scripts when a string that matches a regex -appears in a text stream (e.g. log file). - -It uses "feeds" (output of commands, or a named pipes) and "policies" that -define what to execute if a regex is matched. - -.. code-block:: none - - system - event-handler - feed <name> - description <feed description> - policy <policy name> - source - preset - syslog # Use the syslog logs for feed - custom - command <command to execute> # E.g. "tail -f /var/log/somelogfile" - named-pipe <path to a names pipe> - policy <policy name> - description <policy description> - event <event name> - description <event description> - pattern <regex> - run <command to run> - -In this small example a script runs every time a login failed and an interface -goes down - -.. code-block:: none - - vyos@vyos# show system event-handler - feed Syslog { - policy MyPolicy - source { - preset syslog - } - } - policy MyPolicy { - description "Test policy" - event BadThingsHappened { - pattern "authentication failure" - pattern "interface \.* index \d+ .* DOWN.*" - run /config/scripts/email-to-admin - } - }
\ No newline at end of file diff --git a/docs/configuration/system/host-name.rst b/docs/configuration/system/host-name.rst index 79fae851..d062fc62 100644 --- a/docs/configuration/system/host-name.rst +++ b/docs/configuration/system/host-name.rst @@ -46,7 +46,12 @@ Static Hostname Mapping How an IP address is assigned to an interface in :ref:`ethernet-interface`. This section shows how to statically map an IP address to a hostname for local -(meaning on this VyOS instance) name resolution. +(meaning on this VyOS instance) name resolution. This is the VyOS equivalent to +`/etc/hosts` file entries. + +.. note:: Do *not* manually edit `/etc/hosts`. This file will automatically be + regenerated on boot based on the settings in this section, which means you'll + lose all your manual edits. Instead, configure static host mappings as follows. .. cfgcmd:: set system static-host-mapping host-name <hostname> inet <address> diff --git a/docs/configuration/system/index.rst b/docs/configuration/system/index.rst index 9b4bf2e3..4df787a9 100644 --- a/docs/configuration/system/index.rst +++ b/docs/configuration/system/index.rst @@ -7,6 +7,7 @@ System :maxdepth: 1 :includehidden: + acceleration conntrack console flow-accounting @@ -16,10 +17,10 @@ System lcd login name-server - ntp option proxy syslog + sysctl task-scheduler time-zone @@ -29,4 +30,3 @@ System :includehidden: default-route - eventhandler diff --git a/docs/configuration/system/ip.rst b/docs/configuration/system/ip.rst index 78aeef4e..29f46ae9 100644 --- a/docs/configuration/system/ip.rst +++ b/docs/configuration/system/ip.rst @@ -9,6 +9,15 @@ System configuration commands Use this command to disable IPv4 forwarding on all interfaces. +.. cfgcmd:: set system ip disable-directed-broadcast + + Use this command to disable IPv4 directed broadcast forwarding on all + interfaces. + + If set, IPv4 directed broadcast forwarding will be completely disabled + regardless of whether per-interface directed broadcast forwarding is + enabled or not. + .. cfgcmd:: set system ip arp table-size <number> Use this command to define the maximum number of entries to keep in @@ -67,4 +76,4 @@ And the different IPv4 **reset** commands available: bgp Clear Border Gateway Protocol (BGP) statistics or status igmp IGMP clear commands multicast IP multicast routing table - route Reset IP route
\ No newline at end of file + route Reset IP route diff --git a/docs/configuration/system/ipv6.rst b/docs/configuration/system/ipv6.rst index 19016e7b..0b9f9cc8 100644 --- a/docs/configuration/system/ipv6.rst +++ b/docs/configuration/system/ipv6.rst @@ -160,7 +160,7 @@ Show commands Reset commands ^^^^^^^^^^^^^^ -.. opcmd:: reset ipv6 bgp <address> +.. opcmd:: reset bgp ipv6 <address> Use this command to clear Border Gateway Protocol statistics or status. diff --git a/docs/configuration/system/login.rst b/docs/configuration/system/login.rst index 08746201..a5c1b558 100644 --- a/docs/configuration/system/login.rst +++ b/docs/configuration/system/login.rst @@ -1,8 +1,10 @@ +:lastproofread: 2022-10-15 + .. _user_management: -############### -User Management -############### +##################### +Login/User Management +##################### The default VyOS user account (`vyos`), as well as newly created user accounts, have all capabilities to configure the system. All accounts have sudo @@ -52,6 +54,8 @@ and paste it. Some terminal emulators may accidentally split this over several lines. Be attentive when you paste it that it only pastes as a single line. The third part is simply an identifier, and is for your own reference. +.. seealso:: SSH :ref:`ssh_operation` + .. cfgcmd:: set system login user <username> authentication public-keys <identifier> key <key> @@ -77,44 +81,154 @@ The third part is simply an identifier, and is for your own reference. .. cfgcmd:: set system login user <username> authentication public-keys <identifier> options <options> - Set the options for this public key. See the ssh ``authorized_keys`` man page - for details of what you can specify here. To place a ``"`` character in the - options field, use ``"``, for example ``from="10.0.0.0/24"`` - to restrict where the user may connect from when using this key. + Set the options for this public key. See the ssh ``authorized_keys`` man + page for details of what you can specify here. To place a ``"`` + character in the options field, use ``"``, for example + ``from="10.0.0.0/24"`` to restrict where the user + may connect from when using this key. -.. cfgcmd:: loadkey <username> <location> +MFA/2FA authentication using OTP (one time passwords) +----------------------------------------------------- - **Deprecation notice:** ``loadkey`` has been deprecated in favour of - :opcmd:`generate public-key-commands` and will be removed in a future - version. See :ref:`ssh`. +It is possible to enhance authentication security by using the :abbr:`2FA +(Two-factor authentication)`/:abbr:`MFA (Multi-factor authentication)` feature +together with :abbr:`OTP (One-Time-Pad)` on VyOS. :abbr:`2FA (Two-factor +authentication)`/:abbr:`MFA (Multi-factor authentication)` is configured +independently per each user. If an OTP key is configured for a user, 2FA/MFA +is automatically enabled for that particular user. If a user does not have an +OTP key configured, there is no 2FA/MFA check for that user. - SSH keys can not only be specified on the command-line but also loaded for - a given user with `<username>` from a file pointed to by `<location>.` Keys - can be either loaded from local filesystem or any given remote location - using one of the following :abbr:`URIs (Uniform Resource Identifier)`: +.. cfgcmd:: set system login user <username> authentication otp key <key> - * ``<file>`` - Load from file on local filesystem path - * ``scp://<user>@<host>:/<file>`` - Load via SCP from remote machine - * ``sftp://<user>@<host>/<file>`` - Load via SFTP from remote machine - * ``ftp://<user>@<host>/<file>`` - Load via FTP from remote machine - * ``http://<host>/<file>`` - Load via HTTP from remote machine - * ``tftp://<host>/<file>`` - Load via TFTP from remote machine + Enable OTP 2FA for user `username` with default settings, using the BASE32 + encoded 2FA/MFA key specified by `<key>`. -Example -------- +Optional/default settings +^^^^^^^^^^^^^^^^^^^^^^^^^ -In the following example, both `User1` and `User2` will be able to SSH into -VyOS as user ``vyos`` using their very own keys. `User1` is restricted to only -be able to connect from a single IP address. +.. cfgcmd:: set system login user <username> authentication otp rate-limit <limit> + :defaultvalue: + + Limit logins to `<limit>` per every ``rate-time`` seconds. Rate limit + must be between 1 and 10 attempts. + +.. cfgcmd:: set system login user <username> authentication otp rate-time <seconds> + :defaultvalue: + + Limit logins to ``rate-limit`` attemps per every `<seconds>`. Rate time must + be between 15 and 600 seconds. + +.. cfgcmd:: set system login user <username> authentication otp window-size <size> + :defaultvalue: + + Set window of concurrently valid codes. + + By default, a new token is generated every 30 seconds by the mobile + application. In order to compensate for possible time-skew between + the client and the server, an extra token before and after the current + time is allowed. This allows for a time skew of up to 30 seconds + between authentication server and client. + + For example, if problems with poor time synchronization are experienced, + the window can be increased from its default size of 3 permitted codes + (one previous code, the current code, the next code) to 17 permitted codes + (the 8 previous codes, the current code, and the 8 next codes). This will + permit for a time skew of up to 4 minutes between client and server. + + The window size must be between 1 and 21. + +OTP-key generation +^^^^^^^^^^^^^^^^^^ + +The following command can be used to generate the OTP key as well +as the CLI commands to configure them: + +.. cfgcmd:: generate system login username <username> otp-key hotp-time + rate-limit <1-10> rate-time <15-600> window-size <1-21> + +An example of key generation: .. code-block:: none - set system login user vyos authentication public-keys 'User1' key "AAAAB3Nz...KwEW" - set system login user vyos authentication public-keys 'User1' type ssh-rsa - set system login user vyos authentication public-keys 'User1' options "from="192.168.0.100"" - set system login user vyos authentication public-keys 'User2' key "AAAAQ39x...fbV3" - set system login user vyos authentication public-keys 'User2' type ssh-rsa + vyos@vyos:~$ generate system login username otptester otp-key hotp-time rate-limit 2 rate-time 20 window-size 5 + # You can share it with the user, he just needs to scan the QR in his OTP app + # username: otptester + # OTP KEY: J5A64ERPMGJOZXY6FMHHLKXKANNI6TCY + # OTP URL: otpauth://totp/otptester@vyos?secret=J5A64ERPMGJOZXY6FMHHLKXKANNI6TCY&digits=6&period=30 + █████████████████████████████████████████████ + █████████████████████████████████████████████ + ████ ▄▄▄▄▄ █▀█ █▄ ▀▄▀▄█▀▄ ▀█▀ █ ▄▄▄▄▄ ████ + ████ █ █ █▀▀▀█ ▄▀ █▄▀ ▀▄ ▄ ▀ ▄█ █ █ ████ + ████ █▄▄▄█ █▀ █▀▀██▄▄ █ █ ██ ▀▄▀ █ █▄▄▄█ ████ + ████▄▄▄▄▄▄▄█▄▀ ▀▄█ █ ▀ █ █ █ █▄█▄█▄▄▄▄▄▄▄████ + ████ ▄ █▄ ▄ ▀▄▀▀▀▀▄▀▄▀▄▄▄▀▀▄▄▄ █ █▄█ █████ + ████▄▄ ██▀▄▄▄▀▀█▀ ▄ ▄▄▄ ▄▀ ▀ █ ▄ ▄ ██▄█ ████ + █████▄ ██▄▄▀█▄█▄█▄ ▀█▄▀▄ ▀█▀▄ █▄▄▄ ▄ ▄████ + ████▀▀▄ ▄█▀▄▀ ▄█▀█▀▄▄▄▀█▄ ██▄▄▄ ▀█ █ ████ + ████ ▄▀▄█▀▄▄█▀▀▄▀▀▀▀█ ▄▀▄▀ ▄█ ▀▄ ▄ ▄▀ █▄████ + ████▄ ██ ▀▄▀▀ ▄█▀ ▄ ██ ▀█▄█ ▄█ ▄ ▀▄ ▄▄ ████ + ████▄█▀▀▄ ▄▄ █▄█▄█▄ █▄▄▀▄▄▀▀▄▄██▀ ▄▀▄▄ ▀▄████ + ████▀▄▀ ▄ ▄▀█ ▄ ▄█▀ █ ▀▄▄ ▄█▀ ▄▄ ▀▄▄ ████ + ████ ▀███▄ █▄█▄▀▀▀▀▄ ▄█▄▄▀ ▀███ ▄▄█▄▄ ▄████ + ████ ███▀ ▄▄▀▀██▀ ▄▀▄█▄▄▄ ██▄▄▀▄▀ ███▄ ▄████ + ████▄████▄▄▄▀▄ █▄█▄▀▄▄▄▄██▀ ▄▀ ▄ ▄▄▄ █▄▄█████ + ████ ▄▄▄▄▄ █▄▄▄ ▄█▀█▀▀▀▀█▀█▀ █▄█ █▄█ ▄█ ████ + ████ █ █ █ ██▄▀▀▀▀▄▄▄▀ ▄▄▄ ▀ ▄ ▄ ▄▄████ + ████ █▄▄▄█ █ ▀▀█▀ ▄▄█ █▄▄██▀▀█▀ █▄▀▄██▄█ ████ + ████▄▄▄▄▄▄▄█▄█▄█▄█▄▄▄▄▄█▄▄▄█▄██████▄██▄▄▄████ + █████████████████████████████████████████████ + █████████████████████████████████████████████ + # To add this OTP key to configuration, run the following commands: + set system login user otptester authentication otp key 'J5A64ERPMGJOZXY6FMHHLKXKANNI6TCY' + set system login user otptester authentication otp rate-limit '2' + set system login user otptester authentication otp rate-time '20' + set system login user otptester authentication otp window-size '5' + +Display OTP key for user +^^^^^^^^^^^^^^^^^^^^^^^^ + +To display the configured OTP user key, use the command: + +.. cfgcmd:: sh system login authentication user <username> otp + <full|key-b32|qrcode|uri> + +An example: + +.. code-block:: none + vyos@vyos:~$ sh system login authentication user otptester otp full + # You can share it with the user, he just needs to scan the QR in his OTP app + # username: otptester + # OTP KEY: J5A64ERPMGJOZXY6FMHHLKXKANNI6TCY + # OTP URL: otpauth://totp/otptester@vyos?secret=J5A64ERPMGJOZXY6FMHHLKXKANNI6TCY&digits=6&period=30 + █████████████████████████████████████████████ + █████████████████████████████████████████████ + ████ ▄▄▄▄▄ █▀█ █▄ ▀▄▀▄█▀▄ ▀█▀ █ ▄▄▄▄▄ ████ + ████ █ █ █▀▀▀█ ▄▀ █▄▀ ▀▄ ▄ ▀ ▄█ █ █ ████ + ████ █▄▄▄█ █▀ █▀▀██▄▄ █ █ ██ ▀▄▀ █ █▄▄▄█ ████ + ████▄▄▄▄▄▄▄█▄▀ ▀▄█ █ ▀ █ █ █ █▄█▄█▄▄▄▄▄▄▄████ + ████ ▄ █▄ ▄ ▀▄▀▀▀▀▄▀▄▀▄▄▄▀▀▄▄▄ █ █▄█ █████ + ████▄▄ ██▀▄▄▄▀▀█▀ ▄ ▄▄▄ ▄▀ ▀ █ ▄ ▄ ██▄█ ████ + █████▄ ██▄▄▀█▄█▄█▄ ▀█▄▀▄ ▀█▀▄ █▄▄▄ ▄ ▄████ + ████▀▀▄ ▄█▀▄▀ ▄█▀█▀▄▄▄▀█▄ ██▄▄▄ ▀█ █ ████ + ████ ▄▀▄█▀▄▄█▀▀▄▀▀▀▀█ ▄▀▄▀ ▄█ ▀▄ ▄ ▄▀ █▄████ + ████▄ ██ ▀▄▀▀ ▄█▀ ▄ ██ ▀█▄█ ▄█ ▄ ▀▄ ▄▄ ████ + ████▄█▀▀▄ ▄▄ █▄█▄█▄ █▄▄▀▄▄▀▀▄▄██▀ ▄▀▄▄ ▀▄████ + ████▀▄▀ ▄ ▄▀█ ▄ ▄█▀ █ ▀▄▄ ▄█▀ ▄▄ ▀▄▄ ████ + ████ ▀███▄ █▄█▄▀▀▀▀▄ ▄█▄▄▀ ▀███ ▄▄█▄▄ ▄████ + ████ ███▀ ▄▄▀▀██▀ ▄▀▄█▄▄▄ ██▄▄▀▄▀ ███▄ ▄████ + ████▄████▄▄▄▀▄ █▄█▄▀▄▄▄▄██▀ ▄▀ ▄ ▄▄▄ █▄▄█████ + ████ ▄▄▄▄▄ █▄▄▄ ▄█▀█▀▀▀▀█▀█▀ █▄█ █▄█ ▄█ ████ + ████ █ █ █ ██▄▀▀▀▀▄▄▄▀ ▄▄▄ ▀ ▄ ▄ ▄▄████ + ████ █▄▄▄█ █ ▀▀█▀ ▄▄█ █▄▄██▀▀█▀ █▄▀▄██▄█ ████ + ████▄▄▄▄▄▄▄█▄█▄█▄█▄▄▄▄▄█▄▄▄█▄██████▄██▄▄▄████ + █████████████████████████████████████████████ + █████████████████████████████████████████████ + # To add this OTP key to configuration, run the following commands: + set system login user otptester authentication otp key 'J5A64ERPMGJOZXY6FMHHLKXKANNI6TCY' + set system login user otptester authentication otp rate-limit '2' + set system login user otptester authentication otp rate-time '20' + set system login user otptester authentication otp window-size '5' RADIUS ====== @@ -158,7 +272,6 @@ Configuration the attribute you will only get regular, non privilegued, system users. - Login Banner ============ @@ -176,3 +289,25 @@ information for this system. .. note:: To create a new line in your login message you need to escape the new line character by using ``\\n``. + + +Example +======= + +In the following example, both `User1` and `User2` will be able to SSH into +VyOS as user ``vyos`` using their very own keys. `User1` is restricted to only +be able to connect from a single IP address. In addition if password base login +is wanted for the ``vyos`` user a 2FA/MFA keycode is required in addition to +the password. + +.. code-block:: none + + set system login user vyos authentication public-keys 'User1' key "AAAAB3Nz...KwEW" + set system login user vyos authentication public-keys 'User1' type ssh-rsa + set system login user vyos authentication public-keys 'User1' options "from="192.168.0.100"" + + set system login user vyos authentication public-keys 'User2' key "AAAAQ39x...fbV3" + set system login user vyos authentication public-keys 'User2' type ssh-rsa + + set system login user vyos authentication otp key OHZ3OJ7U2N25BK4G7SOFFJTZDTCFUUE2 + set system login user vyos authentication plaintext-password vyos diff --git a/docs/configuration/system/option.rst b/docs/configuration/system/option.rst index a4e08245..c9c9bfb1 100644 --- a/docs/configuration/system/option.rst +++ b/docs/configuration/system/option.rst @@ -39,6 +39,20 @@ HTTP client .. note:: `source-address` and `source-interface` can not be used at the same time. +********** +SSH client +********** + +.. cfgcmd:: set system option ssh-client source-address <address> + + Use the specified address on the local machine as the source address of the + connection. Only useful on systems with more than one address. + +.. cfgcmd:: set system option ssh-client source-interface <interface> + + Use the address of the specified interface on the local machine as the + source address of the connection. + *************** Keyboard Layout *************** diff --git a/docs/configuration/system/sysctl.disable b/docs/configuration/system/sysctl.disable deleted file mode 100644 index 82ffd159..00000000 --- a/docs/configuration/system/sysctl.disable +++ /dev/null @@ -1,2 +0,0 @@ -sysctl -######
\ No newline at end of file diff --git a/docs/configuration/system/sysctl.rst b/docs/configuration/system/sysctl.rst new file mode 100644 index 00000000..06e15031 --- /dev/null +++ b/docs/configuration/system/sysctl.rst @@ -0,0 +1,12 @@ +.. _sysctl: + +###### +Sysctl +###### + +This chapeter describes how to configure kernel parameters at runtime. + +``sysctl`` is used to modify kernel parameters at runtime. The parameters +available are those listed under /proc/sys/. + +.. cfgcmd:: set system sysctl parameter <parameter> value <value> diff --git a/docs/configuration/vpn/dmvpn.rst b/docs/configuration/vpn/dmvpn.rst index f2c7b162..66fc79da 100644 --- a/docs/configuration/vpn/dmvpn.rst +++ b/docs/configuration/vpn/dmvpn.rst @@ -218,7 +218,7 @@ Hub set vpn ipsec ike-group IKE-HUB proposal 2 encryption 'aes128' set vpn ipsec ike-group IKE-HUB proposal 2 hash 'sha1' - set vpn ipsec ipsec-interfaces interface 'eth0' + set vpn ipsec interface 'eth0' set vpn ipsec profile NHRPVPN authentication mode 'pre-shared-secret' set vpn ipsec profile NHRPVPN authentication pre-shared-secret 'secret' @@ -278,6 +278,7 @@ spoke01-spoke04 ip nhrp registration timeout 75 tunnel source FastEthernet0/0 tunnel mode gre multipoint + tunnel protection ipsec profile DMVPN tunnel key 1 ! interface FastEthernet0/0 @@ -327,7 +328,7 @@ VyOS can also run in DMVPN spoke mode. set vpn ipsec ike-group IKE-HUB proposal 2 encryption 'aes128' set vpn ipsec ike-group IKE-HUB proposal 2 hash 'sha1' - set vpn ipsec ipsec-interfaces interface 'eth0' + set vpn ipsec interface 'eth0' set vpn ipsec profile NHRPVPN authentication mode 'pre-shared-secret' set vpn ipsec profile NHRPVPN authentication pre-shared-secret 'secret' diff --git a/docs/configuration/vpn/ipsec.rst b/docs/configuration/vpn/ipsec.rst index 693f3ec6..d6a4733c 100644 --- a/docs/configuration/vpn/ipsec.rst +++ b/docs/configuration/vpn/ipsec.rst @@ -111,6 +111,8 @@ VyOS IKE group has the next options: * ``hash`` hash algorithm. + * ``prf`` pseudo-random function. + *********************************************** ESP (Encapsulating Security Payload) Attributes *********************************************** @@ -166,7 +168,7 @@ VyOS ESP group has the next options: *********************************************** Options (Global IPsec settings) Attributes *********************************************** -* ``options`` IPsec settings: +* ``options`` * ``disable-route-autoinstall`` Do not automatically install routes to remote networks; @@ -198,7 +200,7 @@ On the LEFT: set interfaces tunnel tun0 address 10.10.10.1/30 ## IPsec - set vpn ipsec ipsec-interfaces interface eth0 + set vpn ipsec interface eth0 # IKE group set vpn ipsec ike-group MyIKEGroup proposal 1 dh-group '2' @@ -210,16 +212,18 @@ On the LEFT: set vpn ipsec esp-group MyESPGroup proposal 1 hash 'sha1' # IPsec tunnel - set vpn ipsec site-to-site peer 203.0.113.45 authentication mode pre-shared-secret - set vpn ipsec site-to-site peer 203.0.113.45 authentication pre-shared-secret MYSECRETKEY + set vpn ipsec site-to-site peer right authentication mode pre-shared-secret + set vpn ipsec site-to-site peer right authentication pre-shared-secret MYSECRETKEY + set vpn ipsec site-to-site peer right authentication remote-id 203.0.113.45 - set vpn ipsec site-to-site peer 203.0.113.45 ike-group MyIKEGroup - set vpn ipsec site-to-site peer 203.0.113.45 default-esp-group MyESPGroup + set vpn ipsec site-to-site peer right ike-group MyIKEGroup + set vpn ipsec site-to-site peer right default-esp-group MyESPGroup - set vpn ipsec site-to-site peer 203.0.113.45 local-address 192.0.2.10 + set vpn ipsec site-to-site peer right local-address 192.0.2.10 + set vpn ipsec site-to-site peer right remote-address 203.0.113.45 # This will match all GRE traffic to the peer - set vpn ipsec site-to-site peer 203.0.113.45 tunnel 1 protocol gre + set vpn ipsec site-to-site peer right tunnel 1 protocol gre On the RIGHT, setup by analogy and swap local and remote addresses. @@ -235,6 +239,8 @@ an IPsec policy to match those loopback addresses. We assume that the LEFT router has static 192.0.2.10 address on eth0, and the RIGHT router has a dynamic address on eth0. +The peer names RIGHT and LEFT are used as informational text. + **Setting up the GRE tunnel** On the LEFT: @@ -325,17 +331,17 @@ On the LEFT (static address): set vpn ipsec ike-group MyIKEGroup proposal 1 encryption aes128 set vpn ipsec ike-group MyIKEGroup proposal 1 hash sha1 - set vpn ipsec site-to-site peer @RIGHT authentication id LEFT - set vpn ipsec site-to-site peer @RIGHT authentication mode rsa - set vpn ipsec site-to-site peer @RIGHT authentication rsa local-key ipsec-LEFT - set vpn ipsec site-to-site peer @RIGHT authentication rsa remote-key ipsec-RIGHT - set vpn ipsec site-to-site peer @RIGHT authentication remote-id RIGHT - set vpn ipsec site-to-site peer @RIGHT default-esp-group MyESPGroup - set vpn ipsec site-to-site peer @RIGHT ike-group MyIKEGroup - set vpn ipsec site-to-site peer @RIGHT local-address 192.0.2.10 - set vpn ipsec site-to-site peer @RIGHT connection-type respond - set vpn ipsec site-to-site peer @RIGHT tunnel 1 local prefix 192.168.99.1/32 # Additional loopback address on the local - set vpn ipsec site-to-site peer @RIGHT tunnel 1 remote prefix 192.168.99.2/32 # Additional loopback address on the remote + set vpn ipsec site-to-site peer RIGHT authentication local-id LEFT + set vpn ipsec site-to-site peer RIGHT authentication mode rsa + set vpn ipsec site-to-site peer RIGHT authentication rsa local-key ipsec-LEFT + set vpn ipsec site-to-site peer RIGHT authentication rsa remote-key ipsec-RIGHT + set vpn ipsec site-to-site peer RIGHT authentication remote-id RIGHT + set vpn ipsec site-to-site peer RIGHT default-esp-group MyESPGroup + set vpn ipsec site-to-site peer RIGHT ike-group MyIKEGroup + set vpn ipsec site-to-site peer RIGHT local-address 192.0.2.10 + set vpn ipsec site-to-site peer RIGHT connection-type respond + set vpn ipsec site-to-site peer RIGHT tunnel 1 local prefix 192.168.99.1/32 # Additional loopback address on the local + set vpn ipsec site-to-site peer RIGHT tunnel 1 remote prefix 192.168.99.2/32 # Additional loopback address on the remote On the RIGHT (dynamic address): @@ -350,14 +356,15 @@ On the RIGHT (dynamic address): set vpn ipsec ike-group MyIKEGroup proposal 1 encryption aes128 set vpn ipsec ike-group MyIKEGroup proposal 1 hash sha1 - set vpn ipsec site-to-site peer 192.0.2.10 authentication id RIGHT - set vpn ipsec site-to-site peer 192.0.2.10 authentication mode rsa - set vpn ipsec site-to-site peer 192.0.2.10 authentication rsa local-key ipsec-RIGHT - set vpn ipsec site-to-site peer 192.0.2.10 authentication rsa remote-key ipsec-LEFT - set vpn ipsec site-to-site peer 192.0.2.10 authentication remote-id LEFT - set vpn ipsec site-to-site peer 192.0.2.10 connection-type initiate - set vpn ipsec site-to-site peer 192.0.2.10 default-esp-group MyESPGroup - set vpn ipsec site-to-site peer 192.0.2.10 ike-group MyIKEGroup - set vpn ipsec site-to-site peer 192.0.2.10 local-address any - set vpn ipsec site-to-site peer 192.0.2.10 tunnel 1 local prefix 192.168.99.2/32 # Additional loopback address on the local - set vpn ipsec site-to-site peer 192.0.2.10 tunnel 1 remote prefix 192.168.99.1/32 # Additional loopback address on the remote + set vpn ipsec site-to-site peer LEFT authentication local-id RIGHT + set vpn ipsec site-to-site peer LEFT authentication mode rsa + set vpn ipsec site-to-site peer LEFT authentication rsa local-key ipsec-RIGHT + set vpn ipsec site-to-site peer LEFT authentication rsa remote-key ipsec-LEFT + set vpn ipsec site-to-site peer LEFT authentication remote-id LEFT + set vpn ipsec site-to-site peer LEFT connection-type initiate + set vpn ipsec site-to-site peer LEFT default-esp-group MyESPGroup + set vpn ipsec site-to-site peer LEFT ike-group MyIKEGroup + set vpn ipsec site-to-site peer LEFT local-address any + set vpn ipsec site-to-site peer LEFT remote-address 192.0.2.10 + set vpn ipsec site-to-site peer LEFT tunnel 1 local prefix 192.168.99.2/32 # Additional loopback address on the local + set vpn ipsec site-to-site peer LEFT tunnel 1 remote prefix 192.168.99.1/32 # Additional loopback address on the remote diff --git a/docs/configuration/vpn/l2tp.rst b/docs/configuration/vpn/l2tp.rst index 411b7b5e..8dc34ee4 100644 --- a/docs/configuration/vpn/l2tp.rst +++ b/docs/configuration/vpn/l2tp.rst @@ -14,7 +14,7 @@ with native Windows and Mac VPN clients): .. code-block:: none - set vpn ipsec ipsec-interfaces interface eth0 + set vpn ipsec interface eth0 set vpn l2tp remote-access outside-address 192.0.2.2 set vpn l2tp remote-access client-ip-pool start 192.168.255.2 @@ -24,7 +24,7 @@ with native Windows and Mac VPN clients): set vpn l2tp remote-access authentication mode local set vpn l2tp remote-access authentication local-users username test password 'test' -In the example above an external IP of 192.0.2.2 is assumed. +In the above example, an external IP of 192.0.2.2 is assumed. If a local firewall policy is in place on your external interface you will need to allow the ports below: diff --git a/docs/configuration/vpn/openconnect.rst b/docs/configuration/vpn/openconnect.rst index 7a279472..1b4d4b4c 100644 --- a/docs/configuration/vpn/openconnect.rst +++ b/docs/configuration/vpn/openconnect.rst @@ -48,7 +48,7 @@ Server Configuration set vpn openconnect authentication local-users username <user> password <pass> set vpn openconnect authentication mode <local password|radius> - set vpn opneconnect network-settings client-ip-settings subnet <subnet> + set vpn openconnect network-settings client-ip-settings subnet <subnet> set vpn openconnect network-settings name-server <address> set vpn openconnect network-settings name-server <address> set vpn openconnect ssl ca-certificate <pki-ca-name> @@ -56,7 +56,7 @@ Server Configuration set vpn openconnect ssl passphrase <pki-password> 2FA OTP support -==================== +=============== Instead of password only authentication, 2FA password authentication + OTP key can be used. Alternatively, OTP authentication only, @@ -215,3 +215,40 @@ and then the OTP key. .. warning:: When using Time-based one-time password (TOTP) (OTP HOTP-time), be sure that the time on the server and the OTP token generator are synchronized by NTP + +To display the configured OTP user settings, use the command: + +.. code-block:: none + + show openconnect-server user <username> otp <full|key-b32|key-hex|qrcode|uri> + +Configuring RADIUS accounting +============================= + +OpenConnect can be configured to send accounting information to a +RADIUS server to capture user session data such as time of +connect/disconnect, data transferred, and so on. + +Configure an accounting server and enable accounting with: + +.. code-block:: none + + set vpn openconnect accounting mode radius + set vpn openconnect accounting radius server 172.20.20.10 + set vpn openconnect accounting radius server 172.20.20.10 port 1813 + set vpn openconnect accounting radius server 172.20.20.10 key your_radius_secret + +.. warning:: The RADIUS accounting feature must be used with the OpenConnect + authentication mode RADIUS. It cannot be used with local authentication. + You must configure the OpenConnect authentication mode to "radius". + +An example of the data captured by a FREERADIUS server with sql accounting: + +.. code-block:: none + + mysql> SELECT username, nasipaddress, acctstarttime, acctstoptime, acctinputoctets, acctoutputoctets, callingstationid, framedipaddress, connectinfo_start FROM radacct; + +----------+---------------+---------------------+---------------------+-----------------+------------------+-------------------+-----------------+-----------------------------------+ + | username | nasipaddress | acctstarttime | acctstoptime | acctinputoctets | acctoutputoctets | callingstationid | framedipaddress | connectinfo_start | + +----------+---------------+---------------------+---------------------+-----------------+------------------+-------------------+-----------------+-----------------------------------+ + | test | 198.51.100.15 | 2023-01-13 00:59:15 | 2023-01-13 00:59:21 | 10606 | 152 | 192.168.6.1 | 172.20.20.198 | Open AnyConnect VPN Agent v8.05-1 | + +----------+---------------+---------------------+---------------------+-----------------+------------------+-------------------+-----------------+-----------------------------------+ diff --git a/docs/configuration/vpn/site2site_ipsec.rst b/docs/configuration/vpn/site2site_ipsec.rst index 2fa59dc1..68f6c48b 100644 --- a/docs/configuration/vpn/site2site_ipsec.rst +++ b/docs/configuration/vpn/site2site_ipsec.rst @@ -8,26 +8,18 @@ to exchange encrypted information between them and VyOS itself or connected/routed networks. To configure site-to-site connection you need to add peers with the -``set vpn ipsec site-to-site`` command. +``set vpn ipsec site-to-site peer <name>`` command. -You can identify a remote peer with: - -* IPv4 or IPv6 address. This mode is easiest for configuration and mostly used - when a peer has a public static IP address; -* Hostname. This mode is similar to IP address, only you define DNS name instead - of an IP. Could be used when a peer has a public IP address and DNS name, but - an IP address could be changed from time to time; -* Remote ID of the peer. In this mode, there is no predefined remote address - nor DNS name of the peer. This mode is useful when a peer doesn't have a - publicly available IP address (NAT between it and VyOS), or IP address could - be changed. +The peer name must be an alphanumeric and can have hypen or underscore as +special characters. It is purely informational. Each site-to-site peer has the next options: * ``authentication`` - configure authentication between VyOS and a remote peer. Suboptions: - * ``id`` - ID for the local VyOS router. If defined, during the authentication + * ``local-id`` - ID for the local VyOS router. If defined, during the + authentication it will be send to remote peer; * ``mode`` - mode for authentication between VyOS and remote peer: @@ -96,26 +88,25 @@ Each site-to-site peer has the next options: * ``dhcp-interface`` - use an IP address, received from DHCP for IPSec connection with this peer, instead of ``local-address``; -* ``force-encapsulation`` - force encapsulation of ESP into UDP datagrams. +* ``force-udp-encapsulation`` - force encapsulation of ESP into UDP datagrams. Useful in case if between local and remote side is firewall or NAT, which not allows passing plain ESP packets between them; * ``ike-group`` - IKE group to use for key exchanges; * ``ikev2-reauth`` - reauthenticate remote peer during the rekeying process. - Can be used only with IKEv2: - - * ``yes`` - create a new IKE_SA from the scratch and try to recreate all - IPsec SAs; - - * ``no`` - rekey without uninstalling the IPsec SAs; - - * ``inherit`` - use default behavior for the used IKE group. + Can be used only with IKEv2. + Create a new IKE_SA from the scratch and try to recreate all IPsec SAs; * ``local-address`` - local IP address for IPSec connection with this peer. If defined ``any``, then an IP address which configured on interface with default route will be used; +* ``remote-address`` - remote IP address or hostname for IPSec connection. + IPv4 or IPv6 address is used when a peer has a public static IP address. + Hostname is a DNS name which could be used when a peer has a public IP + address and DNS name, but an IP address could be changed from time to time. + * ``tunnel`` - define criteria for traffic to be matched for encrypting and send it to a peer: @@ -170,50 +161,46 @@ Example: .. code-block:: none # server config - set vpn ipsec esp-group office-srv-esp compression 'disable' set vpn ipsec esp-group office-srv-esp lifetime '1800' set vpn ipsec esp-group office-srv-esp mode 'tunnel' set vpn ipsec esp-group office-srv-esp pfs 'enable' set vpn ipsec esp-group office-srv-esp proposal 1 encryption 'aes256' set vpn ipsec esp-group office-srv-esp proposal 1 hash 'sha1' - set vpn ipsec ike-group office-srv-ike ikev2-reauth 'no' set vpn ipsec ike-group office-srv-ike key-exchange 'ikev1' set vpn ipsec ike-group office-srv-ike lifetime '3600' set vpn ipsec ike-group office-srv-ike proposal 1 encryption 'aes256' set vpn ipsec ike-group office-srv-ike proposal 1 hash 'sha1' - set vpn ipsec ipsec-interfaces interface 'eth1' - set vpn ipsec site-to-site peer 203.0.113.2 authentication mode 'pre-shared-secret' - set vpn ipsec site-to-site peer 203.0.113.2 authentication pre-shared-secret 'SomePreSharedKey' - set vpn ipsec site-to-site peer 203.0.113.2 ike-group 'office-srv-ike' - set vpn ipsec site-to-site peer 203.0.113.2 local-address '198.51.100.3' - set vpn ipsec site-to-site peer 203.0.113.2 tunnel 0 allow-nat-networks 'disable' - set vpn ipsec site-to-site peer 203.0.113.2 tunnel 0 allow-public-networks 'disable' - set vpn ipsec site-to-site peer 203.0.113.2 tunnel 0 esp-group 'office-srv-esp' - set vpn ipsec site-to-site peer 203.0.113.2 tunnel 0 local prefix '192.168.0.0/24' - set vpn ipsec site-to-site peer 203.0.113.2 tunnel 0 remote prefix '10.0.0.0/21' + set vpn ipsec interface 'eth1' + set vpn ipsec site-to-site peer OFFICE-B authentication mode 'pre-shared-secret' + set vpn ipsec site-to-site peer OFFICE-B authentication pre-shared-secret 'SomePreSharedKey' + set vpn ipsec site-to-site peer OFFICE-B authentication remote-id '203.0.113.2' + set vpn ipsec site-to-site peer OFFICE-B ike-group 'office-srv-ike' + set vpn ipsec site-to-site peer OFFICE-B local-address '198.51.100.3' + set vpn ipsec site-to-site peer OFFICE-B remote-address '203.0.113.2' + set vpn ipsec site-to-site peer OFFICE-B tunnel 0 esp-group 'office-srv-esp' + set vpn ipsec site-to-site peer OFFICE-B tunnel 0 local prefix '192.168.0.0/24' + set vpn ipsec site-to-site peer OFFICE-B tunnel 0 remote prefix '10.0.0.0/21' # remote office config - set vpn ipsec esp-group office-srv-esp compression 'disable' set vpn ipsec esp-group office-srv-esp lifetime '1800' set vpn ipsec esp-group office-srv-esp mode 'tunnel' set vpn ipsec esp-group office-srv-esp pfs 'enable' set vpn ipsec esp-group office-srv-esp proposal 1 encryption 'aes256' set vpn ipsec esp-group office-srv-esp proposal 1 hash 'sha1' - set vpn ipsec ike-group office-srv-ike ikev2-reauth 'no' set vpn ipsec ike-group office-srv-ike key-exchange 'ikev1' set vpn ipsec ike-group office-srv-ike lifetime '3600' set vpn ipsec ike-group office-srv-ike proposal 1 encryption 'aes256' set vpn ipsec ike-group office-srv-ike proposal 1 hash 'sha1' - set vpn ipsec ipsec-interfaces interface 'eth1' - set vpn ipsec site-to-site peer 198.51.100.3 authentication mode 'pre-shared-secret' - set vpn ipsec site-to-site peer 198.51.100.3 authentication pre-shared-secret 'SomePreSharedKey' - set vpn ipsec site-to-site peer 198.51.100.3 ike-group 'office-srv-ike' - set vpn ipsec site-to-site peer 198.51.100.3 local-address '203.0.113.2' - set vpn ipsec site-to-site peer 198.51.100.3 tunnel 0 allow-nat-networks 'disable' - set vpn ipsec site-to-site peer 198.51.100.3 tunnel 0 allow-public-networks 'disable' - set vpn ipsec site-to-site peer 198.51.100.3 tunnel 0 esp-group 'office-srv-esp' - set vpn ipsec site-to-site peer 198.51.100.3 tunnel 0 local prefix '10.0.0.0/21' - set vpn ipsec site-to-site peer 198.51.100.3 tunnel 0 remote prefix '192.168.0.0/24' + set vpn ipsec interface 'eth1' + set vpn ipsec site-to-site peer OFFICE-A authentication mode 'pre-shared-secret' + set vpn ipsec site-to-site peer OFFICE-A authentication pre-shared-secret 'SomePreSharedKey' + set vpn ipsec site-to-site peer OFFICE-A authentication remote-id '198.51.100.3' + set vpn ipsec site-to-site peer OFFICE-A ike-group 'office-srv-ike' + set vpn ipsec site-to-site peer OFFICE-A local-address '203.0.113.2' + set vpn ipsec site-to-site peer OFFICE-A remote-address '198.51.100.3' + set vpn ipsec site-to-site peer OFFICE-A tunnel 0 esp-group 'office-srv-esp' + set vpn ipsec site-to-site peer OFFICE-A tunnel 0 local prefix '10.0.0.0/21' + set vpn ipsec site-to-site peer OFFICE-A tunnel 0 remote prefix '192.168.0.0/24' Show status of new setup: @@ -292,30 +279,28 @@ Imagine the following topology set interfaces vti vti10 address '10.0.0.2/31' - set vpn ipsec esp-group ESP_DEFAULT compression 'disable' set vpn ipsec esp-group ESP_DEFAULT lifetime '3600' set vpn ipsec esp-group ESP_DEFAULT mode 'tunnel' set vpn ipsec esp-group ESP_DEFAULT pfs 'dh-group19' set vpn ipsec esp-group ESP_DEFAULT proposal 10 encryption 'aes256gcm128' set vpn ipsec esp-group ESP_DEFAULT proposal 10 hash 'sha256' - set vpn ipsec ike-group IKEv2_DEFAULT ikev2-reauth 'no' set vpn ipsec ike-group IKEv2_DEFAULT key-exchange 'ikev2' set vpn ipsec ike-group IKEv2_DEFAULT lifetime '10800' - set vpn ipsec ike-group IKEv2_DEFAULT mobike 'disable' + set vpn ipsec ike-group IKEv2_DEFAULT disable-mobike set vpn ipsec ike-group IKEv2_DEFAULT proposal 10 dh-group '19' set vpn ipsec ike-group IKEv2_DEFAULT proposal 10 encryption 'aes256gcm128' set vpn ipsec ike-group IKEv2_DEFAULT proposal 10 hash 'sha256' - set vpn ipsec ipsec-interfaces interface 'eth0.201' - set vpn ipsec site-to-site peer 172.18.202.10 authentication id '172.18.201.10' - set vpn ipsec site-to-site peer 172.18.202.10 authentication mode 'pre-shared-secret' - set vpn ipsec site-to-site peer 172.18.202.10 authentication pre-shared-secret 'secretkey' - set vpn ipsec site-to-site peer 172.18.202.10 authentication remote-id '172.18.202.10' - set vpn ipsec site-to-site peer 172.18.202.10 connection-type 'respond' - set vpn ipsec site-to-site peer 172.18.202.10 ike-group 'IKEv2_DEFAULT' - set vpn ipsec site-to-site peer 172.18.202.10 ikev2-reauth 'inherit' - set vpn ipsec site-to-site peer 172.18.202.10 local-address '192.168.0.10' - set vpn ipsec site-to-site peer 172.18.202.10 vti bind 'vti10' - set vpn ipsec site-to-site peer 172.18.202.10 vti esp-group 'ESP_DEFAULT' + set vpn ipsec interface 'eth0.201' + set vpn ipsec site-to-site peer OFFICE-B authentication local-id '172.18.201.10' + set vpn ipsec site-to-site peer OFFICE-B authentication mode 'pre-shared-secret' + set vpn ipsec site-to-site peer OFFICE-B authentication pre-shared-secret 'secretkey' + set vpn ipsec site-to-site peer OFFICE-B authentication remote-id '172.18.202.10' + set vpn ipsec site-to-site peer OFFICE-B connection-type 'respond' + set vpn ipsec site-to-site peer OFFICE-B ike-group 'IKEv2_DEFAULT' + set vpn ipsec site-to-site peer OFFICE-B local-address '192.168.0.10' + set vpn ipsec site-to-site peer OFFICE-B remote-address '172.18.202.10' + set vpn ipsec site-to-site peer OFFICE-B vti bind 'vti10' + set vpn ipsec site-to-site peer OFFICE-B vti esp-group 'ESP_DEFAULT' **right** @@ -323,7 +308,6 @@ Imagine the following topology set interfaces vti vti10 address '10.0.0.3/31' - set vpn ipsec esp-group ESP_DEFAULT compression 'disable' set vpn ipsec esp-group ESP_DEFAULT lifetime '3600' set vpn ipsec esp-group ESP_DEFAULT mode 'tunnel' set vpn ipsec esp-group ESP_DEFAULT pfs 'dh-group19' @@ -332,31 +316,30 @@ Imagine the following topology set vpn ipsec ike-group IKEv2_DEFAULT dead-peer-detection action 'restart' set vpn ipsec ike-group IKEv2_DEFAULT dead-peer-detection interval '30' set vpn ipsec ike-group IKEv2_DEFAULT dead-peer-detection timeout '120' - set vpn ipsec ike-group IKEv2_DEFAULT ikev2-reauth 'no' set vpn ipsec ike-group IKEv2_DEFAULT key-exchange 'ikev2' set vpn ipsec ike-group IKEv2_DEFAULT lifetime '10800' - set vpn ipsec ike-group IKEv2_DEFAULT mobike 'disable' + set vpn ipsec ike-group IKEv2_DEFAULT disable-mobike set vpn ipsec ike-group IKEv2_DEFAULT proposal 10 dh-group '19' set vpn ipsec ike-group IKEv2_DEFAULT proposal 10 encryption 'aes256gcm128' set vpn ipsec ike-group IKEv2_DEFAULT proposal 10 hash 'sha256' - set vpn ipsec ipsec-interfaces interface 'eth0.202' - set vpn ipsec site-to-site peer 172.18.201.10 authentication id '172.18.202.10' - set vpn ipsec site-to-site peer 172.18.201.10 authentication mode 'pre-shared-secret' - set vpn ipsec site-to-site peer 172.18.201.10 authentication pre-shared-secret 'secretkey' - set vpn ipsec site-to-site peer 172.18.201.10 authentication remote-id '172.18.201.10' - set vpn ipsec site-to-site peer 172.18.201.10 connection-type 'initiate' - set vpn ipsec site-to-site peer 172.18.201.10 ike-group 'IKEv2_DEFAULT' - set vpn ipsec site-to-site peer 172.18.201.10 ikev2-reauth 'inherit' - set vpn ipsec site-to-site peer 172.18.201.10 local-address '172.18.202.10' - set vpn ipsec site-to-site peer 172.18.201.10 vti bind 'vti10' - set vpn ipsec site-to-site peer 172.18.201.10 vti esp-group 'ESP_DEFAULT' + set vpn ipsec interface 'eth0.202' + set vpn ipsec site-to-site peer OFFICE-A authentication local-id '172.18.202.10' + set vpn ipsec site-to-site peer OFFICE-A authentication mode 'pre-shared-secret' + set vpn ipsec site-to-site peer OFFICE-A authentication pre-shared-secret 'secretkey' + set vpn ipsec site-to-site peer OFFICE-A authentication remote-id '172.18.201.10' + set vpn ipsec site-to-site peer OFFICE-A connection-type 'initiate' + set vpn ipsec site-to-site peer OFFICE-A ike-group 'IKEv2_DEFAULT' + set vpn ipsec site-to-site peer OFFICE-A local-address '172.18.202.10' + set vpn ipsec site-to-site peer OFFICE-A remote-address '172.18.201.10' + set vpn ipsec site-to-site peer OFFICE-A vti bind 'vti10' + set vpn ipsec site-to-site peer OFFICE-A vti esp-group 'ESP_DEFAULT' Key Parameters: -* ``authentication id/remote-id`` - IKE identification is used for validation - of VPN peer devices during IKE negotiation. If you do not configure local/ - remote-identity, the device uses the IPv4 or IPv6 address that corresponds - to the local/remote peer by default. +* ``authentication local-id/remote-id`` - IKE identification is used for + validation of VPN peer devices during IKE negotiation. If you do not configure + local/remote-identity, the device uses the IPv4 or IPv6 address that + corresponds to the local/remote peer by default. In certain network setups (like ipsec interface with dynamic address, or behind the NAT ), the IKE ID received from the peer does not match the IKE gateway configured on the device. This can lead to a Phase 1 validation @@ -370,7 +353,7 @@ Key Parameters: * ``dead-peer-detection action = clear | hold | restart`` - R_U_THERE notification messages(IKEv1) or empty INFORMATIONAL messages (IKEv2) - are periodically sent in order to check the liveliness of theIPsec peer. The + are periodically sent in order to check the liveliness of the IPsec peer. The values clear, hold, and restart all activate DPD and determine the action to perform on a timeout. With ``clear`` the connection is closed with no further actions taken. @@ -384,6 +367,15 @@ Key Parameters: values). A closeaction should not be used if the peer uses reauthentication or uniqueids. - For a responder, close-action or dead-peer-detection must not be enabled. - For an initiator DPD with `restart` action, and `close-action 'restart'` - is recommended in IKE profile. + When the close-action option is set on the peers, the connection-type + of each peer has to considered carefully. For example, if the option is set + on both peers, then both would attempt to initiate and hold open multiple + copies of each child SA. This might lead to instability of the device or + cpu/memory utilization. + + Below flow-chart could be a quick reference for the close-action + combination depending on how the peer is configured. + +.. figure:: /_static/images/IPSec_close_action_settings.jpg + + Similar combinations are applicable for the dead-peer-detection. diff --git a/docs/configuration/vpn/sstp.rst b/docs/configuration/vpn/sstp.rst index 3600681f..f3e062fe 100644 --- a/docs/configuration/vpn/sstp.rst +++ b/docs/configuration/vpn/sstp.rst @@ -1,8 +1,8 @@ .. _sstp: -#### -SSTP -#### +########### +SSTP Server +########### :abbr:`SSTP (Secure Socket Tunneling Protocol)` is a form of :abbr:`VPN (Virtual Private Network)` tunnel that provides a mechanism to transport PPP @@ -111,6 +111,11 @@ Configuration interfaces. +.. cfgcmd:: set vpn sstp port <port> + + Specifies the port `<port>` that the SSTP port will listen on (default 443). + + .. cfgcmd:: set vpn sstp client-ip-pool subnet <subnet> Use `<subnet>` as the IP pool for all connecting clients. @@ -153,9 +158,6 @@ SSL Certificates Path to `<file>` pointing to the servers certificate (public portion). -.. cfgcmd:: set vpn sstp ssl key-file <file> - - Path to `<file>` pointing to the servers certificate (private portion). PPP Settings ------------ diff --git a/docs/configuration/vrf/index.rst b/docs/configuration/vrf/index.rst index 90d99c56..e58005e7 100644 --- a/docs/configuration/vrf/index.rst +++ b/docs/configuration/vrf/index.rst @@ -197,7 +197,7 @@ Example VRF route leaking ----------------- -The following example topology was build using EVE-NG. +The following example topology was built using EVE-NG. .. figure:: /_static/images/vrf-example-topology-01.png :alt: VRF topology example @@ -338,7 +338,7 @@ VRF Route Leaking BGP routes may be leaked (i.e. copied) between a unicast VRF RIB and the VPN SAFI RIB of the default VRF for use in MPLS-based L3VPNs. Unicast routes may also be leaked between any VRFs (including the unicast RIB of the default BGP -instanced). A shortcut syntax is also available for specifying leaking from +instance). A shortcut syntax is also available for specifying leaking from one VRF to another VRF using the default instance’s VPN RIB as the intemediary . A common application of the VRF-VRF feature is to connect a customer’s private routing domain to a provider’s VPN service. Leaking is configured from diff --git a/docs/configuration/zonepolicy/index.rst b/docs/configuration/zonepolicy/index.rst deleted file mode 100644 index 8fe18778..00000000 --- a/docs/configuration/zonepolicy/index.rst +++ /dev/null @@ -1,71 +0,0 @@ - -########### -Zone Policy -########### - - -.. toctree:: - :maxdepth: 1 - :includehidden: - -In zone-based policy, interfaces are assigned to zones, and inspection policy is applied to traffic moving between the zones and acted on according to firewall rules. -A Zone is a group of interfaces that have similar functions or features. It establishes the security borders of a network. -A zone defines a boundary where traffic is subjected to policy restrictions as it crosses to another region of a network. - -Key Points: - -* A zone must be configured before an interface is assigned to it and an interface can be assigned to only a single zone. -* All traffic to and from an interface within a zone is permitted. -* All traffic between zones is affected by existing policies -* Traffic cannot flow between zone member interface and any interface that is not a zone member. -* You need 2 separate firewalls to define traffic: one for each direction. - -Example: LAN Network is given SSH access to VyOS box. - -Firewall rules: - -.. code-block:: none - - set firewall name lan-local default-action 'drop' - set firewall name lan-local rule 1 action 'accept' - set firewall name lan-local rule 1 state established 'enable' - set firewall name lan-local rule 1 state related 'enable' - set firewall name lan-local rule 2 action 'drop' - set firewall name lan-local rule 2 state invalid 'enable' - set firewall name lan-local rule 2 log enable - set firewall name lan-local rule 100 action 'accept' - set firewall name lan-local rule 100 destination port '22' - set firewall name lan-local rule 100 log 'enable' - set firewall name lan-local rule 100 protocol 'tcp' - set firewall name local-lan default-action 'drop' - set firewall name local-lan rule 1 action 'accept' - set firewall name local-lan rule 1 state established 'enable' - set firewall name local-lan rule 1 state related 'enable' - set firewall name local-lan rule 2 action 'drop' - set firewall name local-lan rule 2 state invalid 'enable' - set firewall name local-lan rule 2 log enable - set firewall name local-lan rule 100 action 'accept' - set firewall name local-lan rule 100 destination address '192.168.0.0/24' - set firewall name local-lan rule 100 log 'enable' - set firewall name local-lan rule 100 protocol 'tcp' - -Zone-policy Config: - -.. code-block:: none - - set zone-policy zone lan default-action 'drop' - set zone-policy zone lan description 'Local Area Network' - set zone-policy zone lan interface 'eth2' - set zone-policy zone lan from local firewall name 'lan-local' - set zone-policy zone local default-action 'drop' - set zone-policy zone local description 'system-defined zone' - set zone-policy zone local from lan firewall name 'local-lan' - set zone-policy zone local local-zone - -A detailed zone-based policy example is written in the Configuration-Blueprints_ section. - -.. stop_vyoslinter - -.. _Configuration-Blueprints: https://docs.vyos.io/en/latest/configexamples/zone-policy.html - -.. start_vyoslinter |