diff options
Diffstat (limited to 'docs/configuration')
260 files changed, 40154 insertions, 0 deletions
diff --git a/docs/configuration/container/index.md b/docs/configuration/container/index.md new file mode 100644 index 00000000..db46db38 --- /dev/null +++ b/docs/configuration/container/index.md @@ -0,0 +1,479 @@ +--- +lastproofread: '2024-07-03' +--- + +# Container + +The VyOS container implementation is based on [Podman](https://podman.io/) as +a daemonless container engine. + +## Configuration + +```{cfgcmd} set container name \<name\> image + +Sets the image name in the hub registry + +:::{code-block} none +set container name mysql-server image mysql:8.0 +::: + +If a registry is not specified, Docker.io will be used as the container +registry unless an alternative registry is specified using +`set container registry <name>` or the registry is included +in the image name + +:::{code-block} none +set container name mysql-server image quay.io/mysql:8.0 +::: +``` + + +```{cfgcmd} set container name \<name\> entrypoint \<entrypoint\> + +Override the default entrypoint from the image for a container. +``` + + +```{cfgcmd} set container name \<name\> command \<command\> + +Override the default command from the image for a container. +``` + + +```{cfgcmd} set container name \<name\> arguments \<arguments\> + +Set the command arguments for a container. +``` + + +```{cfgcmd} set container name \<name\> host-name \<hostname\> + +Set the host name for a container. +``` + + +```{cfgcmd} set container name \<name\> allow-host-pid + +The container and the host share the same process namespace. +This means that processes running on the host are visible inside the +container, and processes inside the container are visible on the host. + +The command translates to "--pid host" when the container is created. +``` + + +```{cfgcmd} set container name \<name\> allow-host-networks + +Allow host networking in a container. The network stack of the container is +not isolated from the host and will use the host IP. + +The command translates to "--net host" when the container is created. + +:::{note} +**allow-host-networks** cannot be used with **network** +::: +``` + + +```{cfgcmd} set container name \<name\> network \<networkname\> + +Attaches user-defined network to a container. +Only one network must be specified and must already exist. +``` + + +```{cfgcmd} set container name \<name\> network \<networkname\> address \<address\> + +Optionally set a specific static IPv4 or IPv6 address for the container. +This address must be within the named network prefix. + +:::{note} +The first IP in the container network is reserved by the +engine and cannot be used +::: +``` + + +```{cfgcmd} set container name \<name\> name-server \<address\> + +Optionally set a custom name server. +If a container network is used with DNS enabled, +this setting will not have any effect. +``` + + +```{cfgcmd} set container name \<name\> description \<text\> + +Set a container description +``` + + +```{cfgcmd} set container name \<name\> environment \<key\> value \<value\> + +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 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\> port \<portname\> source \<portnumber\> + +``` +```{cfgcmd} set container name \<name\> port \<portname\> destination \<portnumber\> +``` + +```{cfgcmd} set container name \<name\> port \<portname\> protocol \<tcp | udp\> + +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 +::: +``` +:::{note} +Port publishing cannot be used with **network**. For this purpose, a workaround +using destination NAT and static IP assignment for the container is available. +::: +```{cfgcmd} set container name \<name\> volume \<volumename\> source \<path\> +``` + +```{cfgcmd} set container name \<name\> volume \<volumename\> destination \<path\> + +Mount a volume into the container + +:::{code-block} none +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\> tmpfs \<tmpfsname\> destination \<path\> + +Mount a tmpfs *(ramdisk)* filesystem to the given path within the container. +``` + +```{cfgcmd} set container name \<name\> tmpfs \<tmpfsname\> size \<MB\> + +Size in MB for tmpfs filesystem, maximum size is 64GB or 50% of the +systems total available memory. +``` + +```{cfgcmd} set container name \<name\> uid \<number\> +``` + +```{cfgcmd} set container name \<name\> gid \<number\> + +Set the User ID or Group ID of the container +``` + +```{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\> cpu-quota \<num\> + +This specifies the number of CPU resources the container can use. + +Default is 0 for unlimited. +For example, 1.25 limits the container to use up to 1.25 cores +worth of CPU time. +This can be a decimal number with up to three decimal places. + +The command translates to "--cpus=\<num\>" when the container is created. +``` + +```{cfgcmd} set container name \<name\> memory \<MB\> + +Constrain the memory available to the container. + +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} set container name \<name\> capability \<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**: Administration operations (quotactl, mount, sethostname, +setdomainame) +- **sys-time**: Permission to set system clock +``` + +```{cfgcmd} set container name \<name\> sysctl parameter \<parameter\> value \<value\> + +Set container sysctl values. + +The subset of possible parameters are: + +- Kernel Parameters: kernel.msgmax, kernel.msgmnb, kernel.msgmni, kernel.sem, +kernel.shmall, kernel.shmmax, kernel.shmmni, kernel.shm_rmid_forced +- Parameters beginning with fs.mqueue.* +- Parameters beginning with net.* (only if user-defined network is used) +``` + +```{cfgcmd} set container name \<name\> label \<label\> value \<value\> + +Add metadata label for this container. +``` + +```{cfgcmd} set container name \<name\> disable + +Disable a container. +``` + +### Container Health checks + + +By default, no health checks are run, even when defined by the image. + +```{cfgcmd} set container name \<name\> health-check + +Default health check is run for the container if defined by the image. +``` + +```{cfgcmd} set container name \<name\> health-check command \<command\> + +Override the default health check command from the image for a container. +``` + +```{cfgcmd} set container name \<name\> health-check interval \<interval\> + +Override the default health-check interval. For example: `60` +``` + +```{cfgcmd} set container name \<name\> health-check timeout \<timeout\> + +Override the default health-check timeout. For example: `10` +``` + +```{cfgcmd} set container name \<name\> health-check retries \<retries\> + +Number of health check retries before container is considered unhealthy. For example: `1` +``` + +### Container Networks + +```{cfgcmd} set container network \<name\> + +Creates a named container network +``` + +```{cfgcmd} set container network \<name\> description + +A brief description what this network is all about. +``` + +```{cfgcmd} set container network \<name\> prefix \<ipv4|ipv6\> + +Define IPv4 and/or IPv6 prefix for a given network name. +Both IPv4 and IPv6 can be used in parallel. +``` + +```{cfgcmd} set container network \<name\> mtu \<number\> + +Configure {abbr}`MTU (Maximum Transmission Unit)` for a given network. It +is the size (in bytes) of the largest ethernet frame sent on this link. +``` + +```{cfgcmd} set container network \<name\> no-name-server + +Disable Domain Name System (DNS) plugin for this network. +``` + +```{cfgcmd} set container network \<name\> vrf \<name\> + +Bind container network to a given VRF instance. +``` + +### Container Registry + +```{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 and quay.io as the container registry. +``` + +```{cfgcmd} set container registry \<name\> disable + +Disable a given container registry +``` + +```{cfgcmd} set container registry \<name\> authentication username +``` + +```{cfgcmd} set container registry \<name\> authentication password + +Some container registries require credentials to be used. + +Credentials can be defined here and will only be used when adding a +container image to the system. +``` + +```{cfgcmd} set container registry \<name\> insecure + +Allow registry access over unencrypted HTTP or TLS connections with +untrusted certificates. +``` + +```{cfgcmd} set container registry \<name\> mirror address \<address\> +``` + +```{cfgcmd} set container registry \<name\> mirror host-name \<host-name\> +``` + +```{cfgcmd} set container registry \<name\> mirror port \<port\> +``` + +```{cfgcmd} set container registry \<name\> mirror path \<path\> + +Registry mirror, use ``(host-name|address)[:port][/path]``. + +If you have mirror http://192.168.1.1:8080 for docker.io, you can use ``docker.io/some/repo`` or run ``podman pull docker.io/some/repo`` + +:::{code-block} none +set container registry docker.io mirror address 192.168.1.1 +set container registry docker.io mirror port 8080 +set container registry docker.io insecure +::: +If http://192.168.1.1:8080 is your own registry, you can use ``192.168.1.1:8080/some/repo`` or run ``podman pull 192.168.1.1:8080/some/repo`` + +:::{code-block} none +set container registry 192.168.1.1:8080 insecure +::: +``` + +### Log Configuration + +```{cfgcmd} set container name \<name\> log-driver [k8s-file | journald | none] + +Set the default log driver for containers. + +- **k8s-file**: Log to a plain text file in Kubernetes-style format. +- **journald**: Log to the system journal +- **none**: Disable logging for the container + +Current default is journald. + +``` + +## 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 +``` +```{opcmd} delete container image \<image id|all\> [force] + +Delete a particular container image based on it's image ID. +You can also delete all container images at once. + +You can not delete a container image if it has more then one tag +assigned, this is why there is a `force` option to pass down to +the container image to also remove those images. +``` + +## Example Configuration + +For the sake of demonstration, [example #1 in the official documentation](https://www.zabbix.com/documentation/current/manual/installation/containers) +to the declarative VyOS CLI syntax. + +```none +set container network zabbix prefix 172.20.0.0/16 +set container network zabbix description 'Network for Zabbix component containers' + +set container name mysql-server image mysql:8.0 +set container name mysql-server network zabbix + +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' + +set container name zabbix-java-gateway image zabbix/zabbix-java-gateway:alpine-5.2-latest +set container name zabbix-java-gateway network zabbix + +set container name zabbix-server-mysql image zabbix/zabbix-server-mysql:alpine-5.2-latest +set container name zabbix-server-mysql network zabbix + +set container name zabbix-server-mysql environment 'DB_SERVER_HOST' value 'mysql-server' +set container name zabbix-server-mysql environment 'MYSQL_DATABASE' value 'zabbix' +set container name zabbix-server-mysql environment 'MYSQL_USER' value 'zabbix' +set container name zabbix-server-mysql environment 'MYSQL_PASSWORD' value 'zabbix_pwd' +set container name zabbix-server-mysql environment 'MYSQL_ROOT_PASSWORD' value 'root_pwd' +set container name zabbix-server-mysql environment 'ZBX_JAVAGATEWAY' value 'zabbix-java-gateway' + +set container name zabbix-server-mysql port zabbix source 10051 +set container name zabbix-server-mysql port zabbix destination 10051 + +set container name zabbix-web-nginx-mysql image zabbix/zabbix-web-nginx-mysql:alpine-5.2-latest +set container name zabbix-web-nginx-mysql network zabbix + +set container name zabbix-web-nginx-mysql environment 'MYSQL_DATABASE' value 'zabbix' +set container name zabbix-web-nginx-mysql environment 'ZBX_SERVER_HOST' value 'zabbix-server-mysql' +set container name zabbix-web-nginx-mysql environment 'DB_SERVER_HOST' value 'mysql-server' +set container name zabbix-web-nginx-mysql environment 'MYSQL_USER' value 'zabbix' +set container name zabbix-web-nginx-mysql environment 'MYSQL_PASSWORD' value 'zabbix_pwd' +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 +``` diff --git a/docs/configuration/container/index.rst b/docs/configuration/container/rst-index.rst index 398f1941..398f1941 100644 --- a/docs/configuration/container/index.rst +++ b/docs/configuration/container/rst-index.rst diff --git a/docs/configuration/firewall/bridge.md b/docs/configuration/firewall/bridge.md new file mode 100644 index 00000000..f0e94f9e --- /dev/null +++ b/docs/configuration/firewall/bridge.md @@ -0,0 +1,685 @@ +--- +lastproofread: '2026-03-28' +--- + +(firewall-configuration)= + +# Bridge Firewall Configuration + +## Overview + +Learn more about bridge firewall configuration +and related op-mode commands. + +The following commands are covered in this section: + +```{cfgcmd} set firewall bridge \<options\> +``` + +From the main structure defined in +{doc}`Firewall Overview</configuration/firewall/index>` +in this section you can find detailed information only for the next part +of the general structure: + +```none +- set firewall + * bridge + - forward + + filter + - input + + filter + - output + + filter + - prerouting + + filter + - name + + custom_name +``` + +Traffic that is received by the router on an interface that is a member of a +bridge is processed on the **Bridge Layer**. Before the bridge decision is +made, all packets are analyzed at **Prerouting**. First filters can be applied +here, and also rules for ignoring connection tracking system can be configured. +The relevant configuration that acts in **prerouting** is: + + +- `set firewall bridge prerouting filter ...`. + + +For traffic that needs to be switched internally by the bridge, the base +chain is **forward**, and its base command for filtering is `set firewall +bridge forward filter ...`, which happens in stage 4, highlighted with red +color. + + +:::{figure} /_static/images/firewall-bridge-forward.webp +::: + + +For traffic destined to the router itself or that needs to be routed +(assuming a layer3 bridge is configured), the base chain is **input**, and the +base command is `set firewall bridge input filter ...` and the path is: + + +:::{figure} /_static/images/firewall-bridge-input.webp +::: + + +If it's not dropped, then the packet is sent to **IP Layer**, and will be +processed by the **IP Layer** firewall: IPv4 or IPv6 ruleset. Check once again +the {doc}`general packet flow diagram</configuration/firewall/index>` if +needed. + + +For traffic that originates from the bridge itself, the base chain is +**output**, and the base command is `set firewall bridge output filter +...`, and the path is: + + +:::{figure} /_static/images/firewall-bridge-output.webp +::: + + +Custom bridge firewall chains can be created with the command `set firewall +bridge name <name> ...`. To use such a custom chain, a rule with action jump +and the appropriate target must be defined in a base chain. + + +## Bridge Rules + + +For firewall filtering, firewall rules need to be created. Each rule is +numbered, has an action to apply if the rule is matched, and the ability +to specify multiple matching criteria. Data packets go through the rules +from 1 - 999999, so order is crucial. At the first match the action of the +rule will be executed. + + +### Actions + + +If a rule is defined, an action must also be defined for it. This tells the +firewall what to do if all matching criteria in the rule are met. + + +In firewall bridge rules, the action can be: + + +- `accept`: accept the packet. +- `continue`: continue parsing next rule. +- `drop`: drop the packet. +- `jump`: jump to another custom chain. +- `return`: Return from the current chain and continue at the next rule + of the last chain. +- `queue`: Enqueue packet to userspace. +- `notrack`: ignore connection tracking system. This action is only + available in prerouting chain. + +```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> action [accept | continue | drop | jump | queue | return] +``` + +```{cfgcmd} set firewall bridge input filter rule \<1-999999\> action [accept | continue | drop | jump | queue | return] +``` + +```{cfgcmd} set firewall bridge output filter rule \<1-999999\> action [accept | continue | drop | jump | queue | return] +``` + +```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> action [accept | continue | drop | jump | notrack | queue | return] +``` + +```{cfgcmd} set firewall bridge name \<name\> rule \<1-999999\> action [accept | continue | drop | jump | queue | 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 bridge forward filter rule \<1-999999\> jump-target \<text\> +``` + +```{cfgcmd} set firewall bridge input filter rule \<1-999999\> jump-target \<text\> +``` + +```{cfgcmd} set firewall bridge output filter rule \<1-999999\> jump-target \<text\> +``` + +```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> jump-target \<text\> +``` + +```{cfgcmd} set firewall bridge name \<name\> rule \<1-999999\> jump-target \<text\> +``` + +If action is set to ``queue``, use next command to specify the queue +target. Range is also supported: + +```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> queue \<0-65535\> +``` + +```{cfgcmd} set firewall bridge input filter rule \<1-999999\> queue \<0-65535\> +``` + +```{cfgcmd} set firewall bridge output filter rule \<1-999999\> queue \<0-65535\> +``` + +```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> queue \<0-65535\> +``` + +```{cfgcmd} set firewall bridge name \<name\> rule \<1-999999\> queue \<0-65535\> + +Also, if action is set to ``queue``, use next command to specify the queue +options. Possible options are ``bypass`` and ``fanout``: +``` + +```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> queue-options bypass +``` + +```{cfgcmd} set firewall bridge input filter rule \<1-999999\> queue-options bypass +``` + +```{cfgcmd} set firewall bridge output filter rule \<1-999999\> queue-options bypass +``` + +```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> queue-options bypass +``` + +```{cfgcmd} set firewall bridge name \<name\> rule \<1-999999\> queue-options bypass +``` + +```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> queue-options fanout +``` + +```{cfgcmd} set firewall bridge input filter rule \<1-999999\> queue-options fanout +``` + +```{cfgcmd} set firewall bridge output filter rule \<1-999999\> queue-options fanout +``` + +```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> queue-options fanout +``` + +```{cfgcmd} set firewall bridge name \<name\> rule \<1-999999\> queue-options fanout +``` + +Also, **default-action** is an action that takes place whenever a packet does +not match any rule in its chain. For base chains, possible options for +**default-action** are **accept** or **drop**. + +```{cfgcmd} set firewall bridge forward filter default-action [accept | drop] +``` + +```{cfgcmd} set firewall bridge input filter default-action [accept | drop] +``` + +```{cfgcmd} set firewall bridge output filter default-action [accept | drop] +``` + +```{cfgcmd} set firewall bridge prerouting filter default-action [accept | drop] +``` + +```{cfgcmd} set firewall bridge name \<name\> default-action [accept | continue | drop | jump | reject | return] + +This sets the default action of the rule-set if a packet does not match +any of the rules in that chain. If default-action is set to ``jump``, then +``default-jump-target`` is also needed. Note that for base chains, default +action can only be set to ``accept`` or ``drop``, while on custom chains +more actions are available. +``` + +```{cfgcmd} set firewall bridge name \<name\> default-jump-target \<text\> + +To be used only when ``default-action`` is set to ``jump``. Use this +command to specify jump target for default rule. +``` +:::{note} +**Important note about default-actions:** +If the default action for any base chain is not defined, then the default +action is set to **accept** for that chain. For custom chains, if the +default action is not defined, then the default-action is set to **drop**. +::: + + +### Firewall Logs + + +You can enable logging for every firewall rule. If enabled, other log options +can be configured. + +```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> log +``` + +```{cfgcmd} set firewall bridge input filter rule \<1-999999\> log +``` + +```{cfgcmd} set firewall bridge output filter rule \<1-999999\> log +``` + +```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> log +``` + +```{cfgcmd} set firewall bridge name \<name\> rule \<1-999999\> log + +Enable logging for the matched packet. If this configuration command is not +present, then the log is not enabled. +``` + +```{cfgcmd} set firewall bridge forward filter default-log +``` + +```{cfgcmd} set firewall bridge input filter default-log +``` + +```{cfgcmd} set firewall bridge output filter default-log +``` + +```{cfgcmd} set firewall bridge prerouting filter default-log +``` + +```{cfgcmd} set firewall bridge name \<name\> default-log + +Use this command to enable the logging of the default action on +the specified chain. +``` + +```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> log-options level [emerg | alert | crit | err | warn | notice | info | debug] +``` + +```{cfgcmd} set firewall bridge input filter rule \<1-999999\> log-options level [emerg | alert | crit | err | warn | notice | info | debug] +``` + +```{cfgcmd} set firewall bridge output filter rule \<1-999999\> log-options level [emerg | alert | crit | err | warn | notice | info | debug] +``` + +```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> log-options level [emerg | alert | crit | err | warn | notice | info | debug] +``` + +```{cfgcmd} set firewall bridge name \<name\> rule \<1-999999\> log-options level [emerg | alert | crit | err | warn | notice | info | debug] + +Define log-level. Only applicable if rule log is enabled. +``` + +```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> log-options group \<0-65535\> +``` + +```{cfgcmd} set firewall bridge input filter rule \<1-999999\> log-options group \<0-65535\> +``` + +```{cfgcmd} set firewall bridge output filter rule \<1-999999\> log-options group \<0-65535\> +``` + +```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> log-options group \<0-65535\> +``` + +```{cfgcmd} set firewall bridge name \<name\> rule \<1-999999\> log-options group \<0-65535\> + +Define the log group to send messages to. Only applicable if rule log is +enabled. +``` + +```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> log-options snapshot-length \<0-9000\> +``` + +```{cfgcmd} set firewall bridge input filter rule \<1-999999\> log-options snapshot-length \<0-9000\> +``` + +```{cfgcmd} set firewall bridge output filter rule \<1-999999\> log-options snapshot-length \<0-9000\> +``` + +```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> log-options snapshot-length \<0-9000\> +``` + +```{cfgcmd} set firewall bridge name \<name\> rule \<1-999999\> log-options snapshot-length \<0-9000\> + +Define length of packet payload to include in netlink message. Only +applicable if rule log is enabled and the log group is defined. +``` + +```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> log-options queue-threshold \<0-65535\> +``` + +```{cfgcmd} set firewall bridge input filter rule \<1-999999\> log-options queue-threshold \<0-65535\> +``` + +```{cfgcmd} set firewall bridge output filter rule \<1-999999\> log-options queue-threshold \<0-65535\> +``` + +```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> log-options queue-threshold \<0-65535\> +``` + +```{cfgcmd} set firewall bridge name \<name\> rule \<1-999999\> log-options queue-threshold \<0-65535\> + +Define the number of packets to queue inside the kernel before sending them +to userspace. Only applicable if rule log is enabled and the log group is +defined. +``` + +### Firewall Description + + +You can define a description for reference for every custom chain. + +```{cfgcmd} set firewall bridge name \<name\> description \<text\> + +Provide a rule-set description to a custom firewall chain. +``` + +```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> description \<text\> +``` + +```{cfgcmd} set firewall bridge input filter rule \<1-999999\> description \<text\> +``` + +```{cfgcmd} set firewall bridge output filter rule \<1-999999\> description \<text\> +``` + +```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> description \<text\> +``` + +```{cfgcmd} set firewall bridge name \<name\> rule \<1-999999\> description \<text\> + +Provide a description for each rule. +``` + +### Rule Status + + +By default, when you define a rule, it is enabled. In some cases, it is +useful to disable the rule instead of removing it. + +```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> disable +``` + +```{cfgcmd} set firewall bridge input filter rule \<1-999999\> disable +``` + +```{cfgcmd} set firewall bridge output filter rule \<1-999999\> disable +``` + +```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> disable +``` + +```{cfgcmd} set firewall bridge name \<name\> rule \<1-999999\> disable + +Command for disabling a rule but keep it in the configuration. +``` + +### Matching criteria + + +There are many matching criteria against which a packet can be tested. Refer +to {doc}`IPv4</configuration/firewall/ipv4>` and +{doc}`IPv6</configuration/firewall/ipv6>` matching criteria for more details. + + +Since bridges operate at layer 2, both matchers for IPv4 and IPv6 are +supported in bridge firewall configuration. Same applies to firewall groups. + + +Same specific matching criteria that can be used in bridge firewall are +described in this section: + +```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> ethernet-type [802.1q | 802.1ad | arp | ipv4 | ipv6] +``` + +```{cfgcmd} set firewall bridge input filter rule \<1-999999\> ethernet-type [802.1q | 802.1ad | arp | ipv4 | ipv6] +``` + +```{cfgcmd} set firewall bridge output filter rule \<1-999999\> ethernet-type [802.1q | 802.1ad | arp | ipv4 | ipv6] +``` + +```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> ethernet-type [802.1q | 802.1ad | arp | ipv4 | ipv6] +``` + +```{cfgcmd} set firewall bridge name \<name\> rule \<1-999999\> ethernet-type [802.1q | 802.1ad | arp | ipv4 | ipv6] + +Match based on the Ethernet type of the packet. +``` + +```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> vlan ethernet-type [802.1q | 802.1ad | arp | ipv4 | ipv6] +``` + +```{cfgcmd} set firewall bridge input filter rule \<1-999999\> vlan ethernet-type [802.1q | 802.1ad | arp | ipv4 | ipv6] +``` + +```{cfgcmd} set firewall bridge output filter rule \<1-999999\> vlan ethernet-type [802.1q | 802.1ad | arp | ipv4 | ipv6] +``` + +```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> vlan ethernet-type [802.1q | 802.1ad | arp | ipv4 | ipv6] +``` + +```{cfgcmd} set firewall bridge name \<name\> rule \<1-999999\> vlan ethernet-type [802.1q | 802.1ad | arp | ipv4 | ipv6] + +Match based on the Ethernet type of the packet when it is VLAN tagged. +``` + +```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> vlan id \<0-4096\> +``` + +```{cfgcmd} set firewall bridge input filter rule \<1-999999\> vlan id \<0-4096\> +``` + +```{cfgcmd} set firewall bridge output filter rule \<1-999999\> vlan id \<0-4096\> +``` + +```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> vlan id \<0-4096\> +``` + +```{cfgcmd} set firewall bridge name \<name\> rule \<1-999999\> vlan id \<0-4096\> + +Match based on VLAN identifier. Range is also supported. +``` + +```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> vlan priority \<0-7\> +``` + +```{cfgcmd} set firewall bridge input filter rule \<1-999999\> vlan priority \<0-7\> +``` + +```{cfgcmd} set firewall bridge output filter rule \<1-999999\> vlan priority \<0-7\> +``` + +```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> vlan priority \<0-7\> +``` + +```{cfgcmd} set firewall bridge name \<name\> rule \<1-999999\> vlan priority \<0-7\> + +Match based on VLAN priority (Priority Code Point - PCP). Range is also +supported. +``` + +### Packet Modifications + + +Starting from **VyOS-1.5-rolling-202410060007**, the firewall can modify +packets before they are sent out. This feature provides more flexibility in +packet handling. + +```{cfgcmd} set firewall bridge [prerouting | forward | output] filter rule \<1-999999\> set dscp \<0-63\> + +Set a specific value of Differentiated Services Codepoint (DSCP). +``` + +```{cfgcmd} set firewall bridge [prerouting | forward | output] filter rule \<1-999999\> set mark \<1-2147483647\> + +Set a specific packet mark value. +``` + +```{cfgcmd} set firewall bridge [prerouting | forward | output] filter rule \<1-999999\> set tcp-mss \<500-1460\> + +Set the TCP-MSS (TCP maximum segment size) for the connection. +``` + +```{cfgcmd} set firewall bridge [prerouting | forward | output] filter rule \<1-999999\> set ttl \<0-255\> + +Set the TTL (Time to Live) value. +``` + +```{cfgcmd} set firewall bridge [prerouting | forward | output] filter rule \<1-999999\> set hop-limit \<0-255\> + +Set hop limit value. +``` + +```{cfgcmd} set firewall bridge [forward | output] filter rule \<1-999999\> set connection-mark \<0-2147483647\> + +Set connection mark value. +``` + +### Use IP firewall + +By default, for switched traffic, only the rules defined under `set firewall +bridge` are applied. There are two global-options that can be configured in +order to force deeper analysis of the packet on the IP layer. These options +are: + +```{cfgcmd} set firewall global-options apply-to-bridged-traffic ipv4 + +This command enables the IPv4 firewall for bridged traffic. If this option +is used, packets are also parsed by rules defined in ``set firewall ipv4 +...`` +``` + +```{cfgcmd} set firewall global-options apply-to-bridged-traffic ipv6 + +This command enables the IPv6 firewall for bridged traffic. If this option +is used, packets are also parsed by rules defined in ``set firewall ipv6 +...`` +``` + +## Operation-mode Firewall +### Rule-set overview + +In this section you can find all useful firewall op-mode commands. +General commands for firewall configuration, counter and statistics: + +```{opcmd} show firewall +``` + +```{opcmd} show firewall summary +``` + +```{opcmd} show firewall statistics +``` + +And, to print only bridge firewall information: + +```{opcmd} show firewall bridge +``` + +```{opcmd} show firewall bridge forward filter +``` + +```{opcmd} show firewall bridge forward filter rule \<rule\> +``` + +```{opcmd} show firewall bridge name \<name\> +``` + +```{opcmd} show firewall bridge name \<name\> rule \<rule\> +``` + +### Show Firewall log + +```{opcmd} show log firewall +``` + +```{opcmd} show log firewall bridge +``` + +```{opcmd} show log firewall bridge forward +``` + +```{opcmd} show log firewall bridge forward filter +``` + +```{opcmd} show log firewall bridge name \<name\> +``` + +```{opcmd} show log firewall bridge forward filter rule \<rule\> +``` + +```{opcmd} show log firewall bridge name \<name\> rule \<rule\> + +Show the logs of all firewall; show all bridge firewall logs; show all logs +for forward hook; show all logs for forward hook and priority filter; show +all logs for particular custom chain; show logs for specific Rule-Set. +``` + +### Example + +Configuration example: + +```none +set firewall bridge forward filter default-action 'drop' +set firewall bridge forward filter default-log +set firewall bridge forward filter rule 10 action 'continue' +set firewall bridge forward filter rule 10 inbound-interface name 'eth2' +set firewall bridge forward filter rule 10 vlan id '22' +set firewall bridge forward filter rule 20 action 'drop' +set firewall bridge forward filter rule 20 inbound-interface group 'TRUNK-RIGHT' +set firewall bridge forward filter rule 20 vlan id '60' +set firewall bridge forward filter rule 30 action 'jump' +set firewall bridge forward filter rule 30 jump-target 'TEST' +set firewall bridge forward filter rule 30 outbound-interface name '!eth1' +set firewall bridge forward filter rule 35 action 'accept' +set firewall bridge forward filter rule 35 vlan id '11' +set firewall bridge forward filter rule 40 action 'continue' +set firewall bridge forward filter rule 40 destination mac-address '66:55:44:33:22:11' +set firewall bridge forward filter rule 40 source mac-address '11:22:33:44:55:66' +set firewall bridge name TEST default-action 'accept' +set firewall bridge name TEST default-log +set firewall bridge name TEST rule 10 action 'continue' +set firewall bridge name TEST rule 10 log +set firewall bridge name TEST rule 10 vlan priority '0' +``` + +And op-mode commands: + +```none +vyos@BRI:~$ show firewall bridge +Rulesets bridge Information + +--------------------------------- +bridge Firewall "forward filter" + +Rule Action Protocol Packets Bytes Conditions +------- -------- ---------- --------- ------- --------------------------------------------------------------------- +10 continue all 0 0 iifname "eth2" vlan id 22 continue +20 drop all 0 0 iifname @I_TRUNK-RIGHT vlan id 60 +30 jump all 2130 170688 oifname != "eth1" jump NAME_TEST +35 accept all 2080 168616 vlan id 11 accept +40 continue all 0 0 ether daddr 66:55:44:33:22:11 ether saddr 11:22:33:44:55:66 continue +default drop all 0 0 + +--------------------------------- +bridge Firewall "name TEST" + +Rule Action Protocol Packets Bytes Conditions +------- -------- ---------- --------- ------- -------------------------------------------------- +10 continue all 2130 170688 vlan pcp 0 prefix "[bri-NAM-TEST-10-C]" continue +default accept all 2130 170688 + +vyos@BRI:~$ +vyos@BRI:~$ show firewall bridge name TEST +Ruleset Information + +--------------------------------- +bridge Firewall "name TEST" + +Rule Action Protocol Packets Bytes Conditions +------- -------- ---------- --------- ------- -------------------------------------------------- +10 continue all 2130 170688 vlan pcp 0 prefix "[bri-NAM-TEST-10-C]" continue +default accept all 2130 170688 + +vyos@BRI:~$ +``` + +Inspect logs: + +```none +vyos@BRI:~$ show log firewall bridge +Dec 05 14:37:47 kernel: [bri-NAM-TEST-10-C]IN=eth1 OUT=eth2 ARP HTYPE=1 PTYPE=0x0800 OPCODE=1 MACSRC=50:00:00:04:00:00 IPSRC=10.11.11.101 MACDST=00:00:00:00:00:00 IPDST=10.11.11.102 +Dec 05 14:37:48 kernel: [bri-NAM-TEST-10-C]IN=eth1 OUT=eth2 ARP HTYPE=1 PTYPE=0x0800 OPCODE=1 MACSRC=50:00:00:04:00:00 IPSRC=10.11.11.101 MACDST=00:00:00:00:00:00 IPDST=10.11.11.102 +Dec 05 14:37:49 kernel: [bri-NAM-TEST-10-C]IN=eth1 OUT=eth2 ARP HTYPE=1 PTYPE=0x0800 OPCODE=1 MACSRC=50:00:00:04:00:00 IPSRC=10.11.11.101 MACDST=00:00:00:00:00:00 IPDST=10.11.11.102 +... +vyos@BRI:~$ show log firewall bridge forward filter +Dec 05 14:42:22 kernel: [bri-FWD-filter-default-D]IN=eth2 OUT=eth1 MAC=33:33:00:00:00:16:50:00:00:06:00:00:86:dd SRC=0000:0000:0000:0000:0000:0000:0000:0000 DST=ff02:0000:0000:0000:0000:0000:0000:0016 LEN=96 TC=0 HOPLIMIT=1 FLOWLBL=0 PROTO=ICMPv6 TYPE=143 CODE=0 +Dec 05 14:42:22 kernel: [bri-FWD-filter-default-D]IN=eth2 OUT=eth1 MAC=33:33:00:00:00:16:50:00:00:06:00:00:86:dd SRC=0000:0000:0000:0000:0000:0000:0000:0000 DST=ff02:0000:0000:0000:0000:0000:0000:0016 LEN=96 TC=0 HOPLIMIT=1 FLOWLBL=0 PROTO=ICMPv6 TYPE=143 CODE=0 +``` diff --git a/docs/configuration/firewall/flowtables.md b/docs/configuration/firewall/flowtables.md new file mode 100644 index 00000000..24d0675e --- /dev/null +++ b/docs/configuration/firewall/flowtables.md @@ -0,0 +1,176 @@ +--- +lastproofread: '2026-03-30' +--- + +(firewall-flowtables-configuration)= + +# Flowtables Firewall Configuration + +```{include} /_include/need_improvement.txt +``` + + +## Overview + +This section provides information on firewall configuration for flowtables. + +```{cfgcmd} set firewall flowtable ... +``` + +To learn about the general traffic flow in VyOS firewalls, +see {doc}`Firewall </configuration/firewall/index>`. + +```none +- set firewall + * flowtable + - custom_flow_table + + ... +``` + +Flowtables let you define a fastpath through the flowtable datapath. +Flowtables support layer 3 (IPv4 and IPv6) and layer 4 (TCP and UDP) +protocols. + +:::{figure} /_static/images/firewall-flowtable-packet-flow.webp +::: + +After the first packet successfully traverses the IP forwarding path (black +circles path), you can offload subsequent packets to the flowtable through your +ruleset. You specify when to add a flow to the flowtable during forward +filtering (red circle number 6). + +When a packet finds a matching entry in the flowtable (flowtable hit), the +system transmits it to the output netdevice. This means packets bypass the +classic IP forwarding path and use the **Fast Path** (orange circles path). +As a result, you do not see these packets from any Netfilter hooks after +ingress. If no matching entry exists in the flowtable (flowtable miss), the +packet traverses the classic IP forwarding path. + +:::{note} +**Flowtable Reference:** +<https://docs.kernel.org/networking/nf_flowtable.html> +::: + +## Flowtable Configuration + +To use flowtables, you need to configure the following: +> - Create a flowtable that includes the interfaces +> that are going to be used by the flowtable. +> - Create a firewall rule. Set the action to +> `offload` and use your desired flowtable for `offload-target`. + +Creating a flow table: + +```{cfgcmd} set firewall flowtable \<flow_table_name\> interface \<iface\> + +Specify interfaces to use in the flowtable. +``` + +```{cfgcmd} set firewall flowtable \<flow_table_name\> description \<text\> +``` + +Provide a description for the flow table. + +```{cfgcmd} set firewall flowtable \<flow_table_name\> offload \<hardware | software\> + +Specify the offload type the flowtable uses: ``hardware`` or +``software``. The default is ``software`` offload. +``` +:::{note} +**Hardware offload**: Make sure your network interface controller +(NIC) supports hardware offloading and that you have the necessary drivers +> installed before enabling this option. +::: + +Creating rules for using flow tables: + +```{cfgcmd} set firewall [ipv4 | ipv6] forward filter rule \<1-999999\> action offload + +Create a firewall rule in the forward chain with the action set to +``offload``. +``` + +```{cfgcmd} set firewall [ipv4 | ipv6] forward filter rule \<1-999999\> offload-target \<flowtable\> + +Create a firewall rule in the forward chain and specify which flowtable +to use. Only applicable if the action is ``offload``. +``` + +## Configuration Example + +Consider the following in this setup: +> - This example uses two interfaces in the flowtables: `eth0` and `eth1`. +> - The example provides a minimal firewall ruleset with filtering rules +> and rules for using flowtable offload capabilities. + +The first packet is evaluated by the firewall path, so a +desired connection should be explicitly accepted. +The same should occur for traffic in reverse order. +In most cases, state policies are +used to accept a connection in the reverse path. + +In the following example only traffic coming from interface `eth0`, +TCP protocol, and destination port 1122 is accepted. +All other traffic to the router is dropped. + +### Commands + +```none +set firewall flowtable FT01 interface 'eth0' +set firewall flowtable FT01 interface 'eth1' +set firewall ipv4 forward filter default-action 'drop' +set firewall ipv4 forward filter rule 10 action 'offload' +set firewall ipv4 forward filter rule 10 offload-target 'FT01' +set firewall ipv4 forward filter rule 10 state 'established' +set firewall ipv4 forward filter rule 10 state 'related' +set firewall ipv4 forward filter rule 20 action 'accept' +set firewall ipv4 forward filter rule 20 state 'established' +set firewall ipv4 forward filter rule 20 state 'related' +set firewall ipv4 forward filter rule 110 action 'accept' +set firewall ipv4 forward filter rule 110 destination address '192.0.2.100' +set firewall ipv4 forward filter rule 110 destination port '1122' +set firewall ipv4 forward filter rule 110 inbound-interface name 'eth0' +set firewall ipv4 forward filter rule 110 protocol 'tcp' +``` + +### Explanation + +Here's what happens for a desired connection: +> 1. A packet arrives on `eth0` with destination address `192.0.2.100`, TCP +> protocol, and destination port 1122. Assume this address is reachable +> through interface `eth1`. +> 2. For this first packet, the connection state is **new**. Neither rule 10 +> nor rule 20 applies. +> 3. Rule 110 matches, so the connection is accepted. +> 4. When the server 192.0.2.100 replies, the connection state becomes +> **established**, and rule 20 accepts the reply. +> 5. The router receives the second packet for this connection. Because the +> connection state is **established**, rule 10 matches and adds a new +> entry in the flowtable FT01 for this connection. +> 6. Subsequent packets skip the traditional path and use the **Fast Path** +> for offloading. + +### Checks + +Check the conntrack table to verify that the system accepted and properly +offloaded connections. + +```none +vyos@FlowTables:~$ show firewall ipv4 forward filter +Ruleset Information + +--------------------------------- +ipv4 Firewall "forward filter" + +Rule Action Protocol Packets Bytes Conditions +------- -------- ---------- --------- ------- ---------------------------------------------------------------- +10 offload all 8 468 ct state { established, related } flow add @VYOS_FLOWTABLE_FT01 +20 accept all 8 468 ct state { established, related } accept +110 accept tcp 2 120 ip daddr 192.0.2.100 tcp dport 1122 iifname "eth0" accept +default drop all 7 420 + +vyos@FlowTables:~$ sudo conntrack -L | grep tcp +conntrack v1.4.6 (conntrack-tools): 5 flow entries have been shown. +tcp 6 src=198.51.100.100 dst=192.0.2.100 sport=41676 dport=1122 src=192.0.2.100 dst=198.51.100.100 sport=1122 dport=41676 [OFFLOAD] mark=0 use=2 +vyos@FlowTables:~$ +``` diff --git a/docs/configuration/firewall/global-options.md b/docs/configuration/firewall/global-options.md new file mode 100644 index 00000000..0f6d91ac --- /dev/null +++ b/docs/configuration/firewall/global-options.md @@ -0,0 +1,186 @@ +--- +lastproofread: '2026-03-30' +--- + +(firewall-global-options-configuration)= + +# Global Options Firewall Configuration + +## Overview + +Some firewall settings are global and affect the entire system. This section +provides information about these global options that you can configure using +the VyOS CLI. + +Configuration commands covered in this section: + +```{cfgcmd} set firewall global-options ... +``` + +## Configuration + +```{cfgcmd} set firewall global-options all-ping [enable | disable] + +By default, when VyOS receives an ICMP echo request packet destined for +itself, it answers with an ICMP echo reply, unless your firewall prevents +it. + +You can set firewall rules to accept, drop, or reject ICMP in, out, or +local traffic. You can also use the **firewall global-options all-ping** +command. This command affects only LOCAL traffic (packets destined for your +VyOS system), not IN or OUT traffic. + +:::{note} +**firewall global-options all-ping** affects only LOCAL traffic +and always behaves in the most restrictive way +::: +:::{code-block} none +set firewall global-options all-ping enable +::: +When you set this command, VyOS answers every ICMP echo request addressed +to itself, but that response occurs only if no other rule drops or rejects +local echo requests. In case of conflict, VyOS does not answer ICMP echo +requests. + +:::{code-block} none +set firewall global-options all-ping disable +::: +When you set this command, VyOS answers no ICMP echo requests addressed to +itself, regardless of where they come from or what specific rules accept +them. +``` + +```{cfgcmd} set firewall global-options apply-to-bridged-traffic [ipv4 | ipv6] + +Apply IPv4 or IPv6 firewall rules to bridged traffic. +``` + +```{cfgcmd} set firewall global-options broadcast-ping [enable | disable] + +Enable or disable the response to ICMP broadcast messages. The system +alters the following parameter: +* ``net.ipv4.icmp_echo_ignore_broadcasts`` +``` + +```{cfgcmd} set firewall global-options ip-src-route [enable | disable] +``` + +```{cfgcmd} set firewall global-options ipv6-src-route [enable | disable] + +Set whether VyOS accepts packets with a source route option. +The following sysctl parameters will be changed: +* ``net.ipv4.conf.all.accept_source_route`` +* ``net.ipv6.conf.all.accept_source_route`` +``` + +```{cfgcmd} set firewall global-options receive-redirects [enable | disable] +``` + +```{cfgcmd} set firewall global-options ipv6-receive-redirects [enable | disable] + +Allow VyOS to accept ICMPv4 and ICMPv6 redirect messages. +The following sysctl parameters will be changed: +* ``net.ipv4.conf.all.accept_redirects`` +* ``net.ipv6.conf.all.accept_redirects`` +``` + +```{cfgcmd} set firewall global-options send-redirects [enable | disable] + +Allow VyOS to send ICMPv4 redirect messages. +The following sysctl parameter will be changed: +* ``net.ipv4.conf.all.send_redirects`` +``` + +```{cfgcmd} set firewall global-options log-martians [enable | disable] + +Allow VyOS to log martian IPv4 packets. +The following sysctl parameter will be changed: +* ``net.ipv4.conf.all.log_martians`` +``` + +```{cfgcmd} set firewall global-options source-validation [strict | loose | disable] + +Set the IPv4 source validation mode. +The following sysctl parameter will be changed: +* ``net.ipv4.conf.all.rp_filter`` +``` + +```{cfgcmd} set firewall global-options syn-cookies [enable | disable] + +Allow VyOS to use IPv4 TCP SYN Cookies. +The following sysctl parameter will be changed: +* ``net.ipv4.tcp_syncookies`` +``` + +```{cfgcmd} set firewall global-options twa-hazards-protection [enable | disable] + +Enable or disable VyOS {rfc}`1337` conformance. +The following sysctl parameter will be changed: +* ``net.ipv4.tcp_rfc1337`` +``` + +```{cfgcmd} set firewall global-options state-policy established action [accept | drop | reject] +``` + +```{cfgcmd} set firewall global-options state-policy established log +``` + +```{cfgcmd} set firewall global-options state-policy established log-level [emerg | alert | crit | err | warn | notice | info | debug] + +Set the global setting for an established connection. +``` + +```{cfgcmd} set firewall global-options state-policy invalid action [accept | drop | reject] +``` + +```{cfgcmd} set firewall global-options state-policy invalid log +``` + +```{cfgcmd} set firewall global-options state-policy invalid log-level [emerg | alert | crit | err | warn | notice | info | debug] + +Set the global setting for invalid packets. +``` + +```{cfgcmd} set firewall global-options state-policy related action [accept | drop | reject] +``` + +```{cfgcmd} set firewall global-options state-policy related log +``` + +```{cfgcmd} set firewall global-options state-policy related log-level [emerg | alert | crit | err | warn | notice | info | debug] + +Set the global setting for related connections. +``` + +VyOS supports setting timeouts for connections by connection type. You can +set timeout values for generic connections, ICMP connections, UDP +connections, or TCP connections in various states. + +```{eval-rst} +.. cfgcmd:: set firewall global-options timeout icmp <1-21474836> + :defaultvalue: +.. cfgcmd:: set firewall global-options timeout other <1-21474836> + :defaultvalue: +.. cfgcmd:: set firewall global-options timeout tcp close <1-21474836> + :defaultvalue: +.. cfgcmd:: set firewall global-options timeout tcp close-wait <1-21474836> + :defaultvalue: +.. cfgcmd:: set firewall global-options timeout tcp established <1-21474836> + :defaultvalue: +.. cfgcmd:: set firewall global-options timeout tcp fin-wait <1-21474836> + :defaultvalue: +.. cfgcmd:: set firewall global-options timeout tcp last-ack <1-21474836> + :defaultvalue: +.. cfgcmd:: set firewall global-options timeout tcp syn-recv <1-21474836> + :defaultvalue: +.. cfgcmd:: set firewall global-options timeout tcp syn-sent <1-21474836> + :defaultvalue: +.. cfgcmd:: set firewall global-options timeout tcp time-wait <1-21474836> + :defaultvalue: +.. cfgcmd:: set firewall global-options timeout udp other <1-21474836> + :defaultvalue: +.. cfgcmd:: set firewall global-options timeout udp stream <1-21474836> + :defaultvalue: + + Set the timeout in seconds for a protocol or state. +```
\ No newline at end of file diff --git a/docs/configuration/firewall/groups.md b/docs/configuration/firewall/groups.md new file mode 100644 index 00000000..817f610e --- /dev/null +++ b/docs/configuration/firewall/groups.md @@ -0,0 +1,477 @@ +--- +lastproofread: '2026-03-30' +--- + +(firewall-groups-configuration)= + +# Firewall groups + +## Configuration + +Firewall groups represent collections of IP addresses, networks, ports, +MAC addresses, domains, or interfaces. You can reference a group in firewall, +NAT, and policy route rules as either a source or destination matcher, and/or +as inbound or outbound in the case of interface groups. + +### Address Groups + +An **address group** contains a single IP address or IP address range. + +```{cfgcmd} set firewall group address-group \<name\> address [address | address range] + +``` +```{cfgcmd} set firewall group ipv6-address-group \<name\> address \<address\> + +Define an IPv4 or 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 an IPv4 or IPv6 address group description. +``` + +### Remote Groups + +A **remote-group** uses a URL that hosts a newline-delimited list of IPv4 +and/or IPv6 addresses, CIDRs, and ranges. VyOS pulls this list periodically +according to the frequency you define in the firewall **resolver-interval** +and loads matching entries into the group for use in rules. The list is cached +in persistent storage, so rules continue to function if updates fail. + +```{cfgcmd} set firewall group remote-group \<name\> url \<http(s) url\> + +Specify a remote list of IPv4 and/or IPv6 addresses, ranges, and CIDRs +to fetch. +``` + +```{cfgcmd} set firewall group remote-group \<name\> description \<text\> + +Set a description for a remote group. +``` + +The remote list format is flexible. VyOS attempts to parse the first word of +each line as an entry and skips lines it cannot match. Lines that begin with +an alphanumeric character but do not match valid IPv4 or IPv6 addresses, +ranges, or CIDRs are logged to the system log. The following examples show +acceptable formats that VyOS parses correctly: + +```none +127.0.0.1 +127.0.0.0/24 +127.0.0.1-127.0.0.254 +2001:db8::1 +2001:db8:cafe::/48 +2001:db8:cafe::1-2001:db8:cafe::ffff +``` + +### Network Groups + +**Network groups** accept IP networks in CIDR notation. You can add specific +IP addresses as a 32-bit prefix. If you need to add a mix of addresses and +networks, use a network group. + +```{cfgcmd} set firewall group network-group \<name\> network \<CIDR\> +``` + +```{cfgcmd} set firewall group ipv6-network-group \<name\> network \<CIDR\> + +Define an 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 an IPv4 or IPv6 network group description. +``` + +### Interface Groups + +An **interface group** represents a collection of interfaces. + +```{cfgcmd} set firewall group interface-group \<name\> interface \<text\> + +Define an interface group. +Wildcard ``*`` is supported. For example: ``eth3*``. +Prepend the character ``!`` to invert the criteria. For example: ``!eth2``. +``` + +```none +set firewall group interface-group LAN interface bond1001 +set firewall group interface-group LAN interface eth3* +``` + +```{cfgcmd} set firewall group interface-group \<name\> description \<text\> + +Provide an interface group description. +``` + +### Port Groups + +A **port group** represents only port numbers, not the protocol. You can +reference port groups for either TCP or UDP. Create TCP and UDP groups +separately to avoid accidentally filtering unnecessary ports. Specify port +ranges 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. For example, ``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. +``` + +```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 +``` + +```{cfgcmd} set firewall group mac-group \<name\> description \<text\> + +Provide a MAC group description. +``` + +### Domain Groups + +A **domain group** represents a collection of domains. + +```{cfgcmd} set firewall group domain-group \<name\> address \<domain\> + +Define a domain group. +``` + +```none +set firewall group domain-group DOM address example.com +``` + +```{cfgcmd} set firewall group domain-group \<name\> description \<text\> + +Provide a domain group description. +``` + +### Dynamic Groups + +Firewall dynamic groups differ from other groups because you can use them as +source/destination in firewall rules, and members are not defined statically +in VyOS configuration. Instead, firewall rules dynamically add members to +these groups. + +#### Defining Dynamic Address Groups + +Dynamic address groups support both IPv4 and IPv6 families. Use these +commands to define dynamic IPv4 and IPv6 address groups: + +```{cfgcmd} set firewall group dynamic-group address-group \<name\> +``` + +```{cfgcmd} set firewall group dynamic-group ipv6-address-group \<name\> +``` + +Add description to firewall groups: + +```{cfgcmd} set firewall group dynamic-group address-group \<name\> description \<text\> +``` + +```{cfgcmd} set firewall group dynamic-group ipv6-address-group \<name\> description \<text\> +``` + +#### Adding elements to Dynamic Firewall Groups + +After you define dynamic firewall groups, use them in firewall rules to +dynamically add elements to them. + +Commands used for this task are: +- Add destination IP address of the connection to a dynamic address group: + +```{cfgcmd} set firewall ipv4 [forward | input | output] filter rule \<1-999999\> add-address-to-group destination-address address-group \<name\> +``` + +```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> add-address-to-group destination-address address-group \<name\> +``` + +```{cfgcmd} set firewall ipv6 [forward | input | output] filter rule \<1-999999\> add-address-to-group destination-address address-group \<name\> +``` + +```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> add-address-to-group destination-address address-group \<name\> +``` + +- Add source IP address of the connection to a dynamic address group: + +```{cfgcmd} set firewall ipv4 [forward | input | output] filter rule \<1-999999\> add-address-to-group source-address address-group \<name\> +``` + +```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> add-address-to-group source-address address-group \<name\> +``` + +```{cfgcmd} set firewall ipv6 [forward | input | output] filter rule \<1-999999\> add-address-to-group source-address address-group \<name\> +``` + +```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> add-address-to-group source-address address-group \<name\> +``` + +You can define specific timeouts per rule. When a rule matches, the source or +destination address is added to the group, and the element remains in the group +until the timeout expires. If you do not define a timeout, the element remains +in the group until the next reboot or until you commit firewall configuration +changes. + +```{cfgcmd} set firewall ipv4 [forward | input | output] filter rule \<1-999999\> add-address-to-group [destination-address | source-address] timeout \<timeout\> +``` + +```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> add-address-to-group [destination-address | source-address] timeout \<timeout\> +``` + +```{cfgcmd} set firewall ipv6 [forward | input | output] filter rule \<1-999999\> add-address-to-group [destination-address | source-address] timeout \<timeout\> +``` + +```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> add-address-to-group [destination-address | source-address] timeout \<timeout\> +``` + +Timeout can be defined using seconds, minutes, hours or days: + +```none +set firewall ipv6 name FOO rule 10 add-address-to-group source-address timeout +Possible completions: +<number>s Timeout value in seconds +<number>m Timeout value in minutes +<number>h Timeout value in hours +<number>d Timeout value in days +``` + +#### Using Dynamic Firewall Groups + +Like other firewall groups, you can use dynamic firewall groups in firewall +rules as matching options. For example: + +```none +set firewall ipv4 input filter rule 10 source group dynamic-address-group FOO +set firewall ipv4 input filter rule 10 destination group dynamic-address-group BAR +``` + +## Examples + +### General example + +After you create firewall groups, you can reference them in firewall, NAT, +NAT66, and/or policy-route rules. The following example creates multiple +groups: + +```{eval-rst} + .. code-block:: none + + set firewall group address-group SERVERS address 198.51.100.101 + set firewall group address-group SERVERS address 198.51.100.102 + set firewall group network-group TRUSTEDv4 network 192.0.2.0/30 + set firewall group network-group TRUSTEDv4 network 203.0.113.128/25 + set firewall group ipv6-network-group TRUSTEDv6 network 2001:db8::/64 + set firewall group interface-group LAN interface eth2.2001 + set firewall group interface-group LAN interface bon0 + set firewall group port-group PORT-SERVERS port http + set firewall group port-group PORT-SERVERS port 443 + set firewall group port-group PORT-SERVERS port 5000-5010 +``` + +And next, some configuration example where groups are used: + +```{eval-rst} + .. code-block:: none + + set firewall ipv4 output filter rule 10 action accept + set firewall ipv4 output filter rule 10 outbound-interface group !LAN + set firewall ipv4 forward filter rule 20 action accept + set firewall ipv4 forward filter rule 20 source group network-group TRUSTEDv4 + set firewall ipv6 input filter rule 10 action accept + set firewall ipv6 input filter rule 10 source group network-group TRUSTEDv6 + set nat destination rule 101 inbound-interface group LAN + set nat destination rule 101 destination group address-group SERVERS + set nat destination rule 101 protocol tcp + set nat destination rule 101 destination group port-group PORT-SERVERS + set nat destination rule 101 translation address 203.0.113.250 + set policy route PBR rule 201 destination group port-group PORT-SERVERS + set policy route PBR rule 201 protocol tcp + set policy route PBR rule 201 set table 15 +``` + +### Port knocking example + +You can use dynamic firewall groups with port knocking to secure access to +the router or any other device. The following example shows a 4-step port +knocking configuration: + +```{eval-rst} + .. code-block:: none + + set firewall global-options state-policy established action 'accept' + set firewall global-options state-policy invalid action 'drop' + set firewall global-options state-policy related action 'accept' + set firewall group dynamic-group address-group ALLOWED + set firewall group dynamic-group address-group PN_01 + set firewall group dynamic-group address-group PN_02 + set firewall ipv4 input filter default-action 'drop' + set firewall ipv4 input filter rule 5 action 'accept' + set firewall ipv4 input filter rule 5 protocol 'icmp' + set firewall ipv4 input filter rule 10 action 'drop' + set firewall ipv4 input filter rule 10 add-address-to-group source-address address-group 'PN_01' + set firewall ipv4 input filter rule 10 add-address-to-group source-address timeout '2m' + set firewall ipv4 input filter rule 10 description 'Port_nock 01' + set firewall ipv4 input filter rule 10 destination port '9990' + set firewall ipv4 input filter rule 10 protocol 'tcp' + set firewall ipv4 input filter rule 20 action 'drop' + set firewall ipv4 input filter rule 20 add-address-to-group source-address address-group 'PN_02' + set firewall ipv4 input filter rule 20 add-address-to-group source-address timeout '3m' + set firewall ipv4 input filter rule 20 description 'Port_nock 02' + set firewall ipv4 input filter rule 20 destination port '9991' + set firewall ipv4 input filter rule 20 protocol 'tcp' + set firewall ipv4 input filter rule 20 source group dynamic-address-group 'PN_01' + set firewall ipv4 input filter rule 30 action 'drop' + set firewall ipv4 input filter rule 30 add-address-to-group source-address address-group 'ALLOWED' + set firewall ipv4 input filter rule 30 add-address-to-group source-address timeout '2h' + set firewall ipv4 input filter rule 30 description 'Port_nock 03' + set firewall ipv4 input filter rule 30 destination port '9992' + set firewall ipv4 input filter rule 30 protocol 'tcp' + set firewall ipv4 input filter rule 30 source group dynamic-address-group 'PN_02' + set firewall ipv4 input filter rule 99 action 'accept' + set firewall ipv4 input filter rule 99 description 'Port_nock 04 - Allow ssh' + set firewall ipv4 input filter rule 99 destination port '22' + set firewall ipv4 input filter rule 99 protocol 'tcp' + set firewall ipv4 input filter rule 99 source group dynamic-address-group 'ALLOWED' +``` + +Before testing, we can check the members of firewall groups: + +```none +vyos@vyos# run show firewall group +Firewall Groups + +Name Type References Members Timeout Expires +------- ---------------------- -------------------- ------------- --------- --------- +ALLOWED address_group(dynamic) ipv4-input-filter-30 N/D N/D N/D +PN_01 address_group(dynamic) ipv4-input-filter-10 N/D N/D N/D +PN_02 address_group(dynamic) ipv4-input-filter-20 N/D N/D N/D +[edit] +vyos@vyos# +``` + +With this configuration, to gain SSH access to the router, the user must: + +1. Create a new TCP connection to destination port 9990. A new entry is added + to dynamic firewall group `PN_01`. + + ```none + vyos@vyos# run show firewall group + Firewall Groups + + Name Type References Members Timeout Expires + ------- ---------------------- -------------------- ------------- --------- --------- + ALLOWED address_group(dynamic) ipv4-input-filter-30 N/D N/D N/D + PN_01 address_group(dynamic) ipv4-input-filter-10 192.168.89.31 120 119 + PN_02 address_group(dynamic) ipv4-input-filter-20 N/D N/D N/D + [edit] + vyos@vyos# + ``` + +2. Create a new TCP connection to destination port 9991. A new entry is added + to dynamic firewall group `PN_02`. + + ```none + vyos@vyos# run show firewall group + Firewall Groups + + Name Type References Members Timeout Expires + ------- ---------------------- -------------------- ------------- --------- --------- + ALLOWED address_group(dynamic) ipv4-input-filter-30 N/D N/D N/D + PN_01 address_group(dynamic) ipv4-input-filter-10 192.168.89.31 120 106 + PN_02 address_group(dynamic) ipv4-input-filter-20 192.168.89.31 180 179 + [edit] + vyos@vyos# + ``` + +3. Create a new TCP connection to destination port 9992. A new entry is added + to dynamic firewall group `ALLOWED`. + + ```none + vyos@vyos# run show firewall group + Firewall Groups + + Name Type References Members Timeout Expires + ------- ---------------------- -------------------- ------------- --------- --------- + ALLOWED address_group(dynamic) ipv4-input-filter-30 192.168.89.31 7200 7199 + PN_01 address_group(dynamic) ipv4-input-filter-10 192.168.89.31 120 89 + PN_02 address_group(dynamic) ipv4-input-filter-20 192.168.89.31 180 170 + [edit] + vyos@vyos# + ``` + +4. Now you can connect via SSH to the router (assuming SSH is + configured). + +## Operation-mode + +```{opcmd} show firewall group +``` + +```{opcmd} show firewall group \<name\> + +Display an overview of defined groups, including the firewall group name, +type, references (where the group is used), members, timeout, and +expiration (the last two only apply to dynamic firewall groups). +``` + +Here is an example of such command: + +```none +vyos@vyos:~$ show firewall group +Firewall Groups + +Name Type References Members Timeout Expires +------------ ---------------------- ---------------------- ---------------- --------- --------- +SERVERS address_group nat-destination-101 198.51.100.101 + 198.51.100.102 +ALLOWED address_group(dynamic) ipv4-input-filter-30 192.168.77.39 7200 7174 +PN_01 address_group(dynamic) ipv4-input-filter-10 192.168.0.245 120 112 + 192.168.77.39 120 85 +PN_02 address_group(dynamic) ipv4-input-filter-20 192.168.77.39 180 151 +LAN interface_group ipv4-output-filter-10 bon0 + nat-destination-101 eth2.2001 +TRUSTEDv6 ipv6_network_group ipv6-input-filter-10 2001:db8::/64 +TRUSTEDv4 network_group ipv4-forward-filter-20 192.0.2.0/30 + 203.0.113.128/25 +PORT-SERVERS port_group route-PBR-201 443 + route-PBR-201 5000-5010 + nat-destination-101 http +vyos@vyos:~$ +``` diff --git a/docs/configuration/firewall/index.md b/docs/configuration/firewall/index.md new file mode 100644 index 00000000..9108a800 --- /dev/null +++ b/docs/configuration/firewall/index.md @@ -0,0 +1,278 @@ +--- +lastproofread: '2026-03-30' +--- + +# Firewall + +:::{warning} +Due to a boot-time race condition, all interfaces initialize +before the firewall. This temporarily leaves the system open to all traffic +and poses a security risk. +::: + +VyOS uses Netfilter. The Netfilter +project developed `iptables` and its successor `nftables` for the Linux +kernel to process packet data flows directly. This extends the concept of +zone-based security to let you manipulate data at multiple stages after the +network interface and driver accept it, and before sending it to its +destination (for example, a web server or another device). + +The following is a simplified traffic flow diagram based on Netfilter +packet flow. +This diagram provides an overview of how packets are processed and the +possible paths traffic can take. + +:::{figure} /_static/images/firewall-gral-packet-flow.webp +::: + +The main points regarding packet flow and terminology in VyOS firewall +are: + +- **Bridge Port?**: Choose the appropriate path based on whether the + interface where the packet was received is part of a bridge. + +If the interface where the packet was received is not part of a bridge, the +packet is processed at the **IP Layer**: + +```{eval-rst} + * **Prerouting**: The router processes all packets in this stage, + regardless of the destination. You can perform several actions in + this stage, and these actions are also defined in different parts of the + VyOS configuration. Order is important. The relevant configuration that + applies in this stage includes: + + * **Firewall prerouting**: Rules you define under ``set firewall + [ipv4 | ipv6] prerouting raw...``. The system processes all rules in + this section before the connection tracking subsystem. + + * **Conntrack Ignore**: Rules you define under ``set system conntrack + ignore [ipv4 | ipv6] ...``. You can configure this section with + ``firewall [ipv4 | ipv6] prerouting ...``. For compatibility reasons, + this feature is supported, but will be deprecated in the future. + + * **Policy Route**: Rules you define under ``set policy [route | + route6] ...``. + + * **Destination NAT**: Rules you define under ``set [nat | nat66] + destination...``. + + * **Destination is the router?**: Choose the appropriate path based on the + destination IP address. Transit traffic continues to **forward**, while + traffic destined for the router continues to **input**. + + * **Input**: The stage where you filter and control traffic destined for + the router itself. This is where you enforce all rules for securing the + router. This includes IPv4 and IPv6 filtering rules, defined in: + + * ``set firewall ipv4 input filter ...``. + + * ``set firewall ipv6 input filter ...``. + + * **Forward**: The stage where you filter and control transit traffic. + This includes IPv4 and IPv6 filtering rules, defined in: + + * ``set firewall ipv4 forward filter ...``. + + * ``set firewall ipv6 forward filter ...``. + + * **Output**: The stage where you filter and control traffic that the + router originates. Note that this traffic comes from either a new + connection that an internal process on the VyOS router (such as NTP) + originates or a response to traffic the router receives externally through + **input** (for example, a response to an SSH login attempt). This includes + IPv4 and IPv6 rules, and two different sections apply: + + * **Output Prerouting**: ``set firewall [ipv4 | ipv6] output + raw ...``. As described in **Prerouting**, the system processes + rules in this section before the connection tracking subsystem. + + * **Output Filter**: ``set firewall [ipv4 | ipv6] output filter ...``. + + * **Postrouting**: As in **Prerouting**, you can perform several actions + defined in different parts of VyOS configuration in this stage. This + includes: + + * **Source NAT**: Rules you define under ``set [nat | nat66] + source...``. +``` + +If the interface where the packet was received is part of a bridge, the +packet is processed at the **Bridge Layer**: + +```{eval-rst} + * **Prerouting (Bridge)**: The bridge processes all packets it receives in + this stage, regardless of the destination. First, you can apply filters + here, or you can configure rules that ignore the connection tracking + system. The relevant configuration that applies: + + * ``set firewall bridge prerouting filter ...``. + + * **Forward (Bridge)**: The stage where you filter and control traffic + that passes through the bridge: + + * ``set firewall bridge forward filter ...``. + + * **Input (Bridge)**: The stage where you filter and control traffic + destined for the bridge itself: + + * ``set firewall bridge input filter ...``. + + * **Output (Bridge)**: The stage where you filter and control traffic that + the bridge originates: + + * ``set firewall bridge output filter ...``. +``` + +The following is the overall structure of the VyOS firewall CLI: + +```none +- set firewall + * bridge + - forward + + filter + - input + + filter + - output + + filter + - prerouting + + filter + - name + + custom_name + * flowtable + - custom_flow_table + + ... + * global-options + + all-ping + + broadcast-ping + + ... + * group + - address-group + - ipv6-address-group + - network-group + - ipv6-network-group + - interface-group + - mac-group + - port-group + - domain-group + * ipv4 + - forward + + filter + - input + + filter + - output + + filter + + raw + - prerouting + + raw + - name + + custom_name + * ipv6 + - forward + + filter + - input + + filter + - output + + filter + + raw + - prerouting + + raw + - ipv6-name + + custom_name + * zone + - custom_zone_name + + ... +``` + +Here is a list of VyOS firewall CLI subcommands and their +corresponding pages in the documentation: + +```{cfgcmd} set firewall bridge ... + +Configure bridge firewall rules for traffic at the bridge layer. +See the Bridge Firewall Configuration page for detailed information. +``` + +```{cfgcmd} set firewall flowtable ... + +Configure firewall flowtables for stateful connection tracking and rules. +See the Flowtables Firewall Configuration page for detailed information. +``` + +```{cfgcmd} set firewall global-options ... + +Configure global firewall options such as ``all-ping``, ``broadcast-ping``, +``syn-cookies``, and other system-wide firewall settings. +See the Global Firewall Options page for detailed information. +``` + +```{cfgcmd} set firewall group ... + +Organize firewall rules by creating reusable address, network, interface, +MAC, port, and domain groups. Use groups in multiple rules to simplify +configuration and maintenance. +See the Firewall Groups page for detailed information. +``` + +```{cfgcmd} set firewall ipv4 ... + +Configure IPv4-specific firewall rules. +See the IPv4 Firewall Configuration page for detailed information. +``` + +```{cfgcmd} set firewall ipv6 ... + +Configure IPv6-specific firewall rules. +See the IPv6 Firewall Configuration page for detailed information. +``` + +```{cfgcmd} set firewall zone ... + +Configure zone-based firewall policies for controlling traffic between +different network zones. +See the Zone-Based Firewall Configuration page for detailed information. +``` + +For more information on firewall configuration, see the following pages: + +```{toctree} +:includehidden: true +:maxdepth: 1 + +global-options +groups +bridge +ipv4 +ipv6 +flowtables +``` + +:::{note} +For more information on Netfilter hooks and Linux networking packet flows, +see the [Netfilter-Hooks](<https://wiki.nftables.org/wiki-nftables/index.php/Netfilter_hooks>) +documentation. +::: + +## Zone-Based firewall + +```{toctree} +:includehidden: true +:maxdepth: 1 + +zone +``` + +With zone-based firewalls, a new concept applies. In addition to the standard +in and out traffic flows, a local flow enables traffic originating from and +destined to the router itself. This means you must configure additional rules to +secure the firewall from the network, in addition to the existing inbound and +outbound rules. + +To configure VyOS with zone-based firewall, see +{doc}`Zone-Based Firewall Configuration </configuration/firewall/zone>`. + +As the following example image shows, you must configure rules to allow or block +traffic to or from the services running on the device that have open +connections on that interface. + +:::{figure} /_static/images/firewall-zonebased.webp +::: diff --git a/docs/configuration/firewall/ipv4.md b/docs/configuration/firewall/ipv4.md new file mode 100644 index 00000000..e5c0a986 --- /dev/null +++ b/docs/configuration/firewall/ipv4.md @@ -0,0 +1,1517 @@ +--- +lastproofread: '2026-03-30' +--- + +(firewall-ipv4-configuration)= + +# IPv4 Firewall Configuration + +## Overview + +This section provides information on IPv4 firewall configuration and +appropriate operation-mode commands. This section covers the following +configuration commands: + +```{cfgcmd} set firewall ipv4 ... +``` + +To learn about the general traffic flow in VyOS firewalls, see {doc}`Firewall </configuration/firewall/index>`. + +```none +- set firewall + * ipv4 + - forward + + filter + - input + + filter + - output + + filter + + raw + - prerouting + + raw + - name + + custom_name +``` + +First, the router receives all traffic and processes it in the **prerouting** +stage. + +This stage includes: + +- **Firewall Prerouting**: commands found under `set firewall ipv4 + prerouting raw ...` +- {doc}`Conntrack Ignore</configuration/system/conntrack>`: `set system + conntrack ignore ipv4...` +- {doc}`Policy Route</configuration/policy/route>`: commands found under + `set policy route ...` +- {doc}`Destination NAT</configuration/nat/nat44>`: commands found under + `set nat destination ...` + +For transit traffic, which is received by the router and forwarded, the base +chain is **forward**. The following is a simplified packet flow diagram for +transit traffic: + +:::{figure} /_static/images/firewall-fwd-packet-flow.webp +::: + +The base firewall chain for configuring filtering rules for transit traffic is +`set firewall ipv4 forward filter ...`, which occurs in stage 5, highlighted +in red. + +For traffic to the router itself, the base chain is **input**. For traffic +the router originates, the base chain is **output**. A simplified packet flow +diagram is shown next, which shows the path for traffic destined to the router +itself and traffic the router generates (starting from circle number 6): + +:::{figure} /_static/images/firewall-input-packet-flow.webp +::: + +The base chain for traffic towards the router is +`set firewall ipv4 input filter ...` + +The base chain for traffic the router generates is `set firewall ipv4 +output ...`, where two sub-chains are available: **filter** and **raw**: + +- **Output Prerouting**: `set firewall ipv4 output raw ...`. As described + in **Prerouting**, the system processes rules in this section before the + connection tracking subsystem. +- **Output Filter**: `set firewall ipv4 output filter ...`. The system + processes rules in this section after the connection tracking subsystem. + +:::{note} +**Important note about default-actions:** +If you do not define a default action for a base chain, the system sets +the default action to **accept** for that chain. For custom chains, if you +do not define a default action, the system sets the default-action to +**drop**. +::: + +You can create custom firewall chains using the following commands: +`set firewall ipv4 name <name> ...`. To use a custom chain, you must define +a rule with the **action jump** and the appropriate **target** in a base +chain. + +## Firewall - IPv4 Rules + +Each firewall rule has a +number, an action to apply if the rule matches, and the ability to specify +multiple matching criteria. Packets traverse rules numbered 1-999999, so order +is crucial. The system executes the rule action at the first match. + +### Actions + +If you define a rule, you must define an action for it. The action tells the +firewall what to do if all the criteria you define for that rule are met. + +The action can be: + +- `accept`: Accept the packet. +- `continue`: Continue parsing the next rule. +- `drop`: Drop the packet. +- `reject`: Reject the packet. +- `jump`: Jump to another custom chain. +- `return`: Return from the current chain and continue at the next rule + of the last chain. +- `queue`: Enqueue packet to userspace. +- `synproxy`: Synproxy the packet. + +```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> action [accept | continue | drop | jump | queue | reject | return | synproxy] +``` + +```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> action [accept | continue | drop | jump | queue | reject | return | synproxy] +``` + +```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> action [accept | continue | drop | jump | queue | reject | return] +``` + +```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> action [accept | continue | drop | jump | queue | reject | return] + +This required setting defines the action of the current rule. If you set +the action to jump, you must also specify a jump-target. +``` + +```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> jump-target \<text\> +``` + +```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> jump-target \<text\> +``` + +```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> jump-target \<text\> +``` + +```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> jump-target \<text\> + +Use this command only when the action is set to ``jump``. Specify the +jump target. +``` + +```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> queue \<0-65535\> +``` + +```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> queue \<0-65535\> +``` + +```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> queue \<0-65535\> +``` + +```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> queue \<0-65535\> + +Use this command only when the action is set to ``queue``. Specify the +queue target to use. Queue range is also supported. +``` + +```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> queue-options bypass +``` + +```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> queue-options bypass +``` + +```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> queue-options bypass +``` + +```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> queue-options bypass + +Use this command only when the action is set to ``queue``. Allow the packet +to pass through the firewall when no userspace software is connected to the +queue. +``` + +```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> queue-options fanout +``` + +```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> queue-options fanout +``` + +```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> queue-options fanout +``` + +```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> queue-options fanout + +Use this command only when the action is set to ``queue``. Distribute +packets between several queues. +``` + +Also, **default-action** is an action that applies when a packet does not +match any rule in its chain. For base chains, possible options for +**default-action** are **accept** or **drop**. + +```{cfgcmd} set firewall ipv4 forward filter default-action [accept | drop] +``` + +```{cfgcmd} set firewall ipv4 input filter default-action [accept | drop] +``` + +```{cfgcmd} set firewall ipv4 output filter default-action [accept | drop] +``` + +```{cfgcmd} set firewall ipv4 name \<name\> default-action [accept | drop | jump | queue | reject | return] + +This command sets the default action of the rule-set if a packet does not +match the criteria of any rule. If you set the default-action to ``jump``, +you must also specify ``default-jump-target``. Note that for base chains, +you can set the default action only to ``accept`` or ``drop``, while on +custom chains, more actions are available. +``` + +```{cfgcmd} set firewall ipv4 name \<name\> default-jump-target \<text\> + +Use this command only when you set ``default-action`` to ``jump``. Specify +the jump target for the default rule. +``` +:::{note} +**Important note about default-actions:** +If you do not define a default action for a base chain, the system sets +the default action to **accept** for that chain. For custom chains, if you +do not define a default action, the system sets the default-action to +**drop**. +::: + +### Firewall Logs + +You can enable logging for every single firewall rule. If you enable logging, +you can define other log options. + +```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> log +``` + +```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> log +``` + +```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> log +``` + +```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> log + +Enable logging for the matched packet. If this command is not present, then +logging is not enabled. +``` + +```{cfgcmd} set firewall ipv4 forward filter default-log +``` + +```{cfgcmd} set firewall ipv4 input filter default-log +``` + +```{cfgcmd} set firewall ipv4 output filter default-log +``` + +```{cfgcmd} set firewall ipv4 name \<name\> default-log + +Use this command to enable logging of the default action on the specified +chain. +``` + +```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> log-options level [emerg | alert | crit | err | warn | notice | info | debug] +``` + +```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> log-options level [emerg | alert | crit | err | warn | notice | info | debug] +``` + +```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> log-options level [emerg | alert | crit | err | warn | notice | info | debug] +``` + +```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> log-options level [emerg | alert | crit | err | warn | notice | info | debug] + +Define the log level. Only applicable if you enable rule logging. +``` + +```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> log-options group \<0-65535\> +``` + +```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> log-options group \<0-65535\> +``` + +```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> log-options group \<0-65535\> +``` + +```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> log-options group \<0-65535\> + +Define the log group to send messages to. Only applicable if you enable rule +logging. +``` + +```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> log-options snapshot-length \<0-9000\> +``` + +```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> log-options snapshot-length \<0-9000\> +``` + +```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> log-options snapshot-length \<0-9000\> +``` + +```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> log-options snapshot-length \<0-9000\> + +Define the length of packet payload to include in a netlink message. Only +applicable if you enable rule logging and define the log group. +``` + +```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> log-options queue-threshold \<0-65535\> +``` + +```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> log-options queue-threshold \<0-65535\> +``` + +```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> log-options queue-threshold \<0-65535\> +``` + +```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> log-options queue-threshold \<0-65535\> + +Define the number of packets to queue inside the kernel before sending them +to userspace. Only applicable if you enable rule logging and define the log +group. +``` + +### Firewall Description + +You can add a description for reference for every single rule and for every +defined custom chain. + +```{cfgcmd} set firewall ipv4 name \<name\> description \<text\> + +Provide a rule-set description for a custom firewall chain. +``` + +```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> description \<text\> +``` + +```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> description \<text\> +``` + +```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> description \<text\> +``` + +```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> description \<text\> + +Provide a description for each rule. +``` + +### Rule Status + +When you define a rule, it is enabled by default. In some cases, it is useful +to disable the rule rather than removing it. + +```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> disable +``` + +```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> disable +``` + +```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> disable +``` + +```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> disable + +Command for disabling a rule but keeping it in the configuration. +``` + +### Matching criteria + +There are a lot of matching criteria against which the packet can be tested. + +```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> connection-status nat [destination | source] +``` + +```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> connection-status nat [destination | source] +``` + +```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> connection-status nat [destination | source] +``` + +```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> connection-status nat [destination | source] + +Match based on nat connection status. +``` + +```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> connection-mark \<1-2147483647\> +``` + +```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> connection-mark \<1-2147483647\> +``` + +```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> connection-mark \<1-2147483647\> +``` + +```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> connection-mark \<1-2147483647\> + +Match based on connection mark. +``` + +```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> conntrack-helper \<module\> +``` + +```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> conntrack-helper \<module\> +``` + +```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> conntrack-helper \<module\> +``` + +```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> conntrack-helper \<module\> + +Match based on connection tracking protocol helper module to secure use of +that helper module. See below for possible completions \<module\>. + +:::{code-block} none +Possible completions: +ftp Related traffic from FTP helper +h323 Related traffic from H.323 helper +pptp Related traffic from PPTP helper +nfs Related traffic from NFS helper +sip Related traffic from SIP helper +tftp Related traffic from TFTP helper +sqlnet Related traffic from SQLNet helper +::: +``` + +```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> source address [address | addressrange | CIDR] +``` + +```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> source address [address | addressrange | CIDR] +``` + +```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> source address [address | addressrange | CIDR] +``` + +```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> source address [address | addressrange | CIDR] +``` + +```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> destination address [address | addressrange | CIDR] +``` + +```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> destination address [address | addressrange | CIDR] +``` + +```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> destination address [address | addressrange | CIDR] +``` + +```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> destination address [address | addressrange | CIDR] + +Match criteria based on source and/or destination address. This is similar +to the network groups part, but here you are able to negate the matching +addresses. + +:::{code-block} none +set firewall ipv4 name FOO rule 50 source address 192.0.2.10-192.0.2.11 +# with a '!' the rule match everything except the specified subnet +set firewall ipv4 name FOO rule 51 source address !203.0.113.0/24 +::: +``` + +```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> source address-mask [address] +``` + +```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> source address-mask [address] +``` + +```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> source address-mask [address] +``` + +```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> source address-mask [address] +``` + +```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> destination address-mask [address] +``` + +```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> destination address-mask [address] +``` + +```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> destination address-mask [address] +``` + +```{cfgcmd} set firewall ipv4 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 functions for both individual addresses and address groups. + +:::{code-block} none +# Match any IPv4 address with `11` as the 2nd octet and `13` as the forth octet +set firewall ipv4 name FOO rule 100 destination address 0.11.0.13 +set firewall ipv4 name FOO rule 100 destination address-mask 0.255.0.255 +::: +``` + +```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> source fqdn \<fqdn\> +``` + +```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> source fqdn \<fqdn\> +``` + +```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> source fqdn \<fqdn\> +``` + +```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> source fqdn \<fqdn\> +``` + +```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> destination fqdn \<fqdn\> +``` + +```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> destination fqdn \<fqdn\> +``` + +```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> destination fqdn \<fqdn\> +``` + +```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> destination fqdn \<fqdn\> + +Specify a Fully Qualified Domain Name as source/destination to match. Ensure +that the router is able to resolve this dns query. +``` + +```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> source geoip country-code \<country\> +``` + +```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> source geoip country-code \<country\> +``` + +```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> source geoip country-code \<country\> +``` + +```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> source geoip country-code \<country\> +``` + +```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> destination geoip country-code \<country\> +``` + +```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> destination geoip country-code \<country\> +``` + +```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> destination geoip country-code \<country\> +``` + +```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> destination geoip country-code \<country\> +``` + +```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> source geoip inverse-match +``` + +```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> source geoip inverse-match +``` + +```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> source geoip inverse-match +``` + +```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> source geoip inverse-match +``` + +```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> destination geoip inverse-match +``` + +```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> destination geoip inverse-match +``` + +```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> destination geoip inverse-match +``` + +```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> destination geoip inverse-match + +Match IP addresses based on its geolocation. More info: 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 ipv4 forward filter rule \<1-999999\> source mac-address \<mac-address\> +``` + +```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> source mac-address \<mac-address\> +``` + +```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> source mac-address \<mac-address\> +``` + +```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> source mac-address \<mac-address\> + +You can only specify a source mac-address to match. + +:::{code-block} none +set firewall ipv4 input filter rule 100 source mac-address 00:53:00:11:22:33 +set firewall ipv4 input filter rule 101 source mac-address !00:53:00:aa:12:34 +::: +``` + +```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> source port [1-65535 | portname | start-end] +``` + +```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> source port [1-65535 | portname | start-end] +``` + +```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> source port [1-65535 | portname | start-end] +``` + +```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> source port [1-65535 | portname | start-end] +``` + +```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> destination port [1-65535 | portname | start-end] +``` + +```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> destination port [1-65535 | portname | start-end] +``` + +```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> destination port [1-65535 | portname | start-end] +``` + +```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> destination port [1-65535 | portname | start-end] + +A port can be set by number or name as defined in ``/etc/services``. + +:::{code-block} none +set firewall ipv4 forward filter rule 10 source port '22' +set firewall ipv4 forward filter rule 11 source port '!http' +set firewall ipv4 forward filter 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: +``` + +```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> source group address-group \<name | !name\> +``` + +```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> source group address-group \<name | !name\> +``` + +```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> source group address-group \<name | !name\> +``` + +```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> source group address-group \<name | !name\> +``` + +```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> destination group address-group \<name | !name\> +``` + +```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> destination group address-group \<name | !name\> +``` + +```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> destination group address-group \<name | !name\> +``` + +```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> destination group address-group \<name | !name\> + +Use a specific address-group. Prepending the character ``!`` to invert the +criteria to match is also supported. +``` + +```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> source group dynamic-address-group \<name | !name\> +``` + +```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> source group dynamic-address-group \<name | !name\> +``` + +```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> source group dynamic-address-group \<name | !name\> +``` + +```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> source group dynamic-address-group \<name | !name\> +``` + +```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> destination group dynamic-address-group \<name | !name\> +``` + +```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> destination group dynamic-address-group \<name | !name\> +``` + +```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> destination group dynamic-address-group \<name | !name\> +``` + +```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> destination group dynamic-address-group \<name | !name\> + +Use a specific dynamic-address-group. Prepending the character ``!`` to +invert the criteria to match is also supported. +``` + +```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> source group network-group \<name | !name\> +``` + +```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> source group network-group \<name | !name\> +``` + +```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> source group network-group \<name | !name\> +``` + +```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> source group network-group \<name | !name\> +``` + +```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> destination group network-group \<name | !name\> +``` + +```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> destination group network-group \<name | !name\> +``` + +```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> destination group network-group \<name | !name\> +``` + +```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> destination group network-group \<name | !name\> + +Use a specific network-group. Prepending the character ``!`` to invert the +criteria to match is also supported. +``` + +```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> source group port-group \<name | !name\> +``` + +```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> source group port-group \<name | !name\> +``` + +```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> source group port-group \<name | !name\> +``` + +```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> source group port-group \<name | !name\> +``` + +```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> destination group port-group \<name | !name\> +``` + +```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> destination group port-group \<name | !name\> +``` + +```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> destination group port-group \<name | !name\> +``` + +```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> destination group port-group \<name | !name\> + +Use a specific port-group. Prepending the character ``!`` to invert the +criteria to match is also supported. +``` + +```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> source group domain-group \<name | !name\> +``` + +```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> source group domain-group \<name | !name\> +``` + +```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> source group domain-group \<name | !name\> +``` + +```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> source group domain-group \<name | !name\> +``` + +```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> destination group domain-group \<name | !name\> +``` + +```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> destination group domain-group \<name | !name\> +``` + +```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> destination group domain-group \<name | !name\> +``` + +```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> destination group domain-group \<name | !name\> + +Use a specific domain-group. Prepending the character ``!`` to invert the +criteria to match is also supported. +``` + +```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> source group mac-group \<name | !name\> +``` + +```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> source group mac-group \<name | !name\> +``` + +```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> source group mac-group \<name | !name\> +``` + +```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> source group mac-group \<name | !name\> +``` + +```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> destination group mac-group \<name | !name\> +``` + +```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> destination group mac-group \<name | !name\> +``` + +```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> destination group mac-group \<name | !name\> +``` + +```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> destination group mac-group \<name | !name\> + +Use a specific mac-group. Prepending the character ``!`` to invert the +criteria to match is also supported. +``` + +```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> dscp [0-63 | start-end] +``` + +```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> dscp [0-63 | start-end] +``` + +```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> dscp [0-63 | start-end] +``` + +```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> dscp [0-63 | start-end] +``` + +```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> dscp-exclude [0-63 | start-end] +``` + +```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> dscp-exclude [0-63 | start-end] +``` + +```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> dscp-exclude [0-63 | start-end] +``` + +```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> dscp-exclude [0-63 | start-end] + +Match based on dscp value. +``` + +```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> fragment [match-frag | match-non-frag] +``` + +```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> fragment [match-frag | match-non-frag] +``` + +```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> fragment [match-frag | match-non-frag] +``` + +```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> fragment [match-frag | match-non-frag] + +Match based on fragmentation. +``` + +```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> icmp [code | type] \<0-255\> +``` + +```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> icmp [code | type] \<0-255\> +``` + +```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> icmp [code | type] \<0-255\> +``` + +```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> icmp [code | type] \<0-255\> + +Match based on icmp code and type. +``` + +```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> icmp type-name \<text\> +``` + +```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> icmp type-name \<text\> +``` + +```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> icmp type-name \<text\> +``` + +```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> icmp type-name \<text\> + +Match based on icmp type-name. Use tab for information +about what **type-name** criteria are supported. +``` + +```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> inbound-interface name \<iface\> +``` + +```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> inbound-interface name \<iface\> +``` + +```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> inbound-interface name \<iface\> + +Match based on inbound interface. Wildcard ``*`` is supported. For example: +``eth2*``. Prepend the character ``!`` to invert the criteria. For example: +``!eth2`` +``` +:::{note} +If an interface is attached to a non-default vrf, when using +**inbound-interface**, the vrf name must be used. For example `set firewall +ipv4 forward filter rule 10 inbound-interface name MGMT` +::: +```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> inbound-interface group \<iface_group\> +``` + +```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> inbound-interface group \<iface_group\> +``` + +```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> inbound-interface group \<iface_group\> + +Match based on the inbound interface group. Prepend the character ``!`` to +invert the criteria. For example, ``!IFACE_GROUP`` +``` + +```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> outbound-interface name \<iface\> +``` + +```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> outbound-interface name \<iface\> +``` + +```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> outbound-interface name \<iface\> + +Match based on outbound interface. Wildcard ``*`` is supported. For example: +``eth2*``. Prepend the character ``!`` to invert the criteria. For example: +``!eth2`` +``` +:::{note} +If an interface is attached to a non-default vrf, when using +**outbound-interface**, the real interface name must be used. For example +`set firewall ipv4 forward filter rule 10 outbound-interface name eth0` +::: +```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> outbound-interface group \<iface_group\> +``` + +```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> outbound-interface group \<iface_group\> +``` + +```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> outbound-interface group \<iface_group\> + +Match based on outbound interface group. Prepend the character ``!`` to +invert the criteria. For example: ``!IFACE_GROUP`` +``` + +```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> ipsec [match-ipsec-in | match-ipsec-out | match-none-in | match-none-out] +``` + +```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> ipsec [match-ipsec-in | match-none-in] +``` + +```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> ipsec [match-ipsec-out | match-none-out] +``` + +```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> ipsec [match-ipsec-in | match-ipsec-out | match-none-in | match-none-out] + +Match based on ipsec. +``` + +```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> limit burst \<0-4294967295\> +``` + +```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> limit burst \<0-4294967295\> +``` + +```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> limit burst \<0-4294967295\> +``` + +```{cfgcmd} set firewall ipv4 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 ipv4 forward filter rule \<1-999999\> limit rate \<text\> +``` + +```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> limit rate \<text\> +``` + +```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> limit rate \<text\> +``` + +```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> limit rate \<text\> + +Specify the maximum average rate as **integer/unit**. For example: +**5/minutes** +``` + +```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> packet-length \<text\> +``` + +```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> packet-length \<text\> +``` + +```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> packet-length \<text\> +``` + +```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> packet-length \<text\> +``` + +```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> packet-length-exclude \<text\> +``` + +```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> packet-length-exclude \<text\> +``` + +```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> packet-length-exclude \<text\> +``` + +```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> packet-length-exclude \<text\> + +Match based on packet length. Specify multiple values from 1 to 65535 and +ranges. +``` + +```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> packet-type [broadcast | host | multicast | other] +``` + +```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> packet-type [broadcast | host | multicast | other] +``` + +```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> packet-type [broadcast | host | multicast | other] +``` + +```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> packet-type [broadcast | host | multicast | other] + +Match based on the packet type. +``` + +```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> protocol [\<text\> | \<0-255\> | all | tcp_udp] +``` + +```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> protocol [\<text\> | \<0-255\> | all | tcp_udp] +``` + +```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> protocol [\<text\> | \<0-255\> | all | tcp_udp] +``` + +```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> protocol [\<text\> | \<0-255\> | all | tcp_udp] + +Match based on protocol number or name as defined in ``/etc/protocols``. +Special names are ``all`` for all protocols and ``tcp_udp`` for TCP and UDP +based packets. The ``!`` character negates the selected protocol. + +:::{code-block} none +set firewall ipv4 forward filter rule 10 protocol tcp_udp +set firewall ipv4 forward filter rule 11 protocol !tcp_udp +::: +``` + +```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> recent count \<1-255\> +``` + +```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> recent count \<1-255\> +``` + +```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> recent count \<1-255\> +``` + +```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> recent count \<1-255\> +``` + +```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> recent time [second | minute | hour] +``` + +```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> recent time [second | minute | hour] +``` + +```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> recent time [second | minute | hour] +``` + +```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> recent time [second | minute | hour] + +Match based on recently seen sources. +``` + +```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> tcp flags [not] \<text\> +``` + +```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> tcp flags [not] \<text\> +``` + +```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> tcp flags [not] \<text\> +``` + +```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> tcp flags [not] \<text\> + +Specify TCP flags. Allowed values are ``ack``, ``cwr``, ``ecn``, ``fin``, +``psh``, ``rst``, ``syn``, and ``urg``. Specify multiple values, and use +``not`` for inverted selection, as shown in the example. + +:::{code-block} none +set firewall ipv4 input filter rule 10 tcp flags 'ack' +set firewall ipv4 input filter rule 12 tcp flags 'syn' +set firewall ipv4 input filter rule 13 tcp flags not 'fin' +::: +``` + +```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> state [established | invalid | new | related] +``` + +```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> state [established | invalid | new | related] +``` + +```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> state [established | invalid | new | related] +``` + +```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> state [established | invalid | new | related] + +Match against the state of a packet. +``` + +```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> time startdate \<text\> +``` + +```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> time startdate \<text\> +``` + +```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> time startdate \<text\> +``` + +```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> time startdate \<text\> +``` + +```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> time starttime \<text\> +``` + +```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> time starttime \<text\> +``` + +```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> time starttime \<text\> +``` + +```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> time starttime \<text\> +``` + +```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> time stopdate \<text\> +``` + +```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> time stopdate \<text\> +``` + +```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> time stopdate \<text\> +``` + +```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> time stopdate \<text\> +``` + +```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> time stoptime \<text\> +``` + +```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> time stoptime \<text\> +``` + +```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> time stoptime \<text\> +``` + +```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> time stoptime \<text\> +``` + +```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> time weekdays \<text\> +``` + +```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> time weekdays \<text\> +``` + +```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> time weekdays \<text\> +``` + +```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> time weekdays \<text\> + +Time to match the defined rule. +``` + +```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> ttl \<eq | gt | lt\> \<0-255\> +``` + +```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> ttl \<eq | gt | lt\> \<0-255\> +``` + +```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> ttl \<eq | gt | lt\> \<0-255\> +``` + +```{cfgcmd} set firewall ipv4 name \<name\> rule \<1-999999\> ttl \<eq | gt | lt\> \<0-255\> + +Match the time to live parameter, where 'eq' means 'equal', 'gt' means +'greater than', and 'lt' means 'less than'. +``` + +### Packet Modifications + +Starting from **VyOS-1.5-rolling-202410060007**, the firewall can modify +packets before sending them out. This feature provides more flexibility in +packet handling. + +```{cfgcmd} set firewall ipv4 prerouting raw rule \<1-999999\> set dscp \<0-63\> +``` + +```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> set dscp \<0-63\> +``` + +```{cfgcmd} set firewall ipv4 output [filter | raw] rule \<1-999999\> set dscp \<0-63\> + +Set a specific value of Differentiated Services Codepoint (DSCP). +``` + +```{cfgcmd} set firewall ipv4 prerouting raw rule \<1-999999\> set mark \<1-2147483647\> +``` + +```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> set mark \<1-2147483647\> +``` + +```{cfgcmd} set firewall ipv4 output [filter | raw] rule \<1-999999\> set mark \<1-2147483647\> + +Set a specific packet mark value. +``` + +```{cfgcmd} set firewall ipv4 prerouting raw rule \<1-999999\> set tcp-mss \<500-1460\> +``` + +```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> set tcp-mss \<500-1460\> +``` + +```{cfgcmd} set firewall ipv4 output [filter | raw] rule \<1-999999\> set tcp-mss \<500-1460\> + +Set the TCP-MSS (TCP maximum segment size) for the connection. +``` + +```{cfgcmd} set firewall ipv4 prerouting raw rule \<1-999999\> set ttl \<0-255\> +``` + +```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> set ttl \<0-255\> +``` + +```{cfgcmd} set firewall ipv4 output [filter | raw] rule \<1-999999\> set ttl \<0-255\> + +Set the TTL (Time to Live) value. +``` + +```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> set connection-mark \<0-2147483647\> +``` + +```{cfgcmd} set firewall ipv4 output [filter | raw] rule \<1-999999\> set connection-mark \<0-2147483647\> + +Set connection mark value. +``` + +## Synproxy + +Synproxy connections + +```{cfgcmd} set firewall ipv4 [input | forward] filter rule \<1-999999\> action synproxy +``` + +```{cfgcmd} set firewall ipv4 [input | forward] filter rule \<1-999999\> protocol tcp +``` + +```{cfgcmd} set firewall ipv4 [input | forward] filter rule \<1-999999\> synproxy tcp mss \<501-65535\> + + Set the TCP-MSS (maximum segment size) for the connection +``` + +```{cfgcmd} set firewall ipv4 [input | forward] filter rule \<1-999999\> synproxy tcp window-scale \<1-14\> + + Set the window scale factor for TCP window scaling +``` + +### Example synproxy + +Requirements to enable synproxy: + +- Traffic must be symmetric. +- Synproxy relies on syncookies and TCP timestamps, ensure these are enabled. +- Disable conntrack loose track option. + +```none +set system sysctl parameter net.ipv4.tcp_timestamps value '1' + +set system conntrack tcp loose disable + +set system conntrack ignore ipv4 rule 10 destination port '8080' + +set system conntrack ignore ipv4 rule 10 protocol 'tcp' + +set system conntrack ignore ipv4 rule 10 tcp flags syn + +set firewall global-options syn-cookies 'enable' + +set firewall ipv4 input filter rule 10 action 'synproxy' + +set firewall ipv4 input filter rule 10 destination port '8080' + +set firewall ipv4 input filter rule 10 inbound-interface name 'eth1' + +set firewall ipv4 input filter rule 10 protocol 'tcp' + +set firewall ipv4 input filter rule 10 synproxy tcp mss '1460' + +set firewall ipv4 input filter rule 10 synproxy tcp window-scale '7' + +set firewall ipv4 input filter rule 1000 action 'drop' + +set firewall ipv4 input filter rule 1000 state invalid + +``` + +## Operation-mode Firewall + +### Rule-set overview + +```{opcmd} show firewall + +This will show you a basic firewall overview, for all rule-sets, not +only for IPv4. + +:::{code-block} none +vyos@vyos:~$ show firewall +Rulesets Information + +--------------------------------- +ipv4 Firewall "forward filter" + +Rule Action Protocol Packets Bytes Conditions +------- -------- ---------- --------- ------- ----------------------------- +20 accept all 0 0 ip saddr @N_TRUSTEDv4 accept +21 jump all 0 0 jump NAME_AUX +default accept all 0 0 + +--------------------------------- +ipv4 Firewall "input filter" + +Rule Action Protocol Packets Bytes Conditions +------- -------- ---------- --------- ------- ------------------------- +10 accept all 156 14377 iifname != @I_LAN accept +default accept all 0 0 + +--------------------------------- +ipv4 Firewall "name AUX" + +Rule Action Protocol Packets Bytes Conditions +------ -------- ---------- --------- ------- -------------------------------------------- +10 accept icmp 0 0 meta l4proto icmp accept +20 accept udp 0 0 meta l4proto udp ip saddr @A_SERVERS accept +30 drop all 0 0 ip saddr != @A_SERVERS iifname "eth2" + +--------------------------------- +ipv4 Firewall "output filter" + +Rule Action Protocol Packets Bytes Conditions +------- -------- ---------- --------- ------- ---------------------------------------- +10 reject all 0 0 oifname @I_LAN +20 accept icmp 2 168 meta l4proto icmp oifname "eth0" accept +default accept all 72 9258 + +--------------------------------- +ipv6 Firewall "input filter" + +Rule Action Protocol Packets Bytes Conditions +------- -------- ---------- --------- ------- ------------------------------- +10 accept all 0 0 ip6 saddr @N6_TRUSTEDv6 accept +default accept all 2 112 + +vyos@vyos:~$ +::: +``` + +```{opcmd} show firewall summary + +This shows you a summary of rule-sets and groups. + +:::{code-block} none +vyos@vyos:~$ show firewall summary +Ruleset Summary + +IPv6 Ruleset: + +Ruleset Hook Ruleset Priority Description +-------------- -------------------- ------------------------- +forward filter +input filter +ipv6_name IPV6-VyOS_MANAGEMENT +ipv6_name IPV6-WAN_IN PUBLIC_INTERNET + +IPv4 Ruleset: + +Ruleset Hook Ruleset Priority Description +-------------- ------------------ ------------------------- +forward filter +input filter +name VyOS_MANAGEMENT +name WAN_IN PUBLIC_INTERNET + +Firewall Groups + +Name Type References Members +----------------------- ------------------ ----------------------- ---------------- +PBX address_group WAN_IN-100 198.51.100.77 +SERVERS address_group WAN_IN-110 192.0.2.10 +WAN_IN-111 192.0.2.11 +WAN_IN-112 192.0.2.12 +WAN_IN-120 +WAN_IN-121 +WAN_IN-122 +SUPPORT address_group VyOS_MANAGEMENT-20 192.168.1.2 +WAN_IN-20 +PHONE_VPN_SERVERS address_group WAN_IN-160 10.6.32.2 +PINGABLE_ADDRESSES address_group WAN_IN-170 192.168.5.2 +WAN_IN-171 +PBX ipv6_address_group IPV6-WAN_IN-100 2001:db8::1 +SERVERS ipv6_address_group IPV6-WAN_IN-110 2001:db8::2 +IPV6-WAN_IN-111 2001:db8::3 +IPV6-WAN_IN-112 2001:db8::4 +IPV6-WAN_IN-120 +IPV6-WAN_IN-121 +IPV6-WAN_IN-122 +SUPPORT ipv6_address_group IPV6-VyOS_MANAGEMENT-20 2001:db8::5 +IPV6-WAN_IN-20 +::: +``` + +```{opcmd} show firewall ipv4 [forward | input | output] filter +``` + +```{opcmd} show firewall ipv4 name \<name\> + +This command will give an overview of a single rule-set. + +:::{code-block} none +vyos@vyos:~$ show firewall ipv4 input filter +Ruleset Information +--------------------------------- +IPv4 Firewall "input filter" +Rule Action Protocol Packets Bytes Conditions +------- -------- ---------- --------- ------- ----------------------------------------- +5 jump all 0 0 iifname "eth2" jump NAME_VyOS_MANAGEMENT +default accept all +::: +``` + +```{opcmd} show firewall ipv4 [forward | input | output] filter rule \<1-999999\> +``` + +```{opcmd} show firewall ipv4 name \<name\> rule \<1-999999\> + +This command gives an overview of a rule in a single rule-set, plus +information for default action. +``` +```none +vyos@vyos:~$show firewall ipv4 output filter rule 20 +Rule Information + +--------------------------------- +ipv4 Firewall "output filter" + +Rule Action Protocol Packets Bytes Conditions +------- -------- ---------- --------- ------- ---------------------------------------- +20 accept icmp 2 168 meta l4proto icmp oifname "eth0" accept +default accept all 286 47614 + +vyos@vyos:~$ +``` + +```{opcmd} show firewall statistics + +This will show you statistics of all rule-sets since the last boot. +``` + +### Show Firewall log + +```{opcmd} show log firewall + +``` +```{opcmd} show log firewall ipv4 +``` + +```{opcmd} show log firewall ipv4 [forward | input | output | name] +``` + +```{opcmd} show log firewall ipv4 [forward | input | output] filter +``` + +```{opcmd} show log firewall ipv4 name \<name\> +``` + +```{opcmd} show log firewall ipv4 [forward | input | output] filter rule \<rule\> +``` + +```{opcmd} show log firewall ipv4 name \<name\> rule \<rule\> + +Show the logs of all firewall; show all IPv4 firewall logs; show all logs +for particular hook; show all logs for particular hook and priority; +show all logs for particular custom chain; show logs for specific rule-set. +``` + +### Example Partial Config + +```none +firewall { + 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 + } + } + ipv4 { + forward { + filter { + default-action accept + rule 5 { + action accept + source { + group { + network-group GOOD-NETWORKS + } + } + } + rule 10 { + action drop + description "Bad Networks" + protocol all + source { + group { + network-group BAD-NETWORKS + } + } + } + } + } + } +} +``` + +### Update geoip database + +```{opcmd} update geoip + +Command to update GeoIP database and firewall sets. +```
\ No newline at end of file diff --git a/docs/configuration/firewall/ipv6.md b/docs/configuration/firewall/ipv6.md new file mode 100644 index 00000000..e9011b4c --- /dev/null +++ b/docs/configuration/firewall/ipv6.md @@ -0,0 +1,1567 @@ +--- +lastproofread: '2026-04-01' +--- + +(firewall-ipv6-configuration)= + +# IPv6 Firewall Configuration + +## Overview + +This section covers useful information about IPv6 firewall configuration and +appropriate operation-mode commands. + +This section describes the following configuration commands: + +```{cfgcmd} set firewall ipv6 ... +``` + +To learn about the general traffic flow in VyOS firewalls, see {doc}`Firewall </configuration/firewall/index>`. + +```none +- set firewall + * ipv6 + - forward + + filter + - input + + filter + - output + + filter + + raw + - prerouting + + raw + - name + + custom_name +``` + +The router first receives all traffic and processes it in the **prerouting** +section. + + +This stage includes: + + +- **Firewall Prerouting**: commands found under `set firewall ipv6 + prerouting raw ...` +- {doc}`Conntrack Ignore</configuration/system/conntrack>`: `set system + conntrack ignore ipv6...` +- {doc}`Policy Route</configuration/policy/route>`: commands found under + `set policy route6 ...` +- {doc}`Destination NAT</configuration/nat/nat44>`: commands found under + `set nat66 destination ...` + + +For transit traffic that the router receives and forwards, the base chain is +**forward**. The following diagram shows a simplified packet flow for transit +traffic: + + +:::{figure} /_static/images/firewall-fwd-packet-flow.webp +::: + + +Use `set firewall ipv6 forward filter ...` to configure filtering rules for +transit traffic. This command corresponds to stage 5 and is highlighted in red +in the diagram. + + +For traffic destined to the router, use the **input** chain. For traffic the +router generates, use the **output** chain. The following diagram shows the +packet flow for traffic destined to the router and traffic generated by the +router (starting from circle number 6): + + +:::{figure} /_static/images/firewall-input-packet-flow.webp +::: + + +Use `set firewall ipv6 input filter ...` to configure traffic destined to +the router. + + +Use `set firewall ipv6 output ...` to configure traffic the router generates. +Two sub-chains are available: **filter** and **raw**: + + +- **Output Prerouting**: `set firewall ipv6 output raw ...`. + As described in **Prerouting**, the firewall processes rules in this + section before the connection tracking subsystem. +- **Output Filter**: `set firewall ipv6 output filter ...`. The firewall + processes rules in this section after the connection tracking subsystem. + + +:::{note} +**Important note about default-actions:** +If you do not define a default action for a base chain, the system sets +the default action to **accept** for that chain. For custom chains, if you +do not define a default action, the system sets the default-action to +**drop** +::: + + +Create custom firewall chains using the commands +`set firewall ipv6 name <name> ...`. To use the custom chain, define a +rule with **action jump** and the appropriate **target** in a base chain. + + +## Firewall - IPv6 Rules + + +Create firewall rules for firewall filtering. Each rule is numbered and has +an action to apply when the rule is matched. You can specify multiple matching +criteria. Packets go through rules from 1 - 999999, so order is crucial. The +firewall executes the action of the first matching rule. + + +### Actions + + +If you define a rule, you must define an action for it. The action tells the +firewall what to do when all criteria for that rule are met. + + +The action can be : + + +- `accept`: accept the packet. +- `continue`: continue parsing next rule. +- `drop`: drop the packet. +- `reject`: reject the packet. +- `jump`: jump to another custom chain. +- `return`: Return from the current chain and continue at the next rule + of the last chain. +- `queue`: Enqueue packet to userspace. +- `synproxy`: synproxy the packet. + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> action [accept | continue | drop | jump | queue | reject | return | synproxy] +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> action [accept | continue | drop | jump | queue | reject | return | synproxy] +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> action [accept | continue | drop | jump | queue | reject | return] +``` + +```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> action [accept | continue | drop | jump | queue | reject | return] + +This required setting defines the action of the current rule. If you set +the action to jump, you must also define a jump-target. +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> jump-target \<text\> +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> jump-target \<text\> +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> jump-target \<text\> +``` + +```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> jump-target \<text\> + +Use this command only when action is set to ``jump``. Specify the jump +target. +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> queue \<0-65535\> +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> queue \<0-65535\> +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> queue \<0-65535\> +``` + +```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> queue \<0-65535\> + +Use this command only when action is set to ``queue``. Specify the queue +target. Queue ranges are also supported. +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> queue-options bypass +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> queue-options bypass +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> queue-options bypass +``` + +```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> queue-options bypass + +Use this command only when action is set to ``queue``. This command allows +the packet to go through the firewall when no userspace software is connected +to the queue. +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> queue-options fanout +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> queue-options fanout +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> queue-options fanout +``` + +```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> queue-options fanout + +Use this command only when action is set to ``queue``. This command +distributes packets among multiple queues. +``` + +Also, **default-action** is an action that takes place whenever a packet does +not match any rule in its chain. For base chains, possible options for +**default-action** are **accept** or **drop**. + +```{cfgcmd} set firewall ipv6 forward filter default-action [accept | drop] +``` + +```{cfgcmd} set firewall ipv6 input filter default-action [accept | drop] +``` + +```{cfgcmd} set firewall ipv6 output filter default-action [accept | drop] +``` + +```{cfgcmd} set firewall ipv6 name \<name\> default-action [accept | drop | jump | queue | reject | return] + +Set the default action of the rule-set if a packet does not match any rule +criteria. If you set default-action to ``jump``, you must also define +``default-jump-target``. For base chains, you can only set the default +action to ``accept`` or ``drop``. For custom chains, more actions are +available. +``` + +```{cfgcmd} set firewall ipv6 name \<name\> default-jump-target \<text\> + +To be used only when ``default-action`` is set to ``jump``. Use this +command to specify the jump target for the default rule. +``` +:::{note} +**Important note about default-actions:** +If you do not define the default action for a base chain, the system sets +the default action to **accept** for that chain. For custom chains, if you +do not define a default action, the system sets the default-action to +**drop**. +::: + + +### Firewall Logs + + +You can enable logging for each firewall rule. When enabled, you can also +define other log options. + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> log +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> log +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> log +``` + +```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> log + +Enable logging for matched packets. If this configuration command is not +present, logging is disabled. +``` + +```{cfgcmd} set firewall ipv6 forward filter default-log +``` + +```{cfgcmd} set firewall ipv6 input filter default-log +``` + +```{cfgcmd} set firewall ipv6 output filter default-log +``` + +```{cfgcmd} set firewall ipv6 name \<name\> default-log + +Use this command to enable the logging of the default action on +the specified chain. +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> log-options level [emerg | alert | crit | err | warn | notice | info | debug] +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> log-options level [emerg | alert | crit | err | warn | notice | info | debug] +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> log-options level [emerg | alert | crit | err | warn | notice | info | debug] +``` + +```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> log-options level [emerg | alert | crit | err | warn | notice | info | debug] + +Define log-level. Only applicable if rule log is enabled. +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> log-options group \<0-65535\> +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> log-options group \<0-65535\> +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> log-options group \<0-65535\> +``` + +```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> log-options group \<0-65535\> + +Define the log group to send messages to. Only applicable if rule log is +enabled. +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> log-options snapshot-length \<0-9000\> +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> log-options snapshot-length \<0-9000\> +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> log-options snapshot-length \<0-9000\> +``` + +```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> log-options snapshot-length \<0-9000\> + +Define the length of packet payload to include in a netlink message. Only +applicable when rule logging is enabled and log group is defined. +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> log-options queue-threshold \<0-65535\> +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> log-options queue-threshold \<0-65535\> +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> log-options queue-threshold \<0-65535\> +``` + +```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> log-options queue-threshold \<0-65535\> + +Define the number of packets to queue inside the kernel before sending them +to userspace. Only applicable when rule logging is enabled and log group is +defined. +``` + +### Firewall Description + + +For reference, you can define descriptions on every rule and custom chain. + +```{cfgcmd} set firewall ipv6 name \<name\> description \<text\> + +Provide a rule-set description to a custom firewall chain. +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> description \<text\> +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> description \<text\> +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> description \<text\> +``` + +```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> description \<text\> + +Provide a description for each rule. +``` + +### Rule Status + + +New rules are enabled by default. In some cases, you may want to disable a +rule rather than remove it. + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> disable +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> disable +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> disable +``` + +```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> disable + +Command for disabling a rule but keep it in the configuration. +``` + +### Matching criteria + + +There are a lot of matching criteria against which the packet can be tested. + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> connection-status nat [destination | source] +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> connection-status nat [destination | source] +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> connection-status nat [destination | source] +``` + +```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> connection-status nat [destination | source] + +Match packets based on NAT connection status. +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> connection-mark \<1-2147483647\> +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> connection-mark \<1-2147483647\> +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> connection-mark \<1-2147483647\> +``` + +```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> connection-mark \<1-2147483647\> + +Match packets based on connection mark. +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> source address [address | addressrange | CIDR] +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> source address [address | addressrange | CIDR] +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> source address [address | addressrange | CIDR] +``` + +```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> source address [address | addressrange | CIDR] +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> destination address [address | addressrange | CIDR] +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> destination address [address | addressrange | CIDR] +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> destination address [address | addressrange | CIDR] +``` + +```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> destination address [address | addressrange | CIDR] + +Match based on source or destination address. This is similar to network +groups, but you can negate the matching addresses here. + +:::{code-block} none +set firewall ipv6 name FOO rule 100 source address 2001:db8::202 +::: +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> source address-mask [address] +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> source address-mask [address] +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> source address-mask [address] +``` + +```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> source address-mask [address] +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> destination address-mask [address] +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> destination address-mask [address] +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> destination address-mask [address] +``` + +```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> destination address-mask [address] + +Apply an arbitrary netmask to mask addresses and match only a specific +portion. This is useful for IPv6 because rules remain valid when the IPv6 +prefix changes if the host portion of the system's IPv6 address is static. +Examples include SLAAC and tokenised IPv6 addresses + +This function works for both individual addresses and address groups. + + +:::{code-block} none +# Match any IPv6 address with the suffix ::0000:0000:0000:beef +set firewall ipv6 forward filter rule 100 destination address ::beef +set firewall ipv6 forward filter rule 100 destination address-mask ::ffff:ffff:ffff:ffff +# Address groups +set firewall group ipv6-address-group WEBSERVERS address ::1000 +set firewall group ipv6-address-group WEBSERVERS address ::2000 +set firewall ipv6 forward filter rule 200 source group address-group WEBSERVERS +set firewall ipv6 forward filter rule 200 source address-mask ::ffff:ffff:ffff:ffff +::: +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> source fqdn \<fqdn\> +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> source fqdn \<fqdn\> +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> source fqdn \<fqdn\> +``` + +```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> source fqdn \<fqdn\> +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> destination fqdn \<fqdn\> +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> destination fqdn \<fqdn\> +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> destination fqdn \<fqdn\> +``` + +```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> destination fqdn \<fqdn\> + +Specify a Fully Qualified Domain Name as source or destination to match. +Ensure that the router can resolve the DNS query. +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> source geoip country-code \<country\> +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> source geoip country-code \<country\> +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> source geoip country-code \<country\> +``` + +```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> source geoip country-code \<country\> +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> destination geoip country-code \<country\> +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> destination geoip country-code \<country\> +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> destination geoip country-code \<country\> +``` + +```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> destination geoip country-code \<country\> +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> source geoip inverse-match +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> source geoip inverse-match +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> source geoip inverse-match +``` + +```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> source geoip inverse-match +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> destination geoip inverse-match +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> destination geoip inverse-match +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> destination geoip inverse-match +``` + +```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> destination geoip inverse-match + +Match IP addresses based on their geolocation. For more information, see +GeoIP matching. +Use inverse-match to match anything except the specified country codes. +``` + +DB-IP.com provides data under CC-BY-4.0 license. Attribution is required and +redistribution is permitted, allowing VyOS to include a database in images +(approximately 3 MB compressed). The package includes a cron script that you +can manually call through op-mode update geoip to keep the database and rules +updated. + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> source mac-address \<mac-address\> +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> source mac-address \<mac-address\> +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> source mac-address \<mac-address\> +``` + +```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> source mac-address \<mac-address\> + +You can specify only a source MAC address to match. + +:::{code-block} none +set firewall ipv6 input filter rule 100 source mac-address 00:53:00:11:22:33 +set firewall ipv6 input filter rule 101 source mac-address !00:53:00:aa:12:34 +::: +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> source port [1-65535 | portname | start-end] +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> source port [1-65535 | portname | start-end] +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> source 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 forward filter rule \<1-999999\> destination port [1-65535 | portname | start-end] +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> destination port [1-65535 | portname | start-end] +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> destination port [1-65535 | portname | start-end] +``` + +```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> destination port [1-65535 | portname | start-end] + +Specify a port by number or by name as defined in ``/etc/services``. + +:::{code-block} none +set firewall ipv6 forward filter rule 10 source port '22' +set firewall ipv6 forward filter rule 11 source port '!http' +set firewall ipv6 forward filter 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 forward filter rule 10 source port '!22,https,3333-3338' +::: +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> source group address-group \<name | !name\> +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> source group address-group \<name | !name\> +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> source group address-group \<name | !name\> +``` + +```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> source group address-group \<name | !name\> +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> destination group address-group \<name | !name\> +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> destination group address-group \<name | !name\> +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> destination group address-group \<name | !name\> +``` + +```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> destination group address-group \<name | !name\> + +Specify an address group. You can prepend the character ``!`` to invert the +matching criteria. +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> source group dynamic-address-group \<name | !name\> +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> source group dynamic-address-group \<name | !name\> +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> source group dynamic-address-group \<name | !name\> +``` + +```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> source group dynamic-address-group \<name | !name\> +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> destination group dynamic-address-group \<name | !name\> +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> destination group dynamic-address-group \<name | !name\> +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> destination group dynamic-address-group \<name | !name\> +``` + +```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> destination group dynamic-address-group \<name | !name\> + +Specify a dynamic address group. You can prepend the character ``!`` to +invert the matching criteria. +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> source group network-group \<name | !name\> +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> source group network-group \<name | !name\> +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> source group network-group \<name | !name\> +``` + +```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> source group network-group \<name | !name\> +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> destination group network-group \<name | !name\> +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> destination group network-group \<name | !name\> +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> destination group network-group \<name | !name\> +``` + +```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> destination group network-group \<name | !name\> + +Specify a network group. You can prepend the character ``!`` to invert the +matching criteria. +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> source group port-group \<name | !name\> +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> source group port-group \<name | !name\> +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> source group port-group \<name | !name\> +``` + +```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> source group port-group \<name | !name\> +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> destination group port-group \<name | !name\> +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> destination group port-group \<name | !name\> +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> destination group port-group \<name | !name\> +``` + +```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> destination group port-group \<name | !name\> + +Specify a port group. You can prepend the character ``!`` to invert the +matching criteria. +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> source group domain-group \<name | !name\> +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> source group domain-group \<name | !name\> +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> source group domain-group \<name | !name\> +``` + +```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> source group domain-group \<name | !name\> +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> destination group domain-group \<name | !name\> +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> destination group domain-group \<name | !name\> +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> destination group domain-group \<name | !name\> +``` + +```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> destination group domain-group \<name | !name\> + +Specify a domain group. You can prepend the character ``!`` to invert the +matching criteria. +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> source group mac-group \<name | !name\> +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> source group mac-group \<name | !name\> +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> source group mac-group \<name | !name\> +``` + +```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> source group mac-group \<name | !name\> +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> destination group mac-group \<name | !name\> +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> destination group mac-group \<name | !name\> +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> destination group mac-group \<name | !name\> +``` + +```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> destination group mac-group \<name | !name\> + +Specify a MAC group. You can prepend the character ``!`` to invert the +matching criteria. +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> dscp [0-63 | start-end] +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> dscp [0-63 | start-end] +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> dscp [0-63 | start-end] +``` + +```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> dscp [0-63 | start-end] +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> dscp-exclude [0-63 | start-end] +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> dscp-exclude [0-63 | start-end] +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> dscp-exclude [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 ipv6 forward filter rule \<1-999999\> fragment [match-frag | match-non-frag] +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> fragment [match-frag | match-non-frag] +``` + +```{cfgcmd} set firewall ipv6 output filter 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 packets based on fragmentation. +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> icmpv6 [code | type] \<0-255\> +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> icmpv6 [code | type] \<0-255\> +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> icmpv6 [code | type] \<0-255\> +``` + +```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> icmpv6 [code | type] \<0-255\> + +Match packets based on ICMP or ICMPv6 code and type. +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> icmpv6 type-name \<text\> +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> icmpv6 type-name \<text\> +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> icmpv6 type-name \<text\> +``` + +```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> icmpv6 type-name \<text\> + +Match based on ICMPv6 type-name. Press **Tab** for information about +supported **type-name** criteria. +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> inbound-interface name \<iface\> +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> inbound-interface name \<iface\> +``` + +```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> inbound-interface name \<iface\> + +Match based on inbound interface. You can use the wildcard ``*``. For +example: ``eth2*``. You can prepend the character ``!`` to invert the +matching criteria. For example ``!eth2`` +``` +:::{note} +If an interface is attached to a non-default VRF, when using +**inbound-interface**, use the VRF name. For example: +`set firewall ipv6 forward filter rule 10 inbound-interface name MGMT` +::: +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> inbound-interface group \<iface_group\> +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> inbound-interface group \<iface_group\> +``` + +```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> inbound-interface group \<iface_group\> + +Match based on the inbound interface group. You can prepend the character +``!`` to invert the matching criteria. For example ``!IFACE_GROUP`` +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> outbound-interface name \<iface\> +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> outbound-interface name \<iface\> +``` + +```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> outbound-interface name \<iface\> + +Match based on outbound interface. You can use the wildcard ``*``. For +example: ``eth2*``. You can prepend the character ``!`` to invert the +matching criteria. For example ``!eth2`` +``` +:::{note} +If an interface is attached to a non-default VRF, when using +**outbound-interface**, use the physical interface name. For example: +`set firewall ipv6 forward filter rule 10 outbound-interface name eth0` +::: +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> outbound-interface group \<iface_group\> +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> outbound-interface group \<iface_group\> +``` + +```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> outbound-interface group \<iface_group\> + +Match based on outbound interface group. You can prepend the character ``!`` +to invert the matching criteria. For example ``!IFACE_GROUP`` +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> ipsec [match-ipsec-in | match-ipsec-out | match-none-in | match-none-out] +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> ipsec [match-ipsec-in | match-none-in] +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> ipsec [match-ipsec-out | match-none-out] +``` + +```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> ipsec [match-ipsec-in | match-ipsec-out | match-none-in | match-none-out] + +Match packets based on IPsec. +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> limit burst \<0-4294967295\> +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> limit burst \<0-4294967295\> +``` + +```{cfgcmd} set firewall ipv6 output filter 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 allowed to exceed the rate +limit. +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> limit rate \<text\> +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> limit rate \<text\> +``` + +```{cfgcmd} set firewall ipv6 output filter 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, specify ``5/minutes``. +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> packet-length \<text\> +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> packet-length \<text\> +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> packet-length \<text\> +``` + +```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> packet-length \<text\> +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> packet-length-exclude \<text\> +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> packet-length-exclude \<text\> +``` + +```{cfgcmd} set firewall ipv6 output filter 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. You can specify multiple values from 1 to +65535 and ranges. +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> packet-type [broadcast | host | multicast | other] +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> packet-type [broadcast | host | multicast | other] +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> packet-type [broadcast | host | multicast | other] +``` + +```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> packet-type [broadcast | host | multicast | other] + +Match based on packet type. +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> protocol [\<text\> | \<0-255\> | all | tcp_udp] +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> protocol [\<text\> | \<0-255\> | all | tcp_udp] +``` + +```{cfgcmd} set firewall ipv6 output filter 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 based on protocol number or name as defined in ``/etc/protocols``. +Specify ``all`` for all protocols and ``tcp_udp`` for TCP and UDP packets. +Prepend ``!`` to negate the protocol selection. + +:::{code-block} none +set firewall ipv6 input filter rule 10 protocol tcp +::: +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> recent count \<1-255\> +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> recent count \<1-255\> +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> recent count \<1-255\> +``` + +```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> recent count \<1-255\> +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> recent time [second | minute | hour] +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> recent time [second | minute | hour] +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> recent time [second | minute | hour] +``` + +```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> recent time [second | minute | hour] + +Match packets based on recently seen sources. +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> tcp flags [not] \<text\> +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> tcp flags [not] \<text\> +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> tcp flags [not] \<text\> +``` + +```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> tcp flags [not] \<text\> + +Allowed values for TCP flags: ``ack``, ``cwr``, ``ecn``, ``fin``, ``psh``, +``rst``, ``syn``, and ``urg``. You can specify multiple values. To invert +the selection, use ``not``, as shown in the following example. + +:::{code-block} none +set firewall ipv6 input filter rule 10 tcp flags 'ack' +set firewall ipv6 input filter rule 12 tcp flags 'syn' +set firewall ipv6 input filter rule 13 tcp flags not 'fin' +::: +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> state [established | invalid | new | related] +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> state [established | invalid | new | related] +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> state [established | invalid | new | related] +``` + +```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> state [established | invalid | new | related] + +Match based on packet state. +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> time startdate \<text\> +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> time startdate \<text\> +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> time startdate \<text\> +``` + +```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> time startdate \<text\> +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> time starttime \<text\> +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> time starttime \<text\> +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> time starttime \<text\> +``` + +```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> time starttime \<text\> +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> time stopdate \<text\> +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> time stopdate \<text\> +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> time stopdate \<text\> +``` + +```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> time stopdate \<text\> +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> time stoptime \<text\> +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> time stoptime \<text\> +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> time stoptime \<text\> +``` + +```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> time stoptime \<text\> +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> time weekdays \<text\> +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> time weekdays \<text\> +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> time weekdays \<text\> +``` + +```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> time weekdays \<text\> + +Match packets based on time criteria. +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> hop-limit \<eq | gt | lt\> \<0-255\> +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> hop-limit \<eq | gt | lt\> \<0-255\> +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> hop-limit \<eq | gt | lt\> \<0-255\> +``` + +```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> hop-limit \<eq | gt | lt\> \<0-255\> + +Match the hop-limit parameter. Use ``eq`` for equal, ``gt`` for greater than, +and ``lt`` for less than. +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> recent count \<1-255\> +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> recent count \<1-255\> +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> recent count \<1-255\> +``` + +```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> recent count \<1-255\> +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> recent time \<second | minute | hour\> +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> recent time \<second | minute | hour\> +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> recent time \<second | minute | hour\> +``` + +```{cfgcmd} set firewall ipv6 name \<name\> rule \<1-999999\> recent time \<second | minute | hour\> + +Match when the specified number of connections occur within the specified +time period. Use these criteria to block brute-force attempts. +``` + +### Packet Modifications + + +The firewall can modify packets before sending them. +This feature provides more flexibility for packet handling. + +```{cfgcmd} set firewall ipv6 prerouting raw rule \<1-999999\> set dscp \<0-63\> +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> set dscp \<0-63\> +``` + +```{cfgcmd} set firewall ipv6 output [filter | raw] rule \<1-999999\> set dscp \<0-63\> + +Set a specific value of Differentiated Services Codepoint (DSCP). +``` + +```{cfgcmd} set firewall ipv6 prerouting raw rule \<1-999999\> set mark \<1-2147483647\> +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> set mark \<1-2147483647\> +``` + +```{cfgcmd} set firewall ipv6 output [filter | raw] rule \<1-999999\> set mark \<1-2147483647\> + +Set a specific packet mark value. +``` + +```{cfgcmd} set firewall ipv6 prerouting raw rule \<1-999999\> set tcp-mss \<500-1460\> +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> set tcp-mss \<500-1460\> +``` + +```{cfgcmd} set firewall ipv6 output [filter | raw] rule \<1-999999\> set tcp-mss \<500-1460\> + +Set the TCP-MSS (TCP maximum segment size) for the connection. +``` + +```{cfgcmd} set firewall ipv6 prerouting raw rule \<1-999999\> set hop-limit \<0-255\> +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> set hop-limit \<0-255\> +``` + +```{cfgcmd} set firewall ipv6 output [filter | raw] rule \<1-999999\> set hop-limit \<0-255\> + +Set hop limit value. +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> set connection-mark \<0-2147483647\> +``` + +```{cfgcmd} set firewall ipv6 output [filter | raw] rule \<1-999999\> set connection-mark \<0-2147483647\> + +Set connection mark value. +``` + +## Synproxy + + +Synproxy connections + +```{cfgcmd} set firewall ipv6 [input | forward] filter rule \<1-999999\> action synproxy +``` + +```{cfgcmd} set firewall ipv6 [input | forward] filter rule \<1-999999\> protocol tcp +``` + +```{cfgcmd} set firewall ipv6 [input | forward] filter rule \<1-999999\> synproxy tcp mss \<501-65535\> + + Set the TCP MSS (maximum segment size) for the connection. +``` + +```{cfgcmd} set firewall ipv6 [input | forward] filter rule \<1-999999\> synproxy tcp window-scale \<1-14\> + + Set the window scale factor for TCP window scaling. +``` + +### Example synproxy + + +Requirements to enable synproxy: + + +- Traffic must be symmetric +- Synproxy relies on syncookies and TCP timestamps, ensure these are enabled +- Disable conntrack loose track option + +```none +set system sysctl parameter net.ipv4.tcp_timestamps value '1' + + +set system conntrack tcp loose disable + +set system conntrack ignore ipv6 rule 10 destination port '8080' + +set system conntrack ignore ipv6 rule 10 protocol 'tcp' + +set system conntrack ignore ipv6 rule 10 tcp flags syn + + +set firewall global-options syn-cookies 'enable' + +set firewall ipv6 input filter rule 10 action 'synproxy' + +set firewall ipv6 input filter rule 10 destination port '8080' + +set firewall ipv6 input filter rule 10 inbound-interface name 'eth1' + +set firewall ipv6 input filter rule 10 protocol 'tcp' + +set firewall ipv6 input filter rule 10 synproxy tcp mss '1460' + +set firewall ipv6 input filter rule 10 synproxy tcp window-scale '7' + +set firewall ipv6 input filter rule 1000 action 'drop' + +set firewall ipv6 input filter rule 1000 state invalid + +``` + +## Operation-mode Firewall + + +### Rule-set overview + +```{opcmd} show firewall + +Show a basic firewall overview for all rule-sets, not only for IPv6: + +:::{code-block} none +vyos@vyos:~$ show firewall +Rulesets Information + +--------------------------------- +IPv4 Firewall "forward filter" + +Rule Action Protocol Packets Bytes Conditions +------- -------- ---------- --------- ------- ----------------------------------------- +5 jump all 0 0 iifname "eth1" jump NAME_VyOS_MANAGEMENT +10 jump all 0 0 oifname "eth1" jump NAME_WAN_IN +15 jump all 0 0 iifname "eth3" jump NAME_WAN_IN +default accept all + +--------------------------------- +IPv4 Firewall "name VyOS_MANAGEMENT" + +Rule Action Protocol Packets Bytes Conditions +------- -------- ---------- --------- ------- -------------------------------- +5 accept all 0 0 ct state established accept +10 drop all 0 0 ct state invalid +20 accept all 0 0 ip saddr @A_GOOD_GUYS accept +30 accept all 0 0 ip saddr @N_ENTIRE_RANGE accept +40 accept all 0 0 ip saddr @A_VyOS_SERVERS accept +50 accept icmp 0 0 meta l4proto icmp accept +default drop all 0 0 + +--------------------------------- +IPv6 Firewall "forward filter" + +Rule Action Protocol +------- -------- ---------- +5 jump all +10 jump all +15 jump all +default accept all + +--------------------------------- +IPv6 Firewall "input filter" + +Rule Action Protocol +------- -------- ---------- +5 jump all +default accept all + +--------------------------------- +IPv6 Firewall "ipv6_name IPV6-VyOS_MANAGEMENT" + +Rule Action Protocol +------- -------- ---------- +5 accept all +10 drop all +20 accept all +30 accept all +40 accept all +50 accept ipv6-icmp +default drop all +::: +``` + +```{opcmd} show firewall summary + +This will show you a summary of rule-sets and groups + +:::{code-block} none +vyos@vyos:~$ show firewall summary +Ruleset Summary + +IPv6 Ruleset: + +Ruleset Hook Ruleset Priority Description +-------------- -------------------- ------------------------- +forward filter +input filter +ipv6_name IPV6-VyOS_MANAGEMENT +ipv6_name IPV6-WAN_IN PUBLIC_INTERNET + +IPv4 Ruleset: + +Ruleset Hook Ruleset Priority Description +-------------- ------------------ ------------------------- +forward filter +input filter +name VyOS_MANAGEMENT +name WAN_IN PUBLIC_INTERNET + +Firewall Groups + +Name Type References Members +----------------------- ------------------ ----------------------- ---------------- +PBX address_group WAN_IN-100 198.51.100.77 +SERVERS address_group WAN_IN-110 192.0.2.10 +WAN_IN-111 192.0.2.11 +WAN_IN-112 192.0.2.12 +WAN_IN-120 +WAN_IN-121 +WAN_IN-122 +SUPPORT address_group VyOS_MANAGEMENT-20 192.168.1.2 +WAN_IN-20 +PHONE_VPN_SERVERS address_group WAN_IN-160 10.6.32.2 +PINGABLE_ADDRESSES address_group WAN_IN-170 192.168.5.2 +WAN_IN-171 +PBX ipv6_address_group IPV6-WAN_IN-100 2001:db8::1 +SERVERS ipv6_address_group IPV6-WAN_IN-110 2001:db8::2 +IPV6-WAN_IN-111 2001:db8::3 +IPV6-WAN_IN-112 2001:db8::4 +IPV6-WAN_IN-120 +IPV6-WAN_IN-121 +IPV6-WAN_IN-122 +SUPPORT ipv6_address_group IPV6-VyOS_MANAGEMENT-20 2001:db8::5 +IPV6-WAN_IN-20 +::: +``` + +```{opcmd} show firewall ipv6 [forward | input | output] filter +``` + +```{opcmd} show firewall ipv6 ipv6-name \<name\> + +This command will give an overview of a single rule-set. + +:::{code-block} none +vyos@vyos:~$ show firewall ipv6 input filter +Ruleset Information + +--------------------------------- +ipv6 Firewall "input filter" + +Rule Action Protocol Packets Bytes Conditions +------- -------- ---------- --------- ------- ------------------------------------------------------------------------------ +10 jump all 13 1456 iifname "eth1" jump NAME6_INP-ETH1 +20 accept ipv6-icmp 10 1112 meta l4proto ipv6-icmp iifname "eth0" prefix "[ipv6-INP-filter-20-A]" accept +default accept all 14 1584 + +vyos@vyos:~$ +::: +``` + +```{opcmd} show firewall ipv6 [forward | input | output] filter rule \<1-999999\> +``` + +```{opcmd} show firewall ipv6 name \<name\> rule \<1-999999\> +``` + +```{opcmd} show firewall ipv6 ipv6-name \<name\> rule \<1-999999\> + +This command will give an overview of a rule in a single rule-set +``` + +```{opcmd} show firewall group \<name\> + +Show an overview of defined groups, including the type, members, and where +the group is used. + +:::{code-block} none +vyos@vyos:~$ show firewall group LAN +Firewall Groups + +Name Type References Members +------------ ------------------ ----------------------- ---------------- +LAN ipv6_network_group IPV6-VyOS_MANAGEMENT-30 2001:db8::0/64 +IPV6-WAN_IN-30 +LAN network_group VyOS_MANAGEMENT-30 192.168.200.0/24 +WAN_IN-30 +::: +``` + +```{opcmd} show firewall statistics + +Show statistics of all rule-sets since the last boot. +``` + +### Show Firewall log + +```{opcmd} show log firewall +``` + +```{opcmd} show log firewall ipv6 +``` + +```{opcmd} show log firewall ipv6 [forward | input | output | name] +``` + +```{opcmd} show log firewall ipv6 [forward | input | output] filter +``` + +```{opcmd} show log firewall ipv6 name \<name\> +``` + +```{opcmd} show log firewall ipv6 [forward | input | output] filter rule \<rule\> +``` + +```{opcmd} show log firewall ipv6 name \<name\> rule \<rule\> + +Show firewall logs for all firewalls, all IPv6 firewalls, specific hooks, +specific priorities, specific custom chains, or specific rule-sets. +``` + +### Example Partial Config + +```none +firewall { + ipv6 { + input { + filter { + rule 10 { + action jump + inbound-interface { + name eth1 + } + jump-target INP-ETH1 + } + rule 20 { + action accept + inbound-interface { + name eth0 + } + log + protocol ipv6-icmp + } + } + } + name INP-ETH1 { + default-action drop + default-log + rule 10 { + action accept + protocol tcp_udp + } + } + } +} +``` + +### 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/bridge.rst b/docs/configuration/firewall/rst-bridge.rst index 53775514..53775514 100644 --- a/docs/configuration/firewall/bridge.rst +++ b/docs/configuration/firewall/rst-bridge.rst diff --git a/docs/configuration/firewall/flowtables.rst b/docs/configuration/firewall/rst-flowtables.rst index f996a59e..f996a59e 100644 --- a/docs/configuration/firewall/flowtables.rst +++ b/docs/configuration/firewall/rst-flowtables.rst diff --git a/docs/configuration/firewall/global-options.rst b/docs/configuration/firewall/rst-global-options.rst index 8eec5c3f..8eec5c3f 100644 --- a/docs/configuration/firewall/global-options.rst +++ b/docs/configuration/firewall/rst-global-options.rst diff --git a/docs/configuration/firewall/groups.rst b/docs/configuration/firewall/rst-groups.rst index 9d29866e..9d29866e 100644 --- a/docs/configuration/firewall/groups.rst +++ b/docs/configuration/firewall/rst-groups.rst diff --git a/docs/configuration/firewall/index.rst b/docs/configuration/firewall/rst-index.rst index c4b3c808..c4b3c808 100644 --- a/docs/configuration/firewall/index.rst +++ b/docs/configuration/firewall/rst-index.rst diff --git a/docs/configuration/firewall/ipv4.rst b/docs/configuration/firewall/rst-ipv4.rst index efd0fe18..efd0fe18 100644 --- a/docs/configuration/firewall/ipv4.rst +++ b/docs/configuration/firewall/rst-ipv4.rst diff --git a/docs/configuration/firewall/ipv6.rst b/docs/configuration/firewall/rst-ipv6.rst index d31ceb6f..d31ceb6f 100644 --- a/docs/configuration/firewall/ipv6.rst +++ b/docs/configuration/firewall/rst-ipv6.rst diff --git a/docs/configuration/firewall/zone.rst b/docs/configuration/firewall/rst-zone.rst index f3b12473..f3b12473 100644 --- a/docs/configuration/firewall/zone.rst +++ b/docs/configuration/firewall/rst-zone.rst diff --git a/docs/configuration/firewall/zone.md b/docs/configuration/firewall/zone.md new file mode 100644 index 00000000..bbb93993 --- /dev/null +++ b/docs/configuration/firewall/zone.md @@ -0,0 +1,201 @@ +--- +lastproofread: '2026-03-30' +--- + +(firewall-zone)= + +# Zone-Based Firewall + +## Overview + +:::{note} +All VyOS versions built after 2023-10-22 (VyOS 1.4 and 1.5) support +this feature. +::: + +This section provides information on firewall configuration for the +zone-based firewall. This section covers the following configuration +commands: + +```{cfgcmd} set firewall zone ... +``` + +To learn about the general traffic flow in VyOS firewalls, +see {doc}`Firewall </configuration/firewall/index>`. + +```none +- set firewall + * zone + - custom_zone_name + + ... +``` + +In zone-based policy, you assign interfaces to zones and apply inspection +policy to traffic moving between zones. The firewall acts on traffic +according to 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 the system subjects traffic to policy +restrictions as it crosses to another region of a network. + +Key Points: +- A zone must be configured before you assign an interface to it, and you + can assign an interface to only a single zone. +- All traffic to and from an interface within a zone flows freely. +- Existing policies affect all traffic between zones. +- Traffic cannot flow between a zone member interface and any interface that + is not a zone member. +- You must define 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, you can +create a zone-based firewall to simplify configuration when multiple +interfaces belong to the same security zone. Instead of applying rule-sets +to interfaces, you apply them to source-destination zone pairs. + +You can find a basic introduction to zone-based firewalls in the +[VyOS Knowledge Base](https://support.vyos.io/en/kb/articles/a-primer-to-zone-based-firewall), +and an example at {ref}`examples-zone-policy`. + +The following steps are required to create a zone-based firewall: +1. Define both the source and destination zones +2. Define the rule-set +3. Apply the rule-set to the zones + +### Define a Zone + +To define a zone, set up either one with interfaces or as the local zone. + +```{cfgcmd} set firewall zone \<name\> interface \<interface\> + +Assign interfaces as a member of a zone. + +:::{note} +* An interface can only be a member of one zone. +* You can have multiple interfaces in a zone. Traffic between +interfaces in the same zone follows the intra-zone-filtering +policy (allowed by default). +::: +``` + +```{cfgcmd} set firewall zone \<name\> local-zone + +Define the zone as the local zone for traffic that originates from or is +destined to the router itself. + +:::{note} +* A local zone cannot have any member interfaces +* You cannot have multiple local zones +::: +``` + +```{cfgcmd} set firewall zone \<name\> default-action [drop | reject] + +Modify the zone default-action, which applies to traffic destined to this +zone that does not match any of the source zone rulesets applied. +``` + +```{cfgcmd} set firewall zone \<name\> default-log + +Enable logging of packets that match this zone's default-action (disabled +by default). +``` + +```{cfgcmd} set firewall zone \<name\> description + +Add a meaningful description. +``` + +### Defining a Rule-Set + +Zone-based firewall rule-sets define traffic from a *Source Zone* to a +*Destination Zone*. + +You create rule-sets as a custom firewall chain using the commands below +(refer to the firewall IPv4/IPv6 sections for the full syntax): +- For {ref}`IPv4<configuration/firewall/ipv4:Firewall - IPv4 Rules>`: + `set firewall ipv4 name <name> ...` +- For {ref}`IPv6<configuration/firewall/ipv6:Firewall - IPv6 Rules>`: + `set firewall ipv6 name <name> ...` + +It is helpful to name the rule-sets in the format +`<Source Zone>-<Destination Zone>-<v4 | v6>` to make them easily +identifiable. + +### Applying a Rule-Set to a Zone + +After you define a rule-set, apply it to the source and destination zones. +The configuration syntax anchors to the destination zone, with each of the +source zone rule-sets listed against the destination. + +```{cfgcmd} set firewall zone \<Destination Zone\> from \<Source Zone\> firewall name \<ipv4-rule-set-name\> +``` + +```{cfgcmd} set firewall zone \<Destination Zone\> from \<Source Zone\> firewall ipv6-name \<ipv6-rule-set-name\> +``` + +You should create two rule-sets for each source-destination zone +pair. + +```none +set firewall zone DMZ from LAN firewall name LAN-DMZ-v4 +set firewall zone LAN from DMZ firewall name DMZ-LAN-v4 +``` + +### Applying a Default Rule-Set to a Zone + +When a destination zone shares a common rule-set for multiple source zones, +or when you require a complex set of default policies, you can apply an +optional default rule-set. The default rule-set applies to all zones that do +not have a rule-set configured as defined in +{ref}`IPv4<configuration/firewall/zone:Applying a Rule-Set to a Zone>` + +```{cfgcmd} set firewall zone \<Destination Zone\> default-firewall name \<ipv4-rule-set-name\> +``` + +```{cfgcmd} set firewall zone \<Destination Zone\> default-firewall ipv6-name \<ipv6-rule-set-name\> +``` + +## Operation-mode + +```{opcmd} show firewall zone-policy + +Display a basic summary of the zone configuration. + +:::{code-block} none +vyos@vyos:~$ show firewall zone-policy +Zone Interfaces From Zone Firewall IPv4 Firewall IPv6 +------ ------------ ----------- --------------- --------------- +LAN eth1 WAN WAN-LAN-v4 +eth2 +LOCAL LOCAL LAN LAN-LOCAL-v4 +WAN WAN-LOCAL-v4 WAN-LOCAL-v6 +WAN eth3 LAN LAN-WAN-v4 +eth0 LOCAL LOCAL-WAN-v4 +::: +``` + +```{opcmd} show firewall zone-policy zone \<zone\> + +Display a basic summary of a particular zone. + +:::{code-block} none +vyos@vyos:~$ show firewall zone-policy zone WAN +Zone Interfaces From Zone Firewall IPv4 Firewall IPv6 +------ ------------ ----------- --------------- --------------- +WAN eth3 LAN LAN-WAN-v4 +eth0 LOCAL LOCAL-WAN-v4 +vyos@vyos:~$ show firewall zone-policy zone LOCAL +Zone Interfaces From Zone Firewall IPv4 Firewall IPv6 +------ ------------ ----------- --------------- --------------- +LOCAL LOCAL LAN LAN-LOCAL-v4 +WAN WAN-LOCAL-v4 WAN-LOCAL-v6 +::: +```
\ No newline at end of file diff --git a/docs/configuration/highavailability/index.md b/docs/configuration/highavailability/index.md new file mode 100644 index 00000000..e26f5791 --- /dev/null +++ b/docs/configuration/highavailability/index.md @@ -0,0 +1,561 @@ +--- +lastproofread: '2021-06-30' +--- + +(high-availability)= + +# High availability + +VRRP (Virtual Router Redundancy Protocol) provides active/backup redundancy for +routers. Every VRRP router has a physical IP/IPv6 address, and a virtual +address. On startup, routers elect the master, and the router with the highest +priority becomes the master and assigns the virtual address to its interface. +All routers with lower priorities become backup routers. The master then starts +sending keepalive packets to notify other routers that it's available. If the +master fails and stops sending keepalive packets, the router with the next +highest priority becomes the new master and takes over the virtual address. + +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 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 + +VRRP groups are created with the +`set high-availability vrrp group $GROUP_NAME` commands. The required +parameters are interface, vrid, and address. + +minimal config + +```none +set high-availability vrrp group Foo vrid 10 +set high-availability vrrp group Foo interface eth0 +set high-availability vrrp group Foo address 192.0.2.1/24 +``` + +You can verify your VRRP group status with the operational mode +`run show vrrp` command: + +```none +vyos@vyos# run show vrrp +Name Interface VRID State Last Transition +---------- ----------- ------ ------- ----------------- +Foo eth1 10 MASTER 2s +``` + +## IPv6 support + +The `address` parameter can be either an IPv4 or IPv6 address, but you can +not mix IPv4 and IPv6 in the same group, and will need to create groups with +different VRIDs specially for IPv4 and IPv6. +If you want to use IPv4 + IPv6 address you can use option `excluded-address` + +## Address + +The `address` can be configured either on the VRRP interface or on not VRRP +interface. + +```none +set high-availability vrrp group Foo address 192.0.2.1/24 +set high-availability vrrp group Foo address 203.0.113.22/24 interface eth2 +set high-availability vrrp group Foo address 198.51.100.33/24 interface eth3 +``` + +## Disabling a VRRP group + +You can disable a VRRP group with `disable` option: + +```none +set high-availability vrrp group Foo disable +``` + +A disabled group will be removed from the VRRP process and your router will not +participate in VRRP for that VRID. It will disappear from operational mode +commands output, rather than enter the backup state. + +## Exclude address + +Exclude IP addresses from `VRRP packets`. This option `excluded-address` is +used when you want to set IPv4 + IPv6 addresses on the same virtual interface +or when used more than 20 IP addresses. + +```none +set high-availability vrrp group Foo excluded-address '203.0.113.254/24' +set high-availability vrrp group Foo excluded-address '2001:db8:aa::1/64' +set high-availability vrrp group Foo excluded-address '2001:db8:22::1/64' +``` + +## Setting VRRP group priority + +VRRP priority can be set with `priority` option: + +```none +set high-availability vrrp group Foo priority 200 +``` + +The priority must be an integer number from 1 to 255. Higher priority value +increases router's precedence in the master elections. + +## Sync groups + +A sync group allows VRRP groups to transition together. + +```none +edit high-availability vrrp +set sync-group MAIN member VLAN9 +set sync-group MAIN member VLAN20 +``` + +In the following example, when VLAN9 transitions, VLAN20 will also transition: + +```none +vrrp { + group VLAN9 { + interface eth0.9 + address 10.9.1.1/24 + priority 200 + vrid 9 + } + group VLAN20 { + interface eth0.20 + priority 200 + address 10.20.20.1/24 + vrid 20 + } + sync-group MAIN { + member VLAN20 + member VLAN9 + } +} +``` + +:::{warning} +All items in a sync group should be similarly configured. +If one VRRP group is set to a different preemption delay or priority, +it would result in an endless transition loop. +::: + +## Preemption + +VRRP can use two modes: preemptive and non-preemptive. In the preemptive mode, +if a router with a higher priority fails and then comes back, routers with lower +priority will give up their master status. In non-preemptive mode, the newly +elected master will keep the master status and the virtual address indefinitely. + +By default VRRP uses preemption. You can disable it with the "no-preempt" +option: + +```none +set high-availability vrrp group Foo no-preempt +``` + +You can also configure the time interval for preemption with the "preempt-delay" +option. For example, to set the higher priority router to take over in 180 +seconds, use: + +```none +set high-availability vrrp group Foo preempt-delay 180 +``` + +## Track + +Track option to track non VRRP interface states. VRRP changes status to +`FAULT` if one of the track interfaces in state `down`. + +```none +set high-availability vrrp group Foo track interface eth0 +set high-availability vrrp group Foo track interface eth1 +``` + +Ignore VRRP main interface faults + +```none +set high-availability vrrp group Foo track exclude-vrrp-interface +``` + +## Unicast VRRP + +By default VRRP uses multicast packets. If your network does not support +multicast for whatever reason, you can make VRRP use unicast communication +instead. + +```none +set high-availability vrrp group Foo peer-address 192.0.2.10 +set high-availability vrrp group Foo hello-source-address 192.0.2.15 +``` + +## rfc3768-compatibility + +RFC 3768 defines a virtual MAC address to each VRRP virtual router. +This virtual router MAC address will be used as the source in all periodic VRRP +messages sent by the active node. When the rfc3768-compatibility option is set, +a new VRRP interface is created, to which the MAC address and the virtual IP +address is automatically assigned. + +```none +set high-availability vrrp group Foo rfc3768-compatibility +``` + +Verification + +```none +$show interfaces ethernet eth0v10 +eth0v10@eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue +state UP group default qlen 1000 +link/ether 00:00:5e:00:01:0a brd ff:ff:ff:ff:ff:ff +inet 172.25.0.247/16 scope global eth0v10 +valid_lft forever preferred_lft forever +``` + +:::{warning} +RFC 3768 creates a virtual interface. If you want to apply +the destination NAT rule to the traffic sent to the virtual MAC, set +the created virtual interface as `inbound-interface`. +::: + +## Global options + +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. + +```{eval-rst} +.. 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. + +```{eval-rst} +.. cfgcmd:: set high-availability vrrp global-parameters garp interval + <0.000-1000> +``` + +```{eval-rst} +.. 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. +``` + +% stop_vyoslinter + +```{eval-rst} +.. cfgcmd:: set high-availability vrrp global-parameters garp master-delay <1-255> +``` + +% start_vyoslinter + +```{eval-rst} +.. 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. +``` + +```{eval-rst} +.. cfgcmd:: set high-availability vrrp global-parameters garp master-refresh + <1-600> +``` + +```{eval-rst} +.. 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. +``` + +```{eval-rst} +.. cfgcmd:: set high-availability vrrp global-parameters garp + master-refresh-repeat <1-600> +``` + +```{eval-rst} +.. 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. +``` + +```{eval-rst} +.. cfgcmd:: set high-availability vrrp global-parameters garp master-repeat + <1-600> +``` + +```{eval-rst} +.. 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. +``` + +## Version + +```{eval-rst} +.. cfgcmd:: set high-availability vrrp global-parameters version 2|3 + + Set the default VRRP version to use. This defaults to 2, but IPv6 instances + will always use version 3. +``` + +## Scripting + +VRRP functionality can be extended with scripts. VyOS supports two kinds of +scripts: health check scripts and transition scripts. Health check scripts +execute custom checks in addition to the master router reachability. Transition +scripts are executed when VRRP state changes from master to backup or fault and +vice versa and can be used to enable or disable certain services, for example. + +:::{note} +Simply placing script files in `/config/scripts/` does not mean the +system can execute them. To make custom scripts executable, grant them +**execute permissions**. Use the following command: + +```none +chmod +x /config/scripts/script-name.sh +``` +::: + +:::{warning} +It is not recommended to change VRRP configuration +inside health-check and transition scripts. +::: + +### Health check scripts + +There is the ability to run an arbitrary script at regular intervals +according to health-check parameters. If a script returns 0, it +indicates success. If a script returns anything else, it will indicate +that the VRRP instance should enter the FAULT state. + +This setup will make the VRRP process execute the +`/config/scripts/vrrp-check.sh script` every 60 seconds, and transition the +group to the fault state if it fails (i.e. exits with non-zero status) three +times: + +% stop_vyoslinter + +```none +set high-availability vrrp group Foo health-check script /config/scripts/vrrp-check.sh +set high-availability vrrp group Foo health-check interval 60 +set high-availability vrrp group Foo health-check failure-count 3 +``` + +% start_vyoslinter + +An optional `timeout` can be set to define the maximum number of seconds the +script is allowed to run. This is useful for scripts that may hang or take +longer than expected — setting the timeout higher than the interval allows +longer-running scripts to complete before being considered failed. + +% stop_vyoslinter + +```none +set high-availability vrrp group Foo health-check script /config/scripts/vrrp-check.sh +set high-availability vrrp group Foo health-check interval 20 +set high-availability vrrp group Foo health-check failure-count 3 +set high-availability vrrp group Foo health-check timeout 40 +``` + +% start_vyoslinter + +When the vrrp group is a member of the sync group will use only +the sync group health check script. +This example shows how to configure it for the sync group: + +% stop_vyoslinter + +```none +set high-availability vrrp sync-group Bar health-check script /config/scripts/vrrp-check.sh +set high-availability vrrp sync-group Bar health-check interval 60 +set high-availability vrrp sync-group Bar health-check failure-count 3 +``` + +% start_vyoslinter + +### Transition scripts + +Transition scripts can help you implement various fixups, such as starting and +stopping services, or even modifying the VyOS config on VRRP transition. +This setup will make the VRRP process execute the +`/config/scripts/vrrp-fail.sh` with argument `Foo` when VRRP fails, +and the `/config/scripts/vrrp-master.sh` when the router becomes the master: + +% stop_vyoslinter + +```none +set high-availability vrrp group Foo transition-script backup "/config/scripts/vrrp-fail.sh Foo" +set high-availability vrrp group Foo transition-script fault "/config/scripts/vrrp-fail.sh Foo" +set high-availability vrrp group Foo transition-script master "/config/scripts/vrrp-master.sh Foo" +``` + +% start_vyoslinter + +To know more about scripting, check the {ref}`command-scripting` section. + +## Virtual-server + +```{eval-rst} +.. include:: /_include/need_improvement.txt +``` + +Virtual Server allows to Load-balance traffic destination virtual-address:port +between several real servers. + +### Algorithm + +Load-balancing schedule algorithm: + +- round-robin +- weighted-round-robin +- least-connection +- weighted-least-connection +- source-hashing +- destination-hashing +- locality-based-least-connection + +```none +set high-availability virtual-server 203.0.113.1 algorithm 'least-connection' +``` + +### Forward method + +- NAT +- direct +- tunnel + +```none +set high-availability virtual-server 203.0.113.1 forward-method 'nat' +``` + +### Health-check + +Custom health-check script allows checking real-server availability + +% stop_vyoslinter + +```none +set high-availability virtual-server 203.0.113.1 real-server 192.0.2.11 health-check script <path-to-script> +``` + +% start_vyoslinter + +### Fwmark + +Firewall mark. It possible to loadbalancing traffic based on `fwmark` value + +```none +set high-availability virtual-server 203.0.113.1 fwmark '111' +``` + +### Real server + +Real server IP address and port + +% stop_vyoslinter + +```none +set high-availability virtual-server 203.0.113.1 real-server 192.0.2.11 port '80' +``` + +% start_vyoslinter + +### Example + +Virtual-server can be configured with VRRP virtual address or without VRRP. + +In the next example all traffic destined to `203.0.113.1` and port `8280` +protocol TCP is balanced between 2 real servers `192.0.2.11` and +`192.0.2.12` to port `80` + +Real server is auto-excluded if port check with this server fail. + +% stop_vyoslinter + +```none +set interfaces ethernet eth0 address '203.0.113.11/24' +set interfaces ethernet eth1 address '192.0.2.1/24' +set high-availability vrrp group FOO interface 'eth0' +set high-availability vrrp group FOO no-preempt +set high-availability vrrp group FOO priority '150' +set high-availability vrrp group FOO address '203.0.113.1/24' +set high-availability vrrp group FOO vrid '10' + +set high-availability virtual-server 203.0.113.1 algorithm 'source-hashing' +set high-availability virtual-server 203.0.113.1 delay-loop '10' +set high-availability virtual-server 203.0.113.1 forward-method 'nat' +set high-availability virtual-server 203.0.113.1 persistence-timeout '180' +set high-availability virtual-server 203.0.113.1 port '8280' +set high-availability virtual-server 203.0.113.1 protocol 'tcp' +set high-availability virtual-server 203.0.113.1 real-server 192.0.2.11 port '80' +set high-availability virtual-server 203.0.113.1 real-server 192.0.2.12 port '80' +``` + +% start_vyoslinter + +A firewall mark `fwmark` allows using multiple ports for high-availability +virtual-server. +It uses fwmark value. + +In this example all traffic destined to ports "80, 2222, 8888" protocol TCP +marks to fwmark "111" and balanced between 2 real servers. +Port "0" is required if multiple ports are used. + +% stop_vyoslinter + +```none +set interfaces ethernet eth0 address 'dhcp' +set interfaces ethernet eth0 description 'WAN' +set interfaces ethernet eth1 address '192.0.2.1/24' +set interfaces ethernet eth1 description 'LAN' + +set policy route PR interface 'eth0' +set policy route PR rule 10 destination port '80,2222,8888' +set policy route PR rule 10 protocol 'tcp' +set policy route PR rule 10 set mark '111' + +set high-availability virtual-server vyos fwmark '111' +set high-availability virtual-server vyos protocol 'tcp' +set high-availability virtual-server vyos real-server 192.0.2.11 health-check script '/config/scripts/check-real-server-first.sh' +set high-availability virtual-server vyos real-server 192.0.2.11 port '0' +set high-availability virtual-server vyos real-server 192.0.2.12 health-check script '/config/scripts/check-real-server-second.sh' +set high-availability virtual-server vyos real-server 192.0.2.12 port '0' + +set nat source rule 100 outbound-interface name 'eth0' +set nat source rule 100 source address '192.0.2.0/24' +set nat source rule 100 translation address 'masquerade' +``` + +% start_vyoslinter + +Op-mode check virtual-server status + +```none +vyos@r14:~$ run show virtual-server +IP Virtual Server version 1.2.1 (size=4096) +Prot LocalAddress:Port Scheduler Flags + -> RemoteAddress:Port Forward Weight ActiveConn InActConn +FWM 111 lc persistent 300 + -> 192.0.2.11:0 Masq 1 0 0 + -> 192.0.2.12:0 Masq 1 1 0 +``` + diff --git a/docs/configuration/highavailability/index.rst b/docs/configuration/highavailability/rst-index.rst index 952a345b..952a345b 100644 --- a/docs/configuration/highavailability/index.rst +++ b/docs/configuration/highavailability/rst-index.rst diff --git a/docs/configuration/index.md b/docs/configuration/index.md new file mode 100644 index 00000000..3e215502 --- /dev/null +++ b/docs/configuration/index.md @@ -0,0 +1,23 @@ +# Configuration Guide + +The following structure represents the CLI structure. + +```{toctree} +:includehidden: true +:maxdepth: 1 + +container/index +firewall/index +highavailability/index +interfaces/index +loadbalancing/index +nat/index +policy/index +pki/index +protocols/index +service/index +system/index +trafficpolicy/index +vpn/index +vrf/index +``` diff --git a/docs/configuration/interfaces/bonding.md b/docs/configuration/interfaces/bonding.md new file mode 100644 index 00000000..7a07a27c --- /dev/null +++ b/docs/configuration/interfaces/bonding.md @@ -0,0 +1,764 @@ +--- +lastproofread: '2025-12-09' +--- + +(bond-interface)= + +# Bond / link aggregation + +A **bonding interface** aggregates multiple network interfaces into a single +logical interface (referred to as a bond, {abbr}`LAG (Link Aggregation Group)`, +EtherChannel, or port-channel). + +The behavior of a bonding interface depends on the selected mode. Modes provide +either fault tolerance or a combination of load balancing and fault tolerance. +Additionally, the bonding interface can be configured for link integrity +monitoring. + +## Configuration + +### Common interface configuration + +```{cmdincludemd} /_include/interface-common-with-dhcp.txt +:var0: bonding +:var1: bond0 +``` + +### Member interfaces + +```{cfgcmd} set interfaces bonding \<interface\> member interface \<member\> + +**Add an interface to the bonding group.** + +**Example:** + +To configure eth0 and eth1 as members of the bonding interface bond0, execute +the following commands: +``` + +```none +set interfaces bonding bond0 member interface eth0 +set interfaces bonding bond0 member interface eth1 +``` + +### Bond modes + +````{cfgcmd} set interfaces bonding \<interface\> mode \<802.3ad | active-backup | broadcast | round-robin | transmit-load-balance | adaptive-load-balance | xor-hash\> + +```{eval-rst} +**Configure the bonding mode on the interface. The default mode is** +``802.3ad``. + +The available modes are: + +* ``802.3ad`` + +.. list-table:: + :widths: 20 80 + + * - **Description:** + - IEEE 802.3ad Dynamic Link Aggregation. Groups only member + interfaces with the same speed (e.g., 1 Gbps) and duplex + settings. Member interfaces with different speed and duplex + settings are not included in the active bond. + + Provides load balancing and fault tolerance. Uses the + :abbr:`LACP (Link Aggregation Control Protocol)` to + negotiate the bond with the switch. + * - **Traffic distribution:** + - Traffic is distributed according to the **transmit hash + policy** (default: XOR). + + The bonding driver applies an XOR operation to specific + packet header fields, generating a hash value that maps to + a particular member interface. This ensures the same network + flow is consistently transmitted over the same member + interface. + + The transmit hash policy is configured via the ``hash-policy`` option. + * - **Failover:** + - If a member interface fails, the hash is recalculated to distribute + traffic among the remaining active member interfaces. + +.. note:: Not all transmit hash policies comply with 802.3ad, particularly + section 43.2.4. Using a non-compliant policy may result in out-of-order + packet delivery. + +* ``active-backup`` + +.. list-table:: + :widths: 20 80 + + * - **Description:** + - Provides fault tolerance. Only one member interface is active + at a time. Other member interfaces remain in a standby mode. + * - **Traffic distribution:** + - All traffic (incoming and outgoing) is routed via one active + member interface. + * - **Failover:** + - If the designated member interface fails, all traffic is + routed to another member interface. The bonding driver sends + a Gratuitous ARP to update the peer's MAC address table, + linking the bond's MAC address to another physical port. + +* ``broadcast`` + +.. list-table:: + :widths: 20 80 + + * - **Description:** + - Provides maximum fault tolerance by duplicating traffic. + * - **Traffic distribution:** + - Every packet is duplicated and transmitted on **all** member + interfaces. + * - **Failover:** + - Traffic flow is not interrupted as long as at least one + member interface remains active. + +* ``round-robin`` + +.. list-table:: + :widths: 20 80 + + * - **Description:** + - Provides load balancing and fault tolerance. + * - **Traffic distribution:** + - Packets are transmitted in sequential order across the member + interfaces (e.g., packet 1 > interface A, packet 2 > + interface B, etc.). + * - **Failover:** + - If a member interface fails, the sequence skips the failed + interface and continues with the remaining active members. + +* ``transmit-load-balance`` + +.. list-table:: + :widths: 20 80 + + * - **Description:** + - Provides adaptive transmit load balancing and fault tolerance. + * - **Traffic distribution:** + - **Outgoing:** Distributed across all active member interfaces + based on the current load. + + **Incoming:** Received by a designated member interface + (active receiver). + * - **Failover:** + - If the active receiver fails, another member interface takes + over as the new active receiver. + +* ``adaptive-load-balance`` + +.. list-table:: + :widths: 20 80 + + * - **Description:** + - Provides adaptive transmit load balancing identical to + ``transmit-load-balance``, receive load balancing for IPv4 + traffic, and fault tolerance for both incoming and outgoing + traffic. + * - **Traffic distribution:** + - **Outgoing:** Identical to ``transmit-load-balance``. + + **Incoming:** Distributed based on ARP manipulation. For + both local and remote connections, the bonding driver + intercepts ARP traffic and changes the source MAC address + to the MAC address of the least loaded member interface. + + All traffic from that peer is then routed to the chosen + member interface. + * - **Failover:** + - If a member interface's state changes (fails, recovers, is + added, or excluded), the traffic is redistributed among all + active member interfaces. + +* ``xor-hash``: Provides load balancing and fault tolerance + based on a hash formula. Distributes traffic and handles + failover identically to ``802.3ad``, but operates without + the :abbr:`LACP (Link Aggregation Control Protocol)`. +``` + +```` + +```{cfgcmd} set interfaces bonding \<interface\> min-links \<0-16\> + +**Configure how many member interfaces must be active (in the +link-up state) to mark the bonding interface UP (carrier +asserted).** + +This command applies only when the bonding interface is configured +in 802.3ad mode and functions like the Cisco EtherChannel min-links +feature. It ensures that a bonding interface is marked UP (carrier +asserted) only when a specified number of member interfaces are +active (in the link-up state). This helps guarantee a minimum level +of bandwidth for higher-level services (such as clustering) relying +on the bonding interface. + +The default value is 0. This marks the bonding interface UP +(carrier asserted) whenever an active LACP aggregator exists, +regardless of the number of member interfaces in that aggregator. + +:::{note} +In 802.3ad mode, a bond cannot be active without at least one active +member interface. Therefore, setting min-links to 0 or 1 has the same result: +the bonding interface is marked UP (carrier asserted). +::: +``` + +```{cfgcmd} set interfaces bonding \<interface\> lacp-rate \<slow|fast\> + +**Configure the rate at which the bonding interface requests its link +partner to send** {abbr}`LACPDUs (Link Aggregation Control Protocol Data +Units)` **in 802.3ad mode.** + +This command applies only when the bonding interface is configured in +802.3ad mode. + +The following options are available: + +* **slow (default):** Requests the link partner to transmit LACPDUs every 30 seconds. + +* **fast:** Requests the link partner to transmit LACPDUs every 1 second. +``` +```{cfgcmd} set interfaces bonding \<interface\> system-mac \<mac address\> + +**Configure a specific MAC address for the bonding interface.** + +This sets the 802.3ad system MAC address, which is used for {abbr}`LACPDU (Link +Aggregation Control Protocol Data Unit)` exchanges with the link partner. +You can assign a fixed MAC address or generate a random one for these +{abbr}`LACPDU (Link Aggregation Control Protocol Data Unit)` exchanges. +``` +```{cfgcmd} set interfaces bonding \<interface\> hash-policy \<policy\> + +**Configure which transmit hash policy to use for distributing traffic across +member interfaces.** + +The following policies are available: + +* ``layer2`` + +**Description:** Routes all traffic destined for a specific network peer through +the same member interface. The policy is 802.3ad-compliant. + +**Hash inputs:** Source MAC address, destination MAC address, and Ethernet packet +type ID. + +**Formula:** + +:::{code-block} none +hash = source MAC address XOR destination MAC address XOR packet type ID +member interface number = hash modulo member interface count +::: + +* ``layer2+3`` + +**Description:** Similar to ``layer2``, routes all traffic destined for a specific +network peer through the same member interface and is IEEE 802.3ad-compliant. Uses +both Layer 2 and Layer 3 information to provide a more balanced traffic distribution. + +**Hash inputs:** +* Source MAC address, destination MAC address, and Ethernet packet type ID. +* Source IP address, destination IP address. IPv6 addresses are first hashed + using ``IPv6_addr_hash``. + +**Formula:** + +:::{code-block} none +hash = source MAC address XOR destination MAC address XOR packet type ID +hash = hash XOR source IP address XOR destination IP address +hash = hash XOR (hash RSHIFT 16) +hash = hash XOR (hash RSHIFT 8) +member interface number = hash modulo member interface count +::: + +For non-IP traffic, the formula is the same as for ``layer2``. + +* ``layer3+4`` + +**Description:** Routes different connections (flows) destined for a specific +network peer through multiple member interfaces, but ensures each individual +flow is routed through only one member interface. + +:::{note} +This policy is not fully 802.3ad-compliant. When a single TCP or UDP flow +contains both fragmented and unfragmented packets, the algorithm may distribute +them across different member interfaces. This may result in out-of-order packet +delivery, violating the 802.3ad standard. +::: + +**Hash inputs:** +* Source port, destination port (if available). +* Source IP address, destination IP address. IPv6 addresses are first hashed + using ``IPv6_addr_hash``. + +**Formula:** + +:::{code-block} none +hash = source port, destination port (as in the header) +hash = hash XOR source IP address XOR destination IP address +hash = hash XOR (hash RSHIFT 16) +hash = hash XOR (hash RSHIFT 8) +member interface number = hash modulo member interface count +::: + +For fragmented TCP or UDP packets and all other IPv4 and IPv6 traffic, the +source and destination port information is omitted. + +For non-IP traffic, the formula is the same as for ``layer2``. +``` + + +```{cfgcmd} set interfaces bonding \<interface\> primary \<interface\> + +**Configure the primary member interface in the bond.** + +The primary member interface remains active as long as it is operational; +alternative member interfaces are used only if it fails. + +Use this configuration when a specific member interface is preferred, +such as one with higher throughput. + +This command applies only to ``active-backup``, ``transmit-load-balance``, and +``adaptive-load-balance`` modes. +``` + + +```{cfgcmd} set interfaces bonding \<interface\> arp-monitor interval \<time\> + +**Configure the ARP monitoring interval, in seconds, for the bonding interface.** + +ARP monitoring periodically assesses the health of each member interface by +checking whether it has recently sent or received traffic (this criterion +varies depending on the bonding mode and the member interface’s state). ARP +probes are sent to the IP addresses specified with the arp-monitor target option. + +When ARP monitoring is used with EtherChannel-compatible modes (such as +``round-robin`` or ``xor-hash``), the switch should be configured to distribute +traffic across all member interfaces. If the switch distributes traffic using +an XOR-based policy, all ARP replies will be received on one member interface, +causing other member interfaces to be incorrectly marked as failed. + +Setting this value to 0 disables ARP monitoring. + +The default value is 0. +``` + + +```{cfgcmd} set interfaces bonding \<interface\> arp-monitor target \<address\> + +**Configure the IP addresses for ARP monitoring requests.** + +The bonding driver sends ARP requests to these IP addresses to check the +state of member interfaces. + +To enable ARP monitoring, configure at least one IP address (up to 16 per +bonding interface). + +By default, no IP addresses are configured. +``` + +### {abbr}`VLAN (Virtual Local Area Network)` + +```{cmdincludemd} /_include/interface-vlan-8021q.txt +:var0: bonding +:var1: bond0 +``` + +### SPAN port mirroring + +```{cmdincludemd} ../../_include/interface-mirror.txt +:var0: bonding +:var1: bond1 +:var2: eth3 +``` + +#### EVPN multihoming + + +EVPN multihoming (EVPN-MH) is a standards-based solution (RFC 7432, RFC 8365) +that enables Customer Edge (CE) devices, such as servers, to connect to two +or more Provider Edge (PE) devices for redundancy and load balancing. + + +EVPN-MH is often used as a modern, standards-based alternative to +{abbr}`MLAG (Multi-Chassis Link Aggregation)` and {abbr}`VTEPs (Virtual +Tunnel Endpoints)`. + + +**Ethernet Segment (ES) and Ethernet Segment Identifier (ESI)** + + +Physical links that connect a CE device to PE devices are bundled using link +aggregation. This logical bundle is called an Ethernet Segment (ES) and is +uniquely identified by an Ethernet Segment Identifier (ESI) within the +EVPN domain. + + +To enable EVPN-MH, configure the same ESI on the bonding interfaces of all +PE devices connected to a single CE device. + + +An ESI is configured by specifying either a system MAC address and a local +discriminator, or an Ethernet Segment Identifier Name (ESINAME). + + +The following two commands generate a 10-byte Type-3 ESI by combining the +system MAC and local discriminator: + +```{cfgcmd} set interfaces bonding \<interface\> evpn es-id \<1-16777215|10-byte ID\> + +``` +```{cfgcmd} set interfaces bonding \<interface\> evpn es-sys-mac \<xx:xx:xx:xx:xx:xx\> + +Alternatively, assign an ESINAME directly as a 10-byte Type-0 ESI using the +following format: 00:AA:BB:CC:DD:EE:FF:GG:HH:II. + +**BGP-EVPN route usage** + +EVPN-MH uses BGP-EVPN route types 1 and 2 for ES discovery and MAC-IP +synchronization: + +* **Type 1 (EAD-per-ES and EAD-per-EVI)** routes advertise the locally +attached ESs and discover remote ESs in the network. +* **Type 2 (MAC-IP advertisement)** routes are advertised with a +destination ESI, enabling MAC-IP synchronization between ES peers. +``` + +```{cfgcmd} set interfaces bonding \<interface\> evpn es-df-pref \<1-65535\> + +**Configure the** {abbr}`DF (Designated Forwarder)` **preference (1-65535) for +the interface. A higher value indicates a higher preference to become the** +{abbr}`DF (Designated Forwarder)`. **The** {abbr}`DF (Designated Forwarder)` +**preference is configured per-ES.** + +The DF election process determines which interface in a specific ES forwards +{abbr}`BUM (Broadcast, Unknown Unicast, and Multicast)` traffic from the EVPN +overlay to the connected CE device. EVPN Type-4 (Ethernet Segment) routes are +used to elect the DF, implementing the preference-based election method defined +in RFC 9785. + +Interfaces not elected as the DF drop any BUM traffic from the EVPN overlay +using non-DF filters. Similarly, traffic received from ES peers via the EVPN +overlay is blocked from forwarding to the CE device to maintain split-horizon +filtering with local bias. +``` + +```{cmdincludemd} /_include/interface-evpn-uplink.txt +:var0: bonding +:var1: bond0 +``` + +## Example + + +The following configuration example applies to all listed third-party vendors. +It creates a bonding interface with two member interfaces, defines VLANs 10 +and 100 on the bonding interface, and assigns an IPv4 address to each VLAN +subinterface. + +```none +# Create the bonding interface bond0 with 802.3ad LACP +set interfaces bonding bond0 hash-policy 'layer2' +set interfaces bonding bond0 mode '802.3ad' + +# Add the required VLANs and IPv4 addresses on them +set interfaces bonding bond0 vif 10 address 192.168.0.1/24 +set interfaces bonding bond0 vif 100 address 10.10.10.1/24 + +# Add the member interfaces to the bonding interface +set interfaces bonding bond0 member interface eth1 +set interfaces bonding bond0 member interface eth2 +``` +:::{note} +If you are running this configuration in a virtual environment like +EVE-NG, ensure the e1000 driver is chosen for your VyOS NIC. The default +drivers, such as ``virtio-net-pci`` or ``vmxnet3``, are incompatible with +this configuration. Specifically, ICMP messages will not be processed +correctly. + +To check your NIC driver, use the following command: +``show interfaces ethernet eth0 physical | grep -i driver`` +::: + + +### Cisco Catalyst configuration + + +Configure a Cisco Catalyst switch to integrate with a two-member VyOS bonding +interface. + + +Assign member interfaces to PortChannel: + +```none +interface GigabitEthernet1/0/23 + description VyOS eth1 + channel-group 1 mode active +! +interface GigabitEthernet1/0/24 + description VyOS eth2 + channel-group 1 mode active +! +``` + +A new interface, `Port-channel1`, becomes available; all configuration, +such as allowed VLAN interfaces and STP, is applied here. + +```none +interface Port-channel1 + description LACP Channel for VyOS + switchport trunk encapsulation dot1q + switchport trunk allowed vlan 10,100 + switchport mode trunk + spanning-tree portfast trunk +! +``` + +### Juniper EX Switch configuration + + +Configure a Juniper EX Series switch to integrate with a two-member VyOS bonding +interface. + +```none +# Create aggregated ethernet device with 802.3ad LACP and port speeds of 10gbit/s +set interfaces ae0 aggregated-ether-options link-speed 10g +set interfaces ae0 aggregated-ether-options lacp active + +# Create layer 2 on the aggregated ethernet device with trunking for our VLANs +set interfaces ae0 unit 0 family ethernet-switching port-mode trunk + +# Add the required vlans to the device +set interfaces ae0 unit 0 family ethernet-switching vlan members 10 +set interfaces ae0 unit 0 family ethernet-switching vlan members 100 + +# Add the two interfaces to the aggregated ethernet device, in this setup both +# ports are on the same switch (switch 0, module 1, port 0 and 1) +set interfaces xe-0/1/0 ether-options 802.3ad ae0 +set interfaces xe-0/1/1 ether-options 802.3ad ae0 + +# But this can also be done with multiple switches in a stack, a virtual +# chassis on Juniper (switch 0 and switch 1, module 1, port 0 on both switches) +set interfaces xe-0/1/0 ether-options 802.3ad ae0 +set interfaces xe-1/1/0 ether-options 802.3ad ae0 +``` + +### Aruba/HP configuration + + +Configure an Aruba/HP 2510G switch to integrate with a two-member VyOS bonding +interface. + +```none +# Create trunk with 2 member interfaces (interface 1 and 2) and LACP +trunk 1-2 Trk1 LACP + +# Add the required VLANs to the trunk +vlan 10 tagged Trk1 +vlan 100 tagged Trk1 +``` + +### Arista EOS configuration + + +When deploying VyOS in environments with Arista switches, use the following +blueprint as an initial setup to configure an operational LACP port-channel +between the two devices. + + +Let's assume the following topology: + + +```{eval-rst} +.. figure:: /_static/images/vyos_arista_bond_lacp.webp + :alt: VyOS Arista EOS setup +``` + + +**R1** + +```none +interfaces { + bonding bond10 { + hash-policy layer3+4 + member { + interface eth1 + interface eth2 + } + mode 802.3ad + vif 100 { + address 192.0.2.1/30 + address 2001:db8::1/64 + } + } +``` +**R2** + + + +```none +interfaces { + bonding bond10 { + hash-policy layer3+4 + member { + interface eth1 + interface eth2 + } + mode 802.3ad + vif 100 { + address 192.0.2.2/30 + address 2001:db8::2/64 + } + } +``` +**SW1** + +```none +! +vlan 100 + name FOO +! +interface Port-Channel10 + switchport trunk allowed vlan 100 + switchport mode trunk + spanning-tree portfast +! +interface Port-Channel20 + switchport mode trunk + no spanning-tree portfast auto + spanning-tree portfast network +! +interface Ethernet1 + channel-group 10 mode active +! +interface Ethernet2 + channel-group 10 mode active +! +interface Ethernet3 + channel-group 20 mode active +! +interface Ethernet4 + channel-group 20 mode active +! +``` +**SW2** + + + +```none +! +vlan 100 + name FOO +! +interface Port-Channel10 + switchport trunk allowed vlan 100 + switchport mode trunk + spanning-tree portfast +! +interface Port-Channel20 + switchport mode trunk + no spanning-tree portfast auto + spanning-tree portfast network +! +interface Ethernet1 + channel-group 10 mode active +! +interface Ethernet2 + channel-group 10 mode active +! +interface Ethernet3 + channel-group 20 mode active +! +interface Ethernet4 + channel-group 20 mode active +! +``` +:::{note} +When testing this environment in EVE-NG, ensure the e1000 driver +is chosen for your VyOS network interfaces. If the default virtio driver +is used, VyOS will not transmit LACP PDUs, preventing the port-channel +from ever becoming active. +::: + + +(operation)= + +## Operation + +```{opcmd} show interfaces bonding + +Show brief interface information. + + +:::{code-block} none +vyos@vyos:~$ show interfaces bonding +Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down +Interface IP Address S/L Description +--------- ---------- --- ----------- +bond0 - u/u my-sw1 int 23 and 24 +bond0.10 192.168.0.1/24 u/u office-net +bond0.100 10.10.10.1/24 u/u management-net +::: +``` +```{opcmd} show interfaces bonding \<interface\> + +Show detailed interface information. + +:::{code-block} none +vyos@vyos:~$ show interfaces bonding bond5 +bond5: <NO-CARRIER,BROADCAST,MULTICAST,MASTER,UP> mtu 1500 qdisc noqueue state DOWN group default qlen 1000 + link/ether 00:50:56:bf:ef:aa brd ff:ff:ff:ff:ff:ff + inet6 fe80::e862:26ff:fe72:2dac/64 scope link tentative + 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 + 0 0 0 0 0 0 +::: +``` +```{opcmd} show interfaces bonding \<interface\> detail + +Show detailed information about the underlying physical links on the given +bonding interface. + +:::{code-block} none +vyos@vyos:~$ show interfaces bonding bond5 detail +Ethernet Channel Bonding Driver: v3.7.1 (April 27, 2011) +Bonding Mode: IEEE 802.3ad Dynamic link aggregation +Transmit Hash Policy: layer2 (0) +MII Status: down +MII Polling Interval (ms): 100 +Up Delay (ms): 0 +Down Delay (ms): 0 +802.3ad info +LACP rate: slow +Min links: 0 +Aggregator selection policy (ad_select): stable +Slave Interface: eth1 +MII Status: down +Speed: Unknown +Duplex: Unknown +Link Failure Count: 0 +Permanent HW addr: 00:50:56:bf:ef:aa +Slave queue ID: 0 +Aggregator ID: 1 +Actor Churn State: churned +Partner Churn State: churned +Actor Churned Count: 1 +Partner Churned Count: 1 +Slave Interface: eth2 +MII Status: down +Speed: Unknown +Duplex: Unknown +Link Failure Count: 0 +Permanent HW addr: 00:50:56:bf:19:26 +Slave queue ID: 0 +Aggregator ID: 2 +Actor Churn State: churned +Partner Churn State: churned +Actor Churned Count: 1 +Partner Churned Count: 1 +::: +```
\ No newline at end of file diff --git a/docs/configuration/interfaces/bridge.md b/docs/configuration/interfaces/bridge.md new file mode 100644 index 00000000..77775767 --- /dev/null +++ b/docs/configuration/interfaces/bridge.md @@ -0,0 +1,431 @@ +--- +lastproofread: '2025-12-22' +--- + +(bridge-interface)= + +# Bridge + +VyOS bridges connect Ethernet segments by grouping multiple interfaces into a +single bridge interface, which acts as a virtual software switch. Unlike +routers, which forward traffic based on Layer 3 IP addresses, bridges operate +at Layer 2 and forward traffic based on MAC addresses. Operating at Layer 2, +bridges are protocol-agnostic and transparently forward all Ethernet- +encapsulated traffic, whether it is IPv4, IPv6, or specialized industrial +protocols. + +This implementation utilizes the Linux bridge subsystem to support a subset of +the ANSI/IEEE 802.1d standard for transparent bridging and MAC address learning. + +:::{note} +{abbr}`STP (Spanning Tree Protocol)` is disabled by default in VyOS +and must be explicitly enabled if required. See {ref}`stp` for details. +::: + +## Configuration + +### Common interface configuration + +```{cmdincludemd} /_include/interface-common-with-dhcp.txt +:var0: bridge +:var1: br0 +``` + + +### Member interfaces + +```{cfgcmd} set interfaces bridge \<interface\> member interface \<member\> + +**Configure an interface as a bridge member.** + +Valid interface types are: {ref}`ethernet-interface`, {ref}`bond-interface`, +{ref}`l2tpv3-interface`, {ref}`openvpn`, {ref}`vxlan-interface`, +{ref}`wireless-interface`, {ref}`tunnel-interface`, and +{ref}`geneve-interface`. + +Use tab completion to list interfaces that can be bridged. +``` + +```{cfgcmd} set interfaces bridge \<interface\> member interface \<member\> priority \<priority\> + +**Configure the** {abbr}`STP (Spanning Tree Protocol)` **port priority +for a specific member interface within a bridge.** + +Within the {abbr}`STP (Spanning Tree Protocol)` topology, each member interface +in a bridge operates as a port with an assigned **priority** and **path cost**. +{abbr}`STP (Spanning Tree Protocol)` uses these values to determine the +**lowest-cost path** to the root bridge, maintaining a loop-free topology. +Traffic flows through the path with the lowest path cost, while alternate +paths remain in standby. + +A **lower** priority value means **higher** precedence in path selection. + +{abbr}`STP (Spanning Tree Protocol)` considers the port priority only if +multiple member interfaces have the same path costs. +``` + +```{cfgcmd} set interfaces bridge \<interface\> member interface \<member\> cost \<cost\> + +**Configure the** {abbr}`STP (Spanning Tree Protocol)` **path cost for a +specific member interface within the bridge.** + +Path cost is the primary metric {abbr}`STP (Spanning Tree Protocol)` uses to +determine the path to the root bridge. This value is based on interface +bandwidth; faster interfaces receive lower costs. + +By assigning a lower cost, you give the interface higher precedence during +path selection. +``` + +```{cfgcmd} set interfaces bridge \<interface\> member interface \<member\> disable-learning + +**Disable MAC address learning for a specific member interface +within a bridge.** + +When learning is disabled, the bridge will not add source MAC addresses +observed on this port to its forwarding database (FDB). Frames destined +to MACs not present in the FDB are then flooded to all bridge ports +rather than unicast-forwarded. +``` + + +### Bridge options + +Configure how bridge interfaces maintain their {abbr}`FDB (Forwarding Database)` +, react to topology changes, and optimize multicast data streams. + +```{cfgcmd} set interfaces bridge \<interface\> aging \<time\> + +**Configure the MAC address aging time for the bridge.** + +The duration in seconds that a MAC address remains in the bridge’s {abbr}`FDB +(Forwarding Database)` before removal if no traffic is received from that +address. + +The default value is 300 seconds. +``` + +```{cfgcmd} set interfaces bridge \<interface\> max-age \<time\> + +**Configure the** {abbr}`STP (Spanning Tree Protocol)` **max age timer for +the bridge.** + +The duration in seconds that the bridge waits for a {abbr}`BPDU (Bridge +Protocol Data Unit)` from the root bridge. + +If the bridge does not receive a {abbr}`BPDU (Bridge Protocol Data Unit)` +within this period, it recalculates the path to the root bridge or initiates +a new root bridge election. +``` + +```{cfgcmd} set interfaces bridge \<interface\> igmp querier + +**Configure the bridge interface to act as the** {abbr}`IGMP (Internet Group +Management Protocol)`/{abbr}`MLD (Multicast Listener Discovery)` **Querier.** + +**When configured:** The bridge interface sends {abbr}`IGMP (Internet Group +Management Protocol)` (IPv4) and {abbr}`MLD (Multicast Listener Discovery)` +(IPv6) general queries to all connected hosts to identify active multicast +listeners. +``` + +```{cfgcmd} set interfaces bridge \<interface\> igmp snooping + +**Configure the bridge interface to perform** {abbr}`IGMP (Internet Group +Management Protocol)`/{abbr}`MLD (Multicast Listener Discovery)` +**snooping.** + +**When configured:** The bridge interface monitors {abbr}`IGMP (Internet Group +Management Protocol)` (IPv4) and {abbr}`MLD (Multicast Listener Discovery)` +(IPv6) join requests and restricts multicast traffic forwarding to only active +listeners. This prevents network flooding. +``` + +(stp)= + +#### STP configuration + +{abbr}`STP (Spanning Tree Protocol)` is a Layer 2 protocol that prevents loops +in Ethernet networks by ensuring only one logical path exists between any two +bridges. This creates a loop-free topology and prevents broadcast storms that +can crash the network. + +By default, {abbr}`STP (Spanning Tree Protocol)` is disabled on bridge interfaces. +To activate loop prevention, you must explicitly enable the protocol and +configure its parameters. + +```{cfgcmd} set interfaces bridge \<interface\> stp + +Enable {abbr}`STP (Spanning Tree Protocol)` on the bridge interface. +``` + +```{cfgcmd} set interfaces bridge \<interface\> forwarding-delay \<delay\> + +**Configure the** {abbr}`STP (Spanning Tree Protocol)` **delay, in seconds, +for the bridge interface.** + +This parameter defines how long the bridge interface remains in the listening +and learning states before forwarding traffic. The delay ensures that the +bridge has sufficient time to detect loops (in the listening state) and learn +the MAC addresses of connected devices (in the learning state). + +The default value is 15 seconds. The total time before forwarding begins is +twice this value. +``` + +```{cfgcmd} set interfaces bridge \<interface\> hello-time \<interval\> + +**Configure the** {abbr}`STP (Spanning Tree Protocol)` **Hello advertisement +interval, in seconds.** + +This parameter sets the frequency at which the bridge interface transmits +Hello packets ({abbr}`BPDUs (Bridge Protocol Data Units)`). These packets +originate from the root bridge and are propagated by designated bridges. If +neighbors stop receiving Hello packets, they assume a connection failure and +trigger a topology recalculation. + +The default value is 2 seconds. +``` + + +### VLAN + +#### VLAN-aware bridges + +```{cfgcmd} set interfaces bridge \<interface\> enable-vlan + +**Enable VLAN filtering (also known as VLAN awareness) on the bridge interface.** + +When enabled, the bridge strictly segregates traffic among VLANs configured +on its member interfaces. + +:::{note} +Do not configure **vif 1** on a VLAN-aware bridge. The main bridge +interface acts as VLAN 1 (the default native VLAN) and automatically +handles all untagged traffic. +::: +``` + +```{cfgcmd} set interfaces bridge \<interface\> protocol \<802.1ad | 802.1q\> + +**Configure the VLAN protocol (EtherType) for the bridge interface.** + +The following options are available: +* ``802.1q`` (default): Sets the EtherType to ``0x8100``. Used for standard +enterprise VLANs. +* ``802.1ad``: Sets the EtherType to ``0x88a8``. Used for QinQ (provider bridging). +``` + + +#### VLAN configuration + +```{cmdincludemd} /_include/interface-vlan-8021q.txt +:var0: bridge +:var1: br0 +``` + +```{cfgcmd} set interfaces bridge \<interface\> member interface \<member\> native-vlan \<vlan-id\> + +**Configure the native VLAN ID for a specific member interface within a +VLAN-aware bridge.** + +This assigns the specified ``<vlan-id>`` to untagged traffic entering the member +interface. The bridge strips the VLAN tag from outgoing traffic matching this +ID. + +**Example:** + +Set the native VLAN ID to 2 for the member interface ``eth0``: + +:::{code-block} none +set interfaces bridge br1 member interface eth0 native-vlan 2 +::: +``` + +```{cfgcmd} set interfaces bridge \<interface\> member interface \<member\> allowed-vlan \<vlan-id\> + +**Configure allowed VLAN IDs for a specific member interface within a +VLAN-aware bridge.** + +Enter a single VLAN ID or a range of VLAN IDs separated by a hyphen. + +**Example:** + +To allow VLAN ID 4 on member interface ``eth0``: + +:::{code-block} none +set interfaces bridge br1 member interface eth0 allowed-vlan 4 +::: +**Example:** + +To allow VLAN IDs 6 through 8 on member interface ``eth0``: + +:::{code-block} none +set interfaces bridge br1 member interface eth0 allowed-vlan 6-8 +::: +``` + + +### SPAN port mirroring + +```{cmdincludemd} ../../_include/interface-mirror.txt +:var0: bridge +:var1: br1 +:var2: eth3 +``` + + +## Examples + +### Configure a standard bridge + +The following example creates a bridge named br100 with {abbr}`STP (Spanning +Tree Protocol)` enabled. + +Configuration requirements: +- **Bridge name:** `br100` +- **Member interfaces:** Physical interface `eth1` and VLAN interface `eth2.10`. +- **STP:** Enabled. +- **Bridge IP addresses:** `192.0.2.1/24` (IPv4) and `2001:db8::ffff/64` (IPv6). + +```none +set interfaces bridge br100 address 192.0.2.1/24 +set interfaces bridge br100 address 2001:db8::ffff/64 +set interfaces bridge br100 member interface eth1 +set interfaces bridge br100 member interface eth2.10 +set interfaces bridge br100 stp +``` + +Verify the configuration: + +```none +vyos@vyos# show interfaces bridge br100 + address 192.0.2.1/24 + address 2001:db8::ffff/64 + member { + interface eth1 { + } + interface eth2.10 { + } + } + stp +``` + + +### Configure a VLAN-aware bridge + +The following example creates a VLAN-aware bridge named br100. In this setup, +one member interface is configured as a trunk port, and the other as an access +port. The VLAN interface is configured with IP addresses. + +**Configuration requirements:** +- **Bridge name:** `br100`. +- **Trunk port** (`eth1`): Handles **tagged** traffic for VLAN 10. +- **Access port** (`eth2`): Handles **untagged** traffic (assigned to native + VLAN 10). +- **STP:** Enabled. +- **VLAN IP addresses** (`vif 10`): `192.0.2.1/24` (IPv4) and + `2001:db8::ffff/64` (IPv6). + +```none +set interfaces bridge br100 enable-vlan +set interfaces bridge br100 member interface eth1 allowed-vlan 10 +set interfaces bridge br100 member interface eth2 native-vlan 10 +set interfaces bridge br100 vif 10 address 192.0.2.1/24 +set interfaces bridge br100 vif 10 address 2001:db8::ffff/64 +set interfaces bridge br100 stp +``` + +Verify the configuration: + +```none +vyos@vyos# show interfaces bridge br100 + enable-vlan + member { + interface eth1 { + allowed-vlan 10 + } + interface eth2 { + native-vlan 10 + } + } + stp + vif 10 { + address 192.0.2.1/24 + address 2001:db8::ffff/64 + } +``` + + +### Operation + +```{opcmd} show bridge + +Show the status of member interfaces for all configured bridges. + +:::{code-block} none +vyos@vyos:~$ show bridge +3: eth1: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 master br0 state forwarding +priority 32 cost 100 +4: eth2: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 master br0 state forwarding +priority 32 cost 100 +::: +``` + +```{opcmd} show bridge \<name\> fdb + +Show the {abbr}`FDB (Forwarding Database)` for the specified bridge. + +:::{code-block} none +vyos@vyos:~$ show bridge br0 fdb +50:00:00:08:00:01 dev eth1 vlan 20 master br0 permanent +50:00:00:08:00:01 dev eth1 vlan 10 master br0 permanent +50:00:00:08:00:01 dev eth1 master br0 permanent +33:33:00:00:00:01 dev eth1 self permanent +33:33:00:00:00:02 dev eth1 self permanent +01:00:5e:00:00:01 dev eth1 self permanent +50:00:00:08:00:02 dev eth2 vlan 20 master br0 permanent +50:00:00:08:00:02 dev eth2 vlan 10 master br0 permanent +50:00:00:08:00:02 dev eth2 master br0 permanent +33:33:00:00:00:01 dev eth2 self permanent +33:33:00:00:00:02 dev eth2 self permanent +01:00:5e:00:00:01 dev eth2 self permanent +33:33:00:00:00:01 dev br0 self permanent +33:33:00:00:00:02 dev br0 self permanent +33:33:ff:08:00:01 dev br0 self permanent +01:00:5e:00:00:6a dev br0 self permanent +33:33:00:00:00:6a dev br0 self permanent +01:00:5e:00:00:01 dev br0 self permanent +33:33:ff:00:00:00 dev br0 self permanent +::: +``` + +```{opcmd} show bridge \<name\> mdb + +Show the {abbr}`MDB (Multicast group Database)` for the specified bridge. + +The {abbr}`MDB (Multicast group Database)` is populated by {abbr}`IGMP +(Internet Group Management Protocol)`/{abbr}`MLD (Multicast Listener +Discovery)` snooping and lists the multicast groups currently active on the +bridge. + +:::{code-block} none +vyos@vyos:~$ show bridge br0 mdb +dev br0 port br0 grp ff02::1:ff00:0 temp vid 1 +dev br0 port br0 grp ff02::2 temp vid 1 +dev br0 port br0 grp ff02::1:ff08:1 temp vid 1 +dev br0 port br0 grp ff02::6a temp vid 1 +::: +``` + +```{opcmd} show bridge \<name\> macs + +Show the learned {abbr}`MAC (Media Access Control)` address table for the +specified bridge. + +:::{code-block} none +vyos@vyos:~$ show bridge br100 macs +port no mac addr is local? ageing timer + 1 00:53:29:44:3b:19 yes 0.00 +::: +```
\ No newline at end of file diff --git a/docs/configuration/interfaces/dummy.md b/docs/configuration/interfaces/dummy.md new file mode 100644 index 00000000..d2d27c5d --- /dev/null +++ b/docs/configuration/interfaces/dummy.md @@ -0,0 +1,87 @@ +--- +lastproofread: '2026-01-23' +--- + +(dummy-interface)= + +# Dummy + +A dummy interface is a virtual network interface that operates like the +loopback interface, accepting traffic and routing it back to the local host. +Unlike the loopback interface, which is limited to one per system and reserved +for internal system use, multiple dummy interfaces can be created, removed, and +managed without impacting core operations. + +As a software-based interface, the dummy interface does not depend on physical +link state and remains active as long as the operating system is running. + +Dummy interfaces are commonly used in environments with multiple redundant +uplinks (e.g., a server connected to two different switches), where assigning a +management IP address to a specific physical interface is risky. If that +interface fails, the management IP address becomes unreachable. + +Assigning the management IP address to a dummy interface and advertising it +over all available physical links ensures the address remains reachable as long +as at least one physical path is active. + +Dummy interfaces are also used for testing and simulation purposes. + +## Configuration + +### Common interface configuration + +```{cmdincludemd} /_include/interface-address.txt +:var0: dummy +:var1: dum0 +``` + +```{cmdincludemd} /_include/interface-description.txt +:var0: dummy +:var1: dum0 +``` + +```{cmdincludemd} /_include/interface-disable.txt +:var0: dummy +:var1: dum0 +``` + +```{cmdincludemd} /_include/interface-vrf.txt +:var0: dummy +:var1: dum0 +``` + + +## Operation + +```{opcmd} show interfaces dummy + +Show brief interface information. + +:::{code-block} none +vyos@vyos:~$ show interfaces dummy +Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down +Interface IP Address S/L Description +--------- ---------- --- ----------- +dum0 172.18.254.201/32 u/u +::: +``` + +```{opcmd} show interfaces dummy \<interface\> + +Show detailed interface information. + +:::{code-block} none +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 + valid_lft forever preferred_lft forever + inet6 fe80::247c:8eff:febc:fcf5/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 +::: +```
\ No newline at end of file diff --git a/docs/configuration/interfaces/ethernet.md b/docs/configuration/interfaces/ethernet.md new file mode 100644 index 00000000..eac0b443 --- /dev/null +++ b/docs/configuration/interfaces/ethernet.md @@ -0,0 +1,515 @@ +--- +lastproofread: '2026-01-19' +--- + +(ethernet-interface)= + +# Ethernet + +Ethernet interfaces (e.g., `eth0`, `eth1`) represent the host's physical +or virtual network ports. + +They are the most common interface type, serving as the base layer upon which +IP addresses, VLANs, and tunnels are configured to carry traffic across both +LANs and WANs. + +## Configuration + +### Common interface configuration + +```{cmdincludemd} /_include/interface-common-with-dhcp.txt +:var0: ethernet +:var1: eth0 +``` + +```{cfgcmd} set interfaces ethernet \<interface\> switchdev + +**Enable** ``switchdev`` **mode for the interface.** + +In ``switchdev`` mode, the interface offloads traffic switching between ports +to the hardware, bypassing the host CPU. This increases the interface’s +traffic-handling capacity and reduces its forwarding delay. +``` + +:::{note} +`switchdev` mode is available only on certain physical network +interfaces and requires a switchdev-compatible driver. +::: + +### Ethernet options + +```{cfgcmd} set interfaces ethernet \<interface\> duplex \<auto | full | half\> + +**Configure duplex mode for the interface.** + +The following duplex modes are available: + +* ``auto``: The interface negotiates the duplex mode with the connected device. +* ``full``: The interface sends and receives data simultaneously. The + connected device must also be set to full-duplex to avoid a duplex mismatch. +* ``half``: The interface either sends or receives data, but not both at the + same time. + +The default duplex mode is ``auto``. +``` + +```{cfgcmd} set interfaces ethernet \<interface\> speed \<auto | 10 | 100 | 1000 | 2500 | 5000 | 10000 | 25000 | 40000 | 50000 | 100000\> + +**Configure the interface's speed, in Mbit/s.** + +The following options are available: + +* ``auto``: The interface negotiates the speed with the connected device. +* ``10, 100, 1000 ...``: The interface operates at the selected speed. The + connected device must be set to the same speed to establish a connection. + +The default option is ``auto``. +``` + +```{cfgcmd} set interfaces ethernet \<interface\> ring-buffer rx \<value\> + +**Configure the receive (RX) ring buffer size for the interface.** + +The RX ring buffer size defines the number of incoming packets the interface +can queue in hardware before the CPU processes them. + +Higher values reduce the risk of drops when the NIC receives network traffic +faster than the CPU can process it, though latency may increase. Lower values +reduce latency but increase the risk of packet drops during incoming traffic +bursts. + +To view supported values for a specific interface, use: +``` + +```none +ethtool -g <interface> +``` + +```{cfgcmd} set interfaces ethernet \<interface\> ring-buffer tx \<value\> + +**Configure the transmit (TX) ring buffer size.** + +The TX ring buffer size defines the number of outgoing packets the interface +can queue in hardware before they are transmitted onto the network. + +Higher values reduce the risk of drops when the CPU generates traffic faster +than the NIC can handle, though latency may increase. Lower values reduce +latency but increase the risk of packet drops during outgoing traffic bursts. + +To view supported values for a specific interface, use: +``` + +```none +ethtool -g <interface> +``` + + +#### Interrupt Coalescing + +Interrupt coalescing is a mechanism that reduces CPU interrupt load by bundling +multiple packets into a single interrupt event instead of interrupting +the CPU for every packet arrival or transmission. + +:::{note} +Not all network drivers or virtual interfaces support all +coalescing parameters. Use `ethtool --show-coalesce <interface>` +to verify which settings are supported by your hardware and driver. +::: + +**Basic adaptive coalescing** + +```{cfgcmd} set interfaces ethernet \<interface\> interrupt-coalescing adaptive-rx + +``` +```{cfgcmd} set interfaces ethernet \<interface\> interrupt-coalescing adaptive-tx + +Enable adaptive interrupt coalescing. The NIC automatically tunes RX/TX +interrupt pacing based on traffic patterns to reduce CPU utilization +during high throughput while preserving latency at low packet rates. +``` + +**Basic interrupt delay** + +```{cfgcmd} set interfaces ethernet \<interface\> interrupt-coalescing rx-usecs \<0-16384\> +``` + +```{cfgcmd} set interfaces ethernet \<interface\> interrupt-coalescing tx-usecs \<0-16384\> + +Set the delay in microseconds before generating an RX/TX interrupt after +receiving or transmitting a packet. Lower values reduce latency; higher +values reduce CPU load. +``` + +**Interrupt frame thresholds** + +```{cfgcmd} set interfaces ethernet \<interface\> interrupt-coalescing rx-frames \<number\> +``` + +```{cfgcmd} set interfaces ethernet \<interface\> interrupt-coalescing tx-frames \<number\> + +Generate an RX/TX interrupt only after the specified number of packets +have been received or transmitted. +``` + +**IRQ-specific coalescing** + +```{cfgcmd} set interfaces ethernet \<interface\> interrupt-coalescing rx-usecs-irq \<number\> +``` + +```{cfgcmd} set interfaces ethernet \<interface\> interrupt-coalescing rx-frames-irq \<number\> +``` + +```{cfgcmd} set interfaces ethernet \<interface\> interrupt-coalescing tx-usecs-irq \<number\> +``` + +```{cfgcmd} set interfaces ethernet \<interface\> interrupt-coalescing tx-frames-irq \<number\> + +Control interrupt coalescing parameters while the driver is already +servicing an interrupt (IRQ context). These settings allow finer tuning +of interrupt behavior under sustained load. +``` + +**Adaptive rate thresholds** + +```{cfgcmd} set interfaces ethernet \<interface\> interrupt-coalescing pkt-rate-low \<number\> +``` + +```{cfgcmd} set interfaces ethernet \<interface\> interrupt-coalescing pkt-rate-high \<number\> + +Define packet-rate thresholds (packets per second) used by adaptive +coalescing to switch between low-rate and high-rate interrupt coalescing +profiles. +``` + +**Low-rate adaptive parameters** + +```{cfgcmd} set interfaces ethernet \<interface\> interrupt-coalescing rx-usecs-low \<number\> +``` + +```{cfgcmd} set interfaces ethernet \<interface\> interrupt-coalescing rx-frame-low \<number\> +``` + +```{cfgcmd} set interfaces ethernet \<interface\> interrupt-coalescing tx-usecs-low \<number\> +``` + +```{cfgcmd} set interfaces ethernet \<interface\> interrupt-coalescing tx-frame-low \<number\> + +Interrupt coalescing parameters applied when the packet rate is below +``pkt-rate-low``. Typically optimized for lower latency. +``` + +**High-rate adaptive parameters** + +```{cfgcmd} set interfaces ethernet \<interface\> interrupt-coalescing rx-usecs-high \<number\> +``` + +```{cfgcmd} set interfaces ethernet \<interface\> interrupt-coalescing rx-frame-high \<number\> +``` + +```{cfgcmd} set interfaces ethernet \<interface\> interrupt-coalescing tx-usecs-high \<number\> +``` + +```{cfgcmd} set interfaces ethernet \<interface\> interrupt-coalescing tx-frame-high \<number\> + +Interrupt coalescing parameters applied when the packet rate exceeds +``pkt-rate-high``. Typically optimized for maximum throughput and +reduced CPU utilization. +``` + +**Statistics and sampling** + +```{cfgcmd} set interfaces ethernet \<interface\> interrupt-coalescing stats-block-usecs \<number\> +``` + +```{cfgcmd} set interfaces ethernet \<interface\> interrupt-coalescing sample-interval \<number\> + +Control how frequently coalescing statistics are updated and how often +the NIC samples traffic rates for adaptive coalescing decisions. +``` + +**Completion queue (CQE) mode** + +```{cfgcmd} set interfaces ethernet \<interface\> interrupt-coalescing cqe-mode-rx +``` + +```{cfgcmd} set interfaces ethernet \<interface\> interrupt-coalescing cqe-mode-tx + +Enable RX/TX Completion Queue Entry (CQE) mode, if supported by the +driver. CQE mode can improve performance on high-speed NICs by +optimizing completion handling. +``` + +**Transmit aggregation** + +```{cfgcmd} set interfaces ethernet \<interface\> interrupt-coalescing tx-aggr-max-bytes \<number\> +``` + +```{cfgcmd} set interfaces ethernet \<interface\> interrupt-coalescing tx-aggr-max-frames \<number\> +``` + +```{cfgcmd} set interfaces ethernet \<interface\> interrupt-coalescing tx-aggr-time-usecs \<number\> + +Control transmit packet aggregation. Packets may be buffered and sent +together until one of the configured limits (bytes, frames, or time) +is reached, reducing interrupt and DMA overhead. +``` + +#### Offloading + +```{cfgcmd} set interfaces ethernet \<interface\> offload \<lro | tso | gso | gro | rps | sg\> + +**Configure the offloading features for the interface.** + +The interface offloading features define whether specific packet-processing tasks +are performed by hardware (the NIC) or by software (the kernel). You can enable +multiple offloading features for a single interface. + + * ``lro`` **(Large Receive Offload):** Instructs the NIC to merge multiple + incoming packets into one larger packet before sending it to the CPU. + + :::{note} + {abbr}`LRO (Large Receive Offload)` hardware support is often limited + to TCP/IPv4 packets. For details on LRO limitations, see + https://lwn.net/Articles/358910/ + ::: + :::{warning} + {abbr}`LRO (Large Receive Offload)` irreversibly alters packet + headers during merging. This prevents the merged packet from being correctly + split back into the original packets, causing packet drops and forwarding + failures on routers and bridges. Use {abbr}`LRO (Large Receive Offload)` only + for end-hosts that do not forward traffic. + ::: + * ``tso`` **(TCP Segmentation Offload):** Instructs the NIC to split large TCP + packets into smaller ones before transmitting them to the network. + + **Important:** {abbr}`SG (Scatter-Gather/Scatter-Gather DMA)` must be enabled + for {abbr}`TSO (TCP Segmentation Offload)` to work. Additionally, {abbr}`GSO + (Generic Segmentation Offload)` should be enabled as a safety fallback; it + ensures that if traffic is rerouted to hardware without {abbr}`TSO (TCP + Segmentation Offload)` support, the kernel can still segment the packets, + preventing transmission failures. + + * ``gso`` **(Generic Segmentation Offload):** Instructs the kernel to split + large packets into smaller ones before sending them to the NIC. + + {abbr}`GSO (Generic Segmentation Offload)` serves as a software fallback for + hardware that does not support {abbr}`TSO (TCP Segmentation Offload)` or for + protocols (like UDP) that hardware cannot offload. + + **Important:** {abbr}`SG (Scatter-Gather/Scatter-Gather DMA)` must be enabled + for {abbr}`GSO (Generic Segmentation Offload)` to work. + + * ``gro`` **(Generic Receive Offload):** Instructs the kernel to merge multiple + incoming packets into one larger packet before passing it to upper protocol + layers. + + Unlike LRO, GRO preserves the necessary packet metadata so the merged packet + can be correctly split back into the original packets. This makes GRO safe for + use on routers and bridges. + + :::{note} +The exception is for IPv4 IDs. If the "Don't Fragment" (DF) bit is +set and IDs are not sequential, {abbr}`GSO (Generic Segmentation Offload)` +alters them to maintain a consistent sequence for {abbr}`GSO (Generic +Segmentation Offload)` compatibility. + ::: + * ``rps`` **(Receive Packet Steering):** Instructs the kernel to distribute + the processing of incoming packets across multiple CPU cores. + + The kernel calculates a hash from packet headers (IP addresses and ports) to + ensure packets from the same flow are processed by the same CPU core. + + :::{note} +{abbr}`RPS (Receive Packet Steering)` is a software version of +{abbr}`RSS (Receive Side Scaling)` and is useful for NICs without hardware +multi-queue support. + ::: + * ``sg`` **(Scatter-Gather/Scatter-Gather DMA):** Instructs the NIC to fetch + data fragments from various RAM locations and transmit them as a single packet + to the network, eliminating the need for the kernel to copy them into a + contiguous block first. +``` + +#### 802.1X (EAPOL) authentication + +```{cmdincludemd} /_include/interface-eapol.txt +:var0: ethernet +:var1: eth0 +``` + +#### EVPN Multihoming + +Uplink/core tracking. + +```{cmdincludemd} /_include/interface-evpn-uplink.txt +:var0: ethernet +:var1: eth0 +``` + +### VLAN +#### Regular VLANs (802.1q) + +```{cmdincludemd} /_include/interface-vlan-8021q.txt +:var0: ethernet +:var1: eth0 +``` + +#### 802.1ad (QinQ) + +```{cmdincludemd} /_include/interface-vlan-8021ad.txt +:var0: ethernet +:var1: eth0 +``` + +### SPAN port mirroring + +```{cmdincludemd} ../../_include/interface-mirror.txt +:var0: ethernet +:var1: eth1 +:var2: eth3 +``` + +## Operation + +```{opcmd} show interfaces ethernet + +Show brief interface information. + +:::{code-block} none +vyos@vyos:~$ show interfaces ethernet +Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down +Interface IP Address S/L Description +--------- ---------- --- ----------- +eth0 172.18.201.10/24 u/u LAN +eth1 172.18.202.11/24 u/u WAN +eth2 - u/D +::: +``` + +```{opcmd} show interfaces ethernet \<interface\> + +Show detailed interface information. + +:::{code-block} none +vyos@vyos:~$ show interfaces ethernet eth0 +eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP group default qlen 1000 + link/ether 00:50:44:00:f5:c9 brd ff:ff:ff:ff:ff:ff + inet6 fe80::250:44ff:fe00:f5c9/64 scope link + valid_lft forever preferred_lft forever + + RX: bytes packets errors dropped overrun mcast + 56735451 179841 0 0 0 142380 + TX: bytes packets errors dropped carrier collisions + 5601460 62595 0 0 0 0 +::: +``` + +```{opcmd} show interfaces ethernet \<interface\> physical + +Show interface hardware-level and driver details. + +:::{code-block} none +vyos@vyos:~$ show interfaces ethernet eth0 physical +Settings for eth0: + Supported ports: [ TP ] + Supported link modes: 1000baseT/Full + 10000baseT/Full + Supported pause frame use: No + Supports auto-negotiation: No + Supported FEC modes: Not reported + Advertised link modes: Not reported + Advertised pause frame use: No + Advertised auto-negotiation: No + Advertised FEC modes: Not reported + Speed: 10000Mb/s + Duplex: Full + Port: Twisted Pair + PHYAD: 0 + Transceiver: internal + Auto-negotiation: off + MDI-X: Unknown + Supports Wake-on: uag + Wake-on: d + Link detected: yes +driver: vmxnet3 +version: 1.4.16.0-k-NAPI +firmware-version: +expansion-rom-version: +bus-info: 0000:0b:00.0 +supports-statistics: yes +supports-test: no +supports-eeprom-access: no +supports-register-dump: yes +supports-priv-flags: no +::: +``` + +```{opcmd} show interfaces ethernet \<interface\> physical offload + +Show the status of the interface offloading features. + +:::{code-block} none +vyos@vyos:~$ show interfaces ethernet eth0 physical offload +rx-checksumming on +tx-checksumming on +tx-checksum-ip-generic on +scatter-gather off +tx-scatter-gather off +tcp-segmentation-offload off +tx-tcp-segmentation off +tx-tcp-mangleid-segmentation off +tx-tcp6-segmentation off +udp-fragmentation-offload off +generic-segmentation-offload off +generic-receive-offload off +large-receive-offload off +rx-vlan-offload on +tx-vlan-offload on +ntuple-filters off +receive-hashing on +tx-gre-segmentation on +tx-gre-csum-segmentation on +tx-udp_tnl-segmentation on +tx-udp_tnl-csum-segmentation on +tx-gso-partial on +tx-nocache-copy off +rx-all off +::: +``` + +```{opcmd} show interfaces ethernet \<interface\> transceiver + +Show information about the transceiver module plugged into the interface +(e.g., SFP+, QSFP). + +:::{code-block} none +vyos@vyos:~$ show interfaces ethernet eth5 transceiver + Identifier : 0x03 (SFP) + Extended identifier : 0x04 (GBIC/SFP defined by 2-wire interface ID) + Connector : 0x07 (LC) + Transceiver codes : 0x00 0x00 0x00 0x01 0x00 0x00 0x00 0x00 0x00 + Transceiver type : Ethernet: 1000BASE-SX + Encoding : 0x01 (8B/10B) + BR, Nominal : 1300MBd + Rate identifier : 0x00 (unspecified) + Length (SMF,km) : 0km + Length (SMF) : 0m + Length (50um) : 550m + Length (62.5um) : 270m + Length (Copper) : 0m + Length (OM3) : 0m + Laser wavelength : 850nm + Vendor name : CISCO-FINISAR + Vendor OUI : 00:90:65 + Vendor PN : FTRJ-8519-7D-CS4 + Vendor rev : A + Option values : 0x00 0x1a + Option : RX_LOS implemented + Option : TX_FAULT implemented + Option : TX_DISABLE implemented + BR margin, max : 0% + BR margin, min : 0% + Vendor SN : FNS092xxxxx + Date code : 0506xx +::: +```
\ No newline at end of file diff --git a/docs/configuration/interfaces/geneve.md b/docs/configuration/interfaces/geneve.md new file mode 100644 index 00000000..1fce1119 --- /dev/null +++ b/docs/configuration/interfaces/geneve.md @@ -0,0 +1,105 @@ +--- +lastproofread: '2026-02-02' +--- + +(geneve-interface)= + +# Geneve + +{abbr}`Geneve (Generic Network Virtualization Encapsulation)` interfaces +operate as virtual network ports. Administrators can apply standard network +configurations on them, such as IP addressing, bridging, or firewall rules, +just as they would on physical Ethernet ports. + +The Geneve protocol encapsulates Layer 2 Ethernet frames originating from +endpoints such as virtual machines, containers, or physical servers inside UDP +packets. It unifies the features of earlier encapsulation protocols, including +VXLAN, NVGRE, and STT, and addresses their limitations, such as fixed header +structures and a lack of metadata support. Because of its extensibility, Geneve +may eventually replace those older protocols. + +Geneve tunnels are used to connect virtual switches residing within +hypervisors, physical switches, middleboxes, and other network appliances. + +Geneve tunnels operate over any standard IP network. In larger deployments, +the underlying network (underlay) is often built using a **Clos** topology, +also known as a *leaf-and-spine* or *fat-tree* topology. + +Geneve header: + +```none ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +|Ver| Opt Len |O|C| Rsvd. | Protocol Type | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +| Virtual Network Identifier (VNI) | Reserved | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +| Variable Length Options | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +``` + + +## Configuration + +### Common interface configuration + +```{cmdincludemd} /_include/interface-address.txt +:var0: geneve +:var1: gnv0 +``` + +```{cmdincludemd} /_include/interface-description.txt +:var0: geneve +:var1: gnv0 +``` + +```{cmdincludemd} /_include/interface-disable.txt +:var0: geneve +:var1: gnv0 +``` + +```{cmdincludemd} /_include/interface-mac.txt +:var0: geneve +:var1: gnv0 +``` + +```{cmdincludemd} /_include/interface-mtu.txt +:var0: geneve +:var1: gnv0 +``` + +```{cmdincludemd} /_include/interface-ip.txt +:var0: geneve +:var1: gnv0 +``` + +```{cmdincludemd} /_include/interface-ipv6.txt +:var0: geneve +:var1: gnv0 +``` + + +### Geneve options + +```{cfgcmd} set interfaces geneve gnv0 remote \<address\> + +Configure the remote endpoint IP address for the Geneve tunnel. +``` + +```{cfgcmd} set interfaces geneve gnv0 vni \<vni\> + +**Configure** {abbr}`VNI (Virtual Network Identifier)` **for the Geneve +interface.** + +The VNI is a virtual network identifier. It allows multiple virtual networks to +share the same physical infrastructure and remain isolated. + +The VNI is also used to distribute traffic after it leaves the tunnel, for +example, to map packets with overlapping IP addresses to specific routing +tables. +``` + +```{cfgcmd} set interfaces gnv0 \<interface\> port \<port\> + +**Configure the destination UDP port for the remote Geneve tunnel endpoint.** +Ensure the remote peer is configured to listen on this specific port. +```
\ No newline at end of file diff --git a/docs/configuration/interfaces/index.md b/docs/configuration/interfaces/index.md new file mode 100644 index 00000000..9082cd80 --- /dev/null +++ b/docs/configuration/interfaces/index.md @@ -0,0 +1,26 @@ +# Interfaces + +```{toctree} +:includehidden: true +:maxdepth: 1 + +bonding +bridge +dummy +ethernet +geneve +l2tpv3 +loopback +macsec +openvpn +wireguard +pppoe +pseudo-ethernet +sstp-client +tunnel +virtual-ethernet +vti +vxlan +wireless +wwan +``` diff --git a/docs/configuration/interfaces/l2tpv3.md b/docs/configuration/interfaces/l2tpv3.md new file mode 100644 index 00000000..324840fa --- /dev/null +++ b/docs/configuration/interfaces/l2tpv3.md @@ -0,0 +1,170 @@ +--- +lastproofread: '2026-02-05' +--- + +(l2tpv3-interface)= + +# L2TPv3 + +{abbr}`L2TPv3 (Layer 2 Tunneling Protocol version 3)` interfaces let you +establish L2TPv3 tunnels to transport Layer 2 traffic over IP networks. + +The L2TPv3 protocol (defined in RFC 3931) wraps Layer 2 frames (e.g., Ethernet, +Frame Relay, HDLC) within IP packets, allowing them to traverse the underlying +IP infrastructure. + +Unlike L2TPv2, which strictly requires UDP encapsulation, the L2TPv3 protocol +is more flexible and supports two encapsulation types: + +> - **Direct IP:** Tunnel data is encapsulated directly inside IP packets +> (Protocol 115) for lower overhead. +> - **UDP:** Tunnel data is encapsulated inside a UDP datagram. This allows the +> tunnel to traverse NAT more easily. + +L2TPv3 tunnels connect geographically separated sites, serving as a simpler +alternative to {ref}`mpls` by operating over basic IP connectivity rather than +requiring a full MPLS infrastructure. + +L2TPv3 tunnels can be established over both IPv4 and IPv6 underlying networks. + +## Configuration + +### Common interface configuration + +```{cmdincludemd} /_include/interface-common-without-dhcp.txt +:var0: l2tpv3 +:var1: l2tpeth0 +``` + + +### L2TPv3 options + +Use the following commands to configure the L2TPv3 tunnel's specific parameters. + +```{cfgcmd} set interfaces l2tpv3 \<interface\> encapsulation \<udp | ip\> + +**Configure the encapsulation type for the L2TPv3 tunnel.** + +Valid values are ``udp`` and ``ip``. + +The default encapsulation type is ``udp``. +``` + +:::{note} +The encapsulation type must match on both the local and remote peers +for the tunnel to establish. +::: + +```{cfgcmd} set interfaces l2tpv3 \<interface\> source-address \<address\> + +**Configure the L2TPv3 tunnel source IP address.** + +The specified address must be a local interface IP address and can be either +IPv4 or IPv6. +``` + +```{cfgcmd} set interfaces l2tpv3 \<interface\> remote \<address\> + +**Configure the L2TPv3 tunnel destination IP address.** + +The specified address must be a remote peer’s interface IP address and can be +either IPv4 or IPv6. +``` + +```{cfgcmd} set interfaces l2tpv3 \<interface\> session-id \<id\> + +**Configure the local session ID within the L2TPv3 tunnel.** + +The ``session-id`` is a 32-bit value that identifies an incoming tunnel session +on the local peer. + +The ``peer-session-id`` that identifies this session on the remote peer must be +set to the same value. +``` + +```{cfgcmd} set interfaces l2tpv3 \<interface\> peer-session-id \<id\> + +**Configure the peer session ID within the L2TPv3 tunnel.** + +The ``peer-session-id`` is a 32-bit value that identifies an outgoing tunnel +session from the local peer. + +The ``peer-session-id`` must match the ``session-id`` configured for this +session on the remote peer. +``` + +```{cfgcmd} set interfaces l2tpv3 \<interface\> tunnel-id \<id\> + +**Configure the local identifier for the L2TPv3 tunnel.** + +The ``tunnel-id`` is a 32-bit value that identifies the L2TPv3 tunnel on the +local peer. + +The ``peer-tunnel-id`` that identifies this tunnel on the remote peer must be +set to the same value. +``` + +```{cfgcmd} set interfaces l2tpv3 \<interface\> peer-tunnel-id \<id\> + +**Configure the peer identifier for the L2TPv3 tunnel.** + +The ``peer-tunnel-id`` is a 32-bit value that identifies the L2TPv3 tunnel on +the remote peer and must correspond to the ``tunnel-id`` configured for that +tunnel on that peer. + +The ``peer-tunnel-id`` must match the ``tunnel-id`` that identifies this tunnel +on the remote peer. +``` + + +## Example + +### L2TPv3 tunnel with IP encapsulation + +The following example shows the configuration of an L2TPv3 tunnel using direct +IP encapsulation: + +```none +# show interfaces l2tpv3 +l2tpv3 l2tpeth10 { + address 192.168.37.1/27 + encapsulation ip + source-address 192.0.2.1 + peer-session-id 100 + peer-tunnel-id 200 + remote 203.0.113.24 + session-id 100 + tunnel-id 200 +} +``` + +The inverse configuration must be applied to the remote peer. + +### L2TPv3 tunnel with UDP encapsulation + +The following example shows the configuration of an L2TPv3 tunnel using UDP +encapsulation. + +This setup is recommended when the tunnel traverses NAT devices. + +Configuration notes: +- Use a local LAN IP address as the `source-address`. +- Configure a forwarding rule to allow tunnel traffic on the specified UDP port + on the upstream NAT device. +- Use a distinct UDP port for each individual tunnel. + +```none +# show interfaces l2tpv3 +l2tpv3 l2tpeth10 { + address 192.168.37.1/27 + destination-port 9001 + encapsulation udp + source-address 192.0.2.1 + peer-session-id 100 + peer-tunnel-id 200 + remote 203.0.113.24 + session-id 100 + source-port 9000 + tunnel-id 200 +} +``` diff --git a/docs/configuration/interfaces/loopback.md b/docs/configuration/interfaces/loopback.md new file mode 100644 index 00000000..72f14c16 --- /dev/null +++ b/docs/configuration/interfaces/loopback.md @@ -0,0 +1,67 @@ +--- +lastproofread: '2026-01-23' +--- + +(loopback-interface)= + +# Loopback + +The loopback interface is a virtual, software-based network interface. All +traffic sent to it loops back and only targets services on the local host. + +:::{note} +Only one loopback `lo` interface is allowed per operating system. +If you require multiple virtual interfaces, use the {ref}`dummy-interface` +interface type. +::: + +## Configuration + +### Common interface configuration + +```{cmdincludemd} /_include/interface-address.txt +:var0: loopback +:var1: lo +``` + +```{cmdincludemd} /_include/interface-description.txt +:var0: loopback +:var1: lo +``` + + +## Operation + +```{opcmd} show interfaces loopback + +Show brief interface information. + +:::{code-block} none +vyos@vyos:~$ show interfaces loopback +Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down +Interface IP Address S/L Description +--------- ---------- --- ----------- +lo 127.0.0.1/8 u/u + ::1/128 +::: +``` + +```{opcmd} show interfaces loopback lo + +Show detailed interface information. + +:::{code-block} none +vyos@vyos:~$ show interfaces loopback lo +lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1000 + link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00 + inet 127.0.0.1/8 scope host lo + valid_lft forever preferred_lft forever + inet6 ::1/128 scope host + valid_lft forever preferred_lft forever + + RX: bytes packets errors dropped overrun mcast + 300 6 0 0 0 0 + TX: bytes packets errors dropped carrier collisions + 300 6 0 0 0 0 +::: +```
\ No newline at end of file diff --git a/docs/configuration/interfaces/macsec.md b/docs/configuration/interfaces/macsec.md new file mode 100644 index 00000000..b3c70362 --- /dev/null +++ b/docs/configuration/interfaces/macsec.md @@ -0,0 +1,319 @@ +--- +lastproofread: '2026-02-13' +--- + +(macsec-interface)= + +# MACsec + +MACsec is an IEEE standard (IEEE 802.1AE) for MAC security, introduced in +2006\. It enables protocol-independent connectivity between two hosts, providing +data confidentiality, authenticity, and integrity using GCM-AES ciphers. MACsec +operates at the Ethernet layer as a Layer 2 protocol and secures traffic within +Layer 2 networks, including DHCP and ARP requests. It does not compete with +other security solutions, such as IPsec (Layer 3) or TLS (Layer 4), as each +addresses distinct use cases. + +## Configuration + +### Common interface configuration + +```{cmdincludemd} /_include/interface-common-with-dhcp.txt +:var0: macsec +:var1: macsec0 +``` + + +### MACsec options + +```{cfgcmd} set interfaces macsec \<interface\> security cipher \<gcm-aes-128|gcm-aes-256\> + +**Configure the cipher suite for the MACsec interface.** + +This configuration parameter is mandatory. +``` + +```{cfgcmd} set interfaces macsec \<interface\> security encrypt + +**Enable encryption on the MACsec interface.** + +By default, MACsec interfaces only provide authentication; encryption is +optional. +When enabled, outgoing packets are encrypted using the configured cipher suite. +``` + +```{cfgcmd} set interfaces macsec \<interface\> source-interface \<physical-source\> + +**Configure a physical source interface for the MACsec interface.** + +Traffic transmitted through this interface is authenticated and, if configured, +encrypted. +``` + + +#### MACsec key management + +**Static** {abbr}`SAK (Secure Authentication Key)` **mode** + +In static SAK mode, administrators must manually configure and update SAKs on +each MACsec peer. {abbr}`MKA (MACsec Key Agreement protocol)` cannot be used in +this mode. + +```{cfgcmd} set interfaces macsec \<interface\> security static key \<key\> + +**Configure the Transmit (TX) SAK for the MACsec interface.** + +The key must be a 16-byte (GCM-AES-128) or 64-byte (GCM-AES-256) hexadecimal +string. +``` + +```{cfgcmd} set interfaces macsec \<interface\> security static peer \<peer\> mac \<mac address\> + +**Configure the MAC address associated with the MACsec peer.** +``` + +```{cfgcmd} set interfaces macsec \<interface\> security static peer \<peer\> key \<key\> + +**Configure the RX SAK for traffic from the MACsec peer.** + +The key must be a 16-byte (GCM-AES-128) or 64-byte (GCM-AES-256) hexadecimal +string. +``` + +```{cfgcmd} set interfaces macsec \<interface\> security static peer \<peer\> disable +``` + +**Dynamic** {abbr}`MKA (MACsec Key Agreement protocol)` **mode** + +In this mode, the {abbr}`MKA (MACsec Key Agreement protocol)` protocol is used +to generate, distribute, and update {abbr}`CAKs (MACsec Connectivity +Association Keys)`, and to authenticate MACsec peers. + +```{cfgcmd} set interfaces macsec \<interface\> security mka cak \<key\> + +**Configure the** {abbr}`CAK (MACsec Connectivity Association Key)` **for the +MACsec interface.** + +The {abbr}`CAK (MACsec Connectivity Association Key)` and its {abbr}`CKN +(MACsec Connectivity Association Key Name)` form the pre-shared master key pair +used to authenticate MACsec peers. +``` + +```{cfgcmd} set interfaces macsec \<interface\> security mka ckn \<key\> + +Configure the {abbr}`CKN (MACsec Connectivity Association Key Name)` for the +MACsec interface. +``` + +```{cfgcmd} set interfaces macsec \<interface\> security mka priority \<priority\> + +Configure the MKA key server priority for the MACsec interface. +The peer with the lowest priority is elected as the key server. +``` + +#### Replay protection + +```{cfgcmd} set interfaces macsec \<interface\> security replay-window \<window\> + +The replay protection window defines how many out-of-order frames can be +received before they are dropped as a potential replay attack. +The following values are valid: +- ``0``: Any out-of-order frame is immediately dropped. +- ``1-4294967295``: Allows the specified number of out-of-order frames. +``` + +## Operation + +```{opcmd} run generate macsec mka cak \<gcm-aes-128|gcm-aes-256\> + +Generate a 128-bit (GCM-AES-128) or 256-bit (GCM-AES-256) {abbr}`MKA (MACsec +Key Agreement protocol)` {abbr}`CAK (MACsec Connectivity Association Key)`. + +:::{code-block} none +vyos@vyos:~$ generate macsec mka cak gcm-aes-128 +20693b6e08bfa482703a563898c9e3ad +::: +``` + +```{opcmd} run generate macsec mka ckn + +Generate an {abbr}`MKA (MACsec Key Agreement protocol)` {abbr}`CAK (MACsec +Connectivity Association Key)`. + +:::{code-block} none +vyos@vyos:~$ generate macsec mka ckn +88737efef314ee319b2cbf30210a5f164957d884672c143aefdc0f5f6bc49eb2 +::: +``` + +```{opcmd} show interfaces macsec + +Show all MACsec interfaces. + +:::{code-block} none +vyos@vyos:~$ show interfaces macsec +17: macsec1: protect on validate strict sc off sa off encrypt on send_sci on end_station off scb off replay off +cipher suite: GCM-AES-128, using ICV length 16 +TXSC: 005056bfefaa0001 on SA 0 +20: macsec0: protect on validate strict sc off sa off encrypt off send_sci on end_station off scb off replay off +cipher suite: GCM-AES-128, using ICV length 16 +TXSC: 005056bfefaa0001 on SA 0 +::: +``` + +```{opcmd} show interfaces macsec \<interface\> + +Show information for a specific MACsec interface. + +:::{code-block} none +vyos@vyos:~$ show interfaces macsec macsec1 +17: macsec1: protect on validate strict sc off sa off encrypt on send_sci on end_station off scb off replay off +cipher suite: GCM-AES-128, using ICV length 16 +TXSC: 005056bfefaa0001 on SA 0 +::: +``` + +## Examples + +**Site-to-site MACsec with dynamic MKA over an untrusted network** + +In the following example, two routers (R1 and R2) are connected via an +untrusted switch, using their `eth1` interfaces as the underlay. The MACsec +interface (`macsec1`) with dynamic MKA encrypts traffic between them. + +Topology details: +- R1 IP addresses: `192.0.2.1/24` and `2001:db8::1/64`. +- R2 IP addresses: `192.0.2.2/24` and `2001:db8::2/64`. + +**R1** + +```none +set interfaces macsec macsec1 address '192.0.2.1/24' +set interfaces macsec macsec1 address '2001:db8::1/64' +set interfaces macsec macsec1 security cipher 'gcm-aes-128' +set interfaces macsec macsec1 security encrypt +set interfaces macsec macsec1 security mka cak '232e44b7fda6f8e2d88a07bf78a7aff4' +set interfaces macsec macsec1 security mka ckn '40916f4b23e3d548ad27eedd2d10c6f98c2d21684699647d63d41b500dfe8836' +set interfaces macsec macsec1 source-interface 'eth1' +``` + +**R2** + +```none +set interfaces macsec macsec1 address '192.0.2.2/24' +set interfaces macsec macsec1 address '2001:db8::2/64' +set interfaces macsec macsec1 security cipher 'gcm-aes-128' +set interfaces macsec macsec1 security encrypt +set interfaces macsec macsec1 security mka cak '232e44b7fda6f8e2d88a07bf78a7aff4' +set interfaces macsec macsec1 security mka ckn '40916f4b23e3d548ad27eedd2d10c6f98c2d21684699647d63d41b500dfe8836' +set interfaces macsec macsec1 source-interface 'eth1' +``` + +Pinging (IPv6) the other host and intercepting traffic on `eth1` confirm that +the content is encrypted. + +```none +17:35:44.586668 00:50:56:bf:ef:aa > 00:50:56:b3:ad:d6, ethertype Unknown (0x88e5), length 150: + 0x0000: 2c00 0000 000a 0050 56bf efaa 0001 d9fb ,......PV....... + 0x0010: 920a 8b8d 68ed 9609 29dd e767 25a4 4466 ....h...)..g%.Df + 0x0020: 5293 487b 9990 8517 3b15 22c7 ea5c ac83 R.H{....;."..\.. + 0x0030: 4c6e 13cf 0743 f917 2c4e 694e 87d1 0f09 Ln...C..,NiN.... + 0x0040: 0f77 5d53 ed75 cfe1 54df 0e5a c766 93cb .w]S.u..T..Z.f.. + 0x0050: c4f2 6e23 f200 6dfe 3216 c858 dcaa a73b ..n#..m.2..X...; + 0x0060: 4dd1 9358 d9e4 ed0e 072f 1acc 31c4 f669 M..X...../..1..i + 0x0070: e93a 9f38 8a62 17c6 2857 6ac5 ec11 8b0e .:.8.b..(Wj..... + 0x0080: 6b30 92a5 7ccc 720b k0..|.r. +``` + +Disabling encryption on the MACsec interface by removing the `security +encrypt` option shows the unencrypted but authenticated content. + +```none +17:37:00.746155 00:50:56:bf:ef:aa > 00:50:56:b3:ad:d6, ethertype Unknown (0x88e5), length 150: + 0x0000: 2000 0000 0009 0050 56bf efaa 0001 86dd .......PV....... + 0x0010: 6009 86f3 0040 3a40 2001 0db8 0000 0000 `....@:@........ + 0x0020: 0000 0000 0000 0001 2001 0db8 0000 0000 ................ + 0x0030: 0000 0000 0000 0002 8100 d977 0f30 0003 ...........w.0.. + 0x0040: 1ca0 c65e 0000 0000 8d93 0b00 0000 0000 ...^............ + 0x0050: 1011 1213 1415 1617 1819 1a1b 1c1d 1e1f ................ + 0x0060: 2021 2223 2425 2627 2829 2a2b 2c2d 2e2f .!"#$%&'()*+,-./ + 0x0070: 3031 3233 3435 3637 87d5 eed3 3a39 d52b 01234567....:9.+ + 0x0080: a282 c842 5254 ef28 ...BRT.( +``` + +**Site-to-site MACsec with static SAK over an untrusted network** + +This example uses the same topology as above, but applies static SAK mode to +the MACsec interface configuration. + +**R1** + +```none +set interfaces macsec macsec1 address '192.0.2.1/24' +set interfaces macsec macsec1 address '2001:db8::1/64' +set interfaces macsec macsec1 security cipher 'gcm-aes-128' +set interfaces macsec macsec1 security encrypt +set interfaces macsec macsec1 security static key 'ddd6f4a7be4d8bbaf88b26f10e1c05f7' +set interfaces macsec macsec1 security static peer R2 mac 00:11:22:33:44:02 +set interfaces macsec macsec1 security static peer R2 key 'eadcc0aa9cf203f3ce651b332bd6e6c7' +set interfaces macsec macsec1 source-interface 'eth1' +``` + +**R2** + +```none +set interfaces macsec macsec1 address '192.0.2.2/24' +set interfaces macsec macsec1 address '2001:db8::2/64' +set interfaces macsec macsec1 security cipher 'gcm-aes-128' +set interfaces macsec macsec1 security encrypt +set interfaces macsec macsec1 security static key 'eadcc0aa9cf203f3ce651b332bd6e6c7' +set interfaces macsec macsec1 security static peer R1 mac 00:11:22:33:44:01 +set interfaces macsec macsec1 security static peer R1 key 'ddd6f4a7be4d8bbaf88b26f10e1c05f7' +set interfaces macsec macsec1 source-interface 'eth1' +``` + +## MACsec over WAN + +MACsec offers an alternative to traditional tunneling solutions by securing +Layer 2 with integrity, origin authentication, and optional encryption. + +While typically deployed between hosts and access switches, MACsec can also +secure traffic over a WAN. In the following example, we combine VXLAN (for +transport) and MACsec (for security) to create a secure tunnel between two +sites. + +**R1 MACsec01** + +```none +set interfaces macsec macsec1 address '192.0.2.1/24' +set interfaces macsec macsec1 address '2001:db8::1/64' +set interfaces macsec macsec1 security cipher 'gcm-aes-128' +set interfaces macsec macsec1 security encrypt +set interfaces macsec macsec1 security static key 'ddd6f4a7be4d8bbaf88b26f10e1c05f7' +set interfaces macsec macsec1 security static peer SEC02 key 'eadcc0aa9cf203f3ce651b332bd6e6c7' +set interfaces macsec macsec1 security static peer SEC02 mac '00:11:22:33:44:02' +set interfaces macsec macsec1 source-interface 'vxlan1' +set interfaces vxlan vxlan1 mac '00:11:22:33:44:01' +set interfaces vxlan vxlan1 remote '10.1.3.3' +set interfaces vxlan vxlan1 source-address '172.16.100.1' +set interfaces vxlan vxlan1 vni '10' +set protocols static route 10.1.3.3/32 next-hop 172.16.100.2 +``` + +**R2 MACsec02** + +```none +set interfaces macsec macsec1 address '192.0.2.2/24' +set interfaces macsec macsec1 address '2001:db8::2/64' +set interfaces macsec macsec1 security cipher 'gcm-aes-128' +set interfaces macsec macsec1 security encrypt +set interfaces macsec macsec1 security static key 'eadcc0aa9cf203f3ce651b332bd6e6c7' +set interfaces macsec macsec1 security static peer SEC01 key 'ddd6f4a7be4d8bbaf88b26f10e1c05f7' +set interfaces macsec macsec1 security static peer SEC01 mac '00:11:22:33:44:01' +set interfaces macsec macsec1 source-interface 'vxlan1' +set interfaces vxlan vxlan1 mac '00:11:22:33:44:02' +set interfaces vxlan vxlan1 remote '10.1.2.2' +set interfaces vxlan vxlan1 source-address '172.16.100.2' +set interfaces vxlan vxlan1 vni '10' +set protocols static route 10.1.2.2/32 next-hop 172.16.100.1 +``` diff --git a/docs/configuration/interfaces/openvpn-examples.md b/docs/configuration/interfaces/openvpn-examples.md new file mode 100644 index 00000000..817e6868 --- /dev/null +++ b/docs/configuration/interfaces/openvpn-examples.md @@ -0,0 +1,769 @@ +# Site-to-site + +:::{todo} +Convert raw command blocks in this file to cfgcmd/opcmd directives for command coverage tracking. +::: + +OpenVPN is popular for client-server setups, but its site-to-site mode is less common and often not supported by router appliances. Despite limited support, it is effective for quickly establishing tunnels between routers. + +As of VyOS 1.4, OpenVPN site-to-site mode can use either pre-shared keys or x.509 certificates. + +Pre-shared key mode is now deprecated and will be removed from future OpenVPN versions. VyOS will also discontinue support for this option because pre-shared keys are significantly less secure than TLS. + +We will configure OpenVPN with self-signed certificates, and then discuss the legacy pre-shared key mode. + +In both cases, we will use the following settings: + +- The public IP address of the local VPN endpoint is 198.51.100.10. +- The public IP address of the remote VPN endpoint is 203.0.113.11. +- The tunnel uses 10.255.1.1 for the local IP address and 10.255.1.2 for the remote IP address. +- The local site has a subnet of 10.0.0.0/16. +- The remote site has a subnet of 10.1.0.0/16. +- The official OpenVPN port 1194 is reserved for client VPN. For site-to-site VPN, port 1195 is used. +- The `persistent-tunnel` directive allows us to configure tunnel-related attributes, such as firewall policy, as we would on any standard network interface. +- If known, the remote router\'s IP address can be configured using the `remote-host` directive. If unknown, it can be omitted. We assume the remote router has a dynamic IP address. + + + +## Set up site-to-site certificates + +Deploying a complete Public Key Infrastructure (PKI) with a Certificate Authority (CA) would overcomplicate site-to-site OpenVPN setups, which are primarily designed for simplicity. To keep their configuration simple without compromising security, VyOS 1.4 and later lets you verify self-signed certificates using certificate fingerprints. + +Generate a self-signed certificate on each router, preferably using the Elliptic Curve (EC) type. In configuration mode, run the following command: `run generate pki certificate self-signed install <name>`. This adds the certificate to the configuration session\'s `pki` subtree. Review and commit the changes. + +``` none +vyos@vyos# run generate pki certificate self-signed install openvpn-local +Enter private key type: [rsa, dsa, ec] (Default: rsa) ec +Enter private key bits: (Default: 256) +Enter country code: (Default: GB) +Enter state: (Default: Some-State) +Enter locality: (Default: Some-City) +Enter organization name: (Default: VyOS) +Enter common name: (Default: vyos.io) +Do you want to configure Subject Alternative Names? [y/N] +Enter how many days certificate will be valid: (Default: 365) +Enter certificate type: (client, server) (Default: server) +Note: If you plan to use the generated key on this router, do not encrypt the private key. +Do you want to encrypt the private key with a passphrase? [y/N] +2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. +[edit] + +vyos@vyos# compare +[pki] ++ certificate openvpn-local { ++ certificate "MIICJTCCAcugAwIBAgIUMXLfRNJ5iOjk/uAZqUe4phW8MdgwCgYIKoZIzj0EAwIwVzELMAkGA1UEBhMCR0IxEzARBgNVBAgMClNvbWUtU3RhdGUxEjAQBgNVBAcMCVNvbWUtQ2l0eTENMAsGA1UECgwEVnlPUzEQMA4GA1UEAwwHdnlvcy5pbzAeFw0yMzA5MDcyMTQzMTNaFw0yNDA5MDYyMTQzMTNaMFcxCzAJBgNVBAYTAkdCMRMwEQYDVQQIDApTb21lLVN0YXRlMRIwEAYDVQQHDAlTb21lLUNpdHkxDTALBgNVBAoMBFZ5T1MxEDAOBgNVBAMMB3Z5b3MuaW8wWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAASp7D0vE3SKSAWAzr/lw9Eq9Q89r247AJR6ec/GT26AIcVA1bsongV1YaWvRwzTPC/yi5pkzV/PcT/WU7JQIyMWo3UwczAMBgNVHRMBAf8EAjAAMA4GA1UdDwEB/wQEAwIHgDATBgNVHSUEDDAKBggrBgEFBQcDATAdBgNVHQ4EFgQUBrAxRdFppdG/UBRdo7qNyHutaTQwHwYDVR0jBBgwFoAUBrAxRdFppdG/UBRdo7qNyHutaTQwCgYIKoZIzj0EAwIDSAAwRQIhAI2+8C92z9wTcTWkQ/goRxs10EBC+h78O+vgo9k97z5iAiBSeqfaVr5taQTS31+McGTAK3cYWNTg0DlOBI8aKO2oRg==" ++ private { ++ key "MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQgtOeEb0dMb5P/2Exi09WWvk6Cvz0oOBoDuP68ZimS2LShRANCAASp7D0vE3SKSAWAzr/lw9Eq9Q89r247AJR6ec/GT26AIcVA1bsongV1YaWvRwzTPC/yi5pkzV/PcT/WU7JQIyMW" ++ } ++ } + +[edit] + +vyos@vyos# commit +``` + +You do **not** need to copy the certificate to the other router. Instead, retrieve its SHA-256 fingerprint. Since OpenVPN currently supports only SHA-256 fingerprints, use the following command: + +``` none +vyos@vyos# run show pki certificate openvpn-local fingerprint sha256 +5C:B8:09:64:8B:59:51:DC:F4:DF:2C:12:5C:B7:03:D1:68:94:D7:5B:62:C2:E1:83:79:F1:F0:68:B2:81:26:79 +``` + +::::{note} +Certificate names are arbitrary. While `openvpn-local` and `openvpn-remote` are used here, you may choose any names. +:::: + +Repeat the procedure on the other router. + +## Set up site-to-site OpenVPN + +Local configuration: + +``` none +Configure the tunnel: + +set interfaces openvpn vtun1 mode site-to-site +set interfaces openvpn vtun1 protocol udp +set interfaces openvpn vtun1 persistent-tunnel +set interfaces openvpn vtun1 remote-host '203.0.113.11' # Public IP of the other side +set interfaces openvpn vtun1 local-port '1195' +set interfaces openvpn vtun1 remote-port '1195' +set interfaces openvpn vtun1 local-address '10.255.1.1' # Local IP of vtun interface +set interfaces openvpn vtun1 remote-address '10.255.1.2' # Remote IP of vtun interface +set interfaces openvpn vtun1 tls certificate 'openvpn-local' # The self-signed certificate +set interfaces openvpn vtun1 tls peer-fingerprint <remote cert fingerprint> # The output of 'run show pki certificate <name> fingerprint sha256' on the remote router +set interfaces openvpn vtun1 tls role active +``` + +Remote configuration: + +``` none +set interfaces openvpn vtun1 mode site-to-site +set interfaces openvpn vtun1 protocol udp +set interfaces openvpn vtun1 persistent-tunnel +set interfaces openvpn vtun1 remote-host '198.51.100.10' # Pub IP of other site +set interfaces openvpn vtun1 local-port '1195' +set interfaces openvpn vtun1 remote-port '1195' +set interfaces openvpn vtun1 local-address '10.255.1.2' # Local IP of vtun interface +set interfaces openvpn vtun1 remote-address '10.255.1.1' # Remote IP of vtun interface +set interfaces openvpn vtun1 tls certificate 'openvpn-remote' # The self-signed certificate +set interfaces openvpn vtun1 tls peer-fingerprint <local cert fingerprint> # The output of 'run show pki certificate <name> fingerprint sha256 on the local router +set interfaces openvpn vtun1 tls role passive +``` + + +## Set up pre-shared keys + +Before VyOS 1.4, site-to-site OpenVPN without PKI required pre-shared keys. This option is still available but is deprecated and will be removed in future releases. If you need to set up a tunnel to an older VyOS version or a system with older OpenVPN, you still need to use pre-shared keys. + +First, generate a key by running `run generate pki openvpn shared-secret install <name>` in configuration mode. You can use any name; in this example, we use `s2s`. + +``` none +vyos@local# run generate pki openvpn shared-secret install s2s +2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. +[edit] +vyos@local# compare +[pki openvpn shared-secret] ++ s2s { ++ key "7c73046a9da91e874d31c7ad894a32688cda054bde157c64270f28eceebc0bb2f44dbb70335fad45148b0456aaa78cb34a34c0958eeed4f75e75fd99ff519ef940f7029a316c436d2366a2b0fb8ea1d1c792a65f67d10a461af83ef4530adc25d1c872de6d9c7d5f338223d1f3b66dc3311bbbddc0e05228c47b91c817c721aadc7ed18f0662df52ad14f898904372679e3d9697d062b0869d12de47ceb2e626fa12e1926a3119be37dd29c9b0ad81997230f4038926900d5edb78522d2940cfe207f8e2b948e0d459fa137ebb18064ac5982b28dd1899020b4f2b082a20d5d4eb65710fbb1e62b5e061df39620267eab429d3eedd9a1ae85957457c8e4655f3" ++ version "1" ++ } + +[edit] + +vyos@local# commit +[edit] +``` + +Next, install the key on the remote router: + +``` none +vyos@remote# set pki openvpn shared-secret s2s key <generated key string> +``` + +Finally, configure the key in your OpenVPN interface settings: + +``` none +set interfaces openvpn vtun1 shared-secret-key s2s +``` + + +## Set up firewall exceptions + +To allow OpenVPN traffic to pass through the WAN interface, create a firewall exception: + +``` none +set firewall ipv4 name OUTSIDE_LOCAL rule 10 action 'accept' +set firewall ipv4 name OUTSIDE_LOCAL rule 10 description 'Allow established/related' +set firewall ipv4 name OUTSIDE_LOCAL rule 10 state 'established' +set firewall ipv4 name OUTSIDE_LOCAL rule 10 state 'related' +set firewall ipv4 name OUTSIDE_LOCAL rule 20 action 'accept' +set firewall ipv4 name OUTSIDE_LOCAL rule 20 description 'OpenVPN_IN' +set firewall ipv4 name OUTSIDE_LOCAL rule 20 destination port '1195' +set firewall ipv4 name OUTSIDE_LOCAL rule 20 log +set firewall ipv4 name OUTSIDE_LOCAL rule 20 protocol 'udp' +``` + +Apply the OUTSIDE_LOCAL firewall group to the WAN interface and to the input filter for traffic destined for the router itself: + +``` none +set firewall ipv4 input filter rule 10 action 'jump' +set firewall ipv4 input filter rule 10 inbound-interface name eth0 +set firewall ipv4 input filter rule 10 jump-target OUTSIDE_LOCAL +``` + +Static routing: + +Configure static routes by referencing the tunnel interface. For example, if the local router\'s network is `10.0.0.0/16` and the remote router\'s network is `10.1.0.0/16`, define the routes as follows: + +Local configuration: + +``` none +set protocols static route 10.1.0.0/16 interface vtun1 +``` + +Remote configuration: + +``` none +set protocols static route 10.0.0.0/16 interface vtun1 +``` + +As with standard Ethernet interfaces, you can apply firewall policies to the tunnel interface for input, output, and forward directions. + +If you use multiple tunnels, OpenVPN must distinguish between them beyond just the pre-shared key. To achieve this, assign either unique IP addresses or unique ports to each tunnel. + +Verify OpenVPN status using the show openvpn operational commands. + +``` none +vyos@vyos:~$ show openvpn site-to-site + +OpenVPN status on vtun1 + +Client CN Remote Host Tunnel IP Local Host TX bytes RX bytes Connected Since +----------- ----------------- ----------- ------------ ---------- ---------- ----------------- +N/A 10.110.12.54:1195 N/A N/A 504.0 B 656.0 B N/A +``` + + +### Server-client + +In OpenVPN's server-client mode, the server acts as a central hub, allowing multiple clients to connect and securely route their traffic or access a private network. Multi-client server is the most popular OpenVPN mode for routers. + +## Set up server-client certificates + +Server-client mode always uses x.509 authentication and therefore requires a PKI setup. The PKI utility now simplifies the creation of Certificate Authorities (CAs), server and client certificates, and Diffie-Hellman keys directly in VyOS using configuration or operational mode commands. + +On the server, generate all certificates by running the following commands in configuration mode. The certificates will be added to the configuration session\'s PKI subtree. + +Certificate Authority (CA): + +``` none +vyos@vyos# run generate pki ca install ca-1 +Enter private key type: [rsa, dsa, ec] (Default: rsa) +Enter private key bits: (Default: 2048) +Enter country code: (Default: GB) +Enter state: (Default: Some-State) +Enter locality: (Default: Some-City) +Enter organization name: (Default: VyOS) +Enter common name: (Default: vyos.io) ca-1 +Enter how many days certificate will be valid: (Default: 1825) +Note: If you plan to use the generated key on this router, do not encrypt the private key. +Do you want to encrypt the private key with a passphrase? [y/N] +2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. +[edit] +vyos@vyos# compare +[pki] ++ ca ca-1 { ++ certificate "MIIDlzCCAn+gAwIBAgIUQW7AtPu0Qzp7VzT0TyYx83/ME8swDQYJKoZIhvcNAQELBQAwVDELMAkGA1UEBhMCR0IxEzARBgNVBAgMClNvbWUtU3RhdGUxEjAQBgNVBAcMCVNvbWUtQ2l0eTENMAsGA1UECgwEVnlPUzENMAsGA1UEAwwEY2EtMTAeFw0yNTA2MTExMTIyMjJaFw0zMDA2MTAxMTIyMjJaMFQxCzAJBgNVBAYTAkdCMRMwEQYDVQQIDApTb21lLVN0YXRlMRIwEAYDVQQHDAlTb21lLUNpdHkxDTALBgNVBAoMBFZ5T1MxDTALBgNVBAMMBGNhLTEwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDi+v6i241T9ABxq1ngjWxDQITkqjV0nq2Jb3HSSuQpXRCu7DWdQZlbvnMHnkV/WTL0RNgkhS4iV/WYhE+bLihwiZ0GTeQnUd1QJSkusFROX46w6kKXYUR5IQtcBC+vdky8PESynPd+DXsJn5X9JTWqDeviUAQz/ZjDzWk+71MBCqa+Zps1zpIjK0ywn7pR/HnDrxJOQXlBMNgvbv8U3IAZ2jJp0jTB8TnuDtWSA+XZejMm/EN/AWUQyliX6OJFSCIhBL2BZ9lmVms4/HkRpbd50k3vvCoz+lAOEE6VsH0fEdLC3lZ+CtXZ7kjp2wdWWuSs5ggIJYZZkixsCisbtEmbAgMBAAGjYTBfMA8GA1UdEwEB/wQFMAMBAf8wDgYDVR0PAQH/BAQDAgGGMB0GA1UdJQQWMBQGCCsGAQUFBwMCBggrBgEFBQcDATAdBgNVHQ4EFgQUAG9lvr7AzJ/y4vY/XlWxXru+6m0wDQYJKoZIhvcNAQELBQADggEBAKsu4eZa8Fha9aKfuKqlGQHPpEFfVDaVJmebw0uMw+b5Y8EpBxzZrgbqbk3Mty8pBjNa9jkZzph04gHN4pR6kg3iQlUKGxZUfsB9ZUjKhkgNdUI9zq1323MKEvuIuYdt61DCfBHwY6Xax5Ge+BahR2bXdPaQH452/+xMTqkukkpLbioTeIDg6FCU2HYPY5emDF5DDZAZWXtTqi0zdT3Y6FqiTvs5VuWwXCcp+HM+Lwe1/VVJhwi4CHTq0CKWnQIH5blYjmyxzRBlrlZm4ntWlL5Mtepa1A3DJirY4kw/SqMAAh/Q9lh41JzBc8epf+OdnOzK55YmtmctGO2o+NBCFi0=" ++ private { ++ key "MIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQDi+v6i241T9ABxq1ngjWxDQITkqjV0nq2Jb3HSSuQpXRCu7DWdQZlbvnMHnkV/WTL0RNgkhS4iV/WYhE+bLihwiZ0GTeQnUd1QJSkusFROX46w6kKXYUR5IQtcBC+vdky8PESynPd+DXsJn5X9JTWqDeviUAQz/ZjDzWk+71MBCqa+Zps1zpIjK0ywn7pR/HnDrxJOQXlBMNgvbv8U3IAZ2jJp0jTB8TnuDtWSA+XZejMm/EN/AWUQyliX6OJFSCIhBL2BZ9lmVms4/HkRpbd50k3vvCoz+lAOEE6VsH0fEdLC3lZ+CtXZ7kjp2wdWWuSs5ggIJYZZkixsCisbtEmbAgMBAAECggEAZdykF6wV8Z4n8NsoG4j8E/ZJbWEhWjO3x1y3JNutJw735LhmmysMSsreToXtxGfgYRTgNwt5l7oHoqmGHCsLxO1NBb5A7JBllIkIwUYqn31syOJofg0NsJpuwZ2zVLfvWe5mGg4tV2lvVPNEWXWwbp+Ow2KLcFWXkA+H8tFuW6F2mH3ntYlIi/WiCNjsEotNx8Kk7OVwt43DbkN/rbF5lxquuLedaSspOHuhIAOfZB5ZySfqohQalSAaguVD66rGPMrerZ2Vc7B1iJ6Mn/KZrSaQeHwyWrwDDHdzVwG9waydevtGTVO0dvH4etWnRypDx8p1FPJJKD4XVcsl3rR6oQKBgQD497Ep2RJcbNnKVj+kNXGriSGmyRSp6CL61KotepzgucK0RtGMeFJge56/otMHMAxIOcDMX6vRn2MB2pqVqwqUBQy6JfLrSemdpIjMN9xlX6Dw3BWP39SdewZ896/Eo0Q1ythMj1ORp+u3PqOlSa14Cy9aPwDWmNy2deD68YDnsQKBgQDpZE/T84BMQ0FzL6NRijZRzR6Dc775hRfmmSTYI0KqpG0gXNSc5UgrWSLN5H7fnx36mT01P7UkgXCInV0AlJOfkt4a8QTqM1Fh/rZbLLWpQE55S6Fs28GDiFYl2kvZT/TtxhA/E0POf/YXl/8KITS7ZVAZxE8rxBe1hVUfDbnlCwKBgQDeWUguGaGeTdCMNk8MNnbYPdaCAB+mRp3G6ls51sF4qi5Lltva2jKn3H/AoohZaP3vGzUm0WLACdsAct2QQXtnCsN9FBtJK2+qzKEn0dPR7X/s3IGdRse6BX+b6BFgSnfGmuxmI7L86L1JoHXCTnTQOx0FOjNjdI3ZnplZRIpdYQKBgFJacASU9l9yl+SiGZnLEDG7FBpEPE3lVbKrtSGDB6IY1NzHhMo76URKdop6Jv6XMcfcTIm+ihdwiRnblRaAVrrG4xJUm2xcYUoXy5bOZudq5oXMVxCHVngoImXG6l6q5P0Fl3P6Q0HZSye2HWsgnm/FZwdAisMhtU/61TdY65BTAoGBAM4jKeImiXta5lz1RgNiW/TPhft3UbOLj3TbzchNCNAamqCv4Tmh9YKB2d/mz2hNxbnAGe2cYn4iRYKcjJLMZ0UfBL2WxlrgQYQPPGzSD0fH1pLIXPohpBZpsGqNR3Nc8Jd+Uw3IiIJ2oxPCOPTOJsklNB0Xf1AlUUagB16bhhZZ" ++ } ++ } + +[edit] +vyos@vyos# commit +``` + +Server certificate: + +``` none +vyos@vyos# run generate pki certificate sign ca-1 install srv-1 +Do you already have a certificate request? [y/N] N +Enter private key type: [rsa, dsa, ec] (Default: rsa) +Enter private key bits: (Default: 2048) +Enter country code: (Default: GB) +Enter state: (Default: Some-State) +Enter locality: (Default: Some-City) +Enter organization name: (Default: VyOS) +Enter common name: (Default: vyos.io) srv-1 +Do you want to configure Subject Alternative Names? [y/N] +Enter how many days certificate will be valid: (Default: 365) +Enter certificate type: (client, server) (Default: server) server +Note: If you plan to use the generated key on this router, do not encrypt the private key. +Do you want to encrypt the private key with a passphrase? [y/N] +2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. +[edit] +vyos@vyos# compare +[pki certificate] ++ srv-1 { ++ certificate "MIIDrDCCApSgAwIBAgIULpu+qZjfG01kUI58XNmqXbQC3qQwDQYJKoZIhvcNAQELBQAwVDELMAkGA1UEBhMCR0IxEzARBgNVBAgMClNvbWUtU3RhdGUxEjAQBgNVBAcMCVNvbWUtQ2l0eTENMAsGA1UECgwEVnlPUzENMAsGA1UEAwwEY2EtMTAeFw0yNTA2MTExMTMxMDJaFw0yNjA2MTExMTMxMDJaMFUxCzAJBgNVBAYTAkdCMRMwEQYDVQQIDApTb21lLVN0YXRlMRIwEAYDVQQHDAlTb21lLUNpdHkxDTALBgNVBAoMBFZ5T1MxDjAMBgNVBAMMBXNydi0xMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAysTrMfVH63aVidJT7bIf+zLwkLse07nGsv4aliGEbufr239RBHV4Jn8LbQ+nB/8mhYGjNY4OnZ7NYz3FU/iglo8qFtaZ26mWtPWpv2xW1F8JAEK7l5BAg42cBucxiIZFeRm+jkE6VN1bcNU0utnn3sbCwZMyH6pS9k08G1qrrFLA7ZFhv5AmgJcODmO8sigSAu7rRS/6O3eO6ICnVjvIfHLb+9DKKUEffHzFV8RrkqVCGmgisz9fF+j1Rvg9s+ylNc2lZJTbb1XnzixvSRro4t9I3uIWdpJ0iOu09YiTXGQgH9ER6V3rFiX00RdSiSXf+MJCV64hC1msg+8V3Nrw9QIDAQABo3UwczAMBgNVHRMBAf8EAjAAMA4GA1UdDwEB/wQEAwIHgDATBgNVHSUEDDAKBggrBgEFBQcDATAdBgNVHQ4EFgQUzH0h4vBxma89HF9rUQ+DW052c5swHwYDVR0jBBgwFoAUAG9lvr7AzJ/y4vY/XlWxXru+6m0wDQYJKoZIhvcNAQELBQADggEBAI/Cyd0y7AJ7wY3yRssCud2iJAl9/ZjgxzXOUo6ibawYIYOnSf9tS3eD4CIH4BgppDXoJZ/qEA4WvIsLx3yvnyOxiqyk3TQmKIZ27VJH+yQkgzPeiKrHn1pCXBKEb1/jlT8Ozu4Lmn/oFwDH6nk8toxI8DM+qsTxqUFlTA3ea9yaRtxeNPMWJdaxZSUYGVSZL0wVKw5ZuQ1Gn7vGVApWlYDKYbMozCuZUG1q8wMzFBRa7x0anvh5hM4bksLz+Y1ujCS8f8b4Xtb8KIdFrZtTvtl97crv62bN05VueAcbwtYbIBNWNoT/CvmqV7k3uPg95GYSNddFqEMbQHoyd8hdDCo=" ++ private { ++ key "MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQDKxOsx9UfrdpWJ0lPtsh/7MvCQux7Tucay/hqWIYRu5+vbf1EEdXgmfwttD6cH/yaFgaM1jg6dns1jPcVT+KCWjyoW1pnbqZa09am/bFbUXwkAQruXkECDjZwG5zGIhkV5Gb6OQTpU3Vtw1TS62efexsLBkzIfqlL2TTwbWqusUsDtkWG/kCaAlw4OY7yyKBIC7utFL/o7d47ogKdWO8h8ctv70MopQR98fMVXxGuSpUIaaCKzP18X6PVG+D2z7KU1zaVklNtvVefOLG9JGuji30je4hZ2knSI67T1iJNcZCAf0RHpXesWJfTRF1KJJd/4wkJXriELWayD7xXc2vD1AgMBAAECggEACsUk3PVzSX11+ekTDigM7NHK11UpEQPoGu/GR70mBKIK9BCyI/N9W0YaPEO9kn4p9KNrINgXzKV3sVLBnXEyTmzyRl5Fs9YxLBF0X7eIcSVPHBVvU2CVHKez5uX2ypKfNAx7A6FRUNqlFbwtXdNfLoUOKSwBWI86ctytWaKaRb/TTSGQkaP/z/cwIsXOLfG9m6iFkw98ShUzalrUWNo/4fJKlO1+DvXVYE9sv9rjD8J7DtAbr5KykQ5n0AAlZTCWQ7jwMybSnjjY9ypZUms0l17raJrfhrdbWayc6xMDvtrmNIDebkF+J7cHU06aEV+yQXV/7yjyZgUSM2ANcHMdzQKBgQDmTi5tUeaj1JUSl9lAP/XUzcElw2tcU1B8qpX69J4ofjTNgj5okLWQZVIy1UyAfLOI3LJbHTBUtSvedhH0VaMulq99NXs5qnbPGG3//RBAc0wKhJknB5Qv0D3FxMI14kMO6jzPly+aIGEk4dTtHvZuHbbVHbKSZ5MMouLyT+SS7wKBgQDhZETARZ0MazeWRaPJwdkjlfNcqqcsnDicdcppCkcDCjeLxkVPZc8ej37rshOvw2Pf1D0PddGyOhJoWCWA8QE2LQoDHLaDnQ0L6aQ3yjN5Gxx9RCDFi3Zuat/mPcv3tFO7uUmeYvRC5fGYrghq29NADmUefOopAc06Izd4A3iqWwKBgQC1uPrpR7a1jwgRo7/I8q8HO1MseQY903+u3ut5GYuyZ+NCRYL4/zZEua4ibivvNnZzh7E0M9PvAwWag4+nO+uG11+hbJHO7rLQtnYVh5lLQa6+neI66cAD+kzDwH1+BwriufFB3Amzk9kTQR7B+6x3NvsNLmG5JADj96Mbj+7MAQKBgFIevEXplyzdK6WevexWqoyip8aNjtdcG+w1pofa7MCYymAs3zfseihCVBYADdguModsxsqJPNvY+Lf31cJDDRP2GP3FSmJtqEE84U5KZ7KqRBkH54DSLVZRrj4vKc+YbiGpgr8ogqKVMQ9V6U81xKREGmefT5mdRG74Qc+CREadAoGAFtdsH5js1yFEeGFad4BZJ69grEavD3pNCfIe9oIPtXvvFdzxd+QbKgqFf3JMJp/HYi8A0iv/i4mzf00KXzF4JU7bIJYrUVlk/w8x77gzDRIphsPqpMBJkTI0jisQHZKWNEe7IbmM/dWW2S4jvCkrhB7F5Szf72Q+j/lPbfx2g/8=" ++ } ++ } + +[edit] +vyos@vyos# commit +``` + +Diffie-Hellman key: + +``` none +vyos@vyos# run generate pki dh install dh-1 +Enter DH parameters key size: (Default: 2048) +Generating parameters... +1 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. +[edit] +vyos@vyos# compare +[pki] ++ dh dh-1 { ++ parameters "MIIBCAKCAQEAp25kxwZeLZ7wcbRii5E5RD4uWCUOBxarzKEE0msa84omh5nZ9dv/4bfJw4gIXlA2+sGc2lLV/jajZminMryiSwJdisyVuUdOB7sJWZwrzHBAY0qFbNyaRMVJBar2xVm+XcKd3A2eNTEgn10G7rPPvf6CJ5isUKFaKT8ymUv+mI0upLneYdGs8/yS3sAojzeulCf49fa5SiaGCcZZkdOI3Nby1u/ZG4okqJ2wE2c2hRVLs1k5qrrono0OF4Dh0B91ihnywRfp1xPYeqpiln+OPh+PPgTuBxkz4VxwRDoQ+NhVr/LOCb3vbhnyFisxI0w4r3109cA3QiDmo1L14aKl1wIBAg==" ++ } + +[edit] +vyos@vyos# commit +``` + +Client certificate: + +``` none +vyos@vyos:~$ generate pki certificate sign ca-1 install client1 +Do you already have a certificate request? [y/N] N +Enter private key type: [rsa, dsa, ec] (Default: rsa) +Enter private key bits: (Default: 2048) +Enter country code: (Default: GB) +Enter state: (Default: Some-State) +Enter locality: (Default: Some-City) +Enter organization name: (Default: VyOS) +Enter common name: (Default: vyos.io) client1 +Do you want to configure Subject Alternative Names? [y/N] +Enter how many days certificate will be valid: (Default: 365) +Enter certificate type: (client, server) (Default: server) client +Note: If you plan to use the generated key on this router, do not encrypt the private key. +Do you want to encrypt the private key with a passphrase? [y/N] +You are not in configure mode, commands to install manually from configure mode: +set pki certificate client1 certificate 'MIIDrjCCApagAwIBAgIUPvtffeYTdoOiHxu++wdrjHwwVX4wDQYJKoZIhvcNAQELBQAwVDELMAkGA1UEBhMCR0IxEzARBgNVBAgMClNvbWUtU3RhdGUxEjAQBgNVBAcMCVNvbWUtQ2l0eTENMAsGA1UECgwEVnlPUzENMAsGA1UEAwwEY2EtMTAeFw0yNTA2MTExMTQxMDlaFw0yNjA2MTExMTQxMDlaMFcxCzAJBgNVBAYTAkdCMRMwEQYDVQQIDApTb21lLVN0YXRlMRIwEAYDVQQHDAlTb21lLUNpdHkxDTALBgNVBAoMBFZ5T1MxEDAOBgNVBAMMB2NsaWVudDEwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQC9H6E6gm0PfXO1n/WoA9xlg89/bnScLmfztVDn1uyNn8epE6zAi2GWBhtj4ixLllIwLdkJ7L2mF3yUZtA1Q0oYbGIqTbnaZ37JydCygVGnlLT7UX9zfRfS3KebCIvIte7OyCmnUfVfFzdIsp+4LI3S2wX/9Vyn4UBAR8QQNbezRB3XPMk9gzULnuLhmEDP6GVcPq7RzGXoXUMqsCxfEOJBjej0y4ANKH07HGVVrfVRiY+zlGkM4TFjVuZKnEA0BO6dhOA0E+7gsIXsC06UzzatkjsyWHpb2/DOECIifBoYej9DITu8VxyyZmgaINHEn2gGb0LRHO7rvQapc+XZ2z9DAgMBAAGjdTBzMAwGA1UdEwEB/wQCMAAwDgYDVR0PAQH/BAQDAgeAMBMGA1UdJQQMMAoGCCsGAQUFBwMCMB0GA1UdDgQWBBQnUyqEzG+AqZzsdSud5MDqsOxiXTAfBgNVHSMEGDAWgBQAb2W+vsDMn/Li9j9eVbFeu77qbTANBgkqhkiG9w0BAQsFAAOCAQEAplItvZpoX/joG3QREu9tHVKwDTmXB2lwUM5G8iKPgd6D6oOILZMe2KuvWt12dcdEzUCGfJwJJ8M8R2WD0OmcLdFqvM/8UM1hYzUP2BCnFCLtElVD+b4wMlQNpdHqNbdckw8J4MLQlhUgu9rZAZ0XjWCprr+U50bX++vYRw7Un3Ds6ETEvjflm5WAPb2e0V1hhISPl8K+VXO7RAwxy0DHcDuR+YaD+hnNgMsJV3/QwA17Iy8x86RpOgqmesbt0U7e9Rmo81aVgiy/V4OCV7u6bPX03fmZNS8UwwJuRUlxkjO+epHNYB2cnOcjSkUxaIJ9Hv3tMWHQEtbVZsNYSOZozw==' +set pki certificate client1 private key 'MIIEvAIBADANBgkqhkiG9w0BAQEFAASCBKYwggSiAgEAAoIBAQC9H6E6gm0PfXO1n/WoA9xlg89/bnScLmfztVDn1uyNn8epE6zAi2GWBhtj4ixLllIwLdkJ7L2mF3yUZtA1Q0oYbGIqTbnaZ37JydCygVGnlLT7UX9zfRfS3KebCIvIte7OyCmnUfVfFzdIsp+4LI3S2wX/9Vyn4UBAR8QQNbezRB3XPMk9gzULnuLhmEDP6GVcPq7RzGXoXUMqsCxfEOJBjej0y4ANKH07HGVVrfVRiY+zlGkM4TFjVuZKnEA0BO6dhOA0E+7gsIXsC06UzzatkjsyWHpb2/DOECIifBoYej9DITu8VxyyZmgaINHEn2gGb0LRHO7rvQapc+XZ2z9DAgMBAAECggEAPS/Fhtt5k2BgFivZW3FcVc+OS0keGwV8hkFsGoXTZIKEIzSFWIn/mX0CUY90C0Rn9MRwiqB4PwssOAsHY6QQjdRK8irRbVK8l2ZeydHC7DfVUdXtKR0YnxTaePML3nTV/TqPF14Rx6EINtHrkLeBbu2DhGsKfhoHIoTVbvUiKLHa2TkGJOkhvjsyMSPKzUXa1AzLmu+UBIhRYpEPHj0SQUUJJnKgIb7mTR2fhJScHcKwsrPq6S8OpChvsYZ6zatgrTFz9tuhD4IjL7NBiYP45BwGaLIaQjph8yAJwwHWoOP+TTj5WYflkW6Uu8F9gC0ve6dPGPNEi2TUdirvAe4LYQKBgQD0UfAPm6tQg8pdkvfMBvYc21fk8zqmgcA4OtvDi60aXuv5jI5+faISvOG2JLuFhKIDOb5ZerzGvkN+LvWgzr9H7YdGZNNtwKgpS/MGqcuuHncTxWBAwYgKhf26a/tqFZRNurJ6GowxDiAcQEc1mWnmdngRa+dvvCwNbXvGVqfVEQKBgQDGKi447TqD76QfvRPn/fRSjM+QE1duk+XorEJ0HHIha5HV9kCrZdV/olGRjDLwPJO6JW7iE2FUsS9SsIrccFE/9P2ZUqfYP2wL5vNO5kAmoLLUl0gwqg1WnBTPJfXeKReTj2uGmOdEuuMPXpL/49hDuPViiE2Q4MGe2Z+oEYN/EwKBgHfQMuTEl2e9qaDn8OM6SrluC5V4fjunh6dLnfgwaCx1fk1702lOnQuJWzsiml9o4raoO6PP4AGqzphz2PsKSJ2ya1NnIJRDFXRjDYQoAn2Z7RViBsja36chfINObxXgDUFtHBdrK3LnFXIlR4aOfHOLh2grvWx7IDNZjIiAeH+xAoGAJlmFZnjqiRv4bDgAQTZRcSRVCvHjSsAOj0++8I+MutEBgSHN9B2aCsBT/tHeDcX7ZNvXsKLFhElh+iO2S+DkqHb2GRT47I2hkFAaqBtBMPiKgz/ftaNDP46nLEuRYHQdXu4zhfHTV+a/CHtqAWGLuddyjaYJNM96SQ6eqjzxcMcCgYAzdxOF2e27hIgo2ttjsROMGqW0/0r/HsKGKPnao7xHQNCAswTnBT+QGugPCe0NXjuxbySP7V1GeWMWF+WV5khtteWerT1/ELAC48NSDpaMxVa4GP8Q/0w6+ZyJty3UGbCYQzZZue81dU+42LUIaVJ4NAc2tYj3jD780udasawS6w==' +``` + +Manually copy the CA, client certificate, and Diffie-Hellman key to the client device, then commit them before configuring the OpenVPN interface. + +For more options, refer to {ref}`configuration/pki/index:pki`. + +## Set up server-client OpenVPN + +The following example demonstrates the most complicated scenario: each client acts as a router with its own subnet (e.g., an HQ and multiple branch offices). Simpler setups are subsets of it. + +In this scenario, the 10.23.1.0/24 network is used for client tunnel endpoints, and all client subnets belong to 10.23.0.0/20. Each client needs access to the 192.168.0.0/16 network. + +Server configuration: + +``` none +set interfaces openvpn vtun10 encryption data-ciphers 'aes256' +set interfaces openvpn vtun10 hash 'sha512' +set interfaces openvpn vtun10 local-host '172.18.201.10' +set interfaces openvpn vtun10 local-port '1194' +set interfaces openvpn vtun10 mode 'server' +set interfaces openvpn vtun10 persistent-tunnel +set interfaces openvpn vtun10 protocol 'udp' +set interfaces openvpn vtun10 server client client1 ip '10.23.1.10' +set interfaces openvpn vtun10 server client client1 subnet '10.23.2.0/25' +set interfaces openvpn vtun10 server domain-name 'vyos.net' +set interfaces openvpn vtun10 server max-connections '250' +set interfaces openvpn vtun10 server name-server '172.16.254.30' +set interfaces openvpn vtun10 server subnet '10.23.1.0/24' +set interfaces openvpn vtun10 server topology 'subnet' +set interfaces openvpn vtun10 tls ca-certificate ca-1 +set interfaces openvpn vtun10 tls certificate srv-1 +set interfaces openvpn vtun10 tls dh-params dh-1 +``` + +The configuration above uses the default 1194/UDP port, 256-bit AES encryption, SHA-512 for HMAC authentication, and the persistent-tunnel option. Persistent-tunnel is recommended as it keeps the TUN/TAP device active during connection resets or daemon reloads. Clients are identified by the CN attribute in their SSL certificates. + +To grant clients access to a specific network behind the router, use the push-route option to automatically install the appropriate route on each client. + +``` none +set interfaces openvpn vtun10 server push-route 192.168.0.0/16 +``` + +OpenVPN does not automatically create kernel routes for client subnets when clients connect; it only uses client-subnet association internally. Therefore, you must manually create a route to the 10.23.0.0/20 network: + +``` none +set protocols static route 10.23.0.0/20 interface vtun10 +``` + + +## Set up OpenVPN client + +VyOS can operate not only as an OpenVPN site-to-site peer or a server for multiple clients, but also as an OpenVPN client. Any VyOS OpenVPN interface can be configured to connect to another VyOS or third-party OpenVPN server. + +Client configuration: + +``` none +set interfaces openvpn vtun10 encryption data-ciphers 'aes256' +set interfaces openvpn vtun10 hash 'sha512' +set interfaces openvpn vtun10 mode 'client' +set interfaces openvpn vtun10 persistent-tunnel +set interfaces openvpn vtun10 protocol 'udp' +set interfaces openvpn vtun10 remote-host '172.18.201.10' +set interfaces openvpn vtun10 remote-port '1194' +set interfaces openvpn vtun10 tls ca-certificate ca-1 +set interfaces openvpn vtun10 tls certificate client1 +``` + + +## Verification + +Check the tunnel status: + +``` none +vyos@vyos:~$ show openvpn server + +OpenVPN status on vtun10 + +Client CN Remote Host Tunnel IP Local Host TX bytes RX bytes Connected Since +----------- ------------------ ----------- ---------------- ---------- ---------- ------------------- +client1 172.16.12.54:33166 10.23.1.10 172.18.201.10:1194 3.4 KB 3.4 KB 2024-06-11 12:07:25 +``` + + +### Server bridge + +In Ethernet bridging configurations, an OpenVPN interface operating in server mode with the device type set to TAP can be added to a bridge. By encapsulating entire Ethernet frames (up to 1514 bytes) rather than just IP packets (up to 1500 bytes), this setup enables clients to transmit Layer 2 frames through the OpenVPN tunnel. + +The following is a basic configuration example: + +Server side: + +``` none +set interfaces bridge br10 member interface eth1.10 +set interfaces bridge br10 member interface vtun10 +set interfaces openvpn vtun10 device-type 'tap' +set interfaces openvpn vtun10 encryption data-ciphers 'aes192' +set interfaces openvpn vtun10 hash 'sha256' +set interfaces openvpn vtun10 local-host '172.18.201.10' +set interfaces openvpn vtun10 local-port '1194' +set interfaces openvpn vtun10 mode 'server' +set interfaces openvpn vtun10 server bridge gateway '10.10.0.1' +set interfaces openvpn vtun10 server bridge start '10.10.0.100' +set interfaces openvpn vtun10 server bridge stop '10.10.0.200' +set interfaces openvpn vtun10 server bridge subnet-mask '255.255.255.0' +set interfaces openvpn vtun10 server topology 'subnet' +set interfaces openvpn vtun10 tls ca-certificate 'ca-1' +set interfaces openvpn vtun10 tls certificate 'srv-1' +set interfaces openvpn vtun10 tls dh-params 'dh-1' +``` + +Client side: + +``` none +set interfaces openvpn vtun10 device-type 'tap' +set interfaces openvpn vtun10 encryption data-ciphers 'aes192' +set interfaces openvpn vtun10 hash 'sha256' +set interfaces openvpn vtun10 mode 'client' +set interfaces openvpn vtun10 protocol 'udp' +set interfaces openvpn vtun10 remote-host '172.18.201.10' +set interfaces openvpn vtun10 remote-port '1194' +set interfaces openvpn vtun10 tls ca-certificate 'ca-1' +set interfaces openvpn vtun10 tls certificate 'client-1' +``` + + +### Server LDAP authentication + +## LDAP + +Enterprise installations usually include a directory service to centralize employee password management. VyOS and OpenVPN support using LDAP and Active Directory as a single user backend. + +Authentication is performed by the `openvpn-auth-ldap.so` plugin, included with every VyOS installation. To use it, you must create a dedicated configuration file. +**Best practice:** Store the configuration file in the `/config` directory to ensure it is preserved after image updates. + +``` none +set interfaces openvpn vtun0 openvpn-option "--plugin /usr/lib/openvpn/openvpn-auth-ldap.so /config/auth/ldap-auth.config" +``` + +A sample configuration file is shown below: + +``` none +<LDAP> +# LDAP server URL +URL ldap://ldap.example.com +# Bind DN (If your LDAP server doesn't support anonymous binds) +BindDN cn=LDAPUser,dc=example,dc=com +# Bind Password password +Password S3cr3t +# Network timeout (in seconds) +Timeout 15 +</LDAP> + +<Authorization> +# Base DN +BaseDN "ou=people,dc=example,dc=com" +# User Search Filter +SearchFilter "(&(uid=%u)(objectClass=shadowAccount))" +# Require Group Membership - allow all users +RequireGroup false +</Authorization> +``` + + +### Active Directory + +A sample configuration file is shown below: + +``` none +<LDAP> + # LDAP server URL + URL ldap://dc01.example.com + # Bind DN (If your LDAP server doesn’t support anonymous binds) + BindDN CN=LDAPUser,DC=example,DC=com + # Bind Password + Password mysecretpassword + # Network timeout (in seconds) + Timeout 15 + # Enable Start TLS + TLSEnable no + # Follow LDAP Referrals (anonymously) + FollowReferrals no +</LDAP> + +<Authorization> + # Base DN + BaseDN "DC=example,DC=com" + # User Search Filter, user must be a member of the VPN AD group + SearchFilter "(&(sAMAccountName=%u)(memberOf=CN=VPN,OU=Groups,DC=example,DC=com))" + # Require Group Membership + RequireGroup false # already handled by SearchFilter + <Group> + BaseDN "OU=Groups,DC=example,DC=com" + SearchFilter "(|(cn=VPN))" + MemberAttribute memberOf + </Group> +</Authorization> +``` + +If you only want to check that the user account is enabled and can authenticate (against the primary group), the following snippet is sufficient: + +``` none +<LDAP> + URL ldap://dc01.example.com + BindDN CN=SA_OPENVPN,OU=ServiceAccounts,DC=example,DC=com + Password ThisIsTopSecret + Timeout 15 + TLSEnable no + FollowReferrals no +</LDAP> + +<Authorization> + BaseDN "DC=example,DC=com" + SearchFilter "sAMAccountName=%u" + RequireGroup false +</Authorization> +``` + +A complete example of an LDAP authentication configuration for OpenVPN is shown below: + +``` none +vyos@vyos# show interfaces openvpn + openvpn vtun0 { + mode server + openvpn-option "--tun-mtu 1500 --fragment 1300 --mssfix" + openvpn-option "--plugin /usr/lib/openvpn/openvpn-auth-ldap.so /config/auth/ldap-auth.config" + openvpn-option "--push redirect-gateway" + openvpn-option --duplicate-cn + openvpn-option "--verify-client-cert none" + openvpn-option --comp-lzo + openvpn-option --persist-key + openvpn-option --persist-tun + server { + domain-name example.com + max-connections 5 + name-server 203.0.113.0.10 + name-server 198.51.100.3 + subnet 172.18.100.128/29 + } + tls { + ca-certificate ca.crt + certificate server.crt + dh-params dh1024.pem + } + } +``` + +For a detailed example, refer to {doc}`OpenVPN with LDAP</configexamples/autotest/OpenVPN_with_LDAP/OpenVPN_with_LDAP>`. + +### Multi-factor authentication + +VyOS supports multi-factor authentication (MFA) or two-factor authentication using Time-based One-Time Passwords (TOTP). It is compatible with Google Authenticator and other software tokens. + +## Server side + +``` none +set interfaces openvpn vtun20 encryption cipher 'aes256' +set interfaces openvpn vtun20 hash 'sha512' +set interfaces openvpn vtun20 mode 'server' +set interfaces openvpn vtun20 persistent-tunnel +set interfaces openvpn vtun20 server client user1 +set interfaces openvpn vtun20 server mfa totp challenge 'disable' +set interfaces openvpn vtun20 server subnet '10.10.2.0/24' +set interfaces openvpn vtun20 server topology 'subnet' +set interfaces openvpn vtun20 tls ca-certificate 'openvpn_vtun20' +set interfaces openvpn vtun20 tls certificate 'openvpn_vtun20' +set interfaces openvpn vtun20 tls dh-params 'dh-pem' +``` + +A TOTP secret is created for each client in the OpenVPN server configuration. To display authentication information, use the following command: `show interfaces openvpn vtun20 user user1 mfa qrcode`. + +Example: + +``` none +vyos@vyos:~$ sh interfaces openvpn vtun20 user user1 mfa qrcode +█████████████████████████████████████ +█████████████████████████████████████ +████ ▄▄▄▄▄ █▀▄▀ ▀▀▄▀ ▀▀▄ █ ▄▄▄▄▄ ████ +████ █ █ █▀▀▄ █▀▀▀█▀██ █ █ █ ████ +████ █▄▄▄█ █▀█ ▄ █▀▀ █▄▄▄█ █▄▄▄█ ████ +████▄▄▄▄▄▄▄█▄█ █ █ ▀ █▄▀▄█▄▄▄▄▄▄▄████ +████▄▄ ▄ █▄▄ ▄▀▄█▄ ▄▀▄█ ▄▄▀ ▀▄█ ▀████ +████ ▀██▄▄▄█▄ ██ █▄▄▄▄ █▄▀█ █ █▀█████ +████ ▄█▀▀▄▄ ▄█▀ ▀▄ ▄▄▀▄█▀▀▀ ▄▄▀████ +████▄█ ▀▄▄▄▀ ▀ ▄█ ▄ █▄█▀ █▀ █▀█████ +████▀█▀ ▀ ▄█▀▄▀▀█▄██▄█▀▀ ▀ ▀ ▄█▀████ +████ ██▄▄▀▄▄█ ██ ▀█ ▄█ ▀▄█ █▀██▀████ +████▄███▄█▄█ ▀█▄ ██▄▄▄█▀ ▄▄▄ █ ▀ ████ +████ ▄▄▄▄▄ █▄█▀▄ ▀▄ ▀█▀ █▄█ ██▀█████ +████ █ █ █ ▄█▀█▀▀▄ ▄▀▀▄▄▄▄▄▄ ████ +████ █▄▄▄█ █ ▄ ▀ █▄▄▄██▄▀█▄▀▄█▄ █████ +████▄▄▄▄▄▄▄█▄██▄█▄▄▄▄▄█▄█▄█▄██▄██████ +█████████████████████████████████████ +█████████████████████████████████████ +``` + +Scan the QR code to add the user account to Google Authenticator. On the client side, use the generated OTP as the password. + +### Authentication with username/password + +An OpenVPN server can securely obtain a username and password from a connecting client and use this information for authentication. + +First, configure the server to use an authentication plugin or script. The server calls this plugin every time a client tries to connect, passing it the client\'s credentials. + +In the following example, the `--auth-user-pass-verify` directive is used with the via-env method and a specified script path to validate the client\'s username and password. + +## Server configuration + +``` none +set interfaces openvpn vtun10 local-port '1194' +set interfaces openvpn vtun10 mode 'server' +set interfaces openvpn vtun10 openvpn-option '--auth-user-pass-verify /config/auth/check_user.sh via-env' +set interfaces openvpn vtun10 openvpn-option '--script-security 3' +set interfaces openvpn vtun10 persistent-tunnel +set interfaces openvpn vtun10 protocol 'udp' +set interfaces openvpn vtun10 server client client-1 ip '10.10.10.55' +set interfaces openvpn vtun10 server push-route 192.0.2.0/24 +set interfaces openvpn vtun10 server subnet '10.10.10.0/24' +set interfaces openvpn vtun10 server topology 'subnet' +set interfaces openvpn vtun10 tls ca-certificate 'ca-1' +set interfaces openvpn vtun10 tls certificate 'srv-1' +set interfaces openvpn vtun10 tls dh-params 'dh-1' +``` + +The /config/auth/check_user.sh example includes two test users: + +``` none +#!/bin/bash +USERNAME="$username" +PASSWORD="$password" + +# Replace this with real user checking logic or use getent +if [[ "$USERNAME" == "client1" && "$PASSWORD" == "pass123" ]]; then + exit 0 +elif [[ "$USERNAME" == "peter" && "$PASSWORD" == "qwerty" ]]; then + exit 0 +else + exit 1 +fi +``` + + +## Client configuration + +Storing the client certificate locally lets you generate the OpenVPN client configuration file. Use the following command: + +``` none +vyos@vyos:~$ generate openvpn client-config interface vtun10 ca ca-1 certificate client1 +``` + +Copy the output and save it as a .ovpn file. Add the `auth-user-pass` directive to the file. This instructs the OpenVPN client to prompt the user for a username and password, which are then sent to the server over the TLS channel. You can now import this file into any OpenVPN client application. + +``` none +client +dev tun +proto udp +remote 192.168.77.10 1194 + +remote-cert-tls server +proto udp +dev tun +dev-type tun +persist-key +persist-tun +verb 3 +auth-user-pass + + +<ca> +-----BEGIN CERTIFICATE----- +MIIDlzCCAn+gAwIBAgIUQW7AtPu0Qzp7VzT0TyYx83/ME8swDQYJKoZIhvcNAQEL +BQAwVDELMAkGA1UEBhMCR0IxEzARBgNVBAgMClNvbWUtU3RhdGUxEjAQBgNVBAcM +CVNvbWUtQ2l0eTENMAsGA1UECgwEVnlPUzENMAsGA1UEAwwEY2EtMTAeFw0yNTA2 +MTExMTIyMjJaFw0zMDA2MTAxMTIyMjJaMFQxCzAJBgNVBAYTAkdCMRMwEQYDVQQI +DApTb21lLVN0YXRlMRIwEAYDVQQHDAlTb21lLUNpdHkxDTALBgNVBAoMBFZ5T1Mx +DTALBgNVBAMMBGNhLTEwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDi ++v6i241T9ABxq1ngjWxDQITkqjV0nq2Jb3HSSuQpXRCu7DWdQZlbvnMHnkV/WTL0 +RNgkhS4iV/WYhE+bLihwiZ0GTeQnUd1QJSkusFROX46w6kKXYUR5IQtcBC+vdky8 +PESynPd+DXsJn5X9JTWqDeviUAQz/ZjDzWk+71MBCqa+Zps1zpIjK0ywn7pR/HnD +rxJOQXlBMNgvbv8U3IAZ2jJp0jTB8TnuDtWSA+XZejMm/EN/AWUQyliX6OJFSCIh +BL2BZ9lmVms4/HkRpbd50k3vvCoz+lAOEE6VsH0fEdLC3lZ+CtXZ7kjp2wdWWuSs +5ggIJYZZkixsCisbtEmbAgMBAAGjYTBfMA8GA1UdEwEB/wQFMAMBAf8wDgYDVR0P +AQH/BAQDAgGGMB0GA1UdJQQWMBQGCCsGAQUFBwMCBggrBgEFBQcDATAdBgNVHQ4E +FgQUAG9lvr7AzJ/y4vY/XlWxXru+6m0wDQYJKoZIhvcNAQELBQADggEBAKsu4eZa +8Fha9aKfuKqlGQHPpEFfVDaVJmebw0uMw+b5Y8EpBxzZrgbqbk3Mty8pBjNa9jkZ +zph04gHN4pR6kg3iQlUKGxZUfsB9ZUjKhkgNdUI9zq1323MKEvuIuYdt61DCfBHw +Y6Xax5Ge+BahR2bXdPaQH452/+xMTqkukkpLbioTeIDg6FCU2HYPY5emDF5DDZAZ +WXtTqi0zdT3Y6FqiTvs5VuWwXCcp+HM+Lwe1/VVJhwi4CHTq0CKWnQIH5blYjmyx +zRBlrlZm4ntWlL5Mtepa1A3DJirY4kw/SqMAAh/Q9lh41JzBc8epf+OdnOzK55Ym +tmctGO2o+NBCFi0= +-----END CERTIFICATE----- + +</ca> + +<cert> +-----BEGIN CERTIFICATE----- +MIIDrjCCApagAwIBAgIUN6vPxDEW89cfbEFPa0tZlnsW1GkwDQYJKoZIhvcNAQEL +BQAwVDELMAkGA1UEBhMCR0IxEzARBgNVBAgMClNvbWUtU3RhdGUxEjAQBgNVBAcM +CVNvbWUtQ2l0eTENMAsGA1UECgwEVnlPUzENMAsGA1UEAwwEY2EtMTAeFw0yNTA2 +MTExMTQ0MjlaFw0yNjA2MTExMTQ0MjlaMFcxCzAJBgNVBAYTAkdCMRMwEQYDVQQI +DApTb21lLVN0YXRlMRIwEAYDVQQHDAlTb21lLUNpdHkxDTALBgNVBAoMBFZ5T1Mx +EDAOBgNVBAMMB2NsaWVudDEwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIB +AQCdOWq8vdO8CznGN83uAXCuN4PcdTJaRFEdJIEfqHjlcG0MZQuPIAlDbOU+IWmu +QBmeCj7SlbYtVYo1uQOMUaIrAvxLIQUaL1Y60oLVTF5eAPrGV+NSTQR5uMApcH9/ +RcZcW530pu/QpYinKTbGkEd54so6YRVPmYbIOPNUMbnZbccpinYi5t2dqubBb585 +A7L40043VtsVVbPjQq5V0HDursvqlaMqMRcffhR8H4B4ByU/EPRK4yTKm1hi19v3 +UtRHiq74CfGtJzYtplgrLJBON7TsbIi/fEux4q1yhbKA0S66L6e5DZldRxNZOXG6 +QjEL0RkYloMgkbv/2HLCu09hAgMBAAGjdTBzMAwGA1UdEwEB/wQCMAAwDgYDVR0P +AQH/BAQDAgeAMBMGA1UdJQQMMAoGCCsGAQUFBwMCMB0GA1UdDgQWBBQCkfdfq3hv +7UtqAxq/5VDRIdgJLTAfBgNVHSMEGDAWgBQAb2W+vsDMn/Li9j9eVbFeu77qbTAN +BgkqhkiG9w0BAQsFAAOCAQEAJ43+aDVRC+y2vsu6WRG2l6zYnLoIJZW4afdKMC1a +nhTWhj4AhAt8evhVbAxi/8qhQX3yXF2bUQKdS++8AVcvZFlSES32S5eBx83AwGLt +QkgvGx+QThKmoJwrelyuS2X0XX3P0WzohYI6HzSr6p9F8KhTvSW97E6SnldpdvEM +uG1C+61/Vys7WLmDBh1PZTGE03nRp3H4Q9ynyXEEf1MK3eZkzg5H3Evj66p82pD5 +8IauRfghMHJf3tOC+y0YIoXshF3lPq4nYso5Jc/HGCHlsboCODMCnY3CZsH7/O1n +/MI710KpzZTCLnv4Qtx9JpZxR7FTddl36OOuYUXU3Gcnsg== +-----END CERTIFICATE----- + +</cert> + +<key> +-----BEGIN PRIVATE KEY----- +MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQCdOWq8vdO8CznG +N83uAXCuN4PcdTJaRFEdJIEfqHjlcG0MZQuPIAlDbOU+IWmuQBmeCj7SlbYtVYo1 +uQOMUaIrAvxLIQUaL1Y60oLVTF5eAPrGV+NSTQR5uMApcH9/RcZcW530pu/QpYin +KTbGkEd54so6YRVPmYbIOPNUMbnZbccpinYi5t2dqubBb585A7L40043VtsVVbPj +Qq5V0HDursvqlaMqMRcffhR8H4B4ByU/EPRK4yTKm1hi19v3UtRHiq74CfGtJzYt +plgrLJBON7TsbIi/fEux4q1yhbKA0S66L6e5DZldRxNZOXG6QjEL0RkYloMgkbv/ +2HLCu09hAgMBAAECggEAOR3xRVUO9Sr816JRSQwz486eNDpNSxazgwtOb3JUTUH9 +E7onq1y/kMOgOmSIEHoP9GaTcQxbbPe86IxomhLT/50ri52YzWzx/heY2SVPyQXB +FMo79putKw0vnj5UyydNiyLrbMQyrhFc5iFmWVdz5/c4cWHwjIThPp7V4znXYwHZ +OB/Xn1NNHDNy872oQn5wZWzuA4ml0OqjU5D+Ne9srODl3r4OTo3lb1N3JuH3aOSA +cACl1JnN/KElN8IotIdweeUFAdn2jsGjZnCpGaJvZQ+2iMn6doJXHgFiF5+GMF7o +aOatglElIuqgPtB/4nvnegSL0DSnB36ojqv2PAh24wKBgQDPBt4S4muqo8SqP2e0 +8X78MyK3tz1VmgPKn3O68Vdi1V7FPz0RHRGsw/kdgxXsJlfZTWgzcq2NNFu0yPBJ +A/h7qo16mv8GW7cJCd2exjb+/oq4r5iWeqLdSsMUXN87x02LRaMNd9wz1mls1Z73 +oQ5hJ7zTtlyYXnvKPQo8X1ImjwKBgQDCaptQxZ/a3tcUQQlXAFMAScviODZd0LCL +30ZalwpNs6nVVIPoZHD3tlzWN5Es74gndfkC7/Gm2cnsOW9QQaU56q+5LeNXItW8 +rc6yXq3vNQerqJxHNUmKWwLCQtSyLRjFqpGTl/PyX2bGXQ7/zjTL3W8VMD5otf4Y +SJJB+sKjDwKBgHSVX3WvAAamFtfwwMwKuwH3IfPnQqj0BHKUfK2nvxgvJCFbzV3X +yt5Jtf3ClhPYO9xpVOa0C7va4lHaXkYf8Exj7SxAIKFKALccUStaYBoU6bW7XOhQ +w2pu8ZCEBEo7oBVv77Rj7SNb+R6K5ex5TAm2QQXQSjCb9IYc/ail3TNNAoGBALu6 +GPMrgKnlFyV1j0E1DPBwUbDEuqpoArFtDRAYXFifLVTS4PQbWIG403f9++659Gy2 +G5ZcfqiwD6xL4VJLsPF1zewvhR/0gRJJehb+GVGrkRaOHykbKUGxk75kreDGbu8f +PqaXyXS17hWIch1Lzes0jDiXdwvA//QOzztqmVq9AoGAVMbmf04+QtzckLolAP4q +Uwr5svfy14A7V3IGkwlsHZdm37L26lfxW0kpOOE7g7D6gdinuALo6oopP7RN/IDq +PLaaHaGrIoLAEVFa0bRLGsrU2q87ytwfSgdra4jmsTn+xEabdI4IgmqWgwSRvGVf +KN18e19Ssw5x7Wq0Rsw/3VM= +-----END PRIVATE KEY----- + +</key> +``` + +When prompted, log in with the username and password. diff --git a/docs/configuration/interfaces/openvpn.md b/docs/configuration/interfaces/openvpn.md new file mode 100644 index 00000000..170c585d --- /dev/null +++ b/docs/configuration/interfaces/openvpn.md @@ -0,0 +1,614 @@ +(openvpn)= + +# OpenVPN + +Traditionally, hardware routers use IPsec exclusively because it is easy to +implement in hardware, and their CPUs lack sufficient power for software-based +encryption. This limitation is less relevant for VyOS, as it is a software +router. + +OpenVPN has been widely used on UNIX platforms for a long time and is a popular +choice for remote-access VPNs. It also supports site-to-site connections. + +OpenVPN offers the following advantages: + +- It uses a single TCP or UDP connection and does not rely on packet source + addresses, so it works even through double NAT. This makes it well-suited for + public hotspots. +- It is easy to set up and offers very flexible split tunneling. +- A variety of client GUI frontends are available for any platform. + +Disadvantages include: + +- It is slower than IPsec due to higher protocol overhead and because it runs + in user mode, while IPsec on Linux runs in kernel mode. +- No operating system includes OpenVPN client software by default. + +In the VyOS CLI, OpenVPN is configured as a network interface using `set +interfaces openvpn` rather than `set vpn`, which is often overlooked. + +## Configuration + +```{cfgcmd} set interfaces openvpn \<interface\> authentication password \<text\> + + **Configure the password for the** ``auth-user-pass`` **authentication method.** + + This option applies only to OpenVPN clients. +``` + + +```{cfgcmd} set interfaces openvpn \<interface\> authentication username \<text\> + +**Configure the username for the** ``auth-user-pass`` **authentication method.** + +This option applies only to OpenVPN clients. +``` + + +```{cfgcmd} set interfaces openvpn \<interface\> description \<description\> + +Configure the description for the OpenVPN interface. +``` + + +```{cfgcmd} set interfaces openvpn \<interface\> device-type \<tap | tun\> + +**Configure the virtual network device type for the OpenVPN interface:** + +* ``tun`` **(default)**: Operates at Layer 3, encapsulating IPv4 or IPv6 packets. +* ``tap``: Operates at Layer 2, encapsulating Ethernet 802.3 frames. +``` + + +```{cfgcmd} set interfaces openvpn \<interface\> disable + +Disable the specific OpenVPN interface. +``` + + +```{cfgcmd} set interfaces openvpn \<interface\> encryption cipher \< 3des | aes128 | aes128gcm | aes192 | aes192gcm | aes256 | aes256gcm | none \> + +**Configure the static encryption cipher for the OpenVPN tunnel.** + +The ``cipher`` option maps to OpenVPN’s ``--cipher`` directive and specifies +the symmetric encryption algorithm for both control and data channels. + +This was previously the default encryption method in all OpenVPN modes. In +newer OpenVPN versions, the ``--cipher`` directive is considered **legacy** +and should be used only in compatibility scenarios. +``` + + +```{cfgcmd} set interfaces openvpn \<interface\> encryption data-ciphers \< 3des | aes128 | aes128gcm | aes192 | aes192gcm | aes256 | aes256gcm | none \> + +**Configure a prioritized list of negotiated ciphers for OpenVPN in** +``client`` **or** ``server`` **mode.** + +The ``data-ciphers`` option represents a list of supported encryption +algorithms. It corresponds to OpenVPN’s ``--data-ciphers`` directive and +enables cipher negotiation, where both peers automatically agree on a mutually +supported cipher during session startup. + +:::{note} +This option is not compatible with ``site-to-site`` mode. +::: +``` + + +```{cfgcmd} set interfaces openvpn \<interface\> encryption data-ciphers-fallback \< 3des | aes128 | aes128gcm | aes192 | aes192gcm | aes256 | aes256gcm | none \> + +**Configure the fallback cipher for** ``site-to-site`` **mode.** + +The ``data-ciphers-fallback`` option maps to OpenVPN’s ``--data-ciphers- +fallback`` directive. It defines the cipher to use if negotiation is **not +supported**. + +:::{note} +This option ensures consistent encryption between two static peers +without cipher negotiation capability. +::: +``` + + +```{cfgcmd} set interfaces openvpn \<interface\> hash \<md5 | sha1 | sha256 | ...\> + +Configure the hashing algorithm for the OpenVPN interface. +``` + + +```{cmdincludemd} /_include/interface-ip.txt +:var0: openvpn +:var1: vtun0 +``` + + +```{cmdincludemd} /_include/interface-ipv6.txt +:var0: openvpn +:var1: vtun0 +``` + + +```{cfgcmd} set interfaces openvpn \<interface\> keep-alive failure-count \<value\> + +**Configure the number of tolerated keepalive packet failures.** + +Default: 60 consecutive failures. +``` + + +```{cfgcmd} set interfaces openvpn \<interface\> keep-alive interval \<value\> + +**Configure the frequency, in seconds, at which keepalive packets are sent.** + +Default: 10 seconds. +``` + + +```{cfgcmd} set interfaces openvpn \<interface\> local-address \<address\> + +Configure the local tunnel IP address for ``site-to-site`` mode. +``` + + +```{cfgcmd} set interfaces openvpn \<interface\> local-host \<address\> + +**Configure the local IP address to accept connections.** + +If configured, OpenVPN binds to this IP address only. + +By default, OpenVPN binds to all interfaces. +``` + + +```{cfgcmd} set interfaces openvpn \<interface\> local-port \<port\> + +Configure the local port to accept connections. +``` + + +```{cfgcmd} set interfaces openvpn \<interface\> mirror egress \<monitor-interface\> + +Configure mirroring of outgoing traffic from this OpenVPN interface to the +designated monitor interface. +``` + + +```{cfgcmd} set interfaces openvpn \<interface\> mirror ingress \<monitor-interface\> + +Configure mirroring of incoming traffic from this OpenVPN interface to the +designated monitor interface. +``` + + +```{cfgcmd} set interfaces openvpn \<interface\> mode \<site-to-site | server | client\> + +**Configure OpenVPN operation mode:** + +* ``site-to-site``: Establishes a site-to-site VPN connection. +* ``client``: Operates as a client in server-client mode. +* ``server``: Operates as a server in server-client mode. +``` + +### OpenVPN Data Channel Offload (DCO) + +OpenVPN {abbr}`DCO (Data Channel Offload)` improves the performance of +encrypted OpenVPN data processing by keeping most data handling in the kernel +and avoiding frequent context switches between the kernel and user space. + +As a result, packet processing becomes more efficient and may utilize hardware +encryption offload support available in the kernel. + +:::{note} +- {abbr}`DCO (Data Channel Offload)` is an **experimental**, not fully supported + OpenVPN feature. Some OpenVPN features and deployment scenarios are **not + compatible** with {abbr}`DCO (Data Channel Offload)`. + + For a complete list of supported features, visit: + <https://community.openvpn.net/openvpn/wiki/DataChannelOffload/Features> +- {abbr}`DCO (Data Channel Offload)` is configured per tunnel and disabled + by default. Existing tunnels operate without {abbr}`DCO (Data Channel + Offload)` unless it is explicitly enabled. +- Enabling {abbr}`DCO (Data Channel Offload)` resets the interface. +::: + +**Best practice:** Create a new tunnel with {abbr}`DCO (Data Channel Offload)` +enabled to avoid compatibility issues with existing clients. + +```{cfgcmd} set interfaces openvpn \<interface\> offload dco + + **Enable** {abbr}`DCO (Data Channel Offload)` **for the specified OpenVPN + interface.** + + Example: + + :::{code-block} none + set interfaces openvpn vtun0 offload dco + ::: + This command enables {abbr}`DCO (Data Channel Offload)` and loads the required + kernel module. +``` + + +```{cfgcmd} set interfaces openvpn \<interface\> openvpn-option \<text\> + +**Add raw OpenVPN configuration options to the openvpn.conf file.** + +OpenVPN provides many configuration options, but not all are available in the +VyOS CLI. + +If a required option is missing, you may submit a feature request at +Phabricator so all users can benefit from it (see Contributing/Issues and Features). + +Alternatively, use ``openvpn-option`` to pass raw OpenVPN configuration options +to the openvpn.conf file. + +:::{warning} +Use this option only as a last resort. Invalid options or syntax +may prevent OpenVPN from starting. Check system logs for errors after applying +changes. +::: +Example: + +:::{code-block} none +set interfaces openvpn vtun0 openvpn-option 'persist-key' +::: +This command adds ``persist-key`` to the configuration file. This solves the +problem by persisting keys across resets, so they do not need to be re-read. + +:::{code-block} none +set interfaces openvpn vtun0 openvpn-option 'route-up "/config/auth/tun_up.sh arg1"' +::: +This command adds ``route-up "/config/auth/tun_up.sh arg1"`` to the +configuration file. This option is executed after connection authentication, +either immediately or after a short delay, as defined. + +Ensure the path and arguments are enclosed in single or double quotes. + +:::{note} +Some raw configuration options require quotes. To include them, use +the " statement. +::: +``` + + +```{cfgcmd} set interfaces openvpn \<interface\> persistent-tunnel + +**Enable always-active mode for the TUN/TAP device.** + +When enabled, the TUN/TAP device remains active upon connection resets or +daemon reloads. +``` + + +```{cfgcmd} set interfaces openvpn \<interface\> protocol \<udp | tcp-passive | tcp-active \> + +**Configure the protocol for OpenVPN communication with a remote host:** + +* ``udp`` **(default)**: Uses the UDP protocol. +* ``tcp-passive``: Uses the TCP protocol and accepts connections passively. +* ``tcp-active``: Uses the TCP protocol and initiates connections actively. +``` + + +```{cfgcmd} set interfaces openvpn \<interface\> redirect \<interface\> + +Enable redirection of incoming packets to the specified interface. +``` + + +```{cfgcmd} set interfaces openvpn \<interface\> remote-address \<address\> + +Configure the remote tunnel IP address for site-to-site mode. +``` + + +```{cfgcmd} set interfaces openvpn \<interface\> remote-host \<address | host\> + +**Configure the IPv4/IPv6 address or hostname for a server device if OpenVPN +runs in client mode.** + +This setting is not used in server mode. +``` + + +```{cfgcmd} set interfaces openvpn \<interface\> remote-port \<port\> + +Configure the remote port to connect to the server. +``` + + +```{cfgcmd} set interfaces openvpn \<interface\> replace-default-route + +Configure the OpenVPN tunnel as the default route. +``` + + +```{cfgcmd} set interfaces openvpn \<interface\> server bridge disable + +Disable the given instance. +``` + + +```{cfgcmd} set interfaces openvpn \<interface\> server bridge gateway \<ipv4 address\> + +Configure the gateway IP address. +``` + + +```{cfgcmd} set interfaces openvpn \<interface\> server bridge start \<ipv4 address\> + +Configure the first IP address in the pool to allocate to connecting clients. +``` + + +```{cfgcmd} set interfaces openvpn \<interface\> server bridge stop \<ipv4 address\> + +Configure the last IP address in the pool to allocate to connecting clients. +``` + + +```{cfgcmd} set interfaces openvpn \<interface\> server bridge subnet-mask \<ipv4 subnet mask\> + +Configure the subnet mask pushed to dynamic clients. +``` + + +```{cfgcmd} set interfaces openvpn \<interface\> server client \<name\> + +Configure the Common Name (CN) specified in the client certificate. +``` + + +```{cfgcmd} set interfaces openvpn \<interface\> server client \<name\> disable + +Disable the client connection. +``` + + +```{cfgcmd} set interfaces openvpn \<interface\> server client \<name\> ip \<address\> + +Configure the IPv4/IPv6 address for the client. +``` + + +```{cfgcmd} set interfaces openvpn \<interface\> server client \<name\> push-route \<subnet\> + +Configure a route to be pushed to the specific client. +``` + + +```{cfgcmd} set interfaces openvpn \<interface\> server client \<name\> subnet \<subnet\> + +**Configure a fixed subnet to be routed from the server to the specified +client.** + +Used as OpenVPN’s ``iroute`` directive. +``` + + +```{cfgcmd} set interfaces openvpn \<interface\> server client-ip-pool start \<address\> + +Configure the first IP address in the subnet's IPv4 pool to be dynamically +allocated to connecting clients. +``` + + +```{cfgcmd} set interfaces openvpn \<interface\> server client-ip-pool stop \<address\> + +Configure the last IP address in the subnet's IPv4 pool to be dynamically +allocated to connecting clients. +``` + + +```{cfgcmd} set interfaces openvpn \<interface\> server client-ip-pool subnet \<netmask\> + +**Configure the subnet mask pushed to dynamic clients.** + +Use this command only for the TAP device type. Do not use it for bridged +interfaces. +``` + + +```{cfgcmd} set interfaces openvpn \<interface\> server client-ipv6-pool base \<ipv6addr/bits\> + +Configure the IPv6 address pool for dynamic assignment to clients. +``` + + +```{cfgcmd} set interfaces openvpn \<interface\> server domain-name \<name\> + +Configure the DNS suffix to be pushed to all clients. +``` + + +```{cfgcmd} set interfaces openvpn \<interface\> server max-connections \<1-4096\> + +Configure the maximum number of client connections. +``` + + +```{cfgcmd} set interfaces openvpn \<interface\> server mfa totp challenge \<enable | disable\> + +If enabled, openvpn-otp expects a password as a result of the challenge/ +response protocol. +``` + + +```{cfgcmd} set interfaces openvpn \<interface\> server mfa totp digits \<1-65535\> + +**Configure the number of digits to use for the** {abbr}`TOTP (Time-based +One-Time Password)` **hash.** + +Default: 6. +``` + + +```{cfgcmd} set interfaces openvpn \<interface\> server mfa totp drift \<1-65535\> + +**Configure the time drift in seconds.** + +Default: 0. +``` + + +```{cfgcmd} set interfaces openvpn \<interface\> server mfa totp slop \<1-65535\> + +**Configure the allowed clock slop in seconds.** + +Default: 180. +``` + + +```{cfgcmd} set interfaces openvpn \<interface\> server mfa totp step \<1-65535\> + +**Configure the step value for** {abbr}`TOTP (Time-based One-Time Password)` +**in seconds.** + +Default: 30. +``` + + +```{cfgcmd} set interfaces openvpn \<interface\> server name-server \<address\> + +Define the client DNS configuration to be used with the connection. +``` + + +```{cfgcmd} set interfaces openvpn \<interface\> server push-route \<subnet\> + +Configure the route to be pushed to all clients. +``` + + +```{cfgcmd} set interfaces openvpn \<interface\> server reject-unconfigured-client + +Reject connections from clients that are not explicitly configured. +``` + + +```{cfgcmd} set interfaces openvpn \<interface\> server subnet \<subnet\> + +**Configure the IPv4 or IPv6 network.** + +This parameter is mandatory when operating in server mode. +``` + + +```{cfgcmd} set interfaces openvpn \<interface\> server topology \< net30 | point-to-point | subnet\> + +**Configure the virtual addressing topology for** ``tun`` **mode.** + +This command does not affect ``tap`` mode, which always uses the ``subnet`` +topology. + +* ``subnet`` **(default)**: Allocates a single IP address to each connecting client. +This is the recommended topology. +* ``net30``: Allocates a /30 subnet to each connecting client. This is a legacy +topology used to support Windows clients. It is now effectively deprecated. +* ``point-to-point``: Creates a point-to-point topology where the remote +endpoint of the client’s ``tun`` interface always points to the local endpoint +of the server’s ``tun`` interface. + +Like ``subnet``, this topology allocates a single IP address per client. Use it +only if no clients run Windows operating systems. +``` +```{cfgcmd} set interfaces openvpn \<interface\> shared-secret-key \<key\> + +Configure the static secret key for a site-to-site OpenVPN connection. +``` +```{cfgcmd} set interfaces openvpn \<interface\> tls auth-key \<key\> + +**Configure the TLS secret key for tls-auth.** + +This adds an HMAC signature to all SSL/TLS handshake packets to verify +integrity. + +Use ``run generate pki openvpn shared-secret install <name>`` to generate +the key. +``` +```{cfgcmd} set interfaces openvpn \<interface\> tls ca-certificate \<name\> + +Configure the Certificate Authority chain in the PKI configuration. +``` +```{cfgcmd} set interfaces openvpn \<interface\> tls certificate \<name\> + +Configure the certificate name in the PKI configuration. +``` +```{cfgcmd} set interfaces openvpn \<interface\> tls crypt-key + +Configure a shared secret key to provide an additional level of security, +a variant similar to tls-auth. +``` +```{cfgcmd} set interfaces openvpn \<interface\> tls dh-params + +Configure Diffie-Hellman parameters for server mode. +``` +```{cfgcmd} set interfaces openvpn \<interface\> tls peer-fingerprint \<text\> + +Configure the peer certificate SHA256 fingerprint for site-to-site mode. +``` +```{cfgcmd} set interfaces openvpn \<interface\> tls role \<active | passive\> + +**Configure the TLS negotiation role, preferably used in site-to-site mode:** +* ``active``: Initiates TLS negotiation actively. +* ``passive``: Waits for incoming TLS connections. +``` +```{cfgcmd} set interfaces openvpn \<interface\> tls tls-version-min \<1.0 | 1.1 | 1.2 | 1.3 \> + +Configure the minimum TLS version to be accepted from the peer. +``` +```{cfgcmd} set interfaces openvpn \<interface\> use-lzo-compression + +Configure fast LZO compression on this TUN/TAP interface. +``` +```{cfgcmd} set interfaces openvpn \<interface\> vrf \<name\> + +Assign the interface to a specific VRF instance. +``` + +## Operation mode + +```{opcmd} show openvpn site-to-site + +Show tunnel status for OpenVPN site-to-site interfaces. +``` +```{opcmd} show openvpn server + +Show tunnel status for OpenVPN server interfaces. +``` +```{opcmd} show openvpn client + +Show tunnel status for OpenVPN client interfaces. +``` +```{opcmd} show log openvpn + +Show logs for all OpenVPN interfaces. +``` +```{opcmd} show log openvpn interface \<interface\> + +Show logs for the specific OpenVPN interface. +``` +```{opcmd} reset openvpn client \<text\> + +Reset the specified OpenVPN client. +``` +```{opcmd} reset openvpn interface \<interface\> + +Reset the OpenVPN process on the specified interface. +``` +```{opcmd} generate openvpn client-config interface \<interface\> ca \<name\> certificate \<name\> + +Generate an OpenVPN client configuration file in the .ovpn format for client machines. +``` + +## Examples + +This section covers examples of OpenVPN configurations for various deployments. + +```{toctree} +:includehidden: true +:maxdepth: 1 + +openvpn-examples +``` + diff --git a/docs/configuration/interfaces/pppoe.md b/docs/configuration/interfaces/pppoe.md new file mode 100644 index 00000000..b79f41a2 --- /dev/null +++ b/docs/configuration/interfaces/pppoe.md @@ -0,0 +1,419 @@ +--- +lastproofread: '2026-03-03' +--- + +(pppoe-interface)= + +# PPPoE + +{abbr}`PPPoE (Point-to-Point Protocol over Ethernet)` is a network protocol +that encapsulates PPP frames within Ethernet frames. +It's often used for connecting ISP clients to a broadband access server. + +## Configuration + +### Common interface configuration + +```{cmdincludemd} /_include/interface-description.txt +:var0: pppoe +:var1: pppoe0 +``` + +```{cmdincludemd} /_include/interface-disable.txt +:var0: pppoe +:var1: pppoe0 +``` + +```{cmdincludemd} /_include/interface-mtu.txt +:var0: pppoe +:var1: pppoe0 +``` + +```{cmdincludemd} /_include/interface-vrf.txt +:var0: pppoe +:var1: pppoe0 +``` + + +### PPPoE options + +```{cfgcmd} set interfaces pppoe \<interface\> access-concentrator \<name\> + +**Configure the name of the target access concentrator for the PPPoE session.** + +During the PPPoE discovery process, the client sends a PPPoE initiation packet. +Multiple access concentrators may respond with offer packets, and the client +selects one of them. + +This setting restricts the client to establishing sessions only with the +specified access concentrator. +``` + +```{cfgcmd} set interfaces pppoe \<interface\> authentication username \<username\> + +**Configure the username for PPPoE session authentication.** + +Although authentication is optional in the interface configuration, most ISPs +require it to establish a connection. +``` + +```{cfgcmd} set interfaces pppoe \<interface\> authentication password \<password\> + +**Configure the password for PPPoE session authentication.** + +Although authentication is optional in the interface configuration, most ISPs +require it to establish a connection. +``` + +```{cfgcmd} set interfaces pppoe \<interface\> connect-on-demand + +**Enable dial-on-demand on the PPPoE interface.** + +When enabled, the system establishes a PPPoE connection only when traffic +passes through the interface. If the connection fails, it is reestablished when +traffic resumes. + +For on-demand connections, you must also configure an ``idle-timeout`` period +to disconnect the session after inactivity. + +:::{note} +Setting the idle timeout to zero, or leaving it unconfigured, keeps +the connection active continuously once established. +::: + +By default, the PPPoE connection is established at boot and remains active +continuously; if the connection fails, it is reestablished immediately. +``` + +```{cfgcmd} set interfaces pppoe \<interface\> no-default-route + +Request an IP address from the PPPoE server without installing a default route. + +Example: + +:::{code-block} none +set interfaces pppoe pppoe0 no-default-route +::: + +:::{note} +Introduced in VyOS 1.4, this command inverts the logic of the former +``default-route`` CLI option. +::: +``` + +```{cfgcmd} set interfaces pppoe \<interface\> default-route-distance \<distance\> + +Configure the distance for the default gateway provided by the PPPoE server. + +Example: + +:::{code-block} none +set interfaces pppoe pppoe0 default-route-distance 220 +::: +``` + +```{cfgcmd} set interfaces pppoe \<interface\> mru \<mru\> + +**Configure the** {abbr}`MRU (Maximum Receive Unit)` **for the PPPoE +interface.** + +This setting instructs the pppd daemon to restrict the remote peer from sending +packets larger than the configured MRU. Allowed MRU values range from 128 to +16384 bytes. + +An MRU of 296 is suitable for very slow links (40 bytes for the TCP/IP header +and 256 bytes for data). + +The default MRU is 1492 bytes. + +:::{note} +When using the IPv6 protocol, the MRU must be at least 1280 bytes. +::: +``` + +```{cfgcmd} set interfaces pppoe \<interface\> idle-timeout \<time\> + +**Configure the idle timeout for on-demand PPPoE sessions.** + +This setting defines how long the connection remains active without any traffic +before being disconnected. + +:::{note} +Setting the idle timeout to zero, or leaving it unconfigured, keeps +the connection active continuously once established. +::: +``` + +```{cfgcmd} set interfaces pppoe \<interface\> holdoff \<time\> + +**Configure the redial delay for persistent PPPoE sessions.** + +If a persistent session (with ``connect-on-demand`` disabled) is terminated by +the remote peer or drops unexpectedly, the router waits the specified interval +before attempting to reconnect. + +The default redial delay is 30 seconds. +``` + +```{cfgcmd} set interfaces pppoe \<interface\> local-address \<address\> + +**Configure the local endpoint IP address for PPPoE sessions.** + +By default, this IP address is negotiated. +``` + +```{cfgcmd} set interfaces pppoe \<interface\> no-peer-dns + +Disable the installation of advertised DNS nameservers on the local system. +``` + +```{cfgcmd} set interfaces pppoe \<interface\> remote-address \<address\> + +**Configure the remote endpoint IP address for PPPoE sessions.** + +By default, this IP address is negotiated. +``` + +```{cfgcmd} set interfaces pppoe \<interface\> service-name \<name\> + +**Configure the service name of the target access concentrator for the PPPoE +session.** + +By default, the PPPoE interface connects to any available access concentrator. +``` + +```{cfgcmd} set interfaces pppoe \<interface\> source-interface \<source-interface\> + +**Configure the underlying interface for the PPPoE connection.** + +Each PPPoE connection is established over an underlying interface, which can be +an Ethernet interface, a VIF, or a bonding interface. +``` + +```{cfgcmd} set interfaces pppoe \<interface\> ip adjust-mss \<mss | clamp-mss-to-pmtu\> + +**Configure the** {abbr}`MSS (Maximum Segment Size)` **advertised in outgoing +TCP SYN packets on the specified interface.** + +By clamping the MSS value in TCP SYN packets, you instruct the remote side not +to send packets larger than the specified size. This helps prevent connection +issues if {abbr}`PMTUD (Path MTU Discovery)` fails. + +The following options are available: + +* ``mss``: Sets the MSS to a specific value in bytes. +* ``clamp-mss-to-pmtu``: Sets the MSS to the interface’s MTU minus 40 bytes for + IPv4 traffic (20 bytes for the IPv4 header and 20 bytes for the TCP header). + This option is recommended to automatically set the proper value. + +:::{note} +Introduced in VyOS 1.4, this command replaces the older ``set firewall +options interface <name> adjust-mss <value>`` syntax. +::: +``` + +```{cfgcmd} set interfaces pppoe \<interface\> ip disable-forwarding + +**Configure the interface for host or router behavior.** + +If configured, the interface switches to host mode, and IPv4 forwarding is +disabled on it. +``` + +```{cfgcmd} set interfaces pppoe \<interface\> ip source-validation \<strict | loose | disable\> + +**Configure source IP address validation using** +{abbr}`RPF (Reverse Path Forwarding)` **on this interface, as specified in** +{rfc}`3704`. + +The following options are available: + +* ``strict``: Each incoming packet’s source IP address is checked against the + {abbr}`FIB (Forwarding Information Base)`. If the interface is not the best + route back to that source, validation fails, and the packet is dropped. +* ``loose``: Each incoming packet’s source IP address is checked against the + {abbr}`FIB (Forwarding Information Base)`. If the source IP address is + unreachable through any interface, validation fails. +* ``disable``: No source IP address validation is performed. All incoming + packets are accepted. + +{rfc}`3704` recommends enabling ``strict`` mode to prevent IP spoofing, such as +DDoS attacks. For asymmetric or other complex routing scenarios, use ``loose`` +mode. +``` + + +#### IPv6 + +```{cfgcmd} set interfaces pppoe \<interface\> ipv6 address autoconf + +Enable IPv6 address assignment via {abbr}`SLAAC (Stateless Address +Auto-Configuration)` on this interface. +``` + +```{cfgcmd} set interfaces pppoe \<interface\> ipv6 adjust-mss \<mss | clamp-mss-to-pmtu\> + +**Configure the** {abbr}`MSS (Maximum Segment Size)` **advertised in outgoing +TCP SYN packets on the specified interface.** + +By clamping the MSS value in TCP SYN packets, you instruct the remote side not +to send packets larger than the specified size. This helps prevent connection +issues if {abbr}`PMTUD (Path MTU Discovery)` fails. + +The following options are available: + +* ``mss``: Sets the MSS to a specific value in bytes. +* ``clamp-mss-to-pmtu``: Sets the MSS to the interface’s MTU minus 60 bytes for + IPv6 traffic (40 bytes for the IPv6 header and 20 bytes for the TCP header). + This option is recommended to automatically set the proper value. + +:::{note} +Introduced in VyOS 1.4, this command replaces the older ``set firewall +options interface <name> adjust-mss <value>`` syntax. +::: +``` + +```{cfgcmd} set interfaces pppoe \<interface\> ipv6 disable-forwarding + +**Configure the interface for host or router behavior.** + +If configured, the interface switches to host mode, and IPv6 forwarding is +disabled on it. +``` + +```{cmdincludemd} /_include/interface-dhcpv6-prefix-delegation.txt +:var0: pppoe +:var1: pppoe0 +``` + + +## Operation + +```{opcmd} show interfaces pppoe \<interface\> + +Show detailed information about a specific PPPoE interface. + +:::{code-block} none +vyos@vyos:~$ show interfaces pppoe pppoe0 +pppoe0: <POINTOPOINT,MULTICAST,NOARP,UP,LOWER_UP> mtu 1492 qdisc pfifo_fast state UNKNOWN group default qlen 3 + link/ppp + inet 192.0.2.1 peer 192.0.2.255/32 scope global pppoe0 + valid_lft forever preferred_lft forever + + RX: bytes packets errors dropped overrun mcast + 7002658233 5064967 0 0 0 0 + TX: bytes packets errors dropped carrier collisions + 533822843 1620173 0 0 0 0 +::: +``` + +```{opcmd} show interfaces pppoe \<interface\> queue + +Show queue information for a specific PPPoE interface. + +:::{code-block} none +vyos@vyos:~$ show interfaces pppoe pppoe0 queue +qdisc pfifo_fast 0: root refcnt 2 bands 3 priomap 1 2 2 2 1 2 0 0 1 1 1 1 1 1 1 1 + Sent 534625359 bytes 1626761 pkt (dropped 62, overlimits 0 requeues 0) + backlog 0b 0p requeues 0 +::: +``` + + +### Connect/disconnect + +```{opcmd} disconnect interface \<interface\> + +Disconnect the specified interface. +``` + +```{opcmd} connect interface \<interface\> + +Initiate a session on the specified interface. +``` + + +## Example + +### PPPoE over DSL + +**Configuration scenario:** + +- Your ISP's DSL modem is connected to the `eth0` interface on your VyOS + router. +- Your ISP does not require VLAN tagging. +- PPPoE credentials are provided by your ISP. The typical username format is + `name@host.net`, though this may vary. + +**Configuration notes:** + +- The maximum MTU size for DSL is 1492 because of PPPoE overhead. If you are + switching from a DHCP-based ISP (e.g., a standard cable connection), ensure + VPN links have MTU sizes adjusted accordingly. +- To ignore ISP-provided nameservers and use only your statically configured + ones, set the `name-server` option to `none`. +- A default route is automatically installed once the interface is up. To + change this behavior, use the `no-default-route` CLI option. + +:::{note} +The PPPoE configuration syntax changed after VyOS 1.2 (Crux) and is +automatically migrated during an upgrade. +::: + +```none +set interfaces pppoe pppoe0 authentication username 'userid' +set interfaces pppoe pppoe0 authentication password 'secret' +set interfaces pppoe pppoe0 source-interface 'eth0' +``` + +Secure your setup by creating rules matching the `pppoe0` interface in the +firewall chains: + +```none +set firewall ipv4 input filter rule 10 inbound-interface name 'pppoe0' +set firewall ipv4 forward filter rule 10 inbound-interface name 'pppoe0' +``` + + +### PPPoE over VLAN + +Some ISPs require PPPoE connections to be +established over a VLAN interface. This specific topology is fully supported by +VyOS. + +The following configuration establishes the PPPoE connection through VLAN 7, +which is the default VLAN for Deutsche Telekom: + +```none +set interfaces pppoe pppoe0 authentication username 'userid' +set interfaces pppoe pppoe0 authentication password 'secret' +set interfaces pppoe pppoe0 source-interface 'eth0.7' +``` + + +#### IPv6 DHCPv6 prefix delegation + +**Configuration scenario:** + +The following configuration establishes a PPPoE session on the `eth1` +interface, requests a `/56` IPv6 prefix delegation from the ISP, and assigns +a `/64` subnet from that delegation to the `eth0` interface. + +**Configuration notes:** + +- The IPv6 address assigned to `eth0` is `<prefix>::1/64`. +- If you do not know your delegated prefix size, begin with `sla-len 0`. +- To advertise the prefix on the `eth0` link, configure IPv6 Router + Advertisement. + +```none +set interfaces pppoe pppoe0 authentication username vyos +set interfaces pppoe pppoe0 authentication password vyos +set interfaces pppoe pppoe0 dhcpv6-options pd 0 interface eth0 address '1' +set interfaces pppoe pppoe0 dhcpv6-options pd 0 interface eth0 sla-id '0' +set interfaces pppoe pppoe0 dhcpv6-options pd 0 length '56' +set interfaces pppoe pppoe0 ipv6 address autoconf +set interfaces pppoe pppoe0 source-interface eth1 + +set service router-advert interface eth0 prefix ::/64 +``` diff --git a/docs/configuration/interfaces/pseudo-ethernet.md b/docs/configuration/interfaces/pseudo-ethernet.md new file mode 100644 index 00000000..fc8833eb --- /dev/null +++ b/docs/configuration/interfaces/pseudo-ethernet.md @@ -0,0 +1,52 @@ +--- +lastproofread: '2026-03-05' +--- + +(pseudo-ethernet-interface)= + +# MACVLAN (pseudo-Ethernet) + +MACVLAN, or pseudo-Ethernet interfaces, operate as logical subinterfaces of +standard Ethernet interfaces. Each subinterface has a unique MAC address but +shares a single physical Ethernet port. +That allows the user to send packets from different source IPv4 or IPv6 addresses +using a different MAC address. + +Pseudo-Ethernet interfaces behave like physical Ethernet interfaces. They +support IPv4 and IPv6 addressing, can obtain IP addresses through DHCP or +DHCPv6, and are mapped to a physical Ethernet port. They inherit +characteristics such as speed and duplex from their parent interface and can +be referenced like standard Ethernet interfaces once created. + +```{eval-rst} +Pseudo-Ethernet interfaces may not work in environments that require a + :abbr:`NIC (Network Interface Card)` to have only one MAC address. + This includes: + + * VMware machines with default settings. + * Network switches that permit only a single MAC address. + * xDSL modems that learn the NIC's MAC address. +``` + +## Configuration + +### Common interface configuration + +```{cmdincludemd} /_include/interface-common-with-dhcp.txt +:var0: pseudo-ethernet +:var1: peth0 +``` + +### MACVLAN (pseudo-Ethernet) options + +```{cfgcmd} set interfaces pseudo-ethernet \<interface\> source-interface \<ethX\> + +Assign a physical Ethernet interface to the specified pseudo-Ethernet interface. +``` + +### VLAN + +```{cmdincludemd} /_include/interface-vlan-8021q.txt +:var0: pseudo-ethernet +:var1: peth0 +```
\ No newline at end of file diff --git a/docs/configuration/interfaces/bonding.rst b/docs/configuration/interfaces/rst-bonding.rst index 7637790c..7637790c 100644 --- a/docs/configuration/interfaces/bonding.rst +++ b/docs/configuration/interfaces/rst-bonding.rst diff --git a/docs/configuration/interfaces/bridge.rst b/docs/configuration/interfaces/rst-bridge.rst index a1710804..a1710804 100644 --- a/docs/configuration/interfaces/bridge.rst +++ b/docs/configuration/interfaces/rst-bridge.rst diff --git a/docs/configuration/interfaces/dummy.rst b/docs/configuration/interfaces/rst-dummy.rst index 55c134e3..55c134e3 100644 --- a/docs/configuration/interfaces/dummy.rst +++ b/docs/configuration/interfaces/rst-dummy.rst diff --git a/docs/configuration/interfaces/ethernet.rst b/docs/configuration/interfaces/rst-ethernet.rst index e6c385e7..e6c385e7 100644 --- a/docs/configuration/interfaces/ethernet.rst +++ b/docs/configuration/interfaces/rst-ethernet.rst diff --git a/docs/configuration/interfaces/geneve.rst b/docs/configuration/interfaces/rst-geneve.rst index bcd6c591..bcd6c591 100644 --- a/docs/configuration/interfaces/geneve.rst +++ b/docs/configuration/interfaces/rst-geneve.rst diff --git a/docs/configuration/interfaces/index.rst b/docs/configuration/interfaces/rst-index.rst index 46d521b0..46d521b0 100644 --- a/docs/configuration/interfaces/index.rst +++ b/docs/configuration/interfaces/rst-index.rst diff --git a/docs/configuration/interfaces/l2tpv3.rst b/docs/configuration/interfaces/rst-l2tpv3.rst index 692dff93..692dff93 100644 --- a/docs/configuration/interfaces/l2tpv3.rst +++ b/docs/configuration/interfaces/rst-l2tpv3.rst diff --git a/docs/configuration/interfaces/loopback.rst b/docs/configuration/interfaces/rst-loopback.rst index 68158111..68158111 100644 --- a/docs/configuration/interfaces/loopback.rst +++ b/docs/configuration/interfaces/rst-loopback.rst diff --git a/docs/configuration/interfaces/macsec.rst b/docs/configuration/interfaces/rst-macsec.rst index 2a893943..2a893943 100644 --- a/docs/configuration/interfaces/macsec.rst +++ b/docs/configuration/interfaces/rst-macsec.rst diff --git a/docs/configuration/interfaces/openvpn-examples.rst b/docs/configuration/interfaces/rst-openvpn-examples.rst index 6e746e46..6e746e46 100644 --- a/docs/configuration/interfaces/openvpn-examples.rst +++ b/docs/configuration/interfaces/rst-openvpn-examples.rst diff --git a/docs/configuration/interfaces/openvpn.rst b/docs/configuration/interfaces/rst-openvpn.rst index 85877d48..85877d48 100644 --- a/docs/configuration/interfaces/openvpn.rst +++ b/docs/configuration/interfaces/rst-openvpn.rst diff --git a/docs/configuration/interfaces/pppoe.rst b/docs/configuration/interfaces/rst-pppoe.rst index d2f8271c..d2f8271c 100644 --- a/docs/configuration/interfaces/pppoe.rst +++ b/docs/configuration/interfaces/rst-pppoe.rst diff --git a/docs/configuration/interfaces/pseudo-ethernet.rst b/docs/configuration/interfaces/rst-pseudo-ethernet.rst index cb42fafc..cb42fafc 100644 --- a/docs/configuration/interfaces/pseudo-ethernet.rst +++ b/docs/configuration/interfaces/rst-pseudo-ethernet.rst diff --git a/docs/configuration/interfaces/sstp-client.rst b/docs/configuration/interfaces/rst-sstp-client.rst index 9c6c6e9b..9c6c6e9b 100644 --- a/docs/configuration/interfaces/sstp-client.rst +++ b/docs/configuration/interfaces/rst-sstp-client.rst diff --git a/docs/configuration/interfaces/tunnel.rst b/docs/configuration/interfaces/rst-tunnel.rst index f1376cdf..f1376cdf 100644 --- a/docs/configuration/interfaces/tunnel.rst +++ b/docs/configuration/interfaces/rst-tunnel.rst diff --git a/docs/configuration/interfaces/virtual-ethernet.rst b/docs/configuration/interfaces/rst-virtual-ethernet.rst index 5df7e962..5df7e962 100644 --- a/docs/configuration/interfaces/virtual-ethernet.rst +++ b/docs/configuration/interfaces/rst-virtual-ethernet.rst diff --git a/docs/configuration/interfaces/vti.rst b/docs/configuration/interfaces/rst-vti.rst index e45c17d9..e45c17d9 100644 --- a/docs/configuration/interfaces/vti.rst +++ b/docs/configuration/interfaces/rst-vti.rst diff --git a/docs/configuration/interfaces/vxlan.rst b/docs/configuration/interfaces/rst-vxlan.rst index 0d357e9b..0d357e9b 100644 --- a/docs/configuration/interfaces/vxlan.rst +++ b/docs/configuration/interfaces/rst-vxlan.rst diff --git a/docs/configuration/interfaces/wireguard.rst b/docs/configuration/interfaces/rst-wireguard.rst index bc53b388..bc53b388 100644 --- a/docs/configuration/interfaces/wireguard.rst +++ b/docs/configuration/interfaces/rst-wireguard.rst diff --git a/docs/configuration/interfaces/wireless.rst b/docs/configuration/interfaces/rst-wireless.rst index 728783b2..728783b2 100644 --- a/docs/configuration/interfaces/wireless.rst +++ b/docs/configuration/interfaces/rst-wireless.rst diff --git a/docs/configuration/interfaces/wwan.rst b/docs/configuration/interfaces/rst-wwan.rst index 7ab3ac74..7ab3ac74 100644 --- a/docs/configuration/interfaces/wwan.rst +++ b/docs/configuration/interfaces/rst-wwan.rst diff --git a/docs/configuration/interfaces/sstp-client.md b/docs/configuration/interfaces/sstp-client.md new file mode 100644 index 00000000..da98aecd --- /dev/null +++ b/docs/configuration/interfaces/sstp-client.md @@ -0,0 +1,170 @@ +--- +lastproofread: '2026-03-16' +--- + +(sstp-client-interface)= + +# SSTP client + +{abbr}`SSTP (Secure Socket Tunneling Protocol)` transports PPP traffic over an +SSL/TLS channel, providing transport-level security through key negotiation, +encryption, and traffic integrity checking. The use of SSL/TLS over TCP port +443 (by default, the port can be changed) allows SSTP to pass through virtually +all firewalls and proxy servers, except for authenticated web proxies. + +:::{note} +VyOS includes a built-in SSTP server. For more information, see +{ref}`sstp`. +::: + +## Configuration + +### Common interface configuration + +```{cmdincludemd} /_include/interface-description.txt +:var0: sstpc +:var1: sstpc0 +``` + +```{cmdincludemd} /_include/interface-disable.txt +:var0: sstpc +:var1: sstpc0 +``` + +```{cmdincludemd} /_include/interface-mtu.txt +:var0: sstpc +:var1: sstpc0 +``` + +```{cmdincludemd} /_include/interface-vrf.txt +:var0: sstpc +:var1: sstpc0 +``` + + +### SSTP client options + +```{cfgcmd} set interfaces sstpc \<interface\> no-default-route + +Request an IP address from the SSTP server without installing a default route. + +Example: + +:::{code-block} none +set interfaces sstpc sstpc0 no-default-route +::: +:::{note} Introduced in VyOS 1.4, this command inverts the logic of the former +``default-route`` CLI option. +::: +``` + +```{cfgcmd} set interfaces sstpc \<interface\> default-route-distance \<distance\> + +Configure the distance for the default gateway provided by the SSTP server. + +Example: + +:::{code-block} none +set interfaces sstpc sstpc0 default-route-distance 220 +::: +``` + +```{cfgcmd} set interfaces sstpc \<interface\> no-peer-dns + +Disable the installation of advertised DNS nameservers on the local system. +``` + +```{cfgcmd} set interfaces sstpc \<interface\> server \<address\> + +**Configure the remote SSTP server address for the client connection.** + +The address can be either an IP address or a {abbr}`FQDN (Fully Qualified +Domain Name)`. +``` + +```{cfgcmd} set interfaces sstpc \<interface\> ip adjust-mss \<mss | clamp-mss-to-pmtu\> + +**Configure the** {abbr}`MSS (Maximum Segment Size)` **advertised in outgoing +TCP SYN packets on the specified interface.** + +By clamping the MSS value in TCP SYN packets, you instruct the remote side not +to send packets larger than the specified size. This helps prevent connection +issues if {abbr}`PMTUD (Path MTU Discovery)` fails. + +The following options are available: + +* ``mss``: Sets the MSS to a specific value in bytes. +* ``clamp-mss-to-pmtu``: Sets the MSS to the interface’s MTU minus 40 bytes for +IPv4 traffic (20 bytes for the IPv4 header and 20 bytes for the TCP header). +This option is recommended to automatically set the proper value. + +:::{note} Introduced in VyOS 1.4, this command replaces the older ``set firewall +options interface <name> adjust-mss <value>`` syntax. +::: +``` + +```{cfgcmd} set interfaces sstpc \<interface\> ip disable-forwarding + +**Configure the interface for host or router behavior.** + +If configured, the interface switches to host mode, and IPv4 forwarding is +disabled on it. +``` + +```{cfgcmd} set interfaces sstpc \<interface\> ip source-validation \<strict | loose | disable\> + +**Configure source IP address validation using** +{abbr}`RPF (Reverse Path Forwarding)` **on this interface, as specified in** +{rfc}`3704`. + +The following options are available: + +* ``strict``: Each incoming packet’s source IP address is checked against the +{abbr}`FIB (Forwarding Information Base)`. If the interface is not the best +route back to that source, validation fails, and the packet is dropped. +* ``loose``: Each incoming packet’s source IP address is checked against the +{abbr}`FIB (Forwarding Information Base)`. If the source IP address is +unreachable through any interface, validation fails. +* ``disable``: No source IP address validation is performed. All incoming +packets are accepted. + +{rfc}`3704` recommends enabling ``strict`` mode to prevent IP spoofing, such as +DDoS attacks. For asymmetric or other complex routing scenarios, use ``loose`` +mode. +``` + + +## Operation + +```{opcmd} show interfaces sstpc \<interface\> + +Show detailed information about the specified 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\> + +Disconnect the specified interface. +``` + +```{opcmd} connect interface \<interface\> + +Initiate a session on the specified interface. +```
\ No newline at end of file diff --git a/docs/configuration/interfaces/tunnel.md b/docs/configuration/interfaces/tunnel.md new file mode 100644 index 00000000..9c9885d2 --- /dev/null +++ b/docs/configuration/interfaces/tunnel.md @@ -0,0 +1,309 @@ +--- +lastproofread: '2026-01-23' +--- + +(tunnel-interface)= + +# Tunnel + +Tunnel interfaces are virtual links that transmit encapsulated traffic between +private networks or hosts across public infrastructure, such as the Internet. +They operate using encapsulation protocols to wrap original traffic for +transport. The supported protocols include {abbr}`GRE (Generic Routing +Encapsulation)`, IPIP, IPIP6, IP6IP6, and 6in4 (SIT). + +While {abbr}`GRE (Generic Routing Encapsulation)` is often the preferred +one-size-fits-all solution due to its versatility, other encapsulation +protocols may be better suited for specific use cases. + +VyOS uses a single tunnel interface type for all of these protocols. There are +no separate {abbr}`GRE (Generic Routing Encapsulation)`, IPIP, or IP6IP6 +interface types; instead, the desired encapsulation protocol is selected within +the `set interfaces tunnel` configuration. + +Configuration options for each protocol are described below. + +:::{warning} +Do not change the encapsulation type for already configured tunnel +interfaces, as this may break their dependent configurations. +::: + +## Common interface configuration + +```{cmdincludemd} /_include/interface-address.txt +:var0: tunnel +:var1: tun0 +``` + +```{cmdincludemd} /_include/interface-common-without-mac.txt +:var0: tunnel +:var1: tun0 +``` + + +## IPIP + +IPIP is a straightforward encapsulation protocol defined in RFC 2003. It +encapsulates one IPv4 packet inside another IPv4 packet. + +Tunnels with IPIP encapsulation do not have protocol-specific configuration +options except for explicitly defining the encapsulation type as IPIP (see +the example below). + +Example: + +```none +set interfaces tunnel tun0 encapsulation ipip +set interfaces tunnel tun0 source-address 192.0.2.10 +set interfaces tunnel tun0 remote 203.0.113.20 +set interfaces tunnel tun0 address 192.168.100.200/24 +``` + + +## IP6IP6 + +IP6IP6 is the IPv6 counterpart to IPIP. It encapsulates one IPv6 packet inside +another IPv6 packet. + +Similar to their IPIP counterparts, tunnels with IP6IP6 encapsulation do not +have protocol-specific configuration options except for explicitly defining +the encapsulation type as IP6IP6. + +Example: + +```none +set interfaces tunnel tun0 encapsulation ip6ip6 +set interfaces tunnel tun0 source-address 2001:db8:aa::1 +set interfaces tunnel tun0 remote 2001:db8:aa::2 +set interfaces tunnel tun0 address 2001:db8:bb::1/64 +``` + + +## IPIP6 + +IPIP6 is an encapsulation protocol that wraps IPv4 packets inside IPv6 packets. + +Similar to IPIP and IP6IP6, protocol-specific configuration for tunnels with +IPIP6 encapsulation only requires defining the encapsulation type as IP6IP6. + +Example: + +```none +set interfaces tunnel tun0 encapsulation ipip6 +set interfaces tunnel tun0 source-address 2001:db8:aa::1 +set interfaces tunnel tun0 remote 2001:db8:aa::2 +set interfaces tunnel tun0 address 192.168.70.80/24 +``` + + +## 6in4 (SIT) + +6in4, also known as {abbr}`SIT (Simple Internet Transition)`, is an +encapsulation protocol defined in {rfc}`4213` that wraps IPv6 packets +inside IPv4 packets. The encapsulating IPv4 headers use IP protocol number 41, +which is reserved exclusively for IPv6 encapsulation. + +The encapsulation process adds a 20-byte IPv4 header to each IPv6 packet. +Consequently, 6in4 tunnel interfaces can transmit IPv6 packets up to 1480 bytes +over an underlying network with a standard MTU of 1500 bytes without +fragmentation. + +6in4 tunnel interfaces are frequently used by IPv6 tunnel brokers (such as +[Hurricane Electric]) to connect isolated IPv6 networks or individual hosts to +the IPv6 internet. + +Example: + +```none +set interfaces tunnel tun0 encapsulation sit +set interfaces tunnel tun0 source-address 192.0.2.10 +set interfaces tunnel tun0 remote 192.0.2.20 +set interfaces tunnel tun0 address 2001:db8:bb::1/64 +``` + +:::{seealso} +For a practical configuration example, see the +{ref}`Tunnelbroker.net (IPv6) <examples-tunnelbroker-ipv6>` section. +::: + +## Generic Routing Encapsulation (GRE) + +{abbr}`GRE (Generic Routing Encapsulation)` is a versatile encapsulation +protocol defined in RFC 2784. Unlike simpler protocols such as IPIP, it allows +both IPv4 and IPv6 to be transported through the same tunnel. + +{abbr}`GRE (Generic Routing Encapsulation)` encapsulates original data packets +by adding a {abbr}`GRE (Generic Routing Encapsulation)` header, followed by an +IP header (the delivery header). The delivery header uses IP protocol number 47 +to identify {abbr}`GRE (Generic Routing Encapsulation)`-encapsulated traffic. + +In VyOS, {abbr}`GRE (Generic Routing Encapsulation)` tunnels can be established +over both IPv4 (encapsulation `gre`) and IPv6 (encapsulation `ip6gre`) +transport networks. + +### Configuration + +To configure a {abbr}`GRE (Generic Routing Encapsulation)` tunnel, you need to +define a tunnel source IP address, a tunnel destination IP address, an +encapsulation type ({abbr}`GRE (Generic Routing Encapsulation)`), and a tunnel +interface IP address. + +Example: + +The following example shows how to configure an IPv4/IPv6-over-IPv6 {abbr}`GRE +(Generic Routing Encapsulation)` tunnel between a VyOS router and a Linux host +running `systemd-networkd`. + +**VyOS router:** + +```none +set interfaces tunnel tun101 address '2001:db8:feed:beef::1/126' +set interfaces tunnel tun101 address '192.168.5.1/30' +set interfaces tunnel tun101 encapsulation 'ip6gre' +set interfaces tunnel tun101 source-address '2001:db8:babe:face::3afe:3' +set interfaces tunnel tun101 remote '2001:db8:9bb:3ce::5' +``` + +**Linux** `systemd-networkd`: + +The `systemd-networkd` setup requires two configuration files: `xxx.netdev` +to create the {abbr}`GRE (Generic Routing Encapsulation)` tunnel interface, and +`xxx.network` to assign IP addresses to it. + +```none +# cat /etc/systemd/network/gre-example.netdev +[NetDev] +Name=gre-example +Kind=ip6gre +MTUBytes=14180 + +[Tunnel] +Remote=2001:db8:babe:face::3afe:3 + + +# cat /etc/systemd/network/gre-example.network +[Match] +Name=gre-example + +[Network] +Address=2001:db8:feed:beef::2/126 + +[Address] +Address=192.168.5.2/30 +``` + + +### GRE keys + +A GRE key is an optional 32-bit field in the GRE header that allows multiple +GRE tunnels to operate between the same source and destination endpoints. When +a packet arrives, the receiver checks the GRE key to determine which tunnel +interface should process it. + +Although it may sound security-related, the GRE key is only an identifier and +provides no encryption or data protection. + +Example: + +```none +set interfaces tunnel tun0 source-address 192.0.2.10 +set interfaces tunnel tun0 remote 192.0.2.20 +set interfaces tunnel tun0 address 10.40.50.60/24 +set interfaces tunnel tun0 parameters ip key 10 +``` + +```none +set interfaces tunnel tun1 source-address 192.0.2.10 +set interfaces tunnel tun1 remote 192.0.2.20 +set interfaces tunnel tun1 address 172.16.17.18/24 +set interfaces tunnel tun1 parameters ip key 20 +``` + + +### GRETAP + +Unlike GRE, which encapsulates only Layer 3 (IP) traffic, GRETAP encapsulates +Layer 2 (Ethernet) frames. + +That means that GRETAP tunnel interfaces can be members of a bridge interface. +This allows two geographically distant sites to connect as if they were on the +same LAN. + +GRETAP tunnels can be established over both IPv4 and IPv6 transport networks. + +Example: + +```none +set interfaces bridge br0 member interface eth0 +set interfaces bridge br0 member interface tun0 +set interfaces tunnel tun0 encapsulation gretap +set interfaces tunnel tun0 source-address 198.51.100.2 +set interfaces tunnel tun0 remote 203.0.113.10 +``` + + +### Troubleshooting + +GRE is a standardized tunneling protocol used in many network environments. + +Although the GRE tunnel setup is straightforward, connectivity failures +frequently occur because ACLs or firewall rules block IP protocol 47 or +prevent direct communication between the tunnel endpoints. + +If your GRE tunnel fails to establish, perform these diagnostic steps: + +1\. Verify that the remote peer is reachable from the configured +`source-address`. + +This ensures that the underlying physical path between the two endpoints is +functional. + +```none +vyos@vyos:~$ ping 203.0.113.10 interface 198.51.100.2 count 4 +PING 203.0.113.10 (203.0.113.10) from 198.51.100.2 : 56(84) bytes of data. +64 bytes from 203.0.113.10: icmp_seq=1 ttl=254 time=0.807 ms +64 bytes from 203.0.113.10: icmp_seq=2 ttl=254 time=1.50 ms +64 bytes from 203.0.113.10: icmp_seq=3 ttl=254 time=0.624 ms +64 bytes from 203.0.113.10: icmp_seq=4 ttl=254 time=1.41 ms + +--- 203.0.113.10 ping statistics --- +4 packets transmitted, 4 received, 0% packet loss, time 3007ms +rtt min/avg/max/mdev = 0.624/1.087/1.509/0.381 ms +``` + +2\. Verify that the tunnel interface is correctly configured (with the link type +set to GRE) and is actively processing traffic. + +```none +vyos@vyos:~$ show interfaces tunnel tun100 +tun100@NONE: <POINTOPOINT,NOARP,UP,LOWER_UP> mtu 1476 qdisc noqueue state UNKNOWN group default qlen 1000 + link/gre 198.51.100.2 peer 203.0.113.10 + inet 10.0.0.1/30 brd 10.0.0.3 scope global tun100 + valid_lft forever preferred_lft forever + inet6 fe80::5efe:c612:2/64 scope link + valid_lft forever preferred_lft forever + + RX: bytes packets errors dropped overrun mcast + 2183 27 0 0 0 0 + TX: bytes packets errors dropped carrier collisions + 836 9 0 0 0 0 +``` + +3\. Test the connection through the tunnel using the private IP addresses +assigned to each tunnel endpoint. + +```none +vyos@vyos:~$ ping 10.0.0.2 interface 10.0.0.1 count 4 +PING 10.0.0.2 (10.0.0.2) from 10.0.0.1 : 56(84) bytes of data. +64 bytes from 10.0.0.2: icmp_seq=1 ttl=255 time=1.05 ms +64 bytes from 10.0.0.2: icmp_seq=2 ttl=255 time=1.88 ms +64 bytes from 10.0.0.2: icmp_seq=3 ttl=255 time=1.98 ms +64 bytes from 10.0.0.2: icmp_seq=4 ttl=255 time=1.98 ms + +--- 10.0.0.2 ping statistics --- +4 packets transmitted, 4 received, 0% packet loss, time 3008ms +rtt min/avg/max/mdev = 1.055/1.729/1.989/0.395 ms +``` + +[hurricane electric]: https://tunnelbroker.net/ +[other proposals]: https://www.isc.org/othersoftware/ diff --git a/docs/configuration/interfaces/virtual-ethernet.md b/docs/configuration/interfaces/virtual-ethernet.md new file mode 100644 index 00000000..dee1b332 --- /dev/null +++ b/docs/configuration/interfaces/virtual-ethernet.md @@ -0,0 +1,119 @@ +--- +lastproofread: '2026-01-26' +--- + +(virtual-ethernet)= + +# Virtual Ethernet + +Virtual Ethernet (veth) interfaces are software-based interfaces that operate +in pairs, creating a tunnel between each other. Traffic transmitted into one +interface of the pair (e.g., `veth0`) is delivered directly to its peer +interface (e.g., `veth1`). + +Veth interfaces are commonly used to connect network namespaces or VRFs, but +they can also function as standalone virtual network interfaces. + +:::{note} +Veth interfaces must be created in pairs, where each interface acts +as the peer of the other. +::: + +## Configuration + +### Common interface configuration + +```{cmdincludemd} /_include/interface-address-with-dhcp.txt +:var0: virtual-ethernet +:var1: veth0 +``` + +```{cmdincludemd} /_include/interface-description.txt +:var0: virtual-ethernet +:var1: veth0 +``` + + +### VLAN + +#### Regular VLANs (802.1q) + +```{cmdincludemd} /_include/interface-vlan-8021q.txt +:var0: virtual-ethernet +:var1: veth0 +``` + + +#### 802.1ad (QinQ) + +```{cmdincludemd} /_include/interface-vlan-8021ad.txt +:var0: virtual-ethernet +:var1: veth0 +``` + +```{cmdincludemd} /_include/interface-disable.txt +:var0: virtual-ethernet +:var1: veth0 +``` + +```{cmdincludemd} /_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 interface information. + +:::{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 + +The following example shows how to connect the global VRF to VRF ‘red ‘ using +the `veth10` and `veth11` veth pair. + +```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/vti.md b/docs/configuration/interfaces/vti.md new file mode 100644 index 00000000..dbd2c88c --- /dev/null +++ b/docs/configuration/interfaces/vti.md @@ -0,0 +1,121 @@ +(vti-interface)= + +# VTI (virtual tunnel interface) + +{abbr}`VTIs (virtual tunnel interfaces)` let you create secure, encrypted +tunnels between private networks or hosts across public infrastructure, such as +the Internet. They operate alongside an underlying IPsec tunnel, which handles +encapsulation and encryption, while VTIs function exclusively as routing +interfaces. + +## Configuration + +### Common interface configuration + +```{cmdincludemd} /_include/interface-address.txt +:var0: vti +:var1: vti0 +``` + +```{cmdincludemd} /_include/interface-description.txt +:var0: vti +:var1: vti0 +``` + +```{cmdincludemd} /_include/interface-disable.txt +:var0: vti +:var1: vti0 +``` + +```{cmdincludemd} /_include/interface-ip.txt +:var0: vti +:var1: vti0 +``` + +```{cmdincludemd} /_include/interface-ipv6.txt +:var0: vti +:var1: vti0 +``` + +```{cmdincludemd} /_include/interface-mtu.txt +:var0: vti +:var1: vti0 +``` + +```{cfgcmd} set interfaces vti \<interface\> mirror egress \<monitor-interface\> + +Configure mirroring of outgoing traffic from the specified VTI to the +designated monitor interface. +``` + +```{cfgcmd} set interfaces vti \<interface\> mirror ingress \<monitor-interface\> + +Configure mirroring of incoming traffic from the specified VTI to the +designated monitor interface. +``` + +```{cfgcmd} set interfaces vti \<interface\> redirect \<interface\> + +Enable redirection of incoming packets to the specified interface. +``` + +```{cmdincludemd} /_include/interface-vrf.txt +:var0: vti +:var1: vti0 +``` + + +## Operation + +```{opcmd} show interfaces vti \<vtiX\> + +Show the operational status and traffic statistics for the specified VTI. +``` + +```{opcmd} show interfaces vti \<vtiX\> brief + +Show a brief operational status summary for the specified VTI. +``` + + +## Example + +**Configure a VTI** + +Assign IPv4 and IPv6 addresses to the VTI, along with a brief description: + +```none +set interfaces vti vti0 address 192.168.2.249/30 +set interfaces vti vti0 address 2001:db8:2::249/64 +set interfaces vti vti0 description "Description" +``` + +Resulting configuration: + +```none +vyos@vyos# show interfaces vti +vti vti0 { + address 192.168.2.249/30 + address 2001:db8:2::249/64 + description "Description" +} +``` + +:::{warning} +When configuring site-to-site IPsec with VTIs, ensure that route +autoinstall is disabled. +::: + +```none +set vpn ipsec options disable-route-autoinstall +``` + +For more information about the IPsec and VTI issue, as well as the +`disable-route-autoinstall` option, see: +<https://blog.vyos.io/vyos-1-dot-2-0-development-news-in-july.> + +The root cause of the problem is that VTI tunnels require their traffic +selectors to be set to `0.0.0.0/0` for traffic to match the tunnel, even +though routing decisions are based on netfilter marks. Unless route insertion +is explicitly disabled, strongSWAN incorrectly inserts a default route through +the VTI peer address, causing all traffic to be misrouted. diff --git a/docs/configuration/interfaces/vxlan.md b/docs/configuration/interfaces/vxlan.md new file mode 100644 index 00000000..8dae75ff --- /dev/null +++ b/docs/configuration/interfaces/vxlan.md @@ -0,0 +1,373 @@ +--- +lastproofread: '2026-03-16' +--- + +(vxlan-interface)= + +# VXLAN + +{abbr}`VXLAN (Virtual Extensible LAN)` is a network virtualization technology +that addresses scalability challenges in large cloud computing environments. +It encapsulates Ethernet frames (Layer 2) within UDP datagrams (Layer 4), which +are then transmitted via UDP port 4789, as assigned by IANA. VXLAN endpoints, +called {abbr}`VTEPs (VXLAN tunnel endpoints)`, terminate VXLAN tunnels and can +be either virtual or physical switch ports. + +VXLAN supports up to 16 million logical networks and enables Layer 2 adjacency +across Layer 3 IP networks. It uses multicast or unicast with head-end +replication (HER) to flood broadcast, unknown unicast, and multicast (BUM) +traffic. + +The VXLAN specification was initially developed by VMware, Arista Networks, and +Cisco. Other supporters include Huawei, Broadcom, Citrix, Pica8, Big Switch +Networks, Cumulus Networks, Dell EMC, Ericsson, Mellanox, FreeBSD, OpenBSD, Red +Hat, Joyent, and Juniper Networks. + +VXLAN is officially documented by the IETF in {rfc}`7348`. + +When configuring VXLAN in a VyOS virtual machine, ensure that MAC spoofing +(Hyper-V) or Forged Transmits (ESX) are permitted. Otherwise, the hypervisor +may block forwarded frames. + +:::{note} +Although the IANA-assigned VXLAN port is **4789**, VyOS uses the +Linux default UDP port **8472** for VXLAN interfaces. To ensure compatibility +with other vendors, set the port to the IANA standard **4789**. +::: + +## Configuration + +### Common interface configuration + +```{cmdincludemd} /_include/interface-common-without-dhcp.txt +:var0: vxlan +:var1: vxlan0 +``` + + +### VXLAN-specific options + +```{cfgcmd} set interfaces vxlan \<interface\> vni \<number\> + +**Configure a** {abbr}`VNI (VXLAN Network Identifier)` **for the VXLAN +interface.** + +Each VXLAN segment is identified by this 24-bit VNI, allowing up to 16 million +segments to coexist within the same administrative domain. +``` + +```{cfgcmd} set interfaces vxlan \<interface\> port \<port\> + +Configure the UDP port of the remote VXLAN endpoint. + +:::{note} +Although the IANA-assigned VXLAN port is **4789**, VyOS uses the +Linux default UDP port **8472** for VXLAN interfaces. +::: +``` + +```{cfgcmd} set interfaces vxlan \<interface\> source-address \<address\> + +Configure the source IP address for the VXLAN underlay. + +:::{warning} +This setting is mandatory when deploying VXLAN via L2VPN/EVPN. +::: +``` + +```{cfgcmd} set interfaces vxlan \<interface\> gpe + +**Enable the** {abbr}`GPE (Generic Protocol Extension)` **for the VXLAN +interface.** + +To use this feature, you must configure the interface with the ``external`` +parameter. +``` + +```{cfgcmd} set interfaces vxlan \<interface\> parameters external + +**Configure the VXLAN interface to use an external control plane, such as BGP +L2VPN/EVPN, for remote endpoint discovery.** + +If not configured, the internal {abbr}`FDB (Forwarding Database)` is used. +``` + +```{cfgcmd} set interfaces vxlan \<interface\> parameters neighbor-suppress + +**Enable ARP and ND suppression on the VXLAN interface.** + +This reduces ARP and ND message flooding across the VXLAN network. As defined +in {rfc}`7432#section-10`, participating VTEPs use known MAC-to-IP bindings +to reply to local requests on behalf of remote hosts. +``` + +```{cfgcmd} set interfaces vxlan \<interface\> parameters nolearning + +Disable {abbr}`SLLA (Source Link-Layer Address)` and IP address learning on +the VXLAN interface. +``` + +```{cfgcmd} set interfaces vxlan \<interface\> parameters vni-filter + +**Enable** {abbr}`VNI (VXLAN Network Identifier)` **filtering on the VXLAN +interface.** + +When enabled, the interface only receives packets with VNIs configured in its +VNI filtering table. + +:::{note} +VNI filtering works only if the interface is configured with the +``external`` parameter. +::: +``` + + +#### Unicast + +```{cfgcmd} set interfaces vxlan \<interface\> remote \<address\> + +**Configure the IPv4 or IPv6 address of the remote VTEP.** + +Unlike multicast setups, this command allows you to directly configure the +remote IPv4 or IPv6 address. +``` + + +#### Multicast + +```{cfgcmd} set interfaces vxlan \<interface\> source-interface \<interface\> + +**Configure the source interface for the VXLAN underlay.** + +All VXLAN traffic is sent and received through the specified interface. +This setting is mandatory when deploying VXLAN over a multicast network. +``` + +```{cfgcmd} set interfaces vxlan \<interface\> group \<address\> + +**Configure the IPv4 or IPv6 multicast group address for the VXLAN interface.** + +VXLAN tunnels can be built using either multicast group or unicast IP addresses. +``` + + +## Multicast VXLAN + +Topology: PC4 - Leaf2 - Spine1 - Leaf3 - PC5 + +PC4 uses the IP address `10.0.0.4/24`, and PC5 uses the IP address +`10.0.0.5/24`. Both devices assume they reside within the same broadcast +domain. + +Assume PC4 on Leaf2 pings PC5 on Leaf3. Rather than manually specifying Leaf3 +as the remote endpoint, Leaf2 encapsulates the packet into a UDP datagram and +sends it to the designated multicast address via Spine1. Spine1 forwards the +packet to all leaves in the same multicast group, including Leaf3. Upon +receiving the datagram, Leaf3 forwards it to PC5 and learns that PC4 is +reachable through Leaf2 by inspecting the source IP in the encapsulated +datagram. + +PC5 receives the ping and responds with an echo reply. Leaf3, now aware of +PC4's location, forwards the reply directly to Leaf2's unicast address. Upon +receiving the echo reply, Leaf2 learns that PC5 is reachable through Leaf3. + +After this discovery, subsequent traffic between PC4 and PC5 will not use the +multicast address between the leaves, as both leaves have learned the PCs' +locations. This reduces multicast traffic and network load, improving +scalability as more leaves are added. + +## Single VXLAN device (SVD) + +In VyOS, you can configure multiple **VLAN-to-VNI mappings** for EVPN-VXLAN on +a single container interface, known as a single VXLAN device (SVD). This +enables significant VNI scaling because a separate VXLAN interface is not +required for each VNI. + +```{cfgcmd} set interfaces vxlan \<interface\> vlan-to-vni \<vlan\> vni \<vni\> + +**Map a VLAN ID to a VNI on the specified VXLAN interface.** + +The VXLAN interface can be added to a bridge. + +The following example shows an SVD configuration with multiple VLAN-to-VNI +mappings. + +:::{code-block} none +set interfaces bridge br0 member interface vxlan0 +set interfaces vxlan vxlan0 parameters external +set interfaces vxlan vxlan0 source-interface 'dum0' +set interfaces vxlan vxlan0 vlan-to-vni 10 vni '10010' +set interfaces vxlan vxlan0 vlan-to-vni 11 vni '10011' +set interfaces vxlan vxlan0 vlan-to-vni 30 vni '10030' +set interfaces vxlan vxlan0 vlan-to-vni 31 vni '10031' +::: +``` + + +### Example + +The following example demonstrates a multicast VXLAN deployment. + +The setup includes three routers: Spine1, a Cisco IOS router, and Leaf2 and +Leaf3, which are VyOS routers. + +**Topology:** Leaf2 - Spine1 - Leaf3. + +The topology is built using GNS3. + +```none +Spine1: +fa0/2 towards Leaf2, IP-address: 10.1.2.1/24 +fa0/3 towards Leaf3, IP-address: 10.1.3.1/24 + +Leaf2: +Eth0 towards Spine1, IP-address: 10.1.2.2/24 +Eth1 towards a VLAN-aware switch + +Leaf3: +Eth0 towards Spine1, IP-address 10.1.3.3/24 +Eth1 towards a VLAN-aware switch +``` + +**Spine1 configuration:** + +```none +conf t +ip multicast-routing +! +interface fastethernet0/2 + ip address 10.1.2.1 255.255.255.0 + ip pim sparse-dense-mode +! +interface fastethernet0/3 + ip address 10.1.3.1 255.255.255.0 + ip pim sparse-dense-mode +! +router ospf 1 + network 10.0.0.0 0.255.255.255 area 0 +``` + +Multicast routing is required for scalable traffic forwarding between leaves. +{abbr}`PIM (Protocol Independent Multicast)` must be enabled towards the leaves +so the spine can learn from which multicast groups each leaf expects traffic. + +**Leaf2 configuration:** + +```none +set interfaces ethernet eth0 address '10.1.2.2/24' +set protocols ospf area 0 network '10.0.0.0/8' + +! First VXLAN interface +set interfaces bridge br241 address '172.16.241.1/24' +set interfaces bridge br241 member interface 'eth1.241' +set interfaces bridge br241 member interface 'vxlan241' + +set interfaces vxlan vxlan241 group '239.0.0.241' +set interfaces vxlan vxlan241 source-interface 'eth0' +set interfaces vxlan vxlan241 vni '241' + +! Second VXLAN interface +set interfaces bridge br242 address '172.16.242.1/24' +set interfaces bridge br242 member interface 'eth1.242' +set interfaces bridge br242 member interface 'vxlan242' + +set interfaces vxlan vxlan242 group '239.0.0.242' +set interfaces vxlan vxlan242 source-interface 'eth0' +set interfaces vxlan vxlan242 vni '242' +``` + +**Leaf3 configuration:** + +```none +set interfaces ethernet eth0 address '10.1.3.3/24' +set protocols ospf area 0 network '10.0.0.0/8' + +! First VXLAN interface +set interfaces bridge br241 address '172.16.241.1/24' +set interfaces bridge br241 member interface 'eth1.241' +set interfaces bridge br241 member interface 'vxlan241' + +set interfaces vxlan vxlan241 group '239.0.0.241' +set interfaces vxlan vxlan241 source-interface 'eth0' +set interfaces vxlan vxlan241 vni '241' + +! Second VXLAN interface +set interfaces bridge br242 address '172.16.242.1/24' +set interfaces bridge br242 member interface 'eth1.242' +set interfaces bridge br242 member interface 'vxlan242' + +set interfaces vxlan vxlan242 group '239.0.0.242' +set interfaces vxlan vxlan242 source-interface 'eth0' +set interfaces vxlan vxlan242 vni '242' +``` + +The configurations for Leaf2 and Leaf3 are nearly identical. Detailed +explanations for each command are provided below. + +```none +set interfaces bridge br241 address '172.16.241.1/24' +``` + +This command creates a bridge to bind traffic on `eth1` VLAN 241 with the +`vxlan241` interface. The IP address is optional. If configured, it can serve +as the default gateway for each leaf, allowing devices on the VLAN to reach +other subnets. Subnets must be redistributed by {abbr}`OSPF (Open Shortest Path +First)` so the spine can learn how to reach them. To advertise `172.16/12` +networks, change the {abbr}`OSPF (Open Shortest Path First)` network from +`10.0.0.0/8` to `0.0.0.0/0`. + +```none +set interfaces bridge br241 member interface 'eth1.241' +set interfaces bridge br241 member interface 'vxlan241' +``` + +These commands bind `eth1.241` and `vxlan241` as member interfaces of the +same bridge. + +```none +set interfaces vxlan vxlan241 group '239.0.0.241' +``` + +This command configures the multicast group used by all leaves for this VLAN +extension. It must be the same on all leaves that have this interface. + +```none +set interfaces vxlan vxlan241 source-interface 'eth0' +``` + +This command configures the interface that listens for multicast packets. It +can also be a loopback interface. + +```none +set interfaces vxlan vxlan241 vni '241' +``` + +This command configures the unique ID for the VXLAN interface. + +```none +set interfaces vxlan vxlan241 port 12345 +``` + +VyOS uses the Linux default UDP port **8472** for VXLAN interfaces. This +command allows you to configure a different UDP port. + +## Unicast VXLAN + +As an alternative to multicast, you can configure the VXLAN tunnel by +specifying the remote IPv4 address directly. The following updates the previous +multicast example: + +```none +# leaf2 and leaf3 +delete interfaces vxlan vxlan241 group '239.0.0.241' +delete interfaces vxlan vxlan241 source-interface 'eth0' + +# leaf2 +set interfaces vxlan vxlan241 remote 10.1.3.3 + +# leaf3 +set interfaces vxlan vxlan241 remote 10.1.2.2 +``` + +The default UDP port is 8472. To configure a different port, use `set +interfaces vxlan <vxlanN> port <port>`. diff --git a/docs/configuration/interfaces/wireguard.md b/docs/configuration/interfaces/wireguard.md new file mode 100644 index 00000000..121d1df0 --- /dev/null +++ b/docs/configuration/interfaces/wireguard.md @@ -0,0 +1,434 @@ +--- +lastproofread: '2026-03-02' +--- + +(wireguard)= + +# WireGuard + +WireGuard is an extremely simple, fast, and modern VPN that utilizes +state-of-the-art cryptography. See <https://www.wireguard.com> for more +information. + +## Site-to-site VPN + +The following diagram illustrates a site-to-site VPN setup. + +:::{figure} /_static/images/wireguard_site2site_diagram.webp +::: + +## Keypairs + +WireGuard requires a keypair, which includes a **private** key +to decrypt incoming traffic, and a **public** key for peer(s) to encrypt +outgoing traffic. + +### Generate keypair + +```{opcmd} generate pki wireguard key-pair + +Generate a keypair: a public and a private key. + +:::{note} +This command only outputs the keys to your console. It neither stores +them in the system nor applies them to the system configuration. +::: + +:::{code-block} none +vyos@vyos:~$ generate pki wireguard key-pair +Private key: iJJyEARGK52Ls1GYRCcFvPuTj7WyWYDo//BknoDU0XY= +Public key: EKY0dxRrSD98QHjfHOK13mZ5PJ7hnddRZt5woB3szyw= +::: +``` + + +```{opcmd} generate pki wireguard key-pair install interface \<interface\> + +Generate a keypair and output the private key assignment command for the +specified interface. + +:::{code-block} none +vyos@vyos:~$ generate pki wireguard key-pair install interface wg10 +"generate" CLI command executed from operational level. +Generated private key is not automatically added to the VyOS configuration, use the following configuration mode commands to install key: + +set interfaces wireguard wg10 private-key '4Krkv8h6NkAYMMaBWI957yYDJDMvj9URTHstdlOcDU0=' + +Corresponding public-key to use on peer system is: 'UxDsYT6EnpTIOKUzvMlw2p0sNOKQvFxEdSVrnNrX1Ro=' +::: + +:::{note} +If you invoke this command from configuration mode with the ``run`` +prefix, the generated private key is automatically assigned to the specified +interface. +::: + +:::{code-block} none +vyos@vyos# run generate pki wireguard key-pair install interface wg10 +"generate" CLI command executed from config session. +Generated private-key was imported to CLI! + +Use the following command to verify: show interfaces wireguard wg10 +Corresponding public-key to use on peer system is: '7d9KwabjLhHpJiEJeIGd0CBlao/eTwFOh6xyCovTfG8=' + +vyos@vyos# compare +[edit interfaces] ++wireguard wg10 { ++ private-key CJweb8FC6BU3Loj4PC2pn5V82cDjIPs7G1saW0ZfLWc= ++} +::: +``` + + +```{opcmd} show interfaces wireguard \<interface\> public-key + +Show the public key assigned to the interface. + +:::{code-block} none +vyos@vyos:~$ show interfaces wireguard wg01 public-key +EKY0dxRrSD98QHjfHOK13mZ5PJ7hnddRZt5woB3szyw= +::: +``` + +#### Optional + +```{opcmd} generate pki wireguard preshared-key + +Generate a pre-shared key. + +The pre-shared key is optional. It adds an additional layer of symmetric-key +cryptography on top of the asymmetric cryptography. + +:::{code-block} none +vyos@vyos:~$ generate pki wireguard preshared-key +Pre-shared key: OHH2EwZfMNK+1L6BXbYw3bKCtMrfjpR4mCAEeBlFnRs= +::: +``` + +```{opcmd} generate pki wireguard preshared-key install interface \<interface\> peer \<peer\> + +Generate a pre-shared key and output the key assignment command for the +specified peer. + +:::{code-block} none +vyos@vyos:~$ generate pki wireguard preshared-key install interface wg10 peer foo +"generate" CLI command executed from operational level. +Generated preshared-key is not stored to CLI, use configure mode commands to install key: + +set interfaces wireguard wg10 peer foo preshared-key '32vQ1w1yFKTna8n7Gu7EimubSe2Y63m8bafz55EG3Ro=' + +Pre-shared key: +LuaZ8W6DjsDFJFX3jJzoNqrsXHhvq08JztM9z8LHCs= +::: + +:::{note} +If you invoke this command from configuration mode with the run +prefix, the generated key is automatically assigned to the specified peer. +::: +``` + +## Interface configuration + +The next step is to configure your local WireGuard interface and define the +networks you want to tunnel (`allowed-ips`). + +If your system only initiates connections, specifying the listen port is +optional. If your system accepts incoming connections, you must define a port +for peers to connect to. Otherwise, WireGuard selects a random port at each +reboot, and that may break your peers' ability to connect if that port is not enabled in your firewall rules. + +To configure a WireGuard tunnel, you also need your peer's public key. + +:::{note} +The public key specified in the peer configuration block is always +the **remote** peer's public key, never your local one. +::: + +**Local side configuration** + +The local side is configured with the following parameters: +- Local WireGuard interface IP: `10.1.0.1/30` +- Local listen port: `51820` +- Remote peer name: `to-wg02` +- Remote peer endpoint: `192.0.2.1` on port `51820` +- Remote peer public key: `XMrlPykaxhdAAiSjhtPlvi30NVkvLQliQuKP7AI7CyI=` +- Allowed networks: `192.168.2.0/24` + +```none +set interfaces wireguard wg01 address '10.1.0.1/30' +set interfaces wireguard wg01 description 'VPN-to-wg02' +set interfaces wireguard wg01 peer to-wg02 allowed-ips '192.168.2.0/24' +set interfaces wireguard wg01 peer to-wg02 address '192.0.2.1' +set interfaces wireguard wg01 peer to-wg02 port '51820' +set interfaces wireguard wg01 peer to-wg02 public-key 'XMrlPykaxhdAAiSjhtPlvi30NVkvLQliQuKP7AI7CyI=' +set interfaces wireguard wg01 port '51820' + +set protocols static route 192.168.2.0/24 interface wg01 +``` + +To send traffic destined for `192.168.2.0/24` through the WireGuard interface +(`wg01`), configure a static route. Multiple IP addresses or networks can be +defined and routed. The final check is performed against `allowed-ips`, which +either permits or drops the traffic. + +:::{warning} +You cannot assign the same `allowed-ips` to multiple WireGuard +peers. This is a strict design restriction. For more information, check the +[WireGuard mailing list]. +::: + +```{cfgcmd} set interfaces wireguard \<interface\> private-key \<private-key\> + +Assign a private key to the specified WireGuard interface. + +Example: + +:::{code-block} none +set interfaces wireguard wg01 private-key 'iJJyEARGK52Ls1GYRCcFvPuTj7WyWYDo//BknoDU0XY=' +::: + +To generate a private key, use the following command: +{opcmd}`generate pki wireguard key-pair`. + +To view the public key assigned to the interface so you can share it with a +peer, use the following command: +{opcmd}`show interfaces wireguard wg01 public-key`. +``` + + +```{cmdincludemd} /_include/interface-per-client-thread.txt +:var0: wireguard +:var1: wg01 +``` + +**Remote side configuration** + +```none +set interfaces wireguard wg01 address '10.1.0.2/30' +set interfaces wireguard wg01 description 'VPN-to-wg01' +set interfaces wireguard wg01 peer to-wg01 allowed-ips '192.168.1.0/24' +set interfaces wireguard wg01 peer to-wg01 address '192.0.2.2' +set interfaces wireguard wg01 peer to-wg01 port '51820' +set interfaces wireguard wg01 peer to-wg01 public-key 'EKY0dxRrSD98QHjfHOK13mZ5PJ7hnddRZt5woB3szyw=' +set interfaces wireguard wg01 port '51820' +set interfaces wireguard wg01 private-key 'OLTQY3HuK5qWDgVs6fJR093SwPgOmCKkDI1+vJLGoFU=' + +set protocols static route 192.168.1.0/24 interface wg01 +``` + +## Firewall exceptions + + +To allow WireGuard traffic through the WAN interface, create a firewall +exception: + +```none +set firewall ipv4 name OUTSIDE_LOCAL rule 10 action accept +set firewall ipv4 name OUTSIDE_LOCAL rule 10 description 'Allow established/related' +set firewall ipv4 name OUTSIDE_LOCAL rule 10 state established enable +set firewall ipv4 name OUTSIDE_LOCAL rule 10 state related enable +set firewall ipv4 name OUTSIDE_LOCAL rule 20 action accept +set firewall ipv4 name OUTSIDE_LOCAL rule 20 description WireGuard_IN +set firewall ipv4 name OUTSIDE_LOCAL rule 20 destination port 51820 +set firewall ipv4 name OUTSIDE_LOCAL rule 20 log enable +set firewall ipv4 name OUTSIDE_LOCAL rule 20 protocol udp +``` + +Ensure that the OUTSIDE_LOCAL firewall group is applied to the WAN interface +and in an input (local) direction. + +```none +set firewall ipv4 input filter rule 10 action jump +set firewall ipv4 input filter rule 10 jump-target 'OUTSIDE_LOCAL' +set firewall ipv4 input filter rule 10 inbound-interface name 'eth0' +``` + +Verify that your firewall rules permit traffic. If so, your WireGuard VPN +should be operational. + +```none +wg01# ping 192.168.1.1 +PING 192.168.1.1 (192.168.1.1) 56(84) bytes of data. +64 bytes from 192.168.1.1: icmp_seq=1 ttl=64 time=1.16 ms +64 bytes from 192.168.1.1: icmp_seq=2 ttl=64 time=1.77 ms + +wg02# ping 192.168.2.1 +PING 192.168.2.1 (192.168.2.1) 56(84) bytes of data. +64 bytes from 192.168.2.1: icmp_seq=1 ttl=64 time=4.40 ms +64 bytes from 192.168.2.1: icmp_seq=2 ttl=64 time=1.02 ms +``` + +An additional layer of symmetric-key cryptography can be used on top of the +asymmetric cryptography. This is optional. + +```none +vyos@vyos:~$ generate pki wireguard preshared-key +Pre-shared key: rvVDOoc2IYEnV+k5p7TNAmHBMEGTHbPU8Qqg8c/sUqc= +``` + +Copy the key, as it is not stored locally. Since it is a symmetric key, only +you and your peer should know its contents. Distribute the key securely. + +```none +wg01# set interfaces wireguard wg01 peer to-wg02 preshared-key 'rvVDOoc2IYEnV+k5p7TNAmHBMEGTHbPU8Qqg8c/sUqc=' +wg02# set interfaces wireguard wg01 peer to-wg01 preshared-key 'rvVDOoc2IYEnV+k5p7TNAmHBMEGTHbPU8Qqg8c/sUqc=' +``` + +## Remote access (road warrior) + + +With WireGuard, a road warrior VPN configuration is similar to a site-to-site +VPN. It just omits the `address` and `port` statements. + + +In the following example, the IP addresses for remote clients are defined +within each peer configuration. This allows peers to communicate with each +other. + + +Additionally, this setup uses a `persistent-keepalive` flag set to 15 seconds +to keep the connection alive. This setting is mainly relevant if a peer is +behind NAT and cannot be reached if the connection is lost. For effectiveness, +the value should be lower than the UDP timeout. + +```none +wireguard wg01 { + address 10.172.24.1/24 + address 2001:db8:470:22::1/64 + description RoadWarrior + peer MacBook { + allowed-ips 10.172.24.30/32 + allowed-ips 2001:db8:470:22::30/128 + persistent-keepalive 15 + pubkey F5MbW7ye7DsoxdOaixjdrudshjjxN5UdNV+pGFHqehc= + } + peer iPhone { + allowed-ips 10.172.24.20/32 + allowed-ips 2001:db8:470:22::20/128 + persistent-keepalive 15 + pubkey BknHcLFo8nOo8Dwq2CjaC/TedchKQ0ebxC7GYn7Al00= + } + port 2224 + private-key OLTQY3HuK5qWDgVs6fJR093SwPgOmCKkDI1+vJLGoFU= +} +``` + +Below is the configuration for the iPhone peer. The `AllowedIPs` wildcard +setting directs all IPv4 and IPv6 traffic through the VPN connection. + +```none +[Interface] +PrivateKey = ARAKLSDJsadlkfjasdfiowqeruriowqeuasdf= +Address = 10.172.24.20/24, 2001:db8:470:22::20/64 +DNS = 10.0.0.53, 10.0.0.54 + +[Peer] +PublicKey = RIbtUTCfgzNjnLNPQ/ulkGnnB2vMWHm7l2H/xUfbyjc= +AllowedIPs = 0.0.0.0/0, ::/0 +Endpoint = 192.0.2.1:2224 +PersistentKeepalive = 15 +``` + +To enable split tunneling, specify the remote subnets. This ensures that only +traffic destined for the remote site is sent through the tunnel, while all +other traffic remains unaffected. + +```none +[Interface] +PrivateKey = 8Iasdfweirousd1EVGUk5XsT+wYFZ9mhPnQhmjzaJE6Go= +Address = 10.172.24.30/24, 2001:db8:470:22::30/64 + +[Peer] +PublicKey = RIbtUTCfgzNjnLNPQ/ulkGnnB2vMWHm7l2H/xUfbyjc= +AllowedIPs = 10.172.24.30/24, 2001:db8:470:22::/64 +Endpoint = 192.0.2.1:2224 +PersistentKeepalive = 15 +``` + +## Operational commands + + +### Status + +```{opcmd} show interfaces wireguard wg01 summary + +Show information about the WireGuard service, including the latest handshake. + +:::{code-block} none +vyos@vyos:~$ show interfaces wireguard wg01 summary +interface: wg01 +public key: +private key: (hidden) +listening port: 51820 + +peer: <peer pubkey> +endpoint: <peer public IP> +allowed ips: 10.69.69.2/32 +latest handshake: 23 hours, 45 minutes, 26 seconds ago +transfer: 1.26 MiB received, 6.47 MiB sent +::: +``` + + +```{opcmd} show interfaces wireguard + +Show a list of all WireGuard interfaces. + +:::{code-block} none +Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down +Interface IP Address S/L Description +--------- ---------- --- ----------- +wg01 10.0.0.1/24 u/u +::: +``` + +```{opcmd} show interfaces wireguard \<interface\> + +Show general information about a specific WireGuard interface. + +:::{code-block} none +vyos@vyos:~$ show interfaces wireguard wg01 +interface: wg01 +address: 10.0.0.1/24 +public key: h1HkYlSuHdJN6Qv4Hz4bBzjGg5WUty+U1L7DJsZy1iE= +private key: (hidden) +listening port: 41751 +RX: bytes packets errors dropped overrun mcast +0 0 0 0 0 0 +TX: bytes packets errors dropped carrier collisions +0 0 0 0 0 0 +::: +``` + +## Remote access (road warrior) clients + +Some users connect mobile devices to their VyOS router using WireGuard. To +simplify deployment, generate a per-mobile configuration from the VyOS CLI. + +:::{warning} +From a security perspective, it is not recommended to let a third +party create and share the private key for a secure connection. You should +create the private portion yourself and hand out only the public key. +::: + +```{opcmd} generate wireguard client-config \<name\> interface \<interface\> server \<ip|fqdn\> address \<client-ip\> + +**Generate a client configuration file that establishes a connection to the +specified interface.** + +The public key from the specified interface is automatically included in the +configuration file. + +The command also generates a configuration snippet that can be copied into the +VyOS CLI. The ``<name>`` you provide will be used as the peer name in the +snippet. + +You must also specify the IP address or FQDN of the server the client connects +to. The address parameter can be used twice to assign both an IPv4 (/32) and +an IPv6 (/128) address to the client. + +:::{figure} /_static/images/wireguard_qrcode.webp +:alt: WireGuard Client QR code +::: +``` + +[wireguard mailing list]: https://lists.zx2c4.com/pipermail/wireguard/2018-December/003704.html diff --git a/docs/configuration/interfaces/wireless.md b/docs/configuration/interfaces/wireless.md new file mode 100644 index 00000000..9e6b7c99 --- /dev/null +++ b/docs/configuration/interfaces/wireless.md @@ -0,0 +1,923 @@ +--- +lastproofread: '2026-03-23' +--- + +(wireless-interface)= + +# Wireless LAN / Wi-Fi + +{abbr}`WLAN (Wireless LAN)` interfaces provide 802.11 (a/b/g/n/ac) wireless +connectivity, referred to as Wi-Fi, and operate in one of the following +modes: + +- {abbr}`WAP (Wireless Access-Point)` mode provides network access to connecting + stations if the physical hardware supports acting as a WAP +- Station mode acts as a Wi-Fi client accessing the network through an available + WAP +- Monitor mode lets the system passively monitor wireless traffic + +If the system detects an unconfigured wireless device, it will be automatically +added to the configuration tree, specifying any detected settings (for example, +its MAC address) and configured to run in monitor mode. + +## Configuration + +### Common interface configuration + +```{cmdincludemd} /_include/interface-common-with-dhcp.txt +:var0: wireless +:var1: wlan0 +``` + + +### System-wide configuration + +```{cfgcmd} set system wireless country-code \<cc\> + +Country code (ISO/IEC 3166-1). Used to set regulatory domain. Set as needed +to indicate country in which device is operating. This can limit available +channels and transmit power. + +:::{note} +This option is mandatory in ``access-point`` mode. +::: +``` + + +### Wireless options + +```{cfgcmd} set interfaces wireless \<interface\> channel \<number\> + +Configure the IEEE 802.11 wireless radio channel for the interface. +Channel allocation depends on the frequency band: +* **2.4 GHz** (802.11b/g/n/ax): Channels range from 1 to 14. +* **5 GHz** (802.11a/h/j/n/ac/ax): Channels range from 34 to 177. +* **6 GHz** (802.11ax): Channels range from 1 to 233. +* **Automatic channel selection:** 0. +``` + +```{cfgcmd} set interfaces wireless \<interface\> disable-broadcast-ssid + +Send empty SSID in beacons and ignore probe request frames that do not specify +full SSID, i.e., require stations to know the SSID. +``` + +```{cfgcmd} set interfaces wireless \<interface\> expunge-failing-stations + +Disassociate stations based on excessive transmission failures or other +indications of connection loss. + +This depends on the driver capabilities and may not be available with all +drivers. +``` + +```{cfgcmd} set interfaces wireless \<interface\> isolate-stations + +Client isolation can be used to prevent low-level bridging of frames between +associated stations in the BSS. + +By default, this bridging is allowed. +``` + +```{cfgcmd} set interfaces wireless \<interface\> max-stations \<count\> + +Maximum number of stations allowed in station table. New stations will be +rejected after the station table is full. IEEE 802.11 has a limit of 2007 +different association IDs, so this number should not be larger than that. + +This defaults to 2007. +``` + +```{cfgcmd} set interfaces wireless \<interface\> mgmt-frame-protection + +Management Frame Protection (MFP) according to IEEE 802.11w + +:::{note} +{abbr}`MFP (Management Frame Protection)` is required for WPA3. +::: +``` + +```{cfgcmd} set interfaces wireless \<interface\> enable-bf-protection + +Beacon Protection: management frame protection for Beacon frames. + +:::{note} +This option requires {abbr}`MFP (Management Frame Protection)` +to be enabled. +::: +``` + +```{cfgcmd} set interfaces wireless \<interface\> mode \<a | b | g | n | ac | ax\> + +Operation mode of wireless radio. +* ``a`` - 802.11a - 54 Mbits/sec +* ``b`` - 802.11b - 11 Mbits/sec +* ``g`` - 802.11g - 54 Mbits/sec (default) +* ``n`` - 802.11n - 600 Mbits/sec +* ``ac`` - 802.11ac - 1300 Mbits/sec +* ``ax`` - 802.11ax - exceeds 1GBit/sec + +:::{note} +In VyOS, 802.11ax is only implemented for 2.4GHz and 6GHz. +::: +``` + +```{cfgcmd} set interfaces wireless \<interface\> physical-device \<device\> + +Wireless hardware device used as underlay radio. + +This defaults to phy0. +``` + +```{cfgcmd} set interfaces wireless \<interface\> reduce-transmit-power \<number\> + +Adds the Power Constraint information element to Beacon and Probe Response +frames. + +This option adds the Power Constraint information element when applicable +and the Country information element is configured. The Power Constraint +element is required by Transmit Power Control. + +Valid values are 0..255. +``` + +```{cfgcmd} set interfaces wireless \<interface\> ssid \<ssid\> + +SSID to be used in IEEE 802.11 management frames +``` + +```{cfgcmd} set interfaces wireless \<interface\> type \<access-point | station | monitor\> + +Wireless device type for this interface +* ``access-point``: Forwards packets between other nodes. +* ``station``: Connects to another {abbr}`AP (Access Point)`. +* ``monitor``: Passively monitors all packets on the frequency/channel. +``` + +```{cmdincludemd} /_include/interface-per-client-thread.txt +:var0: wireless +:var1: wlan0 +``` + + +#### PPDU + +```{cfgcmd} set interfaces wireless \<interface\> capabilities require-ht + +``` +```{cfgcmd} set interfaces wireless \<interface\> capabilities require-vht +``` + +```{cfgcmd} set interfaces wireless \<interface\> capabilities require-he +``` + +##### HT (High Throughput) capabilities (802.11n) + +> Configuring HT mode options is required when using 802.11n or +> 802.11ax at 2.4GHz. + +```{cfgcmd} set interfaces wireless \<interface\> capabilities ht 40mhz-incapable + +Device is incapable of 40 MHz, do not advertise. This sets ``[40-INTOLERANT]`` +``` + +```{cfgcmd} set interfaces wireless \<interface\> capabilities ht auto-powersave + +WMM-PS Unscheduled Automatic Power Save Delivery [U-APSD] +``` + +```{cfgcmd} set interfaces wireless \<interface\> capabilities ht channel-set-width \<ht20 | ht40+ | ht40-\> + +Supported channel width set. +* ``ht20`` - 20 MHz channel width +* ``ht40-`` - Both 20 MHz and 40 MHz with secondary channel below the primary +channel +* ``ht40+`` - Both 20 MHz and 40 MHz with secondary channel above the primary +channel + +:::{note} +Channel availability for HT40- and HT40+ is limited. The following +table lists channels permitted for HT40- and HT40+ according to IEEE +802.11n Annex J. Channel availability may vary by location. + + ::::{code-block} none + freq HT40- HT40+ + 2.4 GHz 5-13 1-7 (1-9 in Europe/Japan) + 5 GHz 40,48,56,64 36,44,52,60 + :::: +::: + +:::{note} +40 MHz channels may switch their primary and secondary channels if +needed or creation of 40 MHz channel may be rejected based on overlapping +BSSes. These changes are done automatically when hostapd is setting up the +40 MHz channel. +::: +``` + +```{cfgcmd} set interfaces wireless \<interface\> capabilities ht delayed-block-ack + +Enable HT-delayed Block Ack ``[DELAYED-BA]`` +``` + +```{cfgcmd} set interfaces wireless \<interface\> capabilities ht dsss-cck-40 + +DSSS/CCK Mode in 40 MHz, this sets ``[DSSS_CCK-40]`` +``` + +```{cfgcmd} set interfaces wireless \<interface\> capabilities ht greenfield + +This enables the greenfield option which sets the ``[GF]`` option +``` + +```{cfgcmd} set interfaces wireless \<interface\> capabilities ht ldpc + +Enable LDPC coding capability +``` + +```{cfgcmd} set interfaces wireless \<interface\> capabilities ht lsig-protection + +Enable L-SIG TXOP protection capability +``` + +```{cfgcmd} set interfaces wireless \<interface\> capabilities ht max-amsdu \<3839 | 7935\> + +Maximum A-MSDU length 3839 (default) or 7935 octets +``` + +```{cfgcmd} set interfaces wireless \<interface\> capabilities ht short-gi \<20 | 40\> + +Short GI capabilities for 20 and 40 MHz +``` + +```{cfgcmd} set interfaces wireless \<interface\> capabilities ht smps \<static | dynamic\> + +Spatial Multiplexing Power Save (SMPS) settings +``` + +```{cfgcmd} set interfaces wireless \<interface\> capabilities ht stbc rx \<num\> + +Enable receiving PPDU using STBC (Space Time Block Coding) +``` + +```{cfgcmd} set interfaces wireless \<interface\> capabilities ht stbc tx + +Enable sending PPDU using STBC (Space Time Block Coding) +``` + +##### VHT (Very High Throughput) capabilities (802.11ac) + +```{cfgcmd} set interfaces wireless \<interface\> capabilities vht antenna-count \<count\> +``` + +% +% Number of antennas on this card + +```{cfgcmd} set interfaces wireless \<interface\> capabilities vht antenna-pattern-fixed + +Set if antenna pattern does not change during the lifetime of an association +``` + +```{cfgcmd} set interfaces wireless \<interface\> capabilities vht beamform \<single-user-beamformer | single-user-beamformee | multi-user-beamformer | multi-user-beamformee> + +Beamforming capabilities: +* ``single-user-beamformer`` - Support for operation as +single user beamformer +* ``single-user-beamformee`` - Support for operation as +single user beamformee +* ``multi-user-beamformer`` - Support for operation as +multi user beamformer +* ``multi-user-beamformee`` - Support for operation as +multi user beamformee +``` + +```{cfgcmd} set interfaces wireless \<interface\> capabilities vht center-channel-freq \<freq-1 | freq-2\> \<number\> + +VHT operating channel center frequency - center freq 1 +(for use with 80, 80+80 and 160 modes) + +VHT operating channel center frequency - center freq 2 +(for use with the 80+80 mode) + +\<number\> must be from 34 - 173. For 80 MHz channels it should be channel + 6. +``` + +```{cfgcmd} set interfaces wireless \<interface\> capabilities vht channel-set-width \<0 | 1 | 2 | 3\> + +* ``0`` - 20 or 40 MHz channel width (default) +* ``1`` - 80 MHz channel width +* ``2`` - 160 MHz channel width +* ``3`` - 80+80 MHz channel width +``` + +```{cfgcmd} set interfaces wireless \<interface\> capabilities vht ldpc + +Enable LDPC (Low Density Parity Check) coding capability +``` + +```{cfgcmd} set interfaces wireless \<interface\> capabilities vht link-adaptation + +VHT link adaptation capabilities +``` + +```{cfgcmd} set interfaces wireless \<interface\> capabilities vht max-mpdu \<value\> + +Increase Maximum MPDU length to 7991 or 11454 octets (default 3895 octets) +``` + +```{cfgcmd} set interfaces wireless \<interface\> capabilities vht max-mpdu-exp \<value\> + +Set the maximum length of A-MPDU pre-EOF padding that the station can +receive +``` + +```{cfgcmd} set interfaces wireless \<interface\> capabilities vht short-gi \<80 | 160\> + +Short GI capabilities +``` + +```{cfgcmd} set interfaces wireless \<interface\> capabilities vht stbc rx \<num\> + +Enable receiving PPDU using STBC (Space Time Block Coding) +``` + +```{cfgcmd} set interfaces wireless \<interface\> capabilities vht stbc tx + +Enable sending PPDU using STBC (Space Time Block Coding) +``` + +```{cfgcmd} set interfaces wireless \<interface\> capabilities vht tx-powersave + +Enable VHT TXOP Power Save Mode +``` + +```{cfgcmd} set interfaces wireless \<interface\> capabilities vht vht-cf + +Station supports receiving VHT variant HT Control field +``` + +##### HE (High Efficiency) capabilities (802.11ax) + +```{cfgcmd} set interfaces wireless \<interface\> capabilities he antenna-pattern-fixed + +Tell the AP that antenna positions are fixed and will not change +during the lifetime of an association. +``` + +```{cfgcmd} set interfaces wireless \<interface\> capabilities he beamform \<single-user-beamformer | single-user-beamformee | multi-user-beamformer\> + +Beamforming capabilities: +* ``single-user-beamformer`` - Support for operation as +single user beamformer +* ``single-user-beamformee`` - Support for operation as +single user beamformee +* ``multi-user-beamformer`` - Support for operation as multi +user beamformer +``` + +```{cfgcmd} set interfaces wireless \<interface\> capabilities he bss-color \<number\> + +BSS coloring helps to prevent channel jamming when multiple APs use +the same channels. + +Valid values are 1..63 +``` + +```{cfgcmd} set interfaces wireless \<interface\> capabilities he center-channel-freq \<freq-1 | freq-2\> \<number\> + +HE operating channel center frequency - center freq 1 +(for use with 80, 80+80 and 160 modes) + +HE operating channel center frequency - center freq 2 +(for use with the 80+80 mode) + +\<number\> must be within 1..233. For 80 MHz channels it should be +channel + 6 and for 160 MHz channels, it should be channel + 14. +``` + +```{cfgcmd} set interfaces wireless \<interface\> capabilities he channel-set-width \<number\> + +\<number\> must be one of: + +* ``81`` - 20 MHz channel width (2.4GHz) +* ``83`` - 40 MHz channel width, secondary 20MHz channel above primary +channel (2.4GHz) +* ``84`` - 40 MHz channel width, secondary 20MHz channel below primary +channel (2.4GHz) +* ``131`` - 20 MHz channel width (6GHz) +* ``132`` - 40 MHz channel width (6GHz) +* ``133`` - 80 MHz channel width (6GHz) +* ``134`` - 160 MHz channel width (6GHz) +* ``135`` - 80+80 MHz channel width (6GHz) +``` + +```{cfgcmd} set interfaces wireless \<interface\> capabilities he coding-scheme \<number\> + +This setting configures Spatial Stream and Modulation Coding Scheme +settings for HE mode (HE-MCS). It is usually not needed to set this +explicitly, but it might help with some WiFi adapters. + +\<number\> must be one of: +* ``0`` - HE-MCS 0-7 +* ``1`` - HE-MCS 0-9 +* ``2`` - HE-MCS 0-11 +* ``3`` - HE-MCS is not supported +``` + +### Wireless options (Station/Client) + +The example creates a wireless station (commonly referred to as Wi-Fi client) +that accesses the network through the WAP defined in the above example. The +default physical device (`phy0`) is used. + +```none +set system wireless country-code de +set interfaces wireless wlan0 type station +set interfaces wireless wlan0 address dhcp +set interfaces wireless wlan0 ssid 'TEST' +set interfaces wireless wlan0 security wpa passphrase '12345678' +``` + +Resulting configuration: + +```none +system { + wireless { + country-code de + } +} +interfaces { + wireless wlan0 { + address dhcp + security { + wpa { + passphrase "12345678" + } + } + ssid TEST + type station + } +``` + +### Security + +{abbr}`WPA (Wi-Fi Protected Access)`, WPA2 Enterprise and WPA3 Enterprise in +combination with 802.1X based authentication can be used to authenticate +users or computers in a domain. + +The wireless client (supplicant) authenticates against the RADIUS server +(authentication server) using an {abbr}`EAP (Extensible Authentication +Protocol)` method configured on the RADIUS server. The WAP (also referred +to as authenticator) role is to send all authentication messages between the +supplicant and the configured authentication server, thus the RADIUS server +is responsible for authenticating the users. + +The WAP in this example has the following characteristics: +- IP address `192.168.2.1/24` +- Network ID (SSID) `Enterprise-TEST` +- WPA passphrase `12345678` +- Use 802.11n protocol +- Wireless channel `1` +- RADIUS server at `192.168.3.10` with shared-secret `VyOSPassword` + +```none +set system wireless country-code de +set interfaces wireless wlan0 address '192.168.2.1/24' +set interfaces wireless wlan0 type access-point +set interfaces wireless wlan0 channel 1 +set interfaces wireless wlan0 mode n +set interfaces wireless wlan0 ssid 'Enterprise-TEST' +set interfaces wireless wlan0 security wpa mode wpa2 +set interfaces wireless wlan0 security wpa cipher CCMP +set interfaces wireless wlan0 security wpa radius server 192.168.3.10 key 'VyOSPassword' +set interfaces wireless wlan0 security wpa radius server 192.168.3.10 port 1812 +``` + +Resulting configuration: + +```none +system { + wireless { + country-code de + } +} +interfaces { + [...] + wireless wlan0 { + address 192.168.2.1/24 + channel 1 + mode n + security { + wpa { + cipher CCMP + mode wpa2 + radius { + server 192.168.3.10 { + key 'VyOSPassword' + port 1812 + } + } + } + } + ssid "Enterprise-TEST" + type access-point + } +} +``` + +### VLAN +#### Regular VLANs (802.1q) + +```{cmdincludemd} /_include/interface-vlan-8021q.txt +:var0: wireless +:var1: wlan0 +``` + +#### QinQ (802.1ad) + +```{cmdincludemd} /_include/interface-vlan-8021ad.txt +:var0: wireless +:var1: wlan0 +``` + +## Operation + +```{opcmd} show interfaces wireless info +``` + +Use this command to view operational status and wireless-specific information +about all wireless interfaces. + +```none +vyos@vyos:~$ show interfaces wireless info +Interface Type SSID Channel +wlan0 access-point VyOS-TEST-0 1 +``` + +```{opcmd} show interfaces wireless detail +``` + +Show the operational status and detailed wireless-specific +information about all wireless interfaces. + +```none +vyos@vyos:~$ show interfaces wireless detail +wlan0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default qlen 1000 + link/ether XX:XX:XX:XX:XX:c3 brd XX:XX:XX:XX:XX:ff + inet xxx.xxx.99.254/24 scope global wlan0 + valid_lft forever preferred_lft forever + inet6 fe80::xxxx:xxxx:fe54:2fc3/64 scope link + valid_lft forever preferred_lft forever + + RX: bytes packets errors dropped overrun mcast + 66072 282 0 0 0 0 + TX: bytes packets errors dropped carrier collisions + 83413 430 0 0 0 0 + +wlan1: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default qlen 1000 + link/ether XX:XX:XX:XX:XX:c3 brd XX:XX:XX:XX:XX:ff + inet xxx.xxx.100.254/24 scope global wlan0 + valid_lft forever preferred_lft forever + inet6 fe80::xxxx:xxxx:ffff:2ed3/64 scope link + valid_lft forever preferred_lft forever + + RX: bytes packets errors dropped overrun mcast + 166072 5282 0 0 0 0 + TX: bytes packets errors dropped carrier collisions + 183413 5430 0 0 0 0 +``` + +```{opcmd} show interfaces wireless \<wlanX\> +``` + +This command shows both status and statistics on the specified wireless +interface. The wireless interface identifier can range from wlan0 to wlan999. + +```none +vyos@vyos:~$ show interfaces wireless wlan0 +wlan0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default qlen 1000 + link/ether XX:XX:XX:XX:XX:c3 brd XX:XX:XX:XX:XX:ff + inet xxx.xxx.99.254/24 scope global wlan0 + valid_lft forever preferred_lft forever + inet6 fe80::xxxx:xxxx:fe54:2fc3/64 scope link + valid_lft forever preferred_lft forever + + RX: bytes packets errors dropped overrun mcast + 66072 282 0 0 0 0 + TX: bytes packets errors dropped carrier collisions + 83413 430 0 0 0 0 +``` + +```{opcmd} show interfaces wireless \<wlanX\> brief +``` + +This command gives a brief status overview of a specified wireless interface. +The wireless interface identifier can range from wlan0 to wlan999. + +```none +vyos@vyos:~$ show interfaces wireless wlan0 brief +Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down +Interface IP Address S/L Description +--------- ---------- --- ----------- +wlan0 192.168.2.254/24 u/u +``` + +```{opcmd} show interfaces wireless \<wlanX\> queue +``` + +Use this command to view wireless interface queue information. +The wireless interface identifier can range from wlan0 to wlan999. + +```none +vyos@vyos:~$ show interfaces wireless wlan0 queue +qdisc pfifo_fast 0: root bands 3 priomap 1 2 2 2 1 2 0 0 1 1 1 1 1 1 1 1 + Sent 810323 bytes 6016 pkt (dropped 0, overlimits 0 requeues 0) + rate 0bit 0pps backlog 0b 0p requeues 0 +``` + +```{opcmd} show interfaces wireless \<wlanX\> scan +``` + +This command is used to retrieve information about WAP within the range of your +wireless interface. This command is useful on wireless interfaces configured +in station mode. + +:::{note} +Scanning is not supported on all wireless drivers and wireless +hardware. Refer to your driver and wireless hardware documentation for +further details. +::: +```none +vyos@vyos:~$ show interfaces wireless wlan0 scan +Address SSID Channel Signal (dbm) +00:53:3b:88:6e:d8 WLAN-576405 1 -64.00 +00:53:3b:88:6e:da Telekom_FON 1 -64.00 +00:53:00:f2:c2:a4 BabyView_F2C2A4 6 -60.00 +00:53:3b:88:6e:d6 Telekom_FON 100 -72.00 +00:53:3b:88:6e:d4 WLAN-576405 100 -71.00 +00:53:44:a4:96:ec KabelBox-4DC8 56 -81.00 +00:53:d9:7a:67:c2 WLAN-741980 1 -75.00 +00:53:7c:99:ce:76 Vodafone Homespot 1 -86.00 +00:53:44:a4:97:21 KabelBox-4DC8 1 -78.00 +00:53:44:a4:97:21 Vodafone Hotspot 1 -79.00 +00:53:44:a4:97:21 Vodafone Homespot 1 -79.00 +00:53:86:40:30:da Telekom_FON 1 -86.00 +00:53:7c:99:ce:76 Vodafone Hotspot 1 -86.00 +00:53:44:46:d2:0b Vodafone Hotspot 1 -87.00 +``` + +## Examples + +The following example creates a WAP. When configuring multiple WAP interfaces, +you must specify unique IP addresses, channels, Network IDs commonly referred +to as {abbr}`SSID (Service Set Identifier)`, and MAC addresses. + +The WAP in this example has the following characteristics: +- IP address `192.168.2.1/24` +- Network ID (SSID) `TEST` +- WPA passphrase `12345678` +- Use 802.11n protocol +- Wireless channel `1` + +```none +set system wireless country-code de +set interfaces wireless wlan0 address '192.168.2.1/24' +set interfaces wireless wlan0 type access-point +set interfaces wireless wlan0 channel 1 +set interfaces wireless wlan0 mode n +set interfaces wireless wlan0 ssid 'TEST' +set interfaces wireless wlan0 security wpa mode wpa2 +set interfaces wireless wlan0 security wpa cipher CCMP +set interfaces wireless wlan0 security wpa passphrase '12345678' +``` + +Resulting configuration: + +```none +system { + wireless { + country-code de + } +} +interfaces { + [...] + wireless wlan0 { + address 192.168.2.1/24 + channel 1 + mode n + security { + wpa { + cipher CCMP + mode wpa2 + passphrase "12345678" + } + } + ssid "TEST" + type access-point + } +} +``` + +To enable access point functionality, configure a DHCP server for this +interface's network, or add the interface to an existing local bridge +(see {ref}`bridge-interface` for details). + +### Wi-Fi 6/6E (802.11ax) + +The following examples configure Wi-Fi 6 (2.4 GHz) and Wi-Fi 6E (6 GHz) +{abbr}`APs (Access Points)` with the following parameters: +- Network ID (SSID): `test.ax` +- WPA passphrase: `super-dooper-secure-passphrase` +- Protocol: 802.11ax +- Wireless channel for 2.4 GHz: `11` +- Wireless channel for 6 GHz: `5` + +#### Example configuration: Wi-Fi 6 at 2.4 GHz + +You may expect real throughput around 10 MB/s or higher in crowded areas. + +```none +set system wireless country-code de +set interfaces wireless wlan0 capabilities he antenna-pattern-fixed +set interfaces wireless wlan0 capabilities he beamform multi-user-beamformer +set interfaces wireless wlan0 capabilities he beamform single-user-beamformee +set interfaces wireless wlan0 capabilities he beamform single-user-beamformer +set interfaces wireless wlan0 capabilities he bss-color 13 +set interfaces wireless wlan0 capabilities he channel-set-width 81 +set interfaces wireless wlan0 capabilities ht 40mhz-incapable +set interfaces wireless wlan0 capabilities ht channel-set-width ht20 +set interfaces wireless wlan0 capabilities ht channel-set-width ht40+ +set interfaces wireless wlan0 capabilities ht channel-set-width ht40- +set interfaces wireless wlan0 capabilities ht short-gi 20 +set interfaces wireless wlan0 capabilities ht short-gi 40 +set interfaces wireless wlan0 capabilities ht stbc rx 2 +set interfaces wireless wlan0 capabilities ht stbc tx +set interfaces wireless wlan0 channel 11 +set interfaces wireless wlan0 description "802.11ax 2.4GHz" +set interfaces wireless wlan0 mode ax +set interfaces wireless wlan0 security wpa cipher CCMP +set interfaces wireless wlan0 security wpa cipher CCMP-256 +set interfaces wireless wlan0 security wpa cipher GCMP-256 +set interfaces wireless wlan0 security wpa cipher GCMP +set interfaces wireless wlan0 security wpa mode wpa2 +set interfaces wireless wlan0 security wpa passphrase super-dooper-secure-passphrase +set interfaces wireless wlan0 ssid test.ax +set interfaces wireless wlan0 type access-point +commit +``` + +Resulting configuration: + +```none +system { + wireless { + country-code de + } +} +interfaces { + [...] + wireless wlan0 { + capabilities { + he { + antenna-pattern-fixed + beamform { + multi-user-beamformer + single-user-beamformee + single-user-beamformer + } + bss-color 13 + channel-set-width 81 + } + ht { + 40mhz-incapable + channel-set-width ht20 + channel-set-width ht40+ + channel-set-width ht40- + short-gi 20 + short-gi 40 + stbc { + rx 2 + tx + } + } + } + channel 11 + description "802.11ax 2.4GHz" + hw-id [...] + mode ax + physical-device phy0 + security { + wpa { + cipher CCMP + cipher CCMP-256 + cipher GCMP-256 + cipher GCMP + mode wpa2 + passphrase super-dooper-secure-passphrase + } + } + ssid test.ax + type access-point + } +} +``` + +#### Example configuration: Wi-Fi 6E at 6 GHz + +You may expect real throughput between 50 MB/s and 150 MB/s, depending on +obstructions from walls, water, metal, or other materials +with high electromagnetic damping at 6 GHz. Best results are achieved +with the AP being in the same room and in line-of-sight. + +```none +set system wireless country-code de +set interfaces wireless wlan0 capabilities he antenna-pattern-fixed +set interfaces wireless wlan0 capabilities he beamform multi-user-beamformer +set interfaces wireless wlan0 capabilities he beamform single-user-beamformee +set interfaces wireless wlan0 capabilities he beamform single-user-beamformer +set interfaces wireless wlan0 capabilities he bss-color 13 +set interfaces wireless wlan0 capabilities he channel-set-width 134 +set interfaces wireless wlan0 capabilities he center-channel-freq freq-1 15 +set interfaces wireless wlan0 channel 5 +set interfaces wireless wlan0 description "802.11ax 6GHz" +set interfaces wireless wlan0 mode ax +set interfaces wireless wlan0 security wpa cipher CCMP +set interfaces wireless wlan0 security wpa cipher CCMP-256 +set interfaces wireless wlan0 security wpa cipher GCMP-256 +set interfaces wireless wlan0 security wpa cipher GCMP +set interfaces wireless wlan0 security wpa mode wpa3 +set interfaces wireless wlan0 security wpa passphrase super-dooper-secure-passphrase +set interfaces wireless wlan0 mgmt-frame-protection required +set interfaces wireless wlan0 enable-bf-protection +set interfaces wireless wlan0 ssid test.ax +set interfaces wireless wlan0 type access-point +set interfaces wireless wlan0 stationary-ap +commit +``` + +Resulting configuration: + +```none +system { + wireless { + country-code de + } +} +interfaces { + [...] + wireless wlan0 { + capabilities { + he { + antenna-pattern-fixed + beamform { + multi-user-beamformer + single-user-beamformee + single-user-beamformer + } + bss-color 13 + center-channel-freq { + freq-1 15 + } + channel-set-width 134 + } + } + channel 5 + description "802.11ax 6GHz" + enable-bf-protection + hw-id [...] + mgmt-frame-protection required + mode ax + physical-device phy0 + security { + wpa { + cipher CCMP + cipher CCMP-256 + cipher GCMP-256 + cipher GCMP + mode wpa3 + passphrase super-dooper-secure-passphrase + } + } + ssid test.ax + stationary-ap + type access-point + } +} +``` + +(wireless-interface-intel-ax200)= + +### Intel AX200 + +The Intel AX200 card does not work out of the box in AP mode. You can +still put this card into AP mode using the following configuration: + +```none +set system wireless country-code 'us' +set interfaces wireless wlan0 channel '1' +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' +``` + diff --git a/docs/configuration/interfaces/wwan.md b/docs/configuration/interfaces/wwan.md new file mode 100644 index 00000000..e8121f28 --- /dev/null +++ b/docs/configuration/interfaces/wwan.md @@ -0,0 +1,355 @@ +--- +lastproofread: '2026-03-30' +--- + +(wwan-interface)= + +# WWAN + +{abbr}`WWAN (Wireless Wide Area Network)` interfaces provide access to cellular +networks via a cellular modem or card. + +Configure these interfaces under the `interfaces wwan` node. + +## Configuration + +### Common interface configuration + +```{cmdincludemd} /_include/interface-address-with-dhcp.txt +:var0: wwan +:var1: wwan0 +``` + +```{cmdincludemd} /_include/interface-description.txt +:var0: wwan +:var1: wwan0 +``` + +```{cmdincludemd} /_include/interface-disable.txt +:var0: wwan +:var1: wwan0 +``` + +```{cmdincludemd} /_include/interface-disable-link-detect.txt +:var0: wwan +:var1: wwan0 +``` + +```{cmdincludemd} /_include/interface-mtu.txt +:var0: wwan +:var1: wwan0 +``` + +```{cmdincludemd} /_include/interface-ip.txt +:var0: wwan +:var1: wwan0 +``` + +```{cmdincludemd} /_include/interface-ipv6.txt +:var0: wwan +:var1: wwan0 +``` + +```{cmdincludemd} /_include/interface-vrf.txt +:var0: wwan +:var1: wwan0 +``` + +**DHCP(v6)** + +```{cmdincludemd} /_include/interface-dhcp-options.txt +:var0: wwan +:var1: wwan0 +``` + +```{cmdincludemd} /_include/interface-dhcpv6-options.txt +:var0: wwan +:var1: wwan0 +``` + +```{cmdincludemd} /_include/interface-dhcpv6-prefix-delegation.txt +:var0: wwan +:var1: wwan0 +``` + + +### WWAN options + +```{cfgcmd} set interfaces wwan \<interface\> apn \<apn\> + +**Configure the** {abbr}`APN (Access Point Name)` **for the WWAN connection.** + +Every WWAN connection requires an {abbr}`APN (Access Point Name)` to connect to +the cellular network. + +This parameter is mandatory. Contact your service provider for the correct +{abbr}`APN (Access Point Name)`. +``` + + +## Operation + +```{opcmd} show interfaces wwan \<interface\> + +Show the operational status and traffic statistics for the specified WWAN +interface. + +:::{code-block} none +vyos@vyos:~$ show interfaces wwan wwan0 +wwan0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UNKNOWN group default qlen 1000 +link/ether 02:c2:f3:00:01:02 brd ff:ff:ff:ff:ff:ff +inet 10.155.144.12/30 brd 10.155.144.15 scope global dynamic wwan0 +valid_lft 7012sec preferred_lft 7012sec +inet6 fe80::c2:f3ff:fe00:0102/64 scope link +valid_lft forever preferred_lft forever + +RX: bytes packets errors dropped overrun mcast +640 2 0 0 0 0 +TX: bytes packets errors dropped carrier collisions +3229 16 0 0 0 0 +::: +``` + + +```{opcmd} show interfaces wwan \<interface\> summary + +Show WWAN module hardware characteristics and connection information. + +:::{code-block} none +vyos@vyos:~$ show interfaces wwan wwan0 summary +-------------------------------- +General | dbus path: /org/freedesktop/ModemManager1/Modem/0 +| device id: 79f4e9cc2e9fc8d4a3b8c8f6327c2e363170194d +-------------------------------- +Hardware | manufacturer: Sierra Wireless, Incorporated +| model: MC7710 +| revision: SWI9200X_03.05.29.03ap r6485 CNSHZ-ED-XP0031 2014/12/02 17:53:15 +| h/w revision: 1.0 +| supported: gsm-umts, lte +| current: gsm-umts, lte +| equipment id: 358xxxxxxxxxxxx +-------------------------------- +System | device: /sys/devices/pci0000:00/0000:00:13.0/usb3/3-1/3-1.3 +| drivers: qcserial, qmi_wwan +| plugin: Generic +| primary port: cdc-wdm0 +| ports: ttyUSB0 (qcdm), ttyUSB2 (at), cdc-wdm0 (qmi), wwan0 (net) +-------------------------------- +Numbers | own: 4917xxxxxxxx +-------------------------------- +Status | lock: sim-pin2 +| unlock retries: sim-pin (3), sim-pin2 (3), sim-puk (10), sim-puk2 (10) +| state: connected +| power state: on +| access tech: lte +| signal quality: 63% (recent) +-------------------------------- +Modes | supported: allowed: 2g; preferred: none +| allowed: 3g; preferred: none +| allowed: 4g; preferred: none +| allowed: 2g, 3g; preferred: 3g +| allowed: 2g, 3g; preferred: 2g +| allowed: 2g, 4g; preferred: 4g +| allowed: 2g, 4g; preferred: 2g +| allowed: 3g, 4g; preferred: 3g +| allowed: 3g, 4g; preferred: 4g +| allowed: 2g, 3g, 4g; preferred: 4g +| allowed: 2g, 3g, 4g; preferred: 3g +| allowed: 2g, 3g, 4g; preferred: 2g +| current: allowed: 2g, 3g, 4g; preferred: 2g +-------------------------------- +Bands | supported: egsm, dcs, pcs, utran-1, utran-8, eutran-1, eutran-3, +| eutran-7, eutran-8, eutran-20 +| current: egsm, dcs, pcs, utran-1, utran-8, eutran-1, eutran-3, +| eutran-7, eutran-8, eutran-20 +-------------------------------- +IP | supported: ipv4, ipv6, ipv4v6 +-------------------------------- +3GPP | imei: 358xxxxxxxxxxxx +| operator id: 26201 +| operator name: Telekom.de +| registration: home +-------------------------------- +3GPP EPS | ue mode of operation: ps-1 +-------------------------------- +SIM | dbus path: /org/freedesktop/ModemManager1/SIM/0 +-------------------------------- +Bearer | dbus path: /org/freedesktop/ModemManager1/Bearer/0 +::: +``` + +```{opcmd} show interfaces wwan \<interface\> capabilities + +Show WWAN module radio capabilities. + +:::{code-block} none +vyos@vyos:~$ show interfaces wwan wwan0 capabilities +Max TX channel rate: '50000000' +Max RX channel rate: '100000000' +Data Service: 'simultaneous-cs-ps' +SIM: 'supported' +Networks: 'gsm, umts, lte' +Bands: 'gsm-dcs-1800, gsm-900-extended, gsm-900-primary, gsm-pcs-1900, wcdma-2100, wcdma-900' +LTE bands: '1, 3, 7, 8, 20' +::: +``` + + +```{opcmd} show interfaces wwan \<interface\> firmware + +Show WWAN module firmware information. + +:::{code-block} none +vyos@vyos:~$ show interfaces wwan wwan0 firmware +Model: MC7710 +Boot version: SWI9200X_03.05.29.03bt r6485 CNSHZ-ED-XP0031 2014/12/02 17:33:08 +AMSS version: SWI9200X_03.05.29.03ap r6485 CNSHZ-ED-XP0031 2014/12/02 17:53:15 +SKU ID: unknown +Package ID: unknown +Carrier ID: 0 +Config version: unknown +::: +``` + +```{opcmd} show interfaces wwan \<interface\> imei + +Show WWAN module IMEI. + +:::{code-block} none +vyos@vyos:~$ show interfaces wwan wwan0 imei +ESN: '0' +IMEI: '358xxxxxxxxxxxx' +MEID: 'unknown' +::: +``` + +```{opcmd} show interfaces wwan \<interface\> imsi + +Show the IMSI of the associated SIM card. + +:::{code-block} none +vyos@vyos:~$ show interfaces wwan wwan0 imsi +IMSI: '262xxxxxxxxxxxx' +::: +``` + +```{opcmd} show interfaces wwan \<interface\> model + +Show WWAN module model. + +:::{code-block} none +vyos@vyos:~$ show interfaces wwan wwan0 model +Model: 'MC7710' +::: +``` + +```{opcmd} show interfaces wwan \<interface\> msisdn + +Show the MSISDN of the associated SIM card. + +:::{code-block} none +vyos@vyos:~$ show interfaces wwan wwan0 msisdn +MSISDN: '4917xxxxxxxx' +::: +``` + +```{opcmd} show interfaces wwan \<interface\> revision + +Show WWAN module hardware revision. + +:::{code-block} none +vyos@vyos:~$ show interfaces wwan wwan0 revision +Revision: 'SWI9200X_03.05.29.03ap r6485 CNSHZ-ED-XP0031 2014/12/02 17:53:15' +::: +``` + +```{opcmd} show interfaces wwan \<interface\> signal + +Show signal information for the cellular connection. + +:::{code-block} none +vyos@vyos:~$ show interfaces wwan wwan0 signal +LTE: +RSSI: '-74 dBm' +RSRQ: '-7 dB' +RSRP: '-100 dBm' +SNR: '13.0 dB' +Radio Interface: 'lte' +Active Band Class: 'eutran-3' +Active Channel: '1300' +::: +``` + +```{opcmd} show interfaces wwan \<interface\> sim + +Show WWAN module SIM card information. + +:::{code-block} none +vyos@vyos:~$ show interfaces wwan wwan0 sim +Provisioning applications: +Primary GW: slot '1', application '1' +Primary 1X: session doesn't exist +Secondary GW: session doesn't exist +Secondary 1X: session doesn't exist +Slot [1]: +Card state: 'present' +UPIN state: 'not-initialized' +UPIN retries: '0' +UPUK retries: '0' +Application [1]: +Application type: 'usim (2)' +Application state: 'ready' +Application ID: +A0:00:00:00:87:10:02:FF:49:94:20:89:03:10:00:00 +Personalization state: 'ready' +UPIN replaces PIN1: 'no' +PIN1 state: 'disabled' +PIN1 retries: '3' +PUK1 retries: '10' +PIN2 state: 'enabled-not-verified' +PIN2 retries: '3' +PUK2 retries: '10' +::: +``` + + +## Example + +The following example shows how to configure a cellular connection using a +Sierra Wireless MC7710 miniPCIe card that operates over USB despite its form +factor. The card is installed in a {ref}`pc-engines-apu4`. + +```none +set interfaces wwan wwan0 apn 'internet.telekom' +set interfaces wwan wwan0 address 'dhcp' +``` + + +## Supported hardware + +The following WWAN modules have been successfully tested with a +{ref}`pc-engines-apu4` board: +- Sierra Wireless AirPrime MC7304 miniPCIe card (LTE) +- Sierra Wireless AirPrime MC7430 miniPCIe card (LTE) +- Sierra Wireless AirPrime MC7455 miniPCIe card (LTE) +- Sierra Wireless AirPrime MC7710 miniPCIe card (LTE) +- Huawei ME909u-521 miniPCIe card (LTE) +- Huawei ME909s-120 miniPCIe card (LTE) +- HP LT4120 Snapdragon X5 LTE + +## Firmware update + +WWAN modules include reprogrammable firmware, and most vendors regularly +provide updates for it. + +Since VyOS communicates with these devices via the QMI interface, you can +update firmware directly within the system using the `qmi-firmware-update` +utility. + +The following example shows how to update the firmware for a Sierra Wireless +MC7710 module using the provided .cwe file. + +```bash +$ sudo qmi-firmware-update --update -d 1199:68a2 \ + 9999999_9999999_9200_03.05.14.00_00_generic_000.000_001_SPKG_MC.cwe +``` diff --git a/docs/configuration/loadbalancing/haproxy.md b/docs/configuration/loadbalancing/haproxy.md new file mode 100644 index 00000000..d60c5248 --- /dev/null +++ b/docs/configuration/loadbalancing/haproxy.md @@ -0,0 +1,510 @@ +--- +lastproofread: '2026-04-06' +--- + +# HAproxy + +```{include} /_include/need_improvement.txt +``` + +HAProxy is a load balancer and proxy server that provides +high-availability, load balancing, and proxying for TCP (level 4) and +HTTP-based (level 7) applications. + +## Configuration + +Service configuration specifies the port to bind to. Backend +configuration defines the load balancing method and specifies the backend +servers. + +### Service + +```{cfgcmd} set load-balancing haproxy service \<name\> listen-address \<address\> + +Set the IP address for the service to bind to. By default, the service +listens on all IPv4 and IPv6 addresses. +``` + +```{cfgcmd} set load-balancing haproxy service \<name\> port \<port\> + +Create service *<name>* to listen on \<port\> +``` + +```{cfgcmd} set load-balancing haproxy service \<name\> mode \<tcp|http\> + +Configure service *<name>* mode TCP or HTTP +``` + +```{cfgcmd} set load-balancing haproxy service \<name\> backend \<name\> + +Configure service *<name>* to use the backend \<name\> +``` + +```{cfgcmd} set load-balancing haproxy service \<name\> ssl certificate \<name\> + +Set the SSL certificate \<name\> for service \<name\>. You can define +multiple certificates. +``` + +```{cfgcmd} set load-balancing haproxy service \<name\> http-response-headers \<header-name\> value \<header-value\> + +Set custom HTTP headers to include in all responses. +``` + +```{cfgcmd} set load-balancing haproxy service \<name\> logging facility \<facility\> level \<level\> + +Specify facility and level for logging. +For an explanation on {ref}`syslog_facilities` and +{ref}`syslog_severity_level`, +see tables in the syslog configuration section. +``` + +```{cfgcmd} set load-balancing haproxy service \<name\> timeout client \<seconds\> + +Set the maximum inactivity time on the client side for this service. +Value range 1-3600 seconds. +``` + +```{cfgcmd} set load-balancing haproxy service \<name\> http-compression algorithm \<gzip | deflate | identity | raw-deflate\> + +Set the compression algorithm to be used when compressing HTTP responses. +``` + +```{cfgcmd} set load-balancing haproxy service \<name\> http-compression mime-type \<mime-type\> + +Set the list of HTTP response MIME types which haproxy will attempt to +compress, if received uncompressed from backend server. +``` + +#### Rules + +Rules control and route incoming traffic to specific backends based on +predefined conditions. Rules define matching criteria and specify actions +to perform. + +```{cfgcmd} set load-balancing haproxy service \<name\> rule \<rule\> domain-name \<name\> + +Match domain name +``` + +````{cfgcmd} set load-balancing haproxy service \<name\> rule \<rule\> ssl \<sni\> + +```{eval-rst} +SSL match Server Name Indication (SNI) option: + * ``req-ssl-sni`` SSL Server Name Indication (SNI) request match + * ``ssl-fc-sni`` SSL frontend connection Server Name Indication match + * ``ssl-fc-sni-end`` SSL frontend match end of connection Server Name + + Indication +``` +```` + +````{cfgcmd} set load-balancing haproxy service \<name\> rule \<rule\> url-path \<match\> \<url\> + +Define URL path matching rules for a specific service. Use this command +to specify how to match the URL path against incoming requests. + +```{eval-rst} +The available options for <match> are: + * ``begin`` Matches the beginning of the URL path + * ``end`` Matches the end of the URL path. + * ``exact`` Matches the URL path exactly. +``` +```` + +```{cfgcmd} set load-balancing haproxy service \<name\> rule \<rule\> set backend \<name\> + +Assign a specific backend to a rule +``` + +```{cfgcmd} set load-balancing haproxy service \<name\> rule \<rule\> redirect-location \<url\> + +Redirect URL to a new location. +``` + +### Backend + +````{cfgcmd} set load-balancing haproxy backend \<name\> balance \<balance\> + +Specify the load balancing algorithm for distributing requests among +available servers. + +```{eval-rst} +Balance algorithms: + * ``source-address`` Distributes requests based on the source IP address + of the client. + * ``round-robin`` Distributes requests in a circular manner, + sequentially sending each request to the next server in line. + * ``least-connection`` Distributes requests to the server with the fewest + active connections. +``` +```` + +```{cfgcmd} set load-balancing haproxy backend \<name\> mode \<mode\> + +Configure backend *<name>* mode TCP or HTTP. +``` + +```{cfgcmd} set load-balancing haproxy backend \<name\> server \<name\> address \<x.x.x.x\> + +Set the address of the backend server that receives incoming traffic. +``` + +```{cfgcmd} set load-balancing haproxy backend \<name\> server \<name\> port \<port\> + +Set the address of the backend port. +``` + +```{cfgcmd} set load-balancing haproxy backend \<name\> server \<name\> check + +Active health check backend server. +``` + +```{cfgcmd} set load-balancing haproxy backend \<name\> server \<name\> check port \<port\> + +Set an alternative port number for health checks. +Overrides the default server port used for TCP/HTTP checks. +``` + +```{cfgcmd} set load-balancing haproxy backend \<name\> server \<name\> send-proxy + +Send a Proxy Protocol version 1 header (text format). +``` + +```{cfgcmd} set load-balancing haproxy backend \<name\> server \<name\> send-proxy-v2 + +Send a Proxy Protocol version 2 header (binary format). +``` + +```{cfgcmd} set load-balancing haproxy backend \<name\> ssl ca-certificate \<ca-certificate\> + +Use SSL encryption for backend requests and authenticate the backend +against ``<ca-certificate>``. +``` + +```{cfgcmd} set load-balancing haproxy backend \<name\> ssl no-verify + +Use SSL encryption for backend requests without validating the server +certificate. +``` + +```{cfgcmd} set load-balancing haproxy backend \<name\> http-response-headers \<header-name\> value \<header-value\> + +Set custom HTTP headers to include in all responses from the backend. +``` + +```{cfgcmd} set load-balancing haproxy backend \<name\> logging facility \<facility\> level \<level\> + +Specify facility and level for logging. +For an explanation on {ref}`syslog_facilities` and +{ref}`syslog_severity_level`, +see tables in the syslog configuration section. +``` + +```{cfgcmd} set load-balancing haproxy backend \<name\> timeout check \<seconds\> + +Set the timeout in seconds for established connections. +Value range 1-3600 seconds. +``` +```{cfgcmd} set load-balancing haproxy backend \<name\> timeout connect \<seconds\> + +Set the maximum time to wait for a connection attempt to a server to succeed. +Value range 1-3600 seconds. +``` + + +```{cfgcmd} set load-balancing haproxy backend \<name\> timeout server \<seconds\> + +Set the maximum inactivity time on the server side. +Value range 1-3600 seconds. +``` + +### Global + +Global configuration parameters: + +```{cfgcmd} set load-balancing haproxy global-parameters max-connections \<num\> + +Limit maximum number of connections +``` + + +```{cfgcmd} set load-balancing haproxy global-parameters ssl-bind-ciphers \<ciphers\> + +Limit the cipher algorithms allowed during SSL/TLS handshake. +``` + + +```{cfgcmd} set load-balancing haproxy global-parameters tls-version-min \<version\> + +Specify the minimum required TLS version 1.2 or 1.3 +``` + + +```{cfgcmd} set load-balancing haproxy global-parameters logging facility \<facility\> level \<level\> + +Specify facility and level for logging. +For an explanation on {ref}`syslog_facilities` and +{ref}`syslog_severity_level`, +see tables in the syslog configuration section. +``` + + +```{cfgcmd} set load-balancing haproxy timeout check \<seconds\> + +Set the timeout in seconds for established connections. +Value range 1-3600 seconds. Default is 5 seconds. +``` + + +```{cfgcmd} set load-balancing haproxy timeout client \<seconds\> + +Set the maximum inactivity time on the client side. +Value range 1-3600 seconds. Default is 50 seconds. +``` + + +```{cfgcmd} set load-balancing haproxy timeout connect \<seconds\> + +Set the maximum time to wait for a connection attempt to a server to succeed. +Value range 1-3600 seconds. Default is 10 seconds. +``` + + +```{cfgcmd} set load-balancing haproxy timeout server \<seconds\> + +Set the maximum inactivity time on the server side. +Value range 1-3600 seconds. Default is 50 seconds. +``` + +## Health checks + + +### HTTP checks + + +Use HTTP health checks to monitor web applications that provide health status +information and determine their availability. + +```{cfgcmd} set load-balancing haproxy backend \<name\> http-check + +Enables HTTP health checks using OPTION HTTP requests against '/' and +expecting a successful response code in the 200-399 range. +``` + + +```{cfgcmd} set load-balancing haproxy backend \<name\> http-check method \<method\> + +Set the HTTP method: ``OPTION``, ``GET``, ``POST``, or ``PUT``. +``` + + +```{cfgcmd} set load-balancing haproxy backend \<name\> http-check uri \<path\> + +Set the endpoint to use for health checks. +``` + + +````{cfgcmd} set load-balancing haproxy backend \<name\> http-check expect \<condition\> + +Set the expected result condition for a server to be considered healthy. + +```{eval-rst} +Some possible examples are: + * ``status 200`` Expecting a 200 response code + * ``status 200-399`` Expecting a non-failure response code + * ``string success`` Expecting the string success in the response body +``` +```` + +### TCP checks + +Configure health checks for TCP mode backends. You can configure protocol-aware +checks for a range of Layer 7 protocols: + +````{cfgcmd} set load-balancing haproxy backend \<name\> health-check \<protocol\> + +```{eval-rst} +Available health check protocols: + * ``ldap`` LDAP protocol check. + * ``redis`` Redis protocol check. + * ``mysql`` MySQL protocol check. + * ``pgsql`` PostgreSQL protocol check. + * ``smtp`` SMTP protocol check. +``` +```` + +:::{note} +If you specify a server to check but do not configure a +protocol, HAProxy performs a basic TCP health check. A server is online if +it responds to a connection attempt with a valid `SYN/ACK` packet. +::: +## Redirect HTTP to HTTPS + +Configure a HAProxy service for HTTP that listens on port 80 and redirects +incoming requests to HTTPS: + +```none +set load-balancing haproxy service http port '80' +set load-balancing haproxy service http redirect-http-to-https +``` + +You can use a different service name; in this example, `http` is just for +convenience. + +## Examples +### Level 4 balancing + +This configuration enables the TCP reverse proxy for the `my-tcp-api` +service. Incoming TCP connections on port 8888 are load balanced across the +backend servers (srv01 and srv02) using the round-robin load balancing +algorithm. + +```none +set load-balancing haproxy service my-tcp-api backend 'bk-01' +set load-balancing haproxy service my-tcp-api mode 'tcp' +set load-balancing haproxy service my-tcp-api port '8888' + +set load-balancing haproxy backend bk-01 balance 'round-robin' +set load-balancing haproxy backend bk-01 mode 'tcp' + +set load-balancing haproxy backend bk-01 server srv01 address '192.0.2.11' +set load-balancing haproxy backend bk-01 server srv01 port '8881' +set load-balancing haproxy backend bk-01 server srv02 address '192.0.2.12' +set load-balancing haproxy backend bk-01 server srv02 port '8882' +``` + +### Balancing based on domain name + +The following configuration demonstrates how to use VyOS +to achieve load balancing based on the domain name: + +The HTTP service listens on TCP port 80. + +Rule 10 matches requests with the domain name `node1.example.com` and +forwards them to the backend `bk-api-01`. + +Rule 20 matches requests with the domain name `node2.example.com` and +forwards them to the backend `bk-api-02`. + +```none +set load-balancing haproxy service http description 'bind app listen on 443 port' +set load-balancing haproxy service http mode 'tcp' +set load-balancing haproxy service http port '80' + +set load-balancing haproxy service http rule 10 domain-name 'node1.example.com' +set load-balancing haproxy service http rule 10 set backend 'bk-api-01' +set load-balancing haproxy service http rule 20 domain-name 'node2.example.com' +set load-balancing haproxy service http rule 20 set backend 'bk-api-02' + +set load-balancing haproxy backend bk-api-01 description 'My API-1' +set load-balancing haproxy backend bk-api-01 mode 'tcp' +set load-balancing haproxy backend bk-api-01 server api01 address '127.0.0.1' +set load-balancing haproxy backend bk-api-01 server api01 port '4431' +set load-balancing haproxy backend bk-api-02 description 'My API-2' +set load-balancing haproxy backend bk-api-02 mode 'tcp' +set load-balancing haproxy backend bk-api-02 server api01 address '127.0.0.2' +set load-balancing haproxy backend bk-api-02 server api01 port '4432' +``` + +### Terminate SSL + +The following configuration terminates SSL on the router. + +The `http` service listens on port 80 and redirects HTTP requests to +HTTPS. + +The `https` service listens on port 443 with the `bk-default` backend +and handles HTTPS traffic using the `cert` certificate for SSL termination. +The HSTS header is set with a 1-year expiry to tell browsers to always use +SSL for the site. + +Rule 10 matches requests with the exact URL path `/.well-known/xxx` and +redirects them to `/certs/`. + +Rule 20 matches requests with URL paths ending in `/mail` or the exact +path `/email/bar` and redirects them to `/postfix/`. + +Global parameters include a maximum connection limit of 4000 and a minimum +TLS version of 1.3. + +```none +set load-balancing haproxy service http description 'Force redirect to HTTPS' +set load-balancing haproxy service http port '80' +set load-balancing haproxy service http redirect-http-to-https + +set load-balancing haproxy service https backend 'bk-default' +set load-balancing haproxy service https description 'listen on 443 port' +set load-balancing haproxy service https mode 'http' +set load-balancing haproxy service https port '443' +set load-balancing haproxy service https ssl certificate 'cert' +set load-balancing haproxy service https http-response-headers Strict-Transport-Security value 'max-age=31536000' + +set load-balancing haproxy service https rule 10 url-path exact '/.well-known/xxx' +set load-balancing haproxy service https rule 10 set redirect-location '/certs/' +set load-balancing haproxy service https rule 20 url-path end '/mail' +set load-balancing haproxy service https rule 20 url-path exact '/email/bar' +set load-balancing haproxy service https rule 20 set redirect-location '/postfix/' + +set load-balancing haproxy backend bk-default description 'Default backend' +set load-balancing haproxy backend bk-default mode 'http' +set load-balancing haproxy backend bk-default server sr01 address '192.0.2.23' +set load-balancing haproxy backend bk-default server sr01 port '80' + +set load-balancing haproxy global-parameters max-connections '4000' +set load-balancing haproxy global-parameters tls-version-min '1.3' +``` + +### SSL Bridging + +The following configuration terminates incoming HTTPS traffic on the router, +then re-encrypts the traffic and sends it to the backend server via HTTPS. +Use this when encryption is required for both paths but you do not want to +install publicly trusted certificates on each backend server. + +Backend service certificates are checked against the certificate authority +specified in the configuration, which could be an internal CA. + +The `https` service listens on port 443 with backend `bk-bridge-ssl` to +handle HTTPS traffic. It uses certificate named `cert` for SSL termination. + +The `bk-bridge-ssl` backend connects to `sr01` server on port 443 via HTTPS +and checks backend server has a valid certificate trusted by CA `cacert` + +```none +set load-balancing haproxy service https backend 'bk-bridge-ssl' +set load-balancing haproxy service https description 'listen on 443 port' +set load-balancing haproxy service https mode 'http' +set load-balancing haproxy service https port '443' +set load-balancing haproxy service https ssl certificate 'cert' + +set load-balancing haproxy backend bk-bridge-ssl description 'SSL backend' +set load-balancing haproxy backend bk-bridge-ssl mode 'http' +set load-balancing haproxy backend bk-bridge-ssl ssl ca-certificate 'cacert' +set load-balancing haproxy backend bk-bridge-ssl server sr01 address '192.0.2.23' +set load-balancing haproxy backend bk-bridge-ssl server sr01 port '443' +``` + +### Balancing with HTTP health checks + +This configuration enables HTTP health checks for backend servers. + +```none +set load-balancing haproxy service my-tcp-api backend 'bk-01' +set load-balancing haproxy service my-tcp-api mode 'tcp' +set load-balancing haproxy service my-tcp-api port '8888' + +set load-balancing haproxy backend bk-01 balance 'round-robin' +set load-balancing haproxy backend bk-01 mode 'tcp' + +set load-balancing haproxy backend bk-01 http-check method 'get' +set load-balancing haproxy backend bk-01 http-check uri '/health' +set load-balancing haproxy backend bk-01 http-check expect 'status 200' + +set load-balancing haproxy backend bk-01 server srv01 address '192.0.2.11' +set load-balancing haproxy backend bk-01 server srv01 port '8881' +set load-balancing haproxy backend bk-01 server srv01 check +set load-balancing haproxy backend bk-01 server srv02 address '192.0.2.12' +set load-balancing haproxy backend bk-01 server srv02 port '8882' +set load-balancing haproxy backend bk-01 server srv02 check port '8892' +``` diff --git a/docs/configuration/loadbalancing/index.md b/docs/configuration/loadbalancing/index.md new file mode 100644 index 00000000..3241edb7 --- /dev/null +++ b/docs/configuration/loadbalancing/index.md @@ -0,0 +1,15 @@ +--- +lastproofread: '2026-04-06' +--- + +(load-balancing)= + +# Load-balancing + +```{toctree} +:includehidden: true +:maxdepth: 1 + +wan +haproxy +``` diff --git a/docs/configuration/loadbalancing/haproxy.rst b/docs/configuration/loadbalancing/rst-haproxy.rst index d742ec18..d742ec18 100644 --- a/docs/configuration/loadbalancing/haproxy.rst +++ b/docs/configuration/loadbalancing/rst-haproxy.rst diff --git a/docs/configuration/loadbalancing/index.rst b/docs/configuration/loadbalancing/rst-index.rst index b87faed2..b87faed2 100644 --- a/docs/configuration/loadbalancing/index.rst +++ b/docs/configuration/loadbalancing/rst-index.rst diff --git a/docs/configuration/loadbalancing/wan.rst b/docs/configuration/loadbalancing/rst-wan.rst index 56fdb02c..56fdb02c 100644 --- a/docs/configuration/loadbalancing/wan.rst +++ b/docs/configuration/loadbalancing/rst-wan.rst diff --git a/docs/configuration/loadbalancing/wan.md b/docs/configuration/loadbalancing/wan.md new file mode 100644 index 00000000..a19bbfae --- /dev/null +++ b/docs/configuration/loadbalancing/wan.md @@ -0,0 +1,306 @@ +--- +lastproofread: '2026-04-06' +--- + +# WAN load balancing + +```{todo} +Convert raw command blocks in this file to cfgcmd/opcmd +directives for command coverage tracking. +``` + +The load balancer distributes outbound traffic across two or more +interfaces. If a path fails, the load balancer balances traffic across the +remaining healthy paths. When a path recovers, it is automatically added back +to the routing table. The load balancer adds routes for each path and +distributes traffic based on interface health and weight. + +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). + +The following examples uses two DHCP WAN interfaces and one LAN (`eth2`): + +```none +set load-balancing wan interface-health eth0 nexthop 'dhcp' +set load-balancing wan interface-health eth1 nexthop 'dhcp' +set load-balancing wan rule 1 inbound-interface 'eth2' +set load-balancing wan rule 1 interface eth0 +set load-balancing wan rule 1 interface eth1 +``` + +:::{note} +Do not use WAN load balancing with dynamic routing protocols. This +feature creates customized routing tables and firewall rules that are +incompatible with routing protocols. +::: + +## Load balancing rules + +You define interfaces, their weight, and the traffic type to balance in +numbered rule sets. The load balancer executes rules in numerical order +against outgoing packets. When a packet matches a rule, it is sent through the +specified interface. Packets that do not match any rule use the system routing +table. You cannot change rule numbers. + +Create a load balancing rule, it can be a number between 1 and 9999: + +```none +vyos@vyos# set load-balancing wan rule 1 +Possible completions: +description Description for this rule +> destination Destination +exclude Exclude packets matching this rule from wan load balance +failover Enable failover for packets matching this rule from wan load balance +inbound-interface Inbound interface name (e.g., "eth0") [REQUIRED] ++> interface Interface name [REQUIRED] +> limit Enable packet limit for this rule +per-packet-balancing Option to match traffic per-packet instead of the default, per-flow +protocol Protocol to match +> source Source information +``` + + +### Interface weight + +By default, the load balancer distributes outbound +traffic randomly across available interfaces. You can assign weights to +interfaces to influence the distribution. If `eth0` has more bandwidth +than `eth1`, you can assign a higher weight to `eth0` to send more +traffic through it: + +```none +set load-balancing wan rule 1 interface eth0 weight 2 +set load-balancing wan rule 1 interface eth1 weight 1 +``` + +In this example,\`\`eth0\`\` receives 66% of traffic, and `eth1` receives +33% of traffic. + +### Rate limit + +Set a packet rate limit for a rule to apply it to traffic above or below a +specified threshold. To configure rate limiting, use: + +```none +set load-balancing wan rule <rule> limit <parameter> +``` + +- `burst`: Number of packets allowed to overshoot the limit within `period`. + Default 5. +- `period`: Time window for rate calculation. Possible values: + `second` (one second), `minute` (one minute), `hour` (one hour). + Default is `second`. +- `rate`: Number of packets. Default: `5`. +- `threshold`: `below` or `above` the specified rate limit. + +### Flow and packet-based balancing + +The load balancer balances outgoing traffic by flow. A connection tracking +table tracks flows by source address, destination address, and port. Each +flow is assigned to an interface based on the balancing rules, and subsequent +packets use the same interface. This ensures packets arrive in order when links +have different speeds. + +Packet-based balancing can improve balance across interfaces when packet +order is not critical. Enable per-packet balancing for a rule with: + +```none +set load-balancing wan rule <rule> per-packet-balancing +``` + + +### Exclude traffic + +To exclude traffic from load balancing, traffic matching an exclude rule +bypasses load balancing and uses the system routing table instead: + +```none +set load-balancing wan rule <rule> exclude +``` + + +## Health checks + +The load balancer periodically checks the health of interfaces and paths by +sending ICMP packets (ping) to remote destinations, performing TTL tests, or +executing a user-defined script. If an interface fails the health check, the +load balancer removes it from its interface pool. +To enable health checking for an interface: + +```none +vyos@vyos# set load-balancing wan interface-health <interface> +Possible completions: +failure-count Failure count +nexthop Outbound interface nexthop address. Can be 'dhcp or ip address' [REQUIRED] +success-count Success count ++> test Rule number +``` + +Specify the nexthop on the path to the destination. You can set +`ipv4-address` to `dhcp`. + +```none +set load-balancing wan interface-health <interface> nexthop <ipv4-address> +``` + +Set the number of health check failures before the load balancer marks an +interface as unavailable (range 1-10, default 1). Or set the number of +successful health checks before adding an interface back to the pool +(range 1-10, default 1). + +```none +set load-balancing wan interface-health <interface> failure-count <number> +set load-balancing wan interface-health <interface> success-count <number> +``` + +Configure each health check in its own test. Tests are numbered and processed +in numeric order. You can define multiple tests for multi-target health +checking: + +```none +vyos@vyos# set load-balancing wan interface-health eth1 test 0 +Possible completions: +resp-time Ping response time (seconds) +target Health target address +test-script Path to user defined script +ttl-limit Ttl limit (hop count) +type WLB test type +``` + +- `resp-time`: The maximum response time for ping in seconds. Range + 1-30, default `5`. +- `target`: The target to receive ICMP packets. The address can be an IPv4 + address or hostname. +- `test-script`: A user-defined script must return 0 to succeed and + non-zero to fail. Scripts reside in `/config/scripts`. For other locations, + provide the full path. +- `ttl-limit`: For the UDP TTL limit test, specify the hop count limit. + The limit must be shorter than the path length. The test succeeds when an + ICMP time-expired message is returned. Default `1`. +- `type`: Specify the test type: `ping`, `ttl`, or a user-defined + script. + +## Source NAT rules + +By default, interfaces in a load balancing pool replace the source IP of +each outgoing packet with their own address to ensure replies arrive on the +same interface. The load balancer handles this through automatically generated +Source NAT (SNAT) rules applied only to balanced traffic. To disable the +automatic generation of SNAT rules when this behavior is not desired, use: + +```none +set load-balancing wan disable-source-nat +``` + + +## Sticky connections + +Inbound connections to a WAN interface can be improperly handled when +replies are sent back to the client. + +```{image} /_static/images/sticky-connections.webp +:align: center +:width: 80% +``` + +When responding to an incoming packet, you may want to ensure the response +leaves from the same interface as the incoming packet. Enable sticky +connections in the load balancer to do this: + +```none +set load-balancing wan sticky-connections inbound +``` + + +## Failover + +In failover mode, one interface is primary and other interfaces are +secondary or spare. The load balancer uses only the primary interface. If it +fails, a secondary interface from the available pool takes over. The load +balancer selects the primary interface based on its weight and health. Other +interfaces become secondary. Secondary interfaces are chosen based on their +weight and health. You can also select interface roles based on rule order by +including interfaces in balancing rules and ordering those rules accordingly. +To enable failover mode, create a failover rule: + +```none +set load-balancing wan rule <number> failover +``` + +Existing sessions do not automatically fail over to a new path. Flush the +session table on each connection state change to enable failover: + +```none +set load-balancing wan flush-connections +``` + +:::{warning} +Flushing the session table causes other connections to revert from +flow-based to packet-based balancing until each flow is reestablished. +::: + +## Script execution + +Run a script when an interface state changes. Scripts run from the +`/config/scripts` directory. To use a script in another location, +specify the full path: + +```none +set load-balancing wan hook script-name +``` + +Two environment variables are available: +- `WLB_INTERFACE_NAME=[interfacename]`: Interface to be monitored +- `WLB_INTERFACE_STATE=[ACTIVE|FAILED]`: Interface state + +:::{warning} +Blocking call with no timeout: VyOS becomes unresponsive if the +script does not return. +::: + +## Handling and monitoring + +The following command shows WAN load balancer information including test +types and targets. The character at the start of each line indicates the test +state: +- `+` successful. +- `-` failed. +- A blank indicates that no test has been carried out. + +```none +vyos@vyos:~$ show wan-load-balance +Interface: eth0 +Status: failed +Last Status Change: Tue Jun 11 20:12:19 2019 +-Test: ping Target: + Last Interface Success: 55s + Last Interface Failure: 0s + # Interface Failure(s): 5 + +Interface: eth1 +Status: active +Last Status Change: Tue Jun 11 20:06:42 2019 ++Test: ping Target: + Last Interface Success: 0s + Last Interface Failure: 6m26s + # Interface Failure(s): 0 +``` + +Show connection data of load balanced traffic: + +```none +vyos@vyos:~$ show wan-load-balance connection +conntrack v1.4.2 (conntrack-tools): 3 flow entries have been shown. +Type State Src Dst Packets Bytes +tcp TIME_WAIT 10.1.1.13:38040 203.0.113.2:80 203.0.113.2 192.168.188.71 +udp 10.1.1.13:41891 198.51.100.3:53 198.51.100.3 192.168.188.71 +udp 10.1.1.13:55437 198.51.100.3:53 198.51.100.3 192.168.188.71 +``` + + +### Restart + +```none +restart wan-load-balance +``` diff --git a/docs/configuration/nat/cgnat.md b/docs/configuration/nat/cgnat.md new file mode 100644 index 00000000..914a466b --- /dev/null +++ b/docs/configuration/nat/cgnat.md @@ -0,0 +1,200 @@ +(cgnat)= + +# CGNAT + +{abbr}`CGNAT (Carrier-Grade Network Address Translation)` , also known as +Large-Scale NAT (LSN), is a type of network address translation used by +Internet Service Providers (ISPs) to enable multiple private IP addresses to +share a single public IP address. This technique helps to conserve the limited +IPv4 address space. +The 100.64.0.0/10 address block is reserved for use in carrier-grade NAT + +## Overview + +CGNAT works by placing a NAT device within the ISP's network. This device +translates private IP addresses from customer networks to a limited pool of +public IP addresses assigned to the ISP. This allows many customers to share a +smaller number of public IP addresses. + +Not all {rfc}`6888` requirements are implemented in CGNAT. + +Implemented the following {rfc}`6888` requirements: + +- REQ 2: A CGN must have a default "IP address pooling" behavior of "Paired". + CGN must use the same external IP address mapping for all sessions associated + with the same internal IP address, be they TCP, UDP, ICMP, something else, + or a mix of different protocols. +- REQ 3: The CGN function should not have any limitations on the size or the + contiguity of the external address pool. +- REQ 4: A CGN must support limiting the number of external ports (or, + equivalently, "identifiers" for ICMP) that are assigned per subscriber + +### Advantages of CGNAT + +- **IPv4 Address Conservation**: CGNAT helps mitigate the exhaustion of IPv4 addresses by allowing multiple customers to share a single public IP address. +- **Scalability**: ISPs can support more customers without needing a proportional increase in public IP addresses. +- **Cost-Effective**: Reduces the cost associated with acquiring additional public IPv4 addresses. + +### Considerations + +- **Traceability Issues**: Since multiple users share the same public IP address, tracking individual users for security and legal purposes can be challenging. +- **Performance Overheads**: The translation process can introduce latency and potential performance bottlenecks, especially under high load. +- **Application Compatibility**: Some applications and protocols may not work well with CGNAT due to their reliance on unique public IP addresses. +- **Port Allocation Limits**: Each public IP address has a limited number of ports, which can be exhausted, affecting the ability to establish new connections. +- **Port Control Protocol**: PCP is not implemented. + +## Port calculation + +When implementing CGNAT, ensuring that there are enough ports allocated per subscriber is critical. Below is a summary based on RFC 6888. + +1. **Total Ports Available**: + + - Total Ports: 65536 (0 to 65535) + - Reserved Ports: Assume 1024 ports are reserved for well-known services and administrative purposes. + - Usable Ports: 65536 - 1024 = 64512 + +2. **Estimate Ports Needed per Subscriber**: + + - Example: A household might need 1000 ports to ensure smooth operation for multiple devices and applications. + +3. **Calculate the Number of Subscribers per Public IP**: + + - Usable Ports / Ports per Subscriber + - 64512 / 1000 ≈ 64 subscribers per public IP + +## Configuration + +```{cfgcmd} set nat cgnat pool external \<pool-name\> external-port-range \<port-range\> + +Set an external port-range for the external pool, the default range is +1024-65535. Multiple entries can be added to the same pool. +``` + + +```{cfgcmd} set nat cgnat pool external \<pool-name\> per-user-limit port \<num\> + +Set external source port limits that will be allocated to each subscriber +individually. The default value is 2000. +``` + + +```{cfgcmd} set nat cgnat pool external \<pool-name\> range [address | address range | network] [seq] + +Set the range of external IP addresses for the CGNAT pool. +The sequence is optional; if set, a lower value means higher priority. +``` + + +```{cfgcmd} set nat cgnat pool internal \<pool-name\> range [address range | network] + +Set the range of internal IP addresses for the CGNAT pool. +``` + + +```{cfgcmd} set nat cgnat rule \<num\> source pool \<internal-pool-name\> + +Set the rule for the source pool. +``` + + +```{cfgcmd} set nat cgnat rule \<num\> translation pool \<external-pool-name\> + +Set the rule for the translation pool. +``` + + +```{cfgcmd} set nat cgnat log-allocation + +Enable logging of IP address and ports allocations. +``` + + +## Configuration Examples + +### Single external address + +Example of setting up a basic CGNAT configuration: +In the following example, we define an external pool named `ext-1` with one +external IP address. + +Each subscriber will be allocated a maximum of 2000 ports from the external pool. + +```none +set nat cgnat pool external ext1 external-port-range '1024-65535' +set nat cgnat pool external ext1 per-user-limit port '2000' +set nat cgnat pool external ext1 range '192.0.2.222/32' +set nat cgnat pool internal int1 range '100.64.0.0/28' +set nat cgnat rule 10 source pool 'int1' +set nat cgnat rule 10 translation pool 'ext1' +``` + + +### Multiple external addresses + +```none +set nat cgnat pool external ext1 external-port-range '1024-65535' +set nat cgnat pool external ext1 per-user-limit port '8000' +set nat cgnat pool external ext1 range '192.0.2.1-192.0.2.2' +set nat cgnat pool external ext1 range '203.0.113.253-203.0.113.254' +set nat cgnat pool internal int1 range '100.64.0.1-100.64.0.32' +set nat cgnat rule 10 source pool 'int1' +set nat cgnat rule 10 translation pool 'ext1' +``` + + +### External address sequences + +```none +set nat cgnat pool external ext-01 per-user-limit port '16000' +set nat cgnat pool external ext-01 range 203.0.113.1/32 seq '10' +set nat cgnat pool external ext-01 range 192.0.2.1/32 seq '20' +set nat cgnat pool internal int-01 range '100.64.0.0/29' +set nat cgnat rule 10 source pool 'int-01' +set nat cgnat rule 10 translation pool 'ext-01' +``` + + +## Operation commands + +```{opcmd} show nat cgnat allocation + +Show address and port allocations +``` + +```{opcmd} show nat cgnat allocation external-address \<address\> + +Show all allocations for an external IP address +``` + +```{opcmd} show nat cgnat allocation internal-address \<address\> + +Show all allocations for an internal IP address +``` + + +### Show CGNAT allocations + +```none +vyos@vyos:~$ show nat cgnat allocation +Internal IP External IP Port range +------------- ------------- ------------ +100.64.0.0 203.0.113.1 1024-17023 +100.64.0.1 203.0.113.1 17024-33023 +100.64.0.2 203.0.113.1 33024-49023 +100.64.0.3 203.0.113.1 49024-65023 +100.64.0.4 192.0.2.1 1024-17023 +100.64.0.5 192.0.2.1 17024-33023 +100.64.0.6 192.0.2.1 33024-49023 +100.64.0.7 192.0.2.1 49024-65023 + +vyos@vyos:~$ show nat cgnat allocation internal-address 100.64.0.4 +Internal IP External IP Port range +------------- ------------- ------------ +100.64.0.4 192.0.2.1 1024-17023 +``` + + +## Further Reading + +- {rfc}`6598` - IANA-Reserved IPv4 Prefix for Shared Address Space +- {rfc}`6888` - Requirements for CGNAT diff --git a/docs/configuration/nat/index.md b/docs/configuration/nat/index.md new file mode 100644 index 00000000..35e5d32b --- /dev/null +++ b/docs/configuration/nat/index.md @@ -0,0 +1,13 @@ +(nat)= + +# NAT + +```{toctree} +:includehidden: true +:maxdepth: 1 + +nat44 +nat64 +nat66 +cgnat +``` diff --git a/docs/configuration/nat/nat44.md b/docs/configuration/nat/nat44.md new file mode 100644 index 00000000..8b02477e --- /dev/null +++ b/docs/configuration/nat/nat44.md @@ -0,0 +1,788 @@ +(nat44)= + +# NAT44 + +{abbr}`NAT (Network Address Translation)` is a common method of +remapping one IP address space into another by modifying network address +information in the IP header of packets while they are in transit across +a traffic routing device. The technique was originally used as a +shortcut to avoid the need to readdress every host when a network was +moved. It has become a popular and essential tool in conserving global +address space in the face of IPv4 address exhaustion. One +Internet-routable IP address of a NAT gateway can be used for an entire +private network. + +IP masquerading is a technique that hides an entire IP address space, +usually consisting of private IP addresses, behind a single IP address +in another, usually public address space. The hidden addresses are +changed into a single (public) IP address as the source address of the +outgoing IP packets so they appear as originating not from the hidden +host but from the routing device itself. Because of the popularity of +this technique to conserve IPv4 address space, the term NAT has become +virtually synonymous with IP masquerading. + +As network address translation modifies the IP address information in +packets, NAT implementations may vary in their specific behavior in +various addressing cases and their effect on network traffic. The +specifics of NAT behavior are not commonly documented by vendors of +equipment containing NAT implementations. + +The computers on an internal network can use any of the addresses set +aside by the {abbr}`IANA (Internet Assigned Numbers Authority)` for +private addressing (see {rfc}`1918`). These reserved IP addresses are +not in use on the Internet, so an external machine will not directly +route to them. The following addresses are reserved for private use: + +- 10.0.0.0 to 10.255.255.255 (CIDR: 10.0.0.0/8) +- 172.16.0.0 to 172.31.255.255 (CIDR: 172.16.0.0/12) +- 192.168.0.0 to 192.168.255.255 (CIDR: 192.168.0.0/16) + +If an ISP deploys a {abbr}`CGN (Carrier-grade NAT)`, and uses +{rfc}`1918` address space to number customer gateways, the risk of +address collision, and therefore routing failures, arises when the +customer network already uses an {rfc}`1918` address space. + +This prompted some ISPs to develop a policy within the {abbr}`ARIN +(American Registry for Internet Numbers)` to allocate new private +address space for CGNs, but ARIN deferred to the IETF before +implementing the policy indicating that the matter was not a typical +allocation issue but a reservation of addresses for technical purposes +(per {rfc}`2860`). + +IETF published {rfc}`6598`, detailing a shared address space for use in +ISP CGN deployments that can handle the same network prefixes occurring +both on inbound and outbound interfaces. ARIN returned address space to +the {abbr}`IANA (Internet Assigned Numbers Authority)` for this +allocation. + +The allocated address block is 100.64.0.0/10. + +Devices evaluating whether an IPv4 address is public must be updated to +recognize the new address space. Allocating more private IPv4 address +space for NAT devices might prolong the transition to IPv6. + +## Overview + +### Different NAT Types + +(source-nat)= + +#### SNAT + +{abbr}`SNAT (Source Network Address Translation)` is the most common +form of {abbr}`NAT (Network Address Translation)` and is typically +referred to simply as NAT. To be more correct, what most people refer +to as {abbr}`NAT (Network Address Translation)` is actually the process +of {abbr}`PAT (Port Address Translation)`, or NAT overload. SNAT is +typically used by internal users/private hosts to access the Internet +\- the source address is translated and thus kept private. + +(destination-nat)= + +#### DNAT + +{abbr}`DNAT (Destination Network Address Translation)` changes the +destination address of packets passing through the router, while +{ref}`source-nat` changes the source address of packets. DNAT is +typically used when an external (public) host needs to initiate a +session with an internal (private) host. A customer needs to access a +private service behind the routers public IP. A connection is +established with the routers public IP address on a well known port and +thus all traffic for this port is rewritten to address the internal +(private) host. + +(bidirectional-nat)= + +#### Bidirectional NAT + +This is a common scenario where both {ref}`source-nat` and +{ref}`destination-nat` are configured at the same time. It's commonly +used when internal (private) hosts need to establish a connection with +external resources and external systems need to access internal +(private) resources. + +### NAT, Routing, Firewall Interaction + +There is a very nice picture/explanation in the Vyatta documentation +which should be rewritten here. + +### NAT Ruleset + +{abbr}`NAT (Network Address Translation)` is configured entirely on a +series of so called *rules*. Rules are numbered and evaluated by the +underlying OS in numerical order! The rule numbers can be changes by +utilizing the {cfgcmd}`rename` and {cfgcmd}`copy` commands. + +:::{note} +Changes to the NAT system only affect newly established +connections. Already established connections are not affected. +::: + +:::{hint} +When designing your NAT ruleset leave some space between +consecutive rules for later extension. Your ruleset could start with +numbers 10, 20, 30. You thus can later extend the ruleset and place +new rules between existing ones. +::: + +Rules will be created for both {ref}`source-nat` and +{ref}`destination-nat`. + +For {ref}`bidirectional-nat` a rule for both {ref}`source-nat` and +{ref}`destination-nat` needs to be created. + +(traffic-filters)= + +### Traffic Filters + +Traffic Filters are used to control which packets will have the defined +NAT rules applied. Five different filters can be applied within a NAT +rule. + +- **outbound-interface** - applicable only to {ref}`source-nat`. It + configures the interface which is used for the outside traffic that + this translation rule applies to. Interface groups, inverted + selection and wildcard, are also supported. + + Examples: + + ```none + set nat source rule 20 outbound-interface name eth0 + set nat source rule 30 outbound-interface name bond1* + set nat source rule 20 outbound-interface name !vtun2 + set nat source rule 20 outbound-interface group GROUP1 + set nat source rule 20 outbound-interface group !GROUP2 + ``` + +- **inbound-interface** - applicable only to {ref}`destination-nat`. It + configures the interface which is used for the inside traffic the + translation rule applies to. Interface groups, inverted + selection and wildcard, are also supported. + + Example: + + ```none + set nat destination rule 20 inbound-interface name eth0 + set nat destination rule 30 inbound-interface name bond1* + set nat destination rule 20 inbound-interface name !vtun2 + set nat destination rule 20 inbound-interface group GROUP1 + set nat destination rule 20 inbound-interface group !GROUP2 + ``` + +- **protocol** - specify which types of protocols this translation rule + applies to. Only packets matching the specified protocol are NATed. + By default this applies to *all* protocols. + + Example: + + - Set SNAT rule 20 to only NAT TCP and UDP packets + - Set DNAT rule 20 to only NAT UDP packets + + ```none + set nat source rule 20 protocol tcp_udp + set nat destination rule 20 protocol udp + ``` + +- **source** - specifies which packets the NAT translation rule applies + to based on the packets source IP address and/or source port. Only + matching packets are considered for NAT. + + Example: + + - Set SNAT rule 20 to only NAT packets arriving from the 192.0.2.0/24 + network + - Set SNAT rule 30 to only NAT packets arriving from the 203.0.113.0/24 + network with a source port of 80 and 443 + + ```none + set nat source rule 20 source address 192.0.2.0/24 + set nat source rule 30 source address 203.0.113.0/24 + set nat source rule 30 source port 80,443 + ``` + +- **destination** - specify which packets the translation will be + applied to, only based on the destination address and/or port number + configured. + + :::{note} + If no destination is specified the rule will match on any + destination address and port. + ::: + + Example: + + - Configure SNAT rule (40) to only NAT packets with a destination + address of 192.0.2.1. + + ```none + set nat source rule 40 destination address 192.0.2.1 + ``` + +### Address Conversion + +Every NAT rule has a translation command defined. The address defined +for the translation is the address used when the address information in +a packet is replaced. + +#### Source Address + +For {ref}`source-nat` rules the packets source address will be replaced +with the address specified in the translation command. A port +translation can also be specified and is part of the translation +address. + +:::{note} +The translation address must be set to one of the available +addresses on the configured *outbound-interface* or it must be set to +*masquerade* which will use the primary IP address of the +*outbound-interface* as its translation address. +::: + +:::{note} +When using NAT for a large number of host systems it +recommended that a minimum of 1 IP address is used to NAT every 256 +private host systems. This is due to the limit of 65,000 port numbers +available for unique translations and a reserving an average of +200-300 sessions per host system. +::: + +Example: + +- Define a discrete source IP address of 100.64.0.1 for SNAT rule 20 +- Use address *masquerade* (the interfaces primary address) on rule 30 +- For a large amount of private machines behind the NAT your address + pool might to be bigger. Use any address in the range 100.64.0.10 - + 100.64.0.20 on SNAT rule 40 when doing the translation + +```none +set nat source rule 20 translation address 100.64.0.1 +set nat source rule 30 translation address 'masquerade' +set nat source rule 40 translation address 100.64.0.10-100.64.0.20 +``` + +#### Destination Address + +For {ref}`destination-nat` rules the packets destination address will be +replaced by the specified address in the *translation address* command. + +Example: + +- DNAT rule 10 replaces the destination address of an inbound packet + with 192.0.2.10 + +```none +set nat destination rule 10 translation address 192.0.2.10 +``` + +Also, in {ref}`destination-nat`, redirection to localhost is supported. +The redirect statement is a special form of dnat which always translates +the destination address to the local host’s one. + +Example of redirection: + +```none +set nat destination rule 10 translation redirect port 22 +``` + +### NAT Load Balance + +Advanced configuration can be used in order to apply source or destination NAT, +and within a single rule, be able to define multiple translated addresses, +so NAT balances the translations among them. + +NAT Load Balance uses an algorithm that generates a hash and based on it, then +it applies corresponding translation. This hash can be generated randomly, or +can use data from the ip header: source-address, destination-address, +source-port and/or destination-port. By default, it will generate the hash +randomly. + +When defining the translated address, called `backends`, a `weight` must +be configured. This lets the user define load balance distribution according +to their needs. Them sum of all the weights defined for the backends should +be equal to 100. In oder words, the weight defined for the backend is the +percentage of the connections that will receive such backend. + +```{cfgcmd} set nat [source | destination] rule \<rule\> load-balance hash [source-address | destination-address | source-port | destination-port | random] +``` + +```{cfgcmd} set nat [source | destination] rule \<rule\> load-balance backend \<x.x.x.x\> weight \<1-100\> +``` + +## Configuration Examples + +To setup SNAT, we need to know: +- The internal IP addresses we want to translate +- The outgoing interface to perform the translation on +- The external IP address to translate to + +In the example used for the Quick Start configuration above, we +demonstrate the following configuration: + +```none +set nat source rule 100 outbound-interface name 'eth0' +set nat source rule 100 source address '192.168.0.0/24' +set nat source rule 100 translation address 'masquerade' +``` + +Which generates the following configuration: + +```none +rule 100 { + outbound-interface { + name eth0 + } + source { + address 192.168.0.0/24 + } + translation { + address masquerade + } +} +``` + +In this example, we use **masquerade** as the translation address +instead of an IP address. The **masquerade** target is effectively an +alias to say "use whatever IP address is on the outgoing interface", +rather than a statically configured IP address. This is useful if you +use DHCP for your outgoing interface and do not know what the external +address will be. + +When using NAT for a large number of host systems it recommended that a +minimum of 1 IP address is used to NAT every 256 host systems. This is +due to the limit of 65,000 port numbers available for unique +translations and a reserving an average of 200-300 sessions per host +system. + +Example: For an ~8,000 host network a source NAT pool of 32 IP addresses +is recommended. + +A pool of addresses can be defined by using a hyphen between two IP +addresses: + +```none +set nat source rule 100 translation address '203.0.113.32-203.0.113.63' +``` + +(avoidng-leaky-nat)= + +### Avoiding "leaky" NAT + +Linux netfilter will not NAT traffic marked as INVALID. This often +confuses people into thinking that Linux (or specifically VyOS) has a +broken NAT implementation because non-NATed traffic is seen leaving an +external interface. This is actually working as intended, and a packet +capture of the "leaky" traffic should reveal that the traffic is either +an additional TCP "RST", "FIN,ACK", or "RST,ACK" sent by client systems +after Linux netfilter considers the connection closed. The most common +is the additional TCP RST some host implementations send after +terminating a connection (which is implementation-specific). + +In other words, connection tracking has already observed the connection +be closed and has transition the flow to INVALID to prevent attacks from +attempting to reuse the connection. + +You can avoid the "leaky" behavior by using a firewall policy that drops +"invalid" state packets. + +Having control over the matching of INVALID state traffic, e.g. the +ability to selectively log, is an important troubleshooting tool for +observing broken protocol behavior. For this reason, VyOS does not +globally drop invalid state traffic, instead allowing the operator to +make the determination on how the traffic is handled. + +(hairpin-nat-reflection)= + +### Hairpin NAT/NAT Reflection + +A typical problem with using NAT and hosting public servers is the +ability for internal systems to reach an internal server using it's +external IP address. The solution to this is usually the use of +split-DNS to correctly point host systems to the internal address when +requests are made internally. Because many smaller networks lack DNS +infrastructure, a work-around is commonly deployed to facilitate the +traffic by NATing the request from internal hosts to the source address +of the internal interface on the firewall. + +This technique is commonly referred to as NAT Reflection or Hairpin NAT. + +Example: + +- Redirect Microsoft RDP traffic from the outside (WAN, external) world + via {ref}`destination-nat` in rule 100 to the internal, private host + 192.0.2.40. +- Redirect Microsoft RDP traffic from the internal (LAN, private) + network via {ref}`destination-nat` in rule 110 to the internal, + private host 192.0.2.40. We also need a {ref}`source-nat` rule 110 for + the reverse path of the traffic. The internal network 192.0.2.0/24 is + reachable via interface *eth0.10*. + +```none +set nat destination rule 100 description 'Regular destination NAT from external' +set nat destination rule 100 destination port '3389' +set nat destination rule 100 inbound-interface name 'pppoe0' +set nat destination rule 100 protocol 'tcp' +set nat destination rule 100 translation address '192.0.2.40' + +set nat destination rule 110 description 'NAT Reflection: INSIDE' +set nat destination rule 110 destination port '3389' +set nat destination rule 110 inbound-interface name 'eth0.10' +set nat destination rule 110 protocol 'tcp' +set nat destination rule 110 translation address '192.0.2.40' + +set nat source rule 110 description 'NAT Reflection: INSIDE' +set nat source rule 110 destination address '192.0.2.0/24' +set nat source rule 110 outbound-interface name 'eth0.10' +set nat source rule 110 protocol 'tcp' +set nat source rule 110 source address '192.0.2.0/24' +set nat source rule 110 translation address 'masquerade' +``` + +Which results in a configuration of: + +```none +vyos@vyos# show nat + destination { + rule 100 { + description "Regular destination NAT from external" + destination { + port 3389 + } + inbound-interface { + name pppoe0 + } + protocol tcp + translation { + address 192.0.2.40 + } + } + rule 110 { + description "NAT Reflection: INSIDE" + destination { + port 3389 + } + inbound-interface { + name eth0.10 + } + protocol tcp + translation { + address 192.0.2.40 + } + } + } + source { + rule 110 { + description "NAT Reflection: INSIDE" + destination { + address 192.0.2.0/24 + } + outbound-interface { + name eth0.10 + } + protocol tcp + source { + address 192.0.2.0/24 + } + translation { + address masquerade + } + } + } +``` + +### Destination NAT + +DNAT is typically referred to as a **Port Forward**. When using VyOS as +a NAT router and firewall, a common configuration task is to redirect +incoming traffic to a system behind the firewall. + +In this example, we will be using the example Quick Start configuration +above as a starting point. + +To setup a destination NAT rule we need to gather: +- The interface traffic will be coming in on; +- The protocol and port we wish to forward; +- The IP address of the internal system we wish to forward traffic to. + +In our example, we will be forwarding web server traffic to an internal +web server on 192.168.0.100. HTTP traffic makes use of the TCP protocol +on port 80. For other common port numbers, see: +<https://en.wikipedia.org/wiki/List_of_TCP_and_UDP_port_numbers> + +Our configuration commands would be: + +```none +set nat destination rule 10 description 'Port Forward: HTTP to 192.168.0.100' +set nat destination rule 10 destination port '80' +set nat destination rule 10 inbound-interface name 'eth0' +set nat destination rule 10 protocol 'tcp' +set nat destination rule 10 translation address '192.168.0.100' +``` + +Which would generate the following NAT destination configuration: + +```none +nat { + destination { + rule 10 { + description "Port Forward: HTTP to 192.168.0.100" + destination { + port 80 + } + inbound-interface { + name eth0 + } + protocol tcp + translation { + address 192.168.0.100 + } + } + } +} +``` +:::{note} +If forwarding traffic to a different port than it is arriving +on, you may also configure the translation port using +*set nat destination rule [n] translation port*. +::: + +This establishes our Port Forward rule, but if we created a firewall +policy it will likely block the traffic. + +#### Firewall rules for Destination NAT + +It is important to note that when creating firewall rules, the DNAT +translation occurs **before** traffic traverses the firewall. In other +words, the destination address has already been translated to +192.168.0.100. + +So in our firewall ruleset, we want to allow traffic which previously matched +a destination nat rule. In order to avoid creating many rules, one for each +destination nat rule, we can accept all **'dnat'** connections with one simple +rule, using `connection-status` matcher: + +```none +set firewall ipv4 forward filter rule 10 action accept +set firewall ipv4 forward filter rule 10 connection-status nat destination +set firewall ipv4 forward filter rule 10 state new +``` + +This would generate the following configuration: + +```none +ipv4 { + forward { + filter { + rule 10 { + action accept + connection-status { + nat destination + } + state new + } + } + } +} +``` + +### 1-to-1 NAT + +Another term often used for DNAT is **1-to-1 NAT**. For a 1-to-1 NAT +configuration, both DNAT and SNAT are used to NAT all traffic from an +external IP address to an internal IP address and vice-versa. + +Typically, a 1-to-1 NAT rule omits the destination port (all ports) and +replaces the protocol with either **all** or **ip**. + +Then a corresponding SNAT rule is created to NAT outgoing traffic for +the internal IP to a reserved external IP. This dedicates an external IP +address to an internal IP address and is useful for protocols which +don't have the notion of ports, such as GRE. + +Here's an extract of a simple 1-to-1 NAT configuration with one internal +and one external interface: + +```none +set interfaces ethernet eth0 address '192.168.1.1/24' +set interfaces ethernet eth0 description 'Inside interface' +set interfaces ethernet eth1 address '192.0.2.30/24' +set interfaces ethernet eth1 description 'Outside interface' +set nat destination rule 2000 description '1-to-1 NAT example' +set nat destination rule 2000 destination address '192.0.2.30' +set nat destination rule 2000 inbound-interface name 'eth1' +set nat destination rule 2000 translation address '192.168.1.10' +set nat source rule 2000 description '1-to-1 NAT example' +set nat source rule 2000 outbound-interface name 'eth1' +set nat source rule 2000 source address '192.168.1.10' +set nat source rule 2000 translation address '192.0.2.30' +``` + +Firewall rules are written as normal, using the internal IP address as +the source of outbound rules and the destination of inbound rules. + +### NAT before VPN + +Some application service providers (ASPs) operate a VPN gateway to +provide access to their internal resources, and require that a +connecting organisation translate all traffic to the service provider +network to a source address provided by the ASP. + +### Load Balance + +Here we provide two examples on how to apply NAT Load Balance. + +First scenario: apply destination NAT for all HTTP traffic coming through +interface eth0, and user 4 backends. First backend should received 30% of +the request, second backend should get 20%, third 15% and the fourth 35% +We will use source and destination address for hash generation. + +```none +set nat destination rule 10 inbound-interface name eth0 +set nat destination rule 10 protocol tcp +set nat destination rule 10 destination port 80 +set nat destination rule 10 load-balance hash source-address +set nat destination rule 10 load-balance hash destination-address +set nat destination rule 10 load-balance backend 198.51.100.101 weight 30 +set nat destination rule 10 load-balance backend 198.51.100.102 weight 20 +set nat destination rule 10 load-balance backend 198.51.100.103 weight 15 +set nat destination rule 10 load-balance backend 198.51.100.104 weight 35 +``` + +Second scenario: apply source NAT for all outgoing connections from +LAN 10.0.0.0/8, using 3 public addresses and equal distribution. +We will generate the hash randomly. + +```none +set nat source rule 10 outbound-interface name eth0 +set nat source rule 10 source address 10.0.0.0/8 +set nat source rule 10 load-balance hash random +set nat source rule 10 load-balance backend 192.0.2.251 weight 33 +set nat source rule 10 load-balance backend 192.0.2.252 weight 33 +set nat source rule 10 load-balance backend 192.0.2.253 weight 34 +``` + +#### Example Network + +Here's one example of a network environment for an ASP. +The ASP requests that all connections from this company should come from +172.29.41.89 - an address that is assigned by the ASP and not in use at +the customer site. + +```{eval-rst} +.. figure:: /_static/images/nat_before_vpn_topology.webp + :scale: 100 % + :alt: NAT before VPN Topology + + NAT before VPN Topology +``` +#### Configuration + +The required configuration can be broken down into 4 major pieces: +- A dummy interface for the provider-assigned IP; +- NAT (specifically, Source NAT); +- IPSec IKE and ESP Groups; +- IPSec VPN tunnels. + +##### Dummy interface + +The dummy interface allows us to have an equivalent of the Cisco IOS +Loopback interface - a router-internal interface we can use for IP +addresses the router must know about, but which are not actually +assigned to a real network. + +We only need a single step for this interface: + +```none +set interfaces dummy dum0 address '172.29.41.89/32' +``` + +##### NAT Configuration + +```none +set nat source rule 110 description 'Internal to ASP' +set nat source rule 110 destination address '172.27.1.0/24' +set nat source rule 110 source address '192.168.43.0/24' +set nat source rule 110 translation address '172.29.41.89' +set nat source rule 120 description 'Internal to ASP' +set nat source rule 120 destination address '10.125.0.0/16' +set nat source rule 120 source address '192.168.43.0/24' +set nat source rule 120 translation address '172.29.41.89' +``` + +##### IPSec IKE and ESP + +The ASP has documented their IPSec requirements: +- IKE Phase: + - aes256 Encryption + - sha256 Hashes +- ESP Phase: + - aes256 Encryption + - sha256 Hashes + - DH Group 14 + +Additionally, we want to use VPNs only on our eth1 interface (the +external interface in the image above) + +```none +set vpn ipsec ike-group my-ike key-exchange 'ikev1' +set vpn ipsec ike-group my-ike lifetime '7800' +set vpn ipsec ike-group my-ike proposal 1 dh-group '14' +set vpn ipsec ike-group my-ike proposal 1 encryption 'aes256' +set vpn ipsec ike-group my-ike proposal 1 hash 'sha256' + +set vpn ipsec esp-group my-esp lifetime '3600' +set vpn ipsec esp-group my-esp mode 'tunnel' +set vpn ipsec esp-group my-esp pfs 'disable' +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 interface 'eth1' +``` + +##### IPSec VPN Tunnels + +We'll use the IKE and ESP groups created above for this VPN. Because we +need access to 2 different subnets on the far side, we will need two +different tunnels. If you changed the names of the ESP group and IKE +group in the previous step, make sure you use the correct names here +too. + +```none +set vpn ipsec authentication psk vyos id '203.0.113.46' +set vpn ipsec authentication psk vyos id '198.51.100.243' +set vpn ipsec authentication psk vyos secret 'MYSECRETPASSWORD' +set vpn ipsec site-to-site peer branch authentication local-id '203.0.113.46' +set vpn ipsec site-to-site peer branch authentication mode 'pre-shared-secret' +set vpn ipsec site-to-site peer branch authentication remote-id '198.51.100.243' +set vpn ipsec site-to-site peer branch connection-type 'initiate' +set vpn ipsec site-to-site peer branch default-esp-group 'my-esp' +set vpn ipsec site-to-site peer branch ike-group 'my-ike' +set vpn ipsec site-to-site peer branch ikev2-reauth 'inherit' +set vpn ipsec site-to-site peer branch local-address '203.0.113.46' +set vpn ipsec site-to-site peer branch remote-address '198.51.100.243' +set vpn ipsec site-to-site peer branch tunnel 0 local prefix '172.29.41.89/32' +set vpn ipsec site-to-site peer branch tunnel 0 remote prefix '172.27.1.0/24' +set vpn ipsec site-to-site peer branch tunnel 1 local prefix '172.29.41.89/32' +set vpn ipsec site-to-site peer branch tunnel 1 remote prefix '10.125.0.0/16' +``` + +##### Testing and Validation + +If you've completed all the above steps you no doubt want to see if it's +all working. + +Start by checking for IPSec SAs (Security Associations) with: + +```none +$ show vpn ipsec sa + +Peer ID / IP Local ID / IP +------------ ------------- +198.51.100.243 203.0.113.46 + + Tunnel State Bytes Out/In Encrypt Hash NAT-T A-Time L-Time Proto + ------ ----- ------------- ------- ---- ----- ------ ------ ----- + 0 up 0.0/0.0 aes256 sha256 no 1647 3600 all + 1 up 0.0/0.0 aes256 sha256 no 865 3600 all +``` + +That looks good - we defined 2 tunnels and they're both up and running. diff --git a/docs/configuration/nat/nat64.md b/docs/configuration/nat/nat64.md new file mode 100644 index 00000000..c1b1c994 --- /dev/null +++ b/docs/configuration/nat/nat64.md @@ -0,0 +1,73 @@ +(nat64)= + +# NAT64 + +{abbr}`NAT64 (IPv6-to-IPv4 Prefix Translation)` is a critical component in +modern networking, facilitating communication between IPv6 and IPv4 networks. +This documentation outlines the setup, configuration, and usage of the NAT64 +feature in your project. Whether you are transitioning to IPv6 or need to +seamlessly connect IPv4 and IPv6 devices. +NAT64 is a stateful translation mechanism that translates IPv6 addresses to +IPv4 addresses and IPv4 addresses to IPv6 addresses. NAT64 is used to enable +IPv6-only clients to contact IPv4 servers using unicast UDP, TCP, or ICMP. + +## Overview + +### Different NAT Types + +(source-nat64)= + +#### SNAT64 + +{abbr}`SNAT64 (IPv6-to-IPv4 Source Address Translation)` is a stateful +translation mechanism that translates IPv6 addresses to IPv4 addresses. + +`64:ff9b::/96` is the well-known prefix for IPv4-embedded IPv6 addresses. +The prefix is used to represent IPv4 addresses in an IPv6 address format. +The IPv4 address is encoded in the low-order 32 bits of the IPv6 address. +The high-order 32 bits are set to the well-known prefix 64:ff9b::/96. + +## Configuration Examples + +The following examples show how to configure NAT64 on a VyOS router. +The 192.0.2.10 address is used as the IPv4 address for the translation pool. + +NAT64 server configuration: + +```none +set interfaces ethernet eth0 address '192.0.2.1/24' +set interfaces ethernet eth0 address '192.0.2.10/24' +set interfaces ethernet eth0 description 'WAN' +set interfaces ethernet eth1 address '2001:db8::1/64' +set interfaces ethernet eth1 description 'LAN' + +set service dns forwarding allow-from '2001:db8::/64' +set service dns forwarding dns64-prefix '64:ff9b::/96' +set service dns forwarding listen-address '2001:db8::1' + +set nat64 source rule 100 source prefix '64:ff9b::/96' +set nat64 source rule 100 translation pool 10 address '192.0.2.10' +set nat64 source rule 100 translation pool 10 port '1-65535' +``` + +NAT64 client configuration: + +```none +set interfaces ethernet eth1 address '2001:db8::2/64' +set protocols static route6 64:ff9b::/96 next-hop 2001:db8::1 +set system name-server '2001:db8::1' +``` + +Test from the IPv6 only client: + +```none +vyos@r1:~$ ping 64:ff9b::192.0.2.1 count 2 +PING 64:ff9b::192.0.2.1(64:ff9b::c000:201) 56 data bytes +64 bytes from 64:ff9b::c000:201: icmp_seq=1 ttl=63 time=0.351 ms +64 bytes from 64:ff9b::c000:201: icmp_seq=2 ttl=63 time=0.373 ms + +--- 64:ff9b::192.0.2.1 ping statistics --- +2 packets transmitted, 2 received, 0% packet loss, time 1023ms +rtt min/avg/max/mdev = 0.351/0.362/0.373/0.011 ms +``` + diff --git a/docs/configuration/nat/nat66.md b/docs/configuration/nat/nat66.md new file mode 100644 index 00000000..1cbe3317 --- /dev/null +++ b/docs/configuration/nat/nat66.md @@ -0,0 +1,243 @@ +(nat66)= + +# NAT66(NPTv6) + +```{todo} +Convert raw command blocks in this file to cfgcmd/opcmd +directives for command coverage tracking. +``` + +{abbr}`NPTv6 (IPv6-to-IPv6 Network Prefix Translation)` is an address +translation technology based on IPv6 networks, used to convert an IPv6 +address prefix in an IPv6 message into another IPv6 address prefix. +We call this address translation method NAT66. Devices that support the NAT66 +function are called NAT66 devices, which can provide NAT66 source +and destination address translation functions. + +## Overview + +### Different NAT Types + +(source-nat66)= + +#### SNAT66 + +{abbr}`SNPTv6 (Source IPv6-to-IPv6 Network Prefix Translation)` The conversion +function is mainly used in the following scenarios: +- A single internal network and external network. Use the NAT66 device to + connect a single internal network and public network, and the hosts in + the internal network use IPv6 address prefixes that only support + routing within the local range. When a host in the internal network + accesses the external network, the source IPv6 address prefix in + the message will be converted into a global unicast IPv6 address + prefix by the NAT66 device. +- Redundancy and load sharing. There are multiple NAT66 devices at the edge + of an IPv6 network to another IPv6 network. The path through the NAT66 + device to another IPv6 network forms an equivalent route, and traffic + can be load-shared on these NAT66 devices. In this case, you + can configure the same source address translation rules on these + NAT66 devices, so that any NAT66 device can handle IPv6 traffic between + different sites. +- Multi-homed. In a multi-homed network environment, the NAT66 device + connects to an internal network and simultaneously connects to + different external networks. Address translation can be configured + on each external network side interface of the NAT66 device to + convert the same internal network address into different external + network addresses, and realize the mapping of the same internal + address to multiple external addresses. +(destination-nat66)= + +#### DNAT66 + +The {abbr}`DNPTv6 (Destination IPv6-to-IPv6 Network Prefix Translation)` +destination address translation function is used in scenarios where the +server in the internal network provides services to the external network, +such as providing Web services or FTP services to the external network. +By configuring the mapping relationship between the internal server +address and the external network address on the external network +side interface of the NAT66 device, external network users can +access the internal network server through the designated +external network address. + +### Prefix Conversion + +#### Source Prefix + +Every SNAT66 rule has a translation command defined. The prefix defined +for the translation is the prefix used when the address information in +a packet is replaced.、 + +The {ref}`source-nat66` rule replaces the source address of the packet +and calculates the converted address using the prefix specified in the rule. + +Example: +- Convert the address prefix of a single `fc01::/64` network to `fc00::/64` +- Output from `eth0` network interface + +```none +set nat66 source rule 1 outbound-interface name 'eth0' +set nat66 source rule 1 source prefix 'fc01::/64' +set nat66 source rule 1 translation address 'fc00::/64' +``` + + +#### Destination Prefix + +For the {ref}`destination-nat66` rule, the destination address of +the packet isreplaced by the address calculated from the specified +address or prefix in the `translation address` command + +Example: +- Convert the address prefix of a single `fc00::/64` network + to `fc01::/64` +- Input from `eth0` network interface + +```none +set nat66 destination rule 1 inbound-interface name 'eth0' +set nat66 destination rule 1 destination address 'fc00::/64' +set nat66 destination rule 1 translation address 'fc01::/64' +``` + +For the destination, groups can also be used instead of an address. + +Example: + +```none +set firewall group ipv6-address-group ADR-INSIDE-v6 address fc00::1 + +set nat66 destination rule 1 inbound-interface name 'eth0' +set nat66 destination rule 1 destination group address-group ADR-INSIDE-v6 +set nat66 destination rule 1 translation address 'fc01::/64' +``` + + +## Configuration Examples + +Use the following topology to build a nat66 based isolated +network between internal and external networks (dynamic prefix is +not supported): + +:::{figure} /_static/images/vyos_1_4_nat66_simple.webp +:alt: VyOS NAT66 Simple Configure +::: + +R1: + +```none +set interfaces ethernet eth0 ipv6 address autoconf +set interfaces ethernet eth1 address 'fc01::1/64' +set nat66 destination rule 1 destination address 'fc00:470:f1cd:101::/64' +set nat66 destination rule 1 inbound-interface name 'eth0' +set nat66 destination rule 1 translation address 'fc01::/64' +set nat66 source rule 1 outbound-interface name 'eth0' +set nat66 source rule 1 source prefix 'fc01::/64' +set nat66 source rule 1 translation address 'fc00:470:f1cd:101::/64' +``` + +R2: + +```none +set interfaces bridge br1 address 'fc01::2/64' +set interfaces bridge br1 member interface eth0 +set interfaces bridge br1 member interface eth1 +set protocols static route6 ::/0 next-hop fc01::1 +set service router-advert interface br1 prefix ::/0 +``` + +Use the following topology to translate internal user local addresses +(`fc::/7`) to DHCPv6-PD provided prefixes from an ISP connected to +a VyOS HA pair. + +:::{figure} /_static/images/vyos_1_5_nat66_dhcpv6_wdummy.webp +:alt: VyOS NAT66 DHCPv6 using a dummy interface +::: + +Configure both routers (a and b) for DHCPv6-PD via dummy interface: + +```none +set interfaces dummy dum1 description 'DHCPv6-PD NPT dummy' +set interfaces bonding bond0 vif 20 dhcpv6-options pd 0 interface dum1 address '0' +set interfaces bonding bond0 vif 20 dhcpv6-options pd 1 interface dum1 address '0' +set interfaces bonding bond0 vif 20 dhcpv6-options pd 2 interface dum1 address '0' +set interfaces bonding bond0 vif 20 dhcpv6-options pd 3 interface dum1 address '0' +set interfaces bonding bond0 vif 20 dhcpv6-options rapid-commit +commit +``` + +Get the DHCPv6-PD prefixes from both routers: + +```none +trae@cr01a-vyos# run show interfaces dummy dum1 br +Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down +Interface IP Address S/L Description +--------- ---------- --- ----------- +dum1 2001:db8:123:b008::/64 u/u DHCPv6-PD NPT dummy + 2001:db8:123:b00a::/64 + 2001:db8:123:b00b::/64 + 2001:db8:123:b009::/64 + +trae@cr01b-vyos# run show int dummy dum1 brief +Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down +Interface IP Address S/L Description +--------- ---------- --- ----------- +dum1 2001:db8:123:b00d::/64 u/u DHCPv6-PD NPT dummy + 2001:db8:123:b00c::/64 + 2001:db8:123:b00e::/64 + 2001:db8:123:b00f::/64 +``` + +Configure the A-side router for NPTv6 using the prefixes above: + +```none +set nat66 source rule 10 description 'NPT to VLAN 10' +set nat66 source rule 10 outbound-interface name 'bond0.20' +set nat66 source rule 10 source prefix 'fd52:d62e:8011:a::/64' +set nat66 source rule 10 translation address '2001:db8:123:b008::/64' +set nat66 source rule 20 description 'NPT to VLAN 70' +set nat66 source rule 20 outbound-interface name 'bond0.20' +set nat66 source rule 20 source prefix 'fd52:d62e:8011:46::/64' +set nat66 source rule 20 translation address '2001:db8:123:b009::/64' +set nat66 source rule 30 description 'NPT to VLAN 200' +set nat66 source rule 30 outbound-interface name 'bond0.20' +set nat66 source rule 30 source prefix 'fd52:d62e:8011:c8::/64' +set nat66 source rule 30 translation address '2001:db8:123:b00a::/64' +set nat66 source rule 40 description 'NPT to VLAN 240' +set nat66 source rule 40 outbound-interface name 'bond0.20' +set nat66 source rule 40 source prefix 'fd52:d62e:8011:f0::/64' +set nat66 source rule 40 translation address '2001:db8:123:b00b::/64' +commit +``` + +Configure the B-side router for NPTv6 using the prefixes above: + +```none +set nat66 source rule 10 description 'NPT to VLAN 10' +set nat66 source rule 10 outbound-interface name 'bond0.20' +set nat66 source rule 10 source prefix 'fd52:d62e:8011:a::/64' +set nat66 source rule 10 translation address '2001:db8:123:b00c::/64' +set nat66 source rule 20 description 'NPT to VLAN 70' +set nat66 source rule 20 outbound-interface name 'bond0.20' +set nat66 source rule 20 source prefix 'fd52:d62e:8011:46::/64' +set nat66 source rule 20 translation address '2001:db8:123:b00d::/64' +set nat66 source rule 30 description 'NPT to VLAN 200' +set nat66 source rule 30 outbound-interface name 'bond0.20' +set nat66 source rule 30 source prefix 'fd52:d62e:8011:c8::/64' +set nat66 source rule 30 translation address '2001:db8:123:b00e::/64' +set nat66 source rule 40 description 'NPT to VLAN 240' +set nat66 source rule 40 outbound-interface name 'bond0.20' +set nat66 source rule 40 source prefix 'fd52:d62e:8011:f0::/64' +set nat66 source rule 40 translation address '2001:db8:123:b00f::/64' +commit +``` + +Verify that connections are hitting the rule on both sides: + +```none +trae@cr01a-vyos# run show nat66 source statistics +Rule Packets Bytes Interface +------ --------- ------- ----------- +10 1 104 bond0.20 +20 1 104 bond0.20 +30 8093 669445 bond0.20 +40 2446 216912 bond0.20 +``` diff --git a/docs/configuration/nat/cgnat.rst b/docs/configuration/nat/rst-cgnat.rst index 1848d45e..1848d45e 100644 --- a/docs/configuration/nat/cgnat.rst +++ b/docs/configuration/nat/rst-cgnat.rst diff --git a/docs/configuration/nat/index.rst b/docs/configuration/nat/rst-index.rst index 2ecacc72..2ecacc72 100644 --- a/docs/configuration/nat/index.rst +++ b/docs/configuration/nat/rst-index.rst diff --git a/docs/configuration/nat/nat44.rst b/docs/configuration/nat/rst-nat44.rst index 63b787ba..63b787ba 100644 --- a/docs/configuration/nat/nat44.rst +++ b/docs/configuration/nat/rst-nat44.rst diff --git a/docs/configuration/nat/nat64.rst b/docs/configuration/nat/rst-nat64.rst index 04ba56f4..04ba56f4 100644 --- a/docs/configuration/nat/nat64.rst +++ b/docs/configuration/nat/rst-nat64.rst diff --git a/docs/configuration/nat/nat66.rst b/docs/configuration/nat/rst-nat66.rst index aecce524..aecce524 100644 --- a/docs/configuration/nat/nat66.rst +++ b/docs/configuration/nat/rst-nat66.rst diff --git a/docs/configuration/pki/index.md b/docs/configuration/pki/index.md new file mode 100644 index 00000000..e7d793de --- /dev/null +++ b/docs/configuration/pki/index.md @@ -0,0 +1,583 @@ +--- +lastproofread: '2024-01-05' +--- + +```{include} /_include/need_improvement.txt +``` + +(pki)= + +# PKI + +VyOS 1.4 changed the way in how encryption keys or certificates are stored on the +system. In the pre VyOS 1.4 era, certificates got stored under /config and every +service referenced a file. That made copying a running configuration from system +A to system B a bit harder, as you had to copy the files and their permissions +by hand. + +{vytask}`T3642` describes a new CLI subsystem that serves as a "certstore" to +all services requiring any kind of encryption key(s). In short, public and +private certificates are now stored in PKCS#8 format in the regular VyOS CLI. +Keys can now be added, edited, and deleted using the regular set/edit/delete +CLI commands. + +VyOS not only can now manage certificates issued by 3rd party Certificate +Authorities, it can also act as a CA on its own. You can create your own root +CA and sign keys with it by making use of some simple op-mode commands. + +Don't be afraid that you need to re-do your configuration. Key transformation is +handled, as always, by our migration scripts, so this will be a smooth transition +for you! + +## Key Generation + +### Certificate Authority (CA) + +VyOS now also has the ability to create CAs, keys, Diffie-Hellman and other +keypairs from an easy to access operational level command. + +```{opcmd} generate pki ca + +Create a new {abbr}`CA (Certificate Authority)` and output the CAs public and +private key on the console. +``` + +```{opcmd} generate pki ca install \<name\> + +Create a new {abbr}`CA (Certificate Authority)` and output the CAs public and +private key on the console. + +:::{note} +In addition to the command above, the output is in a format which can be used +to directly import the key into the VyOS CLI by simply copy-pasting the output +from op-mode into configuration mode. + +``name`` is used for the VyOS CLI command to identify this key. This +key ``name`` is then used in the CLI configuration to reference the key +instance. +::: +``` + +```{opcmd} generate pki ca sign \<ca-name\> + +Create a new subordinate {abbr}`CA (Certificate Authority)` and sign it using +the private key referenced by ca-name. +``` + +```{opcmd} generate pki ca sign \<ca-name\> install \<name\> + +Create a new subordinate {abbr}`CA (Certificate Authority)` and sign it using +the private key referenced by `name`. + +:::{note} +In addition to the command above, the output is in a format which can be used +to directly import the key into the VyOS CLI by simply copy-pasting the output +from op-mode into configuration mode. + +``name`` is used for the VyOS CLI command to identify this key. This +key ``name`` is then used in the CLI configuration to reference the key +instance. +::: +``` + +### Certificates + +```{opcmd} generate pki certificate + +Create a new public/private keypair and output the certificate on the console. +``` + +```{opcmd} generate pki certificate install \<name\> + +Create a new public/private keypair and output the certificate on the console. + +:::{note} +In addition to the command above, the output is in a format which can be used +to directly import the key into the VyOS CLI by simply copy-pasting the output +from op-mode into configuration mode. + +``name`` is used for the VyOS CLI command to identify this key. This +key ``name`` is then used in the CLI configuration to reference the key +instance. +::: +``` + +```{opcmd} generate pki certificate self-signed + +Create a new self-signed certificate. The public/private is then shown on the +console. +``` + +```{opcmd} generate pki certificate self-signed install \<name\> + +Create a new self-signed certificate. The public/private is then shown on the +console. + +:::{note} +In addition to the command above, the output is in a format which can be used +to directly import the key into the VyOS CLI by simply copy-pasting the output +from op-mode into configuration mode. + +``name`` is used for the VyOS CLI command to identify this key. This +key ``name`` is then used in the CLI configuration to reference the key +instance. +::: +``` + +```{opcmd} generate pki certificate sign \<ca-name\> + +Create a new public/private keypair which is signed by the CA referenced by +ca-name. The signed certificate is then output to the console. +``` + +```{opcmd} generate pki certificate sign \<ca-name\> install \<name\> + +Create a new public/private keypair which is signed by the CA referenced by +ca-name. The signed certificate is then output to the console. + +:::{note} +In addition to the command above, the output is in a format which can be used +to directly import the key into the VyOS CLI by simply copy-pasting the output +from op-mode into configuration mode. + +``name`` is used for the VyOS CLI command to identify this key. This +key ``name`` is then used in the CLI configuration to reference the key +instance. +::: +``` + +### Diffie-Hellman parameters + +```{opcmd} generate pki dh + +Generate a new set of {abbr}`DH (Diffie-Hellman)` parameters. The key size +is requested by the CLI and defaults to 2048 bit. + +The generated parameters are then output to the console. +``` + +```{opcmd} generate pki dh install \<name\> + +Generate a new set of {abbr}`DH (Diffie-Hellman)` parameters. The key size +is requested by the CLI and defaults to 2048 bit. + +:::{note} +In addition to the command above, the output is in a format which can be used +to directly import the key into the VyOS CLI by simply copy-pasting the output +from op-mode into configuration mode. + +``name`` is used for the VyOS CLI command to identify this key. This +key ``name`` is then used in the CLI configuration to reference the key +instance. +::: +``` + +### OpenVPN + +```{opcmd} generate pki openvpn shared-secret + +Generate a new OpenVPN shared secret. The generated secret is the output to +the console. +``` + +```{opcmd} generate pki openvpn shared-secret install \<name\> + +Generate a new OpenVPN shared secret. The generated secret is the output to +the console. + +:::{note} +In addition to the command above, the output is in a format which can be used +to directly import the key into the VyOS CLI by simply copy-pasting the output +from op-mode into configuration mode. + +``name`` is used for the VyOS CLI command to identify this key. This +key ``name`` is then used in the CLI configuration to reference the key +instance. +::: +``` + +### WireGuard + +```{opcmd} generate pki wireguard key-pair + +Generate a new WireGuard public/private key portion and output the result to +the console. +``` + +```{opcmd} generate pki wireguard key-pair install \<interface\> + +Generate a new WireGuard public/private key portion and output the result to +the console. + +:::{note} +In addition to the command above, the output is in a format which can +be used to directly import the key into the VyOS CLI by simply copy-pasting +the output from op-mode into configuration mode. + +``interface`` is used for the VyOS CLI command to identify the WireGuard +interface where this private key is to be used. +::: +``` + +```{opcmd} generate pki wireguard preshared-key + +Generate a WireGuard pre-shared secret used for peers to communicate. +``` + +```{opcmd} generate pki wireguard preshared-key install \<peer\> + +Generate a WireGuard pre-shared secret used for peers to communicate. + +:::{note} +In addition to the command above, the output is in a format which can +be used to directly import the key into the VyOS CLI by simply copy-pasting +the output from op-mode into configuration mode. + +``peer`` is used for the VyOS CLI command to identify the WireGuard peer where +this secret is to be used. +::: +``` + +## Key usage (CLI) +### CA (Certificate Authority) + +```{cfgcmd} set pki ca \<name\> certificate + +Add the public CA certificate for the CA named `name` to the VyOS CLI. + +:::{note} +When loading the certificate you need to manually strip the +``-----BEGIN CERTIFICATE-----`` and ``-----END CERTIFICATE-----`` tags. +Also, the certificate/key needs to be presented in a single line without +line breaks (``\n``), this can be done using the following shell command: + +``$ tail -n +2 ca.pem | head -n -1 | tr -d '\n'`` +::: +``` + +```{cfgcmd} set pki ca \<name\> crl + +Certificate revocation list in PEM format. +``` + +```{cfgcmd} set pki ca \<name\> description + +A human readable description what this CA is about. +``` + +```{cfgcmd} set pki ca \<name\> private key + +Add the CAs private key to the VyOS CLI. This should never leave the system, +and is only required if you use VyOS as your certificate generator as +mentioned above. + +:::{note} +When loading the certificate you need to manually strip the +``-----BEGIN KEY-----`` and ``-----END KEY-----`` tags. Also, the +certificate/key needs to be presented in a single line without line +breaks (``\n``), this can be done using the following shell command: + +``$ tail -n +2 ca.key | head -n -1 | tr -d '\n'`` +::: +``` + +```{cfgcmd} set pki ca \<name\> private password-protected + +Mark the CAs private key as password protected. User is asked for the password +when the key is referenced. +``` + +### Server Certificate + +After we have imported the CA certificate(s) we can now import and add +certificates used by services on this router. + +```{cfgcmd} set pki certificate \<name\> certificate + +Add public key portion for the certificate named `name` to the VyOS CLI. + +:::{note} +When loading the certificate you need to manually strip the +``-----BEGIN CERTIFICATE-----`` and ``-----END CERTIFICATE-----`` tags. +Also, the certificate/key needs to be presented in a single line without +line breaks (``\n``), this can be done using the following shell command: + +``$ tail -n +2 cert.pem | head -n -1 | tr -d '\n'`` +::: +``` + +```{cfgcmd} set pki certificate \<name\> description + +A human readable description what this certificate is about. +``` + +```{cfgcmd} set pki certificate \<name\> private key + +Add the private key portion of this certificate to the CLI. This should never +leave the system as it is used to decrypt the data. + +:::{note} +When loading the certificate you need to manually strip the +``-----BEGIN KEY-----`` and ``-----END KEY-----`` tags. Also, the +certificate/key needs to be presented in a single line without line +breaks (``\n``), this can be done using the following shell command: + +``$ tail -n +2 cert.key | head -n -1 | tr -d '\n'`` +::: +``` + +```{cfgcmd} set pki certificate \<name\> private password-protected + +Mark the private key as password protected. User is asked for the password +when the key is referenced. +``` + +```{cfgcmd} set pki certificate \<name\> revoke + +If CA is present, this certificate will be included in generated CRLs +``` + +### Import files to PKI format + +VyOS provides this utility to import existing certificates/key files directly +into PKI from op-mode. Previous to VyOS 1.4, certificates were stored under the +/config folder permanently and will be retained post upgrade. + +```{opcmd} import pki ca \<name\> file \<Path to CA certificate file\> + +Import the public CA certificate from the defined file to VyOS CLI. +``` + +```{opcmd} import pki ca \<name\> key-file \<Path to private key file\> + +Import the CAs private key portion to the CLI. This should never leave the +system as it is used to decrypt the data. The key is required if you use +VyOS as your certificate generator. +``` + +```{opcmd} import pki certificate \<name\> file \<path to certificate\> + +Import the certificate from the file to VyOS CLI. +``` + +```{opcmd} import pki certificate \<name\> key-file \<path to private key\> + +Import the private key of the certificate to the VyOS CLI. This should never +leave the system as it is used to decrypt the data. +``` + +```{opcmd} import pki openvpn shared-secret \<name\> file \<path to OpenVPN secret key\> + +Import the OpenVPN shared secret stored in file to the VyOS CLI. +``` + +#### ACME + +The VyOS PKI subsystem can also be used to automatically retrieve Certificates +using the {abbr}`ACME (Automatic Certificate Management Environment)` protocol. + +```{cfgcmd} set pki certificate \<name\> acme domain-name \<name\> + +Domain names to apply, multiple domain-names can be specified. + +This is a mandatory option +``` + +```{cfgcmd} set pki certificate \<name\> acme email \<address\> + +Email used for registration and recovery contact. + +This is a mandatory option +``` + +```{cfgcmd} set pki certificate \<name\> acme listen-address \<address\> + +The address the server listens to during http-01 challenge +``` + +```{cfgcmd} set pki certificate \<name\> acme rsa-key-size \<2048 | 3072 | 4096\> + +Size of the RSA key. + +This options defaults to 2048 +``` + +```{cfgcmd} set pki certificate \<name\> acme url \<url\> + +ACME Directory Resource URI. + +This defaults to https://acme-v02.api.letsencrypt.org/directory + +:::{note} +During initial deployment we recommend using the staging API +of LetsEncrypt to prevent and blacklisting of your system. The API +endpoint is https://acme-staging-v02.api.letsencrypt.org/directory +::: +``` + +## Operation + +VyOS operational mode commands are not only available for generating keys but +also to display them. + +```{opcmd} show pki ca + +Show a list of installed {abbr}`CA (Certificate Authority)` certificates. + +:::{code-block} none +vyos@vyos:~$ show pki ca +Certificate Authorities: +Name Subject Issuer CN Issued Expiry Private Key Parent +-------------- ------------------------------------------------------- ----------------- ------------------- ------------------- ------------- -------------- +DST_Root_CA_X3 CN=ISRG Root X1,O=Internet Security Research Group,C=US CN=DST Root CA X3 2021-01-20 19:14:03 2024-09-30 18:14:03 No N/A +R3 CN=R3,O=Let's Encrypt,C=US CN=ISRG Root X1 2020-09-04 00:00:00 2025-09-15 16:00:00 No DST_Root_CA_X3 +vyos_rw CN=VyOS RW CA,O=VyOS,L=Some-City,ST=Some-State,C=GB CN=VyOS RW CA 2021-07-05 13:46:03 2026-07-04 13:46:03 Yes N/A +::: +``` + +```{opcmd} show pki ca \<name\> + +Show only information for specified Certificate Authority. +``` + +```{opcmd} show pki certificate + +Show a list of installed certificates + +:::{code-block} none +vyos@vyos:~$ show pki certificate +Certificates: +Name Type Subject CN Issuer CN Issued Expiry Revoked Private Key CA Present +--------- ------ --------------------- ------------- ------------------- ------------------- --------- ------------- ------------- +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 certificate \<name\> + +Show only information for specified certificate. +``` + +```{opcmd} show pki crl + +Show a list of installed {abbr}`CRLs (Certificate Revocation List)`. +``` + +```{opcmd} renew certbot + +Manually trigger certificate renewal. This will be done twice a day. +``` + +## Examples + +### Create a CA chain and leaf certificates + +This configuration generates & installs into the VyOS PKI system a root +certificate authority, alongside two intermediary certificate authorities for +client & server certificates. These CAs are then used to generate a server +certificate for the router, and a client certificate for a user. +- `vyos_root_ca` is the root certificate authority. +- `vyos_client_ca` and `vyos_server_ca` are intermediary certificate authorities, + which are signed by the root CA. +- `vyos_cert` is a leaf server certificate used to identify the VyOS router, + signed by the server intermediary CA. +- `vyos_example_user` is a leaf client certificate used to identify a user, + signed by client intermediary CA. + +First, we create the root certificate authority. + +```none +[edit] +vyos@vyos# run generate pki ca install vyos_root_ca +Enter private key type: [rsa, dsa, ec] (Default: rsa) rsa +Enter private key bits: (Default: 2048) 2048 +Enter country code: (Default: GB) GB +Enter state: (Default: Some-State) Some-State +Enter locality: (Default: Some-City) Some-City +Enter organization name: (Default: VyOS) VyOS +Enter common name: (Default: vyos.io) VyOS Root CA +Enter how many days certificate will be valid: (Default: 1825) 1825 +Note: If you plan to use the generated key on this router, do not encrypt the private key. +Do you want to encrypt the private key with a passphrase? [y/N] n +2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. +``` + +Secondly, we create the intermediary certificate authorities, which are used to +sign the leaf certificates. + +```none +[edit] +vyos@vyos# run generate pki ca sign vyos_root_ca install vyos_server_ca +Do you already have a certificate request? [y/N] n +Enter private key type: [rsa, dsa, ec] (Default: rsa) rsa +Enter private key bits: (Default: 2048) 2048 +Enter country code: (Default: GB) GB +Enter state: (Default: Some-State) Some-State +Enter locality: (Default: Some-City) Some-City +Enter organization name: (Default: VyOS) VyOS +Enter common name: (Default: vyos.io) VyOS Intermediary Server CA +Enter how many days certificate will be valid: (Default: 1825) 1095 +Note: If you plan to use the generated key on this router, do not encrypt the private key. +Do you want to encrypt the private key with a passphrase? [y/N] n +2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. + + +[edit] +vyos@vyos# run generate pki ca sign vyos_root_ca install vyos_client_ca +Do you already have a certificate request? [y/N] n +Enter private key type: [rsa, dsa, ec] (Default: rsa) rsa +Enter private key bits: (Default: 2048) 2048 +Enter country code: (Default: GB) GB +Enter state: (Default: Some-State) Some-State +Enter locality: (Default: Some-City) Some-City +Enter organization name: (Default: VyOS) VyOS +Enter common name: (Default: vyos.io) VyOS Intermediary Client CA +Enter how many days certificate will be valid: (Default: 1825) 1095 +Note: If you plan to use the generated key on this router, do not encrypt the private key. +Do you want to encrypt the private key with a passphrase? [y/N] n +2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. +``` + +Lastly, we can create the leaf certificates that devices and users will utilise. + +```none +[edit] +vyos@vyos# run generate pki certificate sign vyos_server_ca install vyos_cert +Do you already have a certificate request? [y/N] n +Enter private key type: [rsa, dsa, ec] (Default: rsa) rsa +Enter private key bits: (Default: 2048) 2048 +Enter country code: (Default: GB) GB +Enter state: (Default: Some-State) Some-State +Enter locality: (Default: Some-City) Some-City +Enter organization name: (Default: VyOS) VyOS +Enter common name: (Default: vyos.io) vyos.net +Do you want to configure Subject Alternative Names? [y/N] y +Enter alternative names in a comma separate list, example: ipv4:1.1.1.1,ipv6:fe80::1,dns:vyos.net +Enter Subject Alternative Names: dns:vyos.net,dns:www.vyos.net +Enter how many days certificate will be valid: (Default: 365) 365 +Enter certificate type: (client, server) (Default: server) server +Note: If you plan to use the generated key on this router, do not encrypt the private key. +Do you want to encrypt the private key with a passphrase? [y/N] n +2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. + + +[edit] +vyos@vyos# run generate pki certificate sign vyos_client_ca install vyos_example_user +Do you already have a certificate request? [y/N] n +Enter private key type: [rsa, dsa, ec] (Default: rsa) rsa +Enter private key bits: (Default: 2048) 2048 +Enter country code: (Default: GB) GB +Enter state: (Default: Some-State) Some-State +Enter locality: (Default: Some-City) Some-City +Enter organization name: (Default: VyOS) VyOS +Enter common name: (Default: vyos.io) Example User +Do you want to configure Subject Alternative Names? [y/N] y +Enter alternative names in a comma separate list, example: ipv4:1.1.1.1,ipv6:fe80::1,dns:vyos.net,rfc822:user@vyos.net +Enter Subject Alternative Names: rfc822:example.user@vyos.net +Enter how many days certificate will be valid: (Default: 365) 365 +Enter certificate type: (client, server) (Default: server) client +Note: If you plan to use the generated key on this router, do not encrypt the private key. +Do you want to encrypt the private key with a passphrase? [y/N] n +2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. +``` diff --git a/docs/configuration/pki/index.rst b/docs/configuration/pki/rst-index.rst index cad80f25..cad80f25 100644 --- a/docs/configuration/pki/index.rst +++ b/docs/configuration/pki/rst-index.rst diff --git a/docs/configuration/policy/access-list.md b/docs/configuration/policy/access-list.md new file mode 100644 index 00000000..c3a92e56 --- /dev/null +++ b/docs/configuration/policy/access-list.md @@ -0,0 +1,70 @@ +# Access List Policy + +Filtering is used for both input and output of the routing information. Once +filtering is defined, it can be applied in any direction. VyOS makes filtering +possible using acls and prefix lists. + +Basic filtering can be done using access-list and access-list6. + +## Configuration + +### Access Lists + +```{cfgcmd} set policy access-list \<acl_number\> + +This command creates the new access list policy, where `<acl_number>` must be +a number from 1 to 2699. +``` + +```{cfgcmd} set policy access-list \<acl_number\> description \<text\> + +Set description for the access list. +``` + +```{cfgcmd} set policy access-list \<acl_number\> rule \<1-65535\> action \<permit|deny\> + +This command creates a new rule in the access list and defines an action. +``` + +```{cfgcmd} set policy access-list \<acl_number\> rule \<1-65535\> \<destination|source\> \<any|host|inverse-mask|network\> + +This command defines matching parameters for access list rule. Matching +criteria could be applied to destination or source parameters: + +* any: any IP address to match. +* host: single host IP address to match. +* inverse-match: network/netmask to match (requires network be defined). +* network: network/netmask to match (requires inverse-match be defined). +``` + + +### IPv6 Access List + +Basic filtering could also be applied to IPv6 traffic. + +```{cfgcmd} set policy access-list6 \<text\> + +This command creates the new IPv6 access list, identified by `<text>` +``` + +```{cfgcmd} set policy access-list6 \<text\> description \<text\> + +Set description for the IPv6 access list. +``` + +```{cfgcmd} set policy access-list6 \<text\> rule \<1-65535\> action \<permit|deny\> + +This command creates a new rule in the IPv6 access list and defines an +action. +``` + +```{cfgcmd} set policy access-list6 \<text\> rule \<1-65535\> source \<any|exact-match|network\> + +This command defines matching parameters for IPv6 access list rule. Matching +criteria could be applied to source parameters: + +* any: any IPv6 address to match. +* exact-match: exact match of the network prefixes. +* network: network/netmask to match (requires inverse-match be defined) BUG, +NO invert-match option in access-list6 +```
\ No newline at end of file diff --git a/docs/configuration/policy/as-path-list.md b/docs/configuration/policy/as-path-list.md new file mode 100644 index 00000000..1fcece91 --- /dev/null +++ b/docs/configuration/policy/as-path-list.md @@ -0,0 +1,29 @@ +# BGP - AS Path Policy + +VyOS provides policies commands exclusively for BGP traffic filtering and +manipulation: **as-path-list** is one of them. + +## Configuration + +### policy as-path-list + +```{cfgcmd} set policy as-path-list \<text\> + +Create as-path-policy identified by name `<text>`. +``` +```{cfgcmd} set policy as-path-list \<text\> description \<text\> + +Set description for as-path-list policy. +``` +```{cfgcmd} set policy as-path-list \<text\> rule \<1-65535\> action \<permit|deny\> + +Set action to take on entries matching this rule. +``` +```{cfgcmd} set policy as-path-list \<text\> rule \<1-65535\> description \<text\> + +Set description for rule. +``` +```{cfgcmd} set policy as-path-list \<text\> rule \<1-65535\> regex \<text\> + +Regular expression to match against an AS path. For example "64501 64502". +```
\ No newline at end of file diff --git a/docs/configuration/policy/community-list.md b/docs/configuration/policy/community-list.md new file mode 100644 index 00000000..bdcf4140 --- /dev/null +++ b/docs/configuration/policy/community-list.md @@ -0,0 +1,29 @@ +# BGP - Community List + +VyOS provides policies commands exclusively for BGP traffic filtering and +manipulation: **community-list** is one of them. + +## Configuration + +### policy community-list + +```{cfgcmd} set policy community-list \<text\> + +Creat community-list policy identified by name `<text>`. +``` +```{cfgcmd} set policy community-list \<text\> description \<text\> + +Set description for community-list policy. +``` +```{cfgcmd} set policy community-list \<text\> rule \<1-65535\> action \<permit|deny\> + +Set action to take on entries matching this rule. +``` +```{cfgcmd} set policy community-list \<text\> rule \<1-65535\> description \<text\> + +Set description for rule. +``` +```{cfgcmd} set policy community-list \<text\> rule \<1-65535\> regex \<aa:nn|local-AS|no-advertise|no-export|additive\> + +Regular expression to match against a community-list. +```
\ No newline at end of file diff --git a/docs/configuration/policy/examples.md b/docs/configuration/policy/examples.md new file mode 100644 index 00000000..4dc3f3b0 --- /dev/null +++ b/docs/configuration/policy/examples.md @@ -0,0 +1,205 @@ +# BGP Example + +**Policy definition:** + +```none +# 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' + +# Apply policy to BGP +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' +``` + +Using 'soft-reconfiguration' we get the policy update without bouncing the +neighbor. + +**Routes learned before routing policy applied:** + +```none +vyos@vos1:~$ show ip bgp +BGP table version is 0, local router ID is 192.168.56.101 +Status codes: s suppressed, d damped, h history, * valid, > best, i - internal, + r RIB-failure, S Stale, R Removed +Origin codes: i - IGP, e - EGP, ? - incomplete + + Network Next Hop Metric LocPrf Weight Path +*> 198.51.100.3/32 203.0.113.2 1 0 2 i < Path + +Total number of prefixes 1 +``` + +**Routes learned after routing policy applied:** + +```none +vyos@vos1:~$ show ip bgp +BGP table version is 0, local router ID is 192.168.56.101 +Status codes: s suppressed, d damped, h history, * valid, > best, i - internal, + r RIB-failure, S Stale, R Removed +Origin codes: i - IGP, e - EGP, ? - incomplete + + Network Next Hop Metric LocPrf Weight Path +*> 198.51.100.3/32 203.0.113.2 1 0 2 2 2 2 i + +Total number of prefixes 1 +vyos@vos1:~$ +``` + +You now see the longer AS path. + +# Transparent Proxy + +The following example will show how VyOS can be used to redirect web +traffic to an external transparent proxy: + +```none +set policy route FILTER-WEB rule 1000 destination port 80 +set policy route FILTER-WEB rule 1000 protocol tcp +set policy route FILTER-WEB rule 1000 set table 100 +``` + +This creates a route policy called FILTER-WEB with one rule to set the +routing table for matching traffic (TCP port 80) to table ID 100 +instead of the default routing table. + +To create routing table 100 and add a new default gateway to be used by +traffic matching our route policy: + +```none +set protocols static table 100 route 0.0.0.0/0 next-hop 10.255.0.2 +``` + +This can be confirmed using the `show ip route table 100` operational +command. + +Finally, to apply the policy route to ingress traffic on our LAN +interface, we use: + +```none +set policy route FILTER-WEB interface eth1 +``` + + +# Multiple Uplinks + +VyOS Policy-Based Routing (PBR) works by matching source IP address +ranges and forwarding the traffic using different routing tables. + +Routing tables that will be used in this example are: + +- `table 10` Routing table used for VLAN 10 (192.168.188.0/24) +- `table 11` Routing table used for VLAN 11 (192.168.189.0/24) +- `main` Routing table used by VyOS and other interfaces not + participating in PBR + +:::{figure} /_static/images/pbr_example_1.webp +:alt: PBR multiple uplinks +:scale: 80 % + +Policy-Based Routing with multiple ISP uplinks +(source ./draw.io/pbr_example_1.drawio) +::: + +Add default routes for routing `table 10` and `table 11` + +```none +set protocols static table 10 route 0.0.0.0/0 next-hop 192.0.2.1 +set protocols static table 11 route 0.0.0.0/0 next-hop 192.0.2.2 +``` + +Add policy route matching VLAN source addresses + +```none +set policy route PBR rule 20 set table '10' +set policy route PBR rule 20 description 'Route VLAN10 traffic to table 10' +set policy route PBR rule 20 source address '192.168.188.0/24' + +set policy route PBR rule 30 set table '11' +set policy route PBR rule 30 description 'Route VLAN11 traffic to table 11' +set policy route PBR rule 30 source address '192.168.189.0/24' +``` + +Apply routing policy to **inbound** direction of out VLAN interfaces + +```none +set policy route 'PBR' interface eth0.10 +set policy route 'PBR' interface eth0.11 +``` + +**OPTIONAL:** Exclude Inter-VLAN traffic (between VLAN10 and VLAN11) +from PBR + +```none +set firewall group network-group VLANS-GR description 'VLANs networks' +set firewall group network-group VLANS-GR network '192.168.188.0/24' +set firewall group network-group VLANS-GR network '192.168.189.0/24' + +set policy route PBR rule 10 description 'VLAN10 <-> VLAN11 shortcut' +set policy route PBR rule 10 destination group network-group 'VLANS-GR' +set policy route PBR rule 10 set table 'main' +``` + +These commands allow the VLAN10 and VLAN11 hosts to communicate with +each other using the main routing table. + +## Local route + +The following example allows VyOS to use {abbr}`PBR (Policy-Based Routing)` +for traffic, which originated from the router itself. That solution for multiple +ISP's and VyOS router will respond from the same interface that the packet was +received. Also, it used, if we want that one VPN tunnel to be through one +provider, and the second through another. + +- `203.0.113.254` IP address on VyOS eth1 from ISP1 +- `192.168.2.254` IP address on VyOS eth2 from ISP2 +- `table 10` Routing table used for ISP1 +- `table 11` Routing table used for ISP2 + +```none +set policy local-route rule 101 set table '10' +set policy local-route rule 101 source address '203.0.113.254' +set policy local-route rule 102 set table '11' +set policy local-route rule 102 source address '192.0.2.254' +set protocols static table 10 route 0.0.0.0/0 next-hop '203.0.113.1' +set protocols static table 11 route 0.0.0.0/0 next-hop '192.0.2.2' +``` + +Add multiple source IP in one rule with same priority + +```none +set policy local-route rule 101 set table '10' +set policy local-route rule 101 source address '203.0.113.254' +set policy local-route rule 101 source address '203.0.113.253' +set policy local-route rule 101 source address '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. + +```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). + +```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: + +```none +show policy route statistics +``` diff --git a/docs/configuration/policy/extcommunity-list.md b/docs/configuration/policy/extcommunity-list.md new file mode 100644 index 00000000..5247c13c --- /dev/null +++ b/docs/configuration/policy/extcommunity-list.md @@ -0,0 +1,33 @@ +# BGP - Extended Community List + +VyOS provides policies commands exclusively for BGP traffic filtering and +manipulation: **extcommunity-list** is one of them. + +## Configuration + +### policy extcommunity-list + +```{cfgcmd} set policy extcommunity-list \<text\> + +Creat extcommunity-list policy identified by name \<text\>. +``` +```{cfgcmd} set policy extcommunity-list \<text\> description \<text\> + +Set description for extcommunity-list policy. +``` +```{cfgcmd} set policy extcommunity-list \<text\> rule \<1-65535\> action \<permit|deny\> + +Set action to take on entries matching this rule. +``` +```{cfgcmd} set policy extcommunity-list \<text\> rule \<1-65535\> description \<text\> + +Set description for rule. +``` +```{cfgcmd} set policy extcommunity-list \<text\> rule \<1-65535\> regex \<text\> + +Regular expression to match against an extended community list, where text +could be: +* \<aa:nn:nn\>: Extended community list regular expression. +* \<rt aa:nn:nn\>: Route Target regular expression. +* \<soo aa:nn:nn\>: Site of Origin regular expression. +```
\ No newline at end of file diff --git a/docs/configuration/policy/index.md b/docs/configuration/policy/index.md new file mode 100644 index 00000000..f919e70a --- /dev/null +++ b/docs/configuration/policy/index.md @@ -0,0 +1,53 @@ +--- +lastproofread: '2021-07-12' +--- + +```{include} /_include/need_improvement.txt +``` + + +# Policy + +Policies are used for filtering and traffic management. With policies, network +administrators could filter and treat traffic +according to their needs. + +There could be a wide range of routing policies. Some examples are listed +below: +- Filter traffic based on source/destination address. +- Set some metric to routes learned from a particular neighbor. +- Set some attributes (like AS PATH or Community value) to advertised routes + to neighbors. +- Prefer a specific routing protocol routes over another routing protocol + running on the same router. + +Policies, in VyOS, are implemented using FRR filtering and route maps. Detailed +information of FRR could be found in <http://docs.frrouting.org/> + +## Policy Sections + +```{toctree} +:includehidden: true +:maxdepth: 1 + +access-list +prefix-list +route +route-map +local-route +as-path-list +community-list +extcommunity-list +large-community-list +``` + +## Examples + +Examples of policies usage: + +```{toctree} +:includehidden: true +:maxdepth: 1 + +examples +``` diff --git a/docs/configuration/policy/large-community-list.md b/docs/configuration/policy/large-community-list.md new file mode 100644 index 00000000..23b9a85a --- /dev/null +++ b/docs/configuration/policy/large-community-list.md @@ -0,0 +1,29 @@ +# BGP - Large Community List + +VyOS provides policies commands exclusively for BGP traffic filtering and +manipulation: **large-community-list** is one of them. + +## Configuration + +### policy large-community-list + +```{cfgcmd} set policy large-community-list \<text\> + +Create large-community-list policy identified by name `<text>`. +``` +```{cfgcmd} set policy large-community-list \<text\> description \<text\> + +Set description for large-community-list policy. +``` +```{cfgcmd} set policy large-community-list \<text\> rule \<1-65535\> action \<permit|deny\> + +Set action to take on entries matching this rule. +``` +```{cfgcmd} set policy large-community-list \<text\> rule \<1-65535\> description \<text\> + +Set description for rule. +``` +```{cfgcmd} set policy large-community-list \<text\> rule \<1-65535\> regex \<aa:nn:nn\> + +Regular expression to match against a large community list. +```
\ No newline at end of file diff --git a/docs/configuration/policy/local-route.md b/docs/configuration/policy/local-route.md new file mode 100644 index 00000000..527a2380 --- /dev/null +++ b/docs/configuration/policy/local-route.md @@ -0,0 +1,100 @@ +# Local Route Policy + +Policies for local traffic are defined in this section. + +## Configuration + +### Local Route IPv4 + +```{cfgcmd} set policy local-route rule \<1-32765\> set table \<1-200|main\> + +Set the routing table to use for forwarding matching packets. +``` + +```{cfgcmd} set policy local-route rule \<1-32765\> set vrf \<vrf|default\> + +Set the VRF to use for forwarding matching packets. +``` + +```{cfgcmd} set policy local-route rule \<1-32765\> protocol \<protocol\> + +Match specified protocol (name or number). +``` + +```{cfgcmd} set policy local-route rule \<1-32765\> fwmark \<1-2147483647\> + +Match specified firewall mark (fwmark). +``` + +```{cfgcmd} set policy local-route rule \<1-32765\> source address \<x.x.x.x|x.x.x.x/x\> + +Match specified source address or prefix. +``` + +```{cfgcmd} set policy local-route rule \<1-32765\> source port \<1-65535\> + +Match specified source port. +``` + +```{cfgcmd} set policy local-route rule \<1-32765\> destination address \<x.x.x.x|x.x.x.x/x\> + +Match specified destination address or prefix. +``` + +```{cfgcmd} set policy local-route rule \<1-32765\> destination port \<1-65535\> + +Match specified destination port. +``` + +```{cfgcmd} set policy local-route rule \<1-32765\> inbound-interface \<interface\> + +Match specified inbound interface. +``` + + +### Local Route IPv6 + +```{cfgcmd} set policy local-route6 rule \<1-32765\> set table \<1-200|main\> + +Set the routing table to use for forwarding matching packets. +``` + +```{cfgcmd} set policy local-route6 rule \<1-32765\> set vrf \<vrf|default\> + +Set the VRF to use for forwarding matching packets. +``` + +```{cfgcmd} set policy local-route6 rule \<1-32765\> protocol \<protocol\> + +Match specified protocol (name or number). +``` + +```{cfgcmd} set policy local-route6 rule \<1-32765\> fwmark \<1-2147483647\> + +Match specified firewall mark (fwmark). +``` + +```{cfgcmd} set policy local-route6 rule \<1-32765\> source address \<h:h:h:h:h:h:h:h|h:h:h:h:h:h:h:h/x\> + +Match specified source address or prefix. +``` + +```{cfgcmd} set policy local-route6 rule \<1-32765\> source port \<1-65535\> + +Match specified source port. +``` + +```{cfgcmd} set policy local-route6 rule \<1-32765\> destination address \<h:h:h:h:h:h:h:h|h:h:h:h:h:h:h:h/x\> + +Match specified destination address or prefix. +``` + +```{cfgcmd} set policy local-route6 rule \<1-32765\> destination port \<1-65535\> + +Match specified destination port. +``` + +```{cfgcmd} set policy local-route6 rule \<1-32765\> inbound-interface \<interface\> + +Match specified inbound interface. +```
\ No newline at end of file diff --git a/docs/configuration/policy/prefix-list.md b/docs/configuration/policy/prefix-list.md new file mode 100644 index 00000000..eb827c77 --- /dev/null +++ b/docs/configuration/policy/prefix-list.md @@ -0,0 +1,152 @@ +# Prefix List Policy + +Prefix lists provides the most powerful prefix based filtering mechanism. In +addition to access-list functionality, ip prefix-list has prefix length range +specification. + +If no ip prefix list is specified, it acts as permit. If ip prefix list is +defined, and no match is found, default deny is applied. + +Prefix filtering can be done using prefix-list and prefix-list6. + +## Configuration + +### IPv4 Prefix Lists (prefix-list) + +```{cfgcmd} set policy prefix-list \<text\> + +This command creates the new prefix-list policy, identified by `<text>`. +``` + +```{cfgcmd} set policy prefix-list \<text\> description \<text\> + +Set description for the prefix-list policy. +``` + +```{cfgcmd} set policy prefix-list \<text\> rule \<1-65535\> action \<permit|deny\> + +This command creates a new rule in the prefix-list and defines an action. +``` + +```{cfgcmd} set policy prefix-list \<text\> rule \<1-65535\> description \<text\> + +Set description for rule in the prefix-list. +``` + +```{cfgcmd} set policy prefix-list \<text\> rule \<1-65535\> prefix \<x.x.x.x/x\> + +Prefix to match against. +``` + +```{cfgcmd} set policy prefix-list \<text\> rule \<1-65535\> ge \<0-32\> + +Netmask greater than length. +``` + +```{cfgcmd} set policy prefix-list \<text\> rule \<1-65535\> le \<0-32\> + +Netmask less than length +``` + + +### Example: IPv4 Prefix Lists (prefix-list) + +This example creates an IPv4 prefix-list named PL4-EXAMPLE-NAME, defines 3 +rules each with 1 prefix, and matches le (less than/equal to) /32. + +```{cfgcmd} set policy prefix-list PL4-EXAMPLE-NAME rule 10 action 'permit' + +``` +```{cfgcmd} set policy prefix-list PL4-EXAMPLE-NAME rule 10 le '32' +``` + +```{cfgcmd} set policy prefix-list PL4-EXAMPLE-NAME rule 10 prefix '192.0.2.0/24' +``` + +```{cfgcmd} set policy prefix-list PL4-EXAMPLE-NAME rule 20 action 'permit' +``` + +```{cfgcmd} set policy prefix-list PL4-EXAMPLE-NAME rule 20 le '32' +``` + +```{cfgcmd} set policy prefix-list PL4-EXAMPLE-NAME rule 20 prefix '198.51.100.0/24' +``` + +```{cfgcmd} set policy prefix-list PL4-EXAMPLE-NAME rule 30 action 'permit' +``` + +```{cfgcmd} set policy prefix-list PL4-EXAMPLE-NAME rule 30 le '32' +``` + +```{cfgcmd} set policy prefix-list PL4-EXAMPLE-NAME rule 30 prefix '203.0.113.0/24' +``` + +### IPv6 Prefix Lists (prefix-list6) + +```{cfgcmd} set policy prefix-list6 \<text\> + +This command creates the new IPv6 prefix-list policy, identified by `<text>`. +``` + +```{cfgcmd} set policy prefix-list6 \<text\> description \<text\> + +Set description for the IPv6 prefix-list policy. +``` + +```{cfgcmd} set policy prefix-list6 \<text\> rule \<1-65535\> action \<permit|deny\> + +This command creates a new rule in the IPv6 prefix-list and defines an +action. +``` + +```{cfgcmd} set policy prefix-list6 \<text\> rule \<1-65535\> description \<text\> + +Set description for rule in IPv6 prefix-list. +``` + +```{cfgcmd} set policy prefix-list6 \<text\> rule \<1-65535\> prefix \<h:h:h:h:h:h:h:h/x\> + +IPv6 prefix. +``` + +```{cfgcmd} set policy prefix-list6 \<text\> rule \<1-65535\> ge \<0-128\> + +Netmask greater than length. +``` + +```{cfgcmd} set policy prefix-list6 \<text\> rule \<1-65535\> le \<0-128\> + +Netmask less than length +``` + +### Example: IPv6 Prefix Lists (prefix-list6) + +This example creates an IPv6 prefix-list6 named PL6-EXAMPLE-NAME, defines 3 +rules each with 1 prefix, and matches le (less than/equal to) /128. + +```{cfgcmd} set policy prefix-list6 PL6-EXAMPLE-NAME rule 10 action 'permit' +``` + +```{cfgcmd} set policy prefix-list6 PL6-EXAMPLE-NAME rule 10 le '128' +``` + +```{cfgcmd} set policy prefix-list6 PL6-EXAMPLE-NAME rule 10 prefix '2001:db8:0:0::/64' +``` + +```{cfgcmd} set policy prefix-list6 PL6-EXAMPLE-NAME rule 20 action 'permit' +``` + +```{cfgcmd} set policy prefix-list6 PL6-EXAMPLE-NAME rule 20 le '128' +``` + +```{cfgcmd} set policy prefix-list6 PL6-EXAMPLE-NAME rule 20 prefix '2001:db8:0:1::/64' +``` + +```{cfgcmd} set policy prefix-list6 PL6-EXAMPLE-NAME rule 30 action 'permit' +``` + +```{cfgcmd} set policy prefix-list6 PL6-EXAMPLE-NAME rule 30 le '128' +``` + +```{cfgcmd} set policy prefix-list6 PL6-EXAMPLE-NAME rule 30 prefix '2001:db8:0:2::/64' +```
\ No newline at end of file diff --git a/docs/configuration/policy/route-map.md b/docs/configuration/policy/route-map.md new file mode 100644 index 00000000..cf419a48 --- /dev/null +++ b/docs/configuration/policy/route-map.md @@ -0,0 +1,439 @@ +# Route Map Policy + +Route map is a powerful command, that gives network administrators a very +useful and flexible tool for traffic manipulation. + +## Configuration + +### Route Map + +```{cfgcmd} set policy route-map \<text\> + + This command creates a new route-map policy, identified by \<text\>. +``` + + +```{cfgcmd} set policy route-map \<text\> description \<text\> + +Set description for the route-map policy. +``` + + +```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> action \<permit|deny\> + +Set action for the route-map policy. +``` + + +```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> call \<text\> + +Call another route-map policy on match. +``` + + +```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> continue \<1-65535\> + +Jump to a different rule in this route-map on a match. +``` + + +```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> description \<text\> + +Set description for the rule in the route-map policy. +``` + + +```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> match as-path \<text\> + +BGP as-path list to match. +``` + + +```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> match community community-list \<text\> + +BGP community-list to match. +``` + + +```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> match community exact-match + +Set BGP community-list to exactly match. +``` + + +```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> match extcommunity \<text\> + +BGP extended community to match. +``` + + +```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> match interface \<text\> + +First hop interface of a route to match. +``` + + +```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> match ip address access-list \<1-2699\> + +IP address of route to match, based on access-list. +``` + + +```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> match ip address prefix-list \<text\> + +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\> + +IP route source of route to match, based on access-list. +``` + + +```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> match ip route-source prefix-list \<text\> + +IP route source of route to match, based on prefix-list. +``` + + +```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> match ipv6 address access-list \<text\> + +IPv6 address of route to match, based on IPv6 access-list. +``` + + +```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> match ipv6 address prefix-list \<text\> + +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\> + +Nexthop IPv6 address to match. +``` + + +```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> match large-community large-community-list \<text\> + +Match BGP large communities. +``` + + +```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> match local-preference \<0-4294967295\> + +Match local preference. +``` + + +```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> match metric \<1-65535\> + +Match route metric. +``` + + +```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> match origin \<egp|igp|incomplete\> + +Boarder Gateway Protocol (BGP) origin code to match. +``` + + +```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> match peer \<x.x.x.x\> + +Peer IP address to match. +``` + + +````{cfgcmd} set policy route-map \<text\> rule \<1-65535\> match protocol \<protocol\> + +```{eval-rst} +Source protocol to match. + * ``babel`` - Babel routing protocol (Babel) + * ``bgp`` - Border Gateway Protocol (BGP) + * ``connected`` - Connected routes (directly attached subnet or host) + * ``isis`` - Intermediate System to Intermediate System (IS-IS) + * ``kernel`` - Kernel routes + * ``ospf`` - Open Shortest Path First (OSPFv2) + * ``ospfv3`` - Open Shortest Path First (IPv6) (OSPFv3) + * ``rip`` - Routing Information Protocol (RIP) + * ``ripng`` - Routing Information Protocol next-generation (IPv6) (RIPng) + * ``static`` - Statically configured routes + * ``table`` - Non-main Kernel Routing Table + * ``vnc`` - Virtual Network Control (VNC) +``` +```` + + +```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> match rpki \<invalid|notfound|valid\> + +Match RPKI validation result. +``` + + +```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> match source-vrf \<text\> + +Source VRF to match. +``` + + +```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> match tag \<1-65535\> + +Route tag to match. +``` + + +```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> on-match goto \<1-65535\> + +Exit policy on match: go to rule <1-65535> +``` + + +```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> on-match next + +Exit policy on match: go to next sequence number. +``` + + +```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> set aggregator \<as|ip\> \<1-4294967295|x.x.x.x\> + +BGP aggregator attribute: AS number or IP address of an aggregation. +``` + + +```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> set as-path exclude \<1-4294967295 | all\> + +Drop AS-NUMBER from the BGP AS path. + +If ``all`` is specified, remove all AS numbers from the AS_PATH of the BGP +path's NLRI. +``` + + +```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> set as-path prepend \<1-4294967295\> + +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 community \<add|replace\> \<community\> + +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 community none + +Delete all BGP communities +``` + + +```{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 large-community \<add|replace\> \<GA:LDP1:LDP2\> + +Add or replace BGP large-community attribute in format +``<0-4294967295:0-4294967295:0-4294967295>`` +``` + + +```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> set large-community none + +Delete all BGP large-communities +``` + + +```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> set large-community delete \<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\> + +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 in format ``<0-65535:0-4294967295>`` or ``<IP:0-65535>``. +``` + + +```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> set extcommunity soo \<text\> + +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\> + +Nexthop IP address. +``` +```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> set ip-next-hop unchanged + +Set the next-hop as unchanged. Pass through the route-map without +changing its value +``` +```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> set ip-next-hop 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 +establish the peering with our neighbor. +``` +```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> set ipv6-next-hop \<global|local\> \<h:h:h:h:h:h:h:h\> + +Nexthop IPv6 address. +``` +```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> set ipv6-next-hop 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 +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 local-preference \<0-4294967295\> + +Set BGP local preference attribute. +``` +```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> set metric \<+/-metric|0-4294967295|rtt|+rtt|-rtt\> + +Set the route metric. When used with BGP, set the BGP attribute MED +to a specific value. Use ``+/-`` to add or subtract the specified value +to/from the existing/MED. Use ``rtt`` to set the MED to the round trip +time or ``+rtt/-rtt`` to add/subtract the round trip time to/from the MED. +``` +```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> set metric-type \<type-1|type-2\> + +Set OSPF external metric-type. +``` +```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> set origin \<igp|egp|incomplete\> + +Set BGP origin code. +``` +```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> set originator-id \<x.x.x.x\> + +Set BGP originator ID attribute. +``` +```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> set src \<x.x.x.x|h:h:h:h:h:h:h:h\> + +Set source IP/IPv6 address for route. +``` +```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> set table \<1-200\> + +Set prefixes to table. +``` +```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> set tag \<1-65535\> + +Set tag value for routing protocol. +``` +```{cfgcmd} set policy route-map \<text\> rule \<1-65535\> set weight \<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 +> - `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.md b/docs/configuration/policy/route.md new file mode 100644 index 00000000..b3ef6540 --- /dev/null +++ b/docs/configuration/policy/route.md @@ -0,0 +1,424 @@ +# Route and Route6 Policy + +IPv4 route and IPv6 route policies are defined in this section. These route +policies can then be associated to interfaces. + +## Rule-Sets + +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\> + +Provide a rule-set description. +``` + +```{cfgcmd} set policy route \<name\> default-log +``` + +```{cfgcmd} set policy route6 \<name\> default-log + +Option to log packets hitting default-action. +``` + +```{cfgcmd} set policy route \<name\> interface \<interface\> +``` + +```{cfgcmd} set policy route6 \<name\> interface \<interface\> + +Apply routing policy to interface +``` + +```{cfgcmd} set policy route \<name\> rule \<n\> description \<text\> +``` + +```{cfgcmd} set policy route6 \<name\> rule \<n\> description \<text\> + +Provide a description for each rule. +``` + +```{cfgcmd} set policy route \<name\> rule \<n\> log \<enable|disable\> +``` + +```{cfgcmd} set policy route6 \<name\> rule \<n\> log \<enable|disable\> + +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\> mark \<match_criteria\> +``` + +```{cfgcmd} set policy route6 \<name\> rule \<n\> mark \<match_criteria\> + +Match based on the firewall mark (fwmark), where \<match_criteria\> can be: + * \<0-2147483647\> a single fwmark + * !\<0-2147483647\> everything except a single fwmark + * <start-end> a range of marks + * !<start-end> everything except the range of marks + +:::{note} +When using the ``set table`` or ``set vrf`` commands the mark +settings are ignored and overwritten with a table-specific mark that +is set to 0x7FFFFFFF - the id of the table/VRF. +::: +``` + +```{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 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. + - !\<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. + +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|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 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 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 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\> +``` + +```{cfgcmd} set policy route6 \<name\> rule \<n\> icmpv6 \<code | type\> + +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: +* match-ipsec: match inbound IPsec packets. +* 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 allow 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\> protocol \<text | 0-255 | tcp_udp | all \> +``` + +```{cfgcmd} set policy route6 \<name\> rule \<n\> protocol \<text | 0-255 | tcp_udp | all \> + +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\> packet-length \<text\> +``` + +```{cfgcmd} set policy route6 \<name\> rule \<n\> packet-length \<text\> +``` + +```{cfgcmd} set policy route \<name\> rule \<n\> packet-length-exclude \<text\> +``` + +```{cfgcmd} set policy route6 \<name\> rule \<n\> packet-length-exclude \<text\> + +Match based on packet length criteria. Multiple values from 1 to 65535 +and ranges are supported. +``` + +```{cfgcmd} set policy route \<name\> rule \<n\> packet-type \[broadcast | host | multicast | other\] +``` + +```{cfgcmd} set policy route6 \<name\> rule \<n\> packet-type \[broadcast | host | multicast | other\] + +Match based on packet type criteria. +``` + +```{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\> state \<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 +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. +``` + +```{cfgcmd} set policy route \<name\> rule \<n\> time monthdays \<text\> +``` + +```{cfgcmd} set policy route6 \<name\> rule \<n\> time monthdays \<text\> +``` + +```{cfgcmd} set policy route \<name\> rule \<n\> time startdate \<text\> +``` + +```{cfgcmd} set policy route6 \<name\> rule \<n\> time startdate \<text\> +``` + +```{cfgcmd} set policy route \<name\> rule \<n\> time starttime \<text\> +``` + +```{cfgcmd} set policy route6 \<name\> rule \<n\> time starttime \<text\> +``` + +```{cfgcmd} set policy route \<name\> rule \<n\> time stopdate \<text\> +``` + +```{cfgcmd} set policy route6 \<name\> rule \<n\> time stopdate \<text\> +``` + +```{cfgcmd} set policy route \<name\> rule \<n\> time stoptime \<text\> +``` + +```{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 + +Time to match the defined rule. +``` + +```{cfgcmd} set policy route rule \<n\> 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 policy route6 rule \<n\> 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'. +``` + +### Actions + +When matching all patterns defined in a rule, then different actions can +be made. This includes dropping 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 route \<name\> rule \<n\> set connection-mark \<1-2147483647\> +``` + +```{cfgcmd} set policy route6 \<name\> rule \<n\> set connection-mark \<1-2147483647\> + +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 a specific packet mark. +``` + +```{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 the routing table to forward packet with. + +:::{note} +When using the ``set table`` or ``set vrf`` commands matching +against the mark is not possible, because it gets overwritten with a +table-specific mark that is 0x7FFFFFFF - the id of the table/VRF. +::: +``` + +```{cfgcmd} set policy route \<name\> rule \<n\> set tcp-mss \<500-1460\> +``` + +```{cfgcmd} set policy route6 \<name\> rule \<n\> set tcp-mss \<500-1460\> + +Set packet modifications: Explicitly set TCP Maximum segment size value. +``` + +```{cfgcmd} set policy route \<name\> rule \<n\> set vrf \<default | text \> +``` + +```{cfgcmd} set policy route6 \<name\> rule \<n\> set vrf \<default | text \> + +Set the VRF to forward packet with. + +:::{note} +When using the ``set table`` or ``set vrf`` commands matching +against the mark is not possible, because it gets overwritten with a +table-specific mark that is 0x7FFFFFFF - the id of the table/VRF. +::: +```
\ No newline at end of file diff --git a/docs/configuration/policy/access-list.rst b/docs/configuration/policy/rst-access-list.rst index 0af9b911..0af9b911 100644 --- a/docs/configuration/policy/access-list.rst +++ b/docs/configuration/policy/rst-access-list.rst diff --git a/docs/configuration/policy/as-path-list.rst b/docs/configuration/policy/rst-as-path-list.rst index ceeb8e01..ceeb8e01 100644 --- a/docs/configuration/policy/as-path-list.rst +++ b/docs/configuration/policy/rst-as-path-list.rst diff --git a/docs/configuration/policy/community-list.rst b/docs/configuration/policy/rst-community-list.rst index ee2da03c..ee2da03c 100644 --- a/docs/configuration/policy/community-list.rst +++ b/docs/configuration/policy/rst-community-list.rst diff --git a/docs/configuration/policy/examples.rst b/docs/configuration/policy/rst-examples.rst index 6c5c592a..6c5c592a 100644 --- a/docs/configuration/policy/examples.rst +++ b/docs/configuration/policy/rst-examples.rst diff --git a/docs/configuration/policy/extcommunity-list.rst b/docs/configuration/policy/rst-extcommunity-list.rst index c413b8b5..c413b8b5 100644 --- a/docs/configuration/policy/extcommunity-list.rst +++ b/docs/configuration/policy/rst-extcommunity-list.rst diff --git a/docs/configuration/policy/index.rst b/docs/configuration/policy/rst-index.rst index 0394eb21..0394eb21 100644 --- a/docs/configuration/policy/index.rst +++ b/docs/configuration/policy/rst-index.rst diff --git a/docs/configuration/policy/large-community-list.rst b/docs/configuration/policy/rst-large-community-list.rst index 0c57fd4a..0c57fd4a 100644 --- a/docs/configuration/policy/large-community-list.rst +++ b/docs/configuration/policy/rst-large-community-list.rst diff --git a/docs/configuration/policy/local-route.rst b/docs/configuration/policy/rst-local-route.rst index a3e42816..a3e42816 100644 --- a/docs/configuration/policy/local-route.rst +++ b/docs/configuration/policy/rst-local-route.rst diff --git a/docs/configuration/policy/prefix-list.rst b/docs/configuration/policy/rst-prefix-list.rst index 98df1b9b..98df1b9b 100644 --- a/docs/configuration/policy/prefix-list.rst +++ b/docs/configuration/policy/rst-prefix-list.rst diff --git a/docs/configuration/policy/route-map.rst b/docs/configuration/policy/rst-route-map.rst index a2313466..a2313466 100644 --- a/docs/configuration/policy/route-map.rst +++ b/docs/configuration/policy/rst-route-map.rst diff --git a/docs/configuration/policy/route.rst b/docs/configuration/policy/rst-route.rst index 1ddd04cf..1ddd04cf 100644 --- a/docs/configuration/policy/route.rst +++ b/docs/configuration/policy/rst-route.rst diff --git a/docs/configuration/protocols/arp.md b/docs/configuration/protocols/arp.md new file mode 100644 index 00000000..7d9bf4f9 --- /dev/null +++ b/docs/configuration/protocols/arp.md @@ -0,0 +1,72 @@ +```{eval-rst} +.. meta:: + :description: The Address Resolution Protocol (ARP) resolves + network-layer addresses to link-layer MAC addresses. + :keywords: arp, network, protocol, mac, address, ipv4, static +``` + +(routing_static_arp)= + +# ARP + +The {abbr}`ARP (Address Resolution Protocol)` resolves IPv4 network layer addresses +to link layer MAC addresses. +addresses. This mapping is essential for communication within the Internet +Protocol suite. ARP was standardized in 1982 by {rfc}`826` (STD 37). + +:::{note} +In Internet Protocol version 6 (IPv6) networks, address resolution is +performed by the Neighbor Discovery Protocol (NDP). +::: + +Use the following commands to configure or view ARP table entries. + +## Configuration + +```{eval-rst} +.. cfgcmd:: set protocols static arp interface <interface> address <host> mac <mac> + + **Configure a static ARP entry on the specified interface.** + + This creates a permanent mapping between an IP address and a MAC address + on the specified interface. + + Example: + + .. code-block:: none + + set protocols static arp interface eth0 address 192.0.2.1 mac 01:23:45:67:89:01 +``` + +## Operation + +```{eval-rst} +.. opcmd:: show protocols static arp + + Show all ARP table entries across all interfaces. + + .. code-block:: none + + vyos@vyos:~$ show protocols static arp + Address HWtype HWaddress Flags Mask Iface + 10.1.1.1 ether 00:53:00:de:23:2e C eth1 + 10.1.1.100 ether 00:53:00:de:23:aa CM eth1 +``` + +```{eval-rst} +.. opcmd:: show protocols static arp interface <interface> + + Show all ARP table entries for the specific interface. + + Example for ``eth1``: + + .. code-block:: none + + vyos@vyos:~$ show protocols static arp interface eth1 + Address HWtype HWaddress Flags Mask Iface + 10.1.1.1 ether 00:53:00:de:23:2e C eth1 + 10.1.1.100 ether 00:53:00:de:23:aa CM eth1 +``` + +[arp]: https://en.wikipedia.org/wiki/Address_Resolution_Protocol + diff --git a/docs/configuration/protocols/babel.md b/docs/configuration/protocols/babel.md new file mode 100644 index 00000000..b03e9fa4 --- /dev/null +++ b/docs/configuration/protocols/babel.md @@ -0,0 +1,296 @@ +```{eval-rst} +.. meta:: + :description: The Babel routing protocol provides robust and efficient + routing for wired and wireless mesh networks. + :keywords: babel, routing, protocol, wireless, mesh, network, metric, + ipv4, ipv6 +``` + +(babel)= + +# Babel + +The Babel protocol provides robust and efficient routing for both wired and +wireless mesh networks. By default, Babel uses hop-count metrics on wired links +and a variant of Expected Transmission Count (ETX) on wireless links. +Administrators can configure Babel to account for radio diversity, +automatically compute link latency, and include that latency in the routing +metric. {rfc}`8966` defines the Babel protocol. + +Babel is a dual-stack protocol. A single Babel instance routes both IPv4 and +IPv6 traffic simultaneously. + +## General configuration + +VyOS does not require a specific command to start the Babel process. The system +automatically starts the routing process when you configure the first +Babel-enabled interface. + +```{cfgcmd} set protocols babel interface \<interface\> + +**Enable Babel routing on the specified interface.** + +The system immediately begins sending and receiving Babel packets on this +interface. +``` + +## Optional configuration + +```{cfgcmd} set protocols babel parameters diversity + +**Enable radio-frequency diversity routing for the Babel process.** + +Enabling this feature is highly recommended for networks with many +wireless nodes. + +:::{note} +When you enable diversity routing, you should also configure the +``diversity-factor`` and ``channel`` parameters. +::: +``` + +```{cfgcmd} set protocols babel parameters diversity-factor \<1-256\> + +**Configure the multiplicative factor for diversity routing, in units of +1/256.** + +Lower multiplicative factors give greater weight to diversity in route +selection. The default value is 256, which disables diversity routing. +On nodes with multiple independent radios, configure a value of 128 or less. +``` + +```{cfgcmd} set protocols babel parameters resend-delay \<20-655340\> + +**Configure the delay in milliseconds before the system resends an +important request or update.** + +The default value is 2000 ms. +``` + +```{cfgcmd} set protocols babel parameters smoothing-half-life \<0-65534\> + +**Configure the time constant, in seconds, for the smoothing algorithm used +to implement hysteresis.** + +Higher values reduce route oscillation but slightly increase convergence +time. A value of 0 disables hysteresis and is suitable for wired networks. +The default is 4 seconds. +``` + +## Interfaces configuration + +```{cfgcmd} set protocols babel interface \<interface\> type \<auto|wired|wireless\> + +**Configure the network type for the Babel-enabled interface.** + +Choose from the following: + +* ``auto``: Babel automatically detects if an interface is wired or + wireless. +* ``wired``: Babel enables optimizations for wired interfaces. +* ``wireless``: Babel disables optimizations suitable only for wired + interfaces. Specifying wireless is always correct, but may cause slower + convergence and increased routing traffic. +``` + +```{cfgcmd} set protocols babel interface \<interface\> split-horizon \<default|disable|enable\> + +**Configure the split-horizon routing behavior for the specified +interface.** + +Use one of the following options: + +* ``default``: Babel automatically enables split-horizon on wired + interfaces and disables it on wireless interfaces. +* ``enable``: Babel enables split-horizon on the interface. This + optimization should be used only on symmetric, transitive (wired) + networks. +* ``disable``: Babel disables split-horizon on the interface. Disabling + split-horizon is always safe and correct. +``` + +```{cfgcmd} set protocols babel interface \<interface\> hello-interval \<20-655340\> + +**Configure the interval, in milliseconds, between scheduled hello messages +on the specified interface.** + +On wired links, Babel detects link failures within two hello intervals. +On wireless links, link quality is reestimated at each interval. The +default is 4000 ms. +``` + +```{cfgcmd} set protocols babel interface \<interface\> update-interval \<20-655340\> + +**Configure the interval, in milliseconds, between scheduled routing +updates on the specified interface.** + +Because Babel uses triggered updates extensively, you can increase this +value on reliable links with minimal packet loss. The default is 20000 ms. +``` + +```{cfgcmd} set protocols babel interface \<interface\> rxcost \<1-65534\> + +**Configure the base receive cost for the specified interface.** + +Babel applies this value based on the configured network type: + +* ``wired``: The value is the routing cost advertised to neighboring + routers. +* ``wireless``: The value is a multiplier used to compute the ETX + (Expected Transmission Count) reception cost. + +The default value is 256. +``` + +```{cfgcmd} set protocols babel interface \<interface\> rtt-decay \<1-256\> + +**Configure the decay factor for the exponential moving average of RTT +samples, in units of 1/256.** + +Higher values discard older samples faster. The default value is 42. +``` + +```{cfgcmd} set protocols babel interface \<interface\> rtt-min \<1-65535\> + +**Configure the minimum RTT, in milliseconds, at which the cost to a +neighbor begins to increase.** + +The additional cost is linear in (rtt - rtt-min). The default value is 10 ms. +``` + +```{cfgcmd} set protocols babel interface \<interface\> rtt-max \<1-65535\> + +**Configure the maximum RTT, in milliseconds, above which the cost to a +neighbor stops increasing.** + +The default value is 120 ms. +``` + +```{cfgcmd} set protocols babel interface \<interface\> max-rtt-penalty \<0-65535\> + +**Configure the maximum cost added to a neighbor when RTT meets or exceeds +rtt-max.** + +Setting this value to 0 disables RTT-based costs. The default value is 150. +``` + +```{cfgcmd} set protocols babel interface \<interface\> enable-timestamps + +**Configure adding timestamps to each Hello and IHU message to calculate +RTT values.** + +Enabling timestamps is recommended for tunnel interfaces. +``` + +```{cfgcmd} set protocols babel interface \<interface\> channel \<1-254|interfering|noninterfering\> + +**Configure the channel identifier that diversity routing uses for the +specified interface.** + +Interfaces interfere with each other based on the assigned channel +identifier: + +* ``1–254``: The interface interferes with interfaces sharing the same + channel number and with interfaces configured as ``interfering``. +* ``interfering``: The interface interferes with all others except those + configured as ``noninterfering``. +* ``noninterfering``: The interface interferes only with itself. +``` + +## Redistribution configuration + +```{cfgcmd} set protocols babel redistribute \<ipv4|ipv6\> \<route source\> + +**Configure the redistribution of routing information from the specified +route source into the Babel process.** + +The following route sources are available: + +* **ipv4:** ``bgp``, ``connected``, ``eigrp``, ``isis``, ``kernel``, + ``nhrp``, ``ospf``, ``rip``, ``static`` +* **ipv6:** ``bgp``, ``connected``, ``eigrp``, ``isis``, ``kernel``, + ``nhrp``, ``ospfv3``, ``ripng``, ``static`` +``` + +```{cfgcmd} set protocols babel distribute-list \<ipv4|ipv6\> access-list \<in|out\> \<number\> + +**Configure global Babel route filtering using an access list.** + +Specify the direction in which the access list is applied: + +* ``in``: Filters incoming routes. +* ``out``: Filters outgoing routes. +``` + +```{cfgcmd} set protocols babel distribute-list \<ipv4|ipv6\> interface \<interface\> access-list \<in|out\> \<number\> + +**Configure Babel route filtering on the specified interface using an +access list.** + +Specify the direction in which the access list is applied: + +* ``in``: Filters incoming routes. +* ``out``: Filters outgoing routes. +``` + +```{cfgcmd} set protocols babel distribute-list \<ipv4|ipv6\> prefix-list \<in|out\> \<name\> + +**Configure global Babel route filtering using a prefix list.** + +Specify the direction in which the prefix list is applied: + +* ``in``: Filters incoming routes. +* ``out``: Filters outgoing routes. +``` + +```{cfgcmd} set protocols babel distribute-list \<ipv4|ipv6\> interface \<interface\> prefix-list \<in|out\> \<name\> + +**Configure Babel route filtering on the specified interface using a +prefix list.** + +Specify the direction in which the prefix list is applied: + +* ``in``: Filters incoming routes. +* ``out``: Filters outgoing routes. +``` + +## Configuration example + +### Basic two-node babel network + +**Goal:** The following example connects two routers (Node 1 and Node 2) via +their eth0 interfaces and uses the Babel routing protocol to advertise +(redistribute) each router's locally configured networks (represented by +loopback addresses) to one another. + +**Node 1:** + +```none +# Configure the loopback (local networks) and physical (eth0) addresses +set interfaces loopback lo address 10.1.1.1/32 +set interfaces loopback lo address fd12:3456:dead:beef::1/128 +set interfaces ethernet eth0 address 192.168.1.1/24 + +# Enable Babel on the physical link +set protocols babel interface eth0 type wired + +# Instruct Babel to advertise (redistribute) the locally configured networks +set protocols babel redistribute ipv4 connected +set protocols babel redistribute ipv6 connected +``` + +**Node 2:** + +```none +# Configure the loopback (local networks) and physical (eth0) addresses +set interfaces loopback lo address 10.2.2.2/32 +set interfaces loopback lo address fd12:3456:beef:dead::2/128 +set interfaces ethernet eth0 address 192.168.1.2/24 + +# Enable Babel on the physical link +set protocols babel interface eth0 type wired + +# Tell Babel to advertise (redistribute) the locally configured networks +set protocols babel redistribute ipv4 connected +set protocols babel redistribute ipv6 connected +``` diff --git a/docs/configuration/protocols/bfd.md b/docs/configuration/protocols/bfd.md new file mode 100644 index 00000000..13623e03 --- /dev/null +++ b/docs/configuration/protocols/bfd.md @@ -0,0 +1,205 @@ +--- +lastproofread: '2023-01-27' +--- + +```{include} /_include/need_improvement.txt +``` + +(routing-bfd)= + +# BFD + +{abbr}`BFD (Bidirectional Forwarding Detection)` is described and extended by +the following RFCs: {rfc}`5880`, {rfc}`5881` and {rfc}`5883`. + +In the age of very fast networks, a second of unreachability may equal millions of lost packets. +The idea behind BFD is to detect very quickly when a peer is down and take action extremely fast. + +BFD sends lots of small UDP packets very quickly to ensures that the peer is still alive. + +This allows avoiding the timers defined in BGP and OSPF protocol to expires. + +## Configure BFD + +```{cfgcmd} set protocols bfd peer \<address\> + +Set BFD peer IPv4 address or IPv6 address +``` + +```{cfgcmd} set protocols bfd peer \<address\> echo-mode + +Enables the echo transmission mode +``` + +```{cfgcmd} set protocols bfd peer \<address\> multihop + +Allow this BFD peer to not be directly connected +``` + +```{cfgcmd} set protocols bfd peer \<address\> source [address \<address\> | interface \<interface\>] + +Bind listener to specific interface/address, mandatory for IPv6 +``` + +```{cfgcmd} set protocols bfd peer \<address\> interval echo-interval \<10-60000\> + +The minimal echo receive transmission interval that this system is +capable of handling +``` + +```{cfgcmd} set protocols bfd peer \<address\> interval multiplier \<2-255\> + +Remote transmission interval will be multiplied by this value +``` + +```{cfgcmd} set protocols bfd peer \<address\> interval [receive | transmit] \<10-60000\> + +Interval in milliseconds +``` + +```{cfgcmd} set protocols bfd peer \<address\> shutdown + +Disable a BFD peer +``` + +```{cfgcmd} set protocols bfd peer \<address\> minimum-ttl \<1-254\> + +For multi hop sessions only. Configure the minimum expected TTL for an +incoming BFD control packet. + +This feature serves the purpose of thightening the packet validation +requirements to avoid receiving BFD control packets from other sessions. +``` + +### Enable BFD in BGP + +```{cfgcmd} set protocols bgp neighbor \<neighbor\> bfd + +Enable BFD on a single BGP neighbor +``` + +```{cfgcmd} set protocols bgp peer-group \<neighbor\> bfd + +Enable BFD on a BGP peer group +``` + +### Enable BFD in OSPF + +```{cfgcmd} set protocols ospf interface \<interface\> bfd + + Enable BFD for OSPF on an interface + +``` + +```{cfgcmd} set protocols ospfv3 interface \<interface\> bfd + +Enable BFD for OSPFv3 on an interface +``` + +### Enable BFD in ISIS + +```{cfgcmd} set protocols isis \<name\> interface \<interface\> bfd + +Enable BFD for ISIS on an interface + +``` + +## Operational Commands + +```{opcmd} show bfd peers + + Show all BFD peers + + :::{code-block} none + BFD Peers: + peer 198.51.100.33 vrf default interface eth4.100 + ID: 4182341893 + Remote ID: 12678929647 + Status: up + Uptime: 1 month(s), 16 hour(s), 29 minute(s), 38 second(s) + Diagnostics: ok + Remote diagnostics: ok + Local timers: + Receive interval: 300ms + Transmission interval: 300ms + Echo transmission interval: 50ms + Remote timers: + Receive interval: 300ms + Transmission interval: 300ms + Echo transmission interval: 0ms + + peer 198.51.100.55 vrf default interface eth4.101 + ID: 4618932327 + Remote ID: 3312345688 + Status: up + Uptime: 20 hour(s), 16 minute(s), 19 second(s) + Diagnostics: ok + Remote diagnostics: ok + Local timers: + Receive interval: 300ms + Transmission interval: 300ms + Echo transmission interval: 50ms + Remote timers: + Receive interval: 300ms + Transmission interval: 300ms + Echo transmission interval: 0ms + ::: +``` + +## BFD Static Route Monitoring + + +A monitored static route conditions the installation to the RIB on the BFD +session running state: when BFD session is up the route is installed to RIB, +but when the BFD session is down it is removed from the RIB. + + +### Configuration + +```{cfgcmd} set protocols static route \<subnet\> next-hop \<address\> bfd profile \<profile\> + +Configure a static route for \<subnet\> using gateway \<address\> +and use the gateway address as BFD peer destination address. +``` + +```{cfgcmd} set protocols static route \<subnet\> next-hop \<address\> bfd multi-hop source \<address\> profile \<profile\> + +Configure a static route for \<subnet\> using gateway \<address\>, +use source address to identify the peer when is multi-hop session +and the gateway address as BFD peer destination address. +``` + +```{cfgcmd} set protocols static route6 \<subnet\> next-hop \<address\> bfd profile \<profile\> + +Configure a static route for \<subnet\> using gateway \<address\> +and use the gateway address as BFD peer destination address. +``` + +```{cfgcmd} set protocols static route6 \<subnet\> next-hop \<address\> bfd multi-hop source \<address\> profile \<profile\> + +Configure a static route for \<subnet\> using gateway \<address\>, +use source address to identify the peer when is multi-hop session +and the gateway address as BFD peer destination address. +``` + +(bfd-operational-commands)= + +## Operational Commands + +```{opcmd} show bfd static routes + +Showing BFD monitored static routes + +:::{code-block} none +Showing BFD monitored static routes: + + Next hops: + VRF default IPv4 Unicast: + 10.10.13.3/32 peer 192.168.2.3 (status: installed) + 172.16.10.3/32 peer 192.168.10.1 (status: uninstalled) + + VRF default IPv4 Multicast: + + VRF default IPv6 Unicast: +::: +```
\ No newline at end of file diff --git a/docs/configuration/protocols/bgp.md b/docs/configuration/protocols/bgp.md new file mode 100644 index 00000000..702a2b1f --- /dev/null +++ b/docs/configuration/protocols/bgp.md @@ -0,0 +1,1414 @@ +(routing-bgp)= + +# BGP + +{abbr}`BGP (Border Gateway Protocol)` is one of the Exterior Gateway Protocols +and the de facto standard interdomain routing protocol. The latest BGP version +is 4. BGP-4 is described in {rfc}`1771` and updated by {rfc}`4271`. {rfc}`2858` +adds multiprotocol support to BGP. + +VyOS makes use of {abbr}`FRR (Free Range Routing)` and we would like to thank +them for their effort! + +## Basic Concepts + +(bgp-autonomous-systems)= + +### Autonomous Systems + +From {rfc}`1930`: + +> An AS is a connected group of one or more IP prefixes run by one or more +> network operators which has a SINGLE and CLEARLY DEFINED routing policy. + +Each {abbr}`AS (Autonomous System)` has an identifying number associated with it +called an {abbr}`ASN (Autonomous System Number)`. This is a two octet value +ranging in value from 1 to 65535. The AS numbers 64512 through 65535 are defined +as private AS numbers. Private AS numbers must not be advertised on the global +Internet. The 2-byte AS number range has been exhausted. 4-byte AS numbers are +specified in {rfc}`6793`, and provide a pool of 4294967296 AS numbers. + +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 system-as \<asn\> + +Set local {abbr}`ASN (Autonomous System Number)` that this router represents. +This is a a mandatory option! +``` + +(bgp-address-families)= + + +### Address Families + + +Multiprotocol extensions enable BGP to carry routing information for multiple +network layer protocols. BGP supports an Address Family Identifier (AFI) for +IPv4 and IPv6. + + +(bgp-route-selection)= + + +### Route Selection + + +The route selection process used by FRR's BGP implementation uses the following +decision criterion, starting at the top of the list and going towards the +bottom until one of the factors can be used. + + +01. **Weight check** + + + Prefer higher local weight routes to lower routes. + + +02. **Local preference check** + + + Prefer higher local preference routes to lower. + + +03. **Local route check** + + + Prefer local routes (statics, aggregates, redistributed) to received routes. + + +04. **AS path length check** + + + Prefer shortest hop-count AS_PATHs. + + +05. **Origin check** + + + Prefer the lowest origin type route. That is, prefer IGP origin routes to + EGP, to Incomplete routes. + + +06. **MED check** + + + Where routes with a MED were received from the same AS, prefer the route + with the lowest MED. + + +07. **External check** + + + Prefer the route received from an external, eBGP peer over routes received + from other types of peers. + + +08. **IGP cost check** + + + Prefer the route with the lower IGP cost. + + +09. **Multi-path check** + + + If multi-pathing is enabled, then check whether the routes not yet + distinguished in preference may be considered equal. If + {cfgcmd}`bgp bestpath as-path multipath-relax` is set, all such routes are + considered equal, otherwise routes received via iBGP with identical AS_PATHs + or routes received from eBGP neighbours in the same AS are considered equal. + + +10. **Already-selected external check** + + + Where both routes were received from eBGP peers, then prefer the route + which is already selected. Note that this check is not applied if + {cfgcmd}`bgp bestpath compare-routerid` is configured. This check can + prevent some cases of oscillation. + + +11. **Router-ID check** + + + Prefer the route with the lowest router-ID. If the route has an + ORIGINATOR_ID attribute, through iBGP reflection, then that router ID is + used, otherwise the router-ID of the peer the route was received from is + used. + + +12. **Cluster-List length check** + + + The route with the shortest cluster-list length is used. The cluster-list + reflects the iBGP reflection path the route has taken. + + +13. **Peer address** + + + Prefer the route received from the peer with the higher transport layer + address, as a last-resort tie-breaker. + + +(bgp-capability-negotiation)= + + +### Capability Negotiation + + +When adding IPv6 routing information exchange feature to BGP. There were some +proposals. {abbr}`IETF (Internet Engineering Task Force)` +{abbr}`IDR (Inter Domain Routing)` adopted a proposal called Multiprotocol +Extension for BGP. The specification is described in {rfc}`2283`. The protocol +does not define new protocols. It defines new attributes to existing BGP. When +it is used exchanging IPv6 routing information it is called BGP-4+. When it is +used for exchanging multicast routing information it is called MBGP. + + +*bgpd* supports Multiprotocol Extension for BGP. So if a remote peer supports +the protocol, *bgpd* can exchange IPv6 and/or multicast routing information. + + +Traditional BGP did not have the feature to detect a remote peer's +capabilities, e.g. whether it can handle prefix types other than IPv4 unicast +routes. This was a big problem using Multiprotocol Extension for BGP in an +operational network. {rfc}`2842` adopted a feature called Capability +Negotiation. *bgpd* use this Capability Negotiation to detect the remote peer's +capabilities. If a peer is only configured as an IPv4 unicast neighbor, *bgpd* +does not send these Capability Negotiation packets (at least not unless other +optional BGP features require capability negotiation). + + +By default, FRR will bring up peering with minimal common capability for the +both sides. For example, if the local router has unicast and multicast +capabilities and the remote router only has unicast capability the local router +will establish the connection with unicast only capability. When there are no +common capabilities, FRR sends Unsupported Capability error and then resets the +connection. + + +## Configuration + + +(bgp-router-configuration)= + + +### BGP Router Configuration + + +First of all you must configure BGP router with the {abbr}`ASN (Autonomous +System Number)`. The AS number is an identifier for the autonomous system. +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 system-as \<asn\> + +Set local autonomous system number that this router represents. This is a +mandatory option! +``` + +#### Peers Configuration + + +##### Defining Peers + +```{cfgcmd} set protocols bgp neighbor \<address|interface\> remote-as \<asn\> + +This command creates a new neighbor whose remote-as is \<asn\>. The neighbor +address can be an IPv4 address or an IPv6 address or an interface to use +for the connection. The command is applicable for peer and peer group. +``` + + +```{cfgcmd} set protocols bgp neighbor \<address|interface\> remote-as internal + +Create a peer as you would when you specify an ASN, except that if the +peers ASN is different than mine as specified under the {cfgcmd}`protocols +bgp <asn>` command the connection will be denied. +``` + + +```{cfgcmd} set protocols bgp neighbor \<address|interface\> remote-as external + +Create a peer as you would when you specify an ASN, except that if the +peers ASN is the same as mine as specified under the {cfgcmd}`protocols +bgp <asn>` command the connection will be denied. +``` + + +```{cfgcmd} set protocols bgp neighbor \<address|interface\> remote-as auto + +Create a peer as you would when you specify an ASN, except that the peers +remote ASN is detected automatically from the OPEN message. +``` + + +```{cfgcmd} set protocols bgp neighbor \<address|interface\> local-role \<role\> [strict] + +BGP roles are defined in RFC {rfc}`9234` and provide an easy way to +add route leak prevention, detection and mitigation. The local Role +value is negotiated with the new BGP Role capability which has a +built-in check of the corresponding value. In case of a mismatch the +new OPEN Roles Mismatch Notification <2, 11> would be sent. +The correct Role pairs are: + +Provider - Customer + +Peer - Peer + +RS-Server - RS-Client + +If {cfgcmd}`strict` is set the BGP session won’t become established +until the BGP neighbor sets local Role on its side. This +configuration parameter is defined in RFC {rfc}`9234` and is used to +enforce the corresponding configuration at your counter-parts side. + +Routes that are sent from provider, rs-server, or the peer local-role +(or if received by customer, rs-client, or the peer local-role) will +be marked with a new Only to Customer (OTC) attribute. + +Routes with this attribute can only be sent to your neighbor if your +local-role is provider or rs-server. Routes with this attribute can +be received only if your local-role is customer or rs-client. + +In case of peer-peer relationship routes can be received only if OTC +value is equal to your neighbor AS number. + +All these rules with OTC will help to detect and mitigate route leaks +and happen automatically if local-role is set. +``` + + +```{cfgcmd} set protocols bgp neighbor \<address|interface\> shutdown + +This command disable the peer or peer group. To reenable the peer use +the delete form of this command. +``` + + +```{cfgcmd} set protocols bgp neighbor \<address|interface\> description \<text\> + +Set description of the peer or peer group. +``` + + +```{cfgcmd} set protocols bgp neighbor \<address|interface\> update-source \<address|interface\> + +Specify the IPv4 source address to use for the BGP session to this neighbor, +may be specified as either an IPv4 address directly or as an interface name. +``` + +(bgp-capability-negotiation-1)= + + +##### Capability Negotiation + +```{cfgcmd} set protocols bgp neighbor \<address|interface\> capability dynamic + +This command would allow the dynamic update of capabilities over an +established BGP session. +``` + + +```{cfgcmd} set protocols bgp neighbor \<address|interface\> capability extended-nexthop + +Allow bgp to negotiate the extended-nexthop capability with it’s peer. +If you are peering over a IPv6 Link-Local address then this capability +is turned on automatically. If you are peering over a IPv6 Global Address +then turning on this command will allow BGP to install IPv4 routes with +IPv6 nexthops if you do not have IPv4 configured on interfaces. +``` + + +```{cfgcmd} set protocols bgp neighbor \<address|interface\> disable-capability-negotiation + +Suppress sending Capability Negotiation as OPEN message optional +parameter to the peer. This command only affects the peer is +configured other than IPv4 unicast configuration. + +When remote peer does not have capability negotiation feature, +remote peer will not send any capabilities at all. In that case, +bgp configures the peer with configured capabilities. + +You may prefer locally configured capabilities more than the negotiated +capabilities even though remote peer sends capabilities. If the peer is +configured by {cfgcmd}`override-capability`, VyOS ignores received +capabilities then override negotiated capabilities with configured values. + +Additionally you should keep in mind that this feature fundamentally +disables the ability to use widely deployed BGP features. BGP unnumbered, +hostname support, AS4, Addpath, Route Refresh, ORF, Dynamic Capabilities, +and graceful restart. +``` + + +```{cfgcmd} set protocols bgp neighbor \<address|interface\> override-capability + +This command allow override the result of Capability Negotiation with +local configuration. Ignore remote peer’s capability value. +``` + + +```{cfgcmd} set protocols bgp neighbor \<address|interface\> strict-capability-match + +This command forces strictly compare remote capabilities and local +capabilities. If capabilities are different, send Unsupported Capability +error then reset connection. + +You may want to disable sending Capability Negotiation OPEN message +optional parameter to the peer when remote peer does not implement +Capability Negotiation. Please use {cfgcmd}`disable-capability-negotiation` +command to disable the feature. +``` + +##### Peer Parameters + +```{cfgcmd} set protocols bgp neighbor \<address|interface\> address-family \<ipv4-unicast|ipv6-unicast\> allowas-in number \<number\> + +This command accept incoming routes with AS path containing AS +number with the same value as the current system AS. This is +used when you want to use the same AS number in your sites, +but you can’t connect them directly. + + The number parameter (1-10) configures the amount of accepted + occurrences of the system AS number in AS path. + + This command is only allowed for eBGP peers. It is not applicable + for peer groups. +``` + + +```{cfgcmd} set protocols bgp neighbor \<address|interface\> address-family \<ipv4-unicast|ipv6-unicast\> as-override + +This command override AS number of the originating router with +the local AS number. + +Usually this configuration is used in PEs (Provider Edge) to +replace the incoming customer AS number so the connected CE ( +Customer Edge) can use the same AS number as the other customer +sites. This allows customers of the provider network to use the +same AS number across their sites. + +This command is only allowed for eBGP peers. +``` + + +```{cfgcmd} set protocols bgp neighbor \<address|interface\> address-family \<ipv4-unicast|ipv6-unicast\> attribute-unchanged \<as-path|med|next-hop\> + +This command specifies attributes to be left unchanged for +advertisements sent to a peer or peer group. +``` + + +```{cfgcmd} set protocols bgp neighbor \<address|interface\> address-family \<ipv4-unicast|ipv6-unicast\> maximum-prefix \<number\> + +This command specifies a maximum number of prefixes we can receive +from a given peer. If this number is exceeded, the BGP session +will be destroyed. The number range is 1 to 4294967295. +``` + + +```{cfgcmd} set protocols bgp neighbor \<address|interface\> address-family \<ipv4-unicast|ipv6-unicast\> nexthop-self + +This command forces the BGP speaker to report itself as the +next hop for an advertised route it advertised to a neighbor. +``` + + +```{cfgcmd} set protocols bgp neighbor \<address|interface\> address-family \<ipv4-unicast|ipv6-unicast\> remove-private-as + +This command removes the private ASN of routes that are advertised +to the configured peer. It removes only private ASNs on routes +advertised to EBGP peers. + +If the AS-Path for the route has only private ASNs, the private +ASNs are removed. + +If the AS-Path for the route has a private ASN between public +ASNs, it is assumed that this is a design choice, and the +private ASN is not removed. +``` + + +```{cfgcmd} set protocols bgp neighbor \<address|interface\> address-family \<ipv4-unicast|ipv6-unicast\> soft-reconfiguration inbound + +Changes in BGP policies require the BGP session to be cleared. Clearing has a +large negative impact on network operations. Soft reconfiguration enables you +to generate inbound updates from a neighbor, change and activate BGP policies +without clearing the BGP session. + +This command specifies that route updates received from this neighbor will be +stored unmodified, regardless of the inbound policy. When inbound soft +reconfiguration is enabled, the stored updates are processed by the new +policy configuration to create new inbound updates. + +:::{note} +Storage of route updates uses memory. If you enable soft +reconfiguration inbound for multiple neighbors, the amount of memory used +can become significant. +::: +``` + + +```{cfgcmd} set protocols bgp neighbor \<address|interface\> address-family \<ipv4-unicast|ipv6-unicast\> weight \<number\> + +This command specifies a default weight value for the neighbor’s +routes. The number range is 1 to 65535. +``` + + +```{cfgcmd} set protocols bgp neighbor \<address|interface\> advertisement-interval \<seconds\> + +This command specifies the minimum route advertisement interval for +the peer. The interval value is 0 to 600 seconds, with the default +advertisement interval being 0. +``` + + +```{cfgcmd} set protocols bgp neighbor \<address|interface\> disable-connected-check + +This command allows peerings between directly connected eBGP peers +using loopback addresses without adjusting the default TTL of 1. +``` + + +```{cfgcmd} set protocols bgp neighbor \<address|interface\> disable-send-community \<extended|standard\> + +This command specifies that the community attribute should not be sent +in route updates to a peer. By default community attribute is sent. +``` + + +```{cfgcmd} set protocols bgp neighbor \<address|interface\> ebgp-multihop \<number\> + +This command allows sessions to be established with eBGP neighbors +when they are multiple hops away. When the neighbor is not directly +connected and this knob is not enabled, the session will not establish. +The number of hops range is 1 to 255. This command is mutually +exclusive with {cfgcmd}`ttl-security hops`. +``` + + +```{cfgcmd} set protocols bgp neighbor \<address|interface\> local-as \<asn\> [no-prepend] [replace-as] + +Specify an alternate AS for this BGP process when interacting with +the specified peer or peer group. With no modifiers, the specified +local-as is prepended to the received AS_PATH when receiving routing +updates from the peer, and prepended to the outgoing AS_PATH (after +the process local AS) when transmitting local routes to the peer. + +If the {cfgcmd}`no-prepend` attribute is specified, then the supplied +local-as is not prepended to the received AS_PATH. + +If the {cfgcmd}`replace-as` attribute is specified, then only the supplied +local-as is prepended to the AS_PATH when transmitting local-route +updates to this peer. + +:::{note} +This command is only allowed for eBGP peers. +::: +``` + + +```{cfgcmd} set protocols bgp neighbor \<address|interface\> passive + +Configures the BGP speaker so that it only accepts inbound connections +from, but does not initiate outbound connections to the peer or peer group. +``` + + +```{cfgcmd} set protocols bgp neighbor \<address|interface\> password \<text\> + +This command specifies a MD5 password to be used with the tcp socket that +is being used to connect to the remote peer. +``` + + +```{cfgcmd} set protocols bgp neighbor \<address|interface\> ttl-security hops \<number\> + +This command enforces Generalized TTL Security Mechanism (GTSM), +as specified in {rfc}`5082`. With this command, only neighbors +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`. +``` + +##### Peer Groups + +Peer groups are used to help improve scaling by generating the same update +information to all members of a peer group. Note that this means that the +routes generated by a member of a peer group will be sent back to that +originating peer with the originator identifier attribute set to indicated +the originating peer. All peers not associated with a specific peer group +are treated as belonging to a default peer group, and will share updates. + +```{cfgcmd} set protocols bgp peer-group \<name\> + + This command defines a new peer group. You can specify to the group the same + parameters that you can specify for specific neighbors. + + :::{note} + If you apply a parameter to an individual neighbor IP address, you + override the action defined for a peer group that includes that IP + address. + ::: +``` + + +```{cfgcmd} set protocols bgp neighbor \<address|interface\> peer-group \<name\> + +This command bind specific peer to peer group with a given name. +``` + +#### Network Advertisement Configuration + +```{cfgcmd} set protocols bgp address-family \<ipv4-unicast|ipv6-unicast\> network \<prefix\> + +This command is used for advertising IPv4 or IPv6 networks. + + :::{note} + By default, the BGP prefix is advertised even if it's not present + in the routing table. This behaviour differs from the implementation of + some vendors. + ::: +``` + + +```{cfgcmd} set protocols bgp parameters network-import-check + +This configuration modifies the behavior of the network statement. If you +have this configured the underlying network must exist in the routing table. +``` + + +```{cfgcmd} set protocols bgp neighbor \<address|interface\> address-family \<ipv4-unicast|ipv6-unicast\> default-originate [route-map \<name\>] + +By default, VyOS does not advertise a default route (0.0.0.0/0) even if it is +in routing table. When you want to announce default routes to the peer, use +this command. Using optional argument {cfgcmd}`route-map` you can inject the +default route to given neighbor only if the conditions in the route map are +met. +``` + +#### Route Aggregation Configuration + +```{cfgcmd} set protocols bgp address-family \<ipv4-unicast|ipv6-unicast\> aggregate-address \<prefix\> + +This command specifies an aggregate address. The router will also +announce longer-prefixes inside of the aggregate address. +``` + + +```{cfgcmd} set protocols bgp address-family \<ipv4-unicast|ipv6-unicast\> aggregate-address \<prefix\> as-set + +This command specifies an aggregate address with a mathematical set of +autonomous systems. This command summarizes the AS_PATH attributes of +all the individual routes. +``` + + +```{cfgcmd} set protocols bgp address-family \<ipv4-unicast|ipv6-unicast\> aggregate-address \<prefix\> summary-only + +This command specifies an aggregate address and provides that +longer-prefixes inside of the aggregate address are suppressed +before sending BGP updates out to peers. +``` + + +```{cfgcmd} set protocols bgp neighbor \<address|interface\> address-family \<ipv4-unicast|ipv6-unicast\> unsuppress-map \<name\> + +This command applies route-map to selectively unsuppress prefixes +suppressed by summarisation. +``` + +#### Redistribution Configuration + +```{cfgcmd} set protocols bgp address-family \<ipv4-unicast|ipv6-unicast\> redistribute <route source> + +This command redistributes routing information from the given route source +to the BGP process. There are six modes available for route source: +connected, kernel, ospf, rip, static, table. +``` + + +```{cfgcmd} set protocols bgp address-family \<ipv4-unicast|ipv6-unicast\> redistribute <route source> metric \<number\> + +This command specifies metric (MED) for redistributed routes. The +metric range is 0 to 4294967295. There are six modes available for +route source: connected, kernel, ospf, rip, static, table. +``` + + +```{cfgcmd} set protocols bgp address-family \<ipv4-unicast|ipv6-unicast\> redistribute <route source> route-map \<name\> + +This command allows to use route map to filter redistributed routes. +There are six modes available for route source: connected, kernel, +ospf, rip, static, table. +``` + +#### General Configuration +##### Common parameters + +```{cfgcmd} set protocols bgp parameters allow-martian-nexthop + + When a peer receives a martian nexthop as part of the NLRI for a route + permit the nexthop to be used as such, instead of rejecting and resetting + the connection. +``` + + +```{cfgcmd} set protocols bgp parameters router-id \<id\> + +This command specifies the router-ID. If router ID is not specified it will +use the highest interface IP address. +``` + + +```{cfgcmd} set protocols bgp address-family \<ipv4-unicast|ipv6-unicast\> maximum-paths \<ebgp|ibgp\> \<number\> + +This command defines the maximum number of parallel routes that +the BGP can support. In order for BGP to use the second path, the +following attributes have to match: Weight, Local Preference, AS +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 no-hard-administrative-reset + +Do not send Hard Reset CEASE Notification for "Administrative Reset" +events. When set and Graceful Restart Notification capability is exchanged +between the peers, Graceful Restart procedures apply, and routes will be retained. +``` + + +```{cfgcmd} set protocols bgp parameters log-neighbor-changes + +This command enable logging neighbor up/down changes and reset reason. +``` + + +```{cfgcmd} set protocols bgp parameters no-client-to-client-reflection + +This command disables route reflection between route reflector clients. +By default, the clients of a route reflector are not required to be +fully meshed and the routes from a client are reflected to other clients. +However, if the clients are fully meshed, route reflection is not required. +In this case, use the {cfgcmd}`no-client-to-client-reflection` command +to disable client-to-client reflection. +``` + + +```{cfgcmd} set protocols bgp parameters no-fast-external-failover + +Disable immediate session reset if peer's connected link goes down. +``` + + +```{cfgcmd} set protocols bgp parameters no-ipv6-auto-ra + +By default, FRR sends router advertisement packets when Extended Next Hop is +on or when a connection is established directly using the device name (Unnumbered BGP). +Setting this option prevents FRR from sending router advertisement packets, but could break Unnumbered BGP. +``` + + +```{cfgcmd} set protocols bgp listen range \<prefix\> peer-group \<name\> + +This command is useful if one desires to loosen the requirement for BGP +to have strictly defined neighbors. Specifically what is allowed is for +the local router to listen to a range of IPv4 or IPv6 addresses defined +by a prefix and to accept BGP open messages. When a TCP connection +(and subsequently a BGP open message) from within this range tries to +connect the local router then the local router will respond and connect +with the parameters that are defined within the peer group. One must define +a peer-group for each range that is listed. If no peer-group is defined +then an error will keep you from committing the configuration. +``` + + +```{cfgcmd} set protocols bgp listen limit \<number\> + +This command goes hand in hand with the listen range command to limit the +amount of BGP neighbors that are allowed to connect to the local router. +The limit range is 1 to 5000. +``` + + +```{cfgcmd} set protocols bgp parameters ebgp-requires-policy + +This command changes the eBGP behavior of FRR. By default FRR enables +{rfc}`8212` functionality which affects how eBGP routes are advertised, +namely no routes are advertised across eBGP sessions without some +sort of egress route-map/policy in place. In VyOS however we have this +RFC functionality disabled by default so that we can preserve backwards +compatibility with older versions of VyOS. With this option one can +enable {rfc}`8212` functionality to operate. +``` + + +```{cfgcmd} set protocols bgp parameters labeled-unicast \<explicit-null | ipv4-explicit-null | ipv6-explicit-null\> + +By default, locally advertised prefixes use the implicit-null label to +encode in the outgoing NLRI. + +The following command uses the explicit-null label value for all the +BGP instances. +``` + +##### Administrative Distance + +```{cfgcmd} set protocols bgp parameters distance global \<external|internal|local\> \<distance\> + +This command change distance value of BGP. The arguments are the distance +values for external routes, internal routes and local routes respectively. +The distance range is 1 to 255. +``` + + +```{cfgcmd} set protocols bgp parameters distance prefix \<subnet\> distance \<distance\> + +This command sets the administrative distance for a particular route. The +distance range is 1 to 255. + +:::{note} +Routes with a distance of 255 are effectively disabled and not +installed into the kernel. +::: +``` + +##### Timers + +```{cfgcmd} set protocols bgp timers holdtime \<seconds\> + + This command specifies hold-time in seconds. The timer range is + 4 to 65535. The default value is 180 second. If you set value to 0 + VyOS will not hold routes. +``` + + +```{cfgcmd} set protocols bgp timers keepalive \<seconds\> + +This command specifies keep-alive time in seconds. The timer +can range from 4 to 65535. The default value is 60 second. +``` + +##### Route Dampening + +When a route fails, a routing update is sent to withdraw the route from the +network's routing tables. When the route is re-enabled, the change in +availability is also advertised. A route that continually fails and returns +requires a great deal of network traffic to update the network about the +route's status. + +Route dampening wich described in {rfc}`2439` enables you to identify routes +that repeatedly fail and return. If route dampening is enabled, an unstable +route accumulates penalties each time the route fails and returns. If the +accumulated penalties exceed a threshold, the route is no longer advertised. +This is route suppression. Routes that have been suppressed are re-entered +into the routing table only when the amount of their penalty falls below a +threshold. + +A penalty of 1000 is assessed each time the route fails. When the penalties +reach a predefined threshold (suppress-value), the router stops advertising +the route. + +Once a route is assessed a penalty, the penalty is decreased by half each time +a predefined amount of time elapses (half-life-time). When the accumulated +penalties fall below a predefined threshold (reuse-value), the route is +unsuppressed and added back into the BGP routing table. + +No route is suppressed indefinitely. Maximum-suppress-time defines the maximum +time a route can be suppressed before it is re-advertised. + +```{cfgcmd} set protocols bgp parameters dampening half-life \<minutes\> + +This command defines the amount of time in minutes after +which a penalty is reduced by half. The timer range is +10 to 45 minutes. +``` + + +```{cfgcmd} set protocols bgp parameters dampening re-use \<seconds\> + +This command defines the accumulated penalty amount at which the +route is re-advertised. The penalty range is 1 to 20000. +``` + + +```{cfgcmd} set protocols bgp parameters dampening start-suppress-time \<seconds\> + +This command defines the accumulated penalty amount at which the +route is suppressed. The penalty range is 1 to 20000. +``` + + +```{cfgcmd} set protocols bgp parameters dampening max-suppress-time \<seconds\> + +This command defines the maximum time in minutes that a route is +suppressed. The timer range is 1 to 255 minutes. +``` + +#### Route Selection Configuration + +```{cfgcmd} set protocols bgp parameters always-compare-med + + This command provides to compare the MED on routes, even when they were + received from different neighbouring ASes. Setting this option makes the + order of preference of routes more defined, and should eliminate MED + induced oscillations. +``` + + +```{cfgcmd} set protocols bgp parameters bestpath as-path confed + +This command specifies that the length of confederation path sets and +sequences should be taken into account during the BGP best path +decision process. +``` + + +```{cfgcmd} set protocols bgp parameters bestpath as-path multipath-relax + +This command specifies that BGP decision process should consider paths +of equal AS_PATH length candidates for multipath computation. Without +the knob, the entire AS_PATH must match for multipath computation. +``` + + +```{cfgcmd} set protocols bgp parameters bestpath as-path ignore + +Ignore AS_PATH length when selecting a route +``` + + +```{cfgcmd} set protocols bgp parameters bestpath compare-routerid + +Ensure that when comparing routes where both are equal on most metrics, +including local-pref, AS_PATH length, IGP cost, MED, that the tie is +broken based on router-ID. + +If this option is enabled, then the already-selected check, where +already selected eBGP routes are preferred, is skipped. + +If a route has an ORIGINATOR_ID attribute because it has been reflected, +that ORIGINATOR_ID will be used. Otherwise, the router-ID of the peer +the route was received from will be used. + +The advantage of this is that the route-selection (at this point) will +be more deterministic. The disadvantage is that a few or even one lowest-ID +router may attract all traffic to otherwise-equal paths because of this +check. It may increase the possibility of MED or IGP oscillation, unless +other measures were taken to avoid these. The exact behaviour will be +sensitive to the iBGP and reflection topology. +``` + + +```{cfgcmd} set protocols bgp parameters bestpath med confed + +This command specifies that BGP considers the MED when comparing routes +originated from different sub-ASs within the confederation to which this +BGP speaker belongs. The default state, where the MED attribute is not +considered. +``` + + +```{cfgcmd} set protocols bgp parameters bestpath med missing-as-worst + +This command specifies that a route with a MED is always considered to be +better than a route without a MED by causing the missing MED attribute to +have a value of infinity. The default state, where the missing MED +attribute is considered to have a value of zero. +``` + + +```{cfgcmd} set protocols bgp parameters default local-pref <local-pref value> + +This command specifies the default local preference value. The local +preference range is 0 to 4294967295. +``` + + +```{cfgcmd} set protocols bgp parameters deterministic-med + +This command provides to compare different MED values that advertised by +neighbours in the same AS for routes selection. When this command is +enabled, routes from the same autonomous system are grouped together, and +the best entries of each group are compared. +``` + + +```{cfgcmd} set protocols bgp address-family ipv4-unicast network \<prefix\> backdoor + +This command allows the router to prefer route to specified prefix learned +via IGP through backdoor link instead of a route to the same prefix learned +via EBGP. +``` + +#### Route Filtering Configuration + +In order to control and modify routing information that is exchanged between +peers you can use route-map, filter-list, prefix-list, distribute-list. + +For inbound updates the order of preference is: + +> - route-map +> - filter-list +> - prefix-list, distribute-list + +For outbound updates the order of preference is: +> - prefix-list, distribute-list +> - filter-list +> - route-map +> +> :::{note} +> The attributes {cfgcmd}`prefix-list` and {cfgcmd}`distribute-list` +> are mutually exclusive, and only one command (distribute-list or +> prefix-list) can be applied to each inbound or outbound direction for a +> particular neighbor. +> ::: + +```{cfgcmd} set protocols bgp neighbor \<address|interface\> address-family \<ipv4-unicast|ipv6-unicast\> distribute-list \<export|import\> \<number\> + +This command applies the access list filters named in \<number\> to the +specified BGP neighbor to restrict the routing information that BGP learns +and/or advertises. The arguments {cfgcmd}`export` and {cfgcmd}`import` +specify the direction in which the access list are applied. +``` + + +```{cfgcmd} set protocols bgp neighbor \<address|interface\> address-family \<ipv4-unicast|ipv6-unicast\> prefix-list \<export|import\> \<name\> + +This command applies the prfefix list filters named in \<name\> to the +specified BGP neighbor to restrict the routing information that BGP learns +and/or advertises. The arguments {cfgcmd}`export` and {cfgcmd}`import` +specify the direction in which the prefix list are applied. +``` + + +```{cfgcmd} set protocols bgp neighbor \<address|interface\> address-family \<ipv4-unicast|ipv6-unicast\> route-map \<export|import\> \<name\> + +This command applies the route map named in \<name\> to the specified BGP +neighbor to control and modify routing information that is exchanged +between peers. The arguments {cfgcmd}`export` and {cfgcmd}`import` +specify the direction in which the route map are applied. +``` + + +```{cfgcmd} set protocols bgp neighbor \<address|interface\> address-family \<ipv4-unicast|ipv6-unicast\> filter-list \<export|import\> \<name\> + +This command applies the AS path access list filters named in \<name\> to the +specified BGP neighbor to restrict the routing information that BGP learns +and/or advertises. The arguments {cfgcmd}`export` and {cfgcmd}`import` +specify the direction in which the AS path access list are applied. +``` + + +```{cfgcmd} set protocols bgp neighbor \<address|interface\> address-family \<ipv4-unicast|ipv6-unicast\> capability orf \<receive|send\> + +This command enables the ORF capability (described in {rfc}`5291`) on the +local router, and enables ORF capability advertisement to the specified BGP +peer. The {cfgcmd}`receive` keyword configures a router to advertise ORF +receive capabilities. The {cfgcmd}`send` keyword configures a router to +advertise ORF send capabilities. To advertise a filter from a sender, you +must create an IP prefix list for the specified BGP peer applied in inbound +derection. +``` + + +```{cfgcmd} set protocols bgp neighbor \<address|interface\> solo + +This command prevents from sending back prefixes learned from the neighbor. +``` + +#### BGP Scaling Configuration + + +BGP routers connected inside the same AS through BGP belong to an internal BGP +session, or IBGP. In order to prevent routing table loops, IBGP speaker does +not advertise IBGP-learned routes to other IBGP speaker (Split Horizon +mechanism). As such, IBGP requires a full mesh of all peers. For large +networks, this quickly becomes unscalable. + + +There are two ways that help us to mitigate the BGPs full-mesh requirement in +a network: + + +> - Using BGP route-reflectors +> - Using BGP confederation + + +##### Route Reflector Configuration + + +Introducing route reflectors removes the need for the full-mesh. When you +configure a route reflector you have to tell the router whether the other IBGP +router is a client or non-client. A client is an IBGP router that the route +reflector will “reflect” routes to, the non-client is just a regular IBGP +neighbor. Route reflectors mechanism is described in {rfc}`4456` and updated +by {rfc}`7606`. + +```{cfgcmd} set protocols bgp neighbor \<address\> address-family \<ipv4-unicast|ipv6-unicast\> route-reflector-client + +This command specifies the given neighbor as route reflector client. +``` + + +```{cfgcmd} set protocols bgp parameters cluster-id \<id\> + +This command specifies cluster ID which identifies a collection of route +reflectors and their clients, and is used by route reflectors to avoid +looping. By default cluster ID is set to the BGP router id value, but can be +set to an arbitrary 32-bit value. +``` + +##### Confederation Configuration + +A BGP confederation divides our AS into sub-ASes to reduce the number of +required IBGP peerings. Within a sub-AS we still require full-mesh IBGP but +between these sub-ASes we use something that looks like EBGP but behaves like +IBGP (called confederation BGP). Confederation mechanism is described in +{rfc}`5065` + +```{cfgcmd} set protocols bgp parameters confederation identifier \<asn\> + +This command specifies a BGP confederation identifier. \<asn\> is the number +of the autonomous system that internally includes multiple sub-autonomous +systems (a confederation). +``` + + +```{cfgcmd} set protocols bgp parameters confederation peers \<nsubasn\> + +This command sets other confederations \<nsubasn\> as members of autonomous +system specified by {cfgcmd}`confederation identifier <asn>`. +``` + +## Operational Mode Commands +### Show + +```{opcmd} show bgp \<ipv4|ipv6\> + + This command displays all entries in BGP routing table. +``` + + +```none +BGP table version is 10, local router ID is 10.0.35.3, vrf id 0 +Default local pref 100, local AS 65000 +Status codes: s suppressed, d damped, h history, * valid, > best, = multipath, + i internal, r RIB-failure, S Stale, R Removed +Nexthop codes: @NNN nexthop's vrf id, < announce-nh-self +Origin codes: i - IGP, e - EGP, ? - incomplete +RPKI validation codes: V valid, I invalid, N Not found + + Network Next Hop Metric LocPrf Weight Path +*> 198.51.100.0/24 10.0.34.4 0 0 65004 i +*> 203.0.113.0/24 10.0.35.5 0 0 65005 i + +Displayed 2 routes and 2 total paths +``` + + +```{opcmd} show bgp \<ipv4|ipv6\> \<address|prefix\> + +This command displays information about the particular entry in the BGP +routing table. +``` + + +```none +BGP routing table entry for 198.51.100.0/24 +Paths: (1 available, best #1, table default) + Advertised to non peer-group peers: + 10.0.13.1 10.0.23.2 10.0.34.4 10.0.35.5 + 65004 + 10.0.34.4 from 10.0.34.4 (10.0.34.4) + Origin IGP, metric 0, valid, external, best (First path received) + Last update: Wed Jan 6 12:18:53 2021 +``` + + +```{opcmd} show bgp cidr-only + +This command displays routes with classless interdomain routing (CIDR). +``` + + +```{opcmd} show bgp \<ipv4|ipv6\> community \<value\> + +This command displays routes that belong to specified BGP communities. +Valid value is a community number in the range from 1 to 4294967200, +or AA:NN (autonomous system-community number/2-byte number), no-export, +local-as, or no-advertise. +``` + + +```{opcmd} show bgp \<ipv4|ipv6\> community-list \<name\> + +This command displays routes that are permitted by the BGP +community list. +``` + + +```{opcmd} show bgp \<ipv4|ipv6\> dampening dampened-paths + +This command displays BGP dampened routes. +``` + + +```{opcmd} show bgp \<ipv4|ipv6\> dampening flap-statistics + +This command displays information about flapping BGP routes. +``` + + +```{opcmd} show bgp \<ipv4|ipv6\> filter-list \<name\> + +This command displays BGP routes allowed by the specified AS Path +access list. +``` + + +```{opcmd} show bgp \<ipv4|ipv6\> neighbors \<address\> advertised-routes + +This command displays BGP routes advertised to a neighbor. +``` + + +```{opcmd} show bgp \<ipv4|ipv6\> neighbors \<address\> received-routes + +This command displays BGP routes originating from the specified BGP +neighbor before inbound policy is applied. To use this command inbound +soft reconfiguration must be enabled. +``` + + +```{opcmd} show bgp \<ipv4|ipv6\> neighbors \<address\> routes + +This command displays BGP received-routes that are accepted after filtering. +``` + + +```{opcmd} show bgp \<ipv4|ipv6\> neighbors \<address\> dampened-routes + +This command displays dampened routes received from BGP neighbor. +``` + + +```{opcmd} show bgp \<ipv4|ipv6\> regexp \<text\> + +This command displays information about BGP routes whose AS path +matches the specified regular expression. +``` + + +```{opcmd} show bgp \<ipv4|ipv6\> summary + +This command displays the status of all BGP connections. +``` + + +```none +IPv4 Unicast Summary: +BGP router identifier 10.0.35.3, local AS number 65000 vrf-id 0 +BGP table version 11 +RIB entries 5, using 920 bytes of memory +Peers 4, using 82 KiB of memory + +Neighbor V AS MsgRcvd MsgSent TblVer InQ OutQ Up/Down State/PfxRcd +10.0.13.1 4 65000 148 159 0 0 0 02:16:01 0 +10.0.23.2 4 65000 136 143 0 0 0 02:13:21 0 +10.0.34.4 4 65004 161 163 0 0 0 02:16:01 1 +10.0.35.5 4 65005 162 166 0 0 0 02:16:01 1 + +Total number of neighbors 4 +``` + +### Reset + +```{opcmd} reset bgp \<ipv4|ipv6\> \<address\> [soft [in|out]] + +This command resets BGP connections to the specified neighbor IP address. +With argument {cfgcmd}`soft` this command initiates a soft reset. If +you do not specify the {cfgcmd}`in` or {cfgcmd}`out` options, both +inbound and outbound soft reconfiguration are triggered. +``` + + +```{opcmd} reset bgp all + +This command resets all BGP connections of given router. +``` + + +```{opcmd} reset bgp \<ipv4|ipv6\> external + +This command resets all external BGP peers of given router. +``` + + +```{opcmd} reset bgp \<ipv4|ipv6\> peer-group \<name\> [soft [in|out]] + +This command resets BGP connections to the specified peer group. +With argument {cfgcmd}`soft` this command initiates a soft reset. If +you do not specify the {cfgcmd}`in` or {cfgcmd}`out` options, both +inbound and outbound soft reconfiguration are triggered. +``` + +## Examples +### IPv4 peering + +A simple eBGP configuration: + +**Node 1:** + +```none +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' +set protocols bgp neighbor 192.168.0.2 address-family ipv4-unicast +set protocols bgp address-family ipv4-unicast network '172.16.0.0/16' +set protocols bgp parameters router-id '192.168.0.1' +``` + +**Node 2:** + +```none +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' +set protocols bgp neighbor 192.168.0.1 address-family ipv4-unicast +set protocols bgp address-family ipv4-unicast network '172.17.0.0/16' +set protocols bgp parameters router-id '192.168.0.2' +``` + +Don't forget, the CIDR declared in the network statement MUST **exist in your +routing table (dynamic or static), the best way to make sure that is true is +creating a static route:** + +**Node 1:** + +```none +set protocols static route 172.16.0.0/16 blackhole distance '254' +``` + +**Node 2:** + +```none +set protocols static route 172.17.0.0/16 blackhole distance '254' +``` + +### IPv6 peering + +A simple BGP configuration via IPv6. + +**Node 1:** + +```none +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' +set protocols bgp neighbor 2001:db8::2 address-family ipv6-unicast +set protocols bgp address-family ipv6-unicast network '2001:db8:1::/48' +set protocols bgp parameters router-id '10.1.1.1' +``` + +**Node 2:** + +```none +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' +set protocols bgp neighbor 2001:db8::1 address-family ipv6-unicast +set protocols bgp address-family ipv6-unicast network '2001:db8:2::/48' +set protocols bgp parameters router-id '10.1.1.2' +``` + +Don't forget, the CIDR declared in the network statement **MUST exist in your +routing table (dynamic or static), the best way to make sure that is true is +creating a static route:** + +**Node 1:** + +```none +set protocols static route6 2001:db8:1::/48 blackhole distance '254' +``` + +**Node 2:** + +```none +set protocols static route6 2001:db8:2::/48 blackhole distance '254' +``` + +### Route Filtering + +Route filter can be applied using a route-map: + +**Node1:** + +```none +set policy prefix-list AS65535-IN rule 10 action 'permit' +set policy prefix-list AS65535-IN rule 10 prefix '172.16.0.0/16' +set policy prefix-list AS65535-OUT rule 10 action 'deny' +set policy prefix-list AS65535-OUT rule 10 prefix '172.16.0.0/16' +set policy prefix-list6 AS65535-IN rule 10 action 'permit' +set policy prefix-list6 AS65535-IN rule 10 prefix '2001:db8:2::/48' +set policy prefix-list6 AS65535-OUT rule 10 action 'deny' +set policy prefix-list6 AS65535-OUT rule 10 prefix '2001:db8:2::/48' + +set policy route-map AS65535-IN rule 10 action 'permit' +set policy route-map AS65535-IN rule 10 match ip address prefix-list 'AS65535-IN' +set policy route-map AS65535-IN rule 10 match ipv6 address prefix-list 'AS65535-IN' +set policy route-map AS65535-IN rule 20 action 'deny' +set policy route-map AS65535-OUT rule 10 action 'deny' +set policy route-map AS65535-OUT rule 10 match ip address prefix-list 'AS65535-OUT' +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 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' +set protocols bgp neighbor 2001:db8::2 address-family ipv6-unicast route-map import 'AS65535-IN' +``` + +**Node2:** + +```none +set policy prefix-list AS65534-IN rule 10 action 'permit' +set policy prefix-list AS65534-IN rule 10 prefix '172.17.0.0/16' +set policy prefix-list AS65534-OUT rule 10 action 'deny' +set policy prefix-list AS65534-OUT rule 10 prefix '172.17.0.0/16' +set policy prefix-list6 AS65534-IN rule 10 action 'permit' +set policy prefix-list6 AS65534-IN rule 10 prefix '2001:db8:1::/48' +set policy prefix-list6 AS65534-OUT rule 10 action 'deny' +set policy prefix-list6 AS65534-OUT rule 10 prefix '2001:db8:1::/48' + +set policy route-map AS65534-IN rule 10 action 'permit' +set policy route-map AS65534-IN rule 10 match ip address prefix-list 'AS65534-IN' +set policy route-map AS65534-IN rule 10 match ipv6 address prefix-list 'AS65534-IN' +set policy route-map AS65534-IN rule 20 action 'deny' +set policy route-map AS65534-OUT rule 10 action 'deny' +set policy route-map AS65534-OUT rule 10 match ip address prefix-list 'AS65534-OUT' +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 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' +set protocols bgp neighbor 2001:db8::1 address-family ipv6-unicast route-map import 'AS65534-IN' +``` + +We could expand on this and also deny link local and multicast in the rule 20 +action deny. diff --git a/docs/configuration/protocols/failover.md b/docs/configuration/protocols/failover.md new file mode 100644 index 00000000..96374d11 --- /dev/null +++ b/docs/configuration/protocols/failover.md @@ -0,0 +1,237 @@ +--- +description: |- + Failover routes are static routes that are installed in the routing + table only while a configured health-check target responds. VyOS uses them + to switch traffic to a backup path when the primary next hop becomes + unreachable, and to restore the primary path automatically once it recovers. +keywords: |- + failover, failover route, static route, health check, icmp probe, + next hop, route metric +--- + +# Failover + +Failover routes are manually configured network paths used only while their +health-check targets are reachable. If the target stops responding, VyOS +removes the route from the routing table and reinstalls it once the target +recovers. + +## Configuration + +Use the following commands to configure failover routes for a specific remote +`<subnet>` reachable via next-hop `<address>`. + +```{eval-rst} +.. cfgcmd:: set protocols failover route <subnet> next-hop <address> check target <target-address> + + **Configure the health check target IP address.** + + This is typically a highly available host, either within the destination + subnet or on the public internet. + + Example: + + .. code-block:: none + + set protocols failover route 203.0.113.1/32 next-hop 10.217.37.254 check target 8.8.8.8 +``` + +```{eval-rst} +.. cfgcmd:: set protocols failover route <subnet> next-hop <address> check timeout <timeout> + + **Configure the timeout interval, in seconds, between target health checks.** + + The valid range is 1 to 300 seconds. The default is 10 seconds. + + Example: + + .. code-block:: none + + set protocols failover route 203.0.113.1/32 next-hop 10.217.37.254 check timeout 2 +``` + +```{eval-rst} +.. cfgcmd:: set protocols failover route <subnet> next-hop <address> check type <protocol> + + **Configure the protocol to use for health checks.** + + The following protocols are available: + + * ``icmp``: VyOS sends two ICMP echo request packets with a 1-second + response timeout. The health check is successful if at least one response + is received. + * ``arp``: VyOS sends two ARP requests with a 1-second response timeout. + The health check is successful if at least one response is received. + * ``tcp``: VyOS verifies whether the destination TCP port is open. The + health check is successful if a TCP connection is successfully + established with the target port. + + The default protocol is ``icmp``. + + .. note:: + + When the check type is set to ``tcp``, you must also define the target + TCP port. + + Example: + + .. code-block:: none + + set protocols failover route 203.0.113.1/32 next-hop 10.217.37.254 check type tcp +``` + +```{eval-rst} +.. cfgcmd:: set protocols failover route <subnet> next-hop <address> check port <port> + + **Configure the destination TCP port on the health check target.** + + This parameter applies only when the check type is configured as ``tcp``. + + The valid port range is 1 to 65535. + + Example: + + .. code-block:: none + + set protocols failover route 203.0.113.1/32 next-hop 10.217.37.254 check port 443 +``` + +```{eval-rst} +.. cfgcmd:: set protocols failover route <subnet> next-hop <address> check policy <policy> + + **Configure the health check success policy for multiple targets.** + + The following policies are available: + + * ``any-available``: The health check succeeds if at least one of the + configured targets responds successfully. + * ``all-available``: The health check succeeds only if every configured + target responds successfully. + + The default policy is ``any-available``. + + Example: + + .. code-block:: none + + set protocols failover route 203.0.113.1/32 next-hop 10.217.37.254 check policy all-available +``` + +```{eval-rst} +.. cfgcmd:: set protocols failover route <subnet> next-hop <address> interface <interface> + + **Configure the local interface used to reach the next-hop address.** + + This parameter is mandatory. + + Example: + + .. code-block:: none + + set protocols failover route 203.0.113.1/32 next-hop 10.217.37.254 interface eth0 +``` + +```{eval-rst} +.. cfgcmd:: set protocols failover route <subnet> next-hop <address> metric <1-255> + + **Configure the metric (cost) for the failover route.** + + The metric defines the route priority. A lower metric value indicates a + more preferred route. + + The default value is 1. + + Example: + + .. code-block:: none + + set protocols failover route 203.0.113.1/32 next-hop 10.217.37.254 metric 50 +``` + +```{eval-rst} +.. cfgcmd:: set protocols failover route <subnet> next-hop <address> onlink + + Configure the next-hop to be reachable via the assigned interface, even + when ``<address>`` is outside any subnet configured on that interface. + + Example: + + .. code-block:: none + + set protocols failover route 203.0.113.1/32 next-hop 10.217.37.254 onlink +``` + +## Examples + +### Failover route with a single next-hop and ICMP health check + +The following example configures a failover route to `203.0.113.1/32` +through next-hop `192.0.2.1` on `eth0`. The next-hop is monitored with +ICMP probes to `192.0.2.1` every 5 seconds, and the route is installed with +a metric of 10. + +```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' +``` + +Verify the route: + +```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 + Flags: Selected + Status: Installed + * 192.0.2.1, via eth0, weight 1 +``` + +### Two failover routes with different metrics + +The following example configures two failover routes to `203.0.113.1/32`, +each through a different next-hop. The primary next-hop `192.0.2.1` is +reached on `eth0` with metric 10, and the backup next-hop `198.51.100.1` +is reached on `eth2` with metric 20. Both next-hops are monitored with ICMP +probes every 5 seconds. + +While both health checks succeed, the lower-metric route through `eth0` is +preferred. If the primary target stops responding, its route is removed from +the routing table, and traffic falls over to `198.51.100.1` via `eth2`. + +```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' +``` + +Verify routes: + +```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 + Flags: Selected + Status: Installed + * 192.0.2.1, via eth0, weight 1 + +Routing entry for 203.0.113.1/32 + Known via "kernel", distance 0, metric 20 + Last update 00:08:14 ago + Flags: None + Status: Installed + * 198.51.100.1, via eth2, weight 1 +``` + diff --git a/docs/configuration/protocols/igmp-proxy.md b/docs/configuration/protocols/igmp-proxy.md new file mode 100644 index 00000000..961f921b --- /dev/null +++ b/docs/configuration/protocols/igmp-proxy.md @@ -0,0 +1,79 @@ +--- +lastproofread: '2023-11-13' +--- + +(igmp-proxy)= + +# IGMP Proxy + +{abbr}`IGMP (Internet Group Management Protocol)` proxy sends IGMP host messages +on behalf of a connected client. The configuration must define one, and only one +upstream interface, and one or more downstream interfaces. + +## Configuration + +```{cfgcmd} set protocols igmp-proxy interface \<interface\> role \<upstream | downstream\> + +* **upstream:** The upstream network interface is the outgoing interface +which is responsible for communicating to available multicast data sources. +There can only be one upstream interface. + +* **downstream:** Downstream network interfaces are the distribution +interfaces to the destination networks, where multicast clients can join +groups and receive multicast data. One or more downstream interfaces must +be configured. +``` + +```{cfgcmd} set protocols igmp-proxy interface \<interface\> alt-subnet \<network\> + +Defines alternate sources for multicasting and IGMP data. The network address +must be on the following format 'a.b.c.d/n'. By default, the router will +accept data from sources on the same network as configured on an interface. +If the multicast source lies on a remote network, one must define from where +traffic should be accepted. + +This is especially useful for the upstream interface, since the source for +multicast traffic is often from a remote location. + +This option can be supplied multiple times. +``` + +```{cfgcmd} set protocols igmp-proxy disable-quickleave + +Disables quickleave mode. In this mode the daemon will not send a Leave IGMP +message upstream as soon as it receives a Leave message for any downstream +interface. The daemon will not ask for Membership reports on the downstream +interfaces, and if a report is received the group is not joined again the +upstream. + +If it's vital that the daemon should act exactly like a real multicast client +on the upstream interface, this function should be enabled. + +Enabling this function increases the risk of bandwidth saturation. +``` + +```{cfgcmd} set protocols igmp-proxy disable + +Disable this service. +``` + +(igmp-proxy-example)= + +### Example + +Interface eth1 LAN is behind NAT. In order to subscribe 10.0.0.0/23 subnet +multicast which is in eth0 WAN we need to configure igmp-proxy. + +```none +set protocols igmp-proxy interface eth0 role upstream +set protocols igmp-proxy interface eth0 alt-subnet 10.0.0.0/23 +set protocols igmp-proxy interface eth1 role downstream +``` + + +## Operation + +```{opcmd} restart igmp-proxy + +Restart the IGMP proxy process. +```
\ No newline at end of file diff --git a/docs/configuration/protocols/index.md b/docs/configuration/protocols/index.md new file mode 100644 index 00000000..5f190ce1 --- /dev/null +++ b/docs/configuration/protocols/index.md @@ -0,0 +1,25 @@ +# Protocols + +```{toctree} +:includehidden: true +:maxdepth: 1 + +arp +babel +bfd +bgp +failover +igmp-proxy +isis +mpls +multicast +segment-routing +traffic-engineering +openfabric +ospf +pim +pim6 +rip +rpki +static +``` diff --git a/docs/configuration/protocols/isis.md b/docs/configuration/protocols/isis.md new file mode 100644 index 00000000..ac6db346 --- /dev/null +++ b/docs/configuration/protocols/isis.md @@ -0,0 +1,746 @@ +```{include} /_include/need_improvement.txt +``` + +(routing-isis)= + +# IS-IS + +{abbr}`IS-IS (Intermediate System to Intermediate System)` is a link-state +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 connected neighbors. IS-IS runs directly on +the data link layer (Layer 2). IS-IS addresses are called +{abbr}`NETs (Network Entity Titles)` and can be 8 to 20 bytes long, but are +generally 10 bytes long. The tree database that is created with IS-IS is +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 + +### 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 command sets network entity title (NET) provided in ISO format. + +Here is an example {abbr}`NET (Network Entity Title)` value: + +:::{code-block} none +49.0001.1921.6800.1002.00 +::: +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 (numerical area ``1``) + +* System identifier: ``1921.6800.1002`` - for system identifiers we recommend + to use IP address or MAC address of the router itself. The way to construct + this is to keep all of the zeroes of the router IP address, and then change + the periods from being every three numbers to every four numbers. The + 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``. + +* {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 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 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 IS-IS router behavior: + +* **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 +{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: + +* **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 + +This command enables {rfc}`6232` purge originator identification. Enable +purge originator identification (POI) by adding the type, length and value +(TLV) with the Intermediate System (IS) identification to the LSPs that do +not contain POI information. If an IS generates a purge, VyOS adds this TLV +with the system ID of the IS to the purge. +``` + +```{cfgcmd} set protocols isis set-attached-bit + +This command sets ATT bit to 1 in Level1 LSPs. It is described in {rfc}`3787`. +``` + +```{cfgcmd} set protocols isis set-overload-bit + +This command sets overload bit to avoid any transit traffic through this +router. It is described in {rfc}`3787`. +``` + +```{cfgcmd} set protocols isis default-information originate \<ipv4|ipv6\> level-1 + +This command will generate a default-route in L1 database. +``` + +```{cfgcmd} set protocols isis default-information originate \<ipv4|ipv6\> level-2 + +This command will generate a default-route in L2 database. +``` + +```{cfgcmd} set protocols isis ldp-sync + +This command will enable IGP-LDP synchronization globally for ISIS. This +requires for LDP to be functional. This is described in {rfc}`5443`. By +default all interfaces operational in IS-IS are enabled for synchronization. +Loopbacks are exempt. + +``` + +```{cfgcmd} set protocols isis ldp-sync holddown \<seconds\> + +This command will change the hold down value globally for IGP-LDP +synchronization during convergence/interface flap events. +``` + +#### Interface Configuration + +```{cfgcmd} set protocols isis interface \<interface\> circuit-type \<level-1|level-1-2|level-2-only\> + +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 + +``` + +```{cfgcmd} set protocols isis interface \<interface\> hello-interval \<seconds\> + +This command sets hello interval in seconds on a given interface. +The range is 1 to 600. +``` + +```{cfgcmd} set protocols isis interface \<interface\> hello-multiplier \<seconds\> + +This command sets multiplier for hello holding time on a given +interface. The range is 2 to 100. +``` + +```{cfgcmd} set protocols isis interface \<interface\> hello-padding + +This command configures padding on hello packets to accommodate asymmetrical +maximum transfer units (MTUs) from different hosts as described in +{rfc}`3719`. This helps to prevent a premature adjacency Up state when one +routing devices MTU does not meet the requirements to establish the adjacency. +``` + +```{cfgcmd} set protocols isis interface \<interface\> metric \<metric\> + +This command set default metric for circuit. + +The metric range is 1 to 16777215 (Max value depend if metric support narrow +or wide value). +``` + +```{cfgcmd} set protocols isis interface \<interface\> network point-to-point + +This command specifies network type to Point-to-Point. The default +network type is broadcast. +``` + +```{cfgcmd} set protocols isis interface \<interface\> passive + +This command configures the passive mode for this interface. +``` + +```{cfgcmd} set protocols isis interface \<interface\> password plaintext-password \<text\> + +This command configures the authentication password for the interface. +``` + +```{cfgcmd} set protocols isis interface \<interface\> priority \<number\> + +This command sets priority for the interface for +{abbr}`DIS (Designated Intermediate System)` election. The priority +range is 0 to 127. +``` + +```{cfgcmd} set protocols isis interface \<interface\> psnp-interval \<number\> + +This command sets PSNP interval in seconds. The interval range is 0 +to 127. +``` + +```{cfgcmd} set protocols isis interface \<interface\> no-three-way-handshake + +This command disables Three-Way Handshake for P2P adjacencies which +described in {rfc}`5303`. Three-Way Handshake is enabled by default. +``` + +```{cfgcmd} set protocols isis interface \<interface\> ldp-sync disable + +This command disables IGP-LDP sync for this specific interface. +``` + +```{cfgcmd} set protocols isis interface \<interface\> ldp-sync holddown \<seconds\> + +This command will change the hold down value for IGP-LDP synchronization +during convergence/interface flap events, but for this interface only. +``` + +```{cfgcmd} set protocols isis interface \<interface\> fast-reroute lfa [level-1 | level-2] enable + +This command enables per-prefix local LFA fast reroute link protection. +``` + +```{cfgcmd} set protocols isis interface \<interface\> fast-reroute lfa [level-1 | level-2] exclude + +This command excludes an interface from the local LFA backup nexthop computation. +``` + +```{cfgcmd} set protocols isis interface \<interface\> fast-reroute remote-lfa [level-1 | level-2] tunnel mpls-ldp + +This command enables per-prefix Remote LFA fast reroute link protection. +Note that other routers in the network need to be configured to accept LDP +targeted hello messages in order for RLFA to work. +``` + +```{cfgcmd} set protocols isis interface \<interface\> fast-reroute remote-lfa [level-1 | level-2] maximum-metric \<metric\> + +This command limits Remote LFA PQ node selection within the specified metric. Metric value range (1-16777215). +``` + +```{cfgcmd} set protocols isis interface \<interface\> fast-reroute ti-lfa [level-1|level-2] [node-protection [link-fallback]] + +This command enables per-prefix TI-LFA fast reroute link or node protection. +When node protection is used, option link-fallback enables the computation +and use of link-protecting LFAs for destinations unprotected by node +protection. +``` + +#### Route Redistribution + +```{cfgcmd} set protocols isis redistribute ipv4 \<route source\> level-1 + +This command redistributes routing information from the given route source +into the ISIS database as Level-1. There are six modes available for route +source: bgp, connected, kernel, ospf, rip, static. +``` + +```{cfgcmd} set protocols isis redistribute ipv4 \<route source\> level-2 + +This command redistributes routing information from the given route source +into the ISIS database as Level-2. There are six modes available for route +source: bgp, connected, kernel, ospf, rip, static. +``` + +```{cfgcmd} set protocols isis redistribute ipv4 \<route source\> \<level-1|level-2\> metric \<number\> + +This command specifies metric for redistributed routes from the given route +source. There are six modes available for route source: bgp, connected, +kernel, ospf, rip, static. The metric range is 1 to 16777215. +``` + +```{cfgcmd} set protocols isis redistribute ipv4 \<route source\> \<level-1|level-2\> route-map \<name\> + +This command allows to use route map to filter redistributed routes from +the given route source. There are six modes available for route source: +bgp, connected, kernel, ospf, rip, static. +``` + +#### Timers + +```{cfgcmd} set protocols isis lsp-gen-interval \<seconds\> + +This command sets minimum interval in seconds between regenerating same +LSP. The interval range is 1 to 120. +``` + +```{cfgcmd} set protocols isis lsp-refresh-interval \<seconds\> + +This command sets LSP refresh interval in seconds. IS-IS generates LSPs +when the state of a link changes. However, to ensure that routing +databases on all routers remain converged, LSPs in stable networks are +generated on a regular basis even though there has been no change to +the state of the links. The interval range is 1 to 65235. The default +value is 900 seconds. +``` + +```{cfgcmd} set protocols isis max-lsp-lifetime \<seconds\> + +This command sets LSP maximum LSP lifetime in seconds. The interval range +is 350 to 65535. LSPs remain in a database for 1200 seconds by default. +If they are not refreshed by that time, they are deleted. You can change +the LSP refresh interval or the LSP lifetime. The LSP refresh interval +should be less than the LSP lifetime or else LSPs will time out before +they are refreshed. +``` + +```{cfgcmd} set protocols isis spf-interval \<seconds\> + +This command sets minimum interval between consecutive SPF calculations in +seconds.The interval range is 1 to 120. +``` + +```{cfgcmd} set protocols isis spf-delay-ietf holddown \<milliseconds\> +``` + +```{cfgcmd} set protocols isis spf-delay-ietf init-delay \<milliseconds\> +``` + +```{cfgcmd} set protocols isis spf-delay-ietf long-delay \<milliseconds\> +``` + +```{cfgcmd} set protocols isis spf-delay-ietf short-delay \<milliseconds\> +``` + +```{cfgcmd} set protocols isis spf-delay-ietf time-to-learn \<milliseconds\> + +This commands specifies the Finite State Machine (FSM) intended to +control the timing of the execution of SPF calculations in response +to IGP events. The process described in {rfc}`8405`. +``` + +#### Loop Free Alternate (LFA) + +```{cfgcmd} set protocols isis fast-reroute lfa remote prefix-list \<name\> \<level-1|level-2\> + +This command enables IP fast re-routing that is part of {rfc}`5286`. +Specifically this is a prefix list which references a prefix in which +will select eligible PQ nodes for remote LFA backups. +``` + +```{cfgcmd} set protocols isis fast-reroute lfa local load-sharing disable \<level-1|level-2\> + +This command disables the load sharing across multiple LFA backups. +``` + +```{cfgcmd} set protocols isis fast-reroute lfa local tiebreaker \<downstream|lowest-backup-metric|node-protecting\> index \<number\> \<level-1|level-2\> + +This command will configure a tie-breaker for multiple local LFA backups. +The lower index numbers will be processed first. +``` + +```{cfgcmd} set protocols isis fast-reroute lfa local priority-limit \<medium|high|critical\> \<level-1|level-2\> + +This command will limit LFA backup computation up to the specified +prefix priority. +``` + +#### Segment Routing over IPv6 (SRv6) + +```{cfgcmd} set protocols isis segment-routing srv6 interface \<interface\> + +The dummy interface used +to install SRv6 SIDs into the Linux data plane. The interface must exist and +must be present when configuring IS-IS with +SRv6. +``` + +```{cfgcmd} set protocols isis segment-routing srv6 locator \<locator\> + +Specifies the SRv6 locator to use for IS-IS. IS-IS automatically allocates +prefix and adjacency SIDs, creates local SID entries and advertises them +into the IGP domain. +``` + +```{cfgcmd} set protocols isis segment-routing srv6 node-msd max-end-d \<0-255\> + +The Maximum End D MSD Type specifies the maximum number of SIDs present in an +SRH when performing decapsulation. As specified in {rfc}`8986`, the permitted +SID types include, but are not limited to, End.DX6, End.DT4, End.DT46, End +with USD, and End.X with USD. + +If the advertised value is zero or no value is advertised, then the router +cannot apply any behavior that results in decapsulation and forwarding of the +inner packet if the outer IPv6 header contains an SRH. + +Reference: {rfc}`9352` +``` + +```{cfgcmd} set protocols isis segment-routing srv6 node-msd max-end-pop \<0-255\> + +The Maximum End Pop MSD Type signals the maximum number of SIDs in the SRH to +which the router can apply "Penultimate Segment Pop (PSP) of the SRH" or +"Ultimate Segment Pop (USP) of the SRH" behavior, as defined in "Flavors" +(Section 4.16 of {rfc}`8986`). + +If the advertised value is zero or no value is advertised, then the router +cannot apply PSP or USP flavors. + +Reference: {rfc}`9352` +``` + +```{cfgcmd} set protocols isis segment-routing srv6 node-msd max-h-encaps \<0-255\> + +The Maximum H.Encaps MSD Type signals the maximum number of SIDs that can be +added to the segment list of an SRH as part of the "H.Encaps" behavior, as +defined in {rfc}`8986`. + +If the advertised value is zero or no value is advertised, then the headend +can apply an SR Policy that only contains one segment without inserting any +SRH header. A non-zero SRH Max H.encaps MSD indicates that the headend can +insert an SRH up to the advertised number of SIDs. + +Reference: {rfc}`9352` +``` + +```{cfgcmd} set protocols isis segment-routing srv6 node-msd max-segs-left \<0-255\> + +The Maximum Segments Left MSD Type signals the maximum value of the +"Segments Left" field ({rfc}`8754`) in the SRH of a received packet before +applying the Endpoint behavior associated with a SID. + +If no value is advertised, the supported value is 0. + +Reference: {rfc}`9352` +``` + +## Examples + +### Enable IS-IS + +**Node 1:** + +```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:** + +```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: + +```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: + +```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 + +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:** + +```none +set interfaces dummy dum0 address '203.0.113.1/24' +set interfaces ethernet eth1 address '192.0.2.1/24' + +set policy prefix-list EXPORT-ISIS rule 10 action 'permit' +set policy prefix-list EXPORT-ISIS rule 10 prefix '203.0.113.0/24' +set policy route-map EXPORT-ISIS rule 10 action 'permit' +set policy route-map EXPORT-ISIS rule 10 match ip address prefix-list 'EXPORT-ISIS' + +set protocols isis interface eth1 +set protocols isis net '49.0001.1921.6800.1002.00' +set protocols isis redistribute ipv4 connected level-2 route-map 'EXPORT-ISIS' +``` + +**Node 2:** + +```none +set interfaces ethernet eth1 address '192.0.2.2/24' + +set protocols isis interface eth1 +set protocols isis net '49.0001.1921.6800.2002.00' +``` + +Routes on Node 2: + +```none +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, + F - PBR, f - OpenFabric, + > - 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 and IGP-LDP synchronization + +**Node 1:** + +```none +set interfaces loopback lo address 192.168.255.255/32 +set interfaces ethernet eth0 address 192.0.2.1/24 + +set protocols isis interface eth0 +set protocols isis interface lo passive +set protocols isis ldp-sync +set protocols isis net 49.0001.1921.6825.5255.00 + +set protocols mpls interface eth0 +set protocols mpls ldp discovery transport-ipv4-address 192.168.255.255 +set protocols mpls ldp interface lo +set protocols mpls ldp interface eth0 +set protocols mpls ldp parameters transport-prefer-ipv4 +set protocols mpls ldp router-id 192.168.255.255 +``` + +This gives us IGP-LDP synchronization for all non-loopback interfaces with +a holddown timer of zero seconds: + +```none +Node-1@vyos:~$ show isis mpls ldp-sync +eth0 + LDP-IGP Synchronization enabled: yes + holddown timer in seconds: 0 + State: Sync achieved +``` + +### Enable IS-IS with Segment Routing (Experimental) + +**Node 1:** + +```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:** + +```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: + +```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: + +```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 +``` + +### Enable IS-IS with Segment Routing over IPv6 (Experimental) + +**Node 1:** + +```none +set interfaces dummy dum6 description "SRv6 IS-IS" +set interfaces ethernet eth1 address '192.0.2.1/24' +set interfaces loopback lo address '192.168.255.255/32' + +set protocols segment-routing srv6 locator MAIN prefix 2001:db8:1::/64 +set protocols segment-routing interface eth1 + +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 srv6 locator MAIN +set protocols isis segment-routing srv6 interface dum6 +``` + +**Node 2:** + +```none +set interfaces dummy dum6 description "SRv6 IS-IS" +set interfaces ethernet eth1 address '192.0.2.2/24' +set interfaces loopback lo address '192.168.255.254/32' + +set protocols segment-routing srv6 locator MAIN prefix 2001:db8:2::/64 +set protocols segment-routing interface eth1 + +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 srv6 locator MAIN +set protocols isis segment-routing srv6 interface dum6 +``` + +### Enable IS-IS with Segment Routing over IPv6 (uSID) (Experimental) + +**Node 1:** + +```none +set interfaces dummy dum6 description "SRv6 IS-IS" +set interfaces ethernet eth1 address '192.0.2.1/24' +set interfaces loopback lo address '192.168.255.255/32' + +set protocols segment-routing interface eth1 +set protocols segment-routing srv6 locator MAIN prefix 2001:db8:1::/48 +set protocols segment-routing srv6 locator MAIN behavior-usid +set protocols segment-routing srv6 locator MAIN block-len 32 +set protocols segment-routing srv6 locator MAIN format usid-f3216 +set protocols segment-routing srv6 locator MAIN func-bits 16 +set protocols segment-routing srv6 locator MAIN node-len 16 + +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 srv6 interface dum6 +set protocols isis segment-routing srv6 locator MAIN +``` + +**Node 2:** + +```none +set interfaces dummy dum6 description "SRv6 IS-IS" +set interfaces ethernet eth1 address '192.0.2.2/24' +set interfaces loopback lo address '192.168.255.254/32' + +set protocols segment-routing interface eth1 +set protocols segment-routing srv6 locator MAIN prefix 2001:db8:2::/48 +set protocols segment-routing srv6 locator MAIN behavior-usid +set protocols segment-routing srv6 locator MAIN block-len 32 +set protocols segment-routing srv6 locator MAIN format usid-f3216 +set protocols segment-routing srv6 locator MAIN func-bits 16 +set protocols segment-routing srv6 locator MAIN node-len 16 + +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 srv6 interface dum6 +set protocols isis segment-routing srv6 locator MAIN +``` diff --git a/docs/configuration/protocols/mpls.md b/docs/configuration/protocols/mpls.md new file mode 100644 index 00000000..71b14be2 --- /dev/null +++ b/docs/configuration/protocols/mpls.md @@ -0,0 +1,285 @@ +(mpls)= + +# MPLS + +{abbr}`MPLS (Multi-Protocol Label Switching)` is a packet forwarding paradigm +which differs from regular IP forwarding. Instead of IP addresses being used to +make the decision on finding the exit interface, a router will instead use an +exact match on a 32 bit/4 byte header called the MPLS label. This label is +inserted between the ethernet (layer 2) header and the IP (layer 3) header. +One can statically or dynamically assign label allocations, but we will focus +on dynamic allocation of labels using some sort of label distribution protocol +(such as the aptly named Label Distribution Protocol / LDP, Resource Reservation +Protocol / RSVP, or Segment Routing through OSPF/ISIS). These protocols allow +for the creation of a unidirectional/unicast path called a labeled switched +path (initialized as LSP) throughout the network that operates very much like +a tunnel through the network. An easy way of thinking about how an MPLS LSP +actually forwards traffic throughout a network is to think of a GRE tunnel. +They are not the same in how they operate, but they are the same in how they +handle the tunneled packet. It would be good to think of MPLS as a tunneling +technology that can be used to transport many different types of packets, to +aid in traffic engineering by allowing one to specify paths throughout the +network (using RSVP or SR), and to generally allow for easier intra/inter +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 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 + +The {abbr}`MPLS (Multi-Protocol Label Switching)` architecture does not assume +a single protocol to create MPLS paths. VyOS supports the Label Distribution +Protocol (LDP) as implemented by FRR, based on {rfc}`5036`. + +{abbr}`LDP (Label Distribution Protocol)` is a TCP based MPLS signaling protocol +that distributes labels creating MPLS label switched paths in a dynamic manner. +LDP is not a routing protocol, as it relies on other routing protocols for +forwarding decisions. LDP cannot bootstrap itself, and therefore relies on said +routing protocols for communication with other routers that use LDP. + +In order to allow for LDP on the local router to exchange label advertisements +with other routers, a TCP session will be established between automatically +discovered and statically assigned routers. LDP will try to establish a TCP +session to the **transport address** of other routers. Therefore for LDP to +function properly please make sure the transport address is shown in the +routing table and reachable to traffic at all times. + +It is highly recommended to use the same address for both the LDP router-id and +the discovery transport address, but for VyOS MPLS LDP to work both parameters +must be explicitly set in the configuration. + +Another thing to keep in mind with LDP is that much like BGP, it is a protocol +that runs on top of TCP. It however does not have an ability to do something +like a refresh capability like BGPs route refresh capability. Therefore one +might have to reset the neighbor for a capability change or a configuration +change to work. + +## Configuration Options + +```{cfgcmd} set protocols mpls interface \<interface\> + +Use this command to enable MPLS processing on the interface you define. +``` + + +```{cfgcmd} set protocols mpls ldp interface \<interface\> + +Use this command to enable LDP on the interface you define. +``` + + +```{cfgcmd} set protocols mpls ldp router-id \<address\> + +Use this command to configure the IP address used as the LDP router-id of the +local device. +``` + + +```{cfgcmd} set protocols mpls ldp discovery transport-ipv4-address \<address\> + +``` +```{cfgcmd} set protocols mpls ldp discovery transport-ipv6-address \<address\> + +Use this command to set the IPv4 or IPv6 transport-address used by LDP. +``` + +```{cfgcmd} set protocols mpls ldp neighbor \<address\> password \<password\> + +Use this command to configure authentication for LDP peers. Set the +IP address of the LDP peer and a password that should be shared in +order to become neighbors. +``` + +```{cfgcmd} set protocols mpls ldp neighbor \<address\> session-holdtime \<seconds\> + +Use this command to configure a specific session hold time for LDP peers. +Set the IP address of the LDP peer and a session hold time that should be +configured for it. You may have to reset the neighbor for this to work. +``` + +```{cfgcmd} set protocols mpls ldp neighbor \<address\> ttl-security \<disable | hop count\> + +Use this command to enable, disable, or specify hop count for TTL security +for LDP peers. By default the value is set to 255 (or max TTL). +``` + +```{eval-rst} +.. cfgcmd:: set protocols mpls ldp discovery hello-ipv4-interval <seconds> +.. cfgcmd:: set protocols mpls ldp discovery hello-ipv4-holdtime <seconds> +.. cfgcmd:: set protocols mpls ldp discovery hello-ipv6-interval <seconds> +.. cfgcmd:: set protocols mpls ldp discovery hello-ipv6-holdtime <seconds> + + Use these commands if you would like to set the discovery hello and hold time + parameters. +``` + +```{eval-rst} +.. cfgcmd:: set protocols mpls ldp discovery session-ipv4-holdtime <seconds> +.. cfgcmd:: set protocols mpls ldp discovery session-ipv6-holdtime <seconds> + + Use this command if you would like to set the TCP session hold time intervals. +``` + +```{eval-rst} +.. cfgcmd:: set protocols mpls ldp import ipv4 import-filter filter-access-list + <access list number> +.. cfgcmd:: set protocols mpls ldp import ipv6 import-filter filter-access-list6 + <access list number> + + Use these commands to control the importing of forwarding equivalence classes + (FECs) for LDP from neighbors. This would be useful for example on only + accepting the labeled routes that are needed and not ones that are not + needed, such as accepting loopback interfaces and rejecting all others. +``` + +```{eval-rst} +.. cfgcmd:: set protocols mpls ldp export ipv4 export-filter filter-access-list + <access list number> +.. cfgcmd:: set protocols mpls ldp export ipv6 export-filter filter-access-list6 + <access list number> + + Use these commands to control the exporting of forwarding equivalence classes + (FECs) for LDP to neighbors. This would be useful for example on only + announcing the labeled routes that are needed and not ones that are not + needed, such as announcing loopback interfaces and no others. +``` + +```{eval-rst} +.. cfgcmd:: set protocols mpls ldp export ipv4 explicit-null +.. cfgcmd:: set protocols mpls ldp export ipv6 explicit-null + + Use this command if you would like for the router to advertise FECs with a + label of 0 for explicit null operations. +``` + +```{eval-rst} +.. cfgcmd:: set protocols mpls ldp allocation ipv4 access-list <access list number> +.. cfgcmd:: set protocols mpls ldp allocation ipv6 access-list6 <access list number> + + Use this command if you would like to control the local FEC allocations for + LDP. A good example would be for your local router to not allocate a label for + everything. Just a label for what it's useful. A good example would be just a + loopback label. +``` + +```{cfgcmd} set protocols mpls ldp parameters cisco-interop-tlv + +Use this command to use a Cisco non-compliant format to send and interpret +the Dual-Stack capability TLV for IPv6 LDP communications. This is related to +{rfc}`7552`. +``` + +```{cfgcmd} set protocols mpls ldp parameters ordered-control + +Use this command to use ordered label distribution control mode. FRR +by default uses independent label distribution control mode for label +distribution. This is related to {rfc}`5036`. +``` + +```{cfgcmd} set protocols mpls ldp parameters transport-prefer-ipv4 + +Use this command to prefer IPv4 for TCP peer transport connection for LDP +when both an IPv4 and IPv6 LDP address are configured on the same interface. +``` + +```{cfgcmd} set protocols mpls ldp targeted-neighbor ipv4 enable +``` + +```{cfgcmd} set protocols mpls ldp targeted-neighbor ipv6 enable + +Use this command to enable targeted LDP sessions to the local router. The +router will then respond to any sessions that are trying to connect to it that +are not a link local type of TCP connection. +``` + +```{cfgcmd} set protocols mpls ldp targeted-neighbor ipv4 address \<address\> +``` + +```{cfgcmd} set protocols mpls ldp targeted-neighbor ipv6 address \<address\> + +Use this command to enable the local router to try and connect with a targeted +LDP session to another router. +``` + +```{cfgcmd} set protocols mpls ldp targeted-neighbor ipv4 hello-holdtime \<seconds\> +``` + +```{cfgcmd} set protocols mpls ldp targeted-neighbor ipv4 hello-interval \<seconds\> +``` + +```{cfgcmd} set protocols mpls ldp targeted-neighbor ipv6 hello-holdtime \<seconds\> +``` + +```{cfgcmd} set protocols mpls ldp targeted-neighbor ipv6 hello-interval \<seconds\> + +Use these commands if you would like to set the discovery hello and hold time +parameters for the targeted LDP neighbors. +``` + +### Sample configuration to setup LDP on VyOS + +```none +set protocols ospf area 0 network '192.168.255.252/32' <--- Routing for loopback +set protocols ospf area 0 network '192.168.0.5/32' <--- Routing for an interface connecting to the network +set protocols ospf parameters router-id '192.168.255.252' <--- Router ID setting for OSPF +set protocols mpls interface 'eth1' <--- Enable MPLS for an interface connecting to network +set protocols mpls ldp discovery transport-ipv4-address '192.168.255.252' <--- Transport address for LDP for TCP sessions to connect to +set protocols mpls ldp interface 'eth1' <--- Enable LDP for an interface connecting to network +set protocols mpls ldp interface 'lo' <--- Enable LDP on loopback for future services connectivity +set protocols mpls ldp router-id '192.168.255.252' <--- Router ID setting for LDP +set interfaces ethernet eth1 address '192.168.0.5/31' <--- Interface IP for connecting to network +set interfaces loopback lo address '192.168.255.252/32' <--- Interface loopback IP for router ID and other uses +``` + +## Operational Mode Commands + +When LDP is working, you will be able to see label information in the outcome +of `show ip route`. Besides that information, there are also specific *show* +commands for LDP: + +### Show + +```{opcmd} show mpls ldp binding + +Use this command to see the Label Information Base. + +``` + +```{opcmd} show mpls ldp discovery + +Use this command to see discovery hello information +``` + +```{opcmd} show mpls ldp interface + +Use this command to see LDP interface information +``` + +```{opcmd} show mpls ldp neighbor + +Use this command to see LDP neighbor information +``` + +```{opcmd} show mpls ldp neighbor detail + +Use this command to see detailed LDP neighbor information +``` + +### Reset + +```{opcmd} reset mpls ldp neighbor \<IPv4 or IPv6 address\> + +Use this command to reset an LDP neighbor/TCP session that is established +``` + +[wikipedia (mpls)]: <https://en.wikipedia.org/wiki/Multiprotocol_Label_Switching> diff --git a/docs/configuration/protocols/multicast.md b/docs/configuration/protocols/multicast.md new file mode 100644 index 00000000..27150a29 --- /dev/null +++ b/docs/configuration/protocols/multicast.md @@ -0,0 +1,31 @@ +(routing-static)= + +# Multicast + +In order to influence Multicast {abbr}`RPF (Reverse Path Forwarding)` lookup, +it is possible to insert into zebra routes for the Multicast +{abbr}`RIB (Routing Information Base)`. These routes are only used for RPF +lookup and will not be used by ZEBRA for insertion into the kernel or for +normal RIB processing. As such it is possible to create weird states with +these commands. + +Use with caution. Most of the time this will not be necessary. + +```{cfgcmd} set protocols static mroute \<subnet\> next-hop \<address\> [distance \<distance\>] + +Insert into the Multicast RIB Route `<subnet>` with specified next-hop. +The distance can be specified as well if desired. +``` +```{cfgcmd} set protocols static mroute \<subnet\> next-hop \<address\> disable + +Do not install route for `<subnet>` into the Multicast RIB. +``` +```{cfgcmd} set protocols static mroute \<subnet\> interface \<interface\> [distance \<distance\>] + +Insert into the Multicast RIB Route `<subnet>` with specified `<interface>`. +The distance can be specified as well if desired. +``` +```{cfgcmd} set protocols static mroute \<subnet\> interface \<interface\> disable + +Do not install route for `<subnet>` into the Multicast RIB. +```
\ No newline at end of file diff --git a/docs/configuration/protocols/openfabric.md b/docs/configuration/protocols/openfabric.md new file mode 100644 index 00000000..09ff5900 --- /dev/null +++ b/docs/configuration/protocols/openfabric.md @@ -0,0 +1,242 @@ +(openfabric)= + +# OpenFabric + +OpenFabric, specified in [draft-white-openfabric-06.txt](https://datatracker.ietf.org/doc/html/draft-white-openfabric-06), is +a routing protocol derived from IS-IS, providing link-state routing with +efficient flooding for topologies like spine-leaf networks. + +OpenFabric a dual stack protocol. +A single OpenFabric instance is able to perform routing for both IPv4 and IPv6. + +## General + +### Configuration + +#### Mandatory Settings + +For OpenFabric to operate correctly, one must do the equivalent of a Router ID +in Connectionless Network Service (CLNS). This Router ID is called the +{abbr}`NET (Network Entity Title)`. The system identifier must be unique within +the network + +```{cfgcmd} set protocols openfabric net \<network-entity-title\> + +This command sets network entity title (NET) provided in ISO format. + +Here is an example {abbr}`NET (Network Entity Title)` value: + +:::{code-block} none +49.0001.1921.6800.1002.00 +::: +The CLNS address consists of the following parts: + +* {abbr}`AFI (Address family authority identifier)` - ``49`` The AFI value + 49 is what OpenFabric uses for private addressing. + +* Area identifier: ``0001`` OpenFabric area number (numerical area ``1``) + +* System identifier: ``1921.6800.1002`` - for system identifiers we recommend + to use IP address or MAC address of the router itself. The way to construct + this is to keep all of the zeroes of the router IP address, and then change + the periods from being every three numbers to every four numbers. The + 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``. + +* {abbr}`NET (Network Entity Title)` selector: ``00`` Must always be 00. This + setting indicates "this system" or "local system." +``` + + +```{cfgcmd} set protocols openfabric domain \<name\> interface \<interface\> address-family \<ipv4|ipv6\> + +This command enables OpenFabric instance with \<NAME\> on this interface, and +allows for adjacency to occur for address family (IPv4 or IPv6 or both). +``` + +#### OpenFabric Global Configuration + +```{cfgcmd} set protocols openfabric domain-password \<plaintext-password|md5\> \<password\> + +This command configures the authentication password for a routing domain, +as clear text or md5 one. +``` + + +```{cfgcmd} set protocols openfabric domain \<name\> purge-originator + +This command enables {rfc}`6232` purge originator identification. +``` + + +```{cfgcmd} set protocols openfabric domain \<name\> set-overload-bit + +This command sets overload bit to avoid any transit traffic through this +router. +``` + + +```{cfgcmd} set protocols openfabric domain \<name\> log-adjacency-changes + +Log changes in adjacency state. +``` + + +```{cfgcmd} set protocols openfabric domain \<name\> fabric-tier \<number\> + +This command sets a static tier number to advertise as location +in the fabric. +``` + +#### Interface Configuration + +```{cfgcmd} set protocols openfabric interface \<interface\> hello-interval \<seconds\> + +This command sets hello interval in seconds on a given interface. +The range is 1 to 600. Hello packets are used to establish and maintain +adjacency between OpenFabric neighbors. +``` + + +```{cfgcmd} set protocols openfabric domain \<name\> interface \<interface\> hello-multiplier \<number\> + +This command sets multiplier for hello holding time on a given +interface. The range is 2 to 100. +``` + + +```{cfgcmd} set protocols openfabric domain \<name\> interface \<interface\> metric \<metric\> + +This command sets default metric for circuit. +The metric range is 1 to 16777215. +``` + + +```{cfgcmd} set protocols openfabric interface \<interface\> passive + +This command enables the passive mode for this interface. +``` + + +```{cfgcmd} set protocols openfabric domain \<name\> interface \<interface\> password plaintext-password \<text\> + +This command sets the authentication password for the interface. +``` + + +```{cfgcmd} set protocols openfabric domain \<name\> interface \<interface\> csnp-interval \<seconds\> + +This command sets Complete Sequence Number Packets (CSNP) interval in seconds. +The interval range is 1 to 600. +``` + + +```{cfgcmd} set protocols openfabric domain \<name\> interface \<interface\> psnp-interval \<number\> + +This command sets Partial Sequence Number Packets (PSNP) interval in seconds. +The interval range is 1 to 120. +``` + +#### Timers + +```{cfgcmd} set protocols openfabric domain \<name\> lsp-gen-interval \<seconds\> + +This command sets minimum interval at which link-state packets (LSPs) are +generated. The interval range is 1 to 120. +``` + + +```{cfgcmd} set protocols openfabric domain \<name\> lsp-refresh-interval \<seconds\> + +This command sets LSP refresh interval in seconds. The interval range +is 1 to 65235. +``` + + +```{cfgcmd} set protocols openfabric domain \<name\> max-lsp-lifetime \<seconds\> + +This command sets LSP maximum LSP lifetime in seconds. The interval range +is 360 to 65535. LSPs remain in a database for 1200 seconds by default. +If they are not refreshed by that time, they are deleted. You can change +the LSP refresh interval or the LSP lifetime. The LSP refresh interval +should be less than the LSP lifetime or else LSPs will time out before +they are refreshed. +``` + + +```{cfgcmd} set protocols openfabric domain \<name\> spf-interval \<seconds\> + +This command sets minimum interval between consecutive shortest path first +(SPF) calculations in seconds.The interval range is 1 to 120. +``` + +## Examples +### Enable OpenFabric + +**Node 1:** + +```none +set interfaces loopback lo address '192.168.255.255/32' +set interfaces ethernet eth1 address '192.0.2.1/24' + +set protocols openfabric domain VyOS interface eth1 address-family ipv4 +set protocols openfabric domain VyOS interface lo address-family ipv4 +set protocols openfabric net '49.0001.1921.6825.5255.00' +``` + +**Node 2:** + +```none +set interfaces loopback lo address '192.168.255.254/32' +set interfaces ethernet eth1 address '192.0.2.2/24' + +set protocols openfabric domain VyOS interface eth1 address-family ipv4 +set protocols openfabric domain VyOS interface lo address-family ipv4 +set protocols openfabric net '49.0001.1921.6825.5254.00' +``` + +This gives us the following neighborships: + +```none +Node-1@vyos:~$ show openfabric neighbor +show openfabric neighbor +Area VyOS: + System Id Interface L State Holdtime SNPA + vyos eth1 2 Up 27 2020.2020.2020 + + +Node-2@vyos:~$ show openfabric neighbor +show openfabric neighbor +Area VyOS: + System Id Interface L State Holdtime SNPA + vyos eth1 2 Up 30 2020.2020.2020 +``` + +Here's the IP routes that are populated: + +```none +Node-1@vyos:~$ show ip route openfabric +show ip route openfabric +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 + +f 192.0.2.0/24 [115/20] via 192.0.2.2, eth1 onlink, weight 1, 00:00:10 +f>* 192.168.255.254/32 [115/20] via 192.0.2.2, eth1 onlink, weight 1, 00:00:10 + +Node-2@vyos:~$ show ip route openfabric +show ip route openfabric +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 + +f 192.0.2.0/24 [115/20] via 192.0.2.1, eth1 onlink, weight 1, 00:00:48 +f>* 192.168.255.255/32 [115/20] via 192.0.2.1, eth1 onlink, weight 1, 00:00:48 +``` diff --git a/docs/configuration/protocols/ospf.md b/docs/configuration/protocols/ospf.md new file mode 100644 index 00000000..72fefb84 --- /dev/null +++ b/docs/configuration/protocols/ospf.md @@ -0,0 +1,1504 @@ +(routing-ospf)= + +# OSPF + +{abbr}`OSPF (Open Shortest Path First)` is a routing protocol for Internet +Protocol (IP) networks. It uses a link state routing (LSR) algorithm and falls +into the group of interior gateway protocols (IGPs), operating within a single +autonomous system (AS). It is defined as OSPF Version 2 in {rfc}`2328` (1998) +for IPv4. Updates for IPv6 are specified as OSPF Version 3 in {rfc}`5340` +(2008). OSPF supports the {abbr}`CIDR (Classless Inter-Domain Routing)` +addressing model. + +OSPF is a widely used IGP in large enterprise networks. + +## OSPFv2 (IPv4) + +### Configuration + +#### General + +VyOS does not have a special command to start the OSPF process. The OSPF process +starts when the first ospf enabled interface is configured. + +```{cfgcmd} set protocols ospf area \<number\> network \<A.B.C.D/M\> + + This command specifies the OSPF enabled interface(s). If the interface has + an address from defined range then the command enables OSPF on this + interface so router can provide network information to the other ospf + routers via this interface. + + This command is also used to enable the OSPF process. The area number can be + specified in decimal notation in the range from 0 to 4294967295. Or it + can be specified in dotted decimal notation similar to ip address. + + Prefix length in interface must be equal or bigger (i.e. smaller network) + than prefix length in network statement. For example statement above doesn't + 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 + basis {cfgcmd}`set protocols ospf interface <interface> area <x.x.x.x | x>` +``` + + +```{cfgcmd} set protocols ospf auto-cost reference-bandwidth \<number\> + +This command sets the reference bandwidth for cost calculations, where +bandwidth can be in range from 1 to 4294967, specified in Mbits/s. The +default is 100Mbit/s (i.e. a link of bandwidth 100Mbit/s or higher will +have a cost of 1. Cost of lower bandwidth links will be scaled with +reference to this cost). +``` + + +```{cfgcmd} set protocols ospf parameters router-id \<rid\> + +This command sets the router-ID of the OSPF process. The router-ID may be an +IP address of the router, but need not be – it can be any arbitrary 32bit +number. However it MUST be unique within the entire OSPF domain to the OSPF +speaker – bad things will happen if multiple OSPF speakers are configured +with the same router-ID! +``` + +#### Optional + +```{cfgcmd} set protocols ospf default-information originate [always] [metric \<number\>] [metric-type \<1|2\>] [route-map \<name\>] + +Originate an AS-External (type-5) LSA describing a default route into all +external-routing capable areas, of the specified metric and metric type. +If the {cfgcmd}`always` keyword is given then the default is always +advertised, even when there is no default present in the routing table. +The argument {cfgcmd}`route-map` specifies to advertise the default route +if the route map is satisfied. +``` + + +```{cfgcmd} set protocols ospf distance global \<distance\> + +This command change distance value of OSPF globally. +The distance range is 1 to 255. +``` + + +```{cfgcmd} set protocols ospf distance ospf \<external|inter-area|intra-area\> \<distance\> + +This command change distance value of OSPF. The arguments are the distance +values for external routes, inter-area routes and intra-area routes +respectively. The distance range is 1 to 255. + +:::{note} +Routes with a distance of 255 are effectively disabled and not +installed into the kernel. +::: +``` + + +```{cfgcmd} set protocols ospf log-adjacency-changes [detail] + +This command allows to log changes in adjacency. With the optional +{cfgcmd}`detail` argument, all changes in adjacency status are shown. +Without {cfgcmd}`detail`, only changes to full or regressions are shown. +``` + + +```{cfgcmd} set protocols ospf max-metric router-lsa \<administrative|on-shutdown <seconds\>|on-startup \<seconds\>> + +This enables {rfc}`3137` support, where the OSPF process describes its +transit links in its router-LSA as having infinite distance so that other +routers will avoid calculating transit paths through the router while +still being able to reach networks through the router. + +This support may be enabled administratively (and indefinitely) with the +{cfgcmd}`administrative` command. It may also be enabled conditionally. +Conditional enabling of max-metric router-lsas can be for a period of +seconds after startup with the {cfgcmd}`on-startup <seconds>` command +and/or for a period of seconds prior to shutdown with the +{cfgcmd}`on-shutdown <seconds>` command. The time range is 5 to 86400. +``` + + +```{cfgcmd} set protocols ospf parameters abr-type \<cisco|ibm|shortcut|standard\> + +This command selects ABR model. OSPF router supports four ABR models: + +**cisco** – a router will be considered as ABR if it has several configured +links to the networks in different areas one of which is a backbone area. +Moreover, the link to the backbone area should be active (working). +**ibm** – identical to "cisco" model but in this case a backbone area link +may not be active. +**standard** – router has several active links to different areas. +**shortcut** – identical to "standard" but in this model a router is +allowed to use a connected areas topology without involving a backbone +area for inter-area connections. + +Detailed information about "cisco" and "ibm" models differences can be +found in {rfc}`3509`. A "shortcut" model allows ABR to create routes +between areas based on the topology of the areas connected to this router +but not using a backbone area in case if non-backbone route will be +cheaper. For more information about "shortcut" model, +see ospf-shortcut-abr-02.txt +``` + + +```{cfgcmd} set protocols ospf parameters rfc1583-compatibility + +{rfc}`2328`, the successor to {rfc}`1583`, suggests according to section +G.2 (changes) in section 16.4.1 a change to the path preference algorithm +that prevents possible routing loops that were possible in the old version +of OSPFv2. More specifically it demands that inter-area paths and +intra-area backbone path are now of equal preference but still both +preferred to external paths. + +This command should NOT be set normally. +``` + + +```{cfgcmd} set protocols ospf interface \<interface\> passive [disable] + +This command specifies interface as passive. Passive interface advertises +its address, but does not run the OSPF protocol (adjacencies are not formed +and hello packets are not generated). + +The optional disable option allows to exclude interface from passive state. +This command is used if the command {cfgcmd}`passive-interface default` was +configured. +``` + + +```{cfgcmd} set protocols ospf passive-interface default + +This command specifies all interfaces as passive by default. Because this +command changes the configuration logic to a default passive; therefore, +interfaces where router adjacencies are expected need to be configured +with the {cfgcmd}`passive-interface-exclude` command. +``` + + +```{cfgcmd} set protocols ospf maximum-paths \<1-64\> + +Use this command to control the maximum number of equal cost paths to reach +a specific destination. The upper limit may differ if you change the value +of MULTIPATH_NUM during compilation. The default is MULTIPATH_NUM (64). +``` + + +```{cfgcmd} set protocols ospf refresh timers \<seconds\> + +The router automatically updates link-state information with its neighbors. +Only an obsolete information is updated which age has exceeded a specific +threshold. This parameter changes a threshold value, which by default is +1800 seconds (half an hour). The value is applied to the whole OSPF router. +The timer range is 10 to 1800. +``` + + +```{cfgcmd} set protocols ospf timers throttle spf \<delay|initial-holdtime|max-holdtime\> \<seconds\> + +This command sets the initial delay, the initial-holdtime and the +maximum-holdtime between when SPF is calculated and the event which +triggered the calculation. The times are specified in milliseconds and must +be in the range of 0 to 600000 milliseconds. {cfgcmd}`delay` sets the +initial SPF schedule delay in milliseconds. The default value is 200 ms. +{cfgcmd}`initial-holdtime` sets the minimum hold time between two +consecutive SPF calculations. The default value is 1000 ms. +{cfgcmd}`max-holdtime` sets the maximum wait time between two +consecutive SPF calculations. The default value is 10000 ms. +``` + + +```{cfgcmd} set protocols ospf ldp-sync + +This command will enable IGP-LDP synchronization globally for OSPF. This +requires for LDP to be functional. This is described in {rfc}`5443`. By +default all interfaces operational in OSPF are enabled for synchronization. +Loopbacks are exempt. +``` + + +```{cfgcmd} set protocols ospf ldp-sync holddown \<seconds\> + +This command will change the hold down value globally for IGP-LDP +synchronization during convergence/interface flap events. +``` + + +```{cfgcmd} set protocols ospf capability opaque + +ospfd supports Opaque LSA {rfc}`2370` as partial support for MPLS Traffic +Engineering LSAs. The opaque-lsa capability must be enabled in the +configuration. + +An alternate command could be "mpls-te on" (Traffic Engineering) + +:::{note} +FRR offers only partial support for some of the routing +protocol extensions that are used with MPLS-TE; it does not +support a complete RSVP-TE solution. +::: +``` + +#### Area Configuration + +```{cfgcmd} set protocols ospf area \<number\> area-type stub + +This command specifies the area to be a Stub Area. That is, an area where +no router originates routes external to OSPF and hence an area where all +external routes are via the ABR(s). Hence, ABRs for such an area do not +need to pass AS-External LSAs (type-5) or ASBR-Summary LSAs (type-4) into +the area. They need only pass Network-Summary (type-3) LSAs into such an +area, along with a default-route summary. +``` + + +```{cfgcmd} set protocols ospf area \<number\> area-type stub no-summary + +This command specifies the area to be a Totally Stub Area. In addition to +stub area limitations this area type prevents an ABR from injecting +Network-Summary (type-3) LSAs into the specified stub area. Only default +summary route is allowed. +``` + + +```{cfgcmd} set protocols ospf area \<number\> area-type stub default-cost \<number\> + +This command sets the cost of default-summary LSAs announced to stubby +areas. The cost range is 0 to 16777215. +``` + + +```{cfgcmd} set protocols ospf area \<number\> area-type nssa + +This command specifies the area to be a Not So Stubby Area. External +routing information is imported into an NSSA in Type-7 LSAs. Type-7 LSAs +are similar to Type-5 AS-external LSAs, except that they can only be +flooded into the NSSA. In order to further propagate the NSSA external +information, the Type-7 LSA must be translated to a Type-5 AS-external-LSA +by the NSSA ABR. +``` + + +```{cfgcmd} set protocols ospf area \<number\> area-type nssa no-summary + +This command specifies the area to be a NSSA Totally Stub Area. ABRs for +such an area do not need to pass Network-Summary (type-3) LSAs (except the +default summary route), ASBR-Summary LSAs (type-4) and AS-External LSAs +(type-5) into the area. But Type-7 LSAs that convert to Type-5 at the NSSA +ABR are allowed. +``` + + +```{cfgcmd} set protocols ospf area \<number\> area-type nssa default-cost \<number\> + +This command sets the default cost of LSAs announced to NSSA areas. +The cost range is 0 to 16777215. +``` + + +```{cfgcmd} set protocols ospf area \<number\> area-type nssa translate \<always|candidate|never\> + +Specifies whether this NSSA border router will unconditionally translate +Type-7 LSAs into Type-5 LSAs. When role is Always, Type-7 LSAs are +translated into Type-5 LSAs regardless of the translator state of other +NSSA border routers. When role is Candidate, this router participates in +the translator election to determine if it will perform the translations +duties. When role is Never, this router will never translate Type-7 LSAs +into Type-5 LSAs. +``` + + +```{cfgcmd} set protocols ospf area \<number\> authentication plaintext-password + +This command specifies that simple password authentication should be used +for the given area. The password must also be configured on a per-interface +basis. +``` + + +```{cfgcmd} set protocols ospf area \<number\> authentication md5 + +This command specify that OSPF packets must be authenticated with MD5 HMACs +within the given area. Keying material must also be configured on a +per-interface basis. +``` + + +```{cfgcmd} set protocols ospf area \<number\> range \<A.B.C.D/M\> [cost \<number\>] + +This command summarizes intra area paths from specified area into one +summary-LSA (Type-3) announced to other areas. This command can be used +only in ABR and ONLY router-LSAs (Type-1) and network-LSAs (Type-2) +(i.e. LSAs with scope area) can be summarized. AS-external-LSAs (Type-5) +can’t be summarized - their scope is AS. The optional argument +{cfgcmd}`cost` specifies the aggregated link metric. The metric range is 0 +to 16777215. +``` + + +```{cfgcmd} set protocols ospf area \<number\> range \<A.B.C.D/M\> not-advertise + +This command instead of summarizing intra area paths filter them - i.e. +intra area paths from this range are not advertised into other areas. +This command makes sense in ABR only. +``` + + +```{cfgcmd} set protocols ospf area \<number\> export-list \<acl_number\> + +Filter Type-3 summary-LSAs announced to other areas originated from +intra- area paths from specified area. +This command makes sense in ABR only. +``` + + +```{cfgcmd} set protocols ospf area \<number\> import-list \<acl_number\> + +Same as export-list, but it applies to paths announced into specified +area as Type-3 summary-LSAs. +This command makes sense in ABR only. +``` + + +```{cfgcmd} set protocols ospf area \<number\> range \<A.B.C.D/M\> substitute \<E.F.G.H/M\> + +One Type-3 summary-LSA with routing info <E.F.G.H/M> is announced into +backbone area if defined area contains at least one intra-area network +(i.e. described with router-LSA or network-LSA) from range <A.B.C.D/M>. +This command makes sense in ABR only. +``` + + +```{cfgcmd} set protocols ospf area \<number\> shortcut \<default|disable|enable\> + +This parameter allows to "shortcut" routes (non-backbone) for inter-area +routes. There are three modes available for routes shortcutting: + +**default** – this area will be used for shortcutting only if ABR does not +have a link to the backbone area or this link was lost. +**enable** – the area will be used for shortcutting every time the route +that goes through it is cheaper. +**disable** – this area is never used by ABR for routes shortcutting. +``` + + +```{cfgcmd} set protocols ospf area \<number\> virtual-link \<A.B.C.D\> + +Provides a backbone area coherence by virtual link establishment. + +In general, OSPF protocol requires a backbone area (area 0) to be coherent +and fully connected. I.e. any backbone area router must have a route to any +other backbone area router. Moreover, every ABR must have a link to +backbone area. However, it is not always possible to have a physical link +to a backbone area. In this case between two ABR (one of them has a link to +the backbone area) in the area (not stub area) a virtual link is organized. + +\<number\> – area identifier through which a virtual link goes. +\<A.B.C.D\> – ABR router-id with which a virtual link is established. Virtual +link must be configured on both routers. + +Formally, a virtual link looks like a point-to-point network connecting two +ABR from one area one of which physically connected to a backbone area. +This pseudo-network is considered to belong to a backbone area. +``` + +#### Interface Configuration + +```{cfgcmd} set protocols ospf interface \<interface\> area \<x.x.x.x | x\> + + Enable ospf on an interface and set associated area. + + If you have a lot of interfaces, and/or a lot of subnets, then enabling + OSPF via this command may result in a slight performance improvement. +``` + + +```{cfgcmd} set protocols ospf interface \<interface\> authentication plaintext-password \<text\> + +This command sets OSPF authentication key to a simple password. After +setting, all OSPF packets are authenticated. Key has length up to 8 chars. + +Simple text password authentication is insecure and deprecated in favour of +MD5 HMAC authentication. +``` + + +```{cfgcmd} set protocols ospf interface \<interface\> authentication md5 key-id \<id\> md5-key \<text\> + +This command specifys that MD5 HMAC authentication must be used on this +interface. It sets OSPF authentication key to a cryptographic password. +Key-id identifies secret key used to create the message digest. This ID +is part of the protocol and must be consistent across routers on a link. +The key can be long up to 16 chars (larger strings will be truncated), +and is associated with the given key-id. +``` + + +```{cfgcmd} set protocols ospf interface \<interface\> bandwidth \<number\> + +This command sets the interface bandwidth for cost calculations, where +bandwidth can be in range from 1 to 100000, specified in Mbits/s. +``` + + +```{cfgcmd} set protocols ospf interface \<interface\> cost \<number\> + +This command sets link cost for the specified interface. The cost value is +set to router-LSA’s metric field and used for SPF calculation. The cost +range is 1 to 65535. +``` + + +```{cfgcmd} set protocols ospf interface \<interface\> dead-interval \<number\> + +Set number of seconds for router Dead Interval timer value used for Wait +Timer and Inactivity Timer. This value must be the same for all routers +attached to a common network. The default value is 40 seconds. The +interval range is 1 to 65535. +``` + + +```{cfgcmd} set protocols ospf interface \<interface\> hello-multiplier \<number\> + +The hello-multiplier specifies how many Hellos to send per second, from 1 +(every second) to 10 (every 100ms). Thus one can have 1s convergence time +for OSPF. If this form is specified, then the hello-interval advertised in +Hello packets is set to 0 and the hello-interval on received Hello packets +is not checked, thus the hello-multiplier need NOT be the same across +multiple routers on a common link. +``` + + +```{cfgcmd} set protocols ospf interface \<interface\> hello-interval \<number\> + +Set number of seconds for Hello Interval timer value. Setting this value, +Hello packet will be sent every timer value seconds on the specified +interface. This value must be the same for all routers attached to a +common network. The default value is 10 seconds. The interval range is 1 +to 65535. +``` + + +```{cfgcmd} set protocols ospf interface \<interface\> bfd + +This command enables {abbr}`BFD (Bidirectional Forwarding Detection)` on +this OSPF link interface. +``` + + +```{cfgcmd} set protocols ospf interface \<interface\> mtu-ignore + +This command disables check of the MTU value in the OSPF DBD packets. Thus, +use of this command allows the OSPF adjacency to reach the FULL state even +though there is an interface MTU mismatch between two OSPF routers. +``` + + +```{cfgcmd} set protocols ospf interface \<interface\> network \<type\> + +This command allows to specify the distribution type for the network +connected to this interface: + +**broadcast** – broadcast IP addresses distribution. +**non-broadcast** – address distribution in NBMA networks topology. +**point-to-multipoint** – address distribution in point-to-multipoint +networks. +**point-to-point** – address distribution in point-to-point networks. +``` + + +```{cfgcmd} set protocols ospf interface \<interface\> priority \<number\> + +This command sets Router Priority integer value. The router with the +highest priority will be more eligible to become Designated Router. +Setting the value to 0, makes the router ineligible to become +Designated Router. The default value is 1. The interval range is 0 to 255. +``` + + +```{cfgcmd} set protocols ospf interface \<interface\> retransmit-interval \<number\> + +This command sets number of seconds for RxmtInterval timer value. This +value is used when retransmitting Database Description and Link State +Request packets if acknowledge was not received. The default value is 5 +seconds. The interval range is 3 to 65535. +``` + + +```{cfgcmd} set protocols ospf interface \<interface\> transmit-delay \<number\> + +This command sets number of seconds for InfTransDelay value. It allows to +set and adjust for each interface the delay interval before starting the +synchronizing process of the router's database with all neighbors. The +default value is 1 seconds. The interval range is 3 to 65535. +``` + + +```{cfgcmd} set protocols ospf interface \<interface\> ldp-sync disable + +This command disables IGP-LDP sync for this specific interface. +``` + + +```{cfgcmd} set protocols ospf interface \<interface\> ldp-sync holddown \<seconds\> + +This command will change the hold down value for IGP-LDP synchronization +during convergence/interface flap events, but for this interface only. +``` + +#### External Route Summarisation + + +This feature summarises originated external LSAs (Type-5 and Type-7). Summary +Route will be originated on-behalf of all matched external LSAs. + +```{cfgcmd} set protocols ospf aggregation timer \<seconds\> + +Configure aggregation delay timer interval. + +Summarisation starts only after this delay timer expiry. +``` + + +```{cfgcmd} set protocols ospf summary-address x.x.x.x/y [tag (1-4294967295)] + +This command enable/disables summarisation for the configured address range. + +Tag is the optional parameter. If tag configured Summary route will be +originated with the configured tag. +``` + + +```{cfgcmd} set protocols ospf summary-address x.x.x.x/y no-advertise + +This command to ensure not advertise the summary lsa for the matched +external LSAs. +``` + +#### Graceful Restart + +```{cfgcmd} set protocols ospf graceful-restart [grace-period (1-1800)] + +Configure Graceful Restart {rfc}`3623` restarting support. When enabled, +the default grace period is 120 seconds. + +To perform a graceful shutdown, the FRR ``graceful-restart prepare ip +ospf`` EXEC-level command needs to be issued before restarting the +ospfd daemon. +``` + + +```{cfgcmd} set protocols ospf graceful-restart helper enable [router-id A.B.C.D] + +Configure Graceful Restart {rfc}`3623` helper support. By default, helper support +is disabled for all neighbours. This config enables/disables helper support +on this router for all neighbours. + +To enable/disable helper support for a specific neighbour, the router-id +(A.B.C.D) has to be specified. +``` + + +```{cfgcmd} set protocols ospf graceful-restart helper no-strict-lsa-checking + +By default strict-lsa-checking is configured then the helper will abort +the Graceful Restart when a LSA change occurs which affects the restarting +router. + +This command disables it. +``` + + +```{cfgcmd} set protocols ospf graceful-restart helper supported-grace-time + +Supports as HELPER for configured grace period. +``` + + +```{cfgcmd} set protocols ospf graceful-restart helper planned-only + +It helps to support as HELPER only for planned restarts. + +By default, it supports both planned and unplanned outages. +``` + +#### Manual Neighbor Configuration + + +OSPF routing devices normally discover their neighbors dynamically by +listening to the broadcast or multicast hello packets on the network. +Because an NBMA network does not support broadcast (or multicast), the +device cannot discover its neighbors dynamically, so you must configure all +the neighbors statically. + +```{cfgcmd} set protocols ospf neighbor \<A.B.C.D\> + +This command specifies the IP address of the neighboring device. +``` + + +```{cfgcmd} set protocols ospf neighbor \<A.B.C.D\> poll-interval \<seconds\> + +This command specifies the length of time, in seconds, before the routing +device sends hello packets out of the interface before it establishes +adjacency with a neighbor. The range is 1 to 65535 seconds. The default +value is 60 seconds. +``` + + +```{cfgcmd} set protocols ospf neighbor \<A.B.C.D\> priority \<number\> + +This command specifies the router priority value of the nonbroadcast +neighbor associated with the IP address specified. The default is 0. +This keyword does not apply to point-to-multipoint interfaces. +``` + +#### Redistribution Configuration + +```{cfgcmd} set protocols ospf redistribute \<route source\> + + This command redistributes routing information from the given route source + to the OSPF process. There are five modes available for route source: bgp, + connected, kernel, rip, static. +``` + + +```{cfgcmd} set protocols ospf default-metric \<number\> + +This command specifies the default metric value of redistributed routes. +The metric range is 0 to 16777214. +``` + + +```{cfgcmd} set protocols ospf redistribute \<route source\> metric \<number\> + +This command specifies metric for redistributed routes from the given +route source. There are five modes available for route source: bgp, +connected, kernel, rip, static. The metric range is 1 to 16777214. +``` + + +```{cfgcmd} set protocols ospf redistribute \<route source\> metric-type \<1|2\> + +This command specifies metric type for redistributed routes. Difference +between two metric types that metric type 1 is a metric which is +"commensurable" with inner OSPF links. When calculating a metric to the +external destination, the full path metric is calculated as a metric sum +path of a router which had advertised this link plus the link metric. +Thus, a route with the least summary metric will be selected. If external +link is advertised with metric type 2 the path is selected which lies +through the router which advertised this link with the least metric +despite of the fact that internal path to this router is longer (with more +cost). However, if two routers advertised an external link and with metric +type 2 the preference is given to the path which lies through the router +with a shorter internal path. If two different routers advertised two +links to the same external destimation but with different metric type, +metric type 1 is preferred. If type of a metric left undefined the router +will consider these external links to have a default metric type 2. +``` + + +```{cfgcmd} set protocols ospf redistribute \<route source\> route-map \<name\> + +This command allows to use route map to filter redistributed routes from +the given route source. There are five modes available for route source: +bgp, connected, kernel, rip, static. +``` + +#### Operational Mode Commands + +```{opcmd} show ip ospf neighbor + + This command displays the neighbors status. +``` + + +```none +Neighbor ID Pri State Dead Time Address Interface RXmtL RqstL DBsmL +10.0.13.1 1 Full/DR 38.365s 10.0.13.1 eth0:10.0.13.3 0 0 0 +10.0.23.2 1 Full/Backup 39.175s 10.0.23.2 eth1:10.0.23.3 0 0 0 +``` + + +```{opcmd} show ip ospf neighbor detail + +This command displays the neighbors information in a detailed form, not +just a summary table. +``` + + +```none + Neighbor 10.0.13.1, interface address 10.0.13.1 + + In the area 0.0.0.0 via interface eth0 + + Neighbor priority is 1, State is Full, 5 state changes + + Most recent state change statistics: + + Progressive change 11m55s ago + + DR is 10.0.13.1, BDR is 10.0.13.3 + + Options 2 *|-|-|-|-|-|E|- + + Dead timer due in 34.854s + + Database Summary List 0 + + Link State Request List 0 + + Link State Retransmission List 0 + + Thread Inactivity Timer on + + Thread Database Description Retransmision off + + Thread Link State Request Retransmission on + + Thread Link State Update Retransmission on + + +Neighbor 10.0.23.2, interface address 10.0.23.2 + + In the area 0.0.0.1 via interface eth1 + + Neighbor priority is 1, State is Full, 4 state changes + + Most recent state change statistics: + + Progressive change 41.193s ago + + DR is 10.0.23.3, BDR is 10.0.23.2 + + Options 2 *|-|-|-|-|-|E|- + + Dead timer due in 35.661s + + Database Summary List 0 + + Link State Request List 0 + + Link State Retransmission List 0 + + Thread Inactivity Timer on + + Thread Database Description Retransmision off + + Thread Link State Request Retransmission on + + Thread Link State Update Retransmission on +``` + + +```{opcmd} show ip ospf neighbor \<A.B.C.D\> + +This command displays the neighbors information in a detailed form for a +neighbor whose IP address is specified. +``` + + +```{opcmd} show ip ospf neighbor \<interface\> + +This command displays the neighbors status for a neighbor on the specified +interface. +``` + + +```{opcmd} show ip ospf interface [\<interface\>] + +This command displays state and configuration of OSPF the specified +interface, or all interfaces if no interface is given. +``` + + +```none +eth0 is up + ifindex 2, MTU 1500 bytes, BW 4294967295 Mbit <UP,BROADCAST,RUNNING,MULTICAST> + Internet Address 10.0.13.3/24, Broadcast 10.0.13.255, Area 0.0.0.0 + MTU mismatch detection: enabled + Router ID 10.0.23.3, Network Type BROADCAST, Cost: 1 + Transmit Delay is 1 sec, State Backup, Priority 1 + Backup Designated Router (ID) 10.0.23.3, Interface Address 10.0.13.3 + Multicast group memberships: OSPFAllRouters OSPFDesignatedRouters + Timer intervals configured, Hello 10s, Dead 40s, Wait 40s, Retransmit 5 + Hello due in 4.470s + Neighbor Count is 1, Adjacent neighbor count is 1 +eth1 is up + ifindex 3, MTU 1500 bytes, BW 4294967295 Mbit <UP,BROADCAST,RUNNING,MULTICAST> + Internet Address 10.0.23.3/24, Broadcast 10.0.23.255, Area 0.0.0.1 + MTU mismatch detection: enabled + Router ID 10.0.23.3, Network Type BROADCAST, Cost: 1 + Transmit Delay is 1 sec, State DR, Priority 1 + Backup Designated Router (ID) 10.0.23.2, Interface Address 10.0.23.2 + Saved Network-LSA sequence number 0x80000002 + Multicast group memberships: OSPFAllRouters OSPFDesignatedRouters + Timer intervals configured, Hello 10s, Dead 40s, Wait 40s, Retransmit 5 + Hello due in 4.563s + Neighbor Count is 1, Adjacent neighbor count is 1 +``` + + +```{opcmd} show ip ospf route [detail] + +This command displays the OSPF routing table, as determined by the most +recent SPF calculation. With the optional {cfgcmd}`detail` argument, +each route item's advertiser router and network attribute will be shown. +``` + + +```none +============ OSPF network routing table ============ +N IA 10.0.12.0/24 [3] area: 0.0.0.0 + via 10.0.13.3, eth0 +N 10.0.13.0/24 [1] area: 0.0.0.0 + directly attached to eth0 +N IA 10.0.23.0/24 [2] area: 0.0.0.0 + via 10.0.13.3, eth0 +N 10.0.34.0/24 [2] area: 0.0.0.0 + via 10.0.13.3, eth0 + +============ OSPF router routing table ============= +R 10.0.23.3 [1] area: 0.0.0.0, ABR + via 10.0.13.3, eth0 +R 10.0.34.4 [2] area: 0.0.0.0, ASBR + via 10.0.13.3, eth0 + +============ OSPF external routing table =========== +N E2 172.16.0.0/24 [2/20] tag: 0 + via 10.0.13.3, eth0 +``` + +The table consists of following data: + + +**OSPF network routing table** – includes a list of acquired routes for all +accessible networks (or aggregated area ranges) of OSPF system. "IA" flag +means that route destination is in the area to which the router is not +connected, i.e. it’s an inter-area path. In square brackets a summary metric +for all links through which a path lies to this network is specified. "via" +prefix defines a router-gateway, i.e. the first router on the way to the +destination (next hop). +**OSPF router routing table** – includes a list of acquired routes to all +accessible ABRs and ASBRs. +**OSPF external routing table** – includes a list of acquired routes that are +external to the OSPF process. "E" flag points to the external link metric type +(E1 – metric type 1, E2 – metric type 2). External link metric is printed in +the "\<metric of the router which advertised the link>/\<link metric>" format. + +```{opcmd} show ip ospf border-routers + +This command displays a table of paths to area boundary and autonomous +system boundary routers. +``` + + +```{opcmd} show ip ospf database + +This command displays a summary table with a database contents (LSA). +``` + + +```none + OSPF Router with ID (10.0.13.1) + + Router Link States (Area 0.0.0.0) + +Link ID ADV Router Age Seq# CkSum Link count +10.0.13.1 10.0.13.1 984 0x80000005 0xd915 1 +10.0.23.3 10.0.23.3 1186 0x80000008 0xfe62 2 +10.0.34.4 10.0.34.4 1063 0x80000004 0x4e3f 1 + + Net Link States (Area 0.0.0.0) + +Link ID ADV Router Age Seq# CkSum +10.0.13.1 10.0.13.1 994 0x80000003 0x30bb +10.0.34.4 10.0.34.4 1188 0x80000001 0x9411 + + Summary Link States (Area 0.0.0.0) + +Link ID ADV Router Age Seq# CkSum Route +10.0.12.0 10.0.23.3 1608 0x80000001 0x6ab6 10.0.12.0/24 +10.0.23.0 10.0.23.3 981 0x80000003 0xe232 10.0.23.0/24 + + AS External Link States + +Link ID ADV Router Age Seq# CkSum Route +172.16.0.0 10.0.34.4 1063 0x80000001 0xc40d E2 172.16.0.0/24 [0x0] +``` + + +```{opcmd} show ip ospf database \<type\> [A.B.C.D] [adv-router \<A.B.C.D\>|self-originate] + + This command displays a database contents for a specific link advertisement + type. + + The type can be the following: + asbr-summary, external, network, nssa-external, opaque-area, opaque-as, + opaque-link, router, summary. + + [A.B.C.D] – link-state-id. With this specified the command displays portion + of the network environment that is being described by the advertisement. + The value entered depends on the advertisement’s LS type. It must be + entered in the form of an IP address. + + {cfgcmd}`adv-router <A.B.C.D>` – router id, which link advertisements need + to be reviewed. + + {cfgcmd}`self-originate` displays only self-originated LSAs from the local + router. +``` + + +```none + OSPF Router with ID (10.0.13.1) + + Router Link States (Area 0.0.0.0) + +LS age: 1213 +Options: 0x2 : *|-|-|-|-|-|E|- +LS Flags: 0x3 +Flags: 0x0 +LS Type: router-LSA +Link State ID: 10.0.13.1 +Advertising Router: 10.0.13.1 +LS Seq Number: 80000009 +Checksum: 0xd119 +Length: 36 + + Number of Links: 1 + + Link connected to: a Transit Network + (Link ID) Designated Router address: 10.0.13.1 + (Link Data) Router Interface address: 10.0.13.1 + Number of TOS metrics: 0 + TOS 0 Metric: 1 +``` + + +```{opcmd} show ip ospf database max-age + +This command displays LSAs in MaxAge list. +``` + +#### Examples +### Enable OSPF + +**Node 1** + +```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** + +```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: + +```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: + +```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** + +```none +set interfaces loopback lo address 10.1.1.1/32 +set protocols ospf area 0 network 192.168.0.0/24 +set protocols ospf default-information originate always +set protocols ospf default-information originate metric 10 +set protocols ospf default-information originate metric-type 2 +set protocols ospf log-adjacency-changes +set protocols ospf parameters router-id 10.1.1.1 +set protocols ospf redistribute connected metric-type 2 +set protocols ospf redistribute connected route-map CONNECT + +set policy route-map CONNECT rule 10 action permit +set policy route-map CONNECT rule 10 match interface lo +``` + +**Node 2** + +```none +set interfaces loopback lo address 10.2.2.2/32 +set protocols ospf area 0 network 192.168.0.0/24 +set protocols ospf log-adjacency-changes +set protocols ospf parameters router-id 10.2.2.2 +set protocols ospf redistribute connected metric-type 2 +set protocols ospf redistribute connected route-map CONNECT + +set policy route-map CONNECT rule 10 action permit +set policy route-map CONNECT rule 10 match interface lo +``` + +### Enable OSPF and IGP-LDP synchronization: + +**Node 1:** + +```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' +set protocols ospf ldp-sync + +set protocols mpls interface eth0 +set protocols mpls ldp discovery transport-ipv4-address 10.1.1.1 +set protocols mpls ldp interface lo +set protocols mpls ldp interface eth0 +set protocols mpls ldp parameters transport-prefer-ipv4 +set protocols mpls ldp router-id 10.1.1.1 +``` + +This gives us IGP-LDP synchronization for all non-loopback interfaces with +a holddown timer of zero seconds: + +```none +Node-1@vyos:~$ show ip ospf mpls ldp-sync + eth0 + LDP-IGP Synchronization enabled: yes + Holddown timer in seconds: 0 + State: Sync achieved +``` + +### Enable OSPF with Segment Routing (Experimental): + +**Node 1** + +```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** + +```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: + +```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: + +```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)= + +## OSPFv3 (IPv6) + +(ospf-v3-configuration)= + +### Configuration + +(ospf-v3-general)= + +#### 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 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 + decimal notation in the range from 0 to 4294967295. Or it can be specified + in dotted decimal notation similar to ip address. +``` + + +```{cfgcmd} set protocols ospfv3 parameters router-id \<rid\> + +This command sets the router-ID of the OSPFv3 process. The router-ID may be +an IP address of the router, but need not be – it can be any arbitrary +32bit number. However it MUST be unique within the entire OSPFv3 domain to +the OSPFv3 speaker – bad things will happen if multiple OSPFv3 speakers are +configured with the same router-ID! +``` + +(ospf-v3-optional)= + +#### Optional + +```{cfgcmd} set protocols ospfv3 distance global \<distance\> + +This command change distance value of OSPFv3 globally. +The distance range is 1 to 255. +``` +```{cfgcmd} set protocols ospfv3 distance ospfv3 \<external|inter-area|intra-area\> \<distance\> + +This command change distance value of OSPFv3. The arguments are the +distance values for external routes, inter-area routes and intra-area +routes respectively. The distance range is 1 to 255. +``` + +(ospf-v3-area-configuration)= + +#### Area Configuration + +```{cfgcmd} set protocols ospfv3 area \<number\> range \<prefix\> + +This command summarizes intra area paths from specified area into one +Type-3 Inter-Area Prefix LSA announced to other areas. This command can be +used only in ABR. +``` +```{cfgcmd} set protocols ospfv3 area \<number\> range \<prefix\> not-advertise + +This command instead of summarizing intra area paths filter them - i.e. +intra area paths from this range are not advertised into other areas. This +command makes sense in ABR only. +``` + +(ospf-v3-interface-config)= + +#### Interface Configuration + +```{cfgcmd} set protocols ospfv3 interface \<interface\> ipv6 cost \<number\> + +This command sets link cost for the specified interface. The cost value is +set to router-LSA’s metric field and used for SPF calculation. The cost +range is 1 to 65535. +``` +```{cfgcmd} set protocols ospfv3 interface \<interface\> dead-interval \<number\> + +Set number of seconds for router Dead Interval timer value used for Wait +Timer and Inactivity Timer. This value must be the same for all routers +attached to a common network. The default value is 40 seconds. The +interval range is 1 to 65535. +``` +```{cfgcmd} set protocols ospfv3 interface \<interface\> hello-interval \<number\> + +Set number of seconds for Hello Interval timer value. Setting this value, +Hello packet will be sent every timer value seconds on the specified +interface. This value must be the same for all routers attached to a +common network. The default value is 10 seconds. The interval range is 1 +to 65535. +``` +```{cfgcmd} set protocols ospfv3 interface \<interface\> mtu-ignore + +This command disables check of the MTU value in the OSPF DBD packets. +Thus, use of this command allows the OSPF adjacency to reach the FULL +state even though there is an interface MTU mismatch between two OSPF +routers. +``` +```{cfgcmd} set protocols ospfv3 interface \<interface\> network \<type\> + +This command allows to specify the distribution type for the network +connected to this interface: + +**broadcast** – broadcast IP addresses distribution. +**point-to-point** – address distribution in point-to-point networks. +``` +```{cfgcmd} set protocols ospfv3 interface \<interface\> priority \<number\> + +This command sets Router Priority integer value. The router with the +highest priority will be more eligible to become Designated Router. +Setting the value to 0, makes the router ineligible to become Designated +Router. The default value is 1. The interval range is 0 to 255. +``` +```{cfgcmd} set protocols ospfv3 interface \<interface\> passive + +This command specifies interface as passive. Passive interface advertises +its address, but does not run the OSPF protocol (adjacencies are not formed +and hello packets are not generated). +``` +```{cfgcmd} set protocols ospfv3 interface \<interface\> retransmit-interval \<number\> + +This command sets number of seconds for RxmtInterval timer value. This +value is used when retransmitting Database Description and Link State +Request packets if acknowledge was not received. The default value is 5 +seconds. The interval range is 3 to 65535. +``` +```{cfgcmd} set protocols ospfv3 interface \<interface\> transmit-delay \<number\> + +This command sets number of seconds for InfTransDelay value. It allows to +set and adjust for each interface the delay interval before starting the +synchronizing process of the router's database with all neighbors. The +default value is 1 seconds. The interval range is 3 to 65535. +``` + +(ospf-v3-graceful-restart)= + +#### Graceful Restart + +```{cfgcmd} set protocols ospfv3 graceful-restart [grace-period (1-1800)] + +Configure Graceful Restart {rfc}`3623` restarting support. When enabled, +the default grace period is 120 seconds. + +To perform a graceful shutdown, the FRR ``graceful-restart prepare ip +ospf`` EXEC-level command needs to be issued before restarting the +ospfd daemon. +``` +```{cfgcmd} set protocols ospfv3 graceful-restart helper enable [router-id A.B.C.D] + +Configure Graceful Restart {rfc}`3623` helper support. By default, helper support +is disabled for all neighbours. This config enables/disables helper support +on this router for all neighbours. + +To enable/disable helper support for a specific neighbour, the router-id +(A.B.C.D) has to be specified. +``` +```{cfgcmd} set protocols ospfv3 graceful-restart helper lsa-check-disable + +By default strict-lsa-checking is configured then the helper will abort +the Graceful Restart when a LSA change occurs which affects the restarting +router. + +This command disables it. +``` +```{cfgcmd} set protocols ospfv3 graceful-restart helper supported-grace-time + +Supports as HELPER for configured grace period. +``` +```{cfgcmd} set protocols ospfv3 graceful-restart helper planned-only + +It helps to support as HELPER only for planned restarts. +By default, it supports both planned and unplanned outages. +``` + +(ospf-v3-redistribution-config)= + +#### Redistribution Configuration + +```{cfgcmd} set protocols ospfv3 redistribute \<route source\> + +This command redistributes routing information from the given route source +to the OSPFv3 process. There are five modes available for route source: +bgp, connected, kernel, ripng, static. +``` +```{cfgcmd} set protocols ospf redistribute \<route source\> route-map \<name\> + +This command allows to use route map to filter redistributed routes from +given route source. There are five modes available for route source: bgp, +connected, kernel, ripng, static. +``` + +(ospf-v3-op-cmd)= + +#### Operational Mode Commands + +```{opcmd} show ipv6 ospfv3 neighbor + +This command displays the neighbors status. +``` +```{opcmd} show ipv6 ospfv3 neighbor detail + +This command displays the neighbors information in a detailed form, not +just a summary table. +``` +```{opcmd} show ipv6 ospfv3 neighbor drchoice + +This command displays the neighbor DR choice information. +``` +```{opcmd} show ipv6 ospfv3 interface [prefix]|[\<interface\> [prefix]] + +This command displays state and configuration of OSPF the specified +interface, or all interfaces if no interface is given. Whith the argument +{cfgcmd}`prefix` this command shows connected prefixes to advertise. +``` +```{opcmd} show ipv6 ospfv3 route + +This command displays the OSPF routing table, as determined by the most +recent SPF calculation. +``` +```{opcmd} show ipv6 ospfv3 border-routers + +This command displays a table of paths to area boundary and autonomous +system boundary routers. +``` +```{opcmd} show ipv6 ospfv3 database + +This command displays a summary table with a database contents (LSA). +``` +```{opcmd} show ipv6 ospfv3 database \<type\> [A.B.C.D] [adv-router \<A.B.C.D\>|self-originate] + +This command displays a database contents for a specific link +advertisement type. +``` +```{opcmd} show ipv6 ospfv3 redistribute + +This command displays external information redistributed into OSPFv3 +``` + +(ospf-v3-config-example)= + +#### Configuration Example + +A typical configuration using 2 nodes. + +**Node 1:** + +```none +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 +``` + +**Node 2:** + +```none +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 +``` + +**To see the redistributed routes:** + +```none +show ipv6 ospfv3 redistribute +``` + +Cost calculation wireguard interfaces is unreliable as ospfv3 uses the link speed to calculate the link cost. +You might therefore want to set the link cost to a fixed value on WireGuard tunnels. + +Example configuration for WireGuard interfaces: + +**Node 1** + +```none +set interfaces wireguard wg01 peer ospf02 allowed-ips '::/0' +set interfaces wireguard wg01 peer ospf02 endpoint '10.1.1.101:12345' +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 interface 'wg01' area 0.0.0.0 +set protocols ospfv3 interface 'wg01' cost 10 +set protocols ospfv3 interface 'lo' area 0.0.0.0 +``` + +**Node 2** + +```none +set interfaces wireguard wg01 peer ospf01 allowed-ips '::/0' +set interfaces wireguard wg01 peer ospf01 endpoint '10.1.1.100:12345' +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 interface 'wg01' area 0.0.0.0 +set protocols ospfv3 interface 'wg01' cost 10 +set protocols ospfv3 interface 'lo' area 0.0.0.0 +``` + +**Status** + +```none +vyos@ospf01:~$ sh ipv6 ospfv3 neighbor +Neighbor ID Pri DeadTime State/IfState Duration I/F[State] +192.168.0.2 1 00:00:37 Full/PointToPoint 00:18:03 wg01[PointToPoint] + +vyos@ospf02# run sh ipv6 ospfv3 neighbor +Neighbor ID Pri DeadTime State/IfState Duration I/F[State] +192.168.0.1 1 00:00:39 Full/PointToPoint 00:19:44 wg01[PointToPoint] +``` diff --git a/docs/configuration/protocols/pim.md b/docs/configuration/protocols/pim.md new file mode 100644 index 00000000..db8c9fb7 --- /dev/null +++ b/docs/configuration/protocols/pim.md @@ -0,0 +1,282 @@ +--- +lastproofread: '2023-11-13' +--- + +(pim)= + +# PIM – Protocol Independent Multicast + +VyOS supports {abbr}`PIM-SM (PIM Sparse Mode)` as well as +{abbr}`IGMP (Internet Group Management Protocol)` v2 and v3 + +{abbr}`PIM (Protocol Independent Multicast)` must be configured in every +interface of every participating router. Every router must also have the +location of the Rendevouz Point manually configured. Then, unidirectional +shared trees rooted at the Rendevouz Point will automatically be built +for multicast distribution. + +Traffic from multicast sources will go to the Rendezvous Point, and +receivers will pull it from a shared tree using {abbr}`IGMP (Internet +Group Management Protocol)`. + +Multicast receivers will talk IGMP to their local router, so, besides +having PIM configured in every router, IGMP must also be configured in +any router where there could be a multicast receiver locally connected. + +VyOS supports both IGMP version 2 and version 3 (which allows +source-specific multicast). + +## PIM-SM - PIM Sparse Mode + +```{cfgcmd} set protocols pim ecmp + +If PIM has the a choice of ECMP nexthops for a particular +{abbr}`RPF (Reverse Path Forwarding)`, PIM will cause S,G flows to be +spread out amongst the nexthops. If this command is not specified then +the first nexthop found will be used. +``` + +```{cfgcmd} set protocols pim ecmp rebalance + +If PIM is using ECMP and an interface goes down, cause PIM to rebalance all +S,G flows across the remaining nexthops. If this command is not configured +PIM only modifies those S,G flows that were using the interface that went +down. +``` + +```{cfgcmd} set protocols pim join-prune-interval \<n\> + +Modify the join/prune interval that PIM uses to the new value. Time is +specified in seconds. + +The default time is 60 seconds. + +If you enter a value smaller than 60 seconds be aware that this can and +will affect convergence at scale. +``` + +```{cfgcmd} set protocols pim keep-alive-timer \<n\> + +Modify the time out value for a S,G flow from 1-65535 seconds. If choosing +a value below 31 seconds be aware that some hardware platforms cannot see +data flowing in better than 30 second chunks. +``` + +```{cfgcmd} set protocols pim packets \<n\> + +When processing packets from a neighbor process the number of packets +incoming at one time before moving on to the next task. + +The default value is 3 packets. + +This command is only useful at scale when you can possibly have a large +number of PIM control packets flowing. +``` + +```{cfgcmd} set protocols pim register-accept-list \<prefix-list\> + +When PIM receives a register packet the source of the packet will be compared +to the prefix-list specified, and if a permit is received normal processing +continues. If a deny is returned for the source address of the register packet +a register stop message is sent to the source. +``` + +```{cfgcmd} set protocols pim register-suppress-time \<n\> + +Modify the time that pim will register suppress a FHR will send register +notifications to the kernel. +``` + +```{cfgcmd} set protocols pim rp \<address\> group \<group\> + +In order to use PIM, it is necessary to configure a {abbr}`RP (Rendezvous Point)` +for join messages to be sent to. Currently the only methodology to do this is +via static rendezvous point commands. + +All routers in the PIM network must agree on these values. + +The first ip address is the RP's address and the second value is the matching +prefix of group ranges covered. +``` + +```{cfgcmd} set protocols pim rp keep-alive-timer \<n\> + +Modify the time out value for a S,G flow from 1-65535 seconds at +{abbr}`RP (Rendezvous Point)`. The normal keepalive period for the KAT(S,G) +defaults to 210 seconds. However, at the {abbr}`RP (Rendezvous Point)`, the +keepalive period must be at least the Register_Suppression_Time, or the RP +may time out the (S,G) state before the next Null-Register arrives. +Thus, the KAT(S,G) is set to max(Keepalive_Period, RP_Keepalive_Period) +when a Register-Stop is sent. + +If choosing a value below 31 seconds be aware that some hardware platforms +cannot see data flowing in better than 30 second chunks. + +See {rfc}`7761#section-4.1` for details. +``` + +```{cfgcmd} set protocols pim no-v6-secondary + +When sending PIM hello packets tell PIM to not send any v6 secondary +addresses on the interface. This information is used to allow PIM to use v6 +nexthops in it's decision for {abbr}`RPF (Reverse Path Forwarding)` lookup +if this option is not set (default). +``` + +```{cfgcmd} set protocols pim spt-switchover infinity-and-beyond [prefix-list \<list\>] + +On the last hop router if it is desired to not switch over to the SPT tree +configure this command. + +Optional parameter prefix-list can be use to control which groups to switch or +not switch. If a group is PERMIT as per the prefix-list, then the SPT switchover +does not happen for it and if it is DENY, then the SPT switchover happens. +``` + +```{cfgcmd} set protocols pim ssm prefix-list \<list\> + +Specify a range of group addresses via a prefix-list that forces PIM to never +do {abbr}`SSM (Source-Specific Multicast)` over. +``` + + +### Interface specific commands + +```{cfgcmd} set protocols pim interface \<interface\> bfd [profile \<name\>] + +Automatically create BFD session for each RIP peer discovered in this +interface. When the BFD session monitor signalize that the link is down +the RIP peer is removed and all the learned routes associated with that +peer are removed. + +If optional profile parameter is used, select a BFD profile for the BFD +sessions created via this interface. +``` + +```{cfgcmd} set protocols pim interface \<interface\> dr-priority \<n\> + +Set the {abbr}`DR (Designated Router)` Priority for the interface. +This command is useful to allow the user to influence what node becomes +the DR for a LAN segment. +``` + +```{cfgcmd} set protocols pim interface \<interface\> hello \<n\> + +Set the PIM hello and hold interval for a interface. +``` + +```{cfgcmd} set protocols pim interface \<interface\> no-bsm + +Tell PIM that we would not like to use this interface to process +bootstrap messages. +``` + +```{cfgcmd} set protocols pim interface \<interface\> no-unicast-bsm + +Tell PIM that we would not like to use this interface to process +unicast bootstrap messages. +``` + +```{cfgcmd} set protocols pim interface \<interface\> passive + +Disable sending and receiving PIM control packets on the interface. +``` + +```{cfgcmd} set protocols pim interface \<interface\> source-address \<ip-address\> + +If you have multiple addresses configured on a particular interface and would +like PIM to use a specific source address associated with that interface. +``` + + +## IGMP - Internet Group Management Protocol) + +```{cfgcmd} set protocols pim igmp watermark-warning \<n\> + +Configure watermark warning generation for an IGMP group limit. Generates +warning once the configured group limit is reached while adding new groups. +``` + +(pim-igmp-interface-commands)= + +### Interface specific commands + +```{cfgcmd} set protocols pim interface \<interface\> igmp join \<multicast-address\> source-address \<IP-address\> + +Use this command to allow the selected interface to join a multicast +group defining the multicast address you want to join and the source +IP address too. +``` + +```{cfgcmd} set protocols pim interface \<interface\> igmp query-interval \<seconds\> + +Use this command to configure in the selected interface the IGMP +host query interval (1-1800) in seconds that PIM will use. +``` + +```{cfgcmd} set protocols pim interface \<interface\> igmp query-max-response-time \<n\> + +Use this command to configure in the selected interface the IGMP +query response timeout value (10-250) in deciseconds. If a report is +not returned in the specified time, it will be assumed the (S,G) or +(\*,G) state {rfc}`7761#section-4.1` has timed out. +``` + +```{cfgcmd} set protocols pim interface \<interface\> igmp version \<version-number\> + +Use this command to define in the selected interface whether you +choose IGMP version 2 or 3. + +The default value is 3. +``` + + +#### Example + +In the following example we can see a basic multicast setup: + +```{image} /_static/images/multicast-basic.webp +:align: center +:alt: Network Topology Diagram +:width: 90% +``` + +**Router 1** + +```none +set interfaces ethernet eth2 address '172.16.0.2/24' +set interfaces ethernet eth1 address '100.64.0.1/24' +set protocols ospf area 0 network '172.16.0.0/24' +set protocols ospf area 0 network '100.64.0.0/24' +set protocols igmp interface eth1 +set protocols pim interface eth1 +set protocols pim interface eth2 +set protocols pim rp address 172.16.255.1 group '224.0.0.0/4' +``` + +**Router 3** + +```none +set interfaces dummy dum0 address '172.16.255.1/24' +set interfaces ethernet eth0 address '172.16.0.1/24' +set interfaces ethernet eth1 address '172.16.1.1/24' +set protocols ospf area 0 network '172.16.0.0/24' +set protocols ospf area 0 network '172.16.255.0/24' +set protocols ospf area 0 network '172.16.1.0/24' +set protocols pim interface dum0 +set protocols pim interface eth0 +set protocols pim interface eth1 +set protocols pim rp address 172.16.255.1 group '224.0.0.0/4' +``` + +**Router 2** + +```none +set interfaces ethernet eth1 address '10.0.0.1/24' +set interfaces ethernet eth2 address '172.16.1.2/24' +set protocols ospf area 0 network '10.0.0.0/24' +set protocols ospf area 0 network '172.16.1.0/24' +set protocols pim interface eth1 +set protocols pim interface eth2 +set protocols pim rp address 172.16.255.1 group '224.0.0.0/4' +``` diff --git a/docs/configuration/protocols/pim6.md b/docs/configuration/protocols/pim6.md new file mode 100644 index 00000000..707ae606 --- /dev/null +++ b/docs/configuration/protocols/pim6.md @@ -0,0 +1,100 @@ +(pim6)= + +# PIM6 - Protocol Independent Multicast for IPv6 + +VyOS facilitates IPv6 Multicast by supporting **PIMv6** and **MLD**. + +PIMv6 (Protocol Independent Multicast for IPv6) must be configured in every +interface of every participating router. Every router must also have the +location of the Rendevouz Point manually configured. +Then, unidirectional shared trees rooted at the Rendevouz Point will +automatically be built for multicast distribution. + +Traffic from multicast sources will go to the Rendezvous Point, and receivers +will pull it from a shared tree using MLD (Multicast Listener Discovery). + +Multicast receivers will talk MLD to their local router, so, besides having +PIMv6 configured in every router, MLD must also be configured in any router +where there could be a multicast receiver locally connected. + +VyOS supports both MLD version 1 and version 2 +(which allows source-specific multicast). + +## Basic commands + +These are the commands for a basic setup. + +```{cfgcmd} set protocols pim6 interface \<interface-name\> + + Use this command to enable PIMv6 in the selected interface so that it + can communicate with PIMv6 neighbors. This command also enables MLD reports + and query on the interface unless {cfgcmd}`mld disable` is configured. +``` + + +```{cfgcmd} set protocols pim6 interface \<interface-name\> mld disable + +Disable MLD reports and query on the interface. +``` + + +## Tuning commands + +You can also tune multicast with the following commands. + +```{cfgcmd} set protocols pim6 interface \<interface-name\> mld interval \<seconds\> + +Use this command to configure in the selected interface the MLD +host query interval (1-65535) in seconds that PIM will use. +The default value is 125 seconds. +``` + +```{cfgcmd} set protocols pim6 interface \<interface-name\> mld join \<multicast-address\> + +Use this command to allow the selected interface to join a multicast group. +``` + +```{cfgcmd} set protocols pim6 interface \<interface-name\> mld join \<multicast-address\> source \<source-address\> + +Use this command to allow the selected interface to join a source-specific multicast +group. +``` + +```{cfgcmd} set protocols pim6 interface \<interface-name\> mld last-member-query-count \<count\> + +Set the MLD last member query count. The default value is 2. +``` + +```{cfgcmd} set protocols pim6 interface \<interface-name\> mld last-member-query-interval \<milliseconds\> + +Set the MLD last member query interval in milliseconds (100-6553500). The default value is 1000 milliseconds. +``` + +```{cfgcmd} set protocols pim6 interface \<interface-name\> mld max-response-time \<milliseconds\> + +Set the MLD query response timeout in milliseconds (100-6553500). The default value is 10000 milliseconds. +``` + +```{cfgcmd} set protocols pim6 interface \<interface-name\> mld version \<version-number\> + +Set the MLD version used on this interface. The default value is 2. +``` + + +### Configuration Example + +To enable MLD reports and query on interfaces `eth0` and `eth1`: + +```none +set protocols pim6 interface eth0 +set protocols pim6 interface eth1 +``` + +The following configuration explicitly joins multicast group `ff15::1234` on interface `eth1` +and source-specific multicast group `ff15::5678` with source address `2001:db8::1` on interface +`eth1`: + +```none +set protocols pim6 interface eth0 mld join ff15::1234 +set protocols pim6 interface eth1 mld join ff15::5678 source 2001:db8::1 +``` diff --git a/docs/configuration/protocols/rip.md b/docs/configuration/protocols/rip.md new file mode 100644 index 00000000..684337d6 --- /dev/null +++ b/docs/configuration/protocols/rip.md @@ -0,0 +1,294 @@ +--- +lastproofread: '2021-10-04' +--- + +(rip)= + +# RIP + +{abbr}`RIP (Routing Information Protocol)` is a widely deployed interior gateway +protocol. RIP was developed in the 1970s at Xerox Labs as part of the XNS +routing protocol. RIP is a distance-vector protocol and is based on the +Bellman-Ford algorithms. As a distance-vector protocol, RIP router send updates +to its neighbors periodically, thus allowing the convergence to a known +topology. In each update, the distance to any given network will be broadcast +to its neighboring router. + +Supported versions of RIP are: + +> - RIPv1 as described in {rfc}`1058` +> - RIPv2 as described in {rfc}`2453` + +## General Configuration + +```{cfgcmd} set protocols rip network \<A.B.C.D/M\> + +This command enables RIP and sets the RIP enable interface by NETWORK. +The interfaces which have addresses matching with NETWORK are enabled. +``` + + +```{cfgcmd} set protocols rip interface \<interface\> + +This command specifies a RIP enabled interface by interface name. Both +the sending and receiving of RIP packets will be enabled on the port +specified in this command. +``` + + +```{cfgcmd} set protocols rip neighbor \<A.B.C.D\> + +This command specifies a RIP neighbor. When a neighbor doesn’t understand +multicast, this command is used to specify neighbors. In some cases, not +all routers will be able to understand multicasting, where packets are +sent to a network or a group of addresses. In a situation where a neighbor +cannot process multicast packets, it is necessary to establish a direct +link between routers. +``` + + +```{cfgcmd} set protocols rip passive-interface interface \<interface\> + +This command sets the specified interface to passive mode. On passive mode +interface, all receiving packets are processed as normal and VyOS does not +send either multicast or unicast RIP packets except to RIP neighbors +specified with neighbor command. +``` + + +```{cfgcmd} set protocols rip passive-interface interface default + +This command specifies all interfaces to passive mode. +``` + +## Optional Configuration + +```{cfgcmd} set protocols rip default-distance \<distance\> + +This command change the distance value of RIP. The distance range is 1 to 255. + +> :::{note} +> Routes with a distance of 255 are effectively disabled and not +> installed into the kernel. +> ::: +``` + + +```{cfgcmd} set protocols rip network-distance \<A.B.C.D/M\> distance \<distance\> + +This command sets default RIP distance to a specified value when the routes +source IP address matches the specified prefix. +``` + + +```{cfgcmd} set protocols rip network-distance \<A.B.C.D/M\> access-list \<name\> + +This command can be used with previous command to sets default RIP distance +to specified value when the route source IP address matches the specified +prefix and the specified access-list. +``` + + +```{cfgcmd} set protocols rip default-information originate + +This command generate a default route into the RIP. +``` + + +```{cfgcmd} set protocols rip distribute-list access-list \<in|out\> \<number\> + +This command can be used to filter the RIP path using access lists. +{cfgcmd}`in` and {cfgcmd}`out` this is the direction in which the access +lists are applied. +``` + + +```{cfgcmd} set protocols rip distribute-list interface \<interface\> access-list \<in|out\> \<number\> + +This command allows you apply access lists to a chosen interface to +filter the RIP path. +``` + + +```{cfgcmd} set protocols rip distribute-list prefix-list \<in|out\> \<name\> + +This command can be used to filter the RIP path using prefix lists. +{cfgcmd}`in` and {cfgcmd}`out` this is the direction in which the prefix +lists are applied. +``` + + +```{cfgcmd} set protocols rip distribute-list interface \<interface\> prefix-list \<in|out\> \<name\> + +This command allows you apply prefix lists to a chosen interface to +filter the RIP path. +``` + + +```{cfgcmd} set protocols rip route \<A.B.C.D/M\> + +This command is specific to FRR and VyOS. The route command makes a static +route only inside RIP. This command should be used only by advanced users +who are particularly knowledgeable about the RIP protocol. In most cases, +we recommend creating a static route in VyOS and redistributing it in RIP +using {cfgcmd}`redistribute static`. +``` + + +```{cfgcmd} set protocols rip timers update \<seconds\> + +This command specifies the update timer. Every update timer seconds, the +RIP process is awakened to send an unsolicited response message containing +the complete routing table to all neighboring RIP routers. The time range +is 5 to 2147483647. The default value is 30 seconds. +``` + + +```{cfgcmd} set protocols rip timers timeout \<seconds\> + +This command specifies the timeout timer. Upon expiration of the timeout, +the route is no longer valid; however, it is retained in the routing table +for a short time so that neighbors can be notified that the route has been +dropped. The time range is 5 to 2147483647. The default value is 180 +seconds. +``` + + +```{cfgcmd} set protocols rip timers garbage-collection \<seconds\> + +This command specifies the garbage-collection timer. Upon expiration of +the garbage-collection timer, the route is finally removed from the +routing table. The time range is 5 to 2147483647. The default value is 120 +seconds. +``` + +## Redistribution Configuration + +```{cfgcmd} set protocols rip redistribute \<route source\> + +This command redistributes routing information from the given route source +into the RIP tables. There are five modes available for route source: bgp, +connected, kernel, ospf, static. +``` + + +```{cfgcmd} set protocols rip redistribute \<route source\> metric \<metric\> + +This command specifies metric for redistributed routes from the given route +source. There are five modes available for route source: bgp, connected, +kernel, ospf, static. The metric range is 1 to 16. +``` + + +```{cfgcmd} set protocols rip redistribute \<route source\> route-map \<name\> + +This command allows to use route map to filter redistributed routes from +the given route source. There are five modes available for route source: +bgp, connected, kernel, ospf, static. +``` + + +```{cfgcmd} set protocols rip default-metric \<metric\> + +This command modifies the default metric (hop count) value for redistributed +routes. The metric range is 1 to 16. The default value is 1. This command +does not affect connected route even if it is redistributed by +{cfgcmd}`redistribute connected`. To modify connected routes metric +value, please use {cfgcmd}`redistribute connected metric`. +``` + +## Interfaces Configuration + +```{cfgcmd} set interfaces \<inttype\> \<intname\> ip rip authentication plaintext-password \<text\> + +This command sets the interface with RIP simple password authentication. +This command also sets authentication string. The string must be shorter +than 16 characters. +``` + + +```{cfgcmd} set interfaces \<inttype\> \<intname\> ip rip authentication md5 \<id\> password \<text\> + +This command sets the interface with RIP MD5 authentication. This command +also sets MD5 Key. The key must be shorter than 16 characters. +``` + + +```{cfgcmd} set interfaces \<inttype\> \<intname\> ip rip split-horizon disable + +This command disables split-horizon on the interface. By default, VyOS does +not advertise RIP routes out the interface over which they were learned +(split horizon).3 +``` + + +```{cfgcmd} set interfaces \<inttype\> \<intname\> ip rip split-horizon poison-reverse + +This command enables poison-reverse on the interface. If both poison reverse +and split horizon are enabled, then VyOS advertises the learned routes +as unreachable over the interface on which the route was learned. +``` + +## Operational Mode Commands + +```{opcmd} show ip rip + +This command displays RIP routes. +``` +```none +Codes: R - RIP, C - connected, S - Static, O - OSPF, B - BGP +Sub-codes: + (n) - normal, (s) - static, (d) - default, (r) - redistribute, + (i) - interface + + Network Next Hop Metric From Tag Time +C(i) 10.0.12.0/24 0.0.0.0 1 self 0 +C(i) 10.0.13.0/24 0.0.0.0 1 self 0 +R(n) 10.0.23.0/24 10.0.12.2 2 10.0.12.2 0 02:53 +``` + +```{opcmd} show ip rip status + +The command displays current RIP status. It includes RIP timer, filtering, +version, RIP enabled interface and RIP peer information. +``` +```none +Routing Protocol is "rip" + Sending updates every 30 seconds with +/-50%, next due in 11 seconds + Timeout after 180 seconds, garbage collect after 120 seconds + Outgoing update filter list for all interface is not set + Incoming update filter list for all interface is not set + Default redistribution metric is 1 + Redistributing: + Default version control: send version 2, receive any version + Interface Send Recv Key-chain + eth0 2 1 2 + eth2 2 1 2 + Routing for Networks: + 10.0.12.0/24 + eth0 + Routing Information Sources: + Gateway BadPackets BadRoutes Distance Last Update + 10.0.12.2 0 0 120 00:00:11 + Distance: (default is 120) +``` + +## Configuration Example + +Simple RIP configuration using 2 nodes and redistributing connected interfaces. + +**Node 1:** + +```none +set interfaces loopback address 10.1.1.1/32 +set protocols rip network 192.168.0.0/24 +set protocols rip redistribute connected +``` + +**Node 2:** + +```none +set interfaces loopback address 10.2.2.2/32 +set protocols rip network 192.168.0.0/24 +set protocols rip redistribute connected +``` diff --git a/docs/configuration/protocols/rpki.md b/docs/configuration/protocols/rpki.md new file mode 100644 index 00000000..1f4cf5bf --- /dev/null +++ b/docs/configuration/protocols/rpki.md @@ -0,0 +1,210 @@ +(rpki)= + +# RPKI + +:::{pull-quote} + +There are two types of Network Admins who deal with BGP, those who have +created an international incident and/or outage, and those who are lying + +-- [tweet by EvilMog](https://twitter.com/Evil_Mog/status/1230924170508169216), 2020-02-21 +::: + +{abbr}`RPKI (Resource Public Key Infrastructure)` is a framework designed to +secure the Internet routing infrastructure. It associates BGP route +announcements with the correct originating {abbr}`ASN (Autonomus System +Number)` which BGP routers can then use to check each route against the +corresponding {abbr}`ROA (Route Origin Authorisation)` for validity. RPKI is +described in {rfc}`6480`. + +A BGP-speaking router like VyOS can retrieve ROA information from RPKI +"Relying Party software" (often just called an "RPKI server" or "RPKI +validator") by using {abbr}`RTR (RPKI to Router)` protocol. There are several +open source implementations to choose from, such as NLNetLabs' [Routinator] +(written in Rust), OpenBSD's [rpki-client] (written in C), and [StayRTR] (written +in Go). The RTR protocol is described in {rfc}`8210`. + +:::{tip} +If you are new to these routing security technologies then there is an +[excellent guide to RPKI] by NLnet Labs which will get you up to speed +very quickly. Their documentation explains everything from what RPKI is to +deploying it in production. It also has some +[help and operational guidance] including "What can I do about my route +having an Invalid state?" +::: + +## Getting started + +First you will need to deploy an RPKI validator for your routers to use. NLnet +Labs provides a collection of [software] you can compare and settle on one. +Once your server is running you can start validating announcements. + +Imported prefixes during the validation may have values: + +> valid +> +> : The prefix and ASN that originated it match a signed ROA. These are +> probably trustworthy route announcements. +> +> invalid +> +> : The prefix or prefix length and ASN that originated it doesn't +> match any existing ROA. This could be the result of a prefix hijack, or +> merely a misconfiguration, but should probably be treated as +> untrustworthy route announcements. +> +> notfound +> +> : No ROA exists which covers that prefix. Unfortunately this is the case for +> about 40%-50% of the prefixes which were announced to the {abbr}`DFZ +> (default-free zone)` at the start of 2024. + +:::{note} +If you are responsible for the global addresses assigned to your +network, please make sure that your prefixes have ROAs associated with them +to avoid being `notfound` by RPKI. For most ASNs this will involve +publishing ROAs via your {abbr}`RIR (Regional Internet Registry)` (RIPE +NCC, APNIC, ARIN, LACNIC, or AFRINIC), and is something you are encouraged +to do whenever you plan to announce addresses into the DFZ. + +Particularly large networks may wish to run their own RPKI certificate +authority and publication server instead of publishing ROAs via their RIR. +This is a subject far beyond the scope of VyOS' documentation. Consider +reading about [Krill] if this is a rabbit hole you need or especially want +to dive down. +::: + +### Features of the Current Implementation + +In a nutshell, the current implementation provides the following features: + +- The BGP router can connect to one or more RPKI cache servers to receive + validated prefix to origin AS mappings. Advanced failover can be implemented + by server sockets with different preference values. +- If no connection to an RPKI cache server can be established after a + pre-defined timeout, the router will process routes without prefix origin + validation. It still will try to establish a connection to an RPKI cache + server in the background. +- By default, enabling RPKI does not change best path selection. In particular, + invalid prefixes will still be considered during best path selection. However, + the router can be configured to ignore all invalid prefixes. +- Route maps can be configured to match a specific RPKI validation state. This + allows the creation of local policies, which handle BGP routes based on the + outcome of the Prefix Origin Validation. +- Updates from the RPKI cache servers are directly applied and path selection is + updated accordingly. (Soft reconfiguration must be enabled for this to work). + +## Configuration + +```{cfgcmd} set protocols rpki polling-period \<1-86400\> + +Define the time interval to update the local cache + +The default value is 300 seconds. +``` + +```{cfgcmd} set protocols rpki expire-interval \<600-172800\> + +Set the number of seconds the router waits until the router +expires the cache. + +The default value is 7200 seconds. +``` + +```{cfgcmd} set protocols rpki retry-interval \<1-7200\> + +Set the number of seconds the router waits until retrying to connect +to the cache server. + +The default value is 600 seconds. +``` + +```{cfgcmd} set protocols rpki cache \<address\> port \<port\> + +Defined the IPv4, IPv6 or FQDN and port number of the caching RPKI caching +instance which is used. + +This is a mandatory setting. +``` + +```{cfgcmd} set protocols rpki cache \<address\> preference \<preference\> + +Multiple RPKI caching instances can be supplied and they need a preference in +which their result sets are used. + +This is a mandatory setting. +``` + + +### SSH + +Connections to the RPKI caching server can not only be established by TCP using +the RTR protocol but you can also rely on a secure SSH session to the server. +This provides transport integrity and confidentiality and it is a good idea if +your validation software supports it. To enable SSH, first you need to create +an SSH client keypair using `generate ssh client-key +/config/auth/id_rsa_rpki`. Once your key is created you can setup the +connection. + +```{cfgcmd} set protocols rpki cache \<address\> ssh username \<user\> + +SSH username to establish an SSH connection to the cache server. +``` + +```{cfgcmd} set protocols rpki cache \<address\> ssh private-key-file \<filepath\> + +Local path that includes the private key file of the router. +``` + +```{cfgcmd} set protocols rpki cache \<address\> ssh public-key-file \<filepath\> + +Local path that includes the public key file of the router. +``` + +:::{note} +When using SSH, private-key-file and public-key-file +are mandatory options. +::: + +## Example + +We can build route-maps for import based on these states. Here is a simple +RPKI configuration, where `routinator` is the RPKI-validating "cache" +server with ip `192.0.2.1`: + +```none +set protocols rpki cache 192.0.2.1 port '3323' +set protocols rpki cache 192.0.2.1 preference '1' +``` + +Here is an example route-map to apply to routes learned at import. In this +filter we reject prefixes with the state `invalid`, and set a higher +`local-preference` if the prefix is RPKI `valid` rather than merely +`notfound`. + +```none +set policy route-map ROUTES-IN rule 10 action 'permit' +set policy route-map ROUTES-IN rule 10 match rpki 'valid' +set policy route-map ROUTES-IN rule 10 set local-preference '300' +set policy route-map ROUTES-IN rule 20 action 'permit' +set policy route-map ROUTES-IN rule 20 match rpki 'notfound' +set policy route-map ROUTES-IN rule 20 set local-preference '125' +set policy route-map ROUTES-IN rule 30 action 'deny' +set policy route-map ROUTES-IN rule 30 match rpki 'invalid' +``` + +Once your routers are configured to reject RPKI-invalid prefixes, you can +test whether the configuration is working correctly using Cloudflare's [test] +website. Keep in mind that in order for this to work, you need to have no +default routes or anything else that would still send traffic to RPKI-invalid +destinations. + +[excellent guide to rpki]: https://rpki.readthedocs.io/ +[help and operational guidance]: https://rpki.readthedocs.io/en/latest/about/help.html +[krill]: https://www.nlnetlabs.nl/projects/rpki/krill/ +[routinator]: https://www.nlnetlabs.nl/projects/rpki/routinator/ +[rpki-client]: https://www.rpki-client.org/ +[software]: https://rpki.readthedocs.io/en/latest/ops/tools.html#relying-party-software +[stayrtr]: https://github.com/bgp/stayrtr/ +[test]: https://isbgpsafeyet.com/ +[tweet by evilmog]: <https://twitter.com/Evil_Mog/status/1230924170508169216> diff --git a/docs/configuration/protocols/arp.rst b/docs/configuration/protocols/rst-arp.rst index 00865104..00865104 100644 --- a/docs/configuration/protocols/arp.rst +++ b/docs/configuration/protocols/rst-arp.rst diff --git a/docs/configuration/protocols/babel.rst b/docs/configuration/protocols/rst-babel.rst index 95543da2..95543da2 100644 --- a/docs/configuration/protocols/babel.rst +++ b/docs/configuration/protocols/rst-babel.rst diff --git a/docs/configuration/protocols/bfd.rst b/docs/configuration/protocols/rst-bfd.rst index 30876efc..30876efc 100644 --- a/docs/configuration/protocols/bfd.rst +++ b/docs/configuration/protocols/rst-bfd.rst diff --git a/docs/configuration/protocols/bgp.rst b/docs/configuration/protocols/rst-bgp.rst index 736cb4cc..736cb4cc 100644 --- a/docs/configuration/protocols/bgp.rst +++ b/docs/configuration/protocols/rst-bgp.rst diff --git a/docs/configuration/protocols/failover.rst b/docs/configuration/protocols/rst-failover.rst index c479649e..c479649e 100644 --- a/docs/configuration/protocols/failover.rst +++ b/docs/configuration/protocols/rst-failover.rst diff --git a/docs/configuration/protocols/igmp-proxy.rst b/docs/configuration/protocols/rst-igmp-proxy.rst index f62a289e..f62a289e 100644 --- a/docs/configuration/protocols/igmp-proxy.rst +++ b/docs/configuration/protocols/rst-igmp-proxy.rst diff --git a/docs/configuration/protocols/index.rst b/docs/configuration/protocols/rst-index.rst index d40a4b12..d40a4b12 100644 --- a/docs/configuration/protocols/index.rst +++ b/docs/configuration/protocols/rst-index.rst diff --git a/docs/configuration/protocols/isis.rst b/docs/configuration/protocols/rst-isis.rst index 75634800..75634800 100644 --- a/docs/configuration/protocols/isis.rst +++ b/docs/configuration/protocols/rst-isis.rst diff --git a/docs/configuration/protocols/mpls.rst b/docs/configuration/protocols/rst-mpls.rst index 550473d7..550473d7 100644 --- a/docs/configuration/protocols/mpls.rst +++ b/docs/configuration/protocols/rst-mpls.rst diff --git a/docs/configuration/protocols/multicast.rst b/docs/configuration/protocols/rst-multicast.rst index 61a04e5e..61a04e5e 100644 --- a/docs/configuration/protocols/multicast.rst +++ b/docs/configuration/protocols/rst-multicast.rst diff --git a/docs/configuration/protocols/openfabric.rst b/docs/configuration/protocols/rst-openfabric.rst index aecb5181..aecb5181 100644 --- a/docs/configuration/protocols/openfabric.rst +++ b/docs/configuration/protocols/rst-openfabric.rst diff --git a/docs/configuration/protocols/ospf.rst b/docs/configuration/protocols/rst-ospf.rst index ac0ed160..ac0ed160 100644 --- a/docs/configuration/protocols/ospf.rst +++ b/docs/configuration/protocols/rst-ospf.rst diff --git a/docs/configuration/protocols/pim.rst b/docs/configuration/protocols/rst-pim.rst index f3f388ba..f3f388ba 100644 --- a/docs/configuration/protocols/pim.rst +++ b/docs/configuration/protocols/rst-pim.rst diff --git a/docs/configuration/protocols/pim6.rst b/docs/configuration/protocols/rst-pim6.rst index 2b2276a7..2b2276a7 100644 --- a/docs/configuration/protocols/pim6.rst +++ b/docs/configuration/protocols/rst-pim6.rst diff --git a/docs/configuration/protocols/rip.rst b/docs/configuration/protocols/rst-rip.rst index fd20a90c..fd20a90c 100644 --- a/docs/configuration/protocols/rip.rst +++ b/docs/configuration/protocols/rst-rip.rst diff --git a/docs/configuration/protocols/rpki.rst b/docs/configuration/protocols/rst-rpki.rst index 17557884..17557884 100644 --- a/docs/configuration/protocols/rpki.rst +++ b/docs/configuration/protocols/rst-rpki.rst diff --git a/docs/configuration/protocols/segment-routing.rst b/docs/configuration/protocols/rst-segment-routing.rst index 5ee710e9..5ee710e9 100644 --- a/docs/configuration/protocols/segment-routing.rst +++ b/docs/configuration/protocols/rst-segment-routing.rst diff --git a/docs/configuration/protocols/static.rst b/docs/configuration/protocols/rst-static.rst index eb5a439c..eb5a439c 100644 --- a/docs/configuration/protocols/static.rst +++ b/docs/configuration/protocols/rst-static.rst diff --git a/docs/configuration/protocols/traffic-engineering.rst b/docs/configuration/protocols/rst-traffic-engineering.rst index 977a5e5c..977a5e5c 100644 --- a/docs/configuration/protocols/traffic-engineering.rst +++ b/docs/configuration/protocols/rst-traffic-engineering.rst diff --git a/docs/configuration/protocols/segment-routing.md b/docs/configuration/protocols/segment-routing.md new file mode 100644 index 00000000..af47d343 --- /dev/null +++ b/docs/configuration/protocols/segment-routing.md @@ -0,0 +1,359 @@ +(segment-routing)= + +# Segment Routing + +Segment Routing (SR) is a network architecture that is similar to source-routing +. In this architecture, the ingress router adds a list of segments, known as +SIDs, to the packet as it enters the network. These segments represent different +portions of the network path that the packet will take. + +The SR segments are portions of the network path taken by the packet, and are +called SIDs. At each node, the first SID of the list is read, executed as a +forwarding function, and may be popped to let the next node read the next SID of +the list. The SID list completely determines the path where the packet is +forwarded. + +Segment Routing can be applied to an existing MPLS-based data plane and defines +a control plane network architecture. In MPLS networks, segments are encoded as +MPLS labels and are added at the ingress router. These MPLS labels are then +exchanged and populated by Interior Gateway Protocols (IGPs) like IS-IS or OSPF +which are running on most ISPs. + +:::{note} +Segment routing defines a control plane network architecture and +can be applied to an existing MPLS based dataplane. In the MPLS networks, +segments are encoded as MPLS labels and are imposed at the ingress router. +MPLS labels are exchanged and populated by IGPs like IS-IS.Segment Routing +as per RFC8667 for MPLS dataplane. It supports IPv4, IPv6 and ECMP and has +been tested against Cisco & Juniper routers.however,this deployment is still +EXPERIMENTAL for FRR. +::: + +## IS-IS SR Configuration + +Segment routing (SR) is used by the IGP protocols to interconnect network +devices, below configuration shows how to enable SR on IS-IS: + +:::{note} +``Known limitations:`` + +No support for level redistribution (L1 to L2 or L2 to L1) + +No support for binding SID + +No support for SRLB + +Only one SRGB and default SPF Algorithm is supported +::: + +```{cfgcmd} set protocols isis segment-routing global-block high-label-value \<label-value\> + +Set the Segment Routing Global Block i.e. the label range used by MPLS to +store label in the MPLS FIB for Prefix SID. Note that the block size may +not exceed 65535. +``` + + +```{cfgcmd} set protocols isis segment-routing global-block low-label-value \<label-value\> + +Set the Segment Routing Global Block i.e. the low label range used by MPLS to +store label in the MPLS FIB for Prefix SID. Note that the block size may +not exceed 65535. +``` + + +```{cfgcmd} set protocols isis segment-routing local-block high-label-value \<label-value\> + +Set the Segment Routing Local Block i.e. the label range used by MPLS to +store label in the MPLS FIB for Prefix SID. Note that the block size may +not exceed 65535.Segment Routing Local Block, The negative command always +unsets both. +``` + + +```{cfgcmd} set protocols isis segment-routing local-block \<low-label-value \<label-value\> + +Set the Segment Routing Local Block i.e. the low label range used by MPLS to +store label in the MPLS FIB for Prefix SID. Note that the block size may +not exceed 65535.Segment Routing Local Block, The negative command always +unsets both. +``` + + +```{cfgcmd} set protocols isis segment-routing maximum-label-depth \<1-16\> + +Set the Maximum Stack Depth supported by the router. The value depend of +the MPLS dataplane. +``` + + +```{cfgcmd} set protocols isis segment-routing prefix \<address\> index value \<0-65535\> + +A segment ID that contains an IP address prefix calculated by an IGP in the +service provider core network. Prefix SIDs are globally unique, this value +identify it +``` + + +```{cfgcmd} set protocols isis segment-routing prefix \<address\> index \<no-php-flag | explicit-null| n-flag-clear\> + +this option allows to configure prefix-sid on SR. The ‘no-php-flag’ means NO +Penultimate Hop Popping that allows SR node to request to its neighbor to +not pop the label. The ‘explicit-null’ flag allows SR node to request to its +neighbor to send IP packet with the EXPLICIT-NULL label. The ‘n-flag-clear’ +option can be used to explicitly clear the Node flag that is set by default +for Prefix-SIDs associated to loopback addresses. This option is necessary +to configure Anycast-SIDs. +``` + +```{opcmd} show isis segment-routing node + + Show detailed information about all learned Segment Routing Nodes +``` + + +```{opcmd} show isis route prefix-sid + +Show detailed information about prefix-sid and label learned +``` + +:::{note} +more information related IGP - {ref}`routing-isis` +::: + + +## OSPF SR Configuration + + +Segment routing (SR) is used by the IGP protocols to interconnect network +devices, below configuration shows how to enable SR on OSPF: + +```{cfgcmd} set protocols ospf parameters opaque-lsa + +Enable the Opaque-LSA capability (rfc2370), necessary to transport label +on IGP +``` + +```{cfgcmd} set protocols ospf segment-routing global-block high-label-value \<label-value\> + +Set the Segment Routing Global Block i.e. the label range used by MPLS to +store label in the MPLS FIB for Prefix SID. Note that the block size may +not exceed 65535. +``` + +```{cfgcmd} set protocols ospf segment-routing global-block low-label-value \<label-value\> + +Set the Segment Routing Global Block i.e. the low label range used by MPLS to +store label in the MPLS FIB for Prefix SID. Note that the block size may +not exceed 65535. +``` + +```{cfgcmd} set protocols ospf segment-routing local-block high-label-value \<label-value\> + +Set the Segment Routing Local Block i.e. the label range used by MPLS to +store label in the MPLS FIB for Prefix SID. Note that the block size may +not exceed 65535.Segment Routing Local Block, The negative command always +unsets both. +``` + +```{cfgcmd} set protocols ospf segment-routing local-block \<low-label-value \<label-value\> + +Set the Segment Routing Local Block i.e. the low label range used by MPLS to +store label in the MPLS FIB for Prefix SID. Note that the block size may +not exceed 65535.Segment Routing Local Block, The negative command always +unsets both. +``` + +```{cfgcmd} set protocols ospf segment-routing maximum-label-depth \<1-16\> + +Set the Maximum Stack Depth supported by the router. The value depend of +the MPLS dataplane. +``` + +```{cfgcmd} set protocols ospf segment-routing prefix \<address\> index value \<0-65535\> + +A segment ID that contains an IP address prefix calculated by an IGP in the +service provider core network. Prefix SIDs are globally unique, this value +identify it +``` + +```{cfgcmd} set protocols ospf segment-routing prefix \<address\> index \<no-php-flag | explicit-null| n-flag-clear\> + +this option allows to configure prefix-sid on SR. The ‘no-php-flag’ means NO +Penultimate Hop Popping that allows SR node to request to its neighbor to +not pop the label. The ‘explicit-null’ flag allows SR node to request to its +neighbor to send IP packet with the EXPLICIT-NULL label. The ‘n-flag-clear’ +option can be used to explicitly clear the Node flag that is set by default +for Prefix-SIDs associated to loopback addresses. This option is necessary +to configure Anycast-SIDs. +``` + +:::{note} +more information related IGP - {ref}`routing-ospf` +::: + +## Configuration Example + +we described the configuration SR ISIS / SR OSPF using 2 connected with them to +share label information. + +### Enable IS-IS with Segment Routing (Experimental) + +**Node 1:** + +```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:** + +```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: + +```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: + +```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 +``` + + +### Enable OSPF with Segment Routing (Experimental): + +**Node 1** + +```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** + +```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: + +```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: + +```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 +``` diff --git a/docs/configuration/protocols/static.md b/docs/configuration/protocols/static.md new file mode 100644 index 00000000..357f7076 --- /dev/null +++ b/docs/configuration/protocols/static.md @@ -0,0 +1,298 @@ +(routing-static)= + +# Static + +Static routes are manually configured routes, which, in general, cannot be +updated dynamically from information VyOS learns about the network topology from +other routing protocols. However, if a link fails, the router will remove +routes, including static routes, from the {abbr}`RIPB (Routing Information +Base)` that used this interface to reach the next hop. In general, static +routes should only be used for very simple network topologies, or to override +the behavior of a dynamic routing protocol for a small number of routes. The +collection of all routes the router has learned from its configuration or from +its dynamic routing protocols is stored in the RIB. Unicast routes are directly +used to determine the forwarding table used for unicast packet forwarding. + +## IPv4 Unicast Routes + +```{cfgcmd} set protocols static route \<subnet\> next-hop \<address\> + +Configure next-hop *\<address\>* for an IPv4 static route. Multiple static +routes can be created. +``` + +```{cfgcmd} set protocols static route \<subnet\> next-hop \<address\> disable + +Disable this IPv4 static route entry. +``` + +```{cfgcmd} set protocols static route \<subnet\> next-hop \<address\> distance \<distance\> + +Defines next-hop distance for this route, routes with smaller administrative +distance are elected prior to those with a higher distance. + +Range is 1 to 255, default is 1. + +:::{note} +Routes with a distance of 255 are effectively disabled and not +installed into the kernel. +::: +``` + + +### IPv4 Interface Routes + +```{cfgcmd} set protocols static route \<subnet\> interface \<interface\> + +Allows you to configure the next-hop interface for an interface-based IPv4 +static route. *\<interface\>* will be the next-hop interface where traffic is +routed for the given *\<subnet\>*. +``` + +```{cfgcmd} set protocols static route \<subnet\> interface \<interface\> disable + +Disables interface-based IPv4 static route. +``` + +```{cfgcmd} set protocols static route \<subnet\> interface \<interface\> distance \<distance\> + +Defines next-hop distance for this route, routes with smaller administrative +distance are elected prior to those with a higher distance. + +Range is 1 to 255, default is 1. +``` + + +### IPv4 BFD + +```{cfgcmd} set protocols static route \<subnet\> next-hop \<address\> bfd + +Configure a static route for *\<subnet\>* using gateway *\<address\>* and use the +gateway address as BFD peer destination address. +``` + +```{cfgcmd} set protocols static route \<subnet\> next-hop \<address\> bfd profile \<profile\> + +Configure a static route for *\<subnet\>* using gateway *\<address\>* and use the +gateway address as BFD peer destination address with BFD profile *\<profile\>*. +``` + +```{cfgcmd} set protocols static route \<subnet\> next-hop \<address\> bfd multi-hop source-address \<source-address\> + +Configure a static route for *\<subnet\>* using gateway *\<address\>* and use the +gateway address as BFD peer destination address with source address +*\<source\>* but initiate a multi-hop session. +``` + + +### DHCP Interface Routes + +```{cfgcmd} set protocols static route \<subnet\> dhcp-interface \<interface\> + +Defines route with DHCP interface supplying next-hop IP address. +``` + + +### IPv4 Reject Routes + +```{cfgcmd} set protocol static route \<subnet\> reject + +Defines route which emits an ICMP unreachable when matched. +``` + +```{cfgcmd} set protocols static route \<subnet\> reject distance \<distance\> + +Defines distance for this route, routes with smaller administrative +distance are elected prior to those with a higher distance. +``` + +```{cfgcmd} set protocols static route \<subnet\> reject tag \<tag\> + +Sets a tag for this route. +``` + +```{cfgcmd} set protocol static route6 \<subnet\> reject + +Defines route which emits an ICMP unreachable when matched. +``` + + +### IPv4 Blackhole Routes + +```{cfgcmd} set protocols static route \<subnet\> blackhole + +Use this command to configure a "black-hole" route on the router. A +black-hole route is a route for which the system silently discard packets +that are matched. This prevents networks leaking out public interfaces, but +it does not prevent them from being used as a more specific route inside your +network. +``` + +```{cfgcmd} set protocols static route \<subnet\> blackhole distance \<distance\> + +Defines blackhole distance for this route, routes with smaller administrative +distance are elected prior to those with a higher distance. +``` + +```{cfgcmd} set protocols static route \<subnet\> blackhole tag \<tag\> + +Sets a tag for this route. +``` + + +## IPv6 Unicast Routes + +```{cfgcmd} set protocols static route6 \<subnet\> next-hop \<address\> + +Configure next-hop *\<address\>* for an IPv6 static route. Multiple static +routes can be created. +``` + +```{cfgcmd} set protocols static route6 \<subnet\> next-hop \<address\> disable + +Disable this IPv6 static route entry. +``` + +```{cfgcmd} set protocols static route6 \<subnet\> next-hop \<address\> distance \<distance\> + +Defines next-hop distance for this route, routes with smaller administrative +distance are elected prior to those with a higher distance. + +Range is 1 to 255, default is 1. + +:::{note} +Routes with a distance of 255 are effectively disabled and not +installed into the kernel. +::: +``` + +```{cfgcmd} set protocols static route6 \<subnet\> next-hop \<address\> segments \<segments\> + +It is possible to specify a static route for ipv6 prefixes using an +SRv6 segments instruction. The ``/`` separator can be used to specify +multiple segment instructions. + +Example: + +:::{code-block} none +set protocols static route6 2001:db8:1000::/36 next-hop 2001:db8:201::ffff segments '2001:db8:aaaa::7/2002::4/2002::3/2002::2' +::: + +:::{code-block} none +vyos@vyos:~$ show ipv6 route +Codes: K - kernel route, C - connected, S - static, R - RIPng, + O - OSPFv3, I - IS-IS, B - BGP, 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 +C>* 2001:db8:201::/64 is directly connected, eth0.201, 00:00:46 +S>* 2001:db8:1000::/36 [1/0] via 2001:db8:201::ffff, eth0.201, seg6 2001:db8:aaaa::7,2002::4,2002::3,2002::2, weight 1, 00:00:08 +::: +``` + + +### IPv6 Interface Routes + +```{cfgcmd} set protocols static route6 \<subnet\> interface \<interface\> + +Allows you to configure the next-hop interface for an interface-based IPv6 +static route. *\<interface\>* will be the next-hop interface where traffic is +routed for the given *\<subnet\>*. +``` + +```{cfgcmd} set protocols static route6 \<subnet\> interface \<interface\> disable + +Disables interface-based IPv6 static route. +``` + +```{cfgcmd} set protocols static route6 \<subnet\> interface \<interface\> distance \<distance\> + +Defines next-hop distance for this route, routes with smaller administrative +distance are elected prior to those with a higher distance. + +Range is 1 to 255, default is 1. +``` + +```{cfgcmd} set protocols static route6 \<subnet\> interface \<interface\> segments \<segments\> + +It is possible to specify a static route for ipv6 prefixes using an +SRv6 segments instruction. The ``/`` separator can be used to specify +multiple segment instructions. + +Example: + +:::{code-block} none +set protocols static route6 2001:db8:1000::/36 interface eth0 segments '2001:db8:aaaa::7/2002::4/2002::3/2002::2' +::: +``` + + +### IPv6 BFD + +```{cfgcmd} set protocols static route6 \<subnet\> next-hop \<address\> bfd + +Configure a static route for *\<subnet\>* using gateway *\<address\>* and use the +gateway address as BFD peer destination address. +``` + +```{cfgcmd} set protocols static route6 \<subnet\> next-hop \<address\> bfd profile \<profile\> + +Configure a static route for *\<subnet\>* using gateway *\<address\>* and use the +gateway address as BFD peer destination address with BFD profile *\<profile\>*. +``` + +```{cfgcmd} set protocols static route6 \<subnet\> next-hop \<address\> bfd multi-hop source-address \<source\> + +Configure a static route for *\<subnet\>* using gateway *\<address\>* and use the +gateway address as BFD peer destination address with source address +*\<source\>* but initiate a multi-hop session. +``` + + +### IPv6 Reject Routes + +```{cfgcmd} set protocol static route6 \<subnet\> reject + +Defines route which emits an ICMP unreachable when matched. +``` + +```{cfgcmd} set protocols static route6 \<subnet\> reject distance \<distance\> + +Defines distance for this route, routes with smaller administrative +distance are elected prior to those with a higher distance. +``` + +```{cfgcmd} set protocols static route6 \<subnet\> reject tag \<tag\> + +Sets a tag for this route. +``` + + +### IPv6 Blackhole Routes + +```{cfgcmd} set protocols static route6 \<subnet\> blackhole + +Use this command to configure a "black-hole" route on the router. A +black-hole route is a route for which the system silently discard packets +that are matched. This prevents networks leaking out public interfaces, but +it does not prevent them from being used as a more specific route inside your +network. +``` + +```{cfgcmd} set protocols static route6 \<subnet\> blackhole distance \<distance\> + +Defines blackhole distance for this route, routes with smaller administrative +distance are elected prior to those with a higher distance. +``` + +```{cfgcmd} set protocols static route6 \<subnet\> blackhole tag \<tag\> + +Sets a tag for this route. +``` + + +## Alternate Routing Tables + +Alternate routing tables are used with policy based routing by utilizing +{ref}`vrf`. diff --git a/docs/configuration/protocols/traffic-engineering.md b/docs/configuration/protocols/traffic-engineering.md new file mode 100644 index 00000000..832023a7 --- /dev/null +++ b/docs/configuration/protocols/traffic-engineering.md @@ -0,0 +1,54 @@ +(traffic-engineering)= + +# Traffic Engineering + +Traffic Engineering (TE) is possibility to send traffic from node to node using +alternative path. + +## Common link parameters + +Traffic Engineering parameters are used for both IS-IS and OSPF (not supported yet). + +```{cfgcmd} set protocols traffic-engineering admin-group \<admin-group-name\> bit-position \<bit-position-value\> + +Create Administrative group and assosiate bit position with it. These groups can be +used in the following commands. + +\<bit-position-value\> can have value 0-31. There cannot be two groups with same bit position. +``` + + +```{cfgcmd} set protocols traffic-engineering interface \<ifname\> admin-group \<admin-group-name\> + +Set administrative group for interface \<ifname\>. Multiple values can be provided. +``` + + +```{cfgcmd} set protocols traffic-engineering interface \<ifname\> max-bandwidth \<max-bandwidth-value-mbps\> + +Set maximum bandwidth for interface \<ifname\>. Value given in Mbits per second. +``` + + +```{cfgcmd} set protocols traffic-engineering interface \<ifname\> max-reservable-bandwidth \<max-reservable-bandwidth-value-mbps\> + +Set maximum reservable bandwidth for interface \<ifname\>. Value given in Mbits per second. +``` + +## IS-IS TE Configuration + +Traffic Engineering (TE) can be enabled and exported for IS-IS +using the following commands: + +```{cfgcmd} set protocols isis traffic-engineering enable + +Enable Traffic Engineering for IS-IS. +``` +```{cfgcmd} set protocols isis traffic-engineering export + +Export Traffic Engineering data to neighbors. +``` +```{cfgcmd} set protocols isis traffic-engineering address \<ipv4-address\> + +Configure IPv4 address for MPLS-TE. +```
\ No newline at end of file diff --git a/docs/configuration/index.rst b/docs/configuration/rst-index.rst index f86365a9..f86365a9 100644 --- a/docs/configuration/index.rst +++ b/docs/configuration/rst-index.rst diff --git a/docs/configuration/service/broadcast-relay.md b/docs/configuration/service/broadcast-relay.md new file mode 100644 index 00000000..4202ad6b --- /dev/null +++ b/docs/configuration/service/broadcast-relay.md @@ -0,0 +1,70 @@ +(udp-broadcast-relay)= + +# UDP Broadcast Relay + +Certain vendors use broadcasts to identify their equipment within one ethernet +segment. Unfortunately if you split your network with multiple VLANs you loose +the ability of identifying your equipment. + +This is where "UDP broadcast relay" comes into play! It will forward received +broadcasts to other configured networks. + +Every UDP port which will be forward requires one unique ID. Currently we +support 99 IDs! + +## Configuration + +```{cfgcmd} set service broadcast-relay id \<n\> description \<description\> + +A description can be added for each and every unique relay ID. This is +useful to distinguish between multiple different ports/applications. +``` + +```{cfgcmd} set service broadcast-relay id \<n\> interface \<interface\> + +The interface used to receive and relay individual broadcast packets. If you +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 application. It is mandatory for this kind +of operation. +``` + +```{cfgcmd} set service broadcast-relay id \<n\> disable + +Each broadcast relay instance can be individually disabled without deleting +the configured node by using the following command: +``` + +```{cfgcmd} set service broadcast-relay disable + +In addition you can also disable the whole service without the need to remove +it from the current configuration. +``` + +:::{note} +You can run the UDP broadcast relay service on multiple routers +connected to a subnet. There is **NO** UDP broadcast relay packet storm! +::: + +## Example + +To forward all broadcast packets received on `UDP port 1900` on `eth3`, `eth4` +or `eth5` to all other interfaces in this configuration. + +```none +set service broadcast-relay id 1 description 'SONOS' +set service broadcast-relay id 1 interface 'eth3' +set service broadcast-relay id 1 interface 'eth4' +set service broadcast-relay id 1 interface 'eth5' +set service broadcast-relay id 1 port '1900' +``` diff --git a/docs/configuration/service/config-sync.md b/docs/configuration/service/config-sync.md new file mode 100644 index 00000000..a575f947 --- /dev/null +++ b/docs/configuration/service/config-sync.md @@ -0,0 +1,164 @@ +(config-sync)= + +# Config Sync + +Configuration synchronization (config sync) is a feature of VyOS that +permits synchronization of the configuration of one VyOS router to +another in a network. + +The main benefit to configuration synchronization is that it eliminates having +to manually replicate configuration changes made on the primary router to the +secondary (replica) router. + +The writing of the configuration to the secondary router is performed through +the VyOS HTTP API. The user can specify which portion(s) of the configuration will +be synchronized and the mode to use - whether to replace or add. + +To prevent issues with divergent configurations between the pair of routers, +synchronization is strictly unidirectional from primary to replica. Both +routers should be online and run the same version of VyOS. + +## Configuration + +```{cfgcmd} set service config-sync secondary \<address|key|timeout|port\> + +Specify the address, API key, timeout and port of the secondary router. +You need to enable and configure the HTTP API service on the secondary +router for config sync to operate. +``` + +```{cfgcmd} set service config-sync section \<section\> + +Specify the section of the configuration to synchronize. If more than one +section is to be synchronized, repeat the command to add additional +sections as required. +``` + +```{cfgcmd} set service config-sync mode \<load|set\> + +Two options are available for *mode*: either *load* and replace or *set* +the configuration section. +``` + +```none +Supported options for <section> include: + firewall + interfaces <interface> + nat + nat66 + pki + policy + protocols <protocol> + qos <interface|policy> + service <service> + system <conntrack| + flow-accounting|option|sflow|static-host-mapping|sysctl|time-zone> + vpn + vrf +``` + + +## Operational Commands + +````{opcmd} show configuration secondary sync [commands] [running | candidate | saved] [\<config-node-path\>] + +Display configuration differences between the local node and +a config-sync secondary node. + +This command allows operators to compare configurations across nodes +participating in configuration synchronization (e.g., primary and +secondary routers). It helps detect configuration drift and validate +intended changes before synchronization. + +**Parameters:** + +```{eval-rst} +.. list-table:: + :widths: 30 70 + :header-rows: 0 + + * - ``commands`` (optional) + - Show output as a list of configuration commands instead of raw diff. + * - ``running|candidate|saved`` (optional, mutually exclusive) + - Select which configuration to compare: + ``running`` (current active configuration, default), + ``candidate`` (uncommitted changes), or + ``saved`` (last saved configuration). Only one of these may be + specified at a time; if omitted, ``running`` is used. +``` + +**Examples:** + +:::{code-block} none +# compare full running configuration with a secondary node +show configuration secondary sync + +# compare only interface configuration +show configuration secondary sync running interfaces dummy + +# compare candidate configuration and display as a list of commands +show configuration secondary sync commands candidate +::: +```` + +Without a built-in cross-node diff, operators may unintentionally push +changes that conflict with the remote configuration (e.g., mismatched +interfaces, firewall policies, or protocol settings). + + +## Example + +- Synchronize the time-zone and OSPF configuration from Router A to Router B +- The address of Router B is 10.0.20.112 and the port used is 8443 + +Configure the HTTP API service on Router B + +```none +set service https listen-address '10.0.20.112' +set service https port '8443' +set service https api keys id KID key 'foo' +set service https api rest +``` + +Configure the config-sync service on Router A + +```none +set service config-sync mode 'load' +set service config-sync secondary address '10.0.20.112' +set service config-sync secondary port '8443' +set service config-sync secondary key 'foo' +set service config-sync section protocols 'ospf' +set service config-sync section system 'time-zone' +``` + +Make config-sync relevant changes to Router A's configuration + +```none +vyos@vyos-A# set system time-zone 'America/Los_Angeles' +vyos@vyos-A# commit +INFO:vyos_config_sync:Config synchronization: Mode=load, +Secondary=10.0.20.112 +vyos@vyos-A# save + +vyos@vyos-A# set protocols ospf area 0 network '10.0.48.0/30' +vyos@vyos-A# commit +INFO:vyos_config_sync:Config synchronization: Mode=load, +Secondary=10.0.20.112 +yos@vyos-A# save +``` + +Verify configuration changes have been replicated to Router B + +```none +vyos@vyos-B:~$ show configuration commands | match time-zone +set system time-zone 'America/Los_Angeles' + +vyos@vyos-B:~$ show configuration commands | match ospf +set protocols ospf area 0 network '10.0.48.0/30' +``` + + +## Known issues + +Configuration resynchronization. With the current implementation of *service +config-sync*, the secondary node must be online. diff --git a/docs/configuration/service/conntrack-sync.md b/docs/configuration/service/conntrack-sync.md new file mode 100644 index 00000000..4aad6283 --- /dev/null +++ b/docs/configuration/service/conntrack-sync.md @@ -0,0 +1,321 @@ +(conntrack-sync)= + +# Conntrack Sync + +One of the important features built on top of the Netfilter framework is +connection tracking. Connection tracking allows the kernel to keep track of all +logical network connections or sessions, and thereby relate all of the packets +which may make up that connection. NAT relies on this information to translate +all related packets in the same way, and iptables can use this information to +act as a stateful firewall. + +The connection state however is completely independent of any upper-level +state, such as TCP's or SCTP's state. Part of the reason for this is that when +merely forwarding packets, i.e. no local delivery, the TCP engine may not +necessarily be invoked at all. Even connectionless-mode transmissions such as +UDP, IPsec (AH/ESP), GRE and other tunneling protocols have, at least, a pseudo +connection state. The heuristic for such protocols is often based upon a preset +timeout value for inactivity, after whose expiration a Netfilter connection is +dropped. + +Each Netfilter connection is uniquely identified by a (layer-3 protocol, source +address, destination address, layer-4 protocol, layer-4 key) tuple. The layer-4 +key depends on the transport protocol; for TCP/UDP it is the port numbers, for +tunnels it can be their tunnel ID, but otherwise is just zero, as if it were +not part of the tuple. To be able to inspect the TCP port in all cases, packets +will be mandatorily defragmented. + +It is possible to use either Multicast or Unicast to sync conntrack traffic. +Most examples below show Multicast, but unicast can be specified by using the +"peer" keyword after the specified interface, as in the following example: + +{cfgcmd}`set service conntrack-sync interface eth0 peer 192.168.0.250` + +## Configuration + +```{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\> + +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 +size growth that can be reached. + +Queue size for listening to local conntrack events in MB. +``` + + +```{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\> + +Failover mechanism to use for conntrack-sync. + +Only VRRP is supported. Required option. +``` + + +```{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\> + +Interface to use for syncing conntrack entries. +``` + + +```{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\> + +Peer to send unicast UDP conntrack sync entries to, if not using Multicast +configuration from above. +``` + + +```{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 disables the external cache and directly injects the flow-states into the +in-kernel Connection Tracking System of the backup firewall. +``` + + +```{cfgcmd} set service conntrack-sync purge-timeout \<timeout\> + +Timeout (in seconds) for purging synchronized entries on handover events. + +On handover, ``conntrackd -t`` is invoked, which schedules a conntrack table +flush after ``<timeout>`` seconds to purge stale (“zombie”) entries and +reduce clashes when multiple handovers occur in a short period. +The default is 60 seconds. +``` + +:::{note} +In VRRP stateful firewall deployments, align VRRP timing with this +behavior: because synchronized conntrack state is purged after the purge +timeout, set **VRRP preempt-delay** to ≥ **purge-timeout** so mastership +can be restored before conntrack state is purged. +::: + +```{cfgcmd} set service conntrack-sync disable-syslog + +Disable connection logging via Syslog. +``` + + +```{cfgcmd} set service conntrack-sync startup-resync + +Order conntrackd to request a complete conntrack table resync against +the other node at startup. +``` + +## Operation + +```{opcmd} show conntrack table ipv4 + +Make sure conntrack is enabled by running and show connection tracking table. + +:::{code-block} none +vyos@vyos:~$ show conntrack table ipv4 +TCP state codes: SS - SYN SENT, SR - SYN RECEIVED, ES - ESTABLISHED, +FW - FIN WAIT, CW - CLOSE WAIT, LA - LAST ACK, +TW - TIME WAIT, CL - CLOSE, LI - LISTEN + +CONN ID Source Destination Protocol TIMEOUT +1015736576 10.35.100.87:58172 172.31.20.12:22 tcp [6] ES 430279 +1006235648 10.35.101.221:57483 172.31.120.21:22 tcp [6] ES 413310 +1006237088 10.100.68.100 172.31.120.21 icmp [1] 29 +1015734848 10.35.100.87:56282 172.31.20.12:22 tcp [6] ES 300 +1015734272 172.31.20.12:60286 239.10.10.14:694 udp [17] 29 +1006239392 10.35.101.221 172.31.120.21 icmp [1] 29 +::: +:::{note} +If the table is empty and you have a warning message, it means +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 cache external + +Show connection syncing external cache entries +``` + + +```{opcmd} show conntrack-sync cache internal + +Show connection syncing internal cache entries +``` + + +```{opcmd} show conntrack-sync statistics + +Retrieve current statistics of connection tracking subsystem. + +:::{code-block} none +vyos@vyos:~$ show conntrack-sync statistics +Main Table Statistics: + +cache internal: +current active connections: 19606 +connections created: 6298470 failed: 0 +connections updated: 3786793 failed: 0 +connections destroyed: 6278864 failed: 0 + +cache external: +current active connections: 15771 +connections created: 1660193 failed: 0 +connections updated: 77204 failed: 0 +connections destroyed: 1644422 failed: 0 + +traffic processed: +0 Bytes 0 Pckts + +multicast traffic (active device=eth0.5): +976826240 Bytes sent 212898000 Bytes recv +8302333 Pckts sent 2009929 Pckts recv +0 Error send 0 Error recv + +message tracking: +0 Malformed msgs 263 Lost msgs +::: +``` +```{opcmd} show conntrack-sync status + +Retrieve current status of connection tracking subsystem. + +:::{code-block} none +vyos@vyos:~$ show conntrack-sync status +sync-interface : eth0.5 +failover-mechanism : vrrp [sync-group GEFOEKOM] +last state transition : no transition yet! +ExpectationSync : disabled +::: +``` + +## Example + +The next example is a simple configuration of conntrack-sync. + +:::{figure} /_static/images/service_conntrack_sync-schema.webp +:alt: Conntrack Sync Example +:scale: 60 % +::: + +Now configure conntrack-sync service on `router1` **and** `router2` + +```none +set high-availability vrrp group internal virtual-address ... etc ... +set high-availability vrrp sync-group syncgrp member 'internal' +set service conntrack-sync accept-protocol 'tcp' +set service conntrack-sync accept-protocol 'udp' +set service conntrack-sync accept-protocol 'icmp' +set service conntrack-sync failover-mechanism vrrp sync-group 'syncgrp' +set service conntrack-sync interface 'eth0' +set service conntrack-sync mcast-group '225.0.0.50' +``` + +On the active router, you should have information in the internal-cache of +conntrack-sync. The same current active connections number should be shown in +the external-cache of the standby router + +On active router run: + +```none +$ show conntrack-sync statistics + +Main Table Statistics: + +cache internal: +current active connections: 10 +connections created: 8517 failed: 0 +connections updated: 127 failed: 0 +connections destroyed: 8507 failed: 0 + +cache external: +current active connections: 0 +connections created: 0 failed: 0 +connections updated: 0 failed: 0 +connections destroyed: 0 failed: 0 + +traffic processed: + 0 Bytes 0 Pckts + +multicast traffic (active device=eth0): + 868780 Bytes sent 224136 Bytes recv + 20595 Pckts sent 14034 Pckts recv + 0 Error send 0 Error recv + +message tracking: + 0 Malformed msgs 0 Lost msgs +``` + +On standby router run: + +```none +$ show conntrack-sync statistics + +Main Table Statistics: + +cache internal: +current active connections: 0 +connections created: 0 failed: 0 +connections updated: 0 failed: 0 +connections destroyed: 0 failed: 0 + +cache external: +current active connections: 10 +connections created: 888 failed: 0 +connections updated: 134 failed: 0 +connections destroyed: 878 failed: 0 + +traffic processed: + 0 Bytes 0 Pckts + +multicast traffic (active device=eth0): + 234184 Bytes sent 907504 Bytes recv + 14663 Pckts sent 21495 Pckts recv + 0 Error send 0 Error recv + +message tracking: + 0 Malformed msgs 0 Lost msgs +``` diff --git a/docs/configuration/service/console-server.md b/docs/configuration/service/console-server.md new file mode 100644 index 00000000..f0556652 --- /dev/null +++ b/docs/configuration/service/console-server.md @@ -0,0 +1,139 @@ +(console-server)= + +# Console Server + +Starting of with VyOS 1.3 (equuleus) we added support for running VyOS as an +Out-of-Band Management device which provides remote access by means of SSH to +directly attached serial interfaces. + +Serial interfaces can be any interface which is directly connected to the CPU +or chipset (mostly known as a ttyS interface in Linux) or any other USB to +serial converter (Prolific PL2303 or FTDI FT232/FT4232 based chips). + +If you happened to use a Cisco NM-16A - Sixteen Port Async Network Module or +NM-32A - Thirty-two Port Async Network Module - this is your VyOS replacement. + +For USB port information please refor to: {ref}`hardware_usb`. + +## Configuration + +Between computers, the most common configuration used was "8N1": eight bit +characters, with one start bit, one stop bit, and no parity bit. Thus 10 Baud +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 \<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 \<device\> description \<string\> + +A user friendly description identifying the connected peripheral. +``` + + +```{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 \<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 \<device\> speed [ 300 | 1200 | 2400 | 4800 | 9600 | 19200 | 38400 | 57600 | 115200 ] + +:::{note} +USB to serial converters will handle most of their work in software +so you should be carefull with the selected baudrate as some times they +can't cope with the expected speed. +::: +``` + +### Remote Access + + +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 \<device\> ssh port \<port\> + +Accept SSH connections for the given `<device>` on TCP port `<port>`. +After successful authentication the user will be directly dropped to +the connected serial device. + +:::{hint} +Multiple users can connect to the same serial device but only +one is allowed to write to the console port. +::: +``` + +## Operation + +```{opcmd} show console-server ports + +Show configured serial ports and their respective interface configuration. + +:::{code-block} none +vyos@vyos:~$ show console-server ports +usb0b2.4p1.0 on /dev/serial/by-bus/usb0b2.4p1.0@ at 9600n +::: +``` + + +```{opcmd} show console-server user + +Show currently connected users. + +:::{code-block} none +vyos@vyos:~$ show console-server user +usb0b2.4p1.0 up vyos@localhost +::: +``` +```{opcmd} connect console \<device\> + +Locally connect to serial port identified by `<device>`. + +:::{code-block} none +vyos@vyos-r1:~$ connect console usb0b2.4p1.0 +[Enter `^Ec?' for help] +[-- MOTD -- VyOS Console Server] + +vyos-r2 login: +::: + +:::{hint} +Multiple users can connect to the same serial device but only +one is allowed to write to the console port. +::: + +:::{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.md b/docs/configuration/service/dhcp-relay.md new file mode 100644 index 00000000..a4a10109 --- /dev/null +++ b/docs/configuration/service/dhcp-relay.md @@ -0,0 +1,205 @@ +(dhcp-relay)= + +# DHCP Relay + +If you want your router to forward DHCP requests to an external DHCP server +you can configure the system to act as a DHCP relay agent. The DHCP relay +agent works with IPv4 and IPv6 addresses. + +All interfaces used for the DHCP relay must be configured. This includes the +uplink to the DHCP server. + +## IPv4 relay + +### Configuration + +```{cfgcmd} set service dhcp-relay interface \<interface\> + +Interfaces that participate in the DHCP relay process. If this command is +used, at least two entries of it are required: one for the interface that +captures the dhcp-requests, and one for the interface to forward such +requests. A warning message will be shown if this command is used, since +new implementations should use ``listen-interface`` and +``upstream-interface``. +``` + +```{cfgcmd} set service dhcp-relay listen-interface \<interface\> + +Interface for DHCP Relay Agent to listen for requests. +``` + +```{cfgcmd} set service dhcp-relay upstream-interface \<interface\> + +Interface for DHCP Relay Agent to forward requests out. +``` + +```{cfgcmd} set service dhcp-relay server \<server\> + +Configure IP address of the DHCP `<server>` which will handle the relayed +packets. +``` + +```{cfgcmd} set service dhcp-relay relay-options relay-agents-packets discard + +The router should discard DHCP packages already containing relay agent +information to ensure that only requests from DHCP clients are forwarded. +``` + +```{cfgcmd} set service dhcp-relay disable + +Disable dhcp-relay service. +``` + + +#### Options + +```{cfgcmd} set service dhcp-relay relay-options hop-count \<count\> + +Set the maximum hop `<count>` before packets are discarded. Range 0...255, +default 10. +``` + +```{cfgcmd} set service dhcp-relay relay-options max-size \<size\> + +Set maximum `<size>` of DHCP packets including relay agent information. If a +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-packets \<append | discard | forward | replace\> + +Four policies for reforwarding DHCP packets exist: +* **append:** The relay agent is allowed to append its own relay information +to a received DHCP packet, disregarding relay information already present +in the packet. +* **discard:** Received packets which already contain relay information will +be discarded. +* **forward:** All packets are forwarded, relay information already present +will be ignored. +* **replace:** Relay information already present in a packet is stripped and +replaced with the router's own relay information set. +``` + + +### Example + +- Listen for DHCP requests on interface `eth1`. +- DHCP server is located at IPv4 address 10.0.1.4 on `eth2`. +- Router receives DHCP client requests on `eth1` and relays them to the + server at 10.0.1.4 on `eth2`. + +:::{figure} /_static/images/service_dhcp-relay01.webp +:alt: DHCP relay example +:scale: 80 % +DHCP relay example +::: + +The generated configuration will look like: + +```none +show service dhcp-relay + listen-interface eth1 + upstream-interface eth2 + server 10.0.1.4 + relay-options { + relay-agents-packets discard + } +``` + +Also, for backwards compatibility this configuration, which uses generic +interface definition, is still valid: + +```none +show service dhcp-relay + interface eth1 + interface eth2 + server 10.0.1.4 + relay-options { + relay-agents-packets discard + } +``` + + +### Operation + +```{opcmd} restart dhcp relay-agent + +Restart DHCP relay service +``` + + +## IPv6 relay + +(dhcp-relay-ipv6-configuration)= + +### Configuration + +```{cfgcmd} set service dhcpv6-relay listen-interface \<interface\> + +Set eth1 to be the listening interface for the DHCPv6 relay. + +Multiple interfaces may be specified. +``` + +```{cfgcmd} set service dhcpv6-relay upstream-interface \<interface\> address \<server\> + +Specifies an upstream network `<interface>` from which replies from +`<server>` and other relay agents will be accepted. +``` + +(dhcp-relay-ipv6-options)= + +```{cfgcmd} set service dhcpv6-relay disable + +Disable dhcpv6-relay service. +``` + +(dhcp-relay-v6-options)= + +#### Options + +```{cfgcmd} set service dhcpv6-relay max-hop-count \<count\> + +Set maximum hop count before packets are discarded, default: 10 +``` + +```{cfgcmd} set service dhcpv6-relay use-interface-id-option + +If this is set the relay agent will insert the interface ID. This option is +set automatically if more than one listening interfaces are in use. +``` + +(dhcp-relay-ipv6-example)= + +### Example + +- DHCPv6 requests are received by the router on `listening interface` `eth1` +- Requests are forwarded through `eth2` as the `upstream interface` +- External DHCPv6 server is at 2001:db8::4 + +:::{figure} /_static/images/service_dhcpv6-relay01.webp +:alt: DHCPv6 relay example +:scale: 80 % +DHCPv6 relay example +::: + +The generated configuration will look like: + +```none +commit +show service dhcpv6-relay + listen-interface eth1 { + } + upstream-interface eth2 { + address 2001:db8::4 + } +``` + +(dhcp-relay-ipv6-op-cmd)= + +### Operation + +```{opcmd} restart dhcpv6 relay-agent + +Restart DHCPv6 relay agent immediately. +```
\ No newline at end of file diff --git a/docs/configuration/service/dhcp-server.md b/docs/configuration/service/dhcp-server.md new file mode 100644 index 00000000..721d6d4a --- /dev/null +++ b/docs/configuration/service/dhcp-server.md @@ -0,0 +1,1178 @@ +(dhcp-server)= + +# DHCP Server + +VyOS uses Kea DHCP server for both IPv4 and IPv6 address assignment. + +## IPv4 server + +The network topology is declared by shared-network-name and the subnet +declarations. The DHCP service can serve multiple shared networks, with each +shared network having 1 or more subnets. Each subnet must be present on an +interface. A range can be declared inside a subnet to define a pool of dynamic +addresses. Multiple ranges can be defined and can contain holes. Static +mappings can be set to assign "static" addresses to clients based on their MAC +address. + +### Configuration + +```{cfgcmd} set service dhcp-server hostfile-update + + Create DNS record per client lease, by adding clients to /etc/hosts file. + Entry will have format: `<shared-network-name>_<hostname>.<domain-name>` +``` + + +```{cfgcmd} set service dhcp-server shared-network-name \<name\> option domain-name \<domain-name\> + +The domain-name parameter should be the domain name that will be appended to +the client's hostname to form a fully-qualified domain-name (FQDN) (DHCP +Option 015). + +This is the configuration parameter for the entire shared network definition. +All subnets will inherit this configuration item if not specified locally. +``` + + +```{cfgcmd} set service dhcp-server shared-network-name \<name\> option domain-search \<domain-name\> + +The domain-name parameter should be the domain name used when completing DNS +request where no full FQDN is passed. This option can be given multiple times +if you need multiple search domains (DHCP Option 119). + +This is the configuration parameter for the entire shared network definition. +All subnets will inherit this configuration item if not specified locally. +``` + + +```{cfgcmd} set service dhcp-server shared-network-name \<name\> option name-server \<address\> + +Inform client that the DNS server can be found at `<address>`. + +This is the configuration parameter for the entire shared network definition. +All subnets will inherit this configuration item if not specified locally. +Multiple DNS servers can be defined. +``` + + +```{cfgcmd} set service dhcp-server shared-network-name \<name\> option vendor-option \<option-name\> + +This configuration parameter lets you specify a vendor-option for the +entire shared network definition. All subnets will inherit this +configuration item if not specified locally. An example for Ubiquiti is +shown below: +``` + +**Example:** + + +Pass address of Unifi controller at `172.16.100.1` to all clients of `NET1` + +```none +set service dhcp-server shared-network-name 'NET1' option vendor-option +ubiquiti '172.16.100.1' +``` + + +```{cfgcmd} set service dhcp-server listen-address \<address\> + +This configuration parameter lets the DHCP server to listen for DHCP +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 + +```{cfgcmd} set service dhcp-server shared-network-name \<name\> authoritative + +This says that this device is the only DHCP server for this network. If other +devices are trying to offer DHCP leases, this machine will send 'DHCPNAK' to +any device trying to request an IP address that is not valid for this +network. +``` + + +```{cfgcmd} set service dhcp-server shared-network-name \<name\> subnet \<subnet\> subnet-id \<id\> + +This configuration parameter is required and must be unique to each subnet. +It is required to map subnets to lease file entries. +``` + + +```{cfgcmd} set service dhcp-server shared-network-name \<name\> subnet \<subnet\> option default-router \<address\> + +This is a configuration parameter for the `<subnet>`, saying that as part of +the response, tell the client that the default gateway can be reached at +`<address>`. +``` + + +```{cfgcmd} set service dhcp-server shared-network-name \<name\> subnet \<subnet\> option name-server \<address\> + +This is a configuration parameter for the subnet, saying that as part of the +response, tell the client that the DNS server can be found at `<address>`. + +Multiple DNS servers can be defined. +``` + + +```{cfgcmd} set service dhcp-server shared-network-name \<name\> subnet \<subnet\> lease \<time\> + +Assign the IP address to this machine for `<time>` seconds. + +The default value is 86400 seconds which corresponds to one day. +``` + + +```{cfgcmd} set service dhcp-server shared-network-name \<name\> subnet \<subnet\> range \<n\> start \<address\> + +Create DHCP address range with a range id of `<n>`. DHCP leases are taken +from this pool. The pool starts at address `<address>`. +``` + + +```{cfgcmd} set service dhcp-server shared-network-name \<name\> subnet \<subnet\> range \<n\> stop \<address\> + +Create DHCP address range with a range id of `<n>`. DHCP leases are taken +from this pool. The pool stops with address `<address>`. +``` + + +```{cfgcmd} set service dhcp-server shared-network-name \<name\> subnet \<subnet\> exclude \<address\> + +Always exclude this address from any defined range. This address will never +be assigned by the DHCP server. + +This option can be specified multiple times. +``` + + +```{cfgcmd} set service dhcp-server shared-network-name \<name\> subnet \<subnet\> option domain-name \<domain-name\> + +The domain-name parameter should be the domain name that will be appended to +the client's hostname to form a fully-qualified domain-name (FQDN) (DHCP +Option 015). +``` + + +```{cfgcmd} set service dhcp-server shared-network-name \<name\> subnet \<subnet\> option domain-search \<domain-name\> + +The domain-name parameter should be the domain name used when completing DNS +request where no full FQDN is passed. This option can be given multiple times +if you need multiple search domains (DHCP Option 119). +``` + + +```{cfgcmd} set service dhcp-server shared-network-name \<name\> subnet \<subnet\> option vendor-option \<option-name\> + +This configuration parameter lets you specify a vendor-option for the +subnet specified within the shared network definition. An example for +Ubiquiti is shown below: +``` + +**Example:** + + +Create `172.18.201.0/24` as a subnet within `NET1` and pass address of +Unifi controller at `172.16.100.1` to clients of that subnet. + +```none +set service dhcp-server shared-network-name 'NET1' subnet +'172.18.201.0/24' option vendor-option ubiquiti '172.16.100.1' +``` + +#### Dynamic DNS Update (RFC 2136) + + +VyOS DHCP service supports RFC-2136 DDNS protocol. Based on DHCP lease change +events, DHCP server generates DDNS update requests (defines as NameChangeRequests +or NCRs) and posts them to a compliant DNS server, that will update its name +database accordingly. + + +VyOS built-in DNS Forwarder does not support DDNS, you will need an external DNS +server with RFC-2136 DDNS support. + +```{cfgcmd} set service dhcp-server dynamic-dns-update + +Enables DDNS globally. +``` + +**Behavioral settings** + + +These settings can be configured on the global level and overridden on the scope +level, i.e. for individual shared networks or subnets. See examples below. + +```{cfgcmd} set service dhcp-server dynamic-dns-update send-updates [ enable | disable ] + +If set to ``enable`` on global level, updates for all scopes will be enabled, +except if explicitly set to ``disable`` on the scope level. If set to ``disable``, +updates will only be sent for scopes, where ``send-updates`` is explicitly +set to ``enable``. + +This model is followed for a few behavioral settings below: if the option is +not set, the setting is inherited from the parent scope. You can override the +parent scope setting by setting the option explicitly. +``` + + +```{cfgcmd} set service dhcp-server dynamic-dns-update override-no-update [ enable | disable ] + +VyOS will ignore client request not to update DNS records and send DDNS +update requests regardless. +``` + + +```{cfgcmd} set service dhcp-server dynamic-dns-update override-client-update [ enable | disable ] + +VyOS will override client DDNS request settings and always update both +forward and reverse DNS records. +``` + + +```{cfgcmd} set service dhcp-server dynamic-dns-update update-on-renew [ enable | disable ] + +Issue DDNS update requests on DHCP lease renew. In busy networks this may +generate a lot of traffic. +``` + + +```{cfgcmd} set service dhcp-server dynamic-dns-update conflict-resolution [ enable | disable ] + +Use RFC-4703 conflict resolution. This algorithm helps in situation when +multiple clients reserve same IP addresses or advertise identical hostnames. +Should be used in most situations. +``` + + +```{cfgcmd} set service dhcp-server dynamic-dns-update replace-client-name [ never | always | when-present | when-not-present ] + +* **never**: use the name sent by the client. If the client didn't provide any, +do not generate one. This is the default behavior + +* **always**: always generate a name for the client + +* **when-present**: replace the name the client sent with a generated one, if +the client didn't send any, do not generate one + +* **when-not-present**: use the name sent by the client. If the client didn't +send any, generate one for the client + +The names are generated using ``generated-prefix``, ``qualifying-suffix`` and the +client's IP address string. +``` + + +```{cfgcmd} set service dhcp-server dynamic-dns-update generated-prefix \<prefix\> + +Prefix used in client name generation. +``` + + +```{cfgcmd} set service dhcp-server dynamic-dns-update qualifying-suffix \<suffix\> + +DNS suffix used in client name generation. +``` + + +```{cfgcmd} set service dhcp-server dynamic-dns-update ttl-percent \<0-100\> + +TTL of the DNS record as a percentage of the DHCP lease time. +``` + + +```{cfgcmd} set service dhcp-server dynamic-dns-update hostname-char-set \<character string\> + +Characters, that are considered invalid in the client name. They will be replaced +with ``hostname-char-replacement`` string. +``` + + +```{cfgcmd} set service dhcp-server dynamic-dns-update hostname-char-replacement \<character string\> + +Replacement string for the invalid characters defined by ``hostname-char-set``. +``` + +**TSIG keys definition** + + +This is the global list of TSIG keys for DDNS updates. They need to be specified by +the name in the DNS domain definitions. + +```{cfgcmd} set service dhcp-server dynamic-dns-update tsig-key \<key-name\> algorithm \<algorithm\> + +Sets the algorithm for the TSIG key. Supported algorithms are ``hmac-md5``, +``hmac-sha1``, ``hmac-sha224``, ``hmac-sha256``, ``hmac-sha384``, ``hmac-sha512`` +``` + + +```{cfgcmd} set service dhcp-server dynamic-dns-update tsig-key \<key-name\> secret \<key-secret\> + +base64-encoded TSIG key secret value +``` + +**DNS domains definition** + + +This is global configuration of DNS servers for the updatable forward and reverse +DNS domains. For every domain multiple DNS servers can be specified. + +```{cfgcmd} set service dhcp-server dynamic-dns-update [forward|reverse]-domain \<domain-name\> key-name \<tsig-key-name\> + +TSIG key used for the domain. +``` + + +```{cfgcmd} set service dhcp-server dynamic-dns-update [forward|reverse]-domain \<domain-name\> dns-server \<number\> address \<ip-address\> + +IP address of the DNS server. +``` + + +```{cfgcmd} set service dhcp-server dynamic-dns-update [forward|reverse]-domain \<domain-name\> dns-server \<number\> port \<port\> + +UDP port of the DNS server. ``53`` is the default. +``` + +**Example:** + + +Global configuration you will most likely want: + +```none +set service dhcp-server dynamic-dns-update send-updates enable +set service dhcp-server dynamic-dns-update conflict-resolution enable +``` + +Override the above configuration for a shared network NET1: + +```none +set service dhcp-server shared-network-name 'NET1' dynamic-dns-update replace-client-name when-not-present +set service dhcp-server shared-network-name 'NET1' dynamic-dns-update generated-prefix ip +set service dhcp-server shared-network-name 'NET1' dynamic-dns-update qualifying-suffix mybigdomain.net +``` + +And in a subnet within the same shared network: + +```none +set service dhcp-server shared-network-name 'NET1' subnet '172.18.201.0/24' dynamic-dns-update qualifying-suffix mydomain.net +``` + +Configure TSIG keys: + +```none +set service dhcp-server dynamic-dns-update tsig-key mydomain-net algorithm hmac-sha256 +set service dhcp-server dynamic-dns-update tsig-key mydomain-net secret eWF5YW15bGl0dGxla2V5IQ== +set service dhcp-server dynamic-dns-update tsig-key reverse-172-18-201 algorithm hmac-sha256 +set service dhcp-server dynamic-dns-update tsig-key reverse-172-18-201 secret eWF5YW15YW5vdGhlcmxpdHRsZWtleSE= +``` + +Configure DDNS domains: + +```none +set service dhcp-server dynamic-dns-update forward-domain mydomain.net key-name mydomain-net +set service dhcp-server dynamic-dns-update forward-domain mydomain.net dns-server 1 address '172.18.0.254' +set service dhcp-server dynamic-dns-update forward-domain mydomain.net dns-server 1 port 1053 +set service dhcp-server dynamic-dns-update forward-domain mydomain.net dns-server 2 address '192.168.124.254' +set service dhcp-server dynamic-dns-update forward-domain mydomain.net dns-server 2 port 53 +set service dhcp-server dynamic-dns-update forward-domain 201.18.172.in-addr.arpa key-name reverse-172-18-201 +set service dhcp-server dynamic-dns-update reverse-domain 201.18.172.in-addr.arpa dns-server 1 address '172.18.0.254' +set service dhcp-server dynamic-dns-update reverse-domain 201.18.172.in-addr.arpa dns-server 1 port 1053 +set service dhcp-server dynamic-dns-update reverse-domain 201.18.172.in-addr.arpa dns-server 2 address '192.168.124.254' +set service dhcp-server dynamic-dns-update reverse-domain 201.18.172.in-addr.arpa dns-server 2 port 53 +``` + +#### High Availability + + +VyOS provides High Availability support for DHCP server. DHCP High +Availability can act in two different modes: + + +- **Active-active**: both DHCP servers will respond to DHCP requests. If + `mode` is not defined, this is the default behavior. +- **Active-passive**: only `primary` server will respond to DHCP requests. + If this server goes offline, then `secondary` server will take place. + + +DHCP High Availability must be configured explicitly by the following +statements on both servers: + +```{cfgcmd} set service dhcp-server high-availability mode [active-active | active-passive] + +Define operation mode of High Availability feature. Default value if command +is not specified is `active-active` +``` + + +```{cfgcmd} set service dhcp-server high-availability source-address \<address\> + +Local IP `<address>` used when communicating to the HA peer. +``` + + +```{cfgcmd} set service dhcp-server high-availability remote \<address\> + +Remote peer IP `<address>` of the second DHCP server in this HA +cluster. +``` + + +```{cfgcmd} set service dhcp-server high-availability name \<name\> + +Define the name of the peer server to establish and identify the HA (High Availability) connection. + +:::{note} +Make sure the specified value does not conflict with the system host-name. +::: +``` + + +```{cfgcmd} set service dhcp-server high-availability status \<primary | secondary\> + +The primary and secondary statements determines whether the server is primary +or secondary. + +:::{note} +In order for the primary and the secondary DHCP server to keep +their lease tables in sync, they must be able to reach each other on TCP +port 647. If you have firewall rules in effect, adjust them accordingly. +::: +:::{hint} +The dialogue between HA partners is neither encrypted nor +authenticated. Since most DHCP servers exist within an organisation's own +secure Intranet, this would be an unnecessary overhead. However, if you +have DHCP HA peers whose communications traverse insecure networks, +then we recommend that you consider the use of VPN tunneling between them +to ensure that the HA partnership is immune to disruption +(accidental or otherwise) via third parties. +::: +``` + +#### Static mappings + + +You can specify a static DHCP assignment on a per host basis. You will need the +MAC address of the station and your desired IP address. The address must be +inside the subnet definition but can be outside of the range statement. + +```{cfgcmd} set service dhcp-server shared-network-name \<name\> subnet \<subnet\> static-mapping \<description\> mac \<address\> + +Create a new DHCP static mapping named `<description>` which is valid for +the host identified by its MAC `<address>`. +``` + + +```{cfgcmd} set service dhcp-server shared-network-name \<name\> subnet \<subnet\> static-mapping \<description\> duid \<identifier\> + +Create a new DHCP static mapping named `<description>` which is valid for +the host identified by its DHCP unique identifier (DUID) `<identifier>`. +``` + + +```{cfgcmd} set service dhcp-server shared-network-name \<name\> subnet \<subnet\> static-mapping \<description\> ip-address \<address\> + +Static DHCP IP address assign to host identified by `<description>`. IP +address must be inside the `<subnet>` which is defined but can be outside +the dynamic range created with {cfgcmd}`set service dhcp-server +shared-network-name <name> subnet <subnet> range <n>`. If no ip-address is +specified, an IP from the dynamic pool is used. + +This is useful, for example, in combination with hostfile update. + +:::{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 `client1` + +```none +set service dhcp-server shared-network-name 'NET1' subnet 192.168.1.0/24 subnet-id 1 +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 aa:bb:11:22:33:00 +``` + +The configuration will look as follows: + +```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 aa:bb:11:22:33:00 + } + subnet-id 1 + } +``` + +#### Relay agent information (Option 82) + + +Some DHCP relays support the injection of information into a DHCP request, depending on +where the request originated from. This is commonly used to determine the +behaviour of the DHCP server, based on the port/switch combination where the +request was first detected. I.e. the device plugged into a particular port (or +set of ports) always gets the same IP address (or range of IP addresses). This +information is usually included in the request using Option 82, hence this +is what we call this part of the configuration. + + +This behaviour is controlled in two parts. First, "client classes" are defined +which determine which inputs match. Once a positive match has been found the +request is "tagged" with this client class. Second, when the DHCP server +processes the request it checks to see if the configuration has a client class +defined. If it does then that part of the configuration will override the others + + +Client classes can be applied at either the subnet or range level, depending on +how you want the server to behave. + + +**Client Class definition** + +```{cfgcmd} set service dhcp-server client-class \<name\> relay-agent-information circuit-id \<value\> + +Create a new client class (if not already defined) and set it to match on +the "Circuit ID" part of the Option 82 field in the DHCP request. This is +sub option "1" as specified by RFC 3046. The value specified here is either +interpreted as a raw hex value, if it starts with the prefix 0x, or ASCII text +otherwise. e.g. ``e1-5`` and ``0x65312d35`` are the same +``` + + +```{cfgcmd} set service dhcp-server client-class \<name\> relay-agent-information remote-id \<value\> + +Create a new client class (if not already defined) and set it to match on +the "Remote ID" part of the Option 82 field in the DHCP request. This is +sub option "2" as specified by RFC 3046. The value specified here is either +interpreted as a raw hex value, if it starts with the prefix 0x, or ASCII text +otherwise. e.g. ``10.100.0.41`` and ``0x31302e3130302e302e3431`` are the +same +``` + +**Client Class application** + +```{cfgcmd} set service dhcp-server shared-network-name \<subnet-name\> subnet \<CIDR\> client-class \<class-name\> + +Applies the Client Class with the name `<class-name>` to the subnet `<subnet-name>`. +This means that whenever the client class matches a request it is always +routed to this subnet definition first. +``` + + +```{cfgcmd} set service dhcp-server shared-network-name \<subnet-name\> subnet \<CIDR\> range \<range-name\> client-class \<class-name\> + +Applies the Client Class with the name `<class-name>` to the range +`<range-name>` which belongs to subnet `<subnet-name>`. This means that whenever the +client class matches a request it is always routed to this range definition +first. +``` + +NB: Kea (the DHCP server used by VyOS) is programmed to offer as many +alternatives as it can to repeated DHCP Discover requests. Some operating +systems (Notably Microsoft Windows) make multiple DHCP Discover requests before +settling on an address. This particularly seems to happen when the DHCP server +isn't set to authoritative. This may explain why the address you expect isn't +being chosen. Wireshark is helpful in these situations. + + +**Example:** + + +The following configuration example will classify requests coming in on port +`e1-5` from DHCP Relay `192.0.2.1` and make sure that they are allocated the +address `192.0.2.4`. Any requests which do not match the circuit and remote ID +will, instead, be allocated from the range otherRange in the usual manner. + + +NB: Both the Circuit ID and Remote ID fields are arbitrary free text. *Most* +switches set the Remote ID to the IP address of the management interface but +that should not be relied upon. Check the documentation of your DHCP Relay for +more detail or, as a measure of last resort, inspect the DHCP requests in +Wireshark. + +```none +service { + dhcp-server { + client-class className { + relay-agent-information { + circuit-id e1-5 + remote-id 192.0.2.1 + } + } + shared-network-name test { + subnet 192.0.2.0/24 { + range classNameRange { + client-class className + start 192.0.2.4 + stop 192.0.2.4 + } + range otherRange { + start 192.0.2.5 + stop 192.0.2.100 + } + subnet-id 1 + } + } + } +} +``` + +### Options + + +:::{list-table} +:header-rows: 1 +:stub-columns: 0 +:widths: 12 7 23 40 20 + +* - Setting name + - Option number + - ISC-DHCP Option name + - Option description + - Multi +* - client-prefix-length + - 1 + - subnet-mask + - Specifies the clients subnet mask as per RFC 950. If unset, + subnet declaration is used. + - N +* - time-offset + - 2 + - time-offset + - Offset of the client's subnet in seconds from Coordinated + Universal Time (UTC) + - N +* - default-router + - 3 + - routers + - IPv4 address of router on the client's subnet + - N +* - time-server + - 4 + - time-servers + - RFC 868 time server IPv4 address + - Y +* - name-server + - 6 + - domain-name-servers + - DNS server IPv4 address + - Y +* - domain-name + - 15 + - domain-name + - Client domain name + - Y +* - ip-forwarding + - 19 + - ip-forwarding + - Enable IP forwarding on client + - N +* - ntp-server + - 42 + - ntp-servers + - IP address of NTP server + - Y +* - wins-server + - 44 + - netbios-name-servers + - NetBIOS over TCP/IP name server + - Y +* - server-identifier + - 54 + - dhcp-server-identifier + - IP address for DHCP server identifier + - N +* - bootfile-server + - siaddr + - next-server + - IPv4 address of next bootstrap server + - N +* - tftp-server-name + - 66 + - tftp-server-name + - Name or IPv4 address of TFTP server + - N +* - bootfile-name + - 67 + - bootfile-name, filename + - Bootstrap file name + - N +* - bootfile-size + - 13 + - boot-size + - Boot image length in 512-octet blocks + - N +* - smtp-server + - 69 + - smtp-server + - IP address of SMTP server + - Y +* - pop-server + - 70 + - pop-server + - IP address of POP3 server + - Y +* - domain-search + - 119 + - domain-search + - Client domain search + - Y +* - static-route + - 121, 249 + - rfc3442-static-route, windows-static-route + - Classless static route + - N +* - wpad-url + - 252 + - wpad-url, wpad-url code 252 = text + - Web Proxy Autodiscovery (WPAD) URL + - N +* - lease + - + - default-lease-time, max-lease-time + - Lease timeout in seconds (default: 86400) + - N +* - range + - + - range + - DHCP lease range + - Y +* - exclude + - + - + - IP address to exclude from DHCP lease range + - Y +* - failover + - + - + - DHCP failover parameters + - +* - static-mapping + - + - + - Name of static mapping + - Y +::: + + +Multi: can be specified multiple times. + + +### Example + + +Please see the {ref}`dhcp-dns-quick-start` configuration. + + +(dhcp-server-v4-example-failover)= + + +#### High Availability + + +Configuration of a DHCP HA pair: + + +- Setup DHCP HA for network 192.0.2.0/24 +- Use active-active HA mode. +- Default gateway and DNS server is at `192.0.2.254` +- The primary DHCP server named dhcp-primary uses address `192.168.189.252` +- The secondary DHCP server with named dhcp-secondary uses address `192.168.189.253` +- DHCP range spans from `192.168.189.10` - `192.168.189.250` + + +Common configuration, valid for both primary and secondary node. + +```none +set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 option default-router '192.0.2.254' +set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 option name-server '192.0.2.254' +set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 option domain-name 'vyos.net' +set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 range 0 start '192.0.2.10' +set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 range 0 stop '192.0.2.250' +set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 subnet-id '1' +``` + +**Primary** + +```none +set service dhcp-server high-availability mode 'active-active' +set service dhcp-server high-availability source-address '192.168.189.252' +set service dhcp-server high-availability name 'dhcp-secondary' +set service dhcp-server high-availability remote '192.168.189.253' +set service dhcp-server high-availability status 'primary' +``` + +**Secondary** + +```none +set service dhcp-server high-availability mode 'active-active' +set service dhcp-server high-availability source-address '192.168.189.253' +set service dhcp-server high-availability name 'dhcp-primary' +set service dhcp-server high-availability remote '192.168.189.252' +set service dhcp-server high-availability status 'secondary' +``` + +(dhcp-server-v4-example-raw)= + + +### Operation Mode + +```{opcmd} show log dhcp server + +Show DHCP server daemon log file +``` + + +```{opcmd} show log dhcp client + +Show logs from all DHCP client processes. +``` + + +```{opcmd} show log dhcp client interface \<interface\> + +Show logs from specific `interface` DHCP client process. +``` + + +```{opcmd} restart dhcp server + +Restart the DHCP server +``` + + +```{opcmd} show dhcp server statistics + +Show the DHCP server statistics: +``` + + +```none +vyos@vyos:~$ show dhcp server statistics +Pool Size Leases Available Usage +----------- ------ -------- ----------- ------- +dhcpexample 99 2 97 2% +``` + + +```{opcmd} show dhcp server statistics pool \<pool\> + +Show the DHCP server statistics for the specified pool. +``` + + +```{opcmd} show dhcp server leases + +Show statuses of all active leases: +``` + + +```none +vyos@vyos:~$ show dhcp server leases +IP Address MAC address State Lease start Lease expiration Remaining Pool Hostname Origin +-------------- ----------------- ------- ------------------- ------------------- ----------- -------- ---------- -------- +192.168.11.134 00:50:79:66:68:09 active 2023/11/29 09:51:05 2023/11/29 10:21:05 0:24:10 LAN VPCS1 local +192.168.11.133 50:00:00:06:00:00 active 2023/11/29 09:51:38 2023/11/29 10:21:38 0:24:43 LAN VYOS-6 local +10.11.11.108 50:00:00:05:00:00 active 2023/11/29 09:51:43 2023/11/29 10:21:43 0:24:48 VIF-1001 VYOS5 local +192.168.11.135 00:50:79:66:68:07 active 2023/11/29 09:55:16 2023/11/29 09:59:16 0:02:21 remote +vyos@vyos:~$ +``` + +:::{hint} +Static mappings aren't shown. To show all states, use +`show dhcp server leases state all`. +::: + +```{opcmd} show dhcp server leases origin [local | remote] + +Show statuses of all active leases granted by local (this server) or +remote (failover server): +``` + + +```none +vyos@vyos:~$ show dhcp server leases origin remote +IP Address MAC address State Lease start Lease expiration Remaining Pool Hostname Origin +-------------- ----------------- ------- ------------------- ------------------- ----------- -------- ---------- -------- +192.168.11.135 00:50:79:66:68:07 active 2023/11/29 09:55:16 2023/11/29 09:59:16 0:02:21 remote +vyos@vyos:~$ +``` + + +```{opcmd} show dhcp server leases pool \<pool\> + +Show only leases in the specified pool. +``` + + +```none +vyos@vyos:~$ show dhcp server leases pool LAN +IP Address MAC address State Lease start Lease expiration Remaining Pool Hostname Origin +-------------- ----------------- ------- ------------------- ------------------- ----------- ------ ---------- -------- +192.168.11.134 00:50:79:66:68:09 active 2023/11/29 09:51:05 2023/11/29 10:21:05 0:23:55 LAN VPCS1 local +192.168.11.133 50:00:00:06:00:00 active 2023/11/29 09:51:38 2023/11/29 10:21:38 0:24:28 LAN VYOS-6 local +vyos@vyos:~$ +``` + + +```{opcmd} show dhcp server leases sort \<key\> + +Sort the output by the specified key. Possible keys: ip, hardware_address, +state, start, end, remaining, pool, hostname (default = ip) +``` + + +```{opcmd} show dhcp server leases state \<state\> + +Show only leases with the specified state. Possible states: all, active, +free, expired, released, abandoned, reset, backup (default = active) +``` + +## IPv6 server + +VyOS also provides DHCPv6 server functionality which is described in this +section. +(dhcp-server-v6-config)= + +### Configuration + +```{cfgcmd} set service dhcpv6-server preference \<preference value\> + + Clients receiving advertise messages from multiple servers choose the server + with the highest preference value. The range for this value is ``0...255``. +``` + + +```{cfgcmd} set service dhcpv6-server shared-network-name \<name\> subnet \<subnet\> subnet-id \<id\> + +This configuration parameter is required and must be unique to each subnet. +It is required to map subnets to lease file entries. +``` + + +```{cfgcmd} set service dhcpv6-server shared-network-name \<name\> subnet \<prefix\> lease-time {default | maximum | minimum} + +The default lease time for DHCPv6 leases is 24 hours. This can be changed by +supplying a ``default-time``, ``maximum-time`` and ``minimum-time``. All +values need to be supplied in seconds. +``` + + +```{cfgcmd} set service dhcpv6-server shared-network-name \<name\> subnet \<prefix\> option nis-domain \<domain-name\> + +A {abbr}`NIS (Network Information Service)` domain can be set to be used for +DHCPv6 clients. +``` + + +```{cfgcmd} set service dhcpv6-server shared-network-name \<name\> subnet \<prefix\> option nisplus-domain \<domain-name\> + +The procedure to specify a {abbr}`NIS+ (Network Information Service Plus)` +domain is similar to the NIS domain one: +``` + + +```{cfgcmd} set service dhcpv6-server shared-network-name \<name\> subnet \<prefix\> option nis-server \<address\> + +Specify a NIS server address for DHCPv6 clients. +``` + + +```{cfgcmd} set service dhcpv6-server shared-network-name \<name\> subnet \<prefix\> option nisplus-server \<address\> + +Specify a NIS+ server address for DHCPv6 clients. +``` + + +```{cfgcmd} set service dhcpv6-server shared-network-name \<name\> subnet \<prefix\> option sip-server \<address | fqdn\> + +Specify a {abbr}`SIP (Session Initiation Protocol)` server by IPv6 +address of Fully Qualified Domain Name for all DHCPv6 clients. +``` + + +```{cfgcmd} set service dhcpv6-server shared-network-name \<name\> subnet \<prefix\> option sntp-server-address \<address\> + +A SNTP server address can be specified for DHCPv6 clients. +``` + +#### Prefix Delegation + + +To hand out individual prefixes to your clients the following configuration is +used: + +```{cfgcmd} set service dhcpv6-server shared-network-name \<name\> subnet \<prefix\> prefix-delegation prefix \<pd-prefix\> prefix-length \<length\> + +Delegate prefixes from `<pd-prefix>` to clients in subnet `<prefix>`. Range +is defined by `<length>` in bits, 32 to 64. +``` + + +```{cfgcmd} set service dhcpv6-server shared-network-name \<name\> subnet \<prefix\> prefix-delegation prefix \<pd-prefix\> delegated-length \<length\> + +Hand out prefixes of size `<length>` in bits from `<pd-prefix>` to clients +in subnet `<prefix>` when the request for prefix delegation. +``` + + +```{cfgcmd} set service dhcpv6-server shared-network-name \<name\> subnet \<prefix\> prefix-delegation prefix \<pd-prefix\> excluded-prefix \<exclude-prefix\> + +Exclude `<exclude-prefix>` from `<pd-prefix>`. +``` +```{cfgcmd} set service dhcpv6-server shared-network-name \<name\> subnet \<prefix\> prefix-delegation prefix \<pd-prefix\> excluded-prefix-length \<length\> + +Define length of exclude prefix in `<pd-prefix>`. +``` + +**Example:** +- A shared network named `PD-NET` serves subnet `2001:db8::/64`. +- It is connected to `eth1`. +- Address pool shall be `2001:db8::100` through `2001:db8::199`. +- It hands out prefixes `2001:db8:0:10::/64` through `2001:db8:0:1f::/64`. + +```none +set service dhcpv6-server shared-network-name 'PD-NET' interface 'eth1' +set service dhcpv6-server shared-network-name 'PD-NET' subnet 2001:db8::/64 range 1 start 2001:db8::100 +set service dhcpv6-server shared-network-name 'PD-NET' subnet 2001:db8::/64 range 1 stop 2001:db8::199 +set service dhcpv6-server shared-network-name 'PD-NET' subnet 2001:db8::/64 prefix-delegation prefix 2001:db8:0:10:: delegated-length '64' +set service dhcpv6-server shared-network-name 'PD-NET' subnet 2001:db8::/64 prefix-delegation prefix 2001:db8:0:10:: prefix-length '60' +set service dhcpv6-server shared-network-name 'PD-NET' subnet 2001:db8::/64 subnet-id 1 +``` + +#### Address pools + +DHCPv6 address pools must be configured for the system to act as a DHCPv6 +server. The following example describes a common scenario. + +**Example:** +- A shared network named `NET1` serves subnet `2001:db8::/64` +- It is connected to `eth1` +- DNS server is located at `2001:db8::ffff` +- Address pool shall be `2001:db8::100` through `2001:db8::199`. +- Lease time will be left at the default value which is 24 hours + +```none +set service dhcpv6-server shared-network-name 'NET' interface 'eth1' +set service dhcpv6-server shared-network-name 'NET1' subnet 2001:db8::/64 range 1 start 2001:db8::100 +set service dhcpv6-server shared-network-name 'NET1' subnet 2001:db8::/64 range 1 stop 2001:db8::199 +set service dhcpv6-server shared-network-name 'NET1' subnet 2001:db8::/64 option name-server 2001:db8::ffff +set service dhcpv6-server shared-network-name 'NET1' subnet 2001:db8::/64 subnet-id 1 +``` + +The configuration will look as follows: + +```none +show service dhcpv6-server + shared-network-name NET1 { + subnet 2001:db8::/64 { + range 1 { + start 2001:db8::100 + stop 2001:db8::199 + } + option { + name-server 2001:db8::ffff + } + subnet-id 1 + } + } +``` + +(dhcp-server-v6-static-mapping)= + +#### Static mappings + +In order to map specific IPv6 addresses to specific hosts static mappings can +be created. The following example explains the process. + +**Example:** +- IPv6 address `2001:db8::101` shall be statically mapped +- IPv6 prefix `2001:db8:0:101::/64` shall be statically mapped +- Host specific mapping shall be named `client1` + +:::{hint} +The identifier is the device's DUID: colon-separated hex list (as +used by isc-dhcp option dhcpv6.client-id). If the device already has a +dynamic lease from the DHCPv6 server, its DUID can be found with `show +service dhcpv6 server leases`. The DUID begins at the 5th octet (after the +4th colon) of IAID_DUID. +::: +```none +set service dhcpv6-server shared-network-name 'NET1' subnet 2001:db8::/64 static-mapping client1 ipv6-address 2001:db8::101 +set service dhcpv6-server shared-network-name 'NET1' subnet 2001:db8::/64 static-mapping client1 ipv6-prefix 2001:db8:0:101::/64 +set service dhcpv6-server shared-network-name 'NET1' subnet 2001:db8::/64 static-mapping client1 duid 00:01:00:01:12:34:56:78:aa:bb:cc:dd:ee:ff +``` + +The configuration will look as follows: + +```none +show service dhcpv6-server shared-network-name NET1 + subnet 2001:db8::/64 { + static-mapping client1 { + duid 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 + } + } +``` + +(dhcp-server-v6-op-cmd)= + +### 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 +``` +```{opcmd} show dhcpv6 server leases + +Shows status of all assigned leases: +``` +```none +vyos@vyos:~$ show dhcpv6 server leases +IPv6 address State Last communication Lease expiration Remaining Type Pool DUID +---------------- ------- -------------------- ------------------- ----------- ----- -------- -------------------------------------------- +2001:db8::101 active 2019/12/05 19:40:10 2019/12/06 07:40:10 11:45:21 IA_NA NET1 98:76:54:32:00:01:00:01:12:34:56:78:aa:bb:cc:dd:ee:ff +2001:db8::102 active 2019/12/05 14:01:23 2019/12/06 02:01:23 6:06:34 IA_NA NET1 87:65:43:21:00:01:00:01:11:22:33:44:fa:fb:fc:fd:fe:ff +2001:db8:10::/64 active 2019/12/05 23:20:10 2019/12/06 11:40:10 11:45:21 IA_PD PD-NET1 98:76:54:32:00:01:00:01:12:34:56:78:aa:bb:cc:dd:ee:ff +``` + +:::{hint} +Static mappings aren't shown. To show all states, use `show dhcp +server leases state all`. +::: + +```{opcmd} show dhcpv6 server leases pool \<pool\> + +Show only leases in the specified pool. +``` +```{opcmd} show dhcpv6 server leases sort \<key\> + +Sort the output by the specified key. Possible keys: expires, iaid_duid, ip, +last_comm, pool, remaining, state, type (default = ip) +``` +```{opcmd} show dhcpv6 server leases state \<state\> + +Show only leases with the specified state. Possible states: abandoned, +active, all, backup, expired, free, released, reset (default = active) +```
\ No newline at end of file diff --git a/docs/configuration/service/dns.md b/docs/configuration/service/dns.md new file mode 100644 index 00000000..e7e9b457 --- /dev/null +++ b/docs/configuration/service/dns.md @@ -0,0 +1,582 @@ +(dns-forwarding)= + +# DNS Forwarding + +## Configuration + +VyOS provides DNS infrastructure for small networks. It is designed to be +lightweight and have a small footprint, suitable for resource constrained +routers and firewalls. For this we utilize PowerDNS recursor. + +The VyOS DNS forwarder does not require an upstream DNS server. It can serve as +a full recursive DNS server - but it can also forward queries to configurable +upstream DNS servers. By not configuring any upstream DNS servers you also +avoid being tracked by the provider of your upstream DNS server. + +```{cfgcmd} set service dns forwarding system + + 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\> port \<port\> + +Send all DNS queries to the IPv4/IPv6 DNS server specified under `<address>` +on optional port specified under `<port>`. The port defaults to 53. You can +configure multiple nameservers here. +``` + + +```{cfgcmd} set service dns forwarding domain \<domain-name\> name-server \<address\> + +Forward received queries for a particular domain +(specified via `domain-name`) to a given nameserver. Multiple nameservers +can be specified. You can use this feature for a DNS split-horizon +configuration. + +:::{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 +attacks, you must configure the networks which are allowed to use this +recursor. A network of ``0.0.0.0/0`` or ``::/0`` would allow all IPv4 and +IPv6 networks to query this server. This is generally a bad idea. +``` + + +```{cfgcmd} set service dns forwarding dnssec \<off | process-no-validate | process | log-fail | validate\> + +The PowerDNS recursor has 5 different levels of DNSSEC processing, which can +be set with the dnssec setting. In order from least to most processing, these +are: + +* **off** In this mode, no DNSSEC processing takes place. The recursor will +not set the DNSSEC OK (DO) bit in the outgoing queries and will ignore the +DO and AD bits in queries. + +* **process-no-validate** In this mode the recursor acts as a "security +aware, non-validating" nameserver, meaning it will set the DO-bit on +outgoing queries and will provide DNSSEC related RRsets (NSEC, RRSIG) to +clients that ask for them (by means of a DO-bit in the query), except for +zones provided through the auth-zones setting. It will not do any +validation in this mode, not even when requested by the client. + +* **process** When dnssec is set to process the behavior is similar to +process-no-validate. However, the recursor will try to validate the data +if at least one of the DO or AD bits is set in the query; in that case, +it will set the AD-bit in the response when the data is validated +successfully, or send SERVFAIL when the validation comes up bogus. + +* **log-fail** In this mode, the recursor will attempt to validate all data +it retrieves from authoritative servers, regardless of the client's DNSSEC +desires, and will log the validation result. This mode can be used to +determine the extra load and amount of possibly bogus answers before +turning on full-blown validation. Responses to client queries are the same +as with process. + +* **validate** The highest mode of DNSSEC processing. In this mode, all +queries will be validated and will be answered with a SERVFAIL in case of +bogus data, regardless of the client's request. + +:::{note} +The popular Unix/Linux ``dig`` tool sets the AD-bit in the query. +This might lead to unexpected query results when testing. Set ``+noad`` +on the ``dig`` command line when this is the case. +::: + +:::{note} +The ``CD``-bit is honored correctly for process and validate. For +log-fail, failures will be logged too. +::: +``` + + +```{cfgcmd} set service dns forwarding ignore-hosts-file + +Do not use the local ``/etc/hosts`` file in name resolution. VyOS DHCP +server will use this file to add resolvers to assigned addresses. +``` + + +```{cfgcmd} set service dns forwarding cache-size \<0-2147483647\> + +Maximum number of DNS cache entries. 1 million per CPU core will generally +suffice for most installations. + +This defaults to 10000. +``` + + +```{cfgcmd} set service dns forwarding negative-ttl \<0-7200\> + +A query for which there is authoritatively no answer is cached to quickly +deny a record's existence later on, without putting a heavy load on the +remote server. In practice, caches can become saturated with hundreds of +thousands of hosts which are tried only once. + +This setting, which defaults to 3600 seconds, puts a maximum on the amount +of time negative entries are cached. +``` + + +```{cfgcmd} set service dns forwarding timeout \<10-60000\> + +The number of milliseconds to wait for a remote authoritative server to +respond before timing out and responding with SERVFAIL. + +This setting defaults to 1500 and is valid between 10 and 60000. +``` + + +```{cfgcmd} set service dns forwarding listen-address \<address\> + +The local IPv4 or IPv6 addresses to bind the DNS forwarder to. The forwarder +will listen on this address for incoming connections. +``` + + +```{cfgcmd} set service dns forwarding source-address \<address\> + +The local IPv4 or IPv6 addresses to use as a source address for sending queries. +The forwarder will send forwarded outbound DNS requests from this address. +``` + + +```{cfgcmd} set service dns forwarding no-serve-rfc1918 + +This makes the server authoritatively not aware of: 10.in-addr.arpa, +168.192.in-addr.arpa, 16-31.172.in-addr.arpa, which enabling upstream +DNS server(s) to be used for reverse lookups of these zones. +``` + +### Authoritative zones + + +The VyOS DNS forwarder can also be configured to host authoritative records for a domain. + +```{cfgcmd} set service dns forwarding authoritative-domain \<domain-name\> disable + +Disable hosting authoritative zone for `<domain-name>` without deleting from +configuration. +``` + + +```{cfgcmd} set service dns forwarding authoritative-domain \<domain-name\> records \<type\> \<name\> disable + +Disable specific record without deleting it from configuration. +``` + + +```{cfgcmd} set service dns forwarding authoritative-domain \<domain-name\> records \<type\> \<name\> ttl \<seconds\> + +Set the {abbr}`TTL (Time-to-live)` for the record in seconds. Default is 300 seconds. +``` + +#### Record types + + +Below are a list of record types available to be configured within VyOS. Some records +support special `<name>` keywords: + + +- `@` Use @ as record name to set the record for the root domain. +- `any` Use any as record name to configure the record as a wildcard. + +```{cfgcmd} set service dns forwarding authoritative-domain \<domain-name\> records a \<name\> address \<x.x.x.x\> + +Set an {abbr}`A (Address)` record. Supports ``@`` and ``any`` keywords. +``` + + +```{cfgcmd} set service dns forwarding authoritative-domain \<domain-name\> records aaaa \<name\> address \<h:h:h:h:h:h:h:h\> + +Set an {abbr}`AAAA (IPv6 Address)` record. Supports ``@`` and ``any`` keywords. +``` + + +```{cfgcmd} set service dns forwarding authoritative-domain \<domain-name\> records cname \<name\> target \<target-domain-name\> + +Set an {abbr}`CNAME (Canonical name)` record. Supports ``@`` keyword. +``` + + +```{cfgcmd} set service dns forwarding authoritative-domain \<domain-name\> records naptr \<name\> rule \<rule-number\> \<option\> \<value\> + +Set an {abbr}`NAPTR (Naming authority pointer)` record. Supports ``@`` keyword. +NAPTR records support the following options: + +* **lookup-a** A Flag. + +* **lookup-srv** S flag. + +* **order** Rule order. Requires `<value>`. + +* **preference** Rule preference. Requires `<value>`. Defaults to 0 if not set. + +* **protocol-specific** P flag. + +* **regexp** Regular expression. Requires `<value>`. + +* **replacement** Replacement DNS name. + +* **resolve-uri** U flag. + +* **service** Service type. Requires `<value>`. +``` + + +```{cfgcmd} set service dns forwarding authoritative-domain \<domain-name\> records ns \<name\> target \<target-name\> + +Set an {abbr}`NS (Nameserver)` record. +``` + + +```{cfgcmd} set service dns forwarding authoritative-domain \<domain-name\> records ptr \<name\> target \<target-name\> + +Set an {abbr}`PTR (Pointer record)` record. Supports ``@`` keyword. +``` + + +```{cfgcmd} set service dns forwarding authoritative-domain \<domain-name\> records spf \<name\> value \<value\> + +Set an {abbr}`SPF (Sender policy framework)` record. Supports ``@`` keyword. +``` + + +```{cfgcmd} set service dns forwarding authoritative-domain \<domain-name\> records srv \<name\> entry \<entry-number\> [hostname | port | priority | weight] \<value\> + +Set an {abbr}`SRV (Service)` record. Supports ``@`` keyword. +``` + + +```{cfgcmd} set service dns forwarding authoritative-domain \<domain-name\> records txt \<name\> value \<value\> + +Set an {abbr}`TXT (Text)` record. Supports ``@`` keyword. +``` + +## Example + + +A VyOS router with two interfaces - eth0 (WAN) and eth1 (LAN) - is required to +implement a split-horizon DNS configuration for example.com. + + +In this scenario: + + +- All DNS requests for example.com must be forwarded to a DNS server + at 192.0.2.254 and 2001:db8:cafe::1 +- All other DNS requests will be forwarded to a different set of DNS servers at + 192.0.2.1, 192.0.2.2, 2001:db8::1:ffff and 2001:db8::2:ffff +- The VyOS DNS forwarder will only listen for requests on the eth1 (LAN) + interface addresses - 192.168.1.254 for IPv4 and 2001:db8::ffff for IPv6 +- The VyOS DNS forwarder will only accept lookup requests from the + LAN subnets - 192.168.1.0/24 and 2001:db8::/64 +- The VyOS DNS forwarder will pass reverse lookups for 10.in-addr.arpa, + 168.192.in-addr.arpa, 16-31.172.in-addr.arpa zones to upstream server. + +```none +set service dns forwarding domain example.com name-server 192.0.2.254 +set service dns forwarding domain example.com name-server 2001:db8:cafe::1 +set service dns forwarding name-server 192.0.2.1 +set service dns forwarding name-server 192.0.2.2 +set service dns forwarding name-server 192.0.2.3 port 853 +set service dns forwarding name-server 2001:db8::1:ffff +set service dns forwarding name-server 2001:db8::2:ffff +set service dns forwarding name-server 2001:db8::3:ffff port 8053 +set service dns forwarding listen-address 192.168.1.254 +set service dns forwarding listen-address 2001:db8::ffff +set service dns forwarding allow-from 192.168.1.0/24 +set service dns forwarding allow-from 2001:db8::/64 +set service dns forwarding no-serve-rfc1918 +``` + +## Operation + +```{opcmd} reset dns forwarding \<all | domain\> + +Resets the local DNS forwarding cache database. You can reset the cache +for all entries or only for entries to a specific domain. +``` + + +```{opcmd} restart dns forwarding + +Restarts the DNS recursor process. This also invalidates the local DNS +forwarding cache. +``` + +(dynamic-dns)= + +# Dynamic DNS + +VyOS is able to update a remote DNS record when an interface gets a new IP +address. In order to do so, VyOS includes [ddclient], a Perl script written for +this only one purpose. + +[ddclient] uses two methods to update a DNS record. The first one will send +updates directly to the DNS daemon, in compliance with {rfc}`2136`. The second +one involves a third party service, like DynDNS.com or any other such +service provider. This method uses HTTP requests to transmit the new IP address. +You can configure both in VyOS. +(dns-dynamic-config)= + +## Configuration +### {rfc}`2136` Based + +```{cfgcmd} set service dns dynamic name \<service-name\> address interface \<interface\> + + Create new dynamic DNS update configuration which will update the IP + address assigned to `<interface>` on the service you configured under + `<service-name>`. +``` + + +```{cfgcmd} set service dns dynamic name \<service-name\> description \<text\> + +Set description `<text>` for dynamic DNS service being configured. +``` + + +```{cfgcmd} set service dns dynamic name \<service-name\> key \<filename\> + +File identified by `<filename>` containing the TSIG authentication key for RFC2136 +nsupdate on remote DNS server. +``` + + +```{cfgcmd} set service dns dynamic name \<service-name\> server \<server\> + +Configure the DNS `<server>` IP/FQDN used when updating this dynamic +assignment. +``` + + +```{cfgcmd} set service dns dynamic name \<service-name\> zone \<zone\> + +Configure DNS `<zone>` to be updated. +``` + + +```{cfgcmd} set service dns dynamic name \<service-name\> host-name \<record\> + +Configure DNS `<record>` which should be updated. This can be set multiple times. +``` + + +```{cfgcmd} set service dns dynamic name \<service-name\> ttl \<ttl\> + +Configure optional TTL value on the given resource record. This defaults to +600 seconds. +``` + + +```{cfgcmd} set service dns dynamic interval \<60-3600\> + +Specify interval in seconds to wait between Dynamic DNS updates. +The default is 300 seconds. +``` + +(dns-dynamic-example)= + + +#### Example + + +- Register DNS record `example.vyos.io` on DNS server `ns1.vyos.io` +- Use auth key file at `/config/auth/my.key` +- Set TTL to 300 seconds + +```none +# Configuration commands entered: +# +set service dns dynamic name 'VyOS-DNS' address interface 'eth0' +set service dns dynamic name 'VyOS-DNS' description 'RFC 2136 dynamic dns service' +set service dns dynamic name 'VyOS-DNS' key '/config/auth/my.key' +set service dns dynamic name 'VyOS-DNS' server 'ns1.vyos.io' +set service dns dynamic name 'VyOS-DNS' zone 'vyos.io' +set service dns dynamic name 'VyOS-DNS' host-name 'example.vyos.io' +set service dns dynamic name 'VyOS-DNS' protocol 'nsupdate' +set service dns dynamic name 'VyOS-DNS' ttl '300' + +# Resulting config: +# +vyos@vyos# show service dns dynamic + name VyOS-DNS { + address { + interface eth0 + } + description "RFC 2136 dynamic dns service" + host-name example.vyos.io + key /config/auth/my.key + protocol nsupdate + server ns1.vyos.io + ttl 300 + zone vyos.io + } +``` + +This will render the following [ddclient] configuration entry: + +```none +# ddclient configuration for interface "eth0": +# + +# Web service dynamic DNS configuration for VyOS-DNS: [nsupdate, example.vyos.io] +use=if, \ +if=eth0, \ +protocol=nsupdate, \ +server=ns1.vyos.io, \ +zone=vyos.io, \ +password='/config/auth/my.key', \ +ttl=300 \ +example.vyos.io +``` + +:::{note} +You can also keep different DNS zone updated. Just create a new +config node: `set service dns dynamic interface <interface> rfc2136 +<other-service-name>` +::: + + +### HTTP based services + + +VyOS is also able to use any service relying on protocols supported by ddclient. + + +To use such a service, one must define a login, password, one or multiple +hostnames, protocol and server. + +```{cfgcmd} set service dns dynamic name \<service-name\> address interface \<interface\> + +Create new dynamic DNS update configuration which will update the IP +address assigned to `<interface>` on the service you configured under +`<service-name>`. +``` + + +```{cfgcmd} set service dns dynamic name \<service-name\> description \<text\> + +Set description `<text>` for dynamic DNS service being configured. +``` + + +```{cfgcmd} set service dns dynamic name \<service-name\> host-name \<hostname\> + +Setup the dynamic DNS hostname `<hostname>` associated with the DynDNS +provider identified by `<service-name>`. +``` + + +```{cfgcmd} set service dns dynamic name \<service-name\> username \<username\> + +Configure `<username>` used when authenticating the update request for +DynDNS service identified by `<service-name>`. +``` + + +```{cfgcmd} set service dns dynamic name \<service-name\> password \<password\> + +Configure `<password>` used when authenticating the update request for +DynDNS service identified by `<service-name>`. +``` + + +```{cfgcmd} set service dns dynamic name \<service-name\> protocol \<protocol\> + +When a ``custom`` DynDNS provider is used, the protocol used for communicating +to the provider must be specified under `<protocol>`. See the embedded +completion helper when entering above command for available protocols. +``` + + +```{cfgcmd} set service dns dynamic name \<service-name\> server \<server\> + +When a ``custom`` DynDNS provider is used the `<server>` where update +requests are being sent to must be specified. +``` + + +```{cfgcmd} set service dns dynamic name \<service-name\> ip-version 'ipv6' + +Allow explicit IPv6 address for the interface. +``` + +#### Example: + +Use deSEC (dedyn.io) as your preferred provider: + +```none +set service dns dynamic name dedyn description 'deSEC dynamic dns service' +set service dns dynamic name dedyn username 'myusername' +set service dns dynamic name dedyn password 'mypassword' +set service dns dynamic name dedyn host-name 'myhostname.dedyn.io' +set service dns dynamic name dedyn protocol 'dyndns2' +set service dns dynamic name dedyn server 'update.dedyn.io' +set service dns dynamic name dedyn address interface 'eth0' +``` + +:::{note} +Multiple services can be used per interface. Just specify as many +services per interface as you like! +::: +#### Example IPv6 only: + +```none +set service dns dynamic name dedyn description 'deSEC ipv6 dynamic dns service' +set service dns dynamic name dedyn username 'myusername' +set service dns dynamic name dedyn password 'mypassword' +set service dns dynamic name dedyn host-name 'myhostname.dedyn.io' +set service dns dynamic name dedyn protocol 'dyndns2' +set service dns dynamic name dedyn ip-version 'ipv6' +set service dns dynamic name dedyn server 'update6.dedyn.io' +set service dns dynamic name dedyn address interface 'eth0' +``` + +### Running Behind NAT + +By default, [ddclient] will update a dynamic dns record using the IP address +directly attached to the interface. If your VyOS instance is behind NAT, your +record will be updated to point to your internal IP. + +[ddclient] has another way to determine the WAN IP address. This is controlled +by: + +```{cfgcmd} set service dns dynamic name \<service-name\> address web \<url\> + +Use configured `<url>` to determine your IP address. [ddclient] will load +`<url>` and tries to extract your IP address from the response. +``` +```{cfgcmd} set service dns dynamic name \<service-name\> address web skip \<pattern\> + +ddclient will skip any address located before the string set in `<pattern>`. +``` + +[ddclient]: https://github.com/ddclient/ddclient diff --git a/docs/configuration/service/eventhandler.md b/docs/configuration/service/eventhandler.md new file mode 100644 index 00000000..6413c24d --- /dev/null +++ b/docs/configuration/service/eventhandler.md @@ -0,0 +1,129 @@ +(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](#create-an-event-handler) +> +> [2. Add regex to the script](#add-regex-to-the-script) +> +> [3. Add a full path to the script](#add-a-full-path-to-the-script) +> +> [4. Add optional parameters](#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 \<syslogid 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 recommend using arguments. Using environment variables is preferable. +::: +``` + + +## Example + +Event handler that monitors the state of interface eth0. + +```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 'eth0' +set service event-handler event INTERFACE_STATE_DOWN script path '/config/scripts/eventhandler.py' +``` + +Event handler script + +```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.md b/docs/configuration/service/https.md new file mode 100644 index 00000000..184fd088 --- /dev/null +++ b/docs/configuration/service/https.md @@ -0,0 +1,138 @@ +(http-api)= + +# HTTP API + +VyOS provide an HTTP API. You can use it to execute op-mode commands, +update VyOS, set or delete config. + +Please take a look at the {ref}`vyosapi` page for an detailed how-to. + +## Configuration + +```{cfgcmd} set service https allow-client address \<address\> + +Only allow certain IP addresses or prefixes to access the https +webserver. +``` + +```{cfgcmd} set service https certificates ca-certificate \<name\> + +Use CA certificate from PKI subsystem +``` + +```{cfgcmd} set service https certificates certificate \<name\> + +Use certificate from PKI subsystem +``` + +```{cfgcmd} set service https certificates dh-params \<name\> + +Use {abbr}`DH (Diffie–Hellman)` parameters from PKI subsystem. +Must be at least 2048 bits in length. +``` + +```{cfgcmd} set service https listen-address \<address\> + +Webserver should only listen on specified IP address +``` + +```{cfgcmd} set service https port \<number\> + +Webserver should listen on specified port. + +Default: 443 +``` + +```{cfgcmd} set service https enable-http-redirect + +Enable automatic redirect from http to https. +``` + +```{cfgcmd} set service https tls-version \<1.2 | 1.3\> + +Select TLS version used. + +This defaults to both 1.2 and 1.3. +``` + +```{cfgcmd} set service https vrf \<name\> + +Start Webserver in given VRF. +``` + +```{cfgcmd} set service https request-body-size-limit \<size\> + +Set the maximum request body size in megabytes. Default is 1MB. +``` + + +### API + +```{cfgcmd} set service https api keys id \<name\> key \<apikey\> + +Set a named api key. Every key has the same, full permissions +on the system. +``` + + +### REST + +```{cfgcmd} set service https api rest + +Enable REST API +``` + +```{cfgcmd} set service https api rest debug + +To enable debug messages. Available via {opcmd}`show log` or +{opcmd}`monitor log` +``` + +```{cfgcmd} set service https api rest strict + +Enforce strict path checking. +``` + + +### GraphQL + +```{cfgcmd} set service https api graphql introspection + +Enable GraphQL Schema introspection. +``` + +:::{note} +Do not leave introspection enabled in production, it is a security risk. +::: + +```{cfgcmd} set service https api graphql authentication type \<key | token\> + +Set the authentication type for GraphQL, default option is key. Available options are: +* ``key`` use API keys configured in ``service https api keys`` +* ``token`` use JWT tokens. +``` + +```{cfgcmd} set service https api graphql authentication expiration + +Set the lifetime for JWT tokens in seconds. Default is 3600 seconds. +``` + +```{cfgcmd} set service https api graphql authentication secret-length + +Set the byte length of the JWT secret. Default is 32. +``` + +```{cfgcmd} set service https api graphql cors allow-origin \<origin\> + +Allow cross-origin requests from \<origin\>. +``` + + +## Example Configuration + +Setting REST API and an API-KEY is the minimal configuration to get a working API Endpoint. + +```none +set service https api keys id MY-HTTPS-API-ID key MY-HTTPS-API-PLAINTEXT-KEY +set service https api rest +``` diff --git a/docs/configuration/service/index.md b/docs/configuration/service/index.md new file mode 100644 index 00000000..4018c5be --- /dev/null +++ b/docs/configuration/service/index.md @@ -0,0 +1,29 @@ +# Service + +```{toctree} +:includehidden: true +:maxdepth: 1 + +broadcast-relay +config-sync +conntrack-sync +console-server +dhcp-relay +dhcp-server +dns +eventhandler +https +ipoe-server +lldp +mdns +monitoring +ntp +pppoe-server +router-advert +salt-minion +snmp +ssh +tftp-server +webproxy +suricata +``` diff --git a/docs/configuration/service/ipoe-server.md b/docs/configuration/service/ipoe-server.md new file mode 100644 index 00000000..f1ef2a63 --- /dev/null +++ b/docs/configuration/service/ipoe-server.md @@ -0,0 +1,512 @@ +(ipoe-server)= + +# IPoE Server + +VyOS utilizes [accel-ppp] to provide {abbr}`IPoE (Internet Protocol over +Ethernet)` server functionality. It can be used with local authentication +(mac-address) or a connected RADIUS server. + +IPoE is a method of delivering an IP payload over an Ethernet-based access +network or an access network using bridged Ethernet over Asynchronous Transfer +Mode (ATM) without using PPPoE. It directly encapsulates the IP datagrams in +Ethernet frames, using the standard {rfc}`894` encapsulation. + +The use of IPoE addresses the disadvantage that PPP is unsuited for multicast +delivery to multiple users. Typically, IPoE uses Dynamic Host Configuration +Protocol and Extensible Authentication Protocol to provide the same +functionality as PPPoE, but in a less robust manner. + +:::{note} +Please be aware, due to an upstream bug, config changes/commits +will restart the ppp daemon and will reset existing IPoE sessions, +in order to become effective. +::: + +## Configuring IPoE Server + +IPoE can be configured on different interfaces, it will depend on each specific +situation which interface will provide IPoE to clients. The client's mac address +and the incoming interface is being used as control parameter, to authenticate +a client. + +The example configuration below will assign an IP to the client on the incoming +interface eth1 with the client mac address 00:50:79:66:68:00. Other DHCP +discovery requests will be ignored, unless the client mac has been enabled in +the configuration. + +```none +set interfaces ethernet eth1 address '192.168.0.1/24' +set service ipoe-server authentication interface eth1.100 mac 00:50:79:66:68:00 +set service ipoe-server authentication interface eth1.101 mac 00:50:79:66:68:01 +set service ipoe-server authentication mode 'local' +set service ipoe-server client-ip-pool IPOE-POOL range '192.168.0.2-192.168.0.254' +set service ipoe-server default-pool 'IPOE-POOL' +set service ipoe-server gateway-address '192.168.0.1/24' +set service ipoe-server interface eth1 mode 'l2' +set service ipoe-server interface eth1 network 'vlan' +set service ipoe-server interface eth1 vlan '100-200' +``` + +```{cfgcmd} set service ipoe-server authentication interface \<interface\> mac \<MAC\> + +Creates local IPoE user with username=\*\*\<interface\>\*\* and +password=\*\*\<MAC\>\*\* (mac-address) +``` + + +```{cfgcmd} set service ipoe-server authentication mode \<local | radius\> + +Set authentication backend. The configured authentication backend is used +for all queries. + +* **radius**: All authentication queries are handled by a configured RADIUS +server. +* **local**: All authentication queries are handled locally. +* **noauth**: Authentication disabled +``` + + +```{cfgcmd} set service ipoe-server client-ip-pool \<POOL-NAME\> range \<x.x.x.x-x.x.x.x | x.x.x.x/x\> + +Use this command to define the first IP address of a pool of +addresses to be given to IPoE clients. If notation ``x.x.x.x-x.x.x.x``, +it must be within a /24 subnet. If notation ``x.x.x.x/x`` is +used there is possibility to set host/netmask. +``` + + +```{cfgcmd} set service ipoe-server default-pool \<POOL-NAME\> + +Use this command to define default address pool name. +``` + + +```{cfgcmd} set service ipoe-server gateway-address \<x.x.x.x/x\> + +Specifies address to be used as server ip address if radius can assign +only client address. In such case if client address is matched network +and mask then specified address and mask will be used. You can specify +multiple such options. +``` + + +```{cfgcmd} set service ipoe-server interface \<interface\> mode \<l2 | l3\> + +> Specifies the client connectivity mode. + +* **l2**: It means that clients are on same network where interface +is.\*\*(default)\*\* +* **l3**: It means that client are behind some router. +``` + + +```{cfgcmd} set service ipoe-server interface \<interface\> network \<shared | vlan\> + +Specify where interface is shared by multiple users or it is vlan-per-user. + +* **shared**: Multiple clients share the same network. **(default)** +* **vlan**: One VLAN per client. +``` + + +```none +vyos@vyos:~$ show ipoe-server sessions + + ifname | username | calling-sid | ip | rate-limit | type | comp | state | uptime +--------+----------+-------------------+-------------+------------+------+------+--------+---------- + ipoe0 | eth1.100 | 00:50:79:66:68:00 | 192.168.0.2 | | ipoe | | active | 00:04:55 + ipoe1 | eth1.101 | 00:50:79:66:68:01 | 192.168.0.3 | | ipoe | | active | 00:04:44 +``` + +## Configuring RADIUS authentication + + +To enable RADIUS based authentication, the authentication mode needs to be +changed within the configuration. Previous settings like the local users, still +exists within the configuration, however they are not used if the mode has been +changed from local to radius. Once changed back to local, it will use all local +accounts again. + +```none +set service ipoe-server authentication mode radius +``` + + +```{cfgcmd} set service ipoe-server authentication radius server \<server\> key \<secret\> + +Configure RADIUS *\<server\>* and its required shared *\<secret\>* for +communicating with the RADIUS server. +``` + +Since the RADIUS server would be a single point of failure, multiple RADIUS +servers can be setup and will be used subsequentially. +For example: + +```none +set service ipoe-server authentication radius server 10.0.0.1 key 'foo' +set service ipoe-server authentication radius server 10.0.0.2 key 'foo' +``` + +:::{note} +Some RADIUS severs use an access control list which allows or denies +queries, make sure to add your VyOS router to the allowed client list. +::: + + +### RADIUS source address + + +If you are using OSPF as IGP, always the closest interface connected to the +RADIUS server is used. With VyOS 1.2 you can bind all outgoing RADIUS requests +to a single source IP e.g. the loopback interface. + +```{cfgcmd} set service ipoe-server authentication radius source-address \<address\> + +Source IPv4 address used in all RADIUS server queries. +``` + +:::{note} +The ``source-address`` must be configured on one of VyOS interface. +Best practice would be a loopback or dummy interface. +::: + + +### RADIUS advanced options + +```{cfgcmd} set service ipoe-server authentication radius server \<server\> port \<port\> + +Configure RADIUS *\<server\>* and its required port for authentication requests. +``` + + +```{cfgcmd} set service ipoe-server authentication radius server \<server\> fail-time \<time\> + +Mark RADIUS server as offline for this given *\<time\>* in seconds. +``` + + +```{cfgcmd} set service ipoe-server authentication radius server \<server\> disable + +Temporary disable this RADIUS server. +``` + + +```{cfgcmd} set service ipoe-server authentication radius acct-timeout \<timeout\> + +Timeout to wait reply for Interim-Update packets. (default 3 seconds) +``` + + +```{cfgcmd} set service ipoe-server authentication radius dynamic-author server \<address\> + +Specifies IP address for Dynamic Authorization Extension server (DM/CoA). +This IP must exist on any VyOS interface or it can be ``0.0.0.0``. +``` + + +```{cfgcmd} set service ipoe-server authentication radius dynamic-author port \<port\> + +UDP port for Dynamic Authorization Extension server (DM/CoA) +``` + + +```{cfgcmd} set service ipoe-server authentication radius dynamic-author key \<secret\> + +Secret for Dynamic Authorization Extension server (DM/CoA) +``` + + +```{cfgcmd} set service ipoe-server authentication radius max-try \<number\> + +Maximum number of tries to send Access-Request/Accounting-Request queries +``` + + +```{cfgcmd} set service ipoe-server authentication radius timeout \<timeout\> + +Timeout to wait response from server (seconds) +``` + + +```{cfgcmd} set service ipoe-server authentication radius nas-identifier \<identifier\> + +Value to send to RADIUS server in NAS-Identifier attribute and to be matched +in DM/CoA requests. +``` + + +```{cfgcmd} set service ipoe-server authentication radius nas-ip-address \<address\> + +Value to send to RADIUS server in NAS-IP-Address attribute and to be matched +in DM/CoA requests. Also DM/CoA server will bind to that address. +``` + + +```{cfgcmd} set service ipoe-server authentication radius source-address \<address\> + +Source IPv4 address used in all RADIUS server queries. +``` + + +```{cfgcmd} set service ipoe-server authentication radius rate-limit attribute \<attribute\> + +Specifies which RADIUS server attribute contains the rate limit information. +The default attribute is *Filter-Id*. +``` + +:::{note} +If you set a custom RADIUS attribute you must define it on both +dictionaries at RADIUS server and client. +::: + +```{cfgcmd} set service ipoe-server authentication radius rate-limit enable + +Enables bandwidth shaping via RADIUS. +``` + + +```{cfgcmd} set service ipoe-server authentication radius rate-limit vendor + +Specifies the vendor dictionary, dictionary needs to be in +/usr/share/accel-ppp/radius. +``` + +Received RADIUS attributes have a higher priority than parameters defined within +the CLI configuration, refer to the explanation below. + + +### Allocation clients ip addresses by RADIUS + + +If the RADIUS server sends the attribute ``Framed-IP-Address`` then this IP +address will be allocated to the client and the option ``default-pool`` within the CLI +config is being ignored. + + +If the RADIUS server sends the attribute ``Framed-Pool``, IP address will be allocated +from a predefined IP pool whose name equals the attribute value. + + +If the RADIUS server sends the attribute ``Stateful-IPv6-Address-Pool``, IPv6 address +will be allocated from a predefined IPv6 pool ``prefix`` whose name equals the attribute value. + + +If the RADIUS server sends the attribute ``Delegated-IPv6-Prefix-Pool``, IPv6 +delegation prefix will be allocated from a predefined IPv6 pool ``delegate`` +whose name equals the attribute value. + + +:::{note} +``Stateful-IPv6-Address-Pool`` and ``Delegated-IPv6-Prefix-Pool`` are defined in +RFC6911. If they are not defined in your RADIUS server, add new [dictionary]. +::: + + +User interface can be put to VRF context via RADIUS Access-Accept packet, or change +it via RADIUS CoA. ``Accel-VRF-Name`` is used from these purposes. It is custom [ACCEL-PPP attribute]. +Define it in your RADIUS server. + + +## IPv6 + +```{cfgcmd} set service ipoe-server client-ipv6-pool \<IPv6-POOL-NAME\> prefix \<address\> mask \<number-of-bits\> + +Use this command to set the IPv6 address pool from which an IPoE client +will get an IPv6 prefix of your defined length (mask) to terminate the +IPoE endpoint at their side. The mask length can be set from 48 to 128 +bit long, the default value is 64. +``` + + +```{cfgcmd} set service ipoe-server client-ipv6-pool \<IPv6-POOL-NAME\> delegate \<address\> delegation-prefix \<number-of-bits\> + +Use this command to configure DHCPv6 Prefix Delegation (RFC3633) on +IPoE. You will have to set your IPv6 pool and the length of the +delegation prefix. From the defined IPv6 pool you will be handing out +networks of the defined length (delegation-prefix). The length of the +delegation prefix can be set from 32 to 64 bit long. +``` + + +```{cfgcmd} set service ipoe-server default-ipv6-pool \<IPv6-POOL-NAME\> + +Use this command to define default IPv6 address pool name. +``` + + +```none +set service ipoe-server client-ipv6-pool IPv6-POOL delegate '2001:db8:8003::/48' delegation-prefix '56' +set service ipoe-server client-ipv6-pool IPv6-POOL prefix '2001:db8:8002::/48' mask '64' +set service ipoe-server default-ipv6-pool IPv6-POOL +``` + +## Scripting + +```{cfgcmd} set service ipoe-server extended-scripts on-change \<path_to_script\> + +Script to run when session interface changed by RADIUS CoA handling +``` + + +```{cfgcmd} set service ipoe-server extended-scripts on-down \<path_to_script\> + +Script to run when session interface going to terminate +``` + + +```{cfgcmd} set service ipoe-server extended-scripts on-pre-up \<path_to_script\> + +Script to run before session interface comes up +``` + + +```{cfgcmd} set service ipoe-server extended-scripts on-up \<path_to_script\> + +Script to run when session interface is completely configured and started +``` + +## Advanced Options + + +### Authentication Advanced Options + +```{cfgcmd} set service ipoe-server authentication interface \<interface\> mac \<MAC\> vlan \<vlan-id\> + +VLAN monitor for automatic creation of VLAN interfaces for specific user on specific \<interface\> +``` + + +```{cfgcmd} set service ipoe-server authentication interface \<interface\> mac \<MAC\> rate-limit download \<bandwidth\> + +Download bandwidth limit in kbit/s for user on interface *\<interface\>*. +``` + + +```{cfgcmd} set service ipoe-server authentication interface \<interface\> mac \<MAC\> rate-limit upload \<bandwidth\> + +Upload bandwidth limit in kbit/s for for user on interface *\<interface\>*. +``` + +### Client IP Pool Advanced Options + +```{cfgcmd} set service ipoe-server client-ip-pool \<POOL-NAME\> next-pool \<NEXT-POOL-NAME\> + +Use this command to define the next address pool name. +``` + +### Advanced Interface Options + +```{cfgcmd} set service ipoe-server interface \<interface\> client-subnet \<x.x.x.x/x\> + +Specify local range of ip address to give to dhcp clients. First IP in range is router IP. +If you need more customization use *client-ip-pool* +``` + + +```{cfgcmd} set service ipoe-server interface \<interface\> external-dhcp dhcp-relay \<x.x.x.x\> + +Specify DHCPv4 relay IP address to pass requests to. If specified giaddr is also needed. +``` + + +```{cfgcmd} set service ipoe-server interface \<interface\> external-dhcp giaddr \<x.x.x.x\> + +Specifies relay agent IP addre +``` + +### Global Advanced options + +```{cfgcmd} set service ipoe-server description \<description\> + +Set description. +``` +```{cfgcmd} set service ipoe-server limits burst \<value\> + +Burst count +``` +```{cfgcmd} set service ipoe-server limits connection-limit \<value\> + +Acceptable rate of connections (e.g. 1/min, 60/sec) +``` +```{cfgcmd} set service ipoe-server limits timeout \<value\> + +Timeout in seconds +``` +```{cfgcmd} set service ipoe-server max-concurrent-sessions + +Maximum number of concurrent session start attempts +``` +```{cfgcmd} set service ipoe-server name-server \<address\> + +Connected client should use *\<address\>* as their DNS server. This +command accepts both IPv4 and IPv6 addresses. Up to two nameservers +can be configured for IPv4, up to three for IPv6. +``` +```{cfgcmd} set service ipoe-server shaper fwmark \<1-2147483647\> + +Match firewall mark value +``` +```{cfgcmd} set service ipoe-server snmp master-agent + +Enable SNMP +``` + +## Monitoring + +```{opcmd} show ipoe-server sessions + +Use this command to locally check the active sessions in the IPoE +server. +``` +```none +vyos@vyos:~$ show ipoe-server sessions +ifname | username | calling-sid | ip | rate-limit | type | comp | state | uptime +----------+----------+-------------------+-------------+------------+------+------+--------+---------- + eth1.100 | eth1.100 | 0c:98:bd:b8:00:01 | 192.168.0.3 | | ipoe | | active | 03:03:58 +``` + +```none +vyos@vyos:~$ show ipoe-server statistics +uptime: 0.03:31:36 +cpu: 0% +mem(rss/virt): 6044/101360 kB +core: + mempool_allocated: 148628 + mempool_available: 144748 + thread_count: 1 + thread_active: 1 + context_count: 10 + context_sleeping: 0 + context_pending: 0 + md_handler_count: 6 + md_handler_pending: 0 + timer_count: 1 + timer_pending: 0 +sessions: + starting: 0 + active: 1 + finishing: 0 +ipoe: + starting: 0 + active: 1 + delayed: 0 +``` + +## Troubleshooting + +```none +vyos@vyos:~$ show log ipoe-server + +Feb 27 14:29:27 vyos accel-ipoe[2262]: eth1.100:: recv [DHCPv4 Discover xid=55df9228 chaddr=0c:98:bd:b8:00:01 <Message-Type Discover> <Request-IP 192.168.0.3> <Host-Name vyos> <Request-List Subnet,Broadcast,Router,DNS,Classless-Route,Domain-Name,MTU>] +Feb 27 14:29:27 vyos accel-ipoe[2262]: eth1.100:eth1.100: eth1.100: authentication succeeded +Feb 27 14:29:27 vyos accel-ipoe[2262]: eth1.100:eth1.100: send [DHCPv4 Offer xid=55df9228 yiaddr=192.168.0.4 chaddr=0c:98:bd:b8:00:01 <Message-Type Offer> <Server-ID 192.168.0.1> <Lease-Time 600> <T1 300> <T2 525> <Router 192.168.0.1> <Subnet 255.255.255.0>] +Feb 27 14:29:27 vyos accel-ipoe[2262]: eth1.100:eth1.100: recv [DHCPv4 Request xid=55df9228 chaddr=0c:98:bd:b8:00:01 <Message-Type Request> <Server-ID 192.168.0.1> <Request-IP 192.168.0.4> <Host-Name vyos> <Request-List Subnet,Broadcast,Router,DNS,Classless-Route,Domain-Name,MTU>] +Feb 27 14:29:27 vyos accel-ipoe[2262]: eth1.100:eth1.100: ipoe: activate session +Feb 27 14:29:27 vyos accel-ipoe[2262]: eth1.100:eth1.100: ipoe: no free IPv6 address +Feb 27 14:29:27 vyos accel-ipoe[2262]: eth1.100:eth1.100: ipoe: session started +Feb 27 14:29:27 vyos accel-ipoe[2262]: eth1.100:eth1.100: send [DHCPv4 Ack xid=55df9228 yiaddr=192.168.0.4 chaddr=0c:98:bd:b8:00:01 <Message-Type Ack> <Server-ID 192.168.0.1> <Lease-Time 600> <T1 300> <T2 525> <Router 192.168.0.1> <Subnet 255.255.255.0>] +``` + +[accel-ppp]: https://accel-ppp.org/ +[accel-ppp attribute]: https://github.com/accel-ppp/accel-ppp/blob/master/accel-pppd/radius/dict/dictionary.accel +[dictionary]: https://github.com/accel-ppp/accel-ppp/blob/master/accel-pppd/radius/dict/dictionary.rfc6911 diff --git a/docs/configuration/service/lldp.md b/docs/configuration/service/lldp.md new file mode 100644 index 00000000..7fdba6c8 --- /dev/null +++ b/docs/configuration/service/lldp.md @@ -0,0 +1,154 @@ +(lldp)= + +# LLDP + +{abbr}`LLDP (Link Layer Discovery Protocol)` is a vendor-neutral link layer +protocol in the Internet Protocol Suite used by network devices for advertising +their identity, capabilities, and neighbors on an IEEE 802 local area network, +principally wired Ethernet. The protocol is formally referred to by the IEEE +as Station and Media Access Control Connectivity Discovery specified in IEEE +802.1AB and IEEE 802.3-2012 section 6 clause 79. + +LLDP performs functions similar to several proprietary protocols, such as +{abbr}`CDP (Cisco Discovery Protocol)`, +{abbr}`FDP (Foundry Discovery Protocol)`, +{abbr}`NDP (Nortel Discovery Protocol)` and {abbr}`LLTD (Link Layer Topology +Discovery)`. + +Information gathered with LLDP is stored in the device as a {abbr}`MIB +(Management Information Database)` and can be queried with {abbr}`SNMP (Simple +Network Management Protocol)` as specified in {rfc}`2922`. The topology of an +LLDP-enabled network can be discovered by crawling the hosts and querying this +database. Information that may be retrieved include: + +- System Name and Description +- Port name and description +- VLAN name +- IP management address +- System capabilities (switching, routing, etc.) +- MAC/PHY information +- MDI power +- Link aggregation + +## Configuration + +```{cfgcmd} set service lldp + +Enable LLDP service +``` + +```{cfgcmd} set service lldp management-address \<address\> + +Define IPv4/IPv6 management address transmitted via LLDP. Multiple addresses +can be defined. Only addresses connected to the system will be transmitted. +``` + +```{cfgcmd} set service lldp interface \<interface\> + +Enable transmission of LLDP information on given \<interface\>. You can also +say ``all`` here so LLDP is turned on on every interface. +``` + +```{cfgcmd} set service lldp interface \<interface\> mode [disable|rx-tx|rx|tx] + +Configure the administrative status of the given port. + +By default, all ports are configured to be in rx-tx mode. This means they +can receive and transmit LLDP frames. + +In rx mode, they won't emit any frames. In tx mode, they won't receive +any frames. In disabled mode, no frame will be sent and any incoming frame +will be discarded. +``` + +```{cfgcmd} set service lldp snmp + +Enable SNMP queries of the LLDP database +``` + +```{cfgcmd} set service lldp legacy-protocols \<cdp|edp|fdp|sonmp\> + +Enable given legacy protocol on this LLDP instance. Legacy protocols include: +* ``cdp`` - Listen for CDP for Cisco routers/switches +* ``edp`` - Listen for EDP for Extreme routers/switches +* ``fdp`` - Listen for FDP for Foundry routers/switches +* ``sonmp`` - Listen for SONMP for Nortel routers/switches +``` + + +## Operation + +```{opcmd} show lldp neighbors + +Displays information about all neighbors discovered via LLDP. + +:::{code-block} none +vyos@vyos:~$ show lldp neighbors +Capability Codes: R - Router, B - Bridge, W - Wlan r - Repeater, S - Station + D - Docsis, T - Telephone, O - Other + +Device ID Local Proto Cap Platform Port ID +--------- ----- ----- --- -------- ------- +BR2.vyos.net eth0 LLDP R VyOS 1.2.4 eth1 +BR3.vyos.net eth0 LLDP RB VyOS 1.2.4 eth2 +SW1.vyos.net eth0 LLDP B Cisco IOS Software GigabitEthernet0/6 +::: +``` + +```{opcmd} show lldp neighbors detail + +Get detailed information about LLDP neighbors. + +:::{code-block} none +vyos@vyos:~$ show lldp neighbors detail +------------------------------------------------------------------------------- +LLDP neighbors: +------------------------------------------------------------------------------- +Interface: eth0, via: LLDP, RID: 28, Time: 0 day, 00:24:33 +Chassis: + ChassisID: mac 00:53:00:01:02:c9 + SysName: BR2.vyos.net + SysDescr: VyOS 1.3-rolling-201912230217 + MgmtIP: 192.0.2.1 + MgmtIP: 2001:db8::ffff + Capability: Bridge, on + Capability: Router, on + Capability: Wlan, off + Capability: Station, off +Port: + PortID: mac 00:53:00:01:02:c9 + PortDescr: eth0 + TTL: 120 + PMD autoneg: supported: no, enabled: no + MAU oper type: 10GigBaseCX4 - X copper over 8 pair 100-Ohm balanced cable +VLAN: 201 eth0.201 +VLAN: 205 eth0.205 +LLDP-MED: + Device Type: Network Connectivity Device + Capability: Capabilities, yes + Capability: Policy, yes + Capability: Location, yes + Capability: MDI/PSE, yes + Capability: MDI/PD, yes + Capability: Inventory, yes + Inventory: + Hardware Revision: None + Software Revision: 4.19.89-amd64-vyos + Firmware Revision: 6.00 + Serial Number: VMware-42 1d 83 b9 fe c1 bd b2-7 + Manufacturer: VMware, Inc. + Model: VMware Virtual Platform + Asset ID: No Asset Tag +------------------------------------------------------------------------------- +::: +``` + +```{opcmd} show lldp neighbors interface \<interface\> + +Show LLDP neighbors connected via interface \<interface\>. +``` + +```{opcmd} show log lldp + +Used for troubleshooting. +```
\ No newline at end of file diff --git a/docs/configuration/service/mdns.md b/docs/configuration/service/mdns.md new file mode 100644 index 00000000..088bca3c --- /dev/null +++ b/docs/configuration/service/mdns.md @@ -0,0 +1,131 @@ +# mDNS Repeater + +Starting with VyOS 1.2 a {abbr}`mDNS (Multicast DNS)` repeater functionality is +provided. Additional information can be obtained from +<https://en.wikipedia.org/wiki/Multicast_DNS>. + +Multicast DNS uses the reserved address `224.0.0.251`, which is +"administratively scoped" and does not leave the subnet. mDNS repeater +retransmits mDNS packets from one interface to other interfaces. This enables +support for devices using mDNS discovery (like network printers, Apple Airplay, +Chromecast, various IP based home-automation devices etc) across multiple VLANs. + +Since the mDNS protocol sends the {abbr}`AA(Authoritative Answer)` records in +the packet itself, the repeater does not need to forge the source address. +Instead, the source address is of the interface that repeats the packet. + +:::{note} +You can not run this in a VRRP setup, if multiple mDNS repeaters +are launched in a subnet you will experience the mDNS packet storm death! +::: + +## Configuration + +```{cfgcmd} set service mdns repeater interface \<interface\> + +To enable mDNS repeater you need to configure at least two interfaces so that +all incoming mDNS packets from one interface configured here can be +re-broadcasted to any other interface(s) configured under this section. +``` + +```{cfgcmd} set service mdns repeater disable + +mDNS repeater can be temporarily disabled without deleting the service using +``` + +```{cfgcmd} set service mdns repeater ip-version \<ipv4 | ipv6 | both\> + +mDNS repeater can be enabled either on IPv4 socket or on IPv6 socket or both +to re-broadcast. By default, mDNS repeater will listen on both IPv4 and IPv6. +``` + +```{cfgcmd} set service mdns repeater allow-service \<service\> + +mDNS repeater can be configured to re-broadcast only specific services. By +default, all services are re-broadcasted. +``` + +```{cfgcmd} set service mdns repeater browse-domain \<domain\> + +Allow listing additional custom domains to be browsed (in addition to the +default ``local``) so that they can be reflected. +``` + +```{cfgcmd} set service mdns repeater cache-entries \<entries\> + +Specify how many resource records are cached per interface. Bigger values +allow mDNS work correctly in large LANs but also increase memory consumption. + +Defaults to: 4096 +``` + + +## Firewall recommendations + +Unlike typical routed traffic, mDNS packets relayed between interfaces do not +traverse the FORWARD hook chain in the firewall. Instead, they are processed +through the following hooks: +> - **INPUT**: For packets received by the local system +> - **OUTPUT**: For packets sent from the local system + +To control or allow mDNS packet forwarding via the relay, you must define +appropriate rules in the INPUT and OUTPUT directions. Rules in the FORWARD +direction will have no effect on mDNS relay traffic. + +```none +set firewall ipv4 input filter rule 10 action 'accept' +set firewall ipv4 input filter rule 10 destination address '224.0.0.251' +set firewall ipv4 input filter rule 10 destination port '5353' +set firewall ipv4 input filter rule 10 protocol 'udp' +set firewall ipv4 output filter rule 10 action 'accept' +set firewall ipv4 output filter rule 10 destination address '224.0.0.251' +set firewall ipv4 output filter rule 10 destination port '5353' +set firewall ipv4 output filter rule 10 protocol 'udp' +``` + + +## Example + +To listen on both `eth0` and `eth1` mDNS packets and also repeat packets +received on `eth0` to `eth1` (and vice-versa) use the following commands: + +```none +set service mdns repeater interface 'eth0' +set service mdns repeater interface 'eth1' +``` + +To allow only specific services, for example `_airplay._tcp` or `_ipp._tcp`, +(instead of all services) to be re-broadcasted, use the following command: + +```none +set service mdns repeater allow-service '_airplay._tcp' +set service mdns repeater allow-service '_ipp._tcp' +``` + +To allow listing additional custom domain, for example +`openthread.thread.home.arpa`, so that it can reflected in addition to the +default `local`, use the following command: + +```none +set service mdns repeater browse-domain 'openthread.thread.home.arpa' +``` + + +## Operation + +```{opcmd} restart mdns repeater + +Restart mDNS repeater service. +``` + +```{opcmd} show log mdns repeater + +Show logs for mDNS repeater service. +``` + +```{opcmd} monitor log mdns repeater + +Follow the logs for mDNS repeater service. +``` + +[multicast dns]: <https://en.wikipedia.org/wiki/Multicast_DNS> diff --git a/docs/configuration/service/monitoring.md b/docs/configuration/service/monitoring.md new file mode 100644 index 00000000..93bd40e6 --- /dev/null +++ b/docs/configuration/service/monitoring.md @@ -0,0 +1,334 @@ +# Monitoring + +VyOS supports monitoring through Telegraf as well as through Prometheus exporters. + +## Telegraf + +Telegraf is the open source server agent to help you collect metrics, events +and logs from your routers. + +The following Telegraf plugins are configurable to export metrics and logs: +: - Azure Data Explorer + - Prometheus Client + - Splunk + - InfluxDB + - Loki + +### 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 database 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] +This plugin allows export of Telegraf metrics to Prometheus, +for Prometheus native metrics through exporters see section below. + +```{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\> + +Metrics version, the default is ``2`` +``` + + +```{cfgcmd} set service monitoring telegraf prometheus-client port \<port\> + +Port number used by connection, default is ``9273`` +``` + +Example: + +```none +set service monitoring telegraf prometheus-client +``` + + +```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: + +```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' +``` + +### InfluxDB + + +Telegraf output plugin [influxdb] to write metrics to `InfluxDB` via HTTP. + +```{cfgcmd} set service monitoring telegraf influxdb authentication organization \<organization\> + +Authentication organization name +``` + + +```{cfgcmd} set service monitoring telegraf influxdb authentication token \<token\> + +Authentication token +``` + + +```{cfgcmd} set service monitoring telegraf bucket \<bucket\> + +Remote ``InfluxDB`` bucket name +``` + + +```{cfgcmd} set service monitoring telegraf influxdb port \<port\> + +Remote port +``` + + +```{cfgcmd} set service monitoring telegraf influxdb url \<url\> + +Remote URL +``` + +Example: + +```none +set service monitoring telegraf influxdb authentication organization 'vyos' +set service monitoring telegraf influxdb authentication token 'ZAml9Uy5wrhA...==' +set service monitoring telegraf influxdb bucket 'bucket_vyos' +set service monitoring telegraf influxdb port '8086' +set service monitoring telegraf influxdb url 'http://r1.influxdb2.local' +``` + +### Loki + +Telegraf can be used to send logs to [loki] using tags as labels. + +```{cfgcmd} set service monitoring telegraf loki port \<port\> + + Remote Loki port + + Default is 3100 +``` + + +```{cfgcmd} set service monitoring telegraf loki url \<url\> + +Remote Loki url +``` + + +```{cfgcmd} set service monitoring telegraf loki authentication username \<username\> +``` + +```{cfgcmd} set service monitoring telegraf loki authentication password \<password\> + +HTTP basic authentication. + +If either is set both must be set. +``` + +```{cfgcmd} set service monitoring telegraf loki metric-name-label \<label\> + +Label to use for the metric name when sending metrics. + +If set to an empty string, the label will not be added. +This is NOT recommended, as it makes it impossible to differentiate +between multiple metrics. +``` + +## Prometheus + + +The following Prometheus exporters are configurable to export metrics: +: - Node Exporter + - FRR Exporter + + +### Node Exporter + + +Prometheus [node_exporter] which provides a wide range of hardware and OS metrics. + +```{cfgcmd} set service monitoring prometheus node-exporter listen-address \<address\> + +Configure the address node_exporter is listening on. +``` + +```{cfgcmd} set service monitoring prometheus node-exporter port \<port\> + +Configure the port number node_exporter is listening on. +``` + +```{cfgcmd} set service monitoring prometheus node-exporter vrf \<name\> + +Configure name of the {abbr}`VRF (Virtual Routing and Forwarding)` instance. +``` + +```{cfgcmd} set service monitoring prometheus node-exporter collectors textfile + +Configure textfile collector to export custom metrics read from +`/run/node_exporter/collector` +``` + +### FRR Exporter + +Prometheus [frr_exporter] which provides free range routing metrics. + +```{cfgcmd} set service monitoring prometheus frr-exporter listen-address \<address\> + +Configure the address frr_exporter is listening on. + +``` + +```{cfgcmd} set service monitoring prometheus frr-exporter port \<port\> + +Configure the port number frr_exporter is listening on. +``` + +```{cfgcmd} set service monitoring prometheus frr-exporter vrf \<name\> + +Configure name of the {abbr}`VRF (Virtual Routing and Forwarding)` instance. +``` + +### Blackbox Exporter + +Prometheus [blackbox_exporter] which allows probing of endpoints over +HTTP, HTTPS, DNS, TCP, ICMP and gRPC . + +```{cfgcmd} set service monitoring prometheus blackbox-exporter listen-address \<address\> + +Configure the address blackbox_exporter is listening on. +``` +```{cfgcmd} set service monitoring prometheus blackbox-exporter port \<port\> + +Configure the port number blackbox_exporter is listening on. +``` +```{cfgcmd} set service monitoring prometheus blackbox-exporter vrf \<name\> + +Configure name of the {abbr}`VRF (Virtual Routing and Forwarding)` instance. +``` + +#### Configuring modules + +Blackbox exporter can be configured with different modules for probing DNS or ICMP. + +DNS module example: + +```none +set service monitoring prometheus blackbox-exporter modules dns name dns4 preferred-ip-protocol ipv4 +set service monitoring prometheus blackbox-exporter modules dns name dns4 query-name vyos.io +set service monitoring prometheus blackbox-exporter modules dns name dns4 query-type A +``` + +ICMP module example: + +```none +set service monitoring prometheus blackbox-exporter modules icmp name ping6 preferred-ip-protocol ipv6 +set service monitoring prometheus blackbox-exporter modules icmp name ping6 ip-protocol-fallback +set service monitoring prometheus blackbox-exporter modules icmp name ping6 timeout 3 +``` + +[azure-data-explorer]: <https://github.com/influxdata/telegraf/tree/master/plugins/outputs/azure_data_explorer> +[blackbox_exporter]: <https://github.com/prometheus/blackbox_exporter> +[frr_exporter]: <https://github.com/tynany/frr_exporter> +[influxdb]: <https://github.com/influxdata/telegraf/tree/master/plugins/outputs/influxdb_v2> +[loki]: https://github.com/influxdata/telegraf/tree/master/plugins/outputs/loki +[node_exporter]: <https://github.com/prometheus/node_exporter> +[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> diff --git a/docs/configuration/service/ntp.md b/docs/configuration/service/ntp.md new file mode 100644 index 00000000..c8c1dee3 --- /dev/null +++ b/docs/configuration/service/ntp.md @@ -0,0 +1,202 @@ +(ntp)= + +# NTP + +{abbr}`NTP (Network Time Protocol`) is a networking protocol for clock +synchronization between computer systems over packet-switched, variable-latency +data networks. In operation since before 1985, NTP is one of the oldest Internet +protocols in current use. + +NTP is intended to synchronize all participating computers to within a few +milliseconds of {abbr}`UTC (Coordinated Universal Time)`. It uses the +intersection algorithm, a modified version of Marzullo's algorithm, to select +accurate time servers and is designed to mitigate the effects of variable +network latency. NTP can usually maintain time to within tens of milliseconds +over the public Internet, and can achieve better than one millisecond accuracy +in local area networks under ideal conditions. Asymmetric routes and network +congestion can cause errors of 100 ms or more. + +The protocol is usually described in terms of a client-server model, but can as +easily be used in peer-to-peer relationships where both peers consider the other +to be a potential time source. Implementations send and receive timestamps using +{abbr}`UDP (User Datagram Protocol)` on port number 123. + +NTP supplies a warning of any impending leap second adjustment, but no +information about local time zones or daylight saving time is transmitted. + +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 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)`. + + There are 3 default NTP server set. You are able to change them. + + * ``time1.vyos.net`` + * ``time2.vyos.net`` + * ``time3.vyos.net`` +``` + + +```{cfgcmd} set service ntp server \<address\> \<noselect | nts | pool | prefer | ptp | interleave\> + +Configure one or more attributes to the given NTP server. + +* ``noselect`` marks the server as unused, except for display purposes. The +server is discarded by the selection algorithm. + +* ``nts`` enables Network Time Security (NTS) for the server as specified +in {rfc}`8915` + +* ``pool`` mobilizes persistent client mode association with a number of +remote servers. + +* ``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. + +* ``ptp`` enables the PTP transport for this server (see {ref}`ptp-transport`). + +* ``interleave`` enables NTP interleaved mode (see [draft-ntp-interleaved-modes]), which can improve +synchronization accuracy and stability when supported by both parties. +``` + + +```{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 for same IP family is no longer supported. Only one IPv4 and one +IPv6 address can be configured, using separate commands for each. +``` + + +```{cfgcmd} set service ntp allow-client address \<address\> + +List of networks or client addresses permitted to contact this NTP server. + +Multiple networks/client IP addresses can be configured. +``` + + +```{cfgcmd} set service ntp vrf \<name\> + +Specify name of the {abbr}`VRF (Virtual Routing and Forwarding)` instance. +``` + + +```{cfgcmd} set service ntp leap-second [ignore|smear|system|timezone] + +Define how to handle leap-seconds. + +* `ignore`: No correction is applied to the clock for the leap second. The +clock will be corrected later in normal operation when new measurements are +made and the estimated offset includes the one second error. + +* `smear`: When smearing a leap second, the leap status is suppressed on the +server and the served time is corrected slowly by slewing instead of +stepping. The clients do not need any special configuration as they do not +know there is any leap second and they follow the server time which +eventually brings them back to UTC. Care must be taken to ensure they use +only NTP servers which smear the leap second in exactly the same way for +synchronisation. + +* `system`: When inserting a leap second, the kernel steps the system clock +backwards by one second when the clock gets to 00:00:00 UTC. When deleting +a leap second, it steps forward by one second when the clock gets to +23:59:59 UTC. + +* `timezone`: This directive specifies a timezone in the system timezone +database which chronyd can use to determine when will the next leap second +occur and what is the current offset between TAI and UTC. It will +periodically check if 23:59:59 and 23:59:60 are valid times in the +timezone. This normally works with the right/UTC timezone which is the +default +``` + +## Hardware Timestamping of NTP Packets + + +The chrony daemon on VyOS can leverage NIC hardware capabilities to record the +exact time packets are received on the interface, as well as when packets were +actually transmitted. This provides improved accuracy and stability when the +system is under load, as queuing and OS context switching can introduce a +variable delay between when the packet is received on the network and when it +is actually processed by the NTP daemon. + + +Hardware timestamping depends on NIC support. Some NICs can be configured to +apply timestamps to any incoming packet, while others only support applying +timestamps to specific protocols (e.g. PTP). + + +When timestamping is enabled on an interface, chrony's default behavior is to +try to configure the interface to only timestamp NTP packets. If this mode is +not supported, chrony will attempt to set it to timestamp all packets. If +neither option is supported (e.g. the NIC can only timestamp received PTP +packets), chrony will leverage timestamping on transmitted packets only, which +still provides some benefit. + +```{cfgcmd} set service ntp timestamp interface \<interface\> + +Configures hardware timestamping on the interface \<interface\>. The special +value `all` can also be specified to enable timestamping on all interfaces +that support it. + +Configure the timestamping behavior with the following option: + +* ``receive-filter [all|ntp|ptp|none]`` selects the receive filter mode, +which controls which inbound packets the NIC applies timestamps to. The +selected mode must be supported by the NIC, or timestamping will be +disabled for the interface. +``` + +The following `receive-filter` modes can be selected: +- *all*: All received packets will be timestamped. +- *ntp*: Only received NTP protocol packets will be timestamped. +- *ptp*: Only received PTP protocol packets will be timestamped. Combined with + the PTP transport for NTP packets, this can be leveraged to take advantage of + hardware timestamping on NICs that only support the ptp filter mode. +- *none*: No received packets will be timestamped. Hardware timestamping of + transmitted packets will still be leveraged, if supported by the NIC. +(ptp-transport)= + +## PTP Transport of NTP Packets + +The Precision Time Protocol (IEEE 1588) is a local network time synchronization +protocol that provides high precision time synchronization by leveraging +hardware clocks in NICs and other network elements. VyOS does not currently +support standards-based PTP, which can be deployed independently of +NTP. + +For networks consisting of VyOS and other Linux systems running relatively +recent versions of the chrony daemon, NTP packets can be "tunneled" over +PTP. NTP over PTP provides the best of both worlds, leveraging hardware support +for timestamping PTP packets while retaining the configuration flexibility and +fault tolerance of NTP. + +```{cfgcmd} set service ntp ptp + +Enables the NTP daemon PTP transport. The NTP daemon will listen on the +configured PTP port. Note that one or more servers must be individually +enabled for PTP before the daemon will synchronize over the transport. +``` +```{cfgcmd} set service ntp ptp port \<port\> + +Configures the PTP port. By default, the standard port 319 is used. +``` + +[draft-ntp-interleaved-modes]: https://datatracker.ietf.org/doc/draft-ietf-ntp-interleaved-modes/07/ diff --git a/docs/configuration/service/pppoe-server.md b/docs/configuration/service/pppoe-server.md new file mode 100644 index 00000000..805740e4 --- /dev/null +++ b/docs/configuration/service/pppoe-server.md @@ -0,0 +1,753 @@ +--- +lastproofread: '2022-09-17' +--- + +(pppoe-server)= + +# PPPoE Server + +VyOS utilizes [accel-ppp](https://accel-ppp.org/) to provide PPPoE server functionality. It can +be used with local authentication or a connected RADIUS server. + +:::{note} +Please be aware, due to an upstream bug, config +changes/commits will restart the ppp daemon and will reset existing +PPPoE connections from connected users, in order to become effective. +::: + +## Configuring PPPoE Server + +```none +set service pppoe-server access-concentrator PPPoE-Server +set service pppoe-server authentication mode local +set service pppoe-server authentication local-users username test password 'test' +set service pppoe-server client-ip-pool PPPOE-POOL range 192.168.255.2-192.168.255.254 +set service pppoe-server default-pool 'PPPOE-POOL' +set service pppoe-server gateway-address 192.168.255.1 +set service pppoe-server interface eth0 +``` + +```{cfgcmd} set service pppoe-server access-concentrator \<name\> + + Use this command to set a name for this PPPoE-server access + concentrator. +``` + + +```{cfgcmd} set service pppoe-server authentication mode \<local | radius\> + +Set authentication backend. The configured authentication backend is used +for all queries. + +* **radius**: All authentication queries are handled by a configured RADIUS +server. +* **local**: All authentication queries are handled locally. +* **noauth**: Authentication disabled. +``` + + +```{cfgcmd} set service pppoe-server authentication local-users username \<name\> password \<password\> + +Create `<user>` for local authentication on this system. The users password +will be set to `<pass>`. +``` + + +```{cfgcmd} set service pppoe-server client-ip-pool \<POOL-NAME\> range \<x.x.x.x-x.x.x.x | x.x.x.x/x\> + +Use this command to define the first IP address of a pool of +addresses to be given to pppoe clients. If notation ``x.x.x.x-x.x.x.x``, +it must be within a /24 subnet. If notation ``x.x.x.x/x`` is +used there is possibility to set host/netmask. +``` + + +```{cfgcmd} set service pppoe-server default-pool \<POOL-NAME\> + +Use this command to define default address pool name. +``` + + +```{cfgcmd} set service pppoe-server interface \<interface\> + +Use this command to define the interface the PPPoE server will use to +listen for PPPoE clients. +``` + + +```{cfgcmd} set service pppoe-server gateway-address \<address\> + +Specifies single `<gateway>` IP address to be used as local address of PPP +interfaces. +``` + +## Configuring RADIUS authentication + +To enable RADIUS based authentication, the authentication mode needs to be +changed within the configuration. Previous settings like the local users, still +exists within the configuration, however they are not used if the mode has been +changed from local to radius. Once changed back to local, it will use all local +accounts again. + +```none +set service pppoe-server authentication mode radius +``` + +```{cfgcmd} set service pppoe-server authentication radius server \<server\> key \<secret\> + +Configure RADIUS `<server>` and its required shared `<secret>` for +communicating with the RADIUS server. +``` + +Since the RADIUS server would be a single point of failure, multiple RADIUS +servers can be setup and will be used subsequentially. +For example: + +```none +set service pppoe-server authentication radius server 10.0.0.1 key 'foo' +set service pppoe-server authentication radius server 10.0.0.2 key 'foo' +``` + +:::{note} +Some RADIUS severs use an access control list which allows or denies +queries, make sure to add your VyOS router to the allowed client list. +::: + + +### RADIUS source address + + +If you are using OSPF as IGP, always the closest interface connected to the +RADIUS server is used. With VyOS 1.2 you can bind all outgoing RADIUS requests +to a single source IP e.g. the loopback interface. + +```{cfgcmd} set service pppoe-server authentication radius source-address \<address\> + +Source IPv4 address used in all RADIUS server queries. +``` + +:::{note} +The `source-address` must be configured on one of VyOS interface. +Best practice would be a loopback or dummy interface. +::: + + +### RADIUS advanced options + +```{cfgcmd} set service pppoe-server authentication radius server \<server\> port \<port\> + +Configure RADIUS `<server>` and its required port for authentication requests. +``` + + +```{cfgcmd} set service pppoe-server authentication radius server \<server\> fail-time \<time\> + +Mark RADIUS server as offline for this given `<time>` in seconds. +``` + + +```{cfgcmd} set service pppoe-server authentication radius server \<server\> disable + +Temporary disable this RADIUS server. +``` + + +```{cfgcmd} set service pppoe-server authentication radius acct-timeout \<timeout\> + +Timeout to wait reply for Interim-Update packets. (default 3 seconds) +``` + + +```{cfgcmd} set service pppoe-server authentication radius dynamic-author server \<address\> + +Specifies IP address for Dynamic Authorization Extension server (DM/CoA). +This IP must exist on any VyOS interface or it can be ``0.0.0.0``. +``` + + +```{cfgcmd} set service pppoe-server authentication radius dynamic-author port \<port\> + +UDP port for Dynamic Authorization Extension server (DM/CoA) +``` + + +```{cfgcmd} set service pppoe-server authentication radius dynamic-author key \<secret\> + +Secret for Dynamic Authorization Extension server (DM/CoA) +``` + + +```{cfgcmd} set service pppoe-server authentication radius max-try \<number\> + +Maximum number of tries to send Access-Request/Accounting-Request queries +``` + + +```{cfgcmd} set service pppoe-server authentication radius timeout \<timeout\> + +Timeout to wait response from server (seconds) +``` + + +```{cfgcmd} set service pppoe-server authentication radius nas-identifier \<identifier\> + +Value to send to RADIUS server in NAS-Identifier attribute and to be matched +in DM/CoA requests. +``` + + +```{cfgcmd} set service pppoe-server authentication radius nas-ip-address \<address\> + +Value to send to RADIUS server in NAS-IP-Address attribute and to be matched +in DM/CoA requests. Also DM/CoA server will bind to that address. +``` + + +```{cfgcmd} set service pppoe-server authentication radius source-address \<address\> + +Source IPv4 address used in all RADIUS server queries. +``` + + +```{cfgcmd} set service pppoe-server authentication radius rate-limit attribute \<attribute\> + +Specifies which RADIUS server attribute contains the rate limit information. +The default attribute is ``Filter-Id``. +``` + +:::{note} +If you set a custom RADIUS attribute you must define it on both +dictionaries at RADIUS server and client. +::: + +```{cfgcmd} set service pppoe-server authentication radius rate-limit enable + +Enables bandwidth shaping via RADIUS. +``` + + +```{cfgcmd} set service pppoe-server authentication radius rate-limit vendor + +Specifies the vendor dictionary, dictionary needs to be in +/usr/share/accel-ppp/radius. +``` + +Received RADIUS attributes have a higher priority than parameters defined within +the CLI configuration, refer to the explanation below. + + +### Allocation clients ip addresses by RADIUS + + +If the RADIUS server sends the attribute `Framed-IP-Address` then this IP +address will be allocated to the client and the option `default-pool` +within the CLI config is being ignored. + + +If the RADIUS server sends the attribute `Framed-Pool`, IP address will +be allocated from a predefined IP pool whose name equals the attribute value. + + +If the RADIUS server sends the attribute `Stateful-IPv6-Address-Pool`, +IPv6 address will be allocated from a predefined IPv6 pool `prefix` +whose name equals the attribute value. + + +If the RADIUS server sends the attribute `Delegated-IPv6-Prefix-Pool`, +IPv6 delegation prefix will be allocated from a predefined IPv6 pool `delegate` +whose name equals the attribute value. + + +:::{note} +`Stateful-IPv6-Address-Pool` and `Delegated-IPv6-Prefix-Pool` +are defined in RFC6911. If they are not defined in your RADIUS server, +add new [dictionary]. +::: + + +User interface can be put to VRF context via RADIUS Access-Accept packet, +or change it via RADIUS CoA. `Accel-VRF-Name` is used from these purposes. +It is custom [ACCEL-PPP attribute]. Define it in your RADIUS server. + + +### Renaming clients interfaces by RADIUS + + +If the RADIUS server uses the attribute `NAS-Port-Id`, ppp tunnels will be +renamed. + + +:::{note} +The value of the attribute `NAS-Port-Id` must be less than 16 +characters, otherwise the interface won't be renamed. +::: + + +## Automatic VLAN Creation + +```{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, 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. +``` + + +```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 + + +Bandwidth rate limits can be set for local users or RADIUS based +attributes. + + +### For Local Users + +```{cfgcmd} set service pppoe-server authentication local-users username \<user\> rate-limit download \<bandwidth\> + +Download bandwidth limit in kbit/s for `<user>`. +``` + + +```{cfgcmd} set service pppoe-server authentication local-users username \<user\> rate-limit upload \<bandwidth\> + +Upload bandwidth limit in kbit/s for `<user>`. +``` +```none +set service pppoe-server access-concentrator 'ACN' +set service pppoe-server authentication local-users username foo password 'bar' +set service pppoe-server authentication local-users username foo rate-limit download '20480' +set service pppoe-server authentication local-users username foo rate-limit upload '10240' +set service pppoe-server authentication mode 'local' +set service pppoe-server client-ip-pool IP-POOL range '10.1.1.100/24' +set service pppoe-server default-pool 'IP-POOL' +set service pppoe-server name-server '10.100.100.1' +set service pppoe-server name-server '10.100.200.1' +set service pppoe-server interface 'eth1' +set service pppoe-server gateway-address '10.1.1.2' +``` + +Once the user is connected, the user session is using the set limits and +can be displayed via `show pppoe-server sessions`. + +```none +show pppoe-server sessions +ifname | username | ip | calling-sid | rate-limit | state | uptime | rx-bytes | tx-bytes +-------+----------+------------+-------------------+-------------+--------+----------+----------+---------- +ppp0 | foo | 10.1.1.100 | 00:53:00:ba:db:15 | 20480/10240 | active | 00:00:11 | 214 B | 76 B +``` + +### For RADIUS users + +The current attribute `Filter-Id` is being used as default and can be +setup within RADIUS: + +Filter-Id=2000/3000 (means 2000Kbit down-stream rate and 3000Kbit +up-stream rate) + +The command below enables it, assuming the RADIUS connection has been +setup and is working. + +```{cfgcmd} set service pppoe-server authentication radius rate-limit enable + + Use this command to enable bandwidth shaping via RADIUS. +``` + +Other attributes can be used, but they have to be in one of the +dictionaries in */usr/share/accel-ppp/radius*. + + +## Load Balancing + +```{cfgcmd} set service pppoe-server pado-delay \<number-of-ms\> sessions \<number-of-sessions\> + +Use this command to enable the delay of PADO (PPPoE Active Discovery +Offer) packets, which can be used as a session balancing mechanism +with other PPPoE servers. +``` + + +```none +set service pppoe-server pado-delay 50 sessions '500' +set service pppoe-server pado-delay 100 sessions '1000' +set service pppoe-server pado-delay 300 sessions '3000' +``` + +In the example above, the first 499 sessions connect without delay. PADO +packets will be delayed 50 ms for connection from 500 to 999, this trick +allows other PPPoE servers send PADO faster and clients will connect to +other servers. Last command says that this PPPoE server can serve only +3000 clients. + + +## IPv6 + +```{cfgcmd} set service pppoe-server ppp-options ipv6 \<require | prefer | allow | deny\> + +Specifies IPv6 negotiation preference. + +* **require** - Require IPv6 negotiation +* **prefer** - Ask client for IPv6 negotiation, do not fail if it rejects +* **allow** - Negotiate IPv6 only if client requests +* **deny** - Do not negotiate IPv6 (default value) +``` + + +```{cfgcmd} set service pppoe-server client-ipv6-pool \<IPv6-POOL-NAME\> prefix \<address\> mask \<number-of-bits\> + +Use this command to set the IPv6 address pool from which a PPPoE client +will get an IPv6 prefix of your defined length (mask) to terminate the +PPPoE endpoint at their side. The mask length can be set from 48 to 128 +bit long, the default value is 64. +``` + + +```{cfgcmd} set service pppoe-server client-ipv6-pool \<IPv6-POOL-NAME\> delegate \<address\> delegation-prefix \<number-of-bits\> + +Use this command to configure DHCPv6 Prefix Delegation (RFC3633) on +PPPoE. You will have to set your IPv6 pool and the length of the +delegation prefix. From the defined IPv6 pool you will be handing out +networks of the defined length (delegation-prefix). The length of the +delegation prefix can be set from 32 to 64 bit long. +``` + + +```{cfgcmd} set service pppoe-server default-ipv6-pool \<IPv6-POOL-NAME\> + +Use this command to define default IPv6 address pool name. +``` + + +```none +set service pppoe-server ppp-options ipv6 allow +set service pppoe-server client-ipv6-pool IPv6-POOL delegate '2001:db8:8003::/48' delegation-prefix '56' +set service pppoe-server client-ipv6-pool IPv6-POOL prefix '2001:db8:8002::/48' mask '64' +set service pppoe-server default-ipv6-pool IPv6-POOL +``` + +### IPv6 Advanced Options + +```{cfgcmd} set service pppoe-server ppp-options ipv6-accept-peer-interface-id + +Accept peer interface identifier. By default is not defined. +``` + + +```{cfgcmd} set service pppoe-server ppp-options ipv6-interface-id \<random | x:x:x:x\> + +Specifies fixed or random interface identifier for IPv6. +By default is fixed. + +* **random** - Random interface identifier for IPv6 +* **x:x:x:x** - Specify interface identifier for IPv6 +``` + + +```{cfgcmd} set service pppoe-server ppp-options ipv6-interface-id \<random | x:x:x:x\> + +Specifies peer interface identifier for IPv6. By default is fixed. + +* **random** - Random interface identifier for IPv6 +* **x:x:x:x** - Specify interface identifier for IPv6 +* **ipv4-addr** - Calculate interface identifier from IPv4 address. +* **calling-sid** - Calculate interface identifier from calling-station-id. +``` + +## Scripting + +```{cfgcmd} set service pppoe-server extended-scripts on-change \<path_to_script\> + +Script to run when session interface changed by RADIUS CoA handling +``` + + +```{cfgcmd} set service pppoe-server extended-scripts on-down \<path_to_script\> + +Script to run when session interface going to terminate +``` + + +```{cfgcmd} set service pppoe-server extended-scripts on-pre-up \<path_to_script\> + +Script to run before session interface comes up +``` + + +```{cfgcmd} set service pppoe-server extended-scripts on-up \<path_to_script\> + +Script to run when session interface is completely configured and started +``` + +## Advanced Options + + +### Authentication Advanced Options + +```{cfgcmd} set service pppoe-server authentication local-users username \<user\> disable + +Disable `<user>` account. +``` + + +```{cfgcmd} set service pppoe-server authentication local-users username \<user\> static-ip \<address\> + +Assign static IP address to `<user>` account. +``` + + +```{cfgcmd} set service pppoe-server authentication protocols \<pap | chap | mschap | mschap-v2\> + +Require the peer to authenticate itself using one of the following protocols: +pap, chap, mschap, mschap-v2. +``` + +### Client IP Pool Advanced Options + +```{cfgcmd} set service pppoe-server client-ip-pool \<POOL-NAME\> next-pool \<NEXT-POOL-NAME\> + +Use this command to define the next address pool name. +``` + +### PPP Advanced Options + +```{cfgcmd} set service pppoe-server ppp-options disable-ccp + +Disable Compression Control Protocol (CCP). +CCP is enabled by default. +``` + + +```{cfgcmd} set service pppoe-server ppp-options interface-cache \<number\> + +Specifies number of interfaces to keep in cache. It means that don’t +destroy interface after corresponding session is destroyed, instead +place it to cache and use it later for new sessions repeatedly. +This should reduce kernel-level interface creation/deletion rate lack. +Default value is **0**. +``` + + +```{cfgcmd} set service pppoe-server ppp-options ipv4 \<require | prefer | allow | deny\> + +Specifies IPv4 negotiation preference. + +* **require** - Require IPv4 negotiation +* **prefer** - Ask client for IPv4 negotiation, do not fail if it rejects +* **allow** - Negotiate IPv4 only if client requests (Default value) +* **deny** - Do not negotiate IPv4 +``` + + +```{cfgcmd} set service pppoe-server ppp-options lcp-echo-failure \<number\> + +Defines the maximum `<number>` of unanswered echo requests. Upon reaching the +value `<number>`, the session will be reset. Default value is **3**. +``` + + +```{cfgcmd} set service pppoe-server ppp-options lcp-echo-interval \<interval\> + +If this option is specified and is greater than 0, then the PPP module will +send LCP pings of the echo request every `<interval>` seconds. +Default value is **30**. +``` + + +```{cfgcmd} set service pppoe-server ppp-options lcp-echo-timeout + +Specifies timeout in seconds to wait for any peer activity. If this option +specified it turns on adaptive lcp echo functionality and "lcp-echo-failure" +is not used. Default value is **0**. +``` + + +```{cfgcmd} set service pppoe-server ppp-options min-mtu \<number\> + +Defines minimum acceptable MTU. If client will try to negotiate less then +specified MTU then it will be NAKed or disconnected if rejects greater MTU. +Default value is **100**. +``` + + +```{cfgcmd} set service pppoe-server ppp-options mppe \<require | prefer | deny\> + +Specifies {abbr}`MPPE (Microsoft Point-to-Point Encryption)` negotiation +preference. + +* **require** - ask client for mppe, if it rejects drop connection +* **prefer** - ask client for mppe, if it rejects don't fail. (Default value) +* **deny** - deny mppe + +Default behavior - don't ask client for mppe, but allow it if client wants. +Please note that RADIUS may override this option by MS-MPPE-Encryption-Policy +attribute. +``` + + +```{cfgcmd} set service pppoe-server ppp-options mru \<number\> + +Defines preferred MRU. By default is not defined. +``` + +### Global Advanced options + +```{cfgcmd} set service pppoe-server description \<description\> + +Set description. +``` + + +```{cfgcmd} set service pppoe-server limits burst \<value\> + +Burst count +``` + + +```{cfgcmd} set service pppoe-server limits connection-limit \<value\> + +Acceptable rate of connections (e.g. 1/min, 60/sec) +``` + + +```{cfgcmd} set service pppoe-server limits timeout \<value\> + +Timeout in seconds +``` + + +```{cfgcmd} set service pppoe-server mtu + +Maximum Transmission Unit (MTU) (default: **1492**) +``` + + +```{cfgcmd} set service pppoe-server max-concurrent-sessions + +Maximum number of concurrent session start attempts +``` + + +```{cfgcmd} set service pppoe-server name-server \<address\> + +Connected client should use `<address>` as their DNS server. This +command accepts both IPv4 and IPv6 addresses. Up to two nameservers +can be configured for IPv4, up to three for IPv6. +``` + + +```{cfgcmd} set service pppoe-server service-name \<names\> + +Specifies Service-Name to respond. If absent any Service-Name is +acceptable and client’s Service-Name will be sent back. Also possible +set multiple service-names: `sn1,sn2,sn3` +``` + +Per default the user session is being replaced if a second +authentication request succeeds. Such session requests can be either +denied or allowed entirely, which would allow multiple sessions for a +user in the latter case. If it is denied, the second session is being +rejected even if the authentication succeeds, the user has to terminate +its first session and can then authentication again. + +```{cfgcmd} set service pppoe-server session-control + +* **disable**: Disables session control. +* **deny**: Deny second session authorization. +* **replace**: Terminate first session when second is authorized **(default)** +``` + + +```{cfgcmd} set service pppoe-server shaper fwmark \<1-2147483647\> + +Match firewall mark value +``` + + +```{cfgcmd} set service pppoe-server snmp master-agent + +Enable SNMP +``` + + +```{cfgcmd} set service pppoe-server wins-server \<address\> + +Windows Internet Name Service (WINS) servers propagated to client +``` + +## Monitoring + +```{opcmd} show pppoe-server sessions + +Use this command to locally check the active sessions in the PPPoE +server. +``` +```none +show pppoe-server sessions +ifname | username | ip | calling-sid | rate-limit | state | uptime | rx-bytes | tx-bytes +-------+----------+------------+-------------------+-------------+--------+----------+----------+---------- +ppp0 | foo | 10.1.1.100 | 00:53:00:ba:db:15 | 20480/10240 | active | 00:00:11 | 214 B | 76 B +``` + +## Examples +### IPv4 + +The example below uses ACN as access-concentrator name, assigns an +address from the pool 10.1.1.100-111, terminates at the local endpoint +10.1.1.1 and serves requests only on eth1. + +```none +set service pppoe-server access-concentrator 'ACN' +set service pppoe-server authentication local-users username foo password 'bar' +set service pppoe-server authentication mode 'local' +set service pppoe-server client-ip-pool IP-POOL range '10.1.1.100-10.1.1.111' +set service pppoe-server default-pool 'IP-POOL' +set service pppoe-server interface eth1 +set service pppoe-server gateway-address '10.1.1.2' +set service pppoe-server name-server '10.100.100.1' +set service pppoe-server name-server '10.100.200.1' +``` + +### Dual-Stack IPv4/IPv6 provisioning with Prefix Delegation + +The example below covers a dual-stack configuration. + +```none +set service pppoe-server authentication local-users username test password 'test' +set service pppoe-server authentication mode 'local' +set service pppoe-server client-ip-pool IP-POOL range '192.168.0.1/24' +set service pppoe-server default-pool 'IP-POOL' +set service pppoe-server client-ipv6-pool IPv6-POOL delegate '2001:db8:8003::/48' delegation-prefix '56' +set service pppoe-server client-ipv6-pool IPV6-POOL prefix '2001:db8:8002::/48' mask '64' +set service pppoe-server default-ipv6-pool IPv6-POOL +set service pppoe-server ppp-options ipv6 allow +set service pppoe-server name-server '10.1.1.1' +set service pppoe-server name-server '2001:db8:4860::8888' +set service pppoe-server interface 'eth2' +set service pppoe-server gateway-address '10.100.100.1' +``` + +The client, once successfully authenticated, will receive an IPv4 and an +IPv6 /64 address to terminate the PPPoE endpoint on the client side and +a /56 subnet for the clients internal use. + +```none +vyos@pppoe-server:~$ sh pppoe-server sessions + ifname | username | ip | ip6 | ip6-dp | calling-sid | rate-limit | state | uptime | rx-bytes | tx-bytes +--------+----------+-------------+--------------------------+---------------------+-------------------+------------+--------+----------+----------+---------- + ppp0 | test | 192.168.0.1 | 2001:db8:8002:0:200::/64 | 2001:db8:8003::1/56 | 00:53:00:12:42:eb | | active | 00:00:49 | 875 B | 2.1 KiB +``` + +[accel-ppp attribute]: https://github.com/accel-ppp/accel-ppp/blob/master/accel-pppd/radius/dict/dictionary.accel +[dictionary]: https://github.com/accel-ppp/accel-ppp/blob/master/accel-pppd/radius/dict/dictionary.rfc6911 diff --git a/docs/configuration/service/router-advert.md b/docs/configuration/service/router-advert.md new file mode 100644 index 00000000..10753105 --- /dev/null +++ b/docs/configuration/service/router-advert.md @@ -0,0 +1,121 @@ +(router-advert)= + +# Router Advertisements + +{abbr}`RAs (Router advertisements)` are described in {rfc}`4861#section-4.6.2`. +They are part of what is known as {abbr}`SLAAC (Stateless Address +Autoconfiguration)`. + +Supported interface types: + +> - bonding +> - bridge +> - ethernet +> - geneve +> - l2tpv3 +> - openvpn +> - pseudo-ethernet +> - tunnel +> - vxlan +> - wireguard +> - wireless +> - wwan + +## Configuration + +```{cfgcmd} set service router-advert interface \<interface\> ... +``` + +```{eval-rst} +.. csv-table:: + :header: "Field", "VyOS Option", "Description" + :widths: 10, 10, 20 + + "Cur Hop Limit", "hop-limit", "Hop count field of the outgoing RA packets" + """Managed address configuration"" flag", "managed-flag", "Tell hosts to use the administered stateful protocol (i.e. DHCP) for autoconfiguration" + """Other configuration"" flag", "other-config-flag", "Tell hosts to use the administered (stateful) protocol (i.e. DHCP) for autoconfiguration of other (non-address) information" + "MTU","link-mtu","Link MTU value placed in RAs, excluded in RAs if unset" + "Router Lifetime","default-lifetime","Lifetime associated with the default router in units of seconds" + "Reachable Time","reachable-time","Time, in milliseconds, that a node assumes a neighbor is reachable after having received a reachability confirmation" + "Retransmit Timer","retrans-timer","Time in milliseconds between retransmitted Neighbor Solicitation messages" + "Default Router Preference","default-preference","Preference associated with the default router" + "Interval", "interval", "Min and max intervals between unsolicited multicast RAs" + "DNSSL", "dnssl", "DNS search list to advertise" + "Name Server", "name-server", "Advertise DNS server per https://tools.ietf.org/html/rfc6106" + "Auto Ignore Prefix", "auto-ignore", "Exclude a prefix from being advertised when the wildcard ::/64 prefix is used" + "Captive Portal", "captive-portal", "Advertise a URL pointing to an RFC 8908-compliant API to tell hosts that they are behind a captive portal" +``` + +### Advertising a Prefix + +```{cfgcmd} set service router-advert interface \<interface\> prefix \<prefix/mask\> + +:::{note} +You can also opt for using ::/64 as prefix for your {abbr}`RAs (Router +Advertisements)`. This is a special wildcard prefix that will emit {abbr}`RAs (Router Advertisements)` for every prefix assigned to the interface. +This comes in handy when using dynamically obtained prefixes from DHCPv6-PD. +::: +``` +```{eval-rst} +.. csv-table:: + :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)" + "valid-lifetime","Time in seconds that the prefix will remain valid (default: 30 days)" +``` + +### Advertising a NAT64 Prefix + +```{cfgcmd} set service router-advert interface \<interface\> nat64prefix \<prefix/mask\> + +Enable PREF64 option as outlined in {rfc}`8781`. + +NAT64 prefix mask must be one of: /32, /40, /48, /56, /64 or 96. + +:::{note} +The well known NAT64 prefix is ``64:ff9b::/96`` +::: +``` +```{eval-rst} +.. csv-table:: + :header: "VyOS Field", "Description" + :widths: 10,30 + + "valid-lifetime","Time in seconds that the prefix will remain valid (default: 65528 seconds)" +``` + +### Disabling Advertisements + +To disable advertisements without deleting the configuration: + +```{cfgcmd} set service router-advert interface \<interface\> no-send-advert + +If set, the router will no longer send periodic router advertisements and +will not respond to router solicitations. +``` + +```{cfgcmd} set service router-advert interface \<interface\> no-send-interval + +Advertisement Interval Option (specified by Mobile IPv6) is always included in +Router Advertisements unless this option is set. +``` + +## Example + +Your LAN connected on eth0 uses prefix `2001:db8:beef:2::/64` with the router +beeing `2001:db8:beef:2::1` + +```none +set interfaces ethernet eth0 address 2001:db8:beef:2::1/64 + +set service router-advert interface eth0 default-preference 'high' +set service router-advert interface eth0 name-server '2001:db8::1' +set service router-advert interface eth0 name-server '2001:db8::2' +set service router-advert interface eth0 other-config-flag +set service router-advert interface eth0 prefix 2001:db8:beef:2::/64 +``` diff --git a/docs/configuration/service/broadcast-relay.rst b/docs/configuration/service/rst-broadcast-relay.rst index f64bb208..f64bb208 100644 --- a/docs/configuration/service/broadcast-relay.rst +++ b/docs/configuration/service/rst-broadcast-relay.rst diff --git a/docs/configuration/service/config-sync.rst b/docs/configuration/service/rst-config-sync.rst index a8984a0d..a8984a0d 100644 --- a/docs/configuration/service/config-sync.rst +++ b/docs/configuration/service/rst-config-sync.rst diff --git a/docs/configuration/service/conntrack-sync.rst b/docs/configuration/service/rst-conntrack-sync.rst index 2527407e..2527407e 100644 --- a/docs/configuration/service/conntrack-sync.rst +++ b/docs/configuration/service/rst-conntrack-sync.rst diff --git a/docs/configuration/service/console-server.rst b/docs/configuration/service/rst-console-server.rst index c9ea7f77..c9ea7f77 100644 --- a/docs/configuration/service/console-server.rst +++ b/docs/configuration/service/rst-console-server.rst diff --git a/docs/configuration/service/dhcp-relay.rst b/docs/configuration/service/rst-dhcp-relay.rst index 6a1b02f2..6a1b02f2 100644 --- a/docs/configuration/service/dhcp-relay.rst +++ b/docs/configuration/service/rst-dhcp-relay.rst diff --git a/docs/configuration/service/dhcp-server.rst b/docs/configuration/service/rst-dhcp-server.rst index 09f40b37..09f40b37 100644 --- a/docs/configuration/service/dhcp-server.rst +++ b/docs/configuration/service/rst-dhcp-server.rst diff --git a/docs/configuration/service/dns.rst b/docs/configuration/service/rst-dns.rst index 365e7885..365e7885 100644 --- a/docs/configuration/service/dns.rst +++ b/docs/configuration/service/rst-dns.rst diff --git a/docs/configuration/service/eventhandler.rst b/docs/configuration/service/rst-eventhandler.rst index 9f4ebb04..9f4ebb04 100644 --- a/docs/configuration/service/eventhandler.rst +++ b/docs/configuration/service/rst-eventhandler.rst diff --git a/docs/configuration/service/https.rst b/docs/configuration/service/rst-https.rst index e72e8e8b..e72e8e8b 100644 --- a/docs/configuration/service/https.rst +++ b/docs/configuration/service/rst-https.rst diff --git a/docs/configuration/service/index.rst b/docs/configuration/service/rst-index.rst index fb6f8413..fb6f8413 100644 --- a/docs/configuration/service/index.rst +++ b/docs/configuration/service/rst-index.rst diff --git a/docs/configuration/service/ipoe-server.rst b/docs/configuration/service/rst-ipoe-server.rst index 5d7acd5a..5d7acd5a 100644 --- a/docs/configuration/service/ipoe-server.rst +++ b/docs/configuration/service/rst-ipoe-server.rst diff --git a/docs/configuration/service/lldp.rst b/docs/configuration/service/rst-lldp.rst index 8aee6183..8aee6183 100644 --- a/docs/configuration/service/lldp.rst +++ b/docs/configuration/service/rst-lldp.rst diff --git a/docs/configuration/service/mdns.rst b/docs/configuration/service/rst-mdns.rst index 8a26722e..8a26722e 100644 --- a/docs/configuration/service/mdns.rst +++ b/docs/configuration/service/rst-mdns.rst diff --git a/docs/configuration/service/monitoring.rst b/docs/configuration/service/rst-monitoring.rst index 8faf0eb8..8faf0eb8 100644 --- a/docs/configuration/service/monitoring.rst +++ b/docs/configuration/service/rst-monitoring.rst diff --git a/docs/configuration/service/ntp.rst b/docs/configuration/service/rst-ntp.rst index f4ccb4b1..f4ccb4b1 100644 --- a/docs/configuration/service/ntp.rst +++ b/docs/configuration/service/rst-ntp.rst diff --git a/docs/configuration/service/pppoe-server.rst b/docs/configuration/service/rst-pppoe-server.rst index f763536a..f763536a 100644 --- a/docs/configuration/service/pppoe-server.rst +++ b/docs/configuration/service/rst-pppoe-server.rst diff --git a/docs/configuration/service/router-advert.rst b/docs/configuration/service/rst-router-advert.rst index 80f5ae30..80f5ae30 100644 --- a/docs/configuration/service/router-advert.rst +++ b/docs/configuration/service/rst-router-advert.rst diff --git a/docs/configuration/service/salt-minion.rst b/docs/configuration/service/rst-salt-minion.rst index 8638246b..8638246b 100644 --- a/docs/configuration/service/salt-minion.rst +++ b/docs/configuration/service/rst-salt-minion.rst diff --git a/docs/configuration/service/snmp.rst b/docs/configuration/service/rst-snmp.rst index 6dc13240..6dc13240 100644 --- a/docs/configuration/service/snmp.rst +++ b/docs/configuration/service/rst-snmp.rst diff --git a/docs/configuration/service/ssh.rst b/docs/configuration/service/rst-ssh.rst index 11f58201..11f58201 100644 --- a/docs/configuration/service/ssh.rst +++ b/docs/configuration/service/rst-ssh.rst diff --git a/docs/configuration/service/suricata.rst b/docs/configuration/service/rst-suricata.rst index b72bc52a..b72bc52a 100644 --- a/docs/configuration/service/suricata.rst +++ b/docs/configuration/service/rst-suricata.rst diff --git a/docs/configuration/service/tftp-server.rst b/docs/configuration/service/rst-tftp-server.rst index 84acf3d4..84acf3d4 100644 --- a/docs/configuration/service/tftp-server.rst +++ b/docs/configuration/service/rst-tftp-server.rst diff --git a/docs/configuration/service/webproxy.rst b/docs/configuration/service/rst-webproxy.rst index a6c5ff0a..a6c5ff0a 100644 --- a/docs/configuration/service/webproxy.rst +++ b/docs/configuration/service/rst-webproxy.rst diff --git a/docs/configuration/service/salt-minion.md b/docs/configuration/service/salt-minion.md new file mode 100644 index 00000000..e430f4fc --- /dev/null +++ b/docs/configuration/service/salt-minion.md @@ -0,0 +1,51 @@ +(saltminion)= + +# Salt-Minion + +[SaltStack] is Python-based, open-source +software for event-driven IT automation, remote task execution, and +configuration management. Supporting the "infrastructure as code" +approach to data center system and network deployment and management, +configuration automation, SecOps orchestration, vulnerability remediation, +and hybrid cloud control. + +## Requirements + +To use the Salt-Minion, a running Salt-Master is required. You can find more +in the [Salt Project Documentation](https://docs.saltproject.io/en/latest/contents.html) + +## Configuration + +```{cfgcmd} set service salt-minion hash \<type\> + + The hash type used when discovering file on master server (default: sha256) +``` + + +```{cfgcmd} set service salt-minion id \<id\> + +Explicitly declare ID for this minion to use (default: hostname) +``` + + +```{cfgcmd} set service salt-minion interval \<1-1440\> + +Interval in minutes between updates (default: 60) +``` + + +```{cfgcmd} set service salt-minion master \<hostname | IP\> + +The hostname or IP address of the master +``` + + +```{cfgcmd} set service salt-minion master-key \<key\> + +URL with signature of master for auth reply verification +``` + +Please take a look in the Automation section to find some useful +Examples. + +[saltstack]: https://saltproject.io/ diff --git a/docs/configuration/service/snmp.md b/docs/configuration/service/snmp.md new file mode 100644 index 00000000..ac0429ff --- /dev/null +++ b/docs/configuration/service/snmp.md @@ -0,0 +1,258 @@ +(snmp)= + +# SNMP + +{abbr}`SNMP (Simple Network Management Protocol)` is an Internet Standard +protocol for collecting and organizing information about managed devices on +IP networks and for modifying that information to change device behavior. +Devices that typically support SNMP include cable modems, routers, switches, +servers, workstations, printers, and more. + +SNMP is widely used in network management for network monitoring. SNMP exposes +management data in the form of variables on the managed systems organized in +a management information base ([MIB]) which describe the system status and +configuration. These variables can then be remotely queried (and, in some +circumstances, manipulated) by managing applications. + +Three significant versions of SNMP have been developed and deployed. SNMPv1 is +the original version of the protocol. More recent versions, SNMPv2c and SNMPv3, +feature improvements in performance, flexibility and security. + +SNMP is a component of the Internet Protocol Suite as defined by the Internet +Engineering Task Force (IETF). It consists of a set of standards for network +management, including an application layer protocol, a database schema, and a +set of data objects. + +## Overview and basic concepts + +In typical uses of SNMP, one or more administrative computers called managers +have the task of monitoring or managing a group of hosts or devices on a +computer network. Each managed system executes a software component called an +agent which reports information via SNMP to the manager. + +An SNMP-managed network consists of three key components: + +- Managed devices +- Agent - software which runs on managed devices +- Network management station (NMS) - software which runs on the manager + +A managed device is a network node that implements an SNMP interface that +allows unidirectional (read-only) or bidirectional (read and write) access to +node-specific information. Managed devices exchange node-specific information +with the NMSs. Sometimes called network elements, the managed devices can be +any type of device, including, but not limited to, routers, access servers, +switches, cable modems, bridges, hubs, IP telephones, IP video cameras, +computer hosts, and printers. + +An agent is a network-management software module that resides on a managed +device. An agent has local knowledge of management information and translates +that information to or from an SNMP-specific form. + +A network management station executes applications that monitor and control +managed devices. NMSs provide the bulk of the processing and memory resources +required for network management. One or more NMSs may exist on any managed +network. + +:::{figure} /_static/images/service_snmp_communication_principles_diagram.webp +:alt: Principle of SNMP Communication +:scale: 20 % + +Image thankfully borrowed from +<https://en.wikipedia.org/wiki/File:SNMP_communication_principles_diagram.PNG> +which is under the GNU Free Documentation License +::: + +:::{note} +VyOS SNMP supports both IPv4 and IPv6. +::: + +## SNMP Protocol Versions + +VyOS itself supports [SNMPv2] (version 2) and [SNMPv3] (version 3) where the +later is recommended because of improved security (optional authentication and +encryption). + +### SNMPv2 + +SNMPv2 is the original and most commonly used version. For authorizing clients, +SNMP uses the concept of communities. Communities may have authorization set +to read only (this is most common) or to read and write (this option is not +actively used in VyOS). + +SNMP can work synchronously or asynchronously. In synchronous communication, +the monitoring system queries the router periodically. In asynchronous, the +router sends notification to the "trap" (the monitoring host). + +SNMPv2 does not support any authentication mechanisms, other than client source +address, so you should specify addresses of clients allowed to monitor the +router. Note that SNMPv2 also supports no encryption and always sends data in +plain text. + +#### Example + +```none +# Define a community +set service snmp community routers authorization ro + +# Allow monitoring access from the entire network +set service snmp community routers network 192.0.2.0/24 +set service snmp community routers network 2001::db8:ffff:eeee::/64 + +# Allow monitoring access from specific addresses +set service snmp community routers client 203.0.113.10 +set service snmp community routers client 203.0.113.20 + +# Define optional router information +set service snmp location "UK, London" +set service snmp contact "admin@example.com" + +# Trap target if you want asynchronous communication +set service snmp trap-target 203.0.113.10 + +# Listen only on specific IP addresses (port defaults to 161) +set service snmp listen-address 172.16.254.36 port 161 +set service snmp listen-address 2001:db8::f00::1 +``` + + +### SNMPv3 + +SNMPv3 (version 3 of the SNMP protocol) introduced a whole slew of new security +related features that have been missing from the previous versions. Security +was one of the biggest weakness of SNMP until v3. Authentication in SNMP +Versions 1 and 2 amounts to nothing more than a password (community string) +sent in clear text between a manager and agent. Each SNMPv3 message contains +security parameters which are encoded as an octet string. The meaning of these +security parameters depends on the security model being used. + +The security approach in SNMPv3 targets: + +- Confidentiality – Encryption of packets to prevent snooping by an + unauthorized source. +- Integrity – Message integrity to ensure that a packet has not been tampered + while in transit including an optional packet replay protection mechanism. +- Authentication – to verify that the message is from a valid source. + +(snmp-v3-example)= + +#### Example + +- Let SNMP daemon listen only on IP address 192.0.2.1 +- Configure new SNMP user named "vyos" with password "vyos12345678" +- New user will use SHA/AES for authentication and privacy + +```none +set service snmp listen-address 192.0.2.1 +set service snmp location 'VyOS Datacenter' +set service snmp v3 engineid '000000000000000000000002' +set service snmp v3 group default mode 'ro' +set service snmp v3 group default view 'default' +set service snmp v3 user vyos auth plaintext-password 'vyos12345678' +set service snmp v3 user vyos auth type 'sha' +set service snmp v3 user vyos group 'default' +set service snmp v3 user vyos privacy plaintext-password 'vyos12345678' +set service snmp v3 user vyos privacy type 'aes' +set service snmp v3 view default oid 1 +``` + +After commit the plaintext passwords will be hashed and stored in your +configuration. The resulting CLI config will look like: + +```none +vyos@vyos# show service snmp + listen-address 192.0.2.1 { + } + location "VyOS Datacenter" + v3 { + engineid 000000000000000000000002 + group default { + mode ro + view default + } + user vyos { + auth { + encrypted-password 4e52fe55fd011c9c51ae2c65f4b78ca93dcafdfe + type sha + } + group default + privacy { + encrypted-password 4e52fe55fd011c9c51ae2c65f4b78ca93dcafdfe + type aes + } + } + view default { + oid 1 { + } + } + } +``` + +You can test the SNMPv3 functionality from any linux based system, just run the +following command: `snmpwalk -v 3 -u vyos -a SHA -A vyos12345678 -x AES +-X vyos12345678 -l authPriv 192.0.2.1 .1` + +## VyOS MIBs + +All SNMP MIBs are located in each image of VyOS here: `/usr/share/snmp/mibs/` + +You are be able to download the files using SCP, once the SSH service +has been activated like so + +```none +scp -r vyos@your_router:/usr/share/snmp/mibs /your_folder/mibs +``` + + +## SNMP Extensions + +To extend SNMP agent functionality, custom scripts can be executed every time +the agent is being called. This can be achieved by using +`arbitrary extensioncommands`. The first step is to create a functional +script of course, then upload it to your VyOS instance via the command +`scp your_script.sh vyos@your_router:/config/user-data`. +Once the script is uploaded, it needs to be configured via the command below. + +```none +set service snmp script-extensions extension-name my-extension script your_script.sh +commit +``` + +The OID `.1.3.6.1.4.1.8072.1.3.2.3.1.1.4.116.101.115.116`, once called, will +contain the output of the extension. + +```none +root@vyos:/home/vyos# snmpwalk -v2c -c public 127.0.0.1 nsExtendOutput1 +NET-SNMP-EXTEND-MIB::nsExtendOutput1Line."my-extension" = STRING: hello +NET-SNMP-EXTEND-MIB::nsExtendOutputFull."my-extension" = STRING: hello +NET-SNMP-EXTEND-MIB::nsExtendOutNumLines."my-extension" = INTEGER: 1 +NET-SNMP-EXTEND-MIB::nsExtendResult."my-extension" = INTEGER: 0 +``` + + +## SolarWinds + +If you happen to use SolarWinds Orion as NMS you can also use the Device +Templates Management. A template for VyOS can be easily imported. + +Create a file named `VyOS-1.3.6.1.4.1.44641.ConfigMgmt-Commands` using the +following content: + +```none +<Configuration-Management Device="VyOS" SystemOID="1.3.6.1.4.1.44641"> + <Commands> + <Command Name="Reset" Value="set terminal width 0${CRLF}set terminal length 0"/> + <Command Name="Reboot" Value="reboot${CRLF}Yes"/> + <Command Name="EnterConfigMode" Value="configure"/> + <Command Name="ExitConfigMode" Value="commit${CRLF}exit"/> + <Command Name="DownloadConfig" Value="show configuration commands"/> + <Command Name="SaveConfig" Value="commit${CRLF}save"/> + <Command Name="Version" Value="show version"/> + <Command Name="MenuBased" Value="False"/> + <Command Name="VirtualPrompt" Value=":~"/> + </Commands> +</Configuration-Management> +``` + +[mib]: <https://en.wikipedia.org/wiki/Management_information_base> +[snmpv2]: <https://en.wikipedia.org/wiki/Simple_Network_Management_Protocol#Version_2> +[snmpv3]: <https://en.wikipedia.org/wiki/Simple_Network_Management_Protocol#Version_3> diff --git a/docs/configuration/service/ssh.md b/docs/configuration/service/ssh.md new file mode 100644 index 00000000..d873cbee --- /dev/null +++ b/docs/configuration/service/ssh.md @@ -0,0 +1,366 @@ +(ssh)= + +# SSH + +{abbr}`SSH (Secure Shell)` is a cryptographic network protocol for operating +network services securely over an unsecured network. The standard TCP port for +SSH is 22. The best known example application is for remote login to computer +systems by users. + +SSH provides a secure channel over an unsecured network in a client-server +architecture, connecting an SSH client application with an SSH server. Common +applications include remote command-line login and remote command execution, +but any network service can be secured with SSH. The protocol specification +distinguishes between two major versions, referred to as SSH-1 and SSH-2. + +The most visible application of the protocol is for access to shell accounts +on Unix-like operating systems, but it sees some limited use on Windows as +well. In 2015, Microsoft announced that they would include native support for +SSH in a future release. + +SSH was designed as a replacement for Telnet and for unsecured remote shell +protocols such as the Berkeley rlogin, rsh, and rexec protocols. +Those protocols send information, notably passwords, in plaintext, +rendering them susceptible to interception and disclosure using packet +analysis. The encryption used by SSH is intended to provide confidentiality +and integrity of data over an unsecured network, such as the Internet. + +:::{note} +VyOS 1.1 supported login as user `root`. This has been removed due +to tighter security in VyOS 1.2. +::: + +:::{seealso} +SSH {ref}`ssh_key_based_authentication` +::: + +## Configuration + +```{cfgcmd} set service ssh port \<port\> + +Enabling SSH only requires you to specify the port ``<port>`` you want SSH to +listen on. By default, SSH runs on port 22. +``` + + +```{cfgcmd} set service ssh listen-address \<address\> + +Specify IPv4/IPv6 listen address of SSH server. Multiple addresses can be +defined. +``` + + +```{cfgcmd} set service ssh cipher \<cipher\> + +Define allowed ciphers used for the SSH connection. A number of allowed +ciphers can be specified, use multiple occurrences to allow multiple ciphers. + +List of supported ciphers: ``3des-cbc``, ``aes128-cbc``, ``aes192-cbc``, +``aes256-cbc``, ``aes128-ctr``, ``aes192-ctr``, ``aes256-ctr``, +``aes128-gcm@openssh.com``, ``aes256-gcm@openssh.com``, +``chacha20-poly1305@openssh.com`` +``` + + +```{cfgcmd} set service ssh disable-password-authentication + +Disable password based authentication. Login via SSH keys only. This hardens +security! +``` + + +```{cfgcmd} set service ssh fido pin-required + +Require FIDO2 keys to attest that a user has been verified (e.g. via a PIN). +``` + + +````{cfgcmd} set service ssh fido touch-required + +Require FIDO2 keys to attest that a user is physically present. + +VyOS supports SSH authentication using FIDO2-backed keys generated by OpenSSH. +Two FIDO2 key types are supported by OpenSSH: ``ed25519-sk``, ``ecdsa-sk`` + +Generic FIDO2-backed SSH key generation example: + +:::{code-block} none +ssh-keygen -t ecdsa-sk -O verify-required -C "fido2-ssh-key" +::: + +```{eval-rst} +During key generation, OpenSSH will: + * Request user presence (for example, a physical touch or confirmation) + * Optionally request user verification (PIN), if supported by the authenticator + * Create a local key handle file and a corresponding public key (``.pub``) +``` + +The private key material never leaves the authenticator device. + +VyOS configuration example: + +:::{code-block} none +# Generate a FIDO2 SSH key on the client system +# Copy the public key to the VyOS instance +set system login user vyos authentication public-keys fido key '<public-key>' +set system login user vyos authentication public-keys fido type 'sk-ecdsa-sha2-nistp256@openssh.com' +set service ssh fido touch-required +::: + +You can now log into the system using: ``ssh -i ~/.ssh/id_fido_key vyos@192.0.2.1`` +```` + + +```{cfgcmd} set service ssh disable-host-validation + +Disable the host validation through reverse DNS lookups - can speedup login +time when reverse lookup is not possible. +``` + + +```{cfgcmd} set service ssh mac \<mac\> + +Specifies the available {abbr}`MAC (Message Authentication Code)` algorithms. +The MAC algorithm is used in protocol version 2 for data integrity protection. +Multiple algorithms can be provided by using multiple commands, defining +one algorithm per command. + +List of supported MACs: ``hmac-md5``, ``hmac-md5-96``, ``hmac-ripemd160``, +``hmac-sha1``, ``hmac-sha1-96``, ``hmac-sha2-256``, ``hmac-sha2-512``, +``umac-64@openssh.com``, ``umac-128@openssh.com``, +``hmac-md5-etm@openssh.com``, ``hmac-md5-96-etm@openssh.com``, +``hmac-ripemd160-etm@openssh.com``, ``hmac-sha1-etm@openssh.com``, +``hmac-sha1-96-etm@openssh.com``, ``hmac-sha2-256-etm@openssh.com``, +``hmac-sha2-512-etm@openssh.com``, ``umac-64-etm@openssh.com``, +``umac-128-etm@openssh.com`` +``` + + +```{cfgcmd} set service ssh access-control \<allow | deny\> \<group | user\> \<name\> + +Add access-control directive to allow or deny users and groups. Directives +are processed in the following order of precedence: ``deny-users``, +``allow-users``, ``deny-groups`` and ``allow-groups``. +``` + + +```{cfgcmd} set service ssh client-keepalive-interval \<interval\> + +Specify timeout interval for keepalive message in seconds. +``` + + +```{cfgcmd} set service ssh key-exchange \<kex\> + +Specify allowed {abbr}`KEX (Key Exchange)` algorithms. + +List of supported algorithms: ``diffie-hellman-group1-sha1``, +``diffie-hellman-group14-sha1``, ``diffie-hellman-group14-sha256``, +``diffie-hellman-group16-sha512``, ``diffie-hellman-group18-sha512``, +``diffie-hellman-group-exchange-sha1``, +``diffie-hellman-group-exchange-sha256``, +``ecdh-sha2-nistp256``, ``ecdh-sha2-nistp384``, ``ecdh-sha2-nistp521``, +``curve25519-sha256`` and ``curve25519-sha256@libssh.org``. +``` + + +```{cfgcmd} set service ssh loglevel \<quiet | fatal | error | info | verbose\> + +Set the ``sshd`` log level. The default is ``info``. +``` + + +```{cfgcmd} set service ssh vrf \<name\> + +Specify name of the {abbr}`VRF (Virtual Routing and Forwarding)` instance. +``` + + +```{cfgcmd} set service ssh pubkey-accepted-algorithm \<name\> + +Specifies the signature algorithms that will be accepted for public key +authentication + +List of supported algorithms: ``ssh-ed25519``, +``ssh-ed25519-cert-v01@openssh.com``, ``sk-ssh-ed25519@openssh.com``, +``sk-ssh-ed25519-cert-v01@openssh.com``, ``ecdsa-sha2-nistp256``, +``ecdsa-sha2-nistp256-cert-v01@openssh.com``, ``ecdsa-sha2-nistp384``, +``ecdsa-sha2-nistp384-cert-v01@openssh.com``, ``ecdsa-sha2-nistp521``, +``ecdsa-sha2-nistp521-cert-v01@openssh.com``, +``sk-ecdsa-sha2-nistp256@openssh.com``, +``sk-ecdsa-sha2-nistp256-cert-v01@openssh.com``, +``webauthn-sk-ecdsa-sha2-nistp256@openssh.com``, +``ssh-dss``, ``ssh-dss-cert-v01@openssh.com``, ``ssh-rsa``, +``ssh-rsa-cert-v01@openssh.com``, ``rsa-sha2-256``, +``rsa-sha2-256-cert-v01@openssh.com``, ``rsa-sha2-512``, +``rsa-sha2-512-cert-v01@openssh.com`` +``` + + +```{cfgcmd} set service ssh trusted-user-ca \<name\> + +Specify the name of the OpenSSH key-pair that acts as certificate authority +and will be used to verify user certificates. + +You can use it by adding the OpenSSH key-pair under the PKI subsystem. + +Example: + +:::{code-block} none +# Generate key-pair acting as CA +$ ssh-keygen -f vyos-ssh-ca.key + +# Generate key for user: vyos_testca +$ ssh-keygen -f vyos_testca -C "vyos_tesca@vyos.net" + +# Sign public key from user vyos_testca and insert principal names: vyos, vyos_testca +# with a key lifetime of two weeks - after which the key is unusable +$ ssh-keygen -s vyos-ssh-ca.key -I vyos_testca@vyos.net -n vyos,vyos_testca -V +2w vyos_testca.pub + +$ set system login user vyos_testca +$ set pki openssh test_ca public key AAAAB3N..... +$ set pki openssh test_ca public type ssh-rsa +$ set service ssh trusted-user-ca test_ca +::: +You can now log into the system using: ``ssh -i vyos_testca vyos_testca@vyos.test.com`` +``` + +## 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 + +```{opcmd} restart ssh + +Restart the SSH daemon process, the current session is not affected, only the +background daemon is restarted. +``` +```{opcmd} generate ssh server-key + +Re-generated the public/private keyportion which SSH uses to secure +connections. + +:::{note} +Already learned known_hosts files of clients need an update as the +public key will change. +::: +``` +```{opcmd} generate ssh client-key /path/to/private_key + +Re-generated a known pub/private keyfile which can be used to connect to +other services (e.g. RPKI cache). + +Example: + +:::{code-block} none +vyos@vyos:~$ generate ssh client-key /config/auth/id_rsa_rpki +Generating public/private rsa key pair. +Your identification has been saved in /config/auth/id_rsa_rpki. +Your public key has been saved in /config/auth/id_rsa_rpki.pub. +The key fingerprint is: +SHA256:XGv2PpdOzVCzpmEzJZga8hTRq7B/ZYL3fXaioLFLS5Q vyos@vyos +The key's randomart image is: ++---[RSA 2048]----+ +| oo | +| ..o | +| . o.o.. o.| +| o+ooo o.o| +| Eo* =.o | +| o = +.o*+ | +| = o *.o.o| +| o * +.o+.+| +| =.. o=.oo| ++----[SHA256]-----+ +::: +Two new files ``/config/auth/id_rsa_rpki`` and +``/config/auth/id_rsa_rpki.pub`` +will be created. +``` +```{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, FTPS, HTTP, HTTPS, SCP/SFTP and TFTP. + +Example: + +:::{code-block} none +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... +set system login user alyssa authentication public-keys alyssa@example.net type ssh-rsa +commit +save +exit + +ben@vyos:~$ generate public-key-command user ben path ~/.ssh/id_rsa.pub +# To add this key as an embedded key, run the following commands: +configure +set system login user ben authentication public-keys ben@vyos key AAA... +set system login user ben authentication public-keys ben@vyos type ssh-dss +commit +save +exit +::: +``` +```{opcmd} show log ssh + +Show SSH server log. +``` +```{opcmd} monitor log ssh + +Follow the SSH server log. +``` +```{opcmd} show log ssh dynamic-protection + +Show SSH dynamic-protection log. +``` +```{opcmd} monitor log ssh dynamic-protection + +Follow the SSH dynamic-protection log. +``` +```{opcmd} show ssh dynamic-protection + +Show list of IPs currently blocked by SSH dynamic-protection. +``` +```{opcmd} show ssh fingerprints + +Show SSH server public key fingerprints. +``` +```{opcmd} show ssh fingerprints ascii + +Show SSH server public key fingerprints, including a visual ASCII art representation. +```
\ No newline at end of file diff --git a/docs/configuration/service/suricata.md b/docs/configuration/service/suricata.md new file mode 100644 index 00000000..ca9ae968 --- /dev/null +++ b/docs/configuration/service/suricata.md @@ -0,0 +1,93 @@ +(suricata)= + +# suricata + +Suricata and VyOS are powerful tools for ensuring network security and traffic management. +Suricata is an open-source intrusion detection and prevention system (IDS/IPS) that analyzes network packets in real-time. + +## Suricata Features + +Intrusion Detection (IDS): Analyzes network traffic and detects suspicious activities, attacks, and malicious traffic. +Intrusion Prevention (IPS): Blocks or modifies suspicious traffic in real-time, preventing attacks before they penetrate the network. +Network Security Monitoring (NSM): Collects and analyzes network data to detect anomalies and identify threats. +Multi-Protocol Support: Suricata supports analysis of various network protocols such as HTTP, FTP, SMB, and many others. +In configuration mode, the commands are as follows: + +```none +vyos@vyos# set service suricata +Possible completions: ++> address-group Address group name ++ interface Interface to use + > log Suricata log outputs ++> port-group Port group name +``` + +These commands create a flexible interface for configuring the Suricata service, allowing users to specify addresses, ports, +and logging parameters. + +After completing the service configuration in configuration mode, the main configuration file suricata.yaml is created, +into which all specified parameters are added. Then, to ensure proper operation, the command {opcmd}`update suricata` must be run +from operational mode, waiting for Suricata to update all its rules, which are used for analyzing traffic for threats and attacks. + +## Configuration + +```{cfgcmd} set service suricata address-group \<text\> \<address | group\> + + Address groups are useful when you need to create rules that apply to specific IP addresses. + For example, if you want to create a rule that monitors traffic going to or from a specific IP address, + you can use the group name instead of the actual IP address. This simplifies rule management and makes the + configuration more flexible. + + * ``address`` IP address or subnet. + + * ``group`` Address group. +``` + + +```{cfgcmd} set service suricata port-group \<text\> \<address | group\> + +Port groups are useful when you need to create rules that apply to specific ports. +For example, if you want to create a rule that monitors traffic directed to a specific port or group of ports, +you can use the group name instead of the actual port. This also simplifies rule management and makes +the configuration more flexible. + +* ``port`` Port number. + +* ``group`` Port group. +``` + + +```{cfgcmd} set service suricata interface \<text\> + +The interface that will be monitored by the Suricata service. +``` +```{cfgcmd} set service suricata log eve \<filename | filetype | type\> + + Configuration of the logging file. + + * ``filename`` Log file (default: eve.json). + + * ``filetype`` EVE logging destination (default: regular). + + * ``type`` Log types. +``` + +## Operation Mode + +```{cfgcmd} update suricata + +Checks for the existence of the Suricata configuration file, updates the service, +and then restarts it. If the configuration file is not found, a message indicates that Suricata is not configured. +``` +```{cfgcmd} restart suricata + +Restarts the service. It checks if the Suricata service is active before attempting to restart it. +If it is not active, a message indicates that the service is not configured. This command is used when adding new rules manually. +``` + +## Conclusion + +Using address and port groups allows you to make your Suricata configuration more flexible and manageable. +Instead of specifying IP addresses and ports directly in each rule, you can define them once in the vars section and then +reference them by group names. This is especially useful in large networks and complex configurations where multiple IP addresses +and ports need to be monitored. diff --git a/docs/configuration/service/tftp-server.md b/docs/configuration/service/tftp-server.md new file mode 100644 index 00000000..f4a6c34c --- /dev/null +++ b/docs/configuration/service/tftp-server.md @@ -0,0 +1,78 @@ +(tftp-server)= + +# TFTP Server + +{abbr}`TFTP (Trivial File Transfer Protocol)` is a simple, lockstep file +transfer protocol which allows a client to get a file from or put a file onto +a remote host. One of its primary uses is in the early stages of nodes booting +from a local area network. TFTP has been used for this application because it +is very simple to implement. + +## Configuration + +```{cfgcmd} set service tftp-server directory \<directory\> + +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 +will be migrated. +::: + +```{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. +``` + +```{cfgcmd} set service tftp-server listen-address \<address\> vrf \<name\> +``` + +Additional option to run TFTP server in the {abbr}`VRF (Virtual Routing and Forwarding)` context + +:::{note} +Configuring a listen-address is essential for the service to work. +::: +```{cfgcmd} set service tftp-server allow-upload + +Optional, if you want to enable uploads, else TFTP server will act as a +read-only server. +``` + +### Example + +Provide TFTP server listening on both IPv4 and IPv6 addresses `192.0.2.1` and +`2001:db8::1` serving the content from `/config/tftpboot`. Uploading via +TFTP to this server is disabled. + +The resulting configuration will look like: + +```none +vyos@vyos# show service + tftp-server { + directory /config/tftpboot + listen-address 2001:db8::1 + listen-address 192.0.2.1 + } +``` + +### Verification + +Client: + +```none +vyos@RTR2:~$ tftp -p -l /config/config.boot -r backup 192.0.2.1 +backup1 100% |******************************| 723 0:00:00 ETA +``` + +Server: + +```none +vyos@RTR1# ls -ltr /config/tftpboot/ +total 1 +-rw-rw-rw- 1 tftp tftp 1995 May 19 16:02 backup +``` diff --git a/docs/configuration/service/webproxy.md b/docs/configuration/service/webproxy.md new file mode 100644 index 00000000..28156b2b --- /dev/null +++ b/docs/configuration/service/webproxy.md @@ -0,0 +1,459 @@ +(webproxy)= + +# Webproxy + +The proxy service in VyOS is based on [Squid] and some related modules. + +[Squid] is a caching and forwarding HTTP web proxy. It has a wide variety of +uses, including speeding up a web server by caching repeated requests, caching +web, DNS and other computer network lookups for a group of people sharing +network resources, and aiding security by filtering traffic. Although primarily +used for HTTP and FTP, Squid includes limited support for several other +protocols including Internet Gopher, SSL,[6] TLS and HTTPS. Squid does not +support the SOCKS protocol. + +URL Filtering is provided by [SquidGuard]. + +## Configuration + +```{cfgcmd} set service webproxy append-domain \<domain\> + +Use this command to specify a domain name to be appended to domain-names +within URLs that do not include a dot ``.`` the domain is appended. + +Example: to be appended is set to ``vyos.net`` and the URL received is +``www/foo.html``, the system will use the generated, final URL of +``www.vyos.net/foo.html``. + +:::{code-block} none +set service webproxy append-domain vyos.net +::: +``` + + +```{cfgcmd} set service webproxy cache-size \<size\> + +The size of the on-disk Proxy cache is user configurable. The Proxies default +cache-size is configured to 100 MB. + +Unit of this command is MB. + +:::{code-block} none +set service webproxy cache-size 1024 +::: +``` + + +```{cfgcmd} set service webproxy default-port \<port\> + +Specify the port used on which the proxy service is listening for requests. +This port is the default port used for the specified listen-address. + +Default port is 3128. + +:::{code-block} none +set service webproxy default-port 8080 +::: +``` + + +```{cfgcmd} set service webproxy domain-block \<domain\> + +Used to block specific domains by the Proxy. Specifying "vyos.net" will block +all access to vyos.net, and specifying ".xxx" will block all access to URLs +having an URL ending on .xxx. + +:::{code-block} none +set service webproxy domain-block vyos.net +::: +``` + + +```{cfgcmd} set service webproxy domain-noncache \<domain\> + +Allow access to sites in a domain without retrieving them from the Proxy +cache. Specifying "vyos.net" will allow access to vyos.net but the pages +accessed will not be cached. It useful for working around problems with +"If-Modified-Since" checking at certain sites. + +:::{code-block} none +set service webproxy domain-noncache vyos.net +::: +``` + + +```{cfgcmd} set service webproxy listen-address \<address\> + +Specifies proxy service listening address. The listen address is the IP +address on which the web proxy service listens for client requests. + +For security, the listen address should only be used on internal/trusted +networks! + +:::{code-block} none +set service webproxy listen-address 192.0.2.1 +::: +``` + + +```{cfgcmd} set service webproxy listen-address \<address\> disable-transparent + +Disables web proxy transparent mode at a listening address. + +In transparent proxy mode, all traffic arriving on port 80 and destined for +the Internet is automatically forwarded through the proxy. This allows +immediate proxy forwarding without configuring client browsers. + +Non-transparent proxying requires that the client browsers be configured with +the proxy settings before requests are redirected. The advantage of this is +that the client web browser can detect that a proxy is in use and can behave +accordingly. In addition, web-transmitted malware can sometimes be blocked by +a non-transparent web proxy, since they are not aware of the proxy settings. + +:::{code-block} none +set service webproxy listen-address 192.0.2.1 disable-transparent +::: +``` + + +```{cfgcmd} set service webproxy listen-address \<address\> port \<port\> + +Sets the listening port for a listening address. This overrides the default +port of 3128 on the specific listen address. + +:::{code-block} none +set service webproxy listen-address 192.0.2.1 port 8080 +::: +``` +```{cfgcmd} set service webproxy reply-block-mime \<mime\> + +Used to block a specific mime-type. + +:::{code-block} none +# block all PDFs +set service webproxy reply-block-mime application/pdf +::: +``` +```{cfgcmd} set service webproxy reply-body-max-size \<size\> + +Specifies the maximum size of a reply body in KB, used to limit the reply +size. + +All reply sizes are accepted by default. + +:::{code-block} none +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 + +The embedded Squid proxy can use LDAP to authenticate users against a company +wide directory. The following configuration is an example of how to use Active +Directory as authentication backend. Queries are done via LDAP. + +```{cfgcmd} set service webproxy authentication children \<number\> + +Maximum number of authenticator processes to spawn. If you start too few +Squid will have to wait for them to process a backlog of credential +verifications, slowing it down. When password verifications are done via a +(slow) network you are likely to need lots of authenticator processes. + +This defaults to 5. + +:::{code-block} none +set service webproxy authentication children 10 +::: +``` + + +```{cfgcmd} set service webproxy authentication credentials-ttl \<time\> + +Specifies how long squid assumes an externally validated username:password +pair is valid for - in other words how often the helper program is called for +that user. Set this low to force revalidation with short lived passwords. + +Time is in minutes and defaults to 60. + +:::{code-block} none +set service webproxy authentication credentials-ttl 120 +::: +``` +```{cfgcmd} set service webproxy authentication method \<ldap\> + +Proxy authentication method, currently only LDAP is supported. + +:::{code-block} none +set service webproxy authentication method ldap +::: +``` + + +```{cfgcmd} set service webproxy authentication realm + +Specifies the protection scope (aka realm name) which is to be reported to +the client for the authentication scheme. It is commonly part of the text +the user will see when prompted for their username and password. + +:::{code-block} none +set service webproxy authentication realm "VyOS proxy auth" +::: +``` + +#### LDAP + +```{cfgcmd} set service webproxy authentication ldap base-dn \<base-dn\> + +Specifies the base DN under which the users are located. + +:::{code-block} none +set service webproxy authentication ldap base-dn DC=vyos,DC=net +::: +``` +```{cfgcmd} set service webproxy authentication ldap bind-dn \<bind-dn\> + +The DN and password to bind as while performing searches. + +:::{code-block} none +set service webproxy authentication ldap bind-dn CN=proxyuser,CN=Users,DC=vyos,DC=net +::: +``` + + +```{cfgcmd} set service webproxy authentication ldap filter-expression \<expr\> + +LDAP search filter to locate the user DN. Required if the users are in a +hierarchy below the base DN, or if the login name is not what builds the user +specific part of the users DN. + +The search filter can contain up to 15 occurrences of %s which will be +replaced by the username, as in "uid=%s" for {rfc}`2037` directories. For a +detailed description of LDAP search filter syntax see {rfc}`2254`. + +:::{code-block} none +set service webproxy authentication ldap filter-expression (cn=%s) +::: +``` + + +```{cfgcmd} set service webproxy authentication ldap password \<password\> + +The DN and password to bind as while performing searches. As the password +needs to be printed in plain text in your Squid configuration it is strongly +recommended to use a account with minimal associated privileges. This to limit +the damage in case someone could get hold of a copy of your Squid +configuration file. + +:::{code-block} none +set service webproxy authentication ldap password vyos +::: +``` + + +```{cfgcmd} set service webproxy authentication ldap persistent-connection + +Use a persistent LDAP connection. Normally the LDAP connection is only open +while validating a username to preserve resources at the LDAP server. This +option causes the LDAP connection to be kept open, allowing it to be reused +for further user validations. + +Recommended for larger installations. + +:::{code-block} none +set service webproxy authentication ldap persistent-connection +::: +``` + + +```{cfgcmd} set service webproxy authentication ldap port \<port\> + +Specify an alternate TCP port where the ldap server is listening if other than +the default LDAP port 389. + +:::{code-block} none +set service webproxy authentication ldap port 389 +::: +``` + + +```{cfgcmd} set service webproxy authentication ldap server \<server\> + +Specify the LDAP server to connect to. + +:::{code-block} none +set service webproxy authentication ldap server ldap.vyos.net +::: +``` +```{cfgcmd} set service webproxy authentication ldap use-ssl + +Use TLS encryption. + +:::{code-block} none +set service webproxy authentication ldap use-ssl +::: +``` +```{cfgcmd} set service webproxy authentication ldap username-attribute \<attr\> + +Specifies the name of the DN attribute that contains the username/login. +Combined with the base DN to construct the users DN when no search filter is +specified (filter-expression). + +Defaults to 'uid' + +:::{note} +This can only be done if all your users are located directly under +the same position in the LDAP tree and the login name is used for naming +each user object. If your LDAP tree does not match these criterias or if you +want to filter who are valid users then you need to use a search filter to +search for your users DN (filter-expression). +::: + +:::{code-block} none +set service webproxy authentication ldap username-attribute uid +::: +``` + + +```{cfgcmd} set service webproxy authentication ldap version \<2 | 3\> + +LDAP protocol version. Defaults to 3 if not specified. + +:::{code-block} none +set service webproxy authentication ldap version 2 +::: +``` + +### URL filtering + +```{include} /_include/need_improvement.txt +``` +```{cfgcmd} set service webproxy url-filtering disable + +Disables web filtering without discarding configuration. + +:::{code-block} none +set service webproxy url-filtering disable +::: +``` + +## Operation + +```{include} /_include/need_improvement.txt +``` + +### Filtering +#### Update + +If you want to use existing blacklists you have to create/download a database +first. Otherwise you will not be able to commit the config changes. + +```{opcmd} update webproxy blacklists + +Download/Update complete blacklist + +:::{code-block} none +vyos@vyos:~$ update webproxy blacklists +Warning: No url-filtering blacklist installed +Would you like to download a default blacklist? [confirm][y] +Connecting to ftp.univ-tlse1.fr (193.49.48.249:21) +blacklists.gz 100% |*************************************************************************************************************| 17.0M 0:00:00 ETA +Uncompressing blacklist... +Checking permissions... +Skip link for [ads] -> [publicite] +Building DB for [adult/domains] - 2467177 entries +Building DB for [adult/urls] - 67798 entries +Skip link for [aggressive] -> [agressif] +Building DB for [agressif/domains] - 348 entries +Building DB for [agressif/urls] - 36 entries +Building DB for [arjel/domains] - 69 entries +... +Building DB for [webmail/domains] - 374 entries +Building DB for [webmail/urls] - 9 entries +The webproxy daemon must be restarted +Would you like to restart it now? [confirm][y] +[ ok ] Restarting squid (via systemctl): squid.service. +vyos@vyos:~$ +::: +``` +```{opcmd} update webproxy blacklists category \<category\> + +Download/Update partial blacklist. + +Use tab completion to get a list of categories. +``` + +- To auto update the blacklist files + + `set service webproxy url-filtering squidguard auto-update update-hour 23` + +- To configure blocking add the following to the configuration + + `set service webproxy url-filtering squidguard block-category ads` + + `set service webproxy url-filtering squidguard block-category malware` + +#### Bypassing the webproxy + +```{include} /_include/need_improvement.txt +``` + +Some services don't work correctly when being handled via a web proxy. +So sometimes it is useful to bypass a transparent proxy: + +- To bypass the proxy for every request that is directed to a specific + destination: + + `set service webproxy whitelist destination-address 198.51.100.33` + + `set service webproxy whitelist destination-address 192.0.2.0/24` + +- To bypass the proxy for every request that is coming from a specific source: + + `set service webproxy whitelist source-address 192.168.1.2` + + `set service webproxy whitelist source-address 192.168.2.0/24` + + (This can be useful when a called service has many and/or often changing + destination addresses - e.g. Netflix.) + +## Examples + +```none +vyos@vyos# show service webproxy + authentication { + children 5 + credentials-ttl 60 + ldap { + base-dn DC=example,DC=local + bind-dn CN=proxyuser,CN=Users,DC=example,DC=local + filter-expression (cn=%s) + password Qwert1234 + server ldap.example.local + username-attribute cn + } + method ldap + realm "VyOS Webproxy" + } + cache-size 100 + default-port 3128 + listen-address 192.168.188.103 { + disable-transparent + } +``` + +[squid]: http://www.squid-cache.org/ +[squidguard]: http://www.squidguard.org/ diff --git a/docs/configuration/system/acceleration.md b/docs/configuration/system/acceleration.md new file mode 100644 index 00000000..871129e6 --- /dev/null +++ b/docs/configuration/system/acceleration.md @@ -0,0 +1,158 @@ +(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} none +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} none +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: + +``` +set interfaces vti vti1 address '192.168.1.2/24' +set vpn ipsec authentication psk right id '10.10.10.2' +set vpn ipsec authentication psk right id '10.10.10.1' +set vpn ipsec authentication psk right secret 'Qwerty123' +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 right authentication local-id '10.10.10.2' +set vpn ipsec site-to-site peer right authentication mode 'pre-shared-secret' +set vpn ipsec site-to-site peer right authentication remote-id '10.10.10.1' +set vpn ipsec site-to-site peer right connection-type 'initiate' +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 '10.10.10.2' +set vpn ipsec site-to-site peer right remote-address '10.10.10.1' +set vpn ipsec site-to-site peer right vti bind 'vti1' +``` + +Side B: + +``` +set interfaces vti vti1 address '192.168.1.1/24' +set vpn ipsec authentication psk left id '10.10.10.2' +set vpn ipsec authentication psk left id '10.10.10.1' +set vpn ipsec authentication psk left secret 'Qwerty123' +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 left authentication local-id '10.10.10.1' +set vpn ipsec site-to-site peer left authentication mode 'pre-shared-secret' +set vpn ipsec site-to-site peer left authentication remote-id '10.10.10.2' +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 '10.10.10.1' +set vpn ipsec site-to-site peer left remote-address '10.10.10.2' +set vpn ipsec site-to-site peer left vti bind 'vti1' +``` + +a bandwidth test over the VPN got these results: + +``` +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. + +``` +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.md b/docs/configuration/system/conntrack.md new file mode 100644 index 00000000..2b7279f6 --- /dev/null +++ b/docs/configuration/system/conntrack.md @@ -0,0 +1,218 @@ +# Conntrack + +VyOS can be configured to track connections using the connection +tracking subsystem. Connection tracking becomes operational once either +stateful firewall or NAT is configured. + +## Configure + +```{cfgcmd} set system conntrack table-size \<1-50000000\> +:defaultvalue: + +The connection tracking table contains one entry for each connection being +tracked by the system. +``` + +```{cfgcmd} set system conntrack expect-table-size \<1-50000000\> +:defaultvalue: + +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. +``` + +```{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. +``` + +```{eval-rst} +.. 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 enabled by default. + + | Use `delete system conntrack modules` to deactivate all modules. + | Or, for example ftp, `delete system conntrack modules ftp`. +``` + +```{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. +``` + +### Contrack Timeouts + +You can define custom timeout values to apply to a specific subset of +connections, based on a packet and flow selector. To do this, you need to +create a rule defining the packet and flow selector. + +```{eval-rst} +.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999> + description <test> + + Set a rule description. + +.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999> + destination address <ip-address> +.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999> + source address <ip-address> + + Set a destination and/or source address. Accepted input for ipv4: + + .. code-block:: none + + set system conntrack timeout custom ipv4 rule <1-999999> [source | destination] address + Possible completions: + <x.x.x.x> IPv4 address to match + <x.x.x.x/x> IPv4 prefix to match + <x.x.x.x>-<x.x.x.x> IPv4 address range to match + !<x.x.x.x> Match everything except the specified address + !<x.x.x.x/x> Match everything except the specified prefix + !<x.x.x.x>-<x.x.x.x> Match everything except the specified range + + set system conntrack timeout custom ipv6 rule <1-999999> [source | destination] address + Possible completions: + <h:h:h:h:h:h:h:h> IP address to match + <h:h:h:h:h:h:h:h/x> Subnet to match + <h:h:h:h:h:h:h:h>-<h:h:h:h:h:h:h:h> + IP 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 system conntrack timeout custom [ipv4 | ipv6] rule <1-999999> + destination port <value> +.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999> + 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 [ipv4 | ipv6] rule <1-999999> + protocol tcp close <1-21474836> +.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999> + protocol tcp close-wait <1-21474836> +.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999> + protocol tcp established <1-21474836> +.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999> + protocol tcp fin-wait <1-21474836> +.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999> + protocol tcp last-ack <1-21474836> +.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999> + protocol tcp syn-recv <1-21474836> +.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999> + protocol tcp syn-sent <1-21474836> +.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999> + protocol tcp time-wait <1-21474836> +.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999> + protocol udp replied <1-21474836> +.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999> + protocol udp unreplied <1-21474836> + + Set the timeout in seconds for a protocol or state in a custom rule. +``` + +### Conntrack ignore rules + +:::{note} +**Important note about conntrack ignore rules:** +Starting from vyos-1.5-rolling-202406120020, ignore rules can be defined in +``set firewall [ipv4 | ipv6] prerouting raw ...``. It's expected that in +the future the conntrack ignore rules will be removed. + +> Customized ignore rules, based on a packet and flow selector. +::: + +```{eval-rst} +.. cfgcmd:: set system conntrack ignore [ipv4 | ipv6] rule <1-999999> + description <text> +.. cfgcmd:: set system conntrack ignore [ipv4 | ipv6] rule <1-999999> + destination address <ip-address> +.. cfgcmd:: set system conntrack ignore [ipv4 | ipv6] rule <1-999999> + destination port <port> +.. cfgcmd:: set system conntrack ignore [ipv4 | ipv6] rule <1-999999> + inbound-interface <interface> +.. cfgcmd:: set system conntrack ignore [ipv4 | ipv6] rule <1-999999> + protocol <protocol> +.. cfgcmd:: set system conntrack ignore [ipv4 | ipv6] rule <1-999999> + source address <ip-address> +.. cfgcmd:: set system conntrack ignore [ipv4 | ipv6] rule <1-999999> + source port <port> +.. cfgcmd:: set system conntrack ignore [ipv4 | ipv6] rule <1-999999> + tcp flags [not] <text> + + Allowed values fpr TCP flags: ``ack``, ``cwr``, ``ecn``, ``fin``, ``psh``, + ``rst``, ``syn`` and ``urg``. Multiple values are supported, and for + inverted selection use ``not``, as shown in the example. +``` + +### Conntrack log + +```{eval-rst} +.. cfgcmd:: set system conntrack log event destroy +.. cfgcmd:: set system conntrack log event new +.. cfgcmd:: set system conntrack log event update + + Log the connection tracking events per type. + +.. cfgcmd:: set system conntrack log event destroy icmp +.. cfgcmd:: set system conntrack log event destroy other +.. cfgcmd:: set system conntrack log event destroy tcp +.. cfgcmd:: set system conntrack log event destroy udp +.. cfgcmd:: set system conntrack log event new icmp +.. cfgcmd:: set system conntrack log event new other +.. cfgcmd:: set system conntrack log event new tcp +.. cfgcmd:: set system conntrack log event new udp +.. cfgcmd:: set system conntrack log event update icmp +.. cfgcmd:: set system conntrack log event update other +.. cfgcmd:: set system conntrack log event update tcp +.. cfgcmd:: set system conntrack log event update udp + + Log the connection tracking events per protocol. + +.. cfgcmd:: set system conntrack log timestamp + + Turn on flow-based timestamp extension. + +.. cfgcmd:: set system conntrack log queue-size <100-999999> + + Manage internal queue size, default size is 4096 events. + +.. cfgcmd:: set system conntrack log log-level <info | debug> + + Manage log level +```
\ No newline at end of file diff --git a/docs/configuration/system/console.md b/docs/configuration/system/console.md new file mode 100644 index 00000000..9017fa30 --- /dev/null +++ b/docs/configuration/system/console.md @@ -0,0 +1,59 @@ +(serial-console)= + +# Serial Console + +For the average user a serial console has no advantage over a console offered +by a directly attached keyboard and screen. Serial consoles are much slower, +taking up to a second to fill a 80 column by 24 line screen. Serial consoles +generally only support non-proportional ASCII text, with limited support for +languages other than English. + +There are some scenarios where serial consoles are useful. System administration +of remote computers is usually done using {ref}`ssh`, but there are times when +access to the console is the only way to diagnose and correct software failures. +Major upgrades to the installed distribution may also require console access. + +```{cfgcmd} set system console device \<device\> + +Defines the specified device as a system console. Available console devices +can be (see completion helper): +* ``ttySN`` - Serial device name +* ``ttyAMAN``- Serial device name for some arm64 systems +* ``ttyUSBX`` - USB Serial device name +* ``hvc0`` - Xen console +``` + +```{cfgcmd} set system console device \<device\> kernel + +When set, the selected serial console is used as the kernel boot console. +When removed, the kernel boot console falls back to tty0. + +:::{note} +Only one serial console can carry the ``kernel`` option. +When VyOS is installed via serial console, this option is set automatically +for the serial interface used during installation; usually ``ttyS0`` or +``ttyAMA0``. +::: +``` + +```{cfgcmd} set system console device \<device\> speed \<speed\> + +The speed (baudrate) of the console device. Supported values are: +* ``1200`` - 1200 bps +* ``2400`` - 2400 bps +* ``4800`` - 4800 bps +* ``9600`` - 9600 bps +* ``19200`` - 19,200 bps +* ``38400`` - 38,400 bps (default for Xen console) +* ``57600`` - 57,600 bps +* ``115200`` - 115,200 bps (default for serial console) + +:::{note} +If you use USB to serial converters for connecting to your VyOS +appliance please note that most of them use software emulation without flow +control. This means you should start with a common baud rate (most likely +9600 baud) as otherwise you probably can not connect to the device using +high speed baud rates as your serial converter simply can not process this +data rate. +::: +```
\ No newline at end of file diff --git a/docs/configuration/system/default-route.md b/docs/configuration/system/default-route.md new file mode 100644 index 00000000..9f2793d1 --- /dev/null +++ b/docs/configuration/system/default-route.md @@ -0,0 +1,40 @@ +(default-gateway)= + +# Default Gateway/Route + +In the past (VyOS 1.1) used a gateway-address configured under the system tree +({cfgcmd}`set system gateway-address <address>`), this is no longer supported +and existing configurations are migrated to the new CLI command. + +## Configuration + +```{cfgcmd} set protocols static route 0.0.0.0/0 next-hop \<address\> + +Specify static route into the routing table sending all non local traffic +to the nexthop address \<address\>. +``` + +```{cfgcmd} delete protocols static route 0.0.0.0/0 + +Delete default route from the system. +``` + + +## Operation + +```{opcmd} show ip route 0.0.0.0 + +Show routing table entry for the default route. + +:::{code-block} none +vyos@vyos:~$ show ip route 0.0.0.0 +Routing entry for 0.0.0.0/0 +Known via "static", distance 10, metric 0, best +Last update 09:46:30 ago +* 172.18.201.254, via eth0.201 +::: +``` + +:::{seealso} +Configuration of {ref}`routing-static` +::: diff --git a/docs/configuration/system/flow-accounting.md b/docs/configuration/system/flow-accounting.md new file mode 100644 index 00000000..c97d5473 --- /dev/null +++ b/docs/configuration/system/flow-accounting.md @@ -0,0 +1,209 @@ +(flow-accounting)= + +# Flow Accounting + +VyOS supports flow-accounting for both IPv4 and IPv6 traffic. The system acts +as a flow exporter, and you are free to use it with any compatible collector. + +Flows can be exported via protocol NetFlow (versions 5, 9 and +10/IPFIX). Additionally, you may save flows to an in-memory table +internally in a router. + +:::{warning} +You need to disable the in-memory table in production environments! +Using {abbr}`IMT (In-Memory Table)` may lead to heavy CPU overloading and +unstable flow-accounting behavior. +::: + +## NetFlow / IPFIX + +NetFlow is a feature that was introduced on Cisco routers around 1996 that +provides the ability to collect IP network traffic as it enters or exits an +interface. By analyzing the data provided by NetFlow, a network administrator +can determine things such as the source and destination of traffic, class of +service, and the causes of congestion. A typical flow monitoring setup (using +NetFlow) consists of three main components: + +- **exporter**: aggregates packets into flows and exports flow records towards + one or more flow collectors +- **collector**: responsible for reception, storage and pre-processing of flow + data received from a flow exporter +- **application**: analyzes received flow data in the context of intrusion + detection or traffic profiling, for example + +For connectionless protocols as like ICMP and UDP, a flow is considered +complete once no more packets for this flow appear after configurable timeout. + +NetFlow is usually enabled on a per-interface basis to limit load on the router +components involved in NetFlow, or to limit the amount of NetFlow records +exported. + +## Configuration + +:::{warning} +Using NetFlow on routers with high traffic levels may lead to +high CPU usage and may affect the router's performance. In such cases, +consider using sFlow instead. +::: + +In order for flow accounting information to be collected and displayed for an +interface, the interface must be configured for flow accounting. + +```{cfgcmd} set system flow-accounting interface \<interface\> + +Configure and enable collection of flow information for the interface +identified by \<interface\>. + +You can configure multiple interfaces which would participate in flow +accounting. +``` + +:::{note} +Will be recorded only packets/flows on **incoming** direction in +configured interfaces by default. +::: + +By default, recorded flows will be saved internally and can be listed with the +CLI command. You may disable using the local in-memory table with the command: + +```{cfgcmd} set system flow-accounting disable-imt + +If you need to sample also egress traffic, you may want to +configure egress flow-accounting: +``` + +```{cfgcmd} set system flow-accounting enable-egress + +Internally, in flow-accounting processes exist a buffer for data exchanging +between core process and plugins (each export target is a separated plugin). +If you have high traffic levels or noted some problems with missed records +or stopping exporting, you may try to increase a default buffer size (10 +MiB) with the next command: +``` + +```{cfgcmd} set system flow-accounting buffer-size \<buffer size\> + +In case, if you need to catch some logs from flow-accounting daemon, you may +configure logging facility: +``` + +```{cfgcmd} set system flow-accounting syslog-facility \<facility\> + +Set the syslog facility for flow-accounting log messages. Supported values +include ``daemon``, ``local0`` through ``local7``, and other standard syslog +facilities. +``` + + +### Flow Export + +In addition to displaying flow accounting information locally, one can also +exported them to a collection server. + +#### NetFlow + +```{cfgcmd} set system flow-accounting netflow version \<version\> + +There are multiple versions available for the NetFlow data. The \<version\> +used in the exported flow data can be configured here. The following +versions are supported: +* **5** - Most common version, but restricted to IPv4 flows only +* **9** - NetFlow version 9 (default) +* **10** - {abbr}`IPFIX (IP Flow Information Export)` as per {rfc}`3917` +``` + +```{cfgcmd} set system flow-accounting netflow server \<address\> + +Configure address of NetFlow collector. NetFlow server at \<address\> can +be both listening on an IPv4 or IPv6 address. +``` + +```{cfgcmd} set system flow-accounting netflow source-ip \<address\> + +IPv4 or IPv6 source address of NetFlow packets +``` + +```{cfgcmd} set system flow-accounting netflow engine-id \<id\> + +NetFlow engine-id which will appear in NetFlow data. The range is 0 to 255. +``` + +```{cfgcmd} set system flow-accounting netflow sampling-rate \<rate\> + +Use this command to configure the sampling rate for flow accounting. The +system samples one in every \<rate\> packets, where \<rate\> is the value +configured for the sampling-rate option. The advantage of sampling every n +packets, where n > 1, allows you to decrease the amount of processing +resources required for flow accounting. The disadvantage of not sampling +every packet is that the statistics produced are estimates of actual data +flows. + +Per default every packet is sampled (that is, the sampling rate is 1). +``` + +```{cfgcmd} set system flow-accounting netflow timeout expiry-interval \<interval\> + +Specifies the interval at which Netflow data will be sent to a collector. As +per default, Netflow data will be sent every 60 seconds. + +You may also additionally configure timeouts for different types of +connections. +``` + +```{cfgcmd} set system flow-accounting netflow max-flows \<n\> + +If you want to change the maximum number of flows, which are tracking +simultaneously, you may do this with this command (default 8192). +``` + + +### Example: + +NetFlow v5 example: + +```none +set system flow-accounting netflow engine-id 100 +set system flow-accounting netflow version 5 +set system flow-accounting netflow server 192.168.2.10 port 2055 +``` + + +## Operation + +Once flow accounting is configured on an interfaces it provides the ability to +display captured network traffic information for all configured interfaces. + +```{opcmd} show flow-accounting interface \<interface\> + +Show flow accounting information for given \<interface\>. + + +:::{code-block} none +vyos@vyos:~$ show flow-accounting interface eth0 +IN_IFACE SRC_MAC DST_MAC SRC_IP DST_IP SRC_PORT DST_PORT PROTOCOL TOS PACKETS FLOWS BYTES +---------- ----------------- ----------------- ------------------------ --------------- ---------- ---------- ---------- ----- --------- ------- ------- +eth0 00:53:01:a8:28:ac ff:ff:ff:ff:ff:ff 192.0.2.2 255.255.255.255 5678 5678 udp 0 1 1 178 +eth0 00:53:01:b2:2f:34 33:33:ff:00:00:00 fe80::253:01ff:feb2:2f34 ff02::1:ff00:0 0 0 ipv6-icmp 0 2 1 144 +eth0 00:53:01:1a:b4:53 33:33:ff:00:00:00 fe80::253:01ff:fe1a:b453 ff02::1:ff00:0 0 0 ipv6-icmp 0 1 1 72 +eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 40152 22 tcp 16 39 1 2064 +eth0 00:53:01:c8:33:af ff:ff:ff:ff:ff:ff 192.0.2.3 255.255.255.255 5678 5678 udp 0 1 1 154 +eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 40006 22 tcp 16 146 1 9444 +eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 0 0 icmp 192 27 1 4455 +::: +``` + +```{opcmd} show flow-accounting interface \<interface\> host \<address\> + +Show flow accounting information for given \<interface\> for a specific host +only. + + +:::{code-block} none +vyos@vyos:~$ show flow-accounting interface eth0 host 192.0.2.14 +IN_IFACE SRC_MAC DST_MAC SRC_IP DST_IP SRC_PORT DST_PORT PROTOCOL TOS PACKETS FLOWS BYTES +---------- ----------------- ----------------- ----------- ---------- ---------- ---------- ---------- ----- --------- ------- ------- +eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 40006 22 tcp 16 197 2 12940 +eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 40152 22 tcp 16 94 1 4924 +eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 0 0 icmp 192 36 1 5877 +::: +```
\ No newline at end of file diff --git a/docs/configuration/system/frr.md b/docs/configuration/system/frr.md new file mode 100644 index 00000000..40305ad7 --- /dev/null +++ b/docs/configuration/system/frr.md @@ -0,0 +1,45 @@ +(system-frr)= + +# FRR + +VyOS uses [FRRouting](https://frrouting.org/) as the control plane for dynamic +and static routing. The routing daemon behavior can be adjusted during runtime, +but requires either a restart of the routing daemon, or a reboot of the system. + +```{cfgcmd} set system frr bmp + +Enable {abbr}`BMP (BGP Monitoring Protocol)` support. +``` + +```{cfgcmd} set system frr descriptors \<number\> + +This allows the operator to control the number of open file descriptors +each daemon is allowed to start with. If the operator plans to run bgp with +several thousands of peers then this is where we would modify FRR to allow +this to happen. +``` + +```{cfgcmd} set system frr irdp + +Enable ICMP Router Discovery Protocol support. +``` + +```{cfgcmd} set system frr profile \<traditional | datacenter\> + +Select an FRR profile to adapt its default settings. If unset, the +traditional profile is applied. +``` + +```{cfgcmd} set system frr snmp \<daemon\> + +Enable SNMP support for an individual routing daemon. + +Supported daemons: +- bgpd +- isisd +- ldpd +- ospf6d +- ospfd +- ripd +- zebra +```
\ No newline at end of file diff --git a/docs/configuration/system/host-name.md b/docs/configuration/system/host-name.md new file mode 100644 index 00000000..81840d1f --- /dev/null +++ b/docs/configuration/system/host-name.md @@ -0,0 +1,70 @@ +(host-information)= + +# Host Information + +This section describes the system's host information and how to configure them, +it covers the following topics: + +- Host name +- Domain +- IP address +- Aliases + +## Hostname + +A hostname is the label (name) assigned to a network device (a host) on a +network and is used to distinguish one device from another on specific networks +or over the internet. On the other hand this will be the name which appears on +the command line prompt. + +```{cfgcmd} set system host-name \<hostname\> + + The hostname can be up to 63 characters. A hostname + must start and end with a letter or digit, and have as interior characters + only letters, digits, or a hyphen. + + The default hostname used is `vyos`. +``` + +## Domain Name + + +A domain name is the label (name) assigned to a computer network and is thus +unique. VyOS appends the domain name as a suffix to any unqualified name. For +example, if you set the domain name `example.com`, and you would ping the +unqualified name of `crux`, then VyOS qualifies the name to `crux.example.com`. + +```{cfgcmd} set system domain-name \<domain\> + +Configure system domain name. A domain name must start and end with a letter +or digit, and have as interior characters only letters, digits, or a hyphen. +``` + +## 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. 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\> + +Create a static hostname mapping which will always resolve the name +`<hostname>` to IP address `<address>`. +``` +```{cfgcmd} set system static-host-mapping host-name \<hostname\> alias \<alias\> + +Create named `<alias>` for the configured static mapping for `<hostname>`. +Thus the address configured as {cfgcmd}`set system static-host-mapping +host-name <hostname> inet <address>` can be reached via multiple names. + +Multiple aliases can be specified per host-name. +```
\ No newline at end of file diff --git a/docs/configuration/system/index.md b/docs/configuration/system/index.md new file mode 100644 index 00000000..e0b8a5a1 --- /dev/null +++ b/docs/configuration/system/index.md @@ -0,0 +1,34 @@ +# System + +```{toctree} +:includehidden: true +:maxdepth: 1 + +acceleration +conntrack +console +flow-accounting +frr +host-name +ip +ipv6 +lcd +login +name-server +option +proxy +sflow +syslog +sysctl +task-scheduler +time-zone +updates +watchdog +``` + +```{toctree} +:includehidden: true +:maxdepth: 1 + +default-route +``` diff --git a/docs/configuration/system/ip.md b/docs/configuration/system/ip.md new file mode 100644 index 00000000..717ee57d --- /dev/null +++ b/docs/configuration/system/ip.md @@ -0,0 +1,126 @@ +# IP + +## System configuration commands + +```{cfgcmd} set system ip disable-forwarding + +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 +the ARP cache (1024, 2048, 4096, 8192, 16384, 32768). +``` + +```{cfgcmd} set system ip multipath layer4-hashing + +Use this command to use Layer 4 information for IPv4 ECMP hashing. +``` + +```{cfgcmd} set system ip import-table \<table-id\> + +Use this command to immport the table, by given table id, into the main RIB. +``` + +```{cfgcmd} set system ip import-table \<table-id\> distance \<distance\> + +Use this command to override the default distance when importing routers +from the alternate table. +``` + +```{cfgcmd} set system ip import-table \<table-id\> route-map \<route-map\> + +Use this command to filter routes that are imported into the main table +from alternate table using route-map. +``` + + +### Zebra/Kernel route filtering + +Zebra supports prefix-lists and Route Maps to match routes received from +other FRR components. The permit/deny facilities provided by these commands +can be used to filter which routes zebra will install in the kernel. + +```{cfgcmd} set system ip protocol \<protocol\> route-map \<route-map\> + +Apply a route-map filter to routes for the specified protocol. The following +protocols can be used: any, babel, bgp, eigrp, isis, ospf, rip, static + +:::{note} +If you choose any as the option that will cause all protocols that +are sending routes to zebra. +::: +``` + + +### Nexthop Tracking + +Nexthop tracking resolve nexthops via the default route by default. This is enabled +by default for a traditional profile of FRR which we use. It and can be disabled if +you do not want to e.g. allow BGP to peer across the default route. + +```{cfgcmd} set system ip nht no-resolve-via-default + +Do not allow IPv4 nexthop tracking to resolve via the default route. This +parameter is configured per-VRF, so the command is also available in the VRF +subnode. +``` + + +## Operational commands + +### show commands + +See below the different parameters available for the IPv4 **show** command: + +```none +vyos@vyos:~$ show ip +Possible completions: + access-list Show all IP access-lists + as-path-access-list + Show all as-path-access-lists + bgp Show Border Gateway Protocol (BGP) information + community-list + Show IP community-lists + extcommunity-list + Show extended IP community-lists + forwarding Show IP forwarding status + groups Show IP multicast group membership + igmp Show IGMP (Internet Group Management Protocol) information + large-community-list + Show IP large-community-lists + multicast Show IP multicast + ospf Show IPv4 Open Shortest Path First (OSPF) routing information + pim Show PIM (Protocol Independent Multicast) information + ports Show IP ports in use by various system services + prefix-list Show all IP prefix-lists + protocol Show IP route-maps per protocol + rip Show Routing Information Protocol (RIP) information + route Show IP routes +``` + + +### reset commands + +And the different IPv4 **reset** commands available: + +```none +vyos@vyos:~$ reset ip +Possible completions: + arp Reset Address Resolution Protocol (ARP) cache + bgp Clear Border Gateway Protocol (BGP) statistics or status + igmp IGMP clear commands + multicast IP multicast routing table + route Reset IP route +``` diff --git a/docs/configuration/system/ipv6.md b/docs/configuration/system/ipv6.md new file mode 100644 index 00000000..ee0a6ade --- /dev/null +++ b/docs/configuration/system/ipv6.md @@ -0,0 +1,193 @@ +# IPv6 + +## System configuration commands + +```{cfgcmd} set system ipv6 disable-forwarding + + Use this command to disable IPv6 forwarding on all interfaces. +``` + + +```{cfgcmd} set system ipv6 neighbor table-size \<number\> + +Use this command to define the maximum number of entries to keep in +the Neighbor cache (1024, 2048, 4096, 8192, 16384, 32768). +``` + + +```{cfgcmd} set system ipv6 strict-dad + +Use this command to disable IPv6 operation on interface when +Duplicate Address Detection fails on Link-Local address. +``` + + +```{cfgcmd} set system ipv6 multipath layer4-hashing + +Use this command to user Layer 4 information for ECMP hashing. +``` + +### Zebra/Kernel route filtering + + +Zebra supports prefix-lists and Route Maps to match routes received from +other FRR components. The permit/deny facilities provided by these commands +can be used to filter which routes zebra will install in the kernel. + +```{cfgcmd} set system ipv6 protocol \<protocol\> route-map \<route-map\> + +Apply a route-map filter to routes for the specified protocol. The following +protocols can be used: any, babel, bgp, isis, ospfv3, ripng, static + +:::{note} +If you choose any as the option that will cause all protocols that +are sending routes to zebra. +::: +``` + +### Nexthop Tracking + + +Nexthop tracking resolve nexthops via the default route by default. This is enabled +by default for a traditional profile of FRR which we use. It and can be disabled if +you do not want to e.g. allow BGP to peer across the default route. + +```{cfgcmd} set system ipv6 nht no-resolve-via-default + +Do not allow IPv6 nexthop tracking to resolve via the default route. This +parameter is configured per-VRF, so the command is also available in the VRF +subnode. +``` + +## Operational commands + + +### Show commands + +```{opcmd} show ipv6 neighbors + +Use this command to show IPv6 Neighbor Discovery Protocol information. +``` + + +```{opcmd} show ipv6 groups + +Use this command to show IPv6 multicast group membership. +``` + + +```{opcmd} show ipv6 forwarding + +Use this command to show IPv6 forwarding status. +``` + + +```{opcmd} show ipv6 route + +Use this command to show IPv6 routes. + +Check the many parameters available for the show ipv6 route command: + +:::{code-block} none +vyos@vyos:~$ show ipv6 route +Possible completions: + <Enter> Execute the current command + <X:X::X:X> Show IPv6 routes of given address or prefix + <X:X::X:X/M> + bgp Show IPv6 BGP routes + cache Show kernel IPv6 route cache + connected Show IPv6 connected routes + forward Show kernel IPv6 route table + isis Show IPv6 ISIS routes + kernel Show IPv6 kernel routes + ospfv3 Show IPv6 OSPF6 routes + ripng Show IPv6 RIPNG routes + static Show IPv6 static routes + summary Show IPv6 routes summary + table Show IP routes in policy table + tag Show only routes with tag + vrf Show IPv6 routes in VRF +::: +``` +```{opcmd} show ipv6 prefix-list + + Use this command to show all IPv6 prefix lists + + There are different parameters for getting prefix-list information: + + :::{code-block} none + vyos@vyos:~$ show ipv6 prefix-list + Possible completions: + <Enter> Execute the current command + <WORD> Show specified IPv6 prefix-list + detail Show detail of IPv6 prefix-lists + summary Show summary of IPv6 prefix-lists + ::: +``` + + +```{opcmd} show ipv6 access-list + +Use this command to show all IPv6 access lists + +You can also specify which IPv6 access-list should be shown: + +:::{code-block} none +vyos@vyos:~$ show ipv6 access-list +Possible completions: + <Enter> Execute the current command + <text> Show specified IPv6 access-list +::: +``` +```{opcmd} show ipv6 ospfv3 + + Use this command to get information about OSPFv3. + + You can get more specific OSPFv3 information by using the parameters + shown below: + + :::{code-block} none + vyos@vyos:~$ show ipv6 ospfv3 + Possible completions: + <Enter> Execute the current command + area Show OSPFv3 spf-tree information + border-routers + Show OSPFv3 border-router (ABR and ASBR) information + database Show OSPFv3 Link state database information + interface Show OSPFv3 interface information + linkstate Show OSPFv3 linkstate routing information + neighbor Show OSPFv3 neighbor information + redistribute Show OSPFv3 redistribute External information + route Show OSPFv3 routing table information + ::: +``` + + +```{opcmd} show ipv6 ripng + +Use this command to get information about the RIPNG protocol +``` + + +```{opcmd} show ipv6 ripng status + +Use this command to show the status of the RIPNG protocol +``` + +### Reset commands + +```{opcmd} reset bgp ipv6 \<address\> + +Use this command to clear Border Gateway Protocol statistics or +status. +``` +```{opcmd} reset ipv6 neighbors \<address | interface\> + +Use this command to reset IPv6 Neighbor Discovery Protocol cache for +an address or interface. +``` +```{opcmd} reset ipv6 route cache + +Use this command to flush the kernel IPv6 route cache. +An address can be added to flush it only for that route. +```
\ No newline at end of file diff --git a/docs/configuration/system/lcd.md b/docs/configuration/system/lcd.md new file mode 100644 index 00000000..ef9031ea --- /dev/null +++ b/docs/configuration/system/lcd.md @@ -0,0 +1,41 @@ +(system-display)= + +# System Display (LCD) + +The system LCD {abbr}`LCD (Liquid-crystal display)` option is for users running +VyOS on hardware that features an LCD display. This is typically a small display +built in an 19 inch rack-mountable appliance. Those displays are used to show +runtime data. + +To configure your LCD display you must first identify the used hardware, and +connectivity of the display to your system. This can be any serial port +(`ttySxx`) or serial via USB or even old parallel port interfaces. + +## Configuration + +```{cfgcmd} set system lcd device \<device\> + +This is the name of the physical interface used to connect to your LCD +display. Tab completion is supported and it will list you all available +serial interface. + +For serial via USB port information please refer to the USB hardware section. +``` + +```{cfgcmd} set system lcd model \<model\> + +This is the LCD model used in your system. + +At the time of this writing the following displays are supported: +* Crystalfontz CFA-533 +* Crystalfontz CFA-631 +* Crystalfontz CFA-633 +* Crystalfontz CFA-635 + +:::{note} +We can't support all displays from the beginning. If your display +type is missing, please create a feature request via +Phabricator. +::: +``` + diff --git a/docs/configuration/system/login.md b/docs/configuration/system/login.md new file mode 100644 index 00000000..288d30a8 --- /dev/null +++ b/docs/configuration/system/login.md @@ -0,0 +1,604 @@ +--- +lastproofread: '2026-01-12' +--- + +(user-management)= + +# Login/user management + +The default VyOS user account (`vyos`), as well as newly created user accounts, +possess full system configuration privileges. These accounts are granted sudo +privileges, allowing them to execute commands as the root user. + +VyOS supports both local authentication and remote authentication via +{abbr}`RADIUS (Remote Authentication Dial-In User Service)`/ {abbr}`TACACS+ +(Terminal Access Controller Access-Control System)`. + +## Local authentication + +```{cfgcmd} set system login user \<name\> full-name "\<string\>" + +**Configure the real name or description for a system user.** + +If the description includes spaces, enclose ``<string>`` in double quotes. + +If the user ``<name>`` already exists, the command updates the current +description. If not, it creates a new user with the specified description. +``` + +```{cfgcmd} set system login user \<name\> authentication plaintext-password \<password\> + +**Configure a password for a system user.** + +Enter the password in plaintext. Upon ``commit``, VyOS hashes the password for +secure storage and removes the plaintext value. + +If the user ``<name>`` already exists, the command updates the current password. +If not, it creates a new user with the specified plaintext password. +``` + +```{cfgcmd} set system login user \<name\> authentication encrypted-password \<password\> + +**Configure a pre-encrypted password for a system user.** + +Enter the password in its hashed format. Upon ``commit``, VyOS stores this value +directly without modification. + +If the user ``<name>`` already exists, the command updates the current password. +If not, it creates a new user with the specified pre-encrypted password. +``` + +```{cfgcmd} set system login user \<name\> authentication principal \<principal\> + +**Configure an SSH certificate principal for a system user.** + +Enter the principal (a string included in the user's signed SSH certificate). +Upon ``commit``, VyOS stores this mapping, allowing the user to log in if the +certificate they present contains this principal. + +If the user ``<name>`` already exists, the command updates the principal. If not, +it creates a new user linked to the specified principal. + +**If not configured**, the principal defaults to ``<name>``. +``` + +```{cfgcmd} set system login user \<name\> disable + +**Disable a system user account.** + +VyOS locks the account, preventing the user from logging in. +``` + +(ssh_key_based_authentication)= + +## Key-based authentication + +Key-based authentication is the recommended method for securing SSH access in +VyOS. It uses a **public/private key pair** to verify user identity without +requiring a password. To authorize access, you assign **SSH public keys** to +user accounts on the router, while SSH private keys remain on local devices. +VyOS allows assigning multiple SSH public keys to a single user account, which +is useful for accessing a router from different devices. + +### Generate the key pair + +Generate an SSH key pair on your **local machine** using the `ssh-keygen` +command. This creates two files: +- **Private key** (e.g., `id_rsa`): Remains on your local machine and must + never be shared. +- **Public key** (e.g., `id_rsa.pub`): Is used to configure the VyOS user + account. By default, it is saved to `~/.ssh/id_rsa.pub`. + +Each SSH public key consists of three parts, separated by spaces: +- **Encryption algorithm type:** `ssh-rsa`, `ssh-ed25519`, etc. +- **Key:** The actual data (a long string beginning with `AAAA...`). +- **Comment:** An identifier for your reference (e.g., `user@host`). + +Only the encryption algorithm type and key parts are required to +configure the authorization entry in VyOS. The comment part is optional. + +:::{seealso} +{ref}`SSH operation <ssh_operation>` +::: + +:::{warning} +SSH key strings are long. When copying and pasting, ensure your +terminal does not insert line breaks. The key must be entered as a **single +line** to function correctly. +::: + +### Configure the router + +To configure SSH public key authentication for a user account, run the +following two commands using the same `<identifier>`: + +```{cfgcmd} set system login user \<username\> authentication public-keys \<identifier\> key \<key\> + +**Configure the SSH public key for the user account.** +* ``<identifier>``: A unique label that identifies this specific key entry. +* ``<key>``: The actual string of characters from your public key. +``` + +```{cfgcmd} set system login user \<username\> authentication public-keys \<identifier\> type \<type\> + +**Configure the SSH key's encryption type.** + +The following encryption algorithm types are available: + +* ``ecdsa-sha2-nistp256`` +* ``ecdsa-sha2-nistp384`` +* ``ecdsa-sha2-nistp521`` +* ``ssh-dss`` +* ``ssh-ed25519`` +* ``ssh-rsa`` + +:::{note} +To assign multiple SSH public keys to a user account, repeat the +commands above with a unique identifier for each key. +::: +``` + +```{cfgcmd} set system login user \<username\> authentication public-keys \<identifier\> options \<options\> + +**Configure specific restrictions or behaviors for an SSH public key.** + +``<options>``: A string of comma-separated values that define permissions +or restrictions for this key. + +The command accepts standard OpenSSH options listed in the router's +``~/.ssh/authorized_keys`` file. + +To include a ``"`` character in the options string, use ``"``. + +For example, to restrict allowed source IP addresses for an SSH public key, +use: ``from="10.0.0.0/24"``. +``` + + +## OTP-based MFA + +VyOS lets you enhance user access security by enabling {abbr}`OTP (One-time +password)`-based {abbr}`MFA (Multi-factor Authentication)` for individual +users. Users with {abbr}`OTP (One-time password)`-based {abbr}`MFA +(Multi-factor Authentication)` must enter a valid {abbr}`OTP (One-time +password)` along with their password at login. Users without {abbr}`OTP +(One-time password)`-based {abbr}`MFA (Multi-factor Authentication)` use +standard authentication. + +```{cfgcmd} set system login user \<username\> authentication otp key \<key\> + +**Configure** {abbr}`OTP (One-time password)`**-based** {abbr}`MFA +(Multi-factor Authentication)` **for a user.** + +``<key>``: A Base32-encoded secret key. This key must be added to the user's +authenticator app to generate valid {abbr}`OTPs (One-time passwords)`. + +**When configured**, the user is required to enter their password followed by +a valid OTP for all subsequent logins. +``` + + +### OTP settings + +```{cfgcmd} set system login user \<username\> authentication otp rate-limit \<limit\> + +**Configure the number of** {abbr}`OTP (One-time password)` **authentication +attempts allowed within a specified time period.** + +If this limit is exceeded, the user is temporarily blocked. + +The default value is 3 attempts. The valid range is 1 to 10 attempts. +``` + +```{cfgcmd} set system login user \<username\> authentication otp rate-time \<seconds\> + +**Configure the time period, in seconds, for tracking** {abbr}`OTP (One-time +password)` **authentication attempts.** + +The default value is 30 seconds. The valid range is 1 to 600 seconds. +``` + +```{cfgcmd} set system login user \<username\> authentication otp window-size \<size\> + +**Configure the** {abbr}`OTP (One-time password)` **window size for a user.** + +The {abbr}`OTP (One-time password)` window size defines the number of +concurrently valid {abbr}`OTPs (One-time passwords)` that the authentication +server accepts. This setting assumes a new token is generated every 30 seconds. + +The default value is 3. This permits 3 concurrent codes: the code for the +current 30-second interval, the preceding code, and the following code. This +allows up to 30 seconds of time skew between the authentication server and +client. + +If the window size is increased to 17, the system permits 17 concurrent codes +(the current code, the 8 preceding codes, and the 8 following codes). This +allows for a time skew of up to 4 minutes. + +The valid range is 1 to 21. +``` + + +### Generate an OTP-key + +Use the following command to generate an OTP key: + +```{cfgcmd} generate system login username \<username\> otp-key hotp-time rate-limit \<1-10\> rate-time \<15-600\> window-size \<1-21\> +``` + +Key generation example: + +```none +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 the OTP key for a user + +Use the following command to display the {abbr}`OTP (One-time password)` +key for a user: + +```{cfgcmd} sh system login authentication user \<username\> otp \<full | key-b32 | qrcode | uri\> +``` + +Example: + +```none +vyos@vyos:~$ sh system login authentication user otptester otp full +# You can share the OTP key with the user. They just need to scan the QR in their 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' +``` + +Once {abbr}`OTP (One-time password)`-based {abbr}`MFA (Multi-factor +Authentication)` is configured for a user account, this user must enter their +standard password followed by the current 6-digit OTP code at login. For +example, if the user's password is `vyosrocks` and the OTP is `817454`, they +should enter `vyosrocks817454`. + +## RADIUS authentication + +For large-scale deployments, managing individual user accounts across multiple +VyOS instances is inefficient. VyOS supports centralized authentication via +{abbr}`RADIUS (Remote Authentication Dial-In User Service)`, consolidating user +account management on a single backend server. + +### Configuration + +```{cfgcmd} set system login radius server \<address\> key \<secret\> + +**Configure the** {abbr}`RADIUS (Remote Authentication Dial-In User Service)` +**server's IP address and shared secret.** + +The shared secret is used to verify the router's identity and to encrypt user +passwords during authentication. + +You can configure multiple {abbr}`RADIUS (Remote Authentication Dial-In User +Service)` servers. +``` + +```{cfgcmd} set system login radius server \<address\> port \<port\> + +**Configure the UDP port for communication with the** {abbr}`RADIUS (Remote +Authentication Dial-In User Service)` **server.** + +The default port is 1812. +``` + +```{cfgcmd} set system login radius server \<address\> disable + +**Disable a** {abbr}`RADIUS (Remote Authentication Dial-In User Service)` +**server from the authentication process.** + +Disabling a specific {abbr}`RADIUS (Remote Authentication Dial-In User +Service)` server doesn’t remove its configuration settings (the server’s IP +address and shared secret). +``` + +```{cfgcmd} set system login radius server \<address\> timeout \<timeout\> + +Configure the duration, in seconds, that the VyOS router waits for a +response from the {abbr}`RADIUS (Remote Authentication Dial-In User Service)` +server after sending an authentication request. + +If the server does not respond within this timeframe, the VyOS router tries to +connect to another configured server or falls back to local authentication. +``` + +```{cfgcmd} set system login radius source-address \<address\> + +**Configure the source IP address the router uses for** {abbr}`RADIUS (Remote +Authentication Dial-In User Service)` **authentication requests.** + +A consistent source IP address is recommended as RADIUS servers typically +accept requests only from known, trusted IP addresses. + +If not explicitly defined, the router uses the current egress interface +address, which may change (e.g., due to a link outage), causing authentication +failures. +``` + +```{cfgcmd} set system login radius vrf \<name\> + +**Configure the router to send all** {abbr}`RADIUS (Remote Authentication +Dial-In User Service)` **authentication requests via a specific VRF.** + +By default, {abbr}`RADIUS (Remote Authentication Dial-In User Service)` +authentication requests are sent via the global routing table. +``` + +### Configuration example + +```none +set system login radius server 192.168.0.2 key 'test-vyos' +set system login radius server 192.168.0.2 port '1812' +set system login radius server 192.168.0.2 timeout '5' +set system login radius source-address '192.168.0.1' +``` + +If communication with the {abbr}`RADIUS (Remote Authentication Dial-In User +Service)` server fails, the router falls back to local user authentication. +During this process, users may experience a login delay while the system waits +for the {abbr}`RADIUS (Remote Authentication Dial-In User Service)` request to +time out. This delay depends on the configured timeout value. + +:::{hint} +To grant administrative privileges to {abbr}`RADIUS (Remote +Authentication Dial-In User Service)`-authenticated users, the server must +return the Cisco-AV-Pair attribute set to `shell:priv-lvl=15`. Otherwise, users +receive standard privileges and cannot perform configuration tasks. +::: + +## TACACS+ authentication + +In addition to {abbr}`RADIUS (Remote Authentication Dial-In User Service)`, +VyOS supports {abbr}`TACACS+ (Terminal Access Controller Access Control +System)`, which is commonly used in large enterprise environments. + +Unlike {abbr}`RADIUS (Remote Authentication Dial-In User Service)`, +{abbr}`TACACS+ (Terminal Access Controller Access Control System)` separates +Authentication, Authorization, and Accounting (AAA) into independent processes +and encrypts the entire packet body for enhanced security. + +{abbr}`TACACS+ (Terminal Access Controller Access Control System)` is defined +in {rfc}`8907`. +(tacacs-configuration)= + +### Configuration + +```{cfgcmd} set system login tacacs server \<address\> key \<secret\> + +**Configure the** {abbr}`TACACS+ (Terminal Access Controller Access Control +System)` **server IP address and shared secret.** + +Unlike {abbr}`RADIUS (Remote Authentication Dial-In User Service)`, which +encrypts only passwords, {abbr}`TACACS+ (Terminal Access Controller Access +Control System)` encrypts the entire packet body for enhanced security. + +You can configure multiple {abbr}`TACACS+ (Terminal Access Controller Access +Control System)` servers. +``` + +```{cfgcmd} set system login tacacs server \<address\> port \<port\> + +**Configure the TCP port for communication with the** {abbr}`TACACS+ (Terminal +Access Controller Access Control System)` **server.** + +The default port is 49. +``` + +```{cfgcmd} set system login tacacs server \<address\> disable + +**Disable a** {abbr}`TACACS+ (Terminal Access Controller Access Control +System)` **server from the authentication process.** + +Disabling a specific {abbr}`TACACS+ (Terminal Access Controller Access Control +System)` server doesn’t remove its configuration settings (the server’s IP +address and shared secret). +``` + +```{cfgcmd} set system login tacacs server \<address\> timeout \<timeout\> + +Configure the duration, in seconds, that the VyOS router waits for a +response from the {abbr}`TACACS+ (Terminal Access Controller Access +Control System)` server after sending an authentication request. + +If the server does not respond within this timeframe, the VyOS router tries +to connect to another configured server or falls back to local authentication. +``` + +```{cfgcmd} set system login tacacs source-address \<address\> + +**Configure the source IP address the router uses for** +{abbr}`TACACS+ (Terminal Access Controller Access Control System)` +**authentication requests.** + +A consistent source IP address is recommended as {abbr}`TACACS+ (Terminal +Access Controller Access Control System)` servers typically accept requests +only from known, trusted IP addresses. + +If not explicitly defined, the router uses the current egress interface address, +which may change (e.g., due to a link outage), causing authentication failures. +``` + +```{cfgcmd} set system login tacacs vrf \<name\> + +Configure the router to send all {abbr}`TACACS+ (Terminal Access Controller +Access Control System)` authentication requests via a specific VRF. + +By default, {abbr}`TACACS+ (Terminal Access Controller Access Control System)` +authentication requests are sent via the global routing table. +``` + +(login-tacacs-example)= + +### Configuration example + +```none +set system login tacacs server 192.168.0.2 key 'test-vyos' +set system login tacacs server 192.168.0.2 port '49' +set system login tacacs source-address '192.168.0.1' +``` + +If communication with the {abbr}`TACACS+ (Terminal Access Controller Access +Control System)` server fails, the router falls back to local user +authentication. + +## Login banners + +VyOS allows you to configure **pre-login** and **post-login** banners. +Pre-login banners are typically used for system identification, legal disclaimers, or security warnings +displayed before authentication, while post-login banners provide system +information or operational notices to users after login. + +```{cfgcmd} set system login banner pre-login \<message\> + +Configure a message to be shown to users before the ``username`` and ``password`` +prompts appear. +``` + +```{cfgcmd} set system login banner post-login \<message\> + +Configure a message to be shown to users after successful authentication. +``` +:::{note} +Use `\\n` to insert line breaks in multi-line banner messages. +::: + +## Login session limits + +```{cfgcmd} set system login max-login-session \<number\> + +**Configure the maximum number of concurrent login sessions.** +``` +:::{note} +If you limit concurrent login sessions, you must also configure a +session `<timeout>`. This clears inactive sessions and prevents blocking new +login attempts. +::: +```{cfgcmd} set system login timeout \<timeout\> + +**Configure the login session timeout, in seconds.** + +Idle login sessions are terminated after this period. +``` + +## Configuration examples + +Example 1: Multi-key SSH with MFA and source restrictions + +In this configuration, `User1` and `User2` both use the vyos user account, +each with a unique SSH key. `User1` is restricted to authentication from a +single IP address. + +For both users, password-based logins require {abbr}`OTP (One-time password)` +-based {abbr}`MFA (Multi-factor Authentication)`. + +```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 +``` + +Example 2: Containerized {abbr}`TACACS+ (Terminal Access Controller Access Control System)` +deployment with redundancy. + +In this configuration, the VyOS router hosts its own authentication +infrastructure using two containerized {abbr}`TACACS+ (Terminal Access +Controller Access Control System)` servers (`tacacs1` and `tacacs2`) on a +private network for redundancy. + +System logins are authenticated against credentials stored within these internal +containers rather than the router's local user database. + +First, download the image in operational mode: + +```none +add container image lfkeitel/tacacs_plus:latest +``` + +Next, configure the containers in configuration mode: + +```none +set container network tac-test prefix '100.64.0.0/24' + +set container name tacacs1 image 'lfkeitel/tacacs_plus:latest' +set container name tacacs1 network tac-test address '100.64.0.11' + +set container name tacacs2 image 'lfkeitel/tacacs_plus:latest' +set container name tacacs2 network tac-test address '100.64.0.12' + +set system login tacacs server 100.64.0.11 key 'tac_plus_key' +set system login tacacs server 100.64.0.12 key 'tac_plus_key' + +commit +``` + +You can now log in via SSH or console using `admin/admin` credentials supplied +by the container image. diff --git a/docs/configuration/system/name-server.md b/docs/configuration/system/name-server.md new file mode 100644 index 00000000..9090ba5f --- /dev/null +++ b/docs/configuration/system/name-server.md @@ -0,0 +1,65 @@ +(system-dns)= + +# System DNS + +:::{warning} +If you are configuring a VRF for management purposes, there is +currently no way to force system DNS traffic via a specific VRF. +::: + +This section describes configuring DNS on the system, namely: + +> - DNS name servers +> - Domain search order + +## DNS name servers + +```{cfgcmd} set system name-server \<address\> + +Use this command to specify a DNS server for the system to be used +for DNS lookups. More than one DNS server can be added, configuring +one at a time. Both IPv4 and IPv6 addresses are supported. +``` + + +### Example + +In this example, some *OpenNIC* servers are used, two IPv4 addresses +and two IPv6 addresses: + +```none +set system name-server 176.9.37.132 +set system name-server 195.10.195.195 +set system name-server 2a01:4f8:161:3441::1 +set system name-server 2a00:f826:8:2::195 +``` + + +## Domain search order + +In order for the system to use and complete unqualified host names, a +list can be defined which will be used for domain searches. + +```{cfgcmd} set system domain-search \<domain\> + +Use this command to define domains, one at a time, so that the system +uses them to complete unqualified host names. Maximum: 6 entries. +``` + +:::{note} +Domain names can include letters, numbers, hyphens and periods +with a maximum length of 253 characters. +::: + +(name-server-domain-search-order-example)= + +### Example + +The system is configured to attempt domain completion in the following +order: vyos.io (first), vyos.net (second) and vyos.network (last): + +```none +set system domain-search vyos.io +set system domain-search vyos.net +set system domain-search vyos.network +``` diff --git a/docs/configuration/system/option.md b/docs/configuration/system/option.md new file mode 100644 index 00000000..ed1c3461 --- /dev/null +++ b/docs/configuration/system/option.md @@ -0,0 +1,190 @@ +(system-option)= + +# Option + +This chapter describe the possibilities of advanced system behavior. + +## General + +```{cfgcmd} set system option ctrl-alt-delete \<ignore | reboot | poweroff\> + +Action which will be run once the ctrl-alt-del keystroke is received. +``` + +```{cfgcmd} set system option reboot-on-panic + +Automatically reboot system on kernel panic after 60 seconds. +``` + +```{cfgcmd} set system option reboot-on-upgrade-failure \<timeout\> + +Automatically reboot after `timeout` minutes into the previous running +image, that was used to perform the image upgrade. + +Reboot `timeout` is configurable in minutes. This gives the user the change +to log into the system and perform some analysis before automatic rebooting. + +Automatic reboot can be cancelled after login using: {opcmd}`reboot cancel` +``` + +```{cfgcmd} set system option startup-beep + +Play an audible beep to the system speaker when system is ready. +``` + +```{cfgcmd} set system option root-partition-auto-resize + +Enables the root partition auto-extension and resizes to the maximum +available space on system boot. +``` + + +### Kernel + +```{cfgcmd} set system option kernel disable-mitigations + +Disable all optional CPU mitigations. This improves system performance, +but it may also expose users to several CPU vulnerabilities. + +This will add the following option to the Kernel commandline: +* ``mitigations=off`` + +:::{note} +Setting will only become active with the next reboot! +::: +``` + +```{cfgcmd} set system option kernel disable-power-saving + +This will add the following two options to the Kernel commandline: +* ``intel_idle.max_cstate=0`` Disable intel_idle and fall back on acpi_idle +* ``processor.max_cstate=1`` Limit processor to maximum C-state 1 + +:::{note} +Setting will only become active with the next reboot! +::: +``` + +```{cfgcmd} set system option kernel amd-pstate-driver \<mode\> + +Enables and configures p-state driver for modern AMD Ryzen and Epyc CPUs. + +The available modes are: +* ``active`` This is the low-level firmware control mode based on the profile +set and the system governor has no effect. +* ``passive`` The driver allows the system governor to manage CPU frequency +while providing available performance states. +* ``guided`` The driver allows to set desired performance levels and the firmware +selects a performance level in this range and fitting to the current workload. + +This will add the following two options to the Kernel commandline: +* ``initcall_blacklist=acpi_cpufreq_init`` Disable default ACPI CPU frequency scale +* ``amd_pstate={mode}`` Sets the p-state mode + +:::{note} +Setting will only become active with the next reboot! +::: + +:::{seealso} +<https://docs.kernel.org/admin-guide/pm/amd-pstate.html> +::: +``` + +```{cfgcmd} set system option kernel quiet + +Suppress most kernel messages during boot. This is useful for systems with +embedded serial console interfaces to speed up the boot process. +``` + + +## HTTP client + +```{cfgcmd} set system option http-client source-address \<address\> + +Several commands utilize cURL to initiate transfers. Configure the local +source IPv4/IPv6 address used for all cURL operations. +``` + +```{cfgcmd} set system option http-client source-interface \<interface\> + +Several commands utilize curl to initiate transfers. Configure the local +source interface used for all CURL operations. +``` + +:::{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 + +When starting a VyOS live system (the installation CD) the configured keyboard +layout defaults to US. As this might not suite everyone's use case you can adjust +the used keyboard layout on the system console. + +```{cfgcmd} set system option keyboard-layout \<us | fr | de | fi | no | dk\> + +Change system keyboard layout to given language. + +Defaults to ``us``. + +:::{note} +Changing the keymap only has an effect on the system console, using +SSH or Serial remote access to the device is not affected as the keyboard +layout here corresponds to your access system. +::: +``` + +(system-options-performance)= + +## Performance + +As more and more routers run on Hypervisors, especially with a {abbr}`NOS +(Network Operating System)` as VyOS, it makes fewer and fewer sense to use +static resource bindings like `smp-affinity` as present in VyOS 1.2 and +earlier to pin certain interrupt handlers to specific CPUs. + +We now utilize `tuned` for dynamic resource balancing based on profiles. + +:::{seealso} +<https://access.redhat.com/sites/default/files/attachments/201501-perf-brief-low-latency-tuning-rhel7-v2.1.pdf> +::: + +```{cfgcmd} set system option performance \< throughput | latency \> + +Configure one of the predefined system performance profiles. + +* ``throughput``: A server profile focused on improving network throughput. + This profile favors performance over power savings by setting + ``intel_pstate`` and ``max_perf_pct=100`` and increasing kernel network + buffer sizes. + + It enables transparent huge pages, and uses cpupower to set the performance + cpufreq governor. It also sets ``kernel.sched_min_granularity_ns`` to 10 us, + ``kernel.sched_wakeup_granularity_ns`` to 15 uss, and ``vm.dirty_ratio`` to + 40%. + +* ``latency``: A server profile focused on lowering network latency. + This profile favors performance over power savings by setting + ``intel_pstate`` and ``min_perf_pct=100``. + + It disables transparent huge pages, and automatic NUMA balancing. It also + uses cpupower to set the performance cpufreq governor, and requests a + cpu_dma_latency value of 1. It also sets busy_read and busy_poll times to + 50 us, and tcp_fastopen to 3. +```
\ No newline at end of file diff --git a/docs/configuration/system/proxy.md b/docs/configuration/system/proxy.md new file mode 100644 index 00000000..3b12634b --- /dev/null +++ b/docs/configuration/system/proxy.md @@ -0,0 +1,27 @@ +(system-proxy)= + +# System Proxy + +Some IT environments require the use of a proxy to connect to the Internet. +Without this configuration VyOS updates could not be installed directly by +using the {opcmd}`add system image` command ({ref}`update_vyos`). + +```{cfgcmd} set system proxy url \<url\> + +Set proxy for all connections initiated by VyOS, including HTTP, HTTPS, and +FTP (anonymous ftp). +``` +```{cfgcmd} set system proxy port \<port\> + +Configure proxy port if it does not listen to the default port 80. +``` +```{cfgcmd} set system proxy username \<username\> + +Some proxies require/support the "basic" HTTP authentication scheme as per +{rfc}`7617`, thus a username can be configured. +``` +```{cfgcmd} set system proxy password \<password\> + +Some proxies require/support the "basic" HTTP authentication scheme as per +{rfc}`7617`, thus a password can be configured. +```
\ No newline at end of file diff --git a/docs/configuration/system/acceleration.rst b/docs/configuration/system/rst-acceleration.rst index 63506d6d..63506d6d 100644 --- a/docs/configuration/system/acceleration.rst +++ b/docs/configuration/system/rst-acceleration.rst diff --git a/docs/configuration/system/conntrack.rst b/docs/configuration/system/rst-conntrack.rst index 59209b36..59209b36 100644 --- a/docs/configuration/system/conntrack.rst +++ b/docs/configuration/system/rst-conntrack.rst diff --git a/docs/configuration/system/console.rst b/docs/configuration/system/rst-console.rst index a0e46afb..a0e46afb 100644 --- a/docs/configuration/system/console.rst +++ b/docs/configuration/system/rst-console.rst diff --git a/docs/configuration/system/default-route.rst b/docs/configuration/system/rst-default-route.rst index e102eb9c..e102eb9c 100644 --- a/docs/configuration/system/default-route.rst +++ b/docs/configuration/system/rst-default-route.rst diff --git a/docs/configuration/system/flow-accounting.rst b/docs/configuration/system/rst-flow-accounting.rst index 0664eac7..0664eac7 100644 --- a/docs/configuration/system/flow-accounting.rst +++ b/docs/configuration/system/rst-flow-accounting.rst diff --git a/docs/configuration/system/frr.rst b/docs/configuration/system/rst-frr.rst index 2fa6e3c3..2fa6e3c3 100644 --- a/docs/configuration/system/frr.rst +++ b/docs/configuration/system/rst-frr.rst diff --git a/docs/configuration/system/host-name.rst b/docs/configuration/system/rst-host-name.rst index 4d1567bf..4d1567bf 100644 --- a/docs/configuration/system/host-name.rst +++ b/docs/configuration/system/rst-host-name.rst diff --git a/docs/configuration/system/index.rst b/docs/configuration/system/rst-index.rst index c0113cce..c0113cce 100644 --- a/docs/configuration/system/index.rst +++ b/docs/configuration/system/rst-index.rst diff --git a/docs/configuration/system/ip.rst b/docs/configuration/system/rst-ip.rst index c724faac..c724faac 100644 --- a/docs/configuration/system/ip.rst +++ b/docs/configuration/system/rst-ip.rst diff --git a/docs/configuration/system/ipv6.rst b/docs/configuration/system/rst-ipv6.rst index eaa1d2b8..eaa1d2b8 100644 --- a/docs/configuration/system/ipv6.rst +++ b/docs/configuration/system/rst-ipv6.rst diff --git a/docs/configuration/system/lcd.rst b/docs/configuration/system/rst-lcd.rst index 3fcf01dd..3fcf01dd 100644 --- a/docs/configuration/system/lcd.rst +++ b/docs/configuration/system/rst-lcd.rst diff --git a/docs/configuration/system/login.rst b/docs/configuration/system/rst-login.rst index 1a2c2c5a..1a2c2c5a 100644 --- a/docs/configuration/system/login.rst +++ b/docs/configuration/system/rst-login.rst diff --git a/docs/configuration/system/name-server.rst b/docs/configuration/system/rst-name-server.rst index 5d08dbc5..5d08dbc5 100644 --- a/docs/configuration/system/name-server.rst +++ b/docs/configuration/system/rst-name-server.rst diff --git a/docs/configuration/system/option.rst b/docs/configuration/system/rst-option.rst index a13e38a8..a13e38a8 100644 --- a/docs/configuration/system/option.rst +++ b/docs/configuration/system/rst-option.rst diff --git a/docs/configuration/system/proxy.rst b/docs/configuration/system/rst-proxy.rst index 8e0339a7..8e0339a7 100644 --- a/docs/configuration/system/proxy.rst +++ b/docs/configuration/system/rst-proxy.rst diff --git a/docs/configuration/system/sflow.rst b/docs/configuration/system/rst-sflow.rst index 926d667b..926d667b 100644 --- a/docs/configuration/system/sflow.rst +++ b/docs/configuration/system/rst-sflow.rst diff --git a/docs/configuration/system/sysctl.rst b/docs/configuration/system/rst-sysctl.rst index 1fedb9bd..1fedb9bd 100644 --- a/docs/configuration/system/sysctl.rst +++ b/docs/configuration/system/rst-sysctl.rst diff --git a/docs/configuration/system/syslog.rst b/docs/configuration/system/rst-syslog.rst index c2767c4a..c2767c4a 100644 --- a/docs/configuration/system/syslog.rst +++ b/docs/configuration/system/rst-syslog.rst diff --git a/docs/configuration/system/task-scheduler.rst b/docs/configuration/system/rst-task-scheduler.rst index 4a754ba3..4a754ba3 100644 --- a/docs/configuration/system/task-scheduler.rst +++ b/docs/configuration/system/rst-task-scheduler.rst diff --git a/docs/configuration/system/time-zone.rst b/docs/configuration/system/rst-time-zone.rst index 025c4376..025c4376 100644 --- a/docs/configuration/system/time-zone.rst +++ b/docs/configuration/system/rst-time-zone.rst diff --git a/docs/configuration/system/updates.rst b/docs/configuration/system/rst-updates.rst index 505d9318..505d9318 100644 --- a/docs/configuration/system/updates.rst +++ b/docs/configuration/system/rst-updates.rst diff --git a/docs/configuration/system/watchdog.rst b/docs/configuration/system/rst-watchdog.rst index 9db4a666..9db4a666 100644 --- a/docs/configuration/system/watchdog.rst +++ b/docs/configuration/system/rst-watchdog.rst diff --git a/docs/configuration/system/sflow.md b/docs/configuration/system/sflow.md new file mode 100644 index 00000000..350bbdd8 --- /dev/null +++ b/docs/configuration/system/sflow.md @@ -0,0 +1,66 @@ +# sFlow + +VyOS supports sFlow accounting for both IPv4 and IPv6 traffic. The system acts as a flow exporter, and you are free to use it with any compatible collector. + +sFlow is a technology that enables monitoring of network traffic by sending sampled packets to a collector device. + +The sFlow accounting based on hsflowd <https://sflow.net/> + +## Configuration + +```{cfgcmd} set system sflow agent-address \<address\> + +Configure sFlow agent IPv4 or IPv6 address +``` +```{cfgcmd} set system sflow agent-interface \<interface\> + +Configure agent IP address associated with this interface. +``` +```{cfgcmd} set system sflow drop-monitor-limit \<limit\> + + Dropped packets reported on DROPMON Netlink channel by Linux kernel are exported via the standard sFlow v5 extension for reporting dropped packets +``` + + +```{cfgcmd} set system sflow interface \<interface\> + +Configure and enable collection of flow information for the interface identified by \<interface\>. + +You can configure multiple interfaces which would participate in sflow accounting. +``` +```{cfgcmd} set system sflow polling \<sec\> + + Configure schedule counter-polling in seconds (default: 30) +``` + + +```{cfgcmd} set system sflow sampling-rate \<rate\> + +Use this command to configure the sampling rate for sFlow accounting (default: 1000) +``` + + +```{cfgcmd} set system sflow server \<address\> port \<port\> + +Configure address of sFlow collector. sFlow server at \<address\> can be both listening on an IPv4 or IPv6 address. +``` + + +```{cfgcmd} set system sflow enable-egress + +Use this command to if you need to sample also egress traffic +``` + +## Example + +```none +set system sflow agent-address '192.0.2.14' +set system sflow agent-interface 'eth0' +set system sflow drop-monitor-limit '50' +set system sflow interface 'eth0' +set system sflow interface 'eth1' +set system sflow polling '30' +set system sflow sampling-rate '1000' +set system sflow server 192.0.2.1 port '6343' +set system sflow server 203.0.113.23 port '6343' +``` diff --git a/docs/configuration/system/sysctl.md b/docs/configuration/system/sysctl.md new file mode 100644 index 00000000..90434fb2 --- /dev/null +++ b/docs/configuration/system/sysctl.md @@ -0,0 +1,16 @@ +(sysctl)= + +# Sysctl + +:::{note} +This page is a stub and needs expansion. Contributions +welcome via the [VyOS documentation repository](https://github.com/vyos/vyos-documentation). +::: + +This chapter 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\> +```
\ No newline at end of file diff --git a/docs/configuration/system/syslog.md b/docs/configuration/system/syslog.md new file mode 100644 index 00000000..ae30d272 --- /dev/null +++ b/docs/configuration/system/syslog.md @@ -0,0 +1,450 @@ +(syslog)= + +# Syslog + +## Overview + +By default, VyOS provides a minimal logging configuration with local storage +and log rotation. All errors, including local7 messages, are saved to a local +file. Emergency alerts are sent to the console. + +To change these settings, enter configuration mode. + +## Syslog configuration + +Syslog supports logging to multiple destinations: a local file, a console, or +a remote syslog server over UDP or TCP. + +The syslog configuration is organized into the following categories: + +- Global settings +- Local logging +- Console logging +- Remote logging +- TLS-encrypted remote logging + +### Global settings + +Configure the general behavior of the syslog service. + +```{cfgcmd} set system syslog marker interval \<number\> + +**Configure the interval, in seconds, for sending syslog mark messages.** + +Syslog mark messages confirm the logging service is operational. + +Default: 1200 seconds. +``` + +```{cfgcmd} set system syslog marker disable + +Disable sending syslog mark messages. +``` + +```{cfgcmd} set system syslog preserve-fqdn + +**Configure how the logging device's hostname appears in log messages sent +to a remote syslog server.** + +If configured, the device includes its {abbr}`FQDN (Fully Qualified Domain +Name)` in log messages, even if the syslog server is in the same domain. +``` + + +### Local logging + +Configure which log messages to save to a local log file. + +```{cfgcmd} set system syslog local \<filename\> facility \<keyword\> level \<keyword\> + +**Configure syslog to save log messages for a specific facility and +severity level to \`\`/var/log/messages\`\`.** + +Refer to the tables below for valid facility and severity options. +``` + +(syslog-console)= + +### Console logging + +Configure which log messages to send to `/dev/console`. + +```{cfgcmd} set system syslog console facility \<keyword\> level \<keyword\> + +**Configure syslog to send log messages for a specific facility and severity +level to the device's console.** + +Refer to the tables below for valid facility and severity options. +``` + +(syslog-remote)= + +### Remote logging + +Configure **remote logging** to send log messages to a remote syslog server. + +Remote logging does not affect either **local** or **console logging** and +runs in parallel with them. Remote logging supports sending log messages +to multiple hosts. + +```{cfgcmd} set system syslog remote \<address\> facility \<keyword\> level \<keyword\> + +**Configure log transmission to the remote syslog server for a specific +facility and severity level.** + +The server’s address can be specified using either a {abbr}`FQDN (Fully +Qualified Domain Name)` or an IP address. + +Refer to the tables below for valid facility and severity options. +``` + +```{cfgcmd} set system syslog remote \<address\> protocol \<udp | tcp\> + +**Configure the protocol for log transmission.** + +The protocol can be either UDP or TCP. By default, log messages are sent +over UDP. +``` + +```{cfgcmd} set system syslog remote \<address\> port \<port\> + +**Configure the port for log transmission.** + +By default, the standard port 514 is used. +``` + +```{cfgcmd} set system syslog remote \<address\> format include-timezone + +**Configure log transmission in the RFC 5424 format.** + +The RFC 5424 format includes the timezone in the timestamp. For example: + +:::{code-block} none +<34>1 2003-10-11T22:14:15.003-07:00 mymachine.example.com su - ID47 - BOM’su root’ failed for lonvick on /dev/pts/8. +::: + +By default, log messages are sent in the RFC 3164 format. For example: + +:::{code-block} none +<34>Oct 11 22:14:15 mymachine su: ‘su root’ failed for lonvick on /dev/pts/8 +::: +``` + +```{cfgcmd} set system syslog remote \<address\> format octet-counted + +**Enable octet-counted framing for log transmission.** + +When enabled, multi-line log messages are sent without splitting. Ensure +the remote server supports octet-counted framing to avoid parsing errors. + +Octet-counted framing is not available for the UDP protocol. +``` + +```{cfgcmd} set system syslog remote \<address\> vrf \<name\> + +Configure the {abbr}`VRF (Virtual Routing and Forwarding)` instance +for log transmission. +``` + +```{cfgcmd} set system syslog remote \<address\> source-address \<address\> + +Configure the source IP address (IPv4 or IPv6) for log transmission. +``` + + +#### {abbr}`TLS (Transport Layer Security)`-encrypted remote logging + +VyOS supports {abbr}`TLS (Transport Layer Security)`-encrypted remote logging +over TCP to ensure secure transmission of syslog data to remote syslog servers. + +**Prerequisites**: Before configuring {abbr}`TLS (Transport Layer +Security)`-encrypted remote logging, ensure you have: +- A valid remote syslog server address. +- Valid {abbr}`CA (Certificate Authority)` and client certificates uploaded + to the local {abbr}`PKI (Public Key Infrastructure)` storage. +- The **remote syslog transport protocol** is set to **TCP**: + + ```none + set system syslog remote <address> protocol tcp + ``` + +:::{note} +{abbr}`TLS (Transport Layer Security)`-encrypted remote logging is +**not supported** over **UDP**. +::: +```{cfgcmd} set system syslog remote \<address\> tls + +Enable TLS-encrypted remote logging. + +``` + +```{cfgcmd} set system syslog remote \<address\> tls ca-certificate \<ca_name\> + +**Configure the** {abbr}`CA (Certificate Authority)` **certificate.** + +The syslog client uses the {abbr}`CA (Certificate Authority)` certificate to +verify the identity of the remote syslog server. + +The {abbr}`CA (Certificate Authority)` certificate is required for **all** +authentication modes except ``anon``. + +``` + +```{cfgcmd} set system syslog remote \<address\> tls certificate \<cert_name\> + +**Configure the client certificate.** + +The remote syslog server uses the client certificate to verify the identity +of the syslog client. + +The client certificate is required if the remote syslog server enforces +client certificate verification. + +``` + +````{cfgcmd} set system syslog remote \<address\> tls auth-mode \<anon | fingerprint | certvalid | name\> + +**Configure the authentication mode.** + +The authentication mode defines how the syslog client verifies the syslog +server's identity. + +The following authentication modes are available: + +```{eval-rst} +* ``anon`` **(default)**: Allows encrypted connections without verifying the syslog + server's identity. This mode is **not recommended**, as it is vulnerable to + :abbr:`MITM (Man-in-the-Middle)` attacks. +* ``fingerprint``: Verifies the server’s certificate fingerprint against the + value preconfigured with: + + .. code-block:: none + + set system syslog remote <address> tls permitted-peer <peer> + +* ``certvalid``: Verifies the server certificate is signed by a trusted + :abbr:`CA (Certificate Authority)`, skipping :abbr:`CN (Common Name)` check. +* ``name``: Verifies that: + + * The server’s certificate is signed by a trusted :abbr:`CA (Certificate + Authority)`. + * The :abbr:`CN (Common Name)` in the certificate matches the value + preconfigured with: + + .. code-block:: none + + set system syslog remote <address> tls permitted-peer <peer> + + This is a **recommended** secure mode for production environments. +``` + +```` + +```{cfgcmd} set system syslog remote \<address\> tls permitted-peer \<peer\> + +**Configure the peer certificate identifiers.** + +The certificate identifier format depends on the authentication mode: +* ``fingerprint``: Enter the expected certificate fingerprints (SHA-1 or +SHA-256). +* ``name``: Enter the expected certificate {abbr}`CNs (Common Names)`. + +For ``anon`` and ``certvalid`` authentication modes, certificate identifiers +are not required. + +``` + +#### Examples: + +```none +# Example of 'anon' authentication mode +set system syslog remote 10.10.2.3 facility all level debug +set system syslog remote 10.10.2.3 port 6514 +set system syslog remote 10.10.2.3 protocol tcp +set system syslog remote 10.10.2.3 tls auth-mode anon +# or just use 'set system syslog remote 10.10.2.3 tls' + +# Example of 'certvalid' authentication mode +set system syslog remote elk.example.com facility all level debug +set system syslog remote elk.example.com port 6514 +set system syslog remote elk.example.com protocol tcp +set system syslog remote elk.example.com tls ca-certificate my-ca +set system syslog remote elk.example.com tls auth-mode certvalid + +# Example of 'fingerprint' authentication mode +set system syslog remote syslog.example.com facility all level debug +set system syslog remote syslog.example.com port 6514 +set system syslog remote syslog.example.com protocol tcp +set system syslog remote syslog.example.com tls ca-certificate my-ca +set system syslog remote syslog.example.com tls auth-mode fingerprint +set system syslog remote syslog.example.com tls permitted-peers 'SHA1:10:C4:26:...,SHA256:7B:4B:10:...' + +# Example of 'name' authentication mode +set system syslog remote graylog.example.com facility all level debug +set system syslog remote graylog.example.com port 6514 +set system syslog remote graylog.example.com protocol tcp +set system syslog remote graylog.example.com tls ca-certificate my-ca +set system syslog remote graylog.example.com tls certificate syslog-client +set system syslog remote graylog.example.com tls auth-mode name +set system syslog remote graylog.example.com tls permitted-peers 'graylog.example.com' +``` + +#### Security recommendations + +- For secure deployments, always use the `name` authentication mode. It + ensures that the server is validated by a trusted {abbr}`CA (Certificate + Authority)` and that the hostname matches the certificate. +- Use the `anon` authentication mode only in testing environments, as it + doesn't provide server authentication. +- Ensure private keys are generated, stored, and maintained exclusively within + the {doc}`PKI system </configuration/pki/index>`. +(syslog_facilities)= + +## Syslog facilities + +This section lists facilities used by syslog. Most facility names are self- +explanatory. The local0–local7 facilities are used for custom purposes, such as +logging from network nodes and equipment. Facility assignment is flexible and +should be tailored to your company's needs. Consider facilities as categorization +tools, rather than strict directives. + +```{eval-rst} ++----------+----------+----------------------------------------------------+ +| Facility | Keyword | Description | +| code | | | ++==========+==========+====================================================+ +| | all | All facilities | ++----------+----------+----------------------------------------------------+ +| 0 | kern | Kernel messages | ++----------+----------+----------------------------------------------------+ +| 1 | user | User-level messages | ++----------+----------+----------------------------------------------------+ +| 2 | mail | Mail system | ++----------+----------+----------------------------------------------------+ +| 3 | daemon | System daemons | ++----------+----------+----------------------------------------------------+ +| 4 | auth | Security/authentication messages | ++----------+----------+----------------------------------------------------+ +| 5 | syslog | Messages generated internally by syslog | ++----------+----------+----------------------------------------------------+ +| 6 | lpr | Line printer subsystem | ++----------+----------+----------------------------------------------------+ +| 7 | news | Network news subsystem | ++----------+----------+----------------------------------------------------+ +| 8 | uucp | UUCP subsystem | ++----------+----------+----------------------------------------------------+ +| 9 | cron | Clock daemon | ++----------+----------+----------------------------------------------------+ +| 10 | security | Security/authentication messages | ++----------+----------+----------------------------------------------------+ +| 11 | ftp | FTP daemon | ++----------+----------+----------------------------------------------------+ +| 12 | ntp | NTP subsystem | ++----------+----------+----------------------------------------------------+ +| 13 | logaudit | Log audit | ++----------+----------+----------------------------------------------------+ +| 14 | logalert | Log alert | ++----------+----------+----------------------------------------------------+ +| 15 | clock | clock daemon (note 2) | ++----------+----------+----------------------------------------------------+ +| 16 | local0 | local use 0 (local0) | ++----------+----------+----------------------------------------------------+ +| 17 | local1 | local use 1 (local1) | ++----------+----------+----------------------------------------------------+ +| 18 | local2 | local use 2 (local2) | ++----------+----------+----------------------------------------------------+ +| 19 | local3 | local use 3 (local3) | ++----------+----------+----------------------------------------------------+ +| 20 | local4 | local use 4 (local4) | ++----------+----------+----------------------------------------------------+ +| 21 | local5 | local use 5 (local5) | ++----------+----------+----------------------------------------------------+ +| 22 | local6 | local use 6 (local6) | ++----------+----------+----------------------------------------------------+ +| 23 | local7 | local use 7 (local7) | ++----------+----------+----------------------------------------------------+ +``` + +(syslog_severity_level)= + +## Severity levels + +```{eval-rst} ++-------+---------------+---------+-------------------------------------------+ +| Value | Severity | Keyword | Description | ++=======+===============+=========+===========================================+ +| | | all | Log everything. | ++-------+---------------+---------+-------------------------------------------+ +| 0 | Emergency | emerg | System is unusable - a panic condition. | ++-------+---------------+---------+-------------------------------------------+ +| 1 | Alert | alert | Action must be taken immediately - A | +| | | | condition that should be corrected | +| | | | immediately, such as a corrupted system | +| | | | database. | ++-------+---------------+---------+-------------------------------------------+ +| 2 | Critical | crit | Critical conditions - e.g., hard drive | +| | | | errors. | ++-------+---------------+---------+-------------------------------------------+ +| 3 | Error | err | Error conditions. | ++-------+---------------+---------+-------------------------------------------+ +| 4 | Warning | warning | Warning conditions. | ++-------+---------------+---------+-------------------------------------------+ +| 5 | Notice | notice | Normal but significant conditions - | +| | | | conditions that are not error conditions, | +| | | | but that may require special handling. | ++-------+---------------+---------+-------------------------------------------+ +| 6 | Informational | info | Informational messages. | ++-------+---------------+---------+-------------------------------------------+ +| 7 | Debug | debug | Debug-level messages - Messages that | +| | | | contain information normally of use only | +| | | | when debugging a program. | ++-------+---------------+---------+-------------------------------------------+ +``` + +## Display logs + +```{opcmd} show log [all | authorization | cluster | conntrack-sync | ...] + +**Display logs for a specific category on the console.** + +Use tab completion to view a list of available categories. + +If no category is specified, all logs are shown. + +``` + +````{opcmd} show log image \<name\> [all | authorization | directory | file \<file name\> | tail \<lines\>] + +**Display logs for a specific image on the console.** + +Available log categories: + +```{eval-rst} +.. list-table:: + :widths: 25 75 + :header-rows: 0 + + * - all + - Displays the contents of system log files of the specified image. + * - authorization + - Displays authorization attempts of the specified image. + * - directory + - Displays user-defined log files of the specified image. + * - file <file name> + - Displays the contents of a specified user-defined log file of the specified + image. + * - tail + - Displays last lines of the system log of the specified image. + * - <lines> + - Number of lines to be displayed, default 10. +``` + +```` + +If no category is specified, the contents of the main syslog file are +displayed. + +:::{hint} +Use `show log | strip-private` to hide private data +when displaying your logs. +::: diff --git a/docs/configuration/system/task-scheduler.md b/docs/configuration/system/task-scheduler.md new file mode 100644 index 00000000..94ca9f4d --- /dev/null +++ b/docs/configuration/system/task-scheduler.md @@ -0,0 +1,45 @@ +(task-scheduler)= + +# Task Scheduler + +The task scheduler allows you to execute tasks on a given schedule. It makes +use of UNIX [cron]. + +:::{note} +All scripts executed this way are executed as root user - this may +be dangerous. Together with {ref}`command-scripting` this can be used for +automating (re-)configuration. +::: + +```{cfgcmd} set system task-scheduler task \<task\> interval \<interval\> + +Specify the time interval when `<task>` should be executed. The interval +is specified as number with one of the following suffixes: +* ``none`` - Execution interval in minutes +* ``m`` - Execution interval in minutes +* ``h`` - Execution interval in hours +* ``d`` - Execution interval in days + +:::{note} +If suffix is omitted, minutes are implied. +::: +``` + +```{cfgcmd} set system task-scheduler task \<task\> crontab-spec \<spec\> + +Set execution time in common cron time format. A cron `<spec>` of +``30 */6 * * *`` would execute the `<task>` at minute 30 past every 6th hour. +``` + +```{cfgcmd} set system task-scheduler task \<task\> executable path \<path\> + +Specify absolute `<path>` to script which will be run when `<task>` is +executed. +``` + +```{cfgcmd} set system task-scheduler task \<task\> executable arguments \<args\> + +Arguments which will be passed to the executable. +``` + +[cron]: https://en.wikipedia.org/wiki/Cron diff --git a/docs/configuration/system/time-zone.md b/docs/configuration/system/time-zone.md new file mode 100644 index 00000000..2279a773 --- /dev/null +++ b/docs/configuration/system/time-zone.md @@ -0,0 +1,17 @@ +(timezone)= + +# Time Zone + +Time Zone setting is very important as e.g all your logfile entries will be +based on the configured zone. Without proper time zone configuration it will +be very difficult to compare logfiles from different systems. + +```{cfgcmd} set system time-zone \<timezone\> + +Specify the systems \<timezone\> as the Region/Location that best defines +your location. For example, specifying US/Pacific sets the time zone to US +Pacific time. + +Command completion can be used to list available time zones. The adjustment +for daylight time will take place automatically based on the time of year. +```
\ No newline at end of file diff --git a/docs/configuration/system/updates.md b/docs/configuration/system/updates.md new file mode 100644 index 00000000..c82d37be --- /dev/null +++ b/docs/configuration/system/updates.md @@ -0,0 +1,36 @@ +# Updates + +VyOS supports online checking for updates + +## Configuration + +```{cfgcmd} set system update-check auto-check + +Configure auto-checking for new images +``` + +```{cfgcmd} set system update-check url \<url\> + +Configure a URL that contains information about images. +``` + + +## Example + +```none +set system update-check auto-check +set system update-check url 'https://raw.githubusercontent.com/vyos/vyos-rolling-nightly-builds/main/version.json' +``` + +Check: + +```none +vyos@r4:~$ show system updates +Current version: 1.5-rolling-202312220023 + +Update available: 1.5-rolling-202312250024 +Update URL: https://github.com/vyos/vyos-rolling-nightly-builds/releases/download/1.5-rolling-202312250024/1.5-rolling-202312250024-amd64.iso +vyos@r4:~$ + +vyos@r4:~$ add system image latest +``` diff --git a/docs/configuration/system/watchdog.md b/docs/configuration/system/watchdog.md new file mode 100644 index 00000000..700051a6 --- /dev/null +++ b/docs/configuration/system/watchdog.md @@ -0,0 +1,212 @@ +(system-watchdog)= + +# Watchdog + +VyOS supports hardware watchdog timers to automatically reboot the system if +it becomes unresponsive. This is particularly useful for remote or embedded +systems where physical access is limited. + +A watchdog timer is a hardware or software mechanism that automatically resets +the system if the operating system stops responding within a configured timeout +period. The system will periodically notify the watchdog that it is still +running. If the watchdog is not notified within the timeout period, the watchdog +will reset the system. + +## Configuration + +The watchdog feature is configured under the `system watchdog` configuration +tree. The presence of the `system watchdog` node enables the watchdog feature. + +```{cfgcmd} set system watchdog + +Enable watchdog support. + +The watchdog is enabled only when a watchdog device is available as +``/dev/watchdog0``. + +:::{note} +If multiple watchdog devices are present, only the first watchdog +device is supported (VyOS uses ``/dev/watchdog0`` only). +::: +If ``/dev/watchdog0`` does not exist and no module is configured, commit will +fail. If a module is configured but ``/dev/watchdog0`` still cannot be +created, VyOS will emit a warning and will not enable the systemd watchdog. +``` + +```{cfgcmd} set system watchdog module \<module-name\> + +Specify the kernel watchdog driver module to load for ``/dev/watchdog0``. + +The configured module must be a watchdog driver module, not an arbitrary +kernel module. + +**In most cases, this option is not required** as the kernel will +automatically load the appropriate watchdog driver for your system. Use this +option if the kernel fails to load the required driver, or when you want to +use the software watchdog (``softdog``). + +Common modules include: +* ``softdog`` - Software watchdog timer (available on all systems) +* ``iTCO_wdt`` - Intel TCO watchdog timer +* ``sp5100_tco`` - AMD SP5100 TCO watchdog timer +* ``i6300esb`` - Intel 6300ESB watchdog timer +* ``ipmi_watchdog`` - IPMI watchdog timer + +:::{warning} +``softdog`` is not a hardware watchdog. It is implemented using +kernel timers and therefore depends on the Linux kernel continuing to run. +In some fault conditions (for example, a kernel hang), ``softdog`` may not +be able to trigger a reset. + +Prefer a hardware watchdog driver whenever possible, as hardware watchdogs +can operate independently of the operating system. +::: + +If no module is specified, VyOS will use an existing ``/dev/watchdog0`` +device if available. + +:::{note} +If a module is specified but a different driver is actually bound +to ``watchdog0``, VyOS will emit a warning during commit. +::: +Example: + +:::{code-block} none +set system watchdog module softdog +::: +``` + +```{cfgcmd} set system watchdog timeout \<seconds\> +:defaultvalue: + +Set the watchdog timeout for normal runtime operation in seconds. + +Valid range: 1-65535 seconds + +:::{note} +Some watchdog drivers expose minimum and maximum supported runtime +timeouts via sysfs. When available, VyOS validates ``timeout`` against +those driver limits during commit. +::: + +This is the interval during which the system must respond to the watchdog. +If the system does not respond within this time, the watchdog will trigger +a reboot. + +Example: + +:::{code-block} none +set system watchdog timeout 30 +::: +``` + +```{cfgcmd} set system watchdog shutdown-timeout \<seconds\> +:defaultvalue: + +Set the watchdog timeout during system shutdown in seconds. + +Valid range: 60-65535 seconds + +This extended timeout allows the system to complete a graceful shutdown +without triggering the watchdog. + +:::{warning} +Setting this value too low (below 120 seconds) may cause +unclean shutdowns, as the system may not have enough time to properly +stop all services and flush disk buffers. The recommended minimum value +is 120 seconds. +::: +Example: + +:::{code-block} none +set system watchdog shutdown-timeout 180 +::: +``` + +```{cfgcmd} set system watchdog reboot-timeout \<seconds\> +:defaultvalue: + +Set the watchdog timeout during system reboot in seconds. + +Valid range: 60-65535 seconds + +This extended timeout allows the system to complete the reboot process +without triggering the watchdog during the transition. + +:::{warning} +Setting this value too low (below 120 seconds) may cause +unclean reboots, as the system may not have enough time to properly +stop all services before restarting. The recommended minimum value +is 120 seconds. +::: +Example: + +:::{code-block} none +set system watchdog reboot-timeout 180 +::: +``` + + +## Examples + +### Basic Configuration with Software Watchdog + +This example configures a basic software watchdog with default timeouts: + +```none +set system watchdog module softdog +``` + +This will: +- Enable the watchdog feature +- Load the `softdog` kernel module +- Use a 10-second runtime timeout (default) +- Use 120-second shutdown and reboot timeouts (default) + +### Advanced Configuration + +This example shows a more customized configuration suitable for a production +system: + +```none +set system watchdog module iTCO_wdt +set system watchdog timeout 30 +set system watchdog shutdown-timeout 300 +set system watchdog reboot-timeout 300 +``` + +This configuration: + +- Enables the watchdog feature +- Loads the Intel TCO hardware watchdog module +- Sets a 30-second runtime timeout +- Allows 5 minutes for shutdown and reboot operations + +## Best Practices + +- **Start with conservative timeouts**: Use longer timeouts initially and + reduce them as you gain confidence in system stability. +- **Test before deployment**: Verify the watchdog works as expected in a + non-production environment before deploying to production systems. +- **Choose appropriate modules**: Use hardware watchdog modules (like + `iTCO_wdt`) when available, as they are more reliable than software + watchdogs. +- **Consider shutdown time**: Set `shutdown-timeout` and `reboot-timeout` + values high enough to allow for normal shutdown procedures, especially on + systems with many services or slow storage. +- **Monitor watchdog events**: Check system logs after any unexpected reboots + to determine if the watchdog triggered the reboot. +- **Remote systems**: For systems without physical console access, use + conservative timeout values to avoid false-positive reboots during high + load conditions. + +:::{note} +The watchdog configuration takes effect immediately after commit, +but systemd must be reloaded. This happens automatically during commit. +::: + +:::{warning} +Incorrect watchdog configuration on remote systems can result +in unexpected reboots. Always test watchdog settings in a controlled +environment before deploying to production systems. +::: diff --git a/docs/configuration/trafficpolicy/index.md b/docs/configuration/trafficpolicy/index.md new file mode 100644 index 00000000..f1dccc92 --- /dev/null +++ b/docs/configuration/trafficpolicy/index.md @@ -0,0 +1,1299 @@ +(qos)= + +# Traffic Policy + +## QoS + +The generic name of Quality of Service or Traffic Control involves +things like shaping traffic, scheduling or dropping packets, which +are the kind of things you may want to play with when you have, for +instance, a bandwidth bottleneck in a link and you want to somehow +prioritize some type of traffic over another. + +[tc] is a powerful tool for Traffic Control found at the Linux kernel. +However, its configuration is often considered a cumbersome task. +Fortunately, VyOS eases the job through its CLI, while using `tc` as +backend. + +### How to make it work + +In order to have VyOS Traffic Control working you need to follow 2 +steps: + +> 1. **Create a traffic policy**. +> 2. **Apply the traffic policy to an interface ingress or egress**. + +But before learning to configure your policy, we will warn you +about the different units you can use and also show you what *classes* +are and how they work, as some policies may require you to configure +them. + +### Units + +When configuring your traffic policy, you will have to set data rate +values, watch out the units you are managing, it is easy to get confused +with the different prefixes and suffixes you can use. VyOS will always +show you the different units you can use. + +#### Prefixes + +They can be **decimal** prefixes. + +```{eval-rst} + .. code-block:: none + + kbit (10^3) kilobit per second + mbit (10^6) megabit per second + gbit (10^9) gigabit per second + tbit (10^12) terabit per second + + kbps (8*10^3) kilobyte per second + mbps (8*10^6) megabyte per second + gbps (8*10^9) gigabyte per second + tbps (8*10^12) terabyte per second +``` + +Or **binary** prefixes. + +```{eval-rst} + .. code-block:: none + + kibit (2^10 = 1024) kibibit per second + mibit (2^20 = 1024^2) mebibit per second + gibit (2^30 = 1024^3) gibibit per second + tbit (2^40 = 1024^4) tebibit per second + + kibps (1024*8) kibibyte (KiB) per second + mibps (1024^2*8) mebibyte (MiB) per second + gibps (1024^3*8) gibibyte (GiB) per second + tibps (1024^4*8) tebibyte (TiB) per second +``` + + +#### Suffixes + +A *bit* is written as **bit**, + +```{eval-rst} + .. code-block:: none + + kbit (kilobits per second) + mbit (megabits per second) + gbit (gigabits per second) + tbit (terabits per second) +``` + +while a *byte* is written as a single **b**. + +```{eval-rst} + .. code-block:: none + + kbps (kilobytes per second) + mbps (megabytes per second) + gbps (gigabytes per second) +``` + +(classes)= + +### Classes + +In the {ref}`creating_a_traffic_policy` section you will see that +some of the policies use *classes*. Those policies let you distribute +traffic into different classes according to different parameters you can +choose. So, a class is just a specific type of traffic you select. + +The ultimate goal of classifying traffic is to give each class a +different treatment. + +#### Matching traffic + +In order to define which traffic goes into which class, you define +filters (that is, the matching criteria). Packets go through these matching +rules (as in the rules of a firewall) and, if a packet matches the filter, it +is assigned to that class. + +In VyOS, a class is identified by a number you can choose when +configuring it. + +:::{note} +The meaning of the Class ID is not the same for every type of +policy. Normally policies just need a meaningless number to identify +a class (Class ID), but that does not apply to every policy. +The number of a class in a Priority Queue it does not only +identify it, it also defines its priority. +::: +```none +set qos policy <policy> <policy-name> class <class-ID> match <class-matching-rule-name> +``` + +In the command above, we set the type of policy we are going to +work with and the name we choose for it; a class (so that we can +differentiate some traffic) and an identifiable number for that class; +then we configure a matching rule (or filter) and a name for it. + +A class can have multiple match filters: + +```none +set qos policy shaper MY-SHAPER class 30 match HTTP +set qos policy shaper MY-SHAPER class 30 match HTTPs +``` + +A match filter can contain multiple criteria and will match traffic if +all those criteria are true. + +For example: + +```none +set qos policy shaper MY-SHAPER class 30 match HTTP ip protocol tcp +set qos policy shaper MY-SHAPER class 30 match HTTP ip source port 80 +``` + +This will match TCP traffic with source port 80. + +There are many parameters you will be able to use in order to match the +traffic you want for a class: + +> - **Ethernet (protocol, destination address or source address)** +> - **Interface name** +> - **IPv4 (DSCP value, maximum packet length, protocol, source address,** +> **destination address, source port, destination port or TCP flags)** +> - **IPv6 (DSCP value, maximum payload length, protocol, source address,** +> **destination address, source port, destination port or TCP flags)** +> - **Firewall mark** +> - **VLAN ID** + +When configuring your filter, you can use the `Tab` key to see the many +different parameters you can configure. + +```none +vyos@vyos# set qos policy shaper MY-SHAPER class 30 match MY-FIRST-FILTER +Possible completions: + description Description + > ether Ethernet header match + interface Interface to use + > ip Match IP protocol header + > ipv6 Match IPV6 protocol header + mark Match on mark applied by firewall + vif Virtual Local Area Network (VLAN) ID for this match +``` + +As shown in the example above, one of the possibilities to match packets +is based on marks done by the firewall, +[that can give you a great deal of flexibility]. + +You can also write a description for a filter: + +```none +set qos policy shaper MY-SHAPER class 30 match MY-FIRST-FILTER description "My filter description" +``` +:::{note} +An IPv4 TCP filter will only match packets with an IPv4 header +length of 20 bytes (which is the majority of IPv4 packets anyway). +::: + +:::{note} +IPv6 TCP filters will only match IPv6 packets with no header +extension, see <https://en.wikipedia.org/wiki/IPv6_packet#Extension_headers> +::: + +#### Traffic Match Group + +In some case where we need to have an organization of our matching selection, +in order to be more flexible and organize with our filter definition. We can +apply traffic match groups, allowing us to create distinct filter groups within +our policy and define various parameters for each group: + +```none +set qos traffic-match-group <group_name> match <match_name> +Possible completions: + description Description + > ip Match IP protocol header + > ipv6 Match IPv6 protocol header + mark Match on mark applied by firewall + vif Virtual Local Area Network (VLAN) ID for this match +``` + +inherit matches from another group + +```none +set qos traffic-match-group <group_name> match-group <match_group_name> +``` + +A match group can contain multiple criteria and inherit them in the same policy. + +For example: + +```none +set qos traffic-match-group Mission-Critical match AF31 ip dscp 'AF31' +set qos traffic-match-group Mission-Critical match AF32 ip dscp 'AF42' +set qos traffic-match-group Mission-Critical match CS3 ip dscp 'CS3' +set qos traffic-match-group Streaming-Video match AF11 ip dscp 'AF11' +set qos traffic-match-group Streaming-Video match AF41 ip dscp 'AF41' +set qos traffic-match-group Streaming-Video match AF43 ip dscp 'AF43' +set qos policy shaper VyOS-HTB class 10 bandwidth '30%' +set qos policy shaper VyOS-HTB class 10 description 'Multimedia' +set qos policy shaper VyOS-HTB class 10 match CS4 ip dscp 'CS4' +set qos policy shaper VyOS-HTB class 10 match-group 'Streaming-Video' +set qos policy shaper VyOS-HTB class 10 priority '1' +set qos policy shaper VyOS-HTB class 10 queue-type 'fair-queue' +set qos policy shaper VyOS-HTB class 20 description 'MC' +set qos policy shaper VyOS-HTB class 20 match-group 'Mission-Critical' +set qos policy shaper VyOS-HTB class 20 priority '2' +set qos policy shaper VyOS-HTB class 20 queue-type 'fair-queue' +set qos policy shaper VyOS-HTB default bandwidth '20%' +set qos policy shaper VyOS-HTB default queue-type 'fq-codel' +``` + +In this example, we can observe that different DSCP criteria are defined based +on our QoS configuration within the same policy group. + +#### Default + +Often you will also have to configure your *default* traffic in the same +way you do with a class. *Default* can be considered a class as it +behaves like that. It contains any traffic that did not match any +of the defined classes, so it is like an open class, a class without +matching filters. + +#### Class treatment + +Once a class has a filter configured, you will also have to define what +you want to do with the traffic of that class, what specific +Traffic-Control treatment you want to give it. You will have different +possibilities depending on the Traffic Policy you are configuring. + +```none +vyos@vyos# set qos policy shaper MY-SHAPER class 30 +Possible completions: + bandwidth Available bandwidth for this policy (default: auto) + burst Burst size for this class (default: 15k) + ceiling Bandwidth limit for this class + codel-quantum + Deficit in the fair queuing algorithm (default 1514) + description Description + flows Number of flows into which the incoming packets are classified(default 1024) + interval Interval used to measure the delay (default 100) ++> match Class matching rule name + priority Priority for rule evaluation + queue-limit Maximum queue size + queue-type Queue type for default traffic (default: fq-codel) + set-dscp Change the Differentiated Services (DiffServ) field in the IP header + target Acceptable minimum standing/persistent queue delay (default: 5) +``` + +For instance, with {code}`set qos policy shaper MY-SHAPER +class 30 set-dscp EF` you would be modifying the DSCP field value of packets in +that class to Expedite Forwarding. + +> DSCP values as per {rfc}`2474` and {rfc}`4595`: +> +> | Binary value | Configured value | Drop rate | Description | +> | ------------ | ---------------- | --------- | ---------------------------- | +> | 101110 | 46 | - | Expedited forwarding (EF) | +> | 000000 | 0 | - | Best effort traffic, default | +> | 001010 | 10 | Low | Assured Forwarding(AF) 11 | +> | 001100 | 12 | Medium | Assured Forwarding(AF) 12 | +> | 001110 | 14 | High | Assured Forwarding(AF) 13 | +> | 010010 | 18 | Low | Assured Forwarding(AF) 21 | +> | 010100 | 20 | Medium | Assured Forwarding(AF) 22 | +> | 010110 | 22 | High | Assured Forwarding(AF) 23 | +> | 011010 | 26 | Low | Assured Forwarding(AF) 31 | +> | 011100 | 28 | Medium | Assured Forwarding(AF) 32 | +> | 011110 | 30 | High | Assured Forwarding(AF) 33 | +> | 100010 | 34 | Low | Assured Forwarding(AF) 41 | +> | 100100 | 36 | Medium | Assured Forwarding(AF) 42 | +> | 100110 | 38 | High | Assured Forwarding(AF) 43 | + +(embed)= + +#### Embedding one policy into another one + +Often we need to embed one policy into another one. It is possible to do +so on classful policies, by attaching a new policy into a class. For +instance, you might want to apply different policies to the different +classes of a Round-Robin policy you have configured. + +A common example is the case of some policies which, in order to be +effective, they need to be applied to an interface that is directly +connected where the bottleneck is. If your router is not +directly connected to the bottleneck, but some hop before it, you can +emulate the bottleneck by embedding your non-shaping policy into a +classful shaping one so that it takes effect. + +You can configure a policy into a class through the `queue-type` +setting. + +```none +set qos policy shaper FQ-SHAPER bandwidth 4gbit +set qos policy shaper FQ-SHAPER default bandwidth 100% +set qos policy shaper FQ-SHAPER default queue-type fq-codel +``` + +As shown in the last command of the example above, the `queue-type` +setting allows these combinations. You will be able to use it +in many policies. + +:::{note} +Some policies already include other embedded policies inside. +That is the case of Shaper: each of its classes use fair-queue +unless you change it. +::: + +(creating_a_traffic_policy)= + +### Creating a traffic policy + +VyOS lets you control traffic in many different ways, here we will cover +every possibility. You can configure as many policies as you want, but +you will only be able to apply one policy per interface and direction +(inbound or outbound). + +Some policies can be combined, you will be able to embed a different +policy that will be applied to a class of the main policy. + +:::{hint} +**If you are looking for a policy for your outbound traffic** +but you don't know which one you need and you don't want to go +through every possible policy shown here, **our bet is that highly +likely you are looking for a** Shaper **policy and you want to** +{ref}`set its queues <embed>` **as FQ-CoDel**. +::: + +#### Drop Tail + +```{eval-rst} +| **Queueing discipline:** PFIFO (Packet First In First Out). +| **Applies to:** Outbound traffic. +``` + +This the simplest queue possible you can apply to your traffic. Traffic +must go through a finite queue before it is actually sent. You must +define how many packets that queue can contain. + +When a packet is to be sent, it will have to go through that queue, so +the packet will be placed at the tail of it. When the packet completely +goes through it, it will be dequeued emptying its place in the queue and +being eventually handed to the NIC to be actually sent out. + +Despite the Drop-Tail policy does not slow down packets, if many packets +are to be sent, they could get dropped when trying to get enqueued at +the tail. This can happen if the queue has still not been able to +release enough packets from its head. + +This is the policy that requires the lowest resources for the same +amount of traffic. But **very likely you do not need it as you cannot +get much from it. Sometimes it is used just to enable logging.** + +```{cfgcmd} set qos policy drop-tail \<policy-name\> queue-limit \<number-of-packets\> + +Use this command to configure a drop-tail policy (PFIFO). Choose a +unique name for this policy and the size of the queue by setting the +number of packets it can contain (maximum 4294967295). + +``` + +#### Fair Queue + +```{eval-rst} +| **Queueing discipline:** SFQ (Stochastic Fairness Queuing). +| **Applies to:** Outbound traffic. +``` + +Fair Queue is a work-conserving scheduler which schedules the +transmission of packets based on flows, that is, it balances traffic +distributing it through different sub-queues in order to ensure +fairness so that each flow is able to send data in turn, preventing any +single one from drowning out the rest. + +```{cfgcmd} set qos policy fair-queue \<policy-name\> + + Use this command to create a Fair-Queue policy and give it a name. + It is based on the Stochastic Fairness Queueing and can be applied to + outbound traffic. + +``` + +In order to separate traffic, Fair Queue uses a classifier based on +source address, destination address and source port. The algorithm +enqueues packets to hash buckets based on those tree parameters. +Each of these buckets should represent a unique flow. Because multiple +flows may get hashed to the same bucket, the hashing algorithm is +perturbed at configurable intervals so that the unfairness lasts only +for a short while. Perturbation may however cause some inadvertent +packet reordering to occur. An advisable value could be 10 seconds. + + +One of the uses of Fair Queue might be the mitigation of Denial of +Service attacks. + +```{cfgcmd} set qos policy fair-queue \<policy-name\> hash-interval \<seconds\> + +Use this command to define a Fair-Queue policy, based on the +Stochastic Fairness Queueing, and set the number of seconds at which +a new queue algorithm perturbation will occur (maximum 4294967295). +``` + +When dequeuing, each hash-bucket with data is queried in a round robin +fashion. You can configure the length of the queue. + +```{cfgcmd} set qos policy fair-queue \<policy-name\> queue-limit \<limit\> + +Use this command to define a Fair-Queue policy, based on the +Stochastic Fairness Queueing, and set the number of maximum packets +allowed to wait in the queue. Any other packet will be dropped. +``` +:::{note} +Fair Queue is a non-shaping (work-conserving) policy, so it +will only be useful if your outgoing interface is really full. If it +is not, VyOS will not own the queue and Fair Queue will have no +effect. If there is bandwidth available on the physical link, you can +embed Fair-Queue into a classful shaping policy to make sure it owns +the queue. +::: + + +(fq-codel)= + + +#### FQ-CoDel + + +```{eval-rst} +| **Queueing discipline:** Fair/Flow Queue CoDel. +| **Applies to:** Outbound Traffic. +``` + + +The FQ-CoDel policy distributes the traffic into 1024 FIFO queues and +tries to provide good service between all of them. It also tries to keep +the length of all the queues short. + + +FQ-CoDel fights bufferbloat and reduces latency without the need of +complex configurations. It has become the new default Queueing +Discipline for the interfaces of some GNU/Linux distributions. + + +It uses a stochastic model to classify incoming packets into +different flows and is used to provide a fair share of the bandwidth to +all the flows using the queue. Each flow is managed by the CoDel +queuing discipline. Reordering within a flow is avoided since Codel +internally uses a FIFO queue. + + +FQ-CoDel is based on a modified Deficit Round Robin (DRR) queue +scheduler with the CoDel Active Queue Management (AQM) algorithm +operating on each queue. + + +:::{note} +FQ-Codel is a non-shaping (work-conserving) policy, so it +will only be useful if your outgoing interface is really full. If it +is not, VyOS will not own the queue and FQ-Codel will have no +effect. If there is bandwidth available on the physical link, you can +embed FQ-Codel into a classful shaping policy to make sure it owns +the queue. If you are not sure if you need to embed your FQ-CoDel +policy into a Shaper, do it. +::: + + +FQ-CoDel is tuned to run ok with its default parameters at 10Gbit +speeds. It might work ok too at other speeds without configuring +anything, but here we will explain some cases when you might want to +tune its parameters. + + +When running it at 1Gbit and lower, you may want to reduce the +`queue-limit` to 1000 packets or less. In rates like 10Mbit, you may +want to set it to 600 packets. + + +If you are using FQ-CoDel embedded into Shaper and you have large rates +(100Mbit and above), you may consider increasing `quantum` to 8000 or +higher so that the scheduler saves CPU. + + +On low rates (below 40Mbit) you may want to tune `quantum` down to +something like 300 bytes. + + +At very low rates (below 3Mbit), besides tuning `quantum` (300 keeps +being ok) you may also want to increase `target` to something like 15ms +and increase `interval` to something around 150 ms. + +```{cfgcmd} set qos policy fq-codel \<policy name\> codel-quantum \<bytes\> + +Use this command to configure an fq-codel policy, set its name and +the maximum number of bytes (default: 1514) to be dequeued from a +queue at once. +``` + +```{cfgcmd} set qos policy fq-codel \<policy name\> flows \<number-of-flows\> + +Use this command to configure an fq-codel policy, set its name and +the number of sub-queues (default: 1024) into which packets are +classified. +``` + +```{cfgcmd} set qos policy fq-codel \<policy name\> interval \<milliseconds\> + +Use this command to configure an fq-codel policy, set its name and +the time period used by the control loop of CoDel to detect when a +persistent queue is developing, ensuring that the measured minimum +delay does not become too stale (default: 100ms). +``` + +```{cfgcmd} set qos policy fq-codel \<policy-name\> queue-limit \<number-of-packets\> + +Use this command to configure an fq-codel policy, set its name, and +define a hard limit on the real queue size. When this limit is +reached, new packets are dropped (default: 10240 packets). +``` + +```{cfgcmd} set qos policy fq-codel \<policy-name\> target \<milliseconds\> + +Use this command to configure an fq-codel policy, set its name, and +define the acceptable minimum standing/persistent queue delay. This +minimum delay is identified by tracking the local minimum queue delay +that packets experience (default: 5ms). +``` + +##### Example + +A simple example of an FQ-CoDel policy working inside a Shaper one. + +```none +set qos policy shaper FQ-CODEL-SHAPER bandwidth 2gbit +set qos policy shaper FQ-CODEL-SHAPER default bandwidth 100% +set qos policy shaper FQ-CODEL-SHAPER default queue-type fq-codel +``` + +#### Limiter + +```{eval-rst} +| **Queueing discipline:** Ingress policer. +| **Applies to:** Inbound traffic. +``` + +Limiter is one of those policies that uses classes (Ingress qdisc is +actually a classless policy but filters do work in it). + +The limiter performs basic ingress policing of traffic flows. Multiple +classes of traffic can be defined and traffic limits can be applied to +each class. Although the policer uses a token bucket mechanism +internally, it does not have the capability to delay a packet as a +shaping mechanism does. Traffic exceeding the defined bandwidth limits +is directly dropped. A maximum allowed burst can be configured too. + +You can configure classes (up to 4090) with different settings and a +default policy which will be applied to any traffic not matching any of +the configured classes. + +:::{note} +In the case you want to apply some kind of **shaping** to your +**inbound** traffic, check the ingress-shaping section. +::: +```{cfgcmd} set qos policy limiter \<policy-name\> class \<class ID\> match \<match-name\> description \<description\> + +Use this command to configure an Ingress Policer, defining its name, +a class identifier (1-4090), a class matching rule name and its +description. + +``` + +Once the matching rules are set for a class, you can start configuring +how you want matching traffic to behave. + +```{cfgcmd} set qos policy limiter \<policy-name\> class \<class-ID\> bandwidth \<rate\> + +Use this command to configure an Ingress Policer, defining its name, +a class identifier (1-4090) and the maximum allowed bandwidth for +this class. + +``` + +```{cfgcmd} set qos policy limiter \<policy-name\> class \<class-ID\> burst \<burst-size\> + +Use this command to configure an Ingress Policer, defining its name, +a class identifier (1-4090) and the burst size in bytes for this +class (default: 15). + +``` + +```{cfgcmd} set qos policy limiter \<policy-name\> default bandwidth \<rate\> + +Use this command to configure an Ingress Policer, defining its name +and the maximum allowed bandwidth for its default policy. + +``` + +```{cfgcmd} set qos policy limiter \<policy-name\> default burst \<burst-size\> + +Use this command to configure an Ingress Policer, defining its name +and the burst size in bytes (default: 15) for its default policy. + +``` + +```{cfgcmd} set qos policy limiter \<policy-name\> class \<class ID\> priority \<value\> + +Use this command to configure an Ingress Policer, defining its name, +a class identifier (1-4090), and the priority (0-20, default 20) in +which the rule is evaluated (the lower the number, the higher the +priority). + +``` + +#### Network Emulator + +```{eval-rst} +| **Queueing discipline:** netem (Network Emulator) + TBF (Token Bucket Filter). +| **Applies to:** Outbound traffic. +``` + +VyOS Network Emulator policy emulates the conditions you can suffer in a +real network. You will be able to configure things like rate, burst, +delay, packet loss, packet corruption or packet reordering. + +This could be helpful if you want to test how an application behaves +under certain network conditions. + +```{cfgcmd} set qos policy network-emulator \<policy-name\> bandwidth \<rate\> + + Use this command to configure the maximum rate at which traffic will + be shaped in a Network Emulator policy. Define the name of the policy + and the rate. + +``` + +```{cfgcmd} set qos policy network-emulator \<policy-name\> burst \<burst-size\> + +Use this command to configure the burst size of the traffic in a +Network Emulator policy. Define the name of the Network Emulator +policy and its traffic burst size (it will be configured through the +Token Bucket Filter qdisc). Default:15kb. It will only take effect if +you have configured its bandwidth too. +``` + +```{cfgcmd} set qos policy network-emulator \<policy-name\> delay \<delay\> + +Use this command to configure a Network Emulator policy defining its +name and the fixed amount of time you want to add to all packet going +out of the interface. The latency will be added through the +Token Bucket Filter qdisc. It will only take effect if you have +configured its bandwidth too. You can use secs, ms and us. Default: +50ms. +``` + +```{cfgcmd} set qos policy network-emulator \<policy-name\> corruption \<percent\> + +Use this command to emulate noise in a Network Emulator policy. Set +the policy name and the percentage of corrupted packets you want. A +random error will be introduced in a random position for the chosen +percent of packets. +``` + +```{cfgcmd} set qos policy network-emulator \<policy-name\> loss \<percent\> + +Use this command to emulate packet-loss conditions in a Network +Emulator policy. Set the policy name and the percentage of loss +packets your traffic will suffer. +``` + +```{cfgcmd} set traffic-policy network-emulator \<policy-name\> reordering \<percent\> + +Use this command to emulate packet-reordering conditions in a Network +Emulator policy. Set the policy name and the percentage of reordered +packets your traffic will suffer. +``` + +```{cfgcmd} set traffic-policy network-emulator \<policy-name\> queue-limit \<limit\> + +Use this command to define the length of the queue of your Network +Emulator policy. Set the policy name and the maximum number of +packets (1-4294967295) the queue may hold queued at a time. +``` + +#### Priority Queue + +```{eval-rst} +| **Queueing discipline:** PRIO. +| **Applies to:** Outbound traffic. +``` + +The Priority Queue is a classful scheduling policy. It does not delay +packets (Priority Queue is not a shaping policy), it simply dequeues +packets according to their priority. + +:::{note} +Priority Queue, as other non-shaping policies, is only useful +if your outgoing interface is really full. If it is not, VyOS will +not own the queue and Priority Queue will have no effect. If there is +bandwidth available on the physical link, you can embed Priority +Queue into a classful shaping policy to make sure it owns the queue. +In that case packets can be prioritized based on DSCP. +::: + +Up to seven queues -defined as classes with different priorities- can +be configured. Packets are placed into queues based on associated match +criteria. Packets are transmitted from the queues in priority order. If +classes with a higher priority are being filled with packets +continuously, packets from lower priority classes will only be +transmitted after traffic volume from higher priority classes decreases. + +:::{note} +In Priority Queue we do not define classes with a meaningless +class ID number but with a class priority number (1-7). The lower the +number, the higher the priority. +::: + +As with other policies, you can define different type of matching rules +for your classes: + +```none +vyos@vyos# set qos policy priority-queue MY-PRIO class 3 match MY-MATCH-RULE +Possible completions: + description Description + > ether Ethernet header match + interface Interface to use + > ip Match IP protocol header + > ipv6 Match IPV6 protocol header + mark Match on mark applied by firewall + vif Virtual Local Area Network (VLAN) ID for this match +``` + +As with other policies, you can embed other policies into the classes +(and default) of your Priority Queue policy through the `queue-type` +setting: + +```none +vyos@vyos# set qos policy priority-queue MY-PRIO class 3 queue-type +Possible completions: + drop-tail First-In-First-Out (FIFO) (default) + fq-codel Fair Queue Codel + fair-queue Stochastic Fair Queue (SFQ) + priority Priority queueing + random-detect + Random Early Detection (RED) +``` + +```{cfgcmd} set qos policy priority-queue \<policy-name\> class \<class-ID\> queue-limit \<limit\> + +Use this command to configure a Priority Queue policy, set its name, +set a class with a priority from 1 to 7 and define a hard limit on +the real queue size. When this limit is reached, new packets are +dropped. + +``` + +(random-detect)= + +#### Random-Detect + +```{eval-rst} +| **Queueing discipline:** Generalized Random Early Drop. +| **Applies to:** Outbound traffic. +``` + +A simple Random Early Detection (RED) policy would start randomly +dropping packets from a queue before it reaches its queue limit thus +avoiding congestion. That is good for TCP connections as the gradual +dropping of packets acts as a signal for the sender to decrease its +transmission rate. + +In contrast to simple RED, VyOS' Random-Detect uses a Generalized Random +Early Detect policy that provides different virtual queues based on the +IP Precedence value so that some virtual queues can drop more packets +than others. + +This is achieved by using the first three bits of the ToS (Type of +Service) field to categorize data streams and, in accordance with the +defined precedence parameters, a decision is made. + +IP precedence as defined in {rfc}`791`: +> | Precedence | Priority | +> | ---------- | -------------------- | +> | 7 | Network Control | +> | 6 | Internetwork Control | +> | 5 | CRITIC/ECP | +> | 4 | Flash Override | +> | 3 | Flash | +> | 2 | Immediate | +> | 1 | Priority | +> | 0 | Routine | +Random-Detect could be useful for heavy traffic. One use of this +algorithm might be to prevent a backbone overload. But only for TCP +(because dropped packets could be retransmitted), not for UDP. + +```{cfgcmd} set qos policy random-detect \<policy-name\> bandwidth \<bandwidth\> + + Use this command to configure a Random-Detect policy, set its name + and set the available bandwidth for this policy. It is used for + calculating the average queue size after some idle time. It should be + set to the bandwidth of your interface. Random Detect is not a + shaping policy, this command will not shape. + +``` + +```{cfgcmd} set qos policy random-detect \<policy-name\> precedence \<IP-precedence-value\> average-packet \<bytes\> + +Use this command to configure a Random-Detect policy and set its +name, then state the IP Precedence for the virtual queue you are +configuring and what the size of its average-packet should be +(in bytes, default: 1024). +``` +:::{note} +When configuring a Random-Detect policy: **the higher the +precedence number, the higher the priority**. +::: +```{cfgcmd} set qos policy random-detect \<policy-name\> precedence \<IP-precedence-value\> mark-probability \<value\> + +Use this command to configure a Random-Detect policy and set its +name, then state the IP Precedence for the virtual queue you are +configuring and what its mark (drop) probability will be. Set the +probability by giving the N value of the fraction 1/N (default: 10). +``` + +```{cfgcmd} set qos policy random-detect \<policy-name\> precedence \<IP-precedence-value\> maximum-threshold \<packets\> + +Use this command to configure a Random-Detect policy and set its +name, then state the IP Precedence for the virtual queue you are +configuring and what its maximum threshold for random detection will +be (from 0 to 4096 packets, default: 18). At this size, the marking +(drop) probability is maximal. + +``` + +```{cfgcmd} set qos policy random-detect \<policy-name\> precedence \<IP-precedence-value\> minimum-threshold \<packets\> + +Use this command to configure a Random-Detect policy and set its +name, then state the IP Precedence for the virtual queue you are +configuring and what its minimum threshold for random detection will +be (from 0 to 4096 packets). If this value is exceeded, packets +start being eligible for being dropped. +``` + +The default values for the minimum-threshold depend on IP precedence: +> | Precedence | default min-threshold | +> | ---------- | --------------------- | +> | 7 | 16 | +> | 6 | 15 | +> | 5 | 14 | +> | 4 | 13 | +> | 3 | 12 | +> | 2 | 11 | +> | 1 | 10 | +> | 0 | 9 | + +```{cfgcmd} set qos policy random-detect \<policy-name\> precedence \<IP-precedence-value\> queue-limit \<packets\> + +Use this command to configure a Random-Detect policy and set its +name, then name the IP Precedence for the virtual queue you are +configuring and what the maximum size of its queue will be (from 1 to +1-4294967295 packets). Packets are dropped when the current queue +length reaches this value. + +``` + +If the average queue size is lower than the **min-threshold**, an +arriving packet will be placed in the queue. + +In the case the average queue size is between **min-threshold** and +**max-threshold**, then an arriving packet would be either dropped or +placed in the queue, it will depend on the defined **mark-probability**. + +If the current queue size is larger than **queue-limit**, +then packets will be dropped. The average queue size depends on its +former average size and its current one. + +If **max-threshold** is set but **min-threshold is not, then +\*\*min-threshold** is scaled to 50% of **max-threshold**. + +In principle, values must be +{code}`min-threshold` < {code}`max-threshold` < {code}`queue-limit`. + +#### Rate Control + +```{eval-rst} +| **Queueing discipline:** Token Bucket Filter. +| **Applies to:** Outbound traffic. +``` + +Rate-Control is a classless policy that limits the packet flow to a set +rate. It is a pure shaper, it does not schedule traffic. Traffic is +filtered based on the expenditure of tokens. Tokens roughly correspond +to bytes. + +Short bursts can be allowed to exceed the limit. On creation, the +Rate-Control traffic is stocked with tokens which correspond to the +amount of traffic that can be burst in one go. Tokens arrive at a steady +rate, until the bucket is full. + +```{cfgcmd} set qos policy rate-control \<policy-name\> bandwidth \<rate\> + + Use this command to configure a Rate-Control policy, set its name + and the rate limit you want to have. + +``` + +```{cfgcmd} set qos policy rate-control \<policy-name\> burst \<burst-size\> + +Use this command to configure a Rate-Control policy, set its name +and the size of the bucket in bytes which will be available for +burst. +``` + +As a reference: for 10mbit/s on Intel, you might need at least 10kbyte +buffer if you want to reach your configured rate. + +A very small buffer will soon start dropping packets. + +```{cfgcmd} set qos policy rate-control \<policy-name\> latency + +Use this command to configure a Rate-Control policy, set its name +and the maximum amount of time a packet can be queued (default: 50 +ms). + +``` + +Rate-Control is a CPU-friendly policy. You might consider using it when +you just simply want to slow traffic down. +(drr)= + +#### Round Robin + +**Queueing discipline:** + Deficit Round Robin. +**Applies to:** + Outbound traffic. + +The round-robin policy is a classful scheduler that divides traffic in +different classes you can configure (up to 4096). You can embed a +new policy into each of those classes (default included). + +Each class is assigned a deficit counter (the number of bytes that a +flow is allowed to transmit when it is its turn) initialized to quantum. +Quantum is a parameter you configure which acts like a credit of fix +bytes the counter receives on each round. Then the Round-Robin policy +starts moving its Round Robin pointer through the queues. If the deficit +counter is greater than the packet's size at the head of the queue, this +packet will be sent and the value of the counter will be decremented by +the packet size. Then, the size of the next packet will be compared to +the counter value again, repeating the process. Once the queue is empty +or the value of the counter is insufficient, the Round-Robin pointer +will move to the next queue. If the queue is empty, the value of the +deficit counter is reset to 0. + +At every round, the deficit counter adds the quantum so that even large +packets will have their opportunity to be dequeued. + +```{cfgcmd} set qos policy round-robin \<policy name\> class \<class-ID\> quantum \<packets\> + +Use this command to configure a Round-Robin policy, set its name, set +a class ID, and the quantum for that class. The deficit counter will +add that value each round. + +``` + +```{cfgcmd} set qos policy round-robin \<policy name\> class <class ID> queue-limit \<packets\> + +Use this command to configure a Round-Robin policy, set its name, set +a class ID, and the queue size in packets. +``` + +As with other policies, Round-Robin can embed another policy into a +class through the `queue-type` setting. + +```none +vyos@vyos# set qos policy round-robin DRR class 10 queue-type +Possible completions: + drop-tail First-In-First-Out (FIFO) (default) + fq-codel Fair Queue Codel + fair-queue Stochastic Fair Queue (SFQ) + priority Priority queueing based + random-detect + Random Early Detection (RED) +``` + +(shaper)= + + +#### Shaper + + +```{eval-rst} +| **Queueing discipline:** Hierarchical Token Bucket. +| **Applies to:** Outbound traffic. +``` + + +The Shaper policy does not guarantee a low delay, but it does guarantee +bandwidth to different traffic classes and also lets you decide how to +allocate more traffic once the guarantees are met. + + +Each class can have a guaranteed part of the total bandwidth defined for +the whole policy, so all those shares together should not be higher +than the policy's whole bandwidth. + + +If guaranteed traffic for a class is met and there is room for more +traffic, the ceiling parameter can be used to set how much more +bandwidth could be used. If guaranteed traffic is met and there are +several classes willing to use their ceilings, the priority parameter +will establish the order in which that additional traffic will be +allocated. Priority can be any number from 0 to 7. The lower the number, +the higher the priority. + +```{cfgcmd} set qos policy shaper \<policy-name\> bandwidth \<rate\> + +Use this command to configure a Shaper policy, set its name +and the maximum bandwidth for all combined traffic. +``` + +```{cfgcmd} set qos policy shaper \<policy-name\> class \<class-ID\> bandwidth \<rate\> + +Use this command to configure a Shaper policy, set its name, define +a class and set the guaranteed traffic you want to allocate to that +class. + +``` + +```{cfgcmd} set qos policy shaper \<policy-name\> class \<class-ID\> burst \<bytes\> + +Use this command to configure a Shaper policy, set its name, define +a class and set the size of the token bucket in bytes, which will +be available to be sent at ceiling speed (default: 15Kb). +``` + +```{cfgcmd} set qos policy shaper \<policy-name\> class \<class-ID\> ceiling \<bandwidth\> + +Use this command to configure a Shaper policy, set its name, define +a class and set the maximum speed possible for this class. The +default ceiling value is the bandwidth value. +``` + +```{cfgcmd} set qos policy shaper \<policy-name\> class \<class-ID\> priority \<0-7\> + +Use this command to configure a Shaper policy, set its name, define +a class and set the priority for usage of available bandwidth once +guarantees have been met. The lower the priority number, the higher +the priority. The default priority value is 0, the highest priority. +``` + +As with other policies, Shaper can embed other policies into its +classes through the `queue-type` setting and then configure their +parameters. + +```none +vyos@vyos# set qos policy shaper HTB class 10 queue-type +Possible completions: + fq-codel Fair Queue Codel (default) + fair-queue Stochastic Fair Queue (SFQ) + drop-tail First-In-First-Out (FIFO) + priority Priority queueing + random-detect + Random Early Detection (RED) +``` + +```none +vyos@vyos# set qos policy shaper HTB class 10 +Possible completions: + bandwidth Available bandwidth for this policy (default: auto) + burst Burst size for this class (default: 15k) + ceiling Bandwidth limit for this class + codel-quantum + Deficit in the fair queuing algorithm (default 1514) + description Description + flows Number of flows into which the incoming packets are classified (default 1024) + interval Interval used to measure the delay (default 100) ++> match Class matching rule name + priority Priority for rule evaluation + queue-limit Maximum queue size (packets) + queue-type Queue type for default traffic (default: fq-codel) + set-dscp Change the Differentiated Services (DiffServ) field in the IP header + target Acceptable minimum standing/persistent queue delay (default: 5) +``` +:::{note} +If you configure a class for **VoIP traffic**, don't give it any +*ceiling*, otherwise new VoIP calls could start when the link is +available and get suddenly dropped when other classes start using +their assigned *bandwidth* share. +::: + +(traffic-policy-shaper-example)= + +##### Example + +A simple example of Shaper using priorities. + +```none +set qos policy shaper MY-HTB bandwidth '50mbit' +set qos policy shaper MY-HTB class 10 bandwidth '20%' +set qos policy shaper MY-HTB class 10 match DSCP ip dscp 'EF' +set qos policy shaper MY-HTB class 10 queue-type 'fq-codel' +set qos policy shaper MY-HTB class 20 bandwidth '10%' +set qos policy shaper MY-HTB class 20 ceiling '50%' +set qos policy shaper MY-HTB class 20 match PORT666 ip destination port '666' +set qos policy shaper MY-HTB class 20 priority '3' +set qos policy shaper MY-HTB class 20 queue-type 'fair-queue' +set qos policy shaper MY-HTB class 30 bandwidth '10%' +set qos policy shaper MY-HTB class 30 ceiling '50%' +set qos policy shaper MY-HTB class 30 match ADDRESS30 ip source address '192.168.30.0/24' +set qos policy shaper MY-HTB class 30 priority '5' +set qos policy shaper MY-HTB class 30 queue-type 'fair-queue' +set qos policy shaper MY-HTB default bandwidth '10%' +set qos policy shaper MY-HTB default ceiling '100%' +set qos policy shaper MY-HTB default priority '7' +set qos policy shaper MY-HTB default queue-type 'fair-queue' +``` + +(cake)= + +#### CAKE + +```{eval-rst} +| **Queueing discipline:** Deficit mode. +| **Applies to:** Outbound traffic. +``` + +Common Applications Kept Enhanced (CAKE) is a comprehensive queue management +system, implemented as a queue discipline (qdisc) for the Linux kernel. It is +designed to replace and improve upon the complex hierarchy of simple qdiscs +presently required to effectively tackle the bufferbloat problem at the network +edge. + +```{cfgcmd} set qos policy cake \<text\> bandwidth \<value\> + + Set the shaper bandwidth, either as an explicit bitrate or a percentage + of the interface bandwidth. + +``` + +```{cfgcmd} set qos policy cake \<text\> description + +Set a description for the shaper. +``` + +```{cfgcmd} set qos policy cake \<text\> flow-isolation blind + +Disables flow isolation, all traffic passes through a single queue. +``` + +```{cfgcmd} set qos policy cake \<text\> flow-isolation dst-host + +Flows are defined only by destination address. +``` + +```{cfgcmd} set qos policy cake \<text\> flow-isolation dual-dst-host + +Flows are defined by the 5-tuple. Fairness is applied first over destination +addresses, then over individual flows. +``` + +```{cfgcmd} set qos policy cake \<text\> flow-isolation dual-src-host + +Flows are defined by the 5-tuple. Fairness is applied first over source +addresses, then over individual flows. +``` + +```{cfgcmd} set qos policy cake \<text\> flow-isolation flow + +Flows are defined by the entire 5-tuple (source IP address, source port, +destination IP address, destination port, transport protocol). +``` + +```{cfgcmd} set qos policy cake \<text\> flow-isolation host + +Flows are defined by source-destination host pairs. +``` + +```{cfgcmd} set qos policy cake \<text\> flow-isolation nat + +Perform NAT lookup before applying flow-isolation rules. +``` + +```{cfgcmd} set qos policy cake \<text\> flow-isolation src-host + +Flows are defined only by source address. +``` + +```{cfgcmd} set qos policy cake \<text\> flow-isolation triple-isolate + +**(Default)** Flows are defined by the 5-tuple, fairness is applied +over source and destination addresses and also over individual flows. +``` + +```{cfgcmd} set qos policy cake \<text\> rtt + +Defines the round-trip time used for active queue management (AQM) in +milliseconds. The default value is 100. +``` + +### Applying a traffic policy + +Once a traffic-policy is created, you can apply it to an interface: + +```none +set qos interface eth0 egress WAN-OUT +``` + +You can only apply one policy per interface and direction, but you could +reuse a policy on different interfaces and directions: + +```none +set qos interface eth0 ingress WAN-IN +set qos interface eth0 egress WAN-OUT +set qos interface eth1 ingress LAN-IN +set qos interface eth1 egress LAN-OUT +set qos interface eth2 ingress LAN-IN +set qos interface eth2 egress LAN-OUT +set qos interface eth3 ingress TWO-WAY-POLICY +set qos interface eth3 egress TWO-WAY-POLICY +set qos interface eth4 ingress TWO-WAY-POLICY +set qos interface eth4 egress TWO-WAY-POLICY +``` + +(ingress-shaping)= + +### The case of ingress shaping + +**Applies to:** + Inbound traffic. + +For the ingress traffic of an interface, there is only one policy you +can directly apply, a **Limiter** policy. You cannot apply a shaping +policy directly to the ingress traffic of any interface because shaping +only works for outbound traffic. + +This workaround lets you apply a shaping policy to the ingress traffic +by first redirecting it to an in-between virtual interface +([Intermediate Functional Block]). There, in that virtual interface, +you will be able to apply any of the policies that work for outbound +traffic, for instance, a shaping one. + +That is how it is possible to do the so-called "ingress shaping". + +```none +set qos policy shaper MY-INGRESS-SHAPING bandwidth 1000kbit +set qos policy shaper MY-INGRESS-SHAPING default bandwidth 1000kbit +set qos policy shaper MY-INGRESS-SHAPING default queue-type fair-queue + +set qos interface ifb0 egress MY-INGRESS-SHAPING +set interfaces ethernet eth0 redirect ifb0 + +set interfaces input ifb0 +``` + +:::{warning} +Do not configure IFB as the first step. First create everything else +of your traffic-policy, and then you can configure IFB. +Otherwise you might get the `RTNETLINK answer: File exists` error, +which can be solved with `sudo ip link delete ifb0`. +::: + +[common applications kept enhanced]: https://www.bufferbloat.net/projects/codel/wiki/Cake/ +[hfsc]: <https://en.wikipedia.org/wiki/Hierarchical_fair-service_curve> +[intermediate functional block]: https://www.linuxfoundation.org/collaborate/workgroups/networking/ifb +[tc]: <https://en.wikipedia.org/wiki/Tc_(Linux)> +[that can give you a great deal of flexibility]: https://blog.vyos.io/using-the-policy-route-and-packet-marking-for-custom-qos-matches +[token bucket]: <https://en.wikipedia.org/wiki/Token_bucket> diff --git a/docs/configuration/trafficpolicy/index.rst b/docs/configuration/trafficpolicy/rst-index.rst index 13cfb9dc..13cfb9dc 100644 --- a/docs/configuration/trafficpolicy/index.rst +++ b/docs/configuration/trafficpolicy/rst-index.rst diff --git a/docs/configuration/vpn/dmvpn.md b/docs/configuration/vpn/dmvpn.md new file mode 100644 index 00000000..4dc2c85f --- /dev/null +++ b/docs/configuration/vpn/dmvpn.md @@ -0,0 +1,431 @@ +(vpn-dmvpn)= + +# DMVPN + +{abbr}`DMVPN (Dynamic Multipoint Virtual Private Network)` is a dynamic +{abbr}`VPN (Virtual Private Network)` technology originally developed by Cisco. +While their implementation was somewhat proprietary, the underlying +technologies are actually standards based. The three technologies are: + +- {abbr}`NHRP (Next Hop Resolution Protocol)` {rfc}`2332` +- {abbr}`mGRE (Multipoint Generic Routing Encapsulation)` {rfc}`1702` +- {abbr}`IPSec (IP Security)` - too many RFCs to list, but start with + {rfc}`4301` + +NHRP provides the dynamic tunnel endpoint discovery mechanism (endpoint +registration, and endpoint discovery/lookup), mGRE provides the tunnel +encapsulation itself, and the IPSec protocols handle the key exchange, and +crypto mechanism. + +In short, DMVPN provides the capability for creating a dynamic-mesh VPN +network without having to pre-configure (static) all possible tunnel end-point +peers. + +:::{note} +DMVPN only automates the tunnel endpoint discovery and setup. A +complete solution also incorporates the use of a routing protocol. BGP is +particularly well suited for use with DMVPN. +::: + +:::{figure} /_static/images/vpn_dmvpn_topology01.webp +:alt: Baseline DMVPN topology +:scale: 40 % +Baseline DMVPN topology +::: + +## Configuration + +### Tunnel interface configuration + +NHRP never handles routing of prefixes itself. You need to run some real routing +protocol (e.g. BGP) to advertise routes over the tunnels. What nhrpd does it +establishes ‘shortcut routes’ that optimizes the routing protocol to avoid going +through extra nodes in NBMA GRE mesh. + +NHRP does route NHRP domain addresses individually using per-host prefixes. +This is similar to Cisco FlexVPN, but in contrast to opennhrp which uses +a generic subnet route. + +To create NBMA GRE tunnel you might use the following: + +```none +set interfaces tunnel tun100 address '10.0.0.1/32' +set interfaces tunnel tun100 enable-multicast +set interfaces tunnel tun100 encapsulation 'gre' +set interfaces tunnel tun100 ip adjust-mss '1360' +set interfaces tunnel tun100 mtu '1400' +set interfaces tunnel tun100 parameters ip key '42' +set interfaces tunnel tun100 source-interface 'eth0' +``` + +- Please refer to the {ref}`tunnel-interface` documentation for the individual + tunnel related options. + + :::{note} + The IP-address is assigned as host prefix to tunnel interface. + NHRP will automatically create additional host routes pointing to tunnel interface + when a connection with these hosts is established. + ::: + +The tunnel interface subnet prefix should be announced by routing protocol +from the hub nodes (e.g. BGP ‘network’ announce). This allows the routing +protocol to decide which is the closest hub and determine the relay hub on +prefix basis when direct tunnel is not established. + +### NHRP protocol configuration + +```{cfgcmd} set protocols nhrp tunnel \<tunnel\> authentication \<secret\> + +Enables Cisco style authentication on NHRP packets. This embeds the +plaintext password to the outgoing NHRP packets. Maximum length of +the password is 8 characters. +``` + +```{cfgcmd} set protocols nhrp tunnel \<tunnel\> holdtime \<timeout\> + +Holdtime is the number of seconds that have to pass before stopping to +advertise an NHRP NBMA address as valid. It also controls how often NHRP +registration requests are sent. By default registrations are sent every +one third of the holdtime +``` + +```{cfgcmd} set protocols nhrp tunnel \<tunnel\> map tunnel-ip \<tunnel-ip\> nbma \<nbma-ip\> + +* **tunnel-ip** - Tunnel ip address in format **x.x.x.x**. +* **nbma-ip** - NBMA ip address in format **x.x.x.x** or **local** + +Map an IP address of a station to the station’s NBMA address. +``` + +```{cfgcmd} set protocols nhrp tunnel \<tunnel\> mtu \<mtu\> + +Configure NHRP advertised MTU. +``` + +```{cfgcmd} set protocols nhrp tunnel \<tunnel\> multicast \<nbma-ip\> + +* **nbma-ip** - NBMA ip address in format **x.x.x.x** or **dynamic** + +Sends multicast packets to the specified NBMA address. If dynamic is specified +then destination NBMA address (or addresses) are learnt dynamically. +``` + +```{cfgcmd} set protocols nhrp tunnel \<tunnel\> network-id \<network-id\> + +* **network-id** - NHRP network id <1-4294967295> + +Enable NHRP on this interface and set the interface’s network ID. The network ID +is used to allow creating multiple nhrp domains on a router when multiple interfaces +are configured on the router. Interfaces configured with the same ID are part of the +same logical NBMA network. The ID is a local only parameter and is not sent to other +NHRP nodes and so IDs on different nodes do not need to match. When NHRP packets are +received on an interface they are assigned to the local NHRP domain for that interface. +``` + +```{cfgcmd} set protocols nhrp tunnel \<tunnel\> nhs tunnel-ip \<tunnel-ip\> nbma \<nbma-ip\> + +* **tunnel-ip** - Tunnel ip address in format **x.x.x.x** or **dynamic** +* **nbma-ip** - NBMA ip address in format **x.x.x.x** + +Configure the Next Hop Server address and its NBMA address. If dynamic is specified +then Next Hop Server can have dynamic address which maps to its NBMA address. +``` + +```{cfgcmd} set protocols nhrp tunnel \<tunnel\> redirect + +This enable redirect replies on the NHS similar to ICMP redirects except this is +managed by the nhrp protocol. This setting allows spokes to communicate with each +others directly. +``` + +```{cfgcmd} set protocols nhrp tunnel \<tunnel\> registration-no-unique + +Allow the client to not set the unique flag in the NHRP packets. This is useful when +a station has a dynamic IP address that could change over time. +``` + +```{cfgcmd} set protocols nhrp tunnel \<tunnel\> shortcut + +Enable shortcut (spoke-to-spoke) tunnels to allow NHC to talk to each others directly +after establishing a connection without going through the hub. +``` + + +### IPSEC configuration + +- Please refer to the {ref}`ipsec_general` documentation for the individual IPSec + related options. + +:::{note} +NHRP daemon based on FRR nhrpd. It controls IPSEC. That's why 'close-action' +parameter in IKE configuration always is set to 'close' and 'dead-peer-detection action' +always is set to 'clear'. +::: + +```{cfgcmd} set vpn ipsec profile \<profile-name\> authentication mode pre-shared-secret + +Set preshared secret mode authentication +``` + +```{cfgcmd} set vpn ipsec profile \<profile-name\> authentication pre-shared-secret \<secret\> + +Set preshared secret +``` + +```{cfgcmd} set vpn ipsec profile \<profile-name\> bind tunnel \<tunnel name\> + +Bind IPSEC profile to the specific tunnel interface. +``` + +```{cfgcmd} set vpn ipsec profile \<profile-name\> esp-group 'ESP-HUB' + +Map ESP group to IPSEC profile +``` + +```{cfgcmd} set vpn ipsec profile \<profile-name\> ike-group 'IKE-HUB' + +Map IKE group to IPSEC profile +``` + + +## Monitoring + +```{opcmd} show ip nhrp cache + +Forwarding cache information. +``` + +```{opcmd} show ip nhrp nhs + +Next hop server information. +``` + +```{opcmd} show ip nhrp shortcut + +Shortcut information. +``` + + +## Example + +This blueprint uses VyOS as the DMVPN Hub and Cisco IOSv 15.5(3)M and VyOS as +multiple spoke sites. + +:::{figure} /_static/images/blueprint-dmvpn.webp +:align: center +:alt: DMVPN Network Topology Diagram +:width: 70% +DMVPN Network Topology Diagram +::: + +Each node (Hub and Spoke) uses an IP address from the network 10.0.0.0/24. + +The below referenced IP address `192.168.0.2` is used as example address +representing a global unicast address under which the HUB can be contacted by +each and every individual spoke. +(dmvpn-example-configuration)= + +### Configuration + +#### Hub + +##### VyOS-HUB-1 + +```none +set interfaces ethernet eth0 address '192.168.0.2/30' + +set interfaces tunnel tun100 address '10.0.0.100/32' +set interfaces tunnel tun100 enable-multicast +set interfaces tunnel tun100 encapsulation 'gre' +set interfaces tunnel tun100 parameters ip key '42' +set interfaces tunnel tun100 source-interface 'eth0' + +set protocols nhrp tunnel tun100 authentication 'test123' +set protocols nhrp tunnel tun100 holdtime '300' +set protocols nhrp tunnel tun100 multicast 'dynamic' +set protocols nhrp tunnel tun100 network-id '1' +set protocols nhrp tunnel tun100 redirect +set protocols nhrp tunnel tun100 registration-no-unique + +set protocols static route 0.0.0.0/0 next-hop 192.168.0.1 + +set vpn ipsec esp-group ESP-HUB lifetime '1800' +set vpn ipsec esp-group ESP-HUB mode 'transport' +set vpn ipsec esp-group ESP-HUB pfs 'dh-group2' +set vpn ipsec esp-group ESP-HUB proposal 1 encryption 'aes256' +set vpn ipsec esp-group ESP-HUB proposal 1 hash 'sha1' +set vpn ipsec ike-group IKE-HUB key-exchange 'ikev1' +set vpn ipsec ike-group IKE-HUB lifetime '3600' +set vpn ipsec ike-group IKE-HUB proposal 1 dh-group '2' +set vpn ipsec ike-group IKE-HUB proposal 1 encryption 'aes256' +set vpn ipsec ike-group IKE-HUB proposal 1 hash 'sha1' +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' +set vpn ipsec profile NHRPVPN bind tunnel 'tun100' +set vpn ipsec profile NHRPVPN esp-group 'ESP-HUB' +set vpn ipsec profile NHRPVPN ike-group 'IKE-HUB' +``` + +:::{note} +Setting this up on AWS will require a "Custom Protocol Rule" for +protocol number "47" (GRE) Allow Rule in TWO places. Firstly on the VPC +Network ACL, and secondly on the security group network ACL attached to the +EC2 instance. This has been tested as working for the official AMI image on +the AWS Marketplace. (Locate the correct VPC and security group by navigating +through the details pane below your EC2 instance in the AWS console). +::: + +#### Spokes + +> The individual spoke configurations only differ in interface IP addresses. + +##### VyOS-Spoke-1 and VyOS-Spoke-2 + +```none +set interfaces ethernet eth0 address '192.168.1.2/30' + +set interfaces tunnel tun100 address '10.0.0.1/32' +set interfaces tunnel tun100 enable-multicast +set interfaces tunnel tun100 encapsulation 'gre' +set interfaces tunnel tun100 parameters ip key '42' +set interfaces tunnel tun100 source-interface 'eth0' + +set protocols nhrp tunnel tun100 authentication 'test123' +set protocols nhrp tunnel tun100 holdtime '300' +set protocols nhrp tunnel tun100 multicast 'dynamic' +set protocols nhrp tunnel tun100 network-id '1' +set protocols nhrp tunnel tun100 nhs tunnel-ip dynamic nbma '192.168.0.2' +set protocols nhrp tunnel tun100 registration-no-unique +set protocols nhrp tunnel tun100 shortcut + +set protocols static route 0.0.0.0/0 next-hop 192.168.1.1 +set protocols static route 10.0.0.0/24 next-hop 10.0.0.100 + +set vpn ipsec esp-group ESP-HUB lifetime '1800' +set vpn ipsec esp-group ESP-HUB mode 'transport' +set vpn ipsec esp-group ESP-HUB pfs 'dh-group2' +set vpn ipsec esp-group ESP-HUB proposal 1 encryption 'aes256' +set vpn ipsec esp-group ESP-HUB proposal 1 hash 'sha1' +set vpn ipsec ike-group IKE-HUB key-exchange 'ikev1' +set vpn ipsec ike-group IKE-HUB lifetime '3600' +set vpn ipsec ike-group IKE-HUB proposal 1 dh-group '2' +set vpn ipsec ike-group IKE-HUB proposal 1 encryption 'aes256' +set vpn ipsec ike-group IKE-HUB proposal 1 hash 'sha1' +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' +set vpn ipsec profile NHRPVPN bind tunnel 'tun100' +set vpn ipsec profile NHRPVPN esp-group 'ESP-HUB' +set vpn ipsec profile NHRPVPN ike-group 'IKE-HUB' +``` + + +##### Cisco-Spoke-3 + +```none +crypto isakmp policy 10 + encr aes 256 + authentication pre-share + group 2 + lifetime 3600 +crypto isakmp key secret address 0.0.0.0 +! +! +crypto ipsec transform-set DMVPNESP esp-aes 256 esp-sha-hmac + mode transport +! +crypto ipsec profile DMVPNPROFILE + set security-association lifetime seconds 1800 + set transform-set DMVPNESP + set pfs group2 +! +! +! +! +! +! +! +interface Tunnel100 + ip address 10.0.0.3 255.255.255.0 + no ip redirects + ip nhrp authentication test123 + ip nhrp map multicast dynamic + ip nhrp network-id 1 + ip nhrp holdtime 300 + ip nhrp nhs 10.0.0.100 nbma 192.168.0.2 + ip nhrp registration no-unique + ip nhrp redirect +tunnel source GigabitEthernet0/0 + tunnel mode gre multipoint + tunnel key 42 + tunnel protection ipsec profile DMVPNPROFILE +! +interface GigabitEthernet0/0 + ip address 192.168.3.2 255.255.255.252 + duplex auto + speed auto + media-type rj45 +! +ip route 0.0.0.0 0.0.0.0 192.168.3.1 +``` + + +##### Monitoring DMVPN Network + +Let send ICMP packets from VyOS-SPOKE-1 to Cisco-SPOKE-3 + +```none +vyos@vyos:~$ ping 10.0.0.3 +PING 10.0.0.3 (10.0.0.3) 56(84) bytes of data. +64 bytes from 10.0.0.3: icmp_seq=1 ttl=255 time=3.44 ms +64 bytes from 10.0.0.3: icmp_seq=2 ttl=255 time=3.07 ms +^C +--- 10.0.0.3 ping statistics --- +2 packets transmitted, 2 received, 0% packet loss, time 1002ms +rtt min/avg/max/mdev = 3.072/3.257/3.442/0.185 ms +``` + + +##### Monitoring on HUB + +```none +vyos@vyos:~$ show ip nhrp cache +Iface Type Protocol NBMA Claimed NBMA Flags Identity +tun100 dynamic 10.0.0.1 192.168.1.2 192.168.1.2 T 192.168.1.2 +tun100 dynamic 10.0.0.3 192.168.3.2 192.168.3.2 T 192.168.3.2 +tun100 dynamic 10.0.0.2 192.168.2.2 192.168.2.2 T 192.168.2.2 +tun100 local 10.0.0.100 192.168.0.2 192.168.0.2 - + +vyos@vyos:~$ show vpn ipsec sa +Connection State Uptime Bytes In/Out Packets In/Out Remote address Remote ID Proposal +-------------------------- ------- -------- -------------- ---------------- ---------------- ----------- ---------------------------------- +dmvpn-NHRPVPN-tun100-child up 3m46s 230B/270B 2/2 192.168.1.2 192.168.1.2 AES_CBC_256/HMAC_SHA1_96/MODP_1024 +dmvpn-NHRPVPN-tun100-child up 5m48s 460B/540B 4/4 192.168.2.2 192.168.2.2 AES_CBC_256/HMAC_SHA1_96/MODP_1024 +dmvpn-NHRPVPN-tun100-child up 16m26s 1K/1K 13/12 192.168.3.2 192.168.3.2 AES_CBC_256/HMAC_SHA1_96/MODP_1024 +``` + + +##### Monitoring on Spokes + +```none +vyos@vyos:~$ show ip nhrp cache +Iface Type Protocol NBMA Claimed NBMA Flags Identity +tun100 local 10.0.0.1 192.168.1.2 192.168.1.2 - +tun100 dynamic 10.0.0.3 192.168.3.2 192.168.3.2 T 192.168.3.2 +tun100 nhs 10.0.0.100 192.168.0.2 192.168.0.2 T 192.168.0.2 + +vyos@vyos:~$ show ip nhrp nhs +Iface FQDN NBMA Protocol +tun100 192.168.0.2 192.168.0.2 10.0.0.100 + +vyos@vyos:~$ show ip nhrp shortcut +Type Prefix Via Identity +dynamic 10.0.0.3/32 10.0.0.3 192.168.3.2 + +vyos@vyos:~$ show vpn ipsec sa +Connection State Uptime Bytes In/Out Packets In/Out Remote address Remote ID Proposal +-------------------------- ------- -------- -------------- ---------------- ---------------- ----------- ---------------------------------- +dmvpn-NHRPVPN-tun100-child up 6m43s 898B/695B 7/6 192.168.0.2 192.168.0.2 AES_CBC_256/HMAC_SHA1_96/MODP_1024 +dmvpn-NHRPVPN-tun100-child up 49s 215B/187B 2/2 192.168.3.2 192.168.3.2 AES_CBC_256/HMAC_SHA1_96/MODP_1024 +``` diff --git a/docs/configuration/vpn/index.md b/docs/configuration/vpn/index.md new file mode 100644 index 00000000..9b06e5df --- /dev/null +++ b/docs/configuration/vpn/index.md @@ -0,0 +1,14 @@ +# VPN + +```{toctree} +:includehidden: true +:maxdepth: 1 + +ipsec/index +l2tp +openconnect +pptp +rsa-keys +sstp +dmvpn +``` diff --git a/docs/configuration/vpn/ipsec/index.md b/docs/configuration/vpn/ipsec/index.md new file mode 100644 index 00000000..cc40b6f8 --- /dev/null +++ b/docs/configuration/vpn/ipsec/index.md @@ -0,0 +1,11 @@ +# IPsec + +```{toctree} +:includehidden: true +:maxdepth: 1 + +ipsec_general +site2site_ipsec +remoteaccess_ipsec +troubleshooting_ipsec +``` diff --git a/docs/configuration/vpn/ipsec/ipsec_general.md b/docs/configuration/vpn/ipsec/ipsec_general.md new file mode 100644 index 00000000..62fcec8a --- /dev/null +++ b/docs/configuration/vpn/ipsec/ipsec_general.md @@ -0,0 +1,407 @@ +(ipsec_general)= + +# IPsec General Information + +## Information about IPsec + +IPsec is the framework used to secure data. +IPsec accomplishes these goals by providing authentication, +encryption of IP network packets, key exchange, and key management. +VyOS uses Strongswan package to implement IPsec. + +**Authentication Header (AH)** is defined in {rfc}`4302`. It creates +a hash using the IP header and data payload, and prepends it to the +packet. This hash is used to validate that the data has not been +changed during transfer over the network. + +**Encapsulating Security Payload (ESP)** is defined in {rfc}`4303`. +It provides encryption and authentication of the data. + +```{eval-rst} +There are two IPsec modes: + **IPsec Transport Mode**: + In transport mode, an IPSec header (AH or ESP) is inserted + between the IP header and the upper layer protocol header. + + **IPsec Tunnel Mode:** + In tunnel mode, the original IP packet is encapsulated in + another IP datagram, and an IPsec header (AH or ESP) is + inserted between the outer and inner headers. + +.. figure:: /_static/images/ESP_AH.webp + :scale: 80 % + :alt: AH and ESP in Transport Mode and Tunnel Mode +``` + +## IKE (Internet Key Exchange) + +The default IPsec method for secure key negotiation is the Internet Key +Exchange (IKE) protocol. IKE is designed to provide mutual authentication +of systems, as well as to establish a shared secret key to create IPsec +security associations. A security association (SA) includes all relevant +attributes of the connection, including the cryptographic algorithm used, +the IPsec mode, the encryption key, and other parameters related to the +transmission of data over the VPN connection. + +### IKEv1 + +IKEv1 is the older version and is still used today. Nowadays, most +manufacturers recommend using IKEv2 protocol. + +IKEv1 is described in the next RFCs: {rfc}`2409` (IKE), {rfc}`3407` +(IPsec DOI), {rfc}`3947` (NAT-T), {rfc}`3948` (UDP Encapsulation +of ESP Packets), {rfc}`3706` (DPD) + +```{eval-rst} +IKEv1 operates in two phases to establish these IKE and IPsec SAs: + * **Phase 1** provides mutual authentication of the IKE peers and + establishment of the session key. This phase creates an IKE SA (a + security association for IKE) using a DH exchange, cookies, and an + ID exchange. Once an IKE SA is established, all IKE communication + between the initiator and responder is protected with encryption + and an integrity check that is authenticated. The purpose of IKE + phase 1 is to facilitate a secure channel between the peers so that + phase 2 negotiations can occur securely. IKE phase 1 offers two modes: + Main and Aggressive. + + * **Main Mode** is used for site-to-site VPN connections. + + * **Aggressive Mode** is used for remote access VPN connections. + + * **Phase 2** provides for the negotiation and establishment of the + IPsec SAs using ESP or AH to protect IP data traffic. +``` + +### IKEv2 + +IKEv2 is described in {rfc}`7296`. The biggest difference between IKEv1 and +IKEv2 is that IKEv2 is much simpler and more reliable than IKEv1 because +fewer messages are exchanged during the establishment of the VPN and +additional security capabilities are available. + +### IKE Authentication + +```{eval-rst} +VyOS supports 3 authentication methods. + * **Pre-shared keys**: In this method, both peers of the IPsec + tunnel must have the same preshared keys. + * **Digital certificates**: PKI is used in this method. + * **RSA-keys**: If the RSA-keys method is used in your IKE policy, + you need to make sure each peer has the other peer’s public keys. +``` + +## DPD (Dead Peer Detection) + +This is a mechanism used to detect when a VPN peer is no longer active. +This mechanism has different algorithms in IKEv1 and IKEv2 in VyOS. +DPD Requests are sent as ISAKMP R-U-THERE messages and DPD Responses +are sent as ISAKMP R-U-THERE-ACK messages. In IKEv1, DPD sends messages +every configured interval. The remote peer is considered unreachable +if no response to these packets is received within the DPD timeout. +In IKEv2, DPD sends messages every configured interval. If one request +is not responded, Strongswan execute its retransmission algorithm with +its timers. [IKEv2 Retransmission](#ikev2-retransmission) + +## Post-Quantum Preshared Keys (PPK) + +Post-Quantum Preshared Keys help provide some quantum resistance to IPSec +tunnels when a post-quantum key exchange algorithm such as ML-KEM is not +available. The use of PPKs in IKEv2 is described in {rfc}`8784`. + +```{eval-rst} +.. cfgmod:: edit vpn authentication ppk <name> +``` + +PPKs can be configured within VyOS under the `vpn ipsec authentication ppk` +config. + +```{eval-rst} +.. cfgmod:: set vpn authentication ppk <name> secret-type <plaintext|hex|base64> +``` + +PPKs need an id and a secret value. The ID and the secret must match if PPKs are +required for a successful IPsec connection. The secret can be plain text, a +hex value, or a Base64 value. The default is plain text. If using another +type of value, you must define the secret type. + +```{eval-rst} +.. cfgmod:: set vpn ipsec site-to-site <name> ppk id <id> +``` + +To use a PPK within a site-to-site or remote access connection, define the PPK +id under the connection. + +```{eval-rst} +.. cfgmod:: set vpn ipsec site-to-site <name> ppk required +``` + +Optionally, you can require the use of PPK to have a successful connection. + +```{eval-rst} +.. cfgmod:: show vpn ipsec connections +``` + +You can view the PPK column for information on if PPK is configured, and +if it is in use. The output is in the format of `<configured> / <in use>`. +The options for configured are none if not configured, opt if configured +but optional, and req is configured and required. The in use will show yes +Possible values of the `configured` field are `none` if not +configured, `opt` if configured but optional, and `req` is +configured and required. The in use will show yes + +## Configuration IKE + +```{eval-rst} +IKE (Internet Key Exchange) Attributes +====================================== + +VyOS IKE group has the next options: + +.. cfgcmd:: set vpn ipsec ike-group <name> close-action <action> + + Defines the action to take if the remote peer unexpectedly + closes a CHILD_SA: + + * **none** - Set action to none (default), + * **trap** - Installs a trap policy (IPsec policy without Security + Association) for the CHILD_SA and traffic matching these policies + will trigger acquire events that cause the daemon to establish the + required IKE/IPsec SAs. + * **start** - Tries to immediately re-create the CHILD_SA. + +.. cfgcmd:: set vpn ipsec ike-group <name> ikev2-reauth + + Whether rekeying of an IKE_SA should also reauthenticate + the peer. In IKEv1, reauthentication is always done. + Setting this parameter enables remote host re-authentication + during an IKE rekey. + +.. cfgcmd:: set vpn ipsec ike-group <name> key-exchange + + Which protocol should be used to initialize the connection + If not set both protocols are handled and connections will + use IKEv2 when initiating, but accept any protocol version + when responding: + + * **ikev1** - Use IKEv1 for Key Exchange. + * **ikev2** - Use IKEv2 for Key Exchange. + +.. cfgcmd:: set vpn ipsec ike-group <name> lifetime + + IKE lifetime in seconds <0-86400> (default 28800). + +.. cfgcmd:: set vpn ipsec ike-group <name> mode + + IKEv1 Phase 1 Mode Selection: + + * **main** - Use Main mode for Key Exchanges in the IKEv1 Protocol + (Recommended Default). + * **aggressive** - Use Aggressive mode for Key Exchanges in the IKEv1 + protocol aggressive mode is much more insecure compared to Main mode. + +.. stop_vyoslinter + +.. cfgcmd:: set vpn ipsec ike-group <name> proposal <number> dh-group <dh-group number> + + Dh-group. Default value is **2**. + +.. cfgcmd:: set vpn ipsec ike-group <name> proposal <number> encryption <encryption> + + Encryption algorithm. Default value is **aes128**. + +.. start_vyoslinter + +.. cfgcmd:: set vpn ipsec ike-group <name> proposal <number> hash <hash> + + Hash algorithm. Default value is **sha1**. + +.. cfgcmd:: set vpn ipsec ike-group <name> proposal <number> prf <prf> + + Pseudo-random function. + + +DPD (Dead Peer Detection) Configuration +======================================= + +.. cfgcmd:: set vpn ipsec ike-group <name> dead-peer-detection action <action> + + Action to perform for this CHILD_SA on DPD timeout. + + * **trap** - Installs a trap policy (IPsec policy without Security + Association), which will catch matching traffic and tries to + re-negotiate the tunnel on-demand. + * **clear** - Closes the CHILD_SA and does not take further action + (default). + * **restart** - Immediately tries to re-negotiate the CHILD_SA + under a fresh IKE_SA. + +.. stop_vyoslinter + +.. cfgcmd:: set vpn ipsec ike-group <name> dead-peer-detection interval <interval> + + Keep-alive interval in seconds <2-86400> (default 30). + +.. start_vyoslinter + +.. cfgcmd:: set vpn ipsec ike-group <name> dead-peer-detection timeout <timeout> + + Keep-alive timeout in seconds <2-86400> (default 120) **IKEv1 only** + +ESP (Encapsulating Security Payload) Attributes +=============================================== + +In VyOS, ESP attributes are specified through ESP groups. +Multiple proposals can be specified in a single group. + +VyOS ESP group has the next options: + +.. cfgcmd:: set vpn ipsec esp-group <name> compression + + Enables the IPComp(IP Payload Compression) protocol which allows + compressing the content of IP packets. + +.. cfgcmd:: set vpn ipsec esp-group <name> disable-rekey + + Do not locally initiate a re-key of the SA, remote peer must + re-key before expiration. + +.. cfgcmd:: set vpn ipsec esp-group <name> life-bytes <bytes> + + ESP life in bytes <1024-26843545600000>. Number of bytes + transmitted over an IPsec SA before it expires. + +.. cfgcmd:: set vpn ipsec esp-group <name> life-packets <packets> + + ESP life in packets <1000-26843545600000>. + Number of packets transmitted over an IPsec SA before it expires. + +.. cfgcmd:: set vpn ipsec esp-group <name> lifetime <timeout> + + ESP lifetime in seconds <30-86400> (default 3600). + How long a particular instance of a connection (a set of + encryption/authentication keys for user packets) should last, + from successful negotiation to expiry. + +.. cfgcmd:: set vpn ipsec esp-group <name> mode <mode> + + The type of the connection: + + * **tunnel** - Tunnel mode (default). + * **transport** - Transport mode. + +.. cfgcmd:: set vpn ipsec esp-group <name> pfs < dh-group> + + Whether Perfect Forward Secrecy of keys is desired on the + connection's keying channel and defines a Diffie-Hellman group for + PFS: + + * **enable** - Inherit Diffie-Hellman group from IKE group (default). + * **disable** - Disable PFS. + * **<dh-group>** - Defines a Diffie-Hellman group for PFS. + +.. stop_vyoslinter + +.. cfgcmd:: set vpn ipsec esp-group <name> proposal <number> encryption <encryption> + + Encryption algorithm. Default value is **aes128**. + +.. start_vyoslinter + +.. cfgcmd:: set vpn ipsec esp-group <name> proposal <number> hash <hash> + + Hash algorithm. Default value is **sha1**. + +Global IPsec Settings +===================== + +.. cfgcmd:: set vpn ipsec interface <name> + + Interface name to restrict outbound IPsec policies. There is a possibility + to specify multiple interfaces. If an interfaces are not specified, IPsec + policies apply to all interfaces. + + +.. cfgcmd:: set vpn ipsec log level <number> + + Level of logging. Default value is **0**. + +.. cfgcmd:: set vpn ipsec log subsystem <name> + + Subsystem of the daemon. + +Options +======= + +.. cfgcmd:: set vpn ipsec options disable-route-autoinstall + + Do not automatically install routes to remote + networks. + +.. cfgcmd:: set vpn ipsec options flexvpn + + Allows FlexVPN vendor ID payload (IKEv2 only). Send the Cisco + FlexVPN vendor ID payload (IKEv2 only), which is required in order to make + Cisco brand devices allow negotiating a local traffic selector (from + strongSwan's point of view) that is not the assigned virtual IP address if + such an address is requested by strongSwan. Sending the Cisco FlexVPN + vendor ID prevents the peer from narrowing the initiator's local traffic + selector and allows it to e.g. negotiate a TS of 0.0.0.0/0 == 0.0.0.0/0 + instead. This has been tested with a "tunnel mode ipsec ipv4" Cisco + template but should also work for GRE encapsulation. + +.. cfgcmd:: set vpn ipsec options interface <name> + + Interface Name to use. The name of the interface on which + virtual IP addresses should be installed. If not specified the addresses + will be installed on the outbound interface. + +.. cfgcmd:: set vpn ipsec options virtual-ip + + Allows the installation of virtual-ip addresses. +``` + +### IKEv2 Retransmission + +If the peer does not respond on DPD packet, the router starts retransmission procedure. + +The following formula is used to calculate the timeout: + +```none +relative timeout = timeout * base ^ (attempts-1) +``` + +```{cfgcmd} set vpn ipsec options retransmission attempts + +Number of attempts before the peer is considered to be in the down state. +Default value is **5**. +``` + +```{cfgcmd} set vpn ipsec options retransmission base + +Base number of exponential backoff. Default value is **1.8**. +``` + +```{cfgcmd} set vpn ipsec options retransmission timeout + +Timeout in seconds before the first retransmission. Default value is **4**. +``` + +Using the default values, packets are retransmitted as follows: + +```{eval-rst} ++-----------+-------------+------------------+------------------+ +| Attempts | Formula | Relative timeout | Absolute timeout | ++-----------+-------------+------------------+------------------+ +| 1 | 4 * 1.8 ^ 0 | 4s | 4s | ++-----------+-------------+------------------+------------------+ +| 2 | 4 * 1.8 ^ 1 | 7s | 11s | ++-----------+-------------+------------------+------------------+ +| 3 | 4 * 1.8 ^ 2 | 13s | 24s | ++-----------+-------------+------------------+------------------+ +| 4 | 4 * 1.8 ^ 3 | 23s | 47s | ++-----------+-------------+------------------+------------------+ +| 5 | 4 * 1.8 ^ 4 | 42s | 89s | ++-----------+-------------+------------------+------------------+ +| peer down | 4 * 1.8 ^ 5 | 76s | 165s | ++-----------+-------------+------------------+------------------+ +``` diff --git a/docs/configuration/vpn/ipsec/remoteaccess_ipsec.md b/docs/configuration/vpn/ipsec/remoteaccess_ipsec.md new file mode 100644 index 00000000..6931e00b --- /dev/null +++ b/docs/configuration/vpn/ipsec/remoteaccess_ipsec.md @@ -0,0 +1,186 @@ +(remoteaccess-ipsec)= + +# IPSec IKEv2 Remote Access VPN + +```{todo} +Convert raw command blocks in this file to cfgcmd/opcmd +directives for command coverage tracking. +``` + +Internet Key Exchange version 2 (IKEv2) is a tunneling protocol, based on IPsec, +that establishes a secure VPN communication between VPN devices, and defines +negotiation and authentication processes for IPsec security associations (SAs). +It is often known as IKEv2/IPSec or IPSec IKEv2 remote-access — or road-warriors +as others call it. + +Key exchange and payload encryption is done using IKE and ESP proposals as known +from IKEv1 but the connections are faster to establish, more reliable, and also +support roaming from IP to IP (called MOBIKE which makes sure your connection +does not drop when changing networks from e.g. WIFI to LTE and back). +Authentication can be achieved with X.509 certificates. + +## Setting up certificates: + +First of all, we need to create a CA root certificate and server certificate +on the server side. + +```none +vyos@vpn.vyos.net# run generate pki ca install ca_root +Enter private key type: [rsa, dsa, ec] (Default: rsa) +Enter private key bits: (Default: 2048) +Enter country code: (Default: GB) +Enter state: (Default: Some-State) +Enter locality: (Default: Some-City) +Enter organization name: (Default: VyOS) +Enter common name: (Default: vyos.io) +Enter how many days certificate will be valid: (Default: 1825) +Note: If you plan to use the generated key on this router, do not encrypt the private key. +Do you want to encrypt the private key with a passphrase? [y/N] N +2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. +[edit] + + +vyos@vpn.vyos.net# comp +[pki ca] ++ ca_root { ++ certificate "MIIDnTCCAoWgAwI…." ++ private { ++ key "MIIEvAIBADANBgkqhkiG9….” + +vyos@vpn.vyos.net# run generate pki certificate sign ca_root install server_cert +Do you already have a certificate request? [y/N] N +Enter private key type: [rsa, dsa, ec] (Default: rsa) +Enter private key bits: (Default: 2048) +Enter country code: (Default: GB) +Enter state: (Default: Some-State) +Enter locality: (Default: Some-City) +Enter organization name: (Default: VyOS) +Enter common name: (Default: vyos.io) vpn.vyos.net +Do you want to configure Subject Alternative Names? [y/N] N +Enter how many days certificate will be valid: (Default: 365) +Enter certificate type: (client, server) (Default: server) +Note: If you plan to use the generated key on this router, do not encrypt the private key. +Do you want to encrypt the private key with a passphrase? [y/N] N +2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. + +vyos@vpn.vyos.net# comp +[pki certificate] ++ server_cert { ++ certificate "MIIDuzCCAqOgAwIBAgIUaSrCPWx………" ++ private { ++ key "MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBK….." ++ } ++ } +``` + +Once the command is completed, it will add the certificate to the configuration +session, to the pki subtree. You can then review the proposed changes and +commit them. + +## Setting up IPSec: + +After the PKI certs are all set up we can start configuring our IPSec/IKE +proposals used for key-exchange end data encryption. The used encryption ciphers +and integrity algorithms vary from operating system to operating system. The +ones used in this example are validated to work on Windows 10. + +```none +set vpn ipsec esp-group ESP-RW lifetime '3600' +set vpn ipsec esp-group ESP-RW pfs 'disable' +set vpn ipsec esp-group ESP-RW proposal 10 encryption 'aes128gcm128' +set vpn ipsec esp-group ESP-RW proposal 10 hash 'sha256' + +set vpn ipsec ike-group IKE-RW key-exchange 'ikev2' +set vpn ipsec ike-group IKE-RW lifetime '7200' +set vpn ipsec ike-group IKE-RW proposal 10 dh-group '14' +set vpn ipsec ike-group IKE-RW proposal 10 encryption 'aes128gcm128' +set vpn ipsec ike-group IKE-RW proposal 10 hash 'sha256' +``` + +Every connection/remote-access pool we configure also needs a pool where we +can draw our client IP addresses from. We provide one IPv4 and IPv6 pool. +Authorized clients will receive an IPv4 address from the configured IPv4 prefix +and an IPv6 address from the IPv6 prefix. We can also send some DNS nameservers +down to our clients used on their connection. + +```none +set vpn ipsec remote-access pool ra-rw-ipv4 name-server '192.0.2.1' +set vpn ipsec remote-access pool ra-rw-ipv4 prefix '192.0.2.128/25' + +set vpn ipsec remote-access pool ra-rw-ipv6 name-server '2001:db8:1000::1' +set vpn ipsec remote-access pool ra-rw-ipv6 prefix '2001:db8:2000::/64' +``` + + +## Setting up tunnel: + +```none +set vpn ipsec remote-access connection rw authentication local-id '192.0.2.1' +set vpn ipsec remote-access connection rw authentication server-mode 'x509' +set vpn ipsec remote-access connection rw authentication x509 ca-certificate 'ca_root' +set vpn ipsec remote-access connection rw authentication x509 certificate 'server_cert' +set vpn ipsec remote-access connection rw esp-group 'ESP-RW' +set vpn ipsec remote-access connection rw ike-group 'IKE-RW' +set vpn ipsec remote-access connection rw local-address '192.0.2.1' +set vpn ipsec remote-access connection rw pool 'ra-rw-ipv4' +set vpn ipsec remote-access connection rw pool 'ra-rw-ipv6' +``` + +VyOS also supports two different modes of authentication, local and RADIUS. +To create a new local user named "vyos" with a password of "vyos" use the +following commands. + +```none +set vpn ipsec remote-access connection rw authentication client-mode 'eap-mschapv2' +set vpn ipsec remote-access connection rw authentication local-users username vyos password 'vyos' +``` + +Some client operating systems like to see the servers certificate. The following +option causes the server to voluntarily send its certificate, even if it wasn't +requested. + +```none +set vpn ipsec remote-access connection rw authentication always-send-cert +``` + + +## Client Configuration + +Most operating systems include native client support for IPsec IKEv2 VPN +connections, and others typically have an app or add-on package which adds the +capability. +This section covers IPsec IKEv2 client configuration for Windows 10. + +VyOS provides a command to generate a connection profile used by Windows clients +that will connect to the "rw" connection on our VyOS server. + +:::{note} +Windows expects the server name to be also used in the server's +certificate common name, so it's best to use this DNS name for your VPN +connection. +::: + +```none +vyos@vpn.vyos.net:~$ generate ipsec profile windows-remote-access rw remote vpn.vyos.net + + +==== <snip> ==== +Add-VpnConnection -Name "VyOS IKEv2 VPN" -ServerAddress "vpn.vyos.net" -TunnelType "Ikev2" + +Set-VpnConnectionIPsecConfiguration -ConnectionName "VyOS IKEv2 VPN" -AuthenticationTransformConstants GCMAES128 -CipherTransformConstants +GCMAES128 -EncryptionMethod GCMAES128 -IntegrityCheckMethod SHA256128 -PfsGroup None -DHGroup "Group14" -PassThru -Force +==== </snip> ==== +``` + +Add the commands from Snippet in the Windows side via PowerShell. +Also import the root CA cert to the Windows “Trusted Root Certification +Authorities” and establish the connection. + +## Verification: + +```none +vyos@vpn.vyos.net:~$ show vpn ipsec remote-access summary + Connection ID Username Protocol State Uptime Tunnel IP Remote Host Remote ID IKE Proposal IPSec Proposal +--------------- ---------- ---------- ------- -------- ----------- ------------- ----------- ------------------------------------------ ------------------ + 5 vyos IKEv2 UP 37s 192.0.2.129 10.0.0.2 10.0.0.2 AES_GCM_16-128/PRF_HMAC_SHA2_256/MODP_2048 ESP:AES_GCM_16-128 +``` diff --git a/docs/configuration/vpn/ipsec/index.rst b/docs/configuration/vpn/ipsec/rst-index.rst index 973c76de..973c76de 100644 --- a/docs/configuration/vpn/ipsec/index.rst +++ b/docs/configuration/vpn/ipsec/rst-index.rst diff --git a/docs/configuration/vpn/ipsec/ipsec_general.rst b/docs/configuration/vpn/ipsec/rst-ipsec_general.rst index 3d21b81d..3d21b81d 100644 --- a/docs/configuration/vpn/ipsec/ipsec_general.rst +++ b/docs/configuration/vpn/ipsec/rst-ipsec_general.rst diff --git a/docs/configuration/vpn/ipsec/remoteaccess_ipsec.rst b/docs/configuration/vpn/ipsec/rst-remoteaccess_ipsec.rst index 50499160..50499160 100644 --- a/docs/configuration/vpn/ipsec/remoteaccess_ipsec.rst +++ b/docs/configuration/vpn/ipsec/rst-remoteaccess_ipsec.rst diff --git a/docs/configuration/vpn/ipsec/site2site_ipsec.rst b/docs/configuration/vpn/ipsec/rst-site2site_ipsec.rst index 9f8231e7..9f8231e7 100644 --- a/docs/configuration/vpn/ipsec/site2site_ipsec.rst +++ b/docs/configuration/vpn/ipsec/rst-site2site_ipsec.rst diff --git a/docs/configuration/vpn/ipsec/troubleshooting_ipsec.rst b/docs/configuration/vpn/ipsec/rst-troubleshooting_ipsec.rst index f0f2e208..f0f2e208 100644 --- a/docs/configuration/vpn/ipsec/troubleshooting_ipsec.rst +++ b/docs/configuration/vpn/ipsec/rst-troubleshooting_ipsec.rst diff --git a/docs/configuration/vpn/ipsec/site2site_ipsec.md b/docs/configuration/vpn/ipsec/site2site_ipsec.md new file mode 100644 index 00000000..d3b65ae1 --- /dev/null +++ b/docs/configuration/vpn/ipsec/site2site_ipsec.md @@ -0,0 +1,780 @@ +(size2site-ipsec)= + +# IPsec Site-to-Site VPN + +## IPsec Site-to-Site VPN Types + +VyOS supports two types of IPsec VPN: Policy-based IPsec VPN and Route-based +IPsec VPN. + +### Policy-based VPN + +Policy-based VPN is based on static configured policies. Each policy creates +individual IPSec SA. Traffic matches these SAs encrypted and directed to the +remote peer. + +### Route-Based VPN + +Route-based VPN is based on secure traffic passing over Virtual Tunnel +Interfaces (VTIs). This type of IPsec VPNs allows using routing protocols. + +## Configuration Site-to-Site VPN + +### Requirements and Prerequisites for Site-to-Site VPN + +**Negotiated parameters that need to match** + +```{eval-rst} +Phase 1 + * IKE version + * Authentication + * Encryption + * Hashing + * PRF + * Lifetime + + .. note:: Strongswan recommends to use the same lifetime value on both peers + +Phase 2 + * Encryption + * Hashing + * PFS + * Mode (tunnel or transport) + * Lifetime + + .. note:: Strongswan recommends to use the same lifetime value on both peers + + * Remote and Local networks in SA must be compatible on both peers +``` + +### Configuration Steps for Site-to-Site VPN + +The next example shows the configuration one of the router participating in +IPsec VPN. + +```{eval-rst} +Tunnel information: + * Phase 1: + * encryption: AES256 + * hash: SHA256 + * PRF: SHA256 + * DH: 14 + * lifetime: 28800 + * Phase 2: + * IPsec mode: tunnel + * encryption: AES256 + * hash: SHA256 + * PFS: inherited from DH Phase 1 + * lifetime: 3600 + * If Policy based VPN is used + * Remote network is 192.168.50.0/24. Local network is 192.168.10.0/24 + * If Route based VPN is used + * IP of the VTI interface is 10.0.0.1/30 +``` + +:::{note} +We do not recommend using policy-based vpn and route-based vpn configurations to the same peer. +::: + +**1. Configure ike-group (IKE Phase 1)** + +```none +set vpn ipsec ike-group IKE close-action 'start' +set vpn ipsec ike-group IKE key-exchange 'ikev1' +set vpn ipsec ike-group IKE lifetime '28800' +set vpn ipsec ike-group IKE proposal 10 dh-group '14' +set vpn ipsec ike-group IKE proposal 10 encryption 'aes256' +set vpn ipsec ike-group IKE proposal 10 hash 'sha256' +set vpn ipsec ike-group IKE proposal 10 prf 'prfsha256' +``` + +**2. Configure ESP-group (IKE Phase 2)** + +```none +set vpn ipsec esp-group ESP lifetime '3600' +set vpn ipsec esp-group ESP mode 'tunnel' +set vpn ipsec esp-group ESP pfs 'enable' +set vpn ipsec esp-group ESP proposal 10 encryption 'aes256' +set vpn ipsec esp-group ESP proposal 10 hash 'sha256' +``` + +**3. Specify interface facing to the protected destination.** + +```none +set vpn ipsec interface eth0 +``` + +**4. Configure PSK keys and authentication ids for this key if authentication type is PSK** + +```none +set vpn ipsec authentication psk PSK-KEY id '192.168.0.2' +set vpn ipsec authentication psk PSK-KEY id '192.168.5.2' +set vpn ipsec authentication psk PSK-KEY secret 'vyos' +``` + +To set base64 secret encode plaintext password to base64 and set secret-type + +```none +echo -n "vyos" | base64 +dnlvcw== +``` + +```none +set vpn ipsec authentication psk PSK-KEY secret 'dnlvcw==' +set vpn ipsec authentication psk PSK-KEY secret-type base64 +``` + +**5. Configure peer and apply IKE-group and esp-group to peer.** + +```none +set vpn ipsec site-to-site peer PEER1 authentication local-id '192.168.0.2' +set vpn ipsec site-to-site peer PEER1 authentication mode 'pre-shared-secret' +set vpn ipsec site-to-site peer PEER1 authentication remote-id '192.168.5.2' +set vpn ipsec site-to-site peer PEER1 connection-type 'initiate' +set vpn ipsec site-to-site peer PEER1 default-esp-group 'ESP' +set vpn ipsec site-to-site peer PEER1 ike-group 'IKE' +set vpn ipsec site-to-site peer PEER1 local-address '192.168.0.2' +set vpn ipsec site-to-site peer PEER1 remote-address '192.168.5.2' + +Peer selects the key from step 4 according to local-id/remote-id pair. +``` + +**6. Depends to vpn type (route-based vpn or policy-based vpn).** + +> **6.1 For Policy-based VPN configure SAs using tunnel command specifying remote and local networks.** +> +> > ```none +> > set vpn ipsec site-to-site peer PEER1 tunnel 1 local prefix '192.168.10.0/24' +> > set vpn ipsec site-to-site peer PEER1 tunnel 1 remote prefix '192.168.50.0/24' +> > ``` +> +> **6.2 For Route-based VPN create VTI interface, set IP address to this interface and bind this interface to the vpn peer.** +> +> > ```none +> > set interfaces vti vti1 address 10.0.0.1/30 +> > set vpn ipsec site-to-site peer PEER1 vti bind vti1 +> > set vpn ipsec options disable-route-autoinstall +> > ``` +> > +> > Create routing between local networks via VTI interface using dynamic or +> > static routing. +> > +> > ```none +> > set protocol static route 192.168.50.0/24 next-hop 10.0.0.2 +> > ``` + +### Initiator and Responder Connection Types + +In Site-to-Site IPsec VPN it is recommended that one peer should be an +initiator and the other - the responder. The initiator actively establishes +the VPN tunnel. The responder passively waits for the remote peer to +establish the VPN tunnel. Depends on selected role it is recommended +select proper values for close-action and DPD action. + +The result of wrong value selection can be unstable work of the VPN. +: - Duplicate CHILD SA creation. + - None of the VPN sides initiates the tunnel establishment. + +Below flow-chart could be a quick reference for the close-action +combination depending on how the peer is configured. + +```{eval-rst} +.. figure:: /_static/images/IPSec_close_action_settings.webp +``` + +Similar combinations are applicable for the dead-peer-detection. + +### Detailed Configuration Commands + +#### PSK Key Authentication + +```{cfgcmd} set vpn ipsec authentication psk \<name\> dhcp-interface + +ID for authentication generated from DHCP address +dynamically. + +``` + +```{cfgcmd} set vpn ipsec authentication psk id \<id\> + +static ID's for authentication. In general local and remote address +``<x.x.x.x>``, ``<h:h:h:h:h:h:h:h>`` or ``%any``. +``` + +```{cfgcmd} set vpn ipsec authentication psk secret \<secret\> + +A predefined shared secret used in configured mode +``pre-shared-secret``. Base64-encoded secrets are allowed if +`secret-type base64` is configured. +``` + +```{cfgcmd} set vpn ipsec authentication psk secret-type \<type\> + +Specifies the secret type: + +* **plaintext** - Plain text type (default value). +* **base64** - Base64 type. +``` + +#### Peer Configuration + + +##### Peer Authentication Commands + +```{cfgcmd} set vpn ipsec site-to-site peer \<name\> authentication mode \<mode\> + +Mode for authentication between VyOS and remote peer: + +* **pre-shared-secret** - Use predefined shared secret phrase. +* **rsa** - Use simple shared RSA key. +* **x509** - Use certificates infrastructure for authentication. +``` + +```{cfgcmd} set vpn ipsec site-to-site peer \<name\> authentication local-id \<id\> + +ID for the local VyOS router. If defined, during the authentication +it will be send to remote peer. +``` + +```{cfgcmd} set vpn ipsec site-to-site peer \<name\> authentication remote-id \<id\> + +ID for remote peer, instead of using peer name or +address. Useful in case if the remote peer is behind NAT +or if ``mode x509`` is used. +``` + +```{cfgcmd} set vpn ipsec site-to-site peer \<name\> authentication rsa local-key \<key\> + +Name of PKI key-pair with local private key. +``` + +```{cfgcmd} set vpn ipsec site-to-site peer \<name\> authentication rsa remote-key \<key\> + +Name of PKI key-pair with remote public key. +``` + +```{cfgcmd} set vpn ipsec site-to-site peer \<name\> authentication rsa passphrase \<passphrase\> + +Local private key passphrase. +``` + +```{cfgcmd} set vpn ipsec site-to-site peer \<name\> authentication use-x509-id \<id\> + +Use local ID from x509 certificate. Cannot be used when +``id`` is defined. +``` + +```{cfgcmd} set vpn ipsec site-to-site peer \<name\> authentication x509 ca-certificate \<name\> + +Name of CA certificate in PKI configuration. Using for authenticating +remote peer in x509 mode. +``` + +```{cfgcmd} set vpn ipsec site-to-site peer \<name\> authentication x509 certificate \<name\> + +Name of certificate in PKI configuration, which will be used +for authenticating local router on remote peer. +``` + +```{cfgcmd} set vpn ipsec authentication x509 passphrase \<passphrase\> + +Private key passphrase, if needed. +``` + +##### Global Peer Configuration Commands + +```{cfgcmd} set vpn ipsec site-to-site peer \<name\> connection-type \<type\> + +Operational mode defines how to handle this connection process. + +* **initiate** - does initial connection to remote peer immediately + after configuring and after boot. In this mode the connection will + not be restarted in case of disconnection, therefore should be used + only together with DPD or another session tracking methods. + +* **trap** - does not try to initiate a connection to a remote + peer immediately. Instead, it installs a trap policy that will + trigger IKE negotiation and establish the IPsec session when + matching traffic is sent from the local side. This can be useful + when there is no direct connectivity to the peer due to firewall + or NAT in the middle of the local and remote side. + + :::{warning} + The ``trap`` mode is not needed in most environments + and can lead to connection confusion or unintended tunnel uptime + behavior if used incorrectly. Using this mode requires careful + coordination with parameters such as ``close-action`` and DPD. + For most deployments, use ``initiate`` and ``none`` as described below. + ::: + +* **none** - loads the connection only, which then can be manually + initiated or used as a responder configuration. + +:::{note} +For most site-to-site VPNs, configure one peer +with ``connection-type initiate`` (active side) and the other peer +with ``connection-type none`` (passive side) to +ensure stable and predictable tunnel behavior. +When using ``connection-type initiate``, you must also configure +DPD or another session tracking method (such as ``close-action``) +to automatically re-establish the tunnel after a disconnection. +Otherwise, the tunnel will not reconnect automatically if it goes down. +::: +``` + +```{cfgcmd} set vpn ipsec site-to-site peer \<name\> default-esp-group \<name\> + +Name of ESP group to use by default for traffic encryption. +Might be overwritten by individual settings for tunnel or VTI +interface binding. +``` + +```{cfgcmd} set vpn ipsec site-to-site peer \<name\> description \<description\> + +Description for this peer. +``` + +```{cfgcmd} set vpn ipsec site-to-site peer \<name\> dhcp-interface \<interface\> + +Specify the interface which IP address, received from DHCP for IPSec +connection with this peer, will be used as ``local-address``. +``` + +```{cfgcmd} set vpn ipsec site-to-site peer \<name\> 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. +``` + +```{cfgcmd} set vpn ipsec site-to-site peer \<name\> ike-group \<name\> + +Name of IKE group to use for key exchanges. +``` + +```{cfgcmd} set vpn ipsec site-to-site peer \<name\> local-address \<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. +``` + +```{cfgcmd} set vpn ipsec site-to-site peer \<name\> remote-address \<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. +``` + +```{cfgcmd} set vpn ipsec site-to-site peer \<name\> replay-window \<size\> + +IPsec replay window to configure for CHILD_SAs +(default: 32), a value of 0 disables IPsec replay protection. +``` + +```{cfgcmd} set vpn ipsec site-to-site peer \<name\> virtual-address \<address\> + +Defines a virtual IP address which is requested by the initiator and +one or several IPv4 and/or IPv6 addresses are assigned from multiple +pools by the responder. The wildcard addresses 0.0.0.0 and :: +request an arbitrary address, specific addresses may be defined. +``` + +##### CHILD SAs Configuration Commands + +###### Policy-Based CHILD SAs Configuration Commands + +Every configured tunnel under peer configuration is a new CHILD SA. + +```{cfgcmd} set vpn ipsec site-to-site peer \<name\> tunnel \<number\> disable + +Disable this tunnel. +``` + +```{cfgcmd} set vpn ipsec site-to-site peer \<name\> tunnel \<number\> esp-group \<name\> + +Specify ESP group for this CHILD SA. +``` + +```{cfgcmd} set vpn ipsec site-to-site peer \<name\> tunnel \<number\> priority \<number\> + +Priority for policy-based IPsec VPN tunnels (lowest value more +preferable). +``` + +```{cfgcmd} set vpn ipsec site-to-site peer \<name\> tunnel \<number\> protocol \<name\> + +Define the protocol for match traffic, which should be encrypted and +send to this peer. +``` + +```{cfgcmd} set vpn ipsec site-to-site peer \<name\> tunnel \<number\> local prefix \<network\> + +IP network at the local side. +``` + +```{cfgcmd} set vpn ipsec site-to-site peer \<name\> tunnel \<number\> local port \<number\> + +Local port number. Have effect only when used together with +``prefix``. +``` + +```{cfgcmd} set vpn ipsec site-to-site peer \<name\> tunnel \<number\> remote prefix \<network\> + +IP network at the remote side. +``` + +```{cfgcmd} set vpn ipsec site-to-site peer \<name\> tunnel \<number\> remote port \<number\> + +Remote port number. Have effect only when used together with +``prefix``. +``` + +###### Route-Based CHILD SAs Configuration Commands + +To configure route-based VPN it is enough to create vti interface and +bind it to the peer. Any traffic, which will be send to VTI interface +will be encrypted and send to this peer. Using VTI makes IPsec +configuration much flexible and easier in complex situation, and +allows to dynamically add/delete remote networks, reachable via a +peer, as in this mode router don't need to create additional SA/policy +for each remote network. + +:::{warning} +When using site-to-site IPsec with VTI interfaces, +be sure to disable route autoinstall. +::: +```none +set vpn ipsec options disable-route-autoinstall +``` + +```{cfgcmd} set vpn ipsec site-to-site peer \<name\> vti bind \<interface\> + +VTI interface to bind to this peer. +``` + +```{cfgcmd} set vpn ipsec site-to-site peer \<name\> vti esp-group \<name\> + +ESP group for encrypt traffic, passed this VTI interface. +``` + +Traffic-selectors parameters for traffic that should pass via vti +interface. + +```{cfgcmd} set vpn ipsec site-to-site peer \<name\> vti traffic-selector local prefix \<network\> + +Local prefix for interesting traffic. +``` + +```{cfgcmd} set vpn ipsec site-to-site peer \<name\> vti traffic-selector remote prefix \<network\> + +Remote prefix for interesting traffic. +``` + +### IPsec Op-mode Commands + +```{opcmd} show vpn ike sa + +Shows active IKE SAs information. +``` + +```{opcmd} show vpn ike secrets + +Shows configured authentication keys. +``` + +```{opcmd} show vpn ike status + +Shows Strongswan daemon status. +``` + +```{opcmd} show vpn ipsec connections + +Shows summary status of all configured IKE and IPsec SAs. +``` + +```{opcmd} show vpn ipsec sa [detail] + +Shows active IPsec SAs information. +``` + +```{opcmd} show vpn ipsec status + +Shows status of IPsec process. +``` + +```{opcmd} show vpn ipsec policy + +Shows the in-kernel crypto policies. +``` + +```{opcmd} show vpn ipsec state + +Shows the in-kernel crypto state. +``` + +```{opcmd} show log ipsec + +Shows IPsec logs. +``` + +```{opcmd} reset vpn ipsec site-to-site all + +Clear all ipsec connection and reinitiate them if VyOS is configured +as initiator. +``` + +```{opcmd} reset vpn ipsec site-to-site peer \<name\> + +Clear all peer IKE SAs with IPsec SAs and reinitiate them if VyOS is +configured as initiator. +``` + +```{opcmd} reset vpn ipsec site-to-site peer \<name\> tunnel \<number\> + +Clear scpecific IPsec SA and reinitiate it if VyOS is configured as +initiator. +``` + +```{opcmd} reset vpn ipsec site-to-site peer \<name\> vti \<number\> + +Clear IPsec SA which is map to vti interface of this peer and +reinitiate it if VyOS is configured as initiator. +``` + +```{opcmd} restart ipsec + +Restart Strongswan daemon. +``` + +## Examples: + +### Policy-Based VPN Example + +**PEER1:** +- WAN interface on `eth0` +- `eth0` interface IP: `10.0.1.2/30` +- `dum0` interface IP: `192.168.0.1/24` (for testing purposes) +- Initiator + +**PEER2:** +- WAN interface on `eth0` +- `eth0` interface IP: `10.0.2.2/30` +- `dum0` interface IP: `192.168.1.0/24` (for testing purposes) +- Responder + +```none +# PEER1 +set interfaces dummy dum0 address '192.168.0.1/32' +set interfaces ethernet eth0 address '10.0.1.2/30' +set protocols static route 0.0.0.0/0 next-hop 10.0.1.1 +set vpn ipsec authentication psk AUTH-PSK id '10.0.1.2' +set vpn ipsec authentication psk AUTH-PSK id '10.0.2.2' +set vpn ipsec authentication psk AUTH-PSK secret 'test' +set vpn ipsec esp-group ESP-GRPOUP lifetime '3600' +set vpn ipsec esp-group ESP-GRPOUP proposal 10 encryption 'aes256' +set vpn ipsec esp-group ESP-GRPOUP proposal 10 hash 'sha1' +set vpn ipsec ike-group IKE-GROUP close-action 'start' +set vpn ipsec ike-group IKE-GROUP dead-peer-detection action 'restart' +set vpn ipsec ike-group IKE-GROUP dead-peer-detection interval '30' +set vpn ipsec ike-group IKE-GROUP dead-peer-detection timeout '120' +set vpn ipsec ike-group IKE-GROUP key-exchange 'ikev1' +set vpn ipsec ike-group IKE-GROUP lifetime '28800' +set vpn ipsec ike-group IKE-GROUP proposal 10 dh-group '14' +set vpn ipsec ike-group IKE-GROUP proposal 10 encryption 'aes256' +set vpn ipsec ike-group IKE-GROUP proposal 10 hash 'sha1' +set vpn ipsec interface 'eth0' +set vpn ipsec site-to-site peer PEER2 authentication local-id '10.0.1.2' +set vpn ipsec site-to-site peer PEER2 authentication mode 'pre-shared-secret' +set vpn ipsec site-to-site peer PEER2 authentication remote-id '10.0.2.2' +set vpn ipsec site-to-site peer PEER2 connection-type 'initiate' +set vpn ipsec site-to-site peer PEER2 default-esp-group 'ESP-GRPOUP' +set vpn ipsec site-to-site peer PEER2 ike-group 'IKE-GROUP' +set vpn ipsec site-to-site peer PEER2 local-address '10.0.1.2' +set vpn ipsec site-to-site peer PEER2 remote-address '10.0.2.2' +set vpn ipsec site-to-site peer PEER2 tunnel 0 local prefix '192.168.0.0/24' +set vpn ipsec site-to-site peer PEER2 tunnel 0 remote prefix '192.168.1.0/24' + + +# PEER2 +set interfaces dummy dum0 address '192.168.1.1/32' +set interfaces ethernet eth0 address '10.0.2.2/30' +set protocols static route 0.0.0.0/0 next-hop 10.0.2.1 +set vpn ipsec authentication psk AUTH-PSK id '10.0.1.2' +set vpn ipsec authentication psk AUTH-PSK id '10.0.2.2' +set vpn ipsec authentication psk AUTH-PSK secret 'test' +set vpn ipsec esp-group ESP-GRPOUP lifetime '3600' +set vpn ipsec esp-group ESP-GRPOUP proposal 10 encryption 'aes256' +set vpn ipsec esp-group ESP-GRPOUP proposal 10 hash 'sha1' +set vpn ipsec ike-group IKE-GROUP close-action 'none' +set vpn ipsec ike-group IKE-GROUP dead-peer-detection action 'clear' +set vpn ipsec ike-group IKE-GROUP dead-peer-detection interval '30' +set vpn ipsec ike-group IKE-GROUP dead-peer-detection timeout '120' +set vpn ipsec ike-group IKE-GROUP key-exchange 'ikev1' +set vpn ipsec ike-group IKE-GROUP lifetime '28800' +set vpn ipsec ike-group IKE-GROUP proposal 10 dh-group '14' +set vpn ipsec ike-group IKE-GROUP proposal 10 encryption 'aes256' +set vpn ipsec ike-group IKE-GROUP proposal 10 hash 'sha1' +set vpn ipsec interface 'eth0' +set vpn ipsec site-to-site peer PEER1 authentication local-id '10.0.2.2' +set vpn ipsec site-to-site peer PEER1 authentication mode 'pre-shared-secret' +set vpn ipsec site-to-site peer PEER1 authentication remote-id '10.0.1.2' +set vpn ipsec site-to-site peer PEER1 connection-type 'none' +set vpn ipsec site-to-site peer PEER1 default-esp-group 'ESP-GRPOUP' +set vpn ipsec site-to-site peer PEER1 ike-group 'IKE-GROUP' +set vpn ipsec site-to-site peer PEER1 local-address '10.0.2.2' +set vpn ipsec site-to-site peer PEER1 remote-address '10.0.1.2' +set vpn ipsec site-to-site peer PEER1 tunnel 0 local prefix '192.168.1.0/24' +set vpn ipsec site-to-site peer PEER1 tunnel 0 remote prefix '192.168.0.0/24' +``` + +Show status of policy-based IPsec VPN setup: + +```none +vyos@PEER2:~$ show vpn ike sa +Peer ID / IP Local ID / IP +------------ ------------- +10.0.1.2 10.0.1.2 10.0.2.2 10.0.2.2 + + State IKEVer Encrypt Hash D-H Group NAT-T A-Time L-Time + ----- ------ ------- ---- --------- ----- ------ ------ + up IKEv1 AES_CBC_256 HMAC_SHA1_96 MODP_2048 no 1254 25633 + + +vyos@srv-gw0:~$ show vpn ipsec sa +Connection State Uptime Bytes In/Out Packets In/Out Remote address Remote ID Proposal +-------------- ------- -------- -------------- ---------------- ---------------- ----------- ---------------------------------- +PEER1-tunnel-0 up 20m42s 0B/0B 0/0 10.0.1.2 10.0.1.2 AES_CBC_256/HMAC_SHA1_96/MODP_2048 + +vyos@PEER2:~$ show vpn ipsec connections +Connection State Type Remote address Local TS Remote TS Local id Remote id Proposal +-------------- ------- ------ ---------------- -------------- -------------- ---------- ----------- ---------------------------------- +PEER1 up IKEv1 10.0.1.2 - - 10.0.2.2 10.0.1.2 AES_CBC/256/HMAC_SHA1_96/MODP_2048 +PEER1-tunnel-0 up IPsec 10.0.1.2 192.168.1.0/24 192.168.0.0/24 10.0.2.2 10.0.1.2 AES_CBC/256/HMAC_SHA1_96/MODP_2048 +``` + +If there is SNAT rules on eth0, need to add exclude rule + +```none +# PEER1 side +set nat source rule 10 destination address '192.168.1.0/24' +set nat source rule 10 'exclude' +set nat source rule 10 outbound-interface name 'eth0' +set nat source rule 10 source address '192.168.0.0/24' + +# PEER2 side +set nat source rule 10 destination address '192.168.0.0/24' +set nat source rule 10 'exclude' +set nat source rule 10 outbound-interface name 'eth0' +set nat source rule 10 source address '192.168.1.0/24' +``` + +### Route-Based VPN Example + +**PEER1:** +- WAN interface on `eth0` +- `eth0` interface IP: `10.0.1.2/30` +- 'vti0' interface IP: `10.100.100.1/30` +- `dum0` interface IP: `192.168.0.1/24` (for testing purposes) +- Role: Initiator + +**PEER2:** +- WAN interface on `eth0` +- `eth0` interface IP: `10.0.2.2/30` +- 'vti0' interface IP: `10.100.100.2/30` +- `dum0` interface IP: `192.168.1.0/24` (for testing purposes) +- Role: Responder + +```none +# PEER1 +set interfaces dummy dum0 address '192.168.0.1/32' +set interfaces ethernet eth0 address '10.0.1.2/30' +set interfaces vti vti0 address '10.100.100.1/30' +set protocols static route 0.0.0.0/0 next-hop 10.0.1.1 +set protocols static route 192.168.1.0/24 next-hop 10.100.100.2 +set vpn ipsec authentication psk AUTH-PSK id '10.0.1.2' +set vpn ipsec authentication psk AUTH-PSK id '10.0.2.2' +set vpn ipsec authentication psk AUTH-PSK secret 'test' +set vpn ipsec esp-group ESP-GRPOUP lifetime '3600' +set vpn ipsec esp-group ESP-GRPOUP proposal 10 encryption 'aes256' +set vpn ipsec esp-group ESP-GRPOUP proposal 10 hash 'sha1' +set vpn ipsec ike-group IKE-GROUP close-action 'start' +set vpn ipsec ike-group IKE-GROUP dead-peer-detection action 'restart' +set vpn ipsec ike-group IKE-GROUP dead-peer-detection interval '30' +set vpn ipsec ike-group IKE-GROUP key-exchange 'ikev2' +set vpn ipsec ike-group IKE-GROUP lifetime '28800' +set vpn ipsec ike-group IKE-GROUP proposal 10 dh-group '14' +set vpn ipsec ike-group IKE-GROUP proposal 10 encryption 'aes256' +set vpn ipsec ike-group IKE-GROUP proposal 10 hash 'sha1' +set vpn ipsec interface 'eth0' +set vpn ipsec options disable-route-autoinstall +set vpn ipsec site-to-site peer PEER2 authentication local-id '10.0.1.2' +set vpn ipsec site-to-site peer PEER2 authentication mode 'pre-shared-secret' +set vpn ipsec site-to-site peer PEER2 authentication remote-id '10.0.2.2' +set vpn ipsec site-to-site peer PEER2 connection-type 'initiate' +set vpn ipsec site-to-site peer PEER2 default-esp-group 'ESP-GRPOUP' +set vpn ipsec site-to-site peer PEER2 ike-group 'IKE-GROUP' +set vpn ipsec site-to-site peer PEER2 local-address '10.0.1.2' +set vpn ipsec site-to-site peer PEER2 remote-address '10.0.2.2' +set vpn ipsec site-to-site peer PEER2 vti bind 'vti0' + + +# PEER2 +set interfaces dummy dum0 address '192.168.1.1/32' +set interfaces ethernet eth0 address '10.0.2.2/30' +set interfaces vti vti0 address '10.100.100.2/30' +set protocols static route 0.0.0.0/0 next-hop 10.0.2.1 +set protocols static route 192.168.0.0/24 next-hop 10.100.100.1 +set vpn ipsec authentication psk AUTH-PSK id '10.0.1.2' +set vpn ipsec authentication psk AUTH-PSK id '10.0.2.2' +set vpn ipsec authentication psk AUTH-PSK secret 'test' +set vpn ipsec esp-group ESP-GRPOUP lifetime '3600' +set vpn ipsec esp-group ESP-GRPOUP proposal 10 encryption 'aes256' +set vpn ipsec esp-group ESP-GRPOUP proposal 10 hash 'sha1' +set vpn ipsec ike-group IKE-GROUP close-action 'none' +set vpn ipsec ike-group IKE-GROUP dead-peer-detection action 'clear' +set vpn ipsec ike-group IKE-GROUP dead-peer-detection interval '30' +set vpn ipsec ike-group IKE-GROUP key-exchange 'ikev2' +set vpn ipsec ike-group IKE-GROUP lifetime '28800' +set vpn ipsec ike-group IKE-GROUP proposal 10 dh-group '14' +set vpn ipsec ike-group IKE-GROUP proposal 10 encryption 'aes256' +set vpn ipsec ike-group IKE-GROUP proposal 10 hash 'sha1' +set vpn ipsec interface 'eth0' +set vpn ipsec options disable-route-autoinstall +set vpn ipsec site-to-site peer PEER1 authentication local-id '10.0.2.2' +set vpn ipsec site-to-site peer PEER1 authentication mode 'pre-shared-secret' +set vpn ipsec site-to-site peer PEER1 authentication remote-id '10.0.1.2' +set vpn ipsec site-to-site peer PEER1 connection-type 'none' +set vpn ipsec site-to-site peer PEER1 default-esp-group 'ESP-GRPOUP' +set vpn ipsec site-to-site peer PEER1 ike-group 'IKE-GROUP' +set vpn ipsec site-to-site peer PEER1 local-address '10.0.2.2' +set vpn ipsec site-to-site peer PEER1 remote-address '10.0.1.2' +set vpn ipsec site-to-site peer PEER1 vti bind 'vti0' +``` + +Show status of route-based IPsec VPN setup: + +```none +vyos@PEER2:~$ show vpn ike sa +Peer ID / IP Local ID / IP +------------ ------------- +10.0.1.2 10.0.1.2 10.0.2.2 10.0.2.2 + + State IKEVer Encrypt Hash D-H Group NAT-T A-Time L-Time + ----- ------ ------- ---- --------- ----- ------ ------ + up IKEv2 AES_CBC_256 HMAC_SHA1_96 MODP_2048 no 404 27650 + +vyos@PEER2:~$ show vpn ipsec sa +Connection State Uptime Bytes In/Out Packets In/Out Remote address Remote ID Proposal +------------ ------- -------- -------------- ---------------- ---------------- ----------- ---------------------------------- +PEER1-vti up 3m28s 0B/0B 0/0 10.0.1.2 10.0.1.2 AES_CBC_256/HMAC_SHA1_96/MODP_2048 + +vyos@PEER2:~$ show vpn ipsec connections +Connection State Type Remote address Local TS Remote TS Local id Remote id Proposal +------------ ------- ------ ---------------- ---------- ----------- ---------- ----------- ---------------------------------- +PEER1 up IKEv2 10.0.1.2 - - 10.0.2.2 10.0.1.2 AES_CBC/256/HMAC_SHA1_96/MODP_2048 +PEER1-vti up IPsec 10.0.1.2 0.0.0.0/0 0.0.0.0/0 10.0.2.2 10.0.1.2 AES_CBC/256/HMAC_SHA1_96/MODP_2048 + ::/0 ::/0 +``` diff --git a/docs/configuration/vpn/ipsec/troubleshooting_ipsec.md b/docs/configuration/vpn/ipsec/troubleshooting_ipsec.md new file mode 100644 index 00000000..2ca37bc2 --- /dev/null +++ b/docs/configuration/vpn/ipsec/troubleshooting_ipsec.md @@ -0,0 +1,313 @@ +(troubleshooting-ipsec)= + +# Troubleshooting Site-to-Site VPN IPsec + +```{todo} +Convert raw command blocks in this file to cfgcmd/opcmd +directives for command coverage tracking. +``` + + +## Introduction + +This document describes the methodology to monitor and troubleshoot +Site-to-Site VPN IPsec. + +Steps for troubleshooting problems with Site-to-Site VPN IPsec: +: 1. Ping the remote site through the tunnel using the source and + destination IPs included in the policy. + 2. Check connectivity between the routers using the ping command + (if ICMP traffic is allowed). + 3. Check the IKE SAs' statuses. + 4. Check the IPsec SAs' statuses. + 5. Check logs to view debug messages. + +## Checking IKE SA Status + +The next command shows IKE SAs' statuses. + +```none +vyos@vyos:~$ show vpn ike sa + +Peer ID / IP Local ID / IP +------------ ------------- +192.168.1.2 192.168.1.2 192.168.0.1 192.168.0.1 + + State IKEVer Encrypt Hash D-H Group NAT-T A-Time L-Time + ----- ------ ------- ---- --------- ----- ------ ------ + up IKEv2 AES_CBC_128 HMAC_SHA1_96 MODP_2048 no 162 27023 +``` + +This command shows the next information: +: - IKE SA status. + - Selected IKE version. + - Selected Encryption, Hash and Diffie-Hellman Group. + - NAT-T. + - ID and IP of both peers. + - A-Time: established time, L-Time: time for next rekeying. + +## IPsec SA (CHILD SA) Status + +The next commands show IPsec SAs' statuses. + +```none +vyos@vyos:~$ show vpn ipsec sa +Connection State Uptime Bytes In/Out Packets In/Out Remote address Remote ID Proposal +------------- ------- -------- -------------- ---------------- ---------------- ----------- ---------------------------------- +PEER-tunnel-1 up 16m30s 168B/168B 2/2 192.168.1.2 192.168.1.2 AES_CBC_128/HMAC_SHA1_96/MODP_2048 +``` + +```none +vyos@vyos:~$ show vpn ipsec sa detail +PEER: #1, ESTABLISHED, IKEv2, 101275ac719d5a1b_i* 68ea4ec3bed3bf0c_r + local '192.168.0.1' @ 192.168.0.1[4500] + remote '192.168.1.2' @ 192.168.1.2[4500] + AES_CBC-128/HMAC_SHA1_96/PRF_HMAC_SHA1/MODP_2048 + established 4054s ago, rekeying in 23131s + PEER-tunnel-1: #2, reqid 1, INSTALLED, TUNNEL, ESP:AES_CBC-128/HMAC_SHA1_96/MODP_2048 + installed 1065s ago, rekeying in 1998s, expires in 2535s + in c5821882, 168 bytes, 2 packets, 81s ago + out c433406a, 168 bytes, 2 packets, 81s ago + local 10.0.0.0/24 + remote 10.0.1.0/24 +``` + +These commands show the next information: +: - IPsec SA status. + - Uptime and time for the next rekeing. + - Amount of transferred data. + - Remote and local ID and IP. + - Selected Encryption, Hash and Diffie-Hellman Group. + - Mode (tunnel or transport). + - Remote and local prefixes which are use for policy. + +There is a possibility to view the summarized information of SAs' status + +```none +vyos@vyos:~$ show vpn ipsec connections +Connection State Type Remote address Local TS Remote TS Local id Remote id Proposal +------------- ------- ------ ---------------- ----------- ----------- ----------- ----------- ---------------------------------- +PEER up IKEv2 192.168.1.2 - - 192.168.0.1 192.168.1.2 AES_CBC/128/HMAC_SHA1_96/MODP_2048 +PEER-tunnel-1 up IPsec 192.168.1.2 10.0.0.0/24 10.0.1.0/24 192.168.0.1 192.168.1.2 AES_CBC/128/HMAC_SHA1_96/MODP_2048 +``` + + +## Viewing Logs for Debugging + +If IKE SAs or IPsec SAs are down, need to debug IPsec connectivity +using logs `show log ipsec` + +The next example of the successful IPsec connection initialization. + +```none +vyos@vyos:~$ show log ipsec +Jun 20 14:29:47 charon[2428]: 02[NET] <PEER|1> received packet: from 192.168.1.2[500] to 192.168.0.1[500] (472 bytes) +Jun 20 14:29:47 charon[2428]: 02[ENC] <PEER|1> parsed IKE_SA_INIT response 0 [ SA KE No N(NATD_S_IP) N(NATD_D_IP) N(FRAG_SUP) N(HASH_ALG) N(CHDLESS_SUP) N(MULT_AUTH) ] +Jun 20 14:29:47 charon-systemd[2428]: received packet: from 192.168.1.2[500] to 192.168.0.1[500] (472 bytes) +Jun 20 14:29:47 charon[2428]: 02[CFG] <PEER|1> selected proposal: IKE:AES_CBC_128/HMAC_SHA1_96/PRF_HMAC_SHA1/MODP_2048 +Jun 20 14:29:47 charon-systemd[2428]: parsed IKE_SA_INIT response 0 [ SA KE No N(NATD_S_IP) N(NATD_D_IP) N(FRAG_SUP) N(HASH_ALG) N(CHDLESS_SUP) N(MULT_AUTH) ] +Jun 20 14:29:47 charon-systemd[2428]: selected proposal: IKE:AES_CBC_128/HMAC_SHA1_96/PRF_HMAC_SHA1/MODP_2048 +Jun 20 14:29:47 charon[2428]: 02[IKE] <PEER|1> authentication of '192.168.0.1' (myself) with pre-shared key +Jun 20 14:29:47 charon-systemd[2428]: authentication of '192.168.0.1' (myself) with pre-shared key +Jun 20 14:29:47 charon[2428]: 02[IKE] <PEER|1> establishing CHILD_SA PEER-tunnel-1{1} +Jun 20 14:29:47 charon-systemd[2428]: establishing CHILD_SA PEER-tunnel-1{1} +Jun 20 14:29:47 charon[2428]: 02[ENC] <PEER|1> generating IKE_AUTH request 1 [ IDi N(INIT_CONTACT) IDr AUTH SA TSi TSr N(MOBIKE_SUP) N(NO_ADD_ADDR) N(MULT_AUTH) N(EAP_ONLY) N(MSG_ID_SYN_SUP) ] +Jun 20 14:29:47 charon-systemd[2428]: generating IKE_AUTH request 1 [ IDi N(INIT_CONTACT) IDr AUTH SA TSi TSr N(MOBIKE_SUP) N(NO_ADD_ADDR) N(MULT_AUTH) N(EAP_ONLY) N(MSG_ID_SYN_SUP) ] +Jun 20 14:29:47 charon[2428]: 02[NET] <PEER|1> sending packet: from 192.168.0.1[4500] to 192.168.1.2[4500] (268 bytes) +Jun 20 14:29:47 charon-systemd[2428]: sending packet: from 192.168.0.1[4500] to 192.168.1.2[4500] (268 bytes) +Jun 20 14:29:47 charon[2428]: 13[NET] <PEER|1> received packet: from 192.168.1.2[4500] to 192.168.0.1[4500] (220 bytes) +Jun 20 14:29:47 charon[2428]: 13[ENC] <PEER|1> parsed IKE_AUTH response 1 [ IDr AUTH SA TSi TSr N(MOBIKE_SUP) N(NO_ADD_ADDR) ] +Jun 20 14:29:47 charon-systemd[2428]: received packet: from 192.168.1.2[4500] to 192.168.0.1[4500] (220 bytes) +Jun 20 14:29:47 charon[2428]: 13[IKE] <PEER|1> authentication of '192.168.1.2' with pre-shared key successful +Jun 20 14:29:47 charon-systemd[2428]: parsed IKE_AUTH response 1 [ IDr AUTH SA TSi TSr N(MOBIKE_SUP) N(NO_ADD_ADDR) ] +Jun 20 14:29:47 charon[2428]: 13[IKE] <PEER|1> peer supports MOBIKE +Jun 20 14:29:47 charon-systemd[2428]: authentication of '192.168.1.2' with pre-shared key successful +Jun 20 14:29:47 charon[2428]: 13[IKE] <PEER|1> IKE_SA PEER[1] established between 192.168.0.1[192.168.0.1]...192.168.1.2[192.168.1.2] +Jun 20 14:29:47 charon-systemd[2428]: peer supports MOBIKE +Jun 20 14:29:47 charon[2428]: 13[IKE] <PEER|1> scheduling rekeying in 27703s +Jun 20 14:29:47 charon-systemd[2428]: IKE_SA PEER[1] established between 192.168.0.1[192.168.0.1]...192.168.1.2[192.168.1.2] +Jun 20 14:29:47 charon[2428]: 13[IKE] <PEER|1> maximum IKE_SA lifetime 30583s +Jun 20 14:29:47 charon-systemd[2428]: scheduling rekeying in 27703s +Jun 20 14:29:47 charon[2428]: 13[CFG] <PEER|1> selected proposal: ESP:AES_CBC_128/HMAC_SHA1_96/NO_EXT_SEQ +Jun 20 14:29:47 charon-systemd[2428]: maximum IKE_SA lifetime 30583s +Jun 20 14:29:47 charon-systemd[2428]: selected proposal: ESP:AES_CBC_128/HMAC_SHA1_96/NO_EXT_SEQ +Jun 20 14:29:47 charon[2428]: 13[IKE] <PEER|1> CHILD_SA PEER-tunnel-1{1} established with SPIs cb94fb3f_i ca99c8a9_o and TS 10.0.0.0/24 === 10.0.1.0/24 +Jun 20 14:29:47 charon-systemd[2428]: CHILD_SA PEER-tunnel-1{1} established with SPIs cb94fb3f_i ca99c8a9_o and TS 10.0.0.0/24 === 10.0.1.0/24 +``` + + +## Troubleshooting Examples + +### IKE PROPOSAL are Different + +In this situation, IKE SAs can be down or not active. + +```none +vyos@vyos:~$ show vpn ike sa +``` + +The problem is in IKE phase (Phase 1). The next step is checking debug logs. + +Responder Side: + +```none +Jun 23 07:36:33 charon[2440]: 01[CFG] <1> received proposals: IKE:AES_CBC_256/HMAC_SHA1_96/PRF_HMAC_SHA1/MODP_2048 +Jun 23 07:36:33 charon-systemd[2440]: received proposals: IKE:AES_CBC_256/HMAC_SHA1_96/PRF_HMAC_SHA1/MODP_2048 +Jun 23 07:36:33 charon[2440]: 01[CFG] <1> configured proposals: IKE:AES_CBC_128/HMAC_SHA1_96/PRF_HMAC_SHA1/MODP_2048 +Jun 23 07:36:33 charon-systemd[2440]: configured proposals: IKE:AES_CBC_128/HMAC_SHA1_96/PRF_HMAC_SHA1/MODP_2048 +Jun 23 07:36:33 charon[2440]: 01[IKE] <1> received proposals unacceptable +Jun 23 07:36:33 charon-systemd[2440]: received proposals unacceptable +Jun 23 07:36:33 charon[2440]: 01[ENC] <1> generating IKE_SA_INIT response 0 [ N(NO_PROP) ] +``` + +Initiator side: + +```none +Jun 23 07:36:32 charon-systemd[2444]: parsed IKE_SA_INIT response 0 [ N(NO_PROP) ] +Jun 23 07:36:32 charon[2444]: 14[IKE] <PEER|1> received NO_PROPOSAL_CHOSEN notify error +Jun 23 07:36:32 charon-systemd[2444]: received NO_PROPOSAL_CHOSEN notify error +``` + +The notification **NO_PROPOSAL_CHOSEN** means that the proposal mismatch. +On the Responder side there is concrete information where is mismatch. +Encryption **AES_CBC_128** is configured in IKE policy on the responder +but **AES_CBC_256** is configured on the initiator side. + +### PSK Secret Mismatch + +In this situation, IKE SAs can be down or not active. + +```none +vyos@vyos:~$ show vpn ike sa +``` + +The problem is in IKE phase (Phase 1). The next step is checking debug logs. + +Responder: + +```none +Jun 23 08:07:26 charon-systemd[2440]: tried 1 shared key for '192.168.1.2' - '192.168.0.1', but MAC mismatched +Jun 23 08:07:26 charon[2440]: 13[ENC] <PEER|3> generating IKE_AUTH response 1 [ N(AUTH_FAILED) ] +``` + +Initiator side: + +```none +Jun 23 08:07:24 charon[2436]: 12[ENC] <PEER|1> parsed IKE_AUTH response 1 [ N(AUTH_FAILED) ] +Jun 23 08:07:24 charon-systemd[2436]: parsed IKE_AUTH response 1 [ N(AUTH_FAILED) ] +Jun 23 08:07:24 charon[2436]: 12[IKE] <PEER|1> received AUTHENTICATION_FAILED notify error +Jun 23 08:07:24 charon-systemd[2436]: received AUTHENTICATION_FAILED notify error +``` + +The notification **AUTHENTICATION_FAILED** means that the authentication +is failed. There is a reason to check PSK on both side. + +### ESP Proposal Mismatch + +The output of **show** commands shows us that IKE SA is established but +IPSec SA is not. + +```none +vyos@vyos:~$ show vpn ike sa +Peer ID / IP Local ID / IP +------------ ------------- +192.168.1.2 192.168.1.2 192.168.0.1 192.168.0.1 + + State IKEVer Encrypt Hash D-H Group NAT-T A-Time L-Time + ----- ------ ------- ---- --------- ----- ------ ------ + up IKEv2 AES_CBC_128 HMAC_SHA1_96 MODP_2048 no 158 26817 +``` + +```none +vyos@vyos:~$ show vpn ipsec sa +Connection State Uptime Bytes In/Out Packets In/Out Remote address Remote ID Proposal +------------ ------- -------- -------------- ---------------- ---------------- ----------- ---------- +``` + +The next step is checking debug logs. + +Initiator side: + +```none +Jun 23 08:16:10 charon[3789]: 13[NET] <PEER|1> received packet: from 192.168.1.2[500] to 192.168.0.1[500] (472 bytes) +Jun 23 08:16:10 charon[3789]: 13[ENC] <PEER|1> parsed IKE_SA_INIT response 0 [ SA KE No N(NATD_S_IP) N(NATD_D_IP) N(FRAG_SUP) N(HASH_ALG) N(CHDLESS_SUP) N(MULT_AUTH) ] +Jun 23 08:16:10 charon-systemd[3789]: received packet: from 192.168.1.2[500] to 192.168.0.1[500] (472 bytes) +Jun 23 08:16:10 charon[3789]: 13[CFG] <PEER|1> selected proposal: IKE:AES_CBC_128/HMAC_SHA1_96/PRF_HMAC_SHA1/MODP_2048 +Jun 23 08:16:10 charon-systemd[3789]: parsed IKE_SA_INIT response 0 [ SA KE No N(NATD_S_IP) N(NATD_D_IP) N(FRAG_SUP) N(HASH_ALG) N(CHDLESS_SUP) N(MULT_AUTH) ] +Jun 23 08:16:10 charon-systemd[3789]: selected proposal: IKE:AES_CBC_128/HMAC_SHA1_96/PRF_HMAC_SHA1/MODP_2048 +Jun 23 08:16:10 charon[3789]: 13[IKE] <PEER|1> authentication of '192.168.0.1' (myself) with pre-shared key +Jun 23 08:16:10 charon-systemd[3789]: authentication of '192.168.0.1' (myself) with pre-shared key +Jun 23 08:16:10 charon[3789]: 13[IKE] <PEER|1> establishing CHILD_SA PEER-tunnel-1{1} +Jun 23 08:16:10 charon-systemd[3789]: establishing CHILD_SA PEER-tunnel-1{1} +Jun 23 08:16:10 charon[3789]: 13[ENC] <PEER|1> generating IKE_AUTH request 1 [ IDi N(INIT_CONTACT) IDr AUTH SA TSi TSr N(MOBIKE_SUP) N(NO_ADD_ADDR) N(MULT_AUTH) N(EAP_ONLY) N(MSG_ID_SYN_SUP) ] +Jun 23 08:16:10 charon-systemd[3789]: generating IKE_AUTH request 1 [ IDi N(INIT_CONTACT) IDr AUTH SA TSi TSr N(MOBIKE_SUP) N(NO_ADD_ADDR) N(MULT_AUTH) N(EAP_ONLY) N(MSG_ID_SYN_SUP) ] +Jun 23 08:16:10 charon[3789]: 13[NET] <PEER|1> sending packet: from 192.168.0.1[4500] to 192.168.1.2[4500] (268 bytes) +Jun 23 08:16:10 charon-systemd[3789]: sending packet: from 192.168.0.1[4500] to 192.168.1.2[4500] (268 bytes) +Jun 23 08:16:10 charon[3789]: 09[NET] <PEER|1> received packet: from 192.168.1.2[4500] to 192.168.0.1[4500] (140 bytes) +Jun 23 08:16:10 charon-systemd[3789]: received packet: from 192.168.1.2[4500] to 192.168.0.1[4500] (140 bytes) +Jun 23 08:16:10 charon[3789]: 09[ENC] <PEER|1> parsed IKE_AUTH response 1 [ IDr AUTH N(MOBIKE_SUP) N(NO_ADD_ADDR) N(NO_PROP) ] +Jun 23 08:16:10 charon-systemd[3789]: parsed IKE_AUTH response 1 [ IDr AUTH N(MOBIKE_SUP) N(NO_ADD_ADDR) N(NO_PROP) ] +Jun 23 08:16:10 charon[3789]: 09[IKE] <PEER|1> authentication of '192.168.1.2' with pre-shared key successful +Jun 23 08:16:10 charon-systemd[3789]: authentication of '192.168.1.2' with pre-shared key successful +Jun 23 08:16:10 charon[3789]: 09[IKE] <PEER|1> peer supports MOBIKE +Jun 23 08:16:10 charon-systemd[3789]: peer supports MOBIKE +Jun 23 08:16:10 charon[3789]: 09[IKE] <PEER|1> IKE_SA PEER[1] established between 192.168.0.1[192.168.0.1]...192.168.1.2[192.168.1.2] +Jun 23 08:16:10 charon-systemd[3789]: IKE_SA PEER[1] established between 192.168.0.1[192.168.0.1]...192.168.1.2[192.168.1.2] +Jun 23 08:16:10 charon[3789]: 09[IKE] <PEER|1> scheduling rekeying in 26975s +Jun 23 08:16:10 charon-systemd[3789]: scheduling rekeying in 26975s +Jun 23 08:16:10 charon[3789]: 09[IKE] <PEER|1> maximum IKE_SA lifetime 29855s +Jun 23 08:16:10 charon-systemd[3789]: maximum IKE_SA lifetime 29855s +Jun 23 08:16:10 charon[3789]: 09[IKE] <PEER|1> received NO_PROPOSAL_CHOSEN notify, no CHILD_SA built +Jun 23 08:16:10 charon-systemd[3789]: received NO_PROPOSAL_CHOSEN notify, no CHILD_SA built +Jun 23 08:16:10 charon[3789]: 09[IKE] <PEER|1> failed to establish CHILD_SA, keeping IKE_SA +Jun 23 08:16:10 charon-systemd[3789]: failed to establish CHILD_SA, keeping IKE_SA +``` + +There are messages: **NO_PROPOSAL_CHOSEN** and +**failed to establish CHILD_SA** which refers that the problem is in +the IPsec(ESP) proposal mismatch. + +The reason of this problem is showed on the responder side. + +```none +Jun 23 08:16:12 charon[2440]: 01[CFG] <PEER|5> received proposals: ESP:AES_CBC_256/HMAC_SHA1_96/NO_EXT_SEQ +Jun 23 08:16:12 charon-systemd[2440]: received proposals: ESP:AES_CBC_256/HMAC_SHA1_96/NO_EXT_SEQ +Jun 23 08:16:12 charon[2440]: 01[CFG] <PEER|5> configured proposals: ESP:AES_CBC_128/HMAC_SHA1_96/MODP_2048/NO_EXT_SEQ +Jun 23 08:16:12 charon-systemd[2440]: configured proposals: ESP:AES_CBC_128/HMAC_SHA1_96/MODP_2048/NO_EXT_SEQ +Jun 23 08:16:12 charon[2440]: 01[IKE] <PEER|5> no acceptable proposal found +Jun 23 08:16:12 charon-systemd[2440]: no acceptable proposal found +Jun 23 08:16:12 charon[2440]: 01[IKE] <PEER|5> failed to establish CHILD_SA, keeping IKE_SA +``` + +Encryption **AES_CBC_128** is configured in IKE policy on the responder but **AES_CBC_256** +is configured on the initiator side. + +### Prefixes in Policies Mismatch + +As in previous situation, IKE SA is in up state but IPsec SA is not up. +According to logs we can see **TS_UNACCEPTABLE** notification. It means +that prefixes (traffic selectors) mismatch on both sides + +Initiator: + +```none +Jun 23 14:13:17 charon[4996]: 11[IKE] <PEER|1> received TS_UNACCEPTABLE notify, no CHILD_SA built +Jun 23 14:13:17 charon-systemd[4996]: maximum IKE_SA lifetime 29437s +Jun 23 14:13:17 charon[4996]: 11[IKE] <PEER|1> failed to establish CHILD_SA, keeping IKE_SA +Jun 23 14:13:17 charon-systemd[4996]: received TS_UNACCEPTABLE notify, no CHILD_SA built +Jun 23 14:13:17 charon-systemd[4996]: failed to establish CHILD_SA, keeping IKE_SA +``` + +The reason of this problem is showed on the responder side. + +```none +Jun 23 14:13:19 charon[2440]: 01[IKE] <PEER|7> traffic selectors 10.0.2.0/24 === 10.0.0.0/24 unacceptable +Jun 23 14:13:19 charon-systemd[2440]: traffic selectors 10.0.2.0/24 === 10.0.0.0/24 unacceptable +Jun 23 14:13:19 charon[2440]: 01[IKE] <PEER|7> failed to establish CHILD_SA, keeping IKE_SA +Jun 23 14:13:19 charon-systemd[2440]: failed to establish CHILD_SA, keeping IKE_SA +Jun 23 14:13:19 charon[2440]: 01[ENC] <PEER|7> generating IKE_AUTH response 1 [ IDr AUTH N(MOBIKE_SUP) N(NO_ADD_ADDR) N(TS_UNACCEPT) ] +Jun 23 14:13:19 charon-systemd[2440]: generating IKE_AUTH response 1 [ IDr AUTH N(MOBIKE_SUP) N(NO_ADD_ADDR) N(TS_UNACCEPT) ] +``` + +Traffic selectors **10.0.2.0/24 === 10.0.0.0/24** are unacceptable on the +responder side. diff --git a/docs/configuration/vpn/l2tp.md b/docs/configuration/vpn/l2tp.md new file mode 100644 index 00000000..3b131b98 --- /dev/null +++ b/docs/configuration/vpn/l2tp.md @@ -0,0 +1,624 @@ +(l2tp)= + +# L2TP + +VyOS utilizes [accel-ppp] to provide L2TP server functionality. It can be used +with local authentication or a connected RADIUS server. + +## Configuring L2TP Server + +```none +set vpn l2tp remote-access authentication mode local +set vpn l2tp remote-access authentication local-users username test password 'test' +set vpn l2tp remote-access client-ip-pool L2TP-POOL range 192.168.255.2-192.168.255.254 +set vpn l2tp remote-access default-pool 'L2TP-POOL' +set vpn l2tp remote-access outside-address 192.0.2.2 +set vpn l2tp remote-access gateway-address 192.168.255.1 +``` + +```{cfgcmd} set vpn l2tp remote-access authentication mode \<local | radius\> + +Set authentication backend. The configured authentication backend is used +for all queries. + +* **radius**: All authentication queries are handled by a configured RADIUS + server. +* **local**: All authentication queries are handled locally. +``` + + +```{cfgcmd} set vpn l2tp remote-access authentication local-users username \<user\> password \<pass\> + +Create `<user>` for local authentication on this system. The users password +will be set to `<pass>`. +``` + + +```{cfgcmd} set vpn l2tp remote-access client-ip-pool \<POOL-NAME\> range \<x.x.x.x-x.x.x.x | x.x.x.x/x\> + +Use this command to define the first IP address of a pool of +addresses to be given to l2tp clients. If notation ``x.x.x.x-x.x.x.x``, +it must be within a /24 subnet. If notation ``x.x.x.x/x`` is +used there is possibility to set host/netmask. +``` + + +```{cfgcmd} set vpn l2tp remote-access default-pool \<POOL-NAME\> + +Use this command to define default address pool name. +``` + + +```{cfgcmd} set vpn l2tp remote-access gateway-address \<gateway\> + +Specifies single `<gateway>` IP address to be used as local address of PPP +interfaces. +``` + + +## Configuring IPsec + +```none +set vpn ipsec interface eth0 +set vpn l2tp remote-access ipsec-settings authentication mode pre-shared-secret +set vpn l2tp remote-access ipsec-settings authentication pre-shared-secret secret +``` + + +```{cfgcmd} set vpn ipsec interface \<INTERFACE\> + +Use this command to define IPsec interface. +``` + + +```{cfgcmd} set vpn l2tp remote-access ipsec-settings authentication mode \<pre-shared-secret | x509\> + +Set mode for IPsec authentication between VyOS and L2TP clients. +``` + + +```{cfgcmd} set vpn l2tp remote-access ipsec-settings authentication pre-shared-secret \<secret\> + +Set predefined shared secret phrase. +``` + +If a local firewall policy is in place on your external interface you will need +to allow the ports below: +- UDP port 500 (IKE) +- IP protocol number 50 (ESP) +- UDP port 1701 for IPsec + +As well as the below to allow NAT-traversal (when NAT is detected by the +VPN client, ESP is encapsulated in UDP for NAT-traversal): + +- UDP port 4500 (NAT-T) + +Example: + +```none +set firewall ipv4 name OUTSIDE-LOCAL rule 40 action 'accept' +set firewall ipv4 name OUTSIDE-LOCAL rule 40 protocol 'esp' +set firewall ipv4 name OUTSIDE-LOCAL rule 41 action 'accept' +set firewall ipv4 name OUTSIDE-LOCAL rule 41 destination port '500' +set firewall ipv4 name OUTSIDE-LOCAL rule 41 protocol 'udp' +set firewall ipv4 name OUTSIDE-LOCAL rule 42 action 'accept' +set firewall ipv4 name OUTSIDE-LOCAL rule 42 destination port '4500' +set firewall ipv4 name OUTSIDE-LOCAL rule 42 protocol 'udp' +set firewall ipv4 name OUTSIDE-LOCAL rule 43 action 'accept' +set firewall ipv4 name OUTSIDE-LOCAL rule 43 destination port '1701' +set firewall ipv4 name OUTSIDE-LOCAL rule 43 ipsec 'match-ipsec' +set firewall ipv4 name OUTSIDE-LOCAL rule 43 protocol 'udp' +``` + +To allow VPN-clients access via your external address, a NAT rule is required: + +```none +set nat source rule 110 outbound-interface name 'eth0' +set nat source rule 110 source address '192.168.255.0/24' +set nat source rule 110 translation address masquerade +``` + + +## Configuring RADIUS authentication + +To enable RADIUS based authentication, the authentication mode needs to be +changed within the configuration. Previous settings like the local users, still +exists within the configuration, however they are not used if the mode has been +changed from local to radius. Once changed back to local, it will use all local +accounts again. + +```none +set vpn l2tp remote-access authentication mode radius +``` + +```{cfgcmd} set vpn l2tp remote-access authentication radius server \<server\> key \<secret\> + +Configure RADIUS `<server>` and its required shared `<secret>` for +communicating with the RADIUS server. +``` + +Since the RADIUS server would be a single point of failure, multiple RADIUS +servers can be setup and will be used subsequentially. +For example: + +```none +set vpn l2tp remote-access authentication radius server 10.0.0.1 key 'foo' +set vpn l2tp remote-access authentication radius server 10.0.0.2 key 'foo' +``` + +:::{note} +Some RADIUS severs use an access control list which allows or denies +queries, make sure to add your VyOS router to the allowed client list. +::: + +### RADIUS source address + +If you are using OSPF as your IGP, use the interface connected closest to the +RADIUS server. You can bind all outgoing RADIUS requests to a single source IP +e.g. the loopback interface. + +```{cfgcmd} set vpn l2tp remote-access authentication radius source-address \<address\> + +Source IPv4 address used in all RADIUS server queries. +``` + +:::{note} +The `source-address` must be configured to that of an interface. +Best practice would be a loopback or dummy interface. +::: + +### RADIUS advanced options + +```{cfgcmd} set vpn l2tp remote-access authentication radius server \<server\> port \<port\> + +Configure RADIUS `<server>` and its required port for authentication requests. +``` + +```{cfgcmd} set vpn l2tp remote-access authentication radius server \<server\> fail-time \<time\> + +Mark RADIUS server as offline for this given `<time>` in seconds. +``` + +```{cfgcmd} set vpn l2tp remote-access authentication radius server \<server\> disable + +Temporary disable this RADIUS server. +``` + +```{cfgcmd} set vpn l2tp remote-access authentication radius acct-timeout \<timeout\> + +Timeout to wait reply for Interim-Update packets. (default 3 seconds) +``` + +```{cfgcmd} set vpn l2tp remote-access authentication radius dynamic-author server \<address\> + +Specifies IP address for Dynamic Authorization Extension server (DM/CoA). +This IP must exist on any VyOS interface or it can be ``0.0.0.0``. +``` + +```{cfgcmd} set vpn l2tp remote-access authentication radius dynamic-author port \<port\> + +UDP port for Dynamic Authorization Extension server (DM/CoA) +``` + +```{cfgcmd} set vpn l2tp remote-access authentication radius dynamic-author key \<secret\> + +Secret for Dynamic Authorization Extension server (DM/CoA) +``` + +```{cfgcmd} set vpn l2tp remote-access authentication radius max-try \<number\> + +Maximum number of tries to send Access-Request/Accounting-Request queries +``` + +```{cfgcmd} set vpn l2tp remote-access authentication radius timeout \<timeout\> + +Timeout to wait response from server (seconds) +``` + +```{cfgcmd} set vpn l2tp remote-access authentication radius nas-identifier \<identifier\> + +Value to send to RADIUS server in NAS-Identifier attribute and to be matched +in DM/CoA requests. +``` + +```{cfgcmd} set vpn l2tp remote-access authentication radius nas-ip-address \<address\> + +Value to send to RADIUS server in NAS-IP-Address attribute and to be matched +in DM/CoA requests. Also DM/CoA server will bind to that address. +``` + +```{cfgcmd} set vpn l2tp remote-access authentication radius source-address \<address\> + +Source IPv4 address used in all RADIUS server queries. +``` + +```{cfgcmd} set vpn l2tp remote-access authentication radius rate-limit attribute \<attribute\> + +Specifies which RADIUS server attribute contains the rate limit information. +The default attribute is `Filter-Id`. +``` + +:::{note} +If you set a custom RADIUS attribute you must define it on both +dictionaries on the RADIUS server and client. +::: + +```{cfgcmd} set vpn l2tp remote-access authentication radius rate-limit enable + +Enables bandwidth shaping via RADIUS. +``` + +```{cfgcmd} set vpn l2tp remote-access authentication radius rate-limit vendor + +Specifies the vendor dictionary. This dictionary needs to be present in +/usr/share/accel-ppp/radius. +``` + +Received RADIUS attributes have a higher priority than parameters defined within +the CLI configuration, refer to the explanation below. + +### Allocation clients ip addresses by RADIUS + +If the RADIUS server sends the attribute `Framed-IP-Address` then this IP +address will be allocated to the client and the option `default-pool` within +the CLI config will be ignored. + +If the RADIUS server sends the attribute `Framed-Pool`, then the IP address +will be allocated from a predefined IP pool whose name equals the attribute +value. + +If the RADIUS server sends the attribute `Stateful-IPv6-Address-Pool`, the +IPv6 address will be allocated from a predefined IPv6 pool `prefix` whose +name equals the attribute value. + +If the RADIUS server sends the attribute `Delegated-IPv6-Prefix-Pool`, an +IPv6 delegation prefix will be allocated from a predefined IPv6 pool +`delegate` whose name equals the attribute value. + +:::{note} +`Stateful-IPv6-Address-Pool` and `Delegated-IPv6-Prefix-Pool` are defined in +RFC6911. If they are not defined in your RADIUS server, add new [dictionary]. +::: + +The client's interface can be put into a VRF context via a RADIUS Access-Accept +packet, or changed via RADIUS CoA. `Accel-VRF-Name` is used for these +purposes. This is a custom [ACCEL-PPP attribute]. Define it in your RADIUS +server. + +### Renaming clients interfaces by RADIUS + +If the RADIUS server uses the attribute `NAS-Port-Id`, ppp tunnels will be +renamed. + +:::{note} +The value of the attribute `NAS-Port-Id` must be less than 16 +characters, otherwise the interface won't be renamed. +::: + +## Configuring LNS (L2TP Network Server) + +LNS are often used to connect to a LAC (L2TP Access Concentrator). + +```{cfgcmd} set vpn l2tp remote-access lns host-name \<hostname\> + +Sent to the client (LAC) in the Host-Name attribute +``` + +```{cfgcmd} set vpn l2tp remote-access lns shared-secret \<secret\> + +Tunnel password used to authenticate the client (LAC) +``` + +To explain the usage of LNS follow our blueprint {ref}`examples-lac-lns`. + +## IPv6 + +```{cfgcmd} set vpn l2tp remote-access ppp-options ipv6 \<require | prefer | allow | deny\> + +Specifies IPv6 negotiation preference. +* **require** - Require IPv6 negotiation +* **prefer** - Ask client for IPv6 negotiation, do not fail if it rejects +* **allow** - Negotiate IPv6 only if client requests +* **deny** - Do not negotiate IPv6 (default value) +``` + +```{cfgcmd} set vpn l2tp remote-access client-ipv6-pool \<IPv6-POOL-NAME\> prefix \<address\> mask \<number-of-bits\> + +Use this command to set the IPv6 address pool from which an l2tp client will +get an IPv6 prefix of your defined length (mask) to terminate the l2tp +endpoint at their side. The mask length can be set between 48 and 128 bits +long, the default value is 64. +``` + +```{cfgcmd} set vpn l2tp remote-access client-ipv6-pool \<IPv6-POOL-NAME\> delegate \<address\> delegation-prefix \<number-of-bits\> + +Use this command to configure DHCPv6 Prefix Delegation (RFC3633) on l2tp. +You will have to set your IPv6 pool and the length of the delegation +prefix. From the defined IPv6 pool you will be handing out networks of the +defined length (delegation-prefix). The length of the delegation prefix can +be between 32 and 64 bits long. +``` + +```{cfgcmd} set vpn l2tp remote-access default-ipv6-pool \<IPv6-POOL-NAME\> + +Use this command to define default IPv6 address pool name. +``` + +```none +set vpn l2tp remote-access ppp-options ipv6 allow +set vpn l2tp remote-access client-ipv6-pool IPv6-POOL delegate '2001:db8:8003::/48' delegation-prefix '56' +set vpn l2tp remote-access client-ipv6-pool IPv6-POOL prefix '2001:db8:8002::/48' mask '64' +set vpn l2tp remote-access default-ipv6-pool IPv6-POOL +``` + + +### IPv6 Advanced Options + +```{cfgcmd} set vpn l2tp remote-access ppp-options ipv6-accept-peer-interface-id + +Accept peer interface identifier. By default this is not defined. +``` + +```{cfgcmd} set vpn l2tp remote-access ppp-options ipv6-interface-id \<random | x:x:x:x\> + +Specifies if a fixed or random interface identifier is used for IPv6. The +default is fixed. +* **random** - Random interface identifier for IPv6 +* **x:x:x:x** - Specify interface identifier for IPv6 +``` + +```{cfgcmd} set vpn l2tp remote-access ppp-options ipv6-interface-id \<random | x:x:x:x\> + +Specifies the peer interface identifier for IPv6. The default is fixed. +* **random** - Random interface identifier for IPv6 +* **x:x:x:x** - Specify interface identifier for IPv6 +* **ipv4-addr** - Calculate interface identifier from IPv4 address. +* **calling-sid** - Calculate interface identifier from calling-station-id. +``` + + +## Scripting + +```{cfgcmd} set vpn l2tp remote-access extended-scripts on-change \<path_to_script\> + +Script to run when the session interface is changed by RADIUS CoA handling +``` + +```{cfgcmd} set vpn l2tp remote-access extended-scripts on-down \<path_to_script\> + +Script to run when the session interface is about to terminate +``` + +```{cfgcmd} set vpn l2tp remote-access extended-scripts on-pre-up \<path_to_script\> + +Script to run before the session interface comes up +``` + +```{cfgcmd} set vpn l2tp remote-access extended-scripts on-up \<path_to_script\> + +Script to run when the session interface is completely configured and started +``` + + +## Advanced Options + +### Authentication Advanced Options + +```{cfgcmd} set vpn l2tp remote-access authentication local-users username \<user\> disable + +Disable `<user>` account. +``` + +```{cfgcmd} set vpn l2tp remote-access authentication local-users username \<user\> static-ip \<address\> + +Assign a static IP address to `<user>` account. +``` + +```{cfgcmd} set vpn l2tp remote-access authentication local-users username \<user\> rate-limit download \<bandwidth\> + +Rate limit the download bandwidth for `<user>` to `<bandwidth>` kbit/s. +``` + +```{cfgcmd} set vpn l2tp remote-access authentication local-users username \<user\> rate-limit upload \<bandwidth\> + +Rate limit the upload bandwidth for `<user>` to `<bandwidth>` kbit/s +``` + +```{cfgcmd} set vpn l2tp remote-access authentication protocols \<pap | chap | mschap | mschap-v2\> + +Require the peer to authenticate itself using one of the following protocols: +pap, chap, mschap, mschap-v2. +``` + + +### Client IP Pool Advanced Options + +```{cfgcmd} set vpn l2tp remote-access client-ip-pool \<POOL-NAME\> next-pool \<NEXT-POOL-NAME\> + +Use this command to define the next address pool name. +``` + + +### PPP Advanced Options + +```{cfgcmd} set vpn l2tp remote-access ppp-options disable-ccp + +Disable Compression Control Protocol (CCP). +CCP is enabled by default. +``` + +```{cfgcmd} set vpn l2tp remote-access ppp-options interface-cache \<number\> + +Specifies number of interfaces to cache. This prevents interfaces from being +removed once the corresponding session is destroyed. Instead, interfaces are +cached for later use in new sessions. This should reduce the kernel-level +interface creation/deletion rate. +Default value is **0**. +``` + +```{cfgcmd} set vpn l2tp remote-access ppp-options ipv4 \<require | prefer | allow | deny\> + +Specifies IPv4 negotiation preference. +* **require** - Require IPv4 negotiation +* **prefer** - Ask client for IPv4 negotiation, do not fail if it rejects +* **allow** - Negotiate IPv4 only if client requests (Default value) +* **deny** - Do not negotiate IPv4 +``` + +```{cfgcmd} set vpn l2tp remote-access ppp-options lcp-echo-failure \<number\> + +Defines the maximum `<number>` of unanswered echo requests. Upon reaching the +value `<number>`, the session will be reset. Default value is **3**. +``` + +```{cfgcmd} set vpn l2tp remote-access ppp-options lcp-echo-interval \<interval\> + +If this option is specified and is greater than 0, then the PPP module will +send LCP echo requests every `<interval>` seconds. +Default value is **30**. +``` + +```{cfgcmd} set vpn l2tp remote-access ppp-options lcp-echo-timeout + +Specifies timeout in seconds to wait for any peer activity. If this option is +specified it turns on adaptive lcp echo functionality and "lcp-echo-failure" +is not used. Default value is **0**. +``` + +```{cfgcmd} set vpn l2tp remote-access ppp-options min-mtu \<number\> + +Defines the minimum acceptable MTU. If a client tries to negotiate an MTU +lower than this it will be NAKed, and disconnected if it rejects a greater +MTU. +Default value is **100**. +``` + +```{cfgcmd} set vpn l2tp remote-access ppp-options mppe \<require | prefer | deny\> + +Specifies {abbr}`MPPE (Microsoft Point-to-Point Encryption)` negotiation +preference. +* **require** - ask client for mppe, if it rejects drop connection +* **prefer** - ask client for mppe, if it rejects don't fail. (Default value) +* **deny** - deny mppe + +Default behavior - don't ask the client for mppe, but allow it if the client +wants. Please note that RADIUS may override this option with the +MS-MPPE-Encryption-Policy attribute. +``` + +```{cfgcmd} set vpn l2tp remote-access ppp-options mru \<number\> + +Defines preferred MRU. By default is not defined. +``` + + +### Global Advanced options + +```{cfgcmd} set vpn l2tp remote-access description \<description\> + +Set description. +``` + +```{cfgcmd} set vpn l2tp remote-access limits burst \<value\> + +Burst count +``` + +```{cfgcmd} set vpn l2tp remote-access limits connection-limit \<value\> + +Maximum accepted connection rate (e.g. 1/min, 60/sec) +``` + +```{cfgcmd} set vpn l2tp remote-access limits timeout \<value\> + +Timeout in seconds +``` + +```{cfgcmd} set vpn l2tp remote-access mtu + +Maximum Transmission Unit (MTU) (default: **1436**) +``` + +```{cfgcmd} set vpn l2tp remote-access max-concurrent-sessions + +Maximum number of concurrent session start attempts +``` + +```{cfgcmd} set vpn l2tp remote-access name-server \<address\> + +Connected clients should use `<address>` as their DNS server. This command +accepts both IPv4 and IPv6 addresses. Up to two nameservers can be configured +for IPv4, up to three for IPv6. +``` + +```{cfgcmd} set vpn l2tp remote-access shaper fwmark \<1-2147483647\> + +Match firewall mark value +``` + +```{cfgcmd} set vpn l2tp remote-access snmp master-agent + +Enable SNMP +``` + +```{cfgcmd} set vpn l2tp remote-access wins-server \<address\> + +Windows Internet Name Service (WINS) servers propagated to client +``` + + +## Monitoring + +```none +vyos@vyos:~$ show l2tp-server sessions + ifname | username | ip | ip6 | ip6-dp | calling-sid | rate-limit | state | uptime | rx-bytes | tx-bytes +--------+----------+---------------+-----+--------+-------------+------------+--------+----------+----------+---------- + l2tp0 | test | 192.168.255.3 | | | 192.168.0.36 | | active | 02:01:47 | 7.7 KiB | 1.2 KiB +``` + +```none +vyos@vyos:~$ show l2tp-server statistics + uptime: 0.02:49:49 +cpu: 0% +mem(rss/virt): 5920/100892 kB +core: + mempool_allocated: 133202 + mempool_available: 131770 + thread_count: 1 + thread_active: 1 + context_count: 5 + context_sleeping: 0 + context_pending: 0 + md_handler_count: 3 + md_handler_pending: 0 + timer_count: 0 + timer_pending: 0 +sessions: + starting: 0 + active: 0 + finishing: 0 +l2tp: + tunnels: + starting: 0 + active: 0 + finishing: 0 + sessions (control channels): + starting: 0 + active: 0 + finishing: 0 + sessions (data channels): + starting: 0 + active: 0 + finishing: 0 +``` + +[accel-ppp]: https://accel-ppp.org/ +[accel-ppp attribute]: https://github.com/accel-ppp/accel-ppp/blob/master/accel-pppd/radius/dict/dictionary.accel +[cloudflare]: https://blog.cloudflare.com/announcing-1111 +[dictionary]: https://github.com/accel-ppp/accel-ppp/blob/master/accel-pppd/radius/dict/dictionary.rfc6911 +[freeradius]: https://freeradius.org +[google public dns]: https://developers.google.com/speed/public-dns +[network policy server]: <https://en.wikipedia.org/wiki/Network_Policy_Server> +[opennic]: https://www.opennic.org/ +[quad9]: https://quad9.net +[radius]: https://en.wikipedia.org/wiki/RADIUS diff --git a/docs/configuration/vpn/openconnect.md b/docs/configuration/vpn/openconnect.md new file mode 100644 index 00000000..af5dcf7b --- /dev/null +++ b/docs/configuration/vpn/openconnect.md @@ -0,0 +1,330 @@ +(vpn-openconnect)= + +# OpenConnect + +```{todo} +Convert raw command blocks in this file to cfgcmd/opcmd +directives for command coverage tracking. +``` + +OpenConnect-compatible server feature has been available since Equuleus (1.3). +Openconnect VPN supports SSL connection and offers full network access. SSL VPN +network extension connects the end-user system to the corporate network with +access controls based only on network layer information, such as destination IP +address and port number. So, it provides safe communication for all types of +device traffic across public networks and private networks, also encrypts the +traffic with SSL protocol. + +The remote user will use the openconnect client to connect to the router and +will receive an IP address from a VPN pool, allowing full access to the +network. + +## Configuration + +### SSL Certificates + +We need to generate the certificate which authenticates users who attempt to +access the network resource through the SSL VPN tunnels. The following commands +will create a self signed certificates and will be stored in configuration: + +```none +run generate pki ca install <CA name> +run generate pki certificate sign <CA name> install <Server name> +``` + +We can also create the certificates using Certbot which is an easy-to-use +client that fetches a certificate from Let's Encrypt an open certificate +authority launched by the EFF, Mozilla, and others and deploys it to a web +server. + +```none +sudo certbot certonly --standalone --preferred-challenges http -d <domain name> +``` + + +### Server Configuration + +```none +set vpn openconnect authentication local-users username <user> password <pass> +set vpn openconnect authentication mode <local password|radius|certificate> +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> +set vpn openconnect ssl certificate <pki-cert-name> +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, +without a password, can be used. +To do this, an OTP configuration must be added to the configuration above: + +```none +set vpn openconnect authentication mode local <password-otp|otp> +set vpn openconnect authentication local-users username <user> otp <key> +set vpn openconnect authentication local-users username <user> interval <interval (optional)> +set vpn openconnect authentication local-users username <user> otp-length <otp-length (optional)> +set vpn openconnect authentication local-users username <user> token-type <token-type (optional)> +``` + +For generating an OTP key in VyOS, you can use the CLI command +(operational mode): + +```none +generate openconnect username <user> otp-key hotp-time +``` + + +### User Certificate Authentication + +You can configure users to be authenticated by certificate by setting +the authentication mode to certificate, and defining what field (by OID) +in the certificate will be used to identify the username. Two pre-defined + +shortcuts for Common Name (OID 2.5.4.3) and User ID +(OID 0.9.2342.19200300.100.1.1) have been provided as cn or uid. + +Otherwise a specific OID value must be provided. + +The user's certificate must be signed by the certificate authority +defined in the configuration for it to be validated for authentication. + +```none +set vpn openconnect authentication mode certificate +set vpn openconnect authentication mode certificate user-identifier-field cn +set vpn openconnect ssl ca-certificate <cert> +``` + + +## Verification + +```none +vyos@vyos:~$ sh openconnect-server sessions +interface username ip remote IP RX TX state uptime +----------- ---------- ------------- ----------- ------- --------- --------- -------- +sslvpn0 tst 172.20.20.198 192.168.6.1 0 bytes 152 bytes connected 3s +``` + +:::{note} +It is compatible with Cisco (R) AnyConnect (R) clients. +::: + +## Example + +### SSL Certificates generation + +Follow the instructions to generate CA cert (in configuration mode): + +```none +vyos@vyos# run generate pki ca install ca-ocserv +Enter private key type: [rsa, dsa, ec] (Default: rsa) +Enter private key bits: (Default: 2048) +Enter country code: (Default: GB) US +Enter state: (Default: Some-State) Delaware +Enter locality: (Default: Some-City) Mycity +Enter organization name: (Default: VyOS) MyORG +Enter common name: (Default: vyos.io) oc-ca +Enter how many days certificate will be valid: (Default: 1825) 3650 +Note: If you plan to use the generated key on this router, do not encrypt the private key. +Do you want to encrypt the private key with a passphrase? [y/N] N +2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. +[edit] +``` + +Follow the instructions to generate server cert (in configuration mode): + +```none +vyos@vyos# run generate pki certificate sign ca-ocserv install srv-ocserv +Do you already have a certificate request? [y/N] N +Enter private key type: [rsa, dsa, ec] (Default: rsa) +Enter private key bits: (Default: 2048) +Enter country code: (Default: GB) US +Enter state: (Default: Some-State) Delaware +Enter locality: (Default: Some-City) Mycity +Enter organization name: (Default: VyOS) MyORG +Enter common name: (Default: vyos.io) oc-srv +Do you want to configure Subject Alternative Names? [y/N] N +Enter how many days certificate will be valid: (Default: 365) 1830 +Enter certificate type: (client, server) (Default: server) +Note: If you plan to use the generated key on this router, do not encrypt the private key. +Do you want to encrypt the private key with a passphrase? [y/N] N +2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. +[edit] +``` + +Each of the install commands should be applied to the configuration and committed +before using under the openconnect configuration: + +```none +vyos@vyos# commit +[edit] +vyos@vyos# save +Saving configuration to '/config/config.boot'... +Done +[edit] +``` + + +### Openconnect Configuration + +Simple setup with one user added and password authentication: + +```none +set vpn openconnect authentication local-users username tst password 'OC_bad_Secret' +set vpn openconnect authentication mode local password +set vpn openconnect network-settings client-ip-settings subnet '172.20.20.0/24' +set vpn openconnect network-settings name-server '10.1.1.1' +set vpn openconnect network-settings name-server '10.1.1.2' +set vpn openconnect ssl ca-certificate 'ca-ocserv' +set vpn openconnect ssl certificate 'srv-ocserv' +``` + +To enable the HTTP security headers in the configuration file, use the command: + +```none +set vpn openconnect http-security-headers +``` + + +### Adding a 2FA with an OTP-key + +First the OTP keys must be generated and sent to the user and to the +configuration: + +```none +vyos@vyos:~$ generate openconnect username tst otp-key hotp-time +# You can share it with the user, he just needs to scan the QR in his OTP app +# username: tst +# OTP KEY: 5PA4SGYTQSGOBO3H3EQSSNCUNZAYAPH2 +# OTP URL: otpauth://totp/tst@vyos?secret=5PA4SGYTQSGOBO3H3EQSSNCUNZAYAPH2&digits=6&period=30 +█████████████████████████████████████████ +█████████████████████████████████████████ +████ ▄▄▄▄▄ █▀ ██▄▀ ▄█▄▀▀▄▄▄▄██ ▄▄▄▄▄ ████ +████ █ █ █▀ █▄▄▀▀▀▄█ ▄▄▀▄ █ █ █ ████ +████ █▄▄▄█ █▀█▀▄▄▀ ▄▀ █▀ ▀▄██ █▄▄▄█ ████ +████▄▄▄▄▄▄▄█▄█▄▀ ▀▄█ ▀ ▀ ▀ █▄█▄▄▄▄▄▄▄████ +████ ▄▄▄▀▄▄ ▄███▀▄▀█▄██▀ ▀▄ ▀▄█ ▀ ▀████ +████ ▀▀ ▀ ▄█▄ ▀ ▀▄ ▄█▀ ▄█ ▄▀▀▄██ █████ +████▄ █▄▀▀▄█▀ ▀█▄█▄▄▄▄ ▄▀█▀▀█ ▀ ▄ ▀█▀████ +█████ ▀█▀▄▄ █ ▀▄▄ ▄█▄ ▀█▀▀ █▀ ▄█████ +████▀██▀█▄▄ ▀▀▀▀█▄▀ ▀█▄▄▀▀▀ ▀ ▀█▄██▀▀████ +████▄ ▄ ▄▀▄██▀█ ▄ ▀▄██ ▄▄ ▀▀▄█▄██ ▄█████ +████▀▀ ▄▀ ▄ ▀█▀█▀█ █▀█▄▄▀█▀█▄██▄▄█ ▀████ +████ █ ▀█▄▄█▄ ▀ ▄▄▀▀ ▀ █▄█▀████ █▀ ▀████ +████▄██▄██▄█▀ ▄▀ ▄▄▀▄ ▄▀█ ▄ ▄▄▄ ▀█▄ ████ +████ ▄▄▄▄▄ █▄ ▀█▄█ ▄ ▀ ▄ ▄ █▄█ ▄▀▄█████ +████ █ █ █ ▀▄██▄▄▀█▄▀▄██▄▀ ▄ ▀██▀████ +████ █▄▄▄█ █ ██▀▄▄ ▀▄▄▀█▀ ▀█ ▄▀█ ▀██████ +████▄▄▄▄▄▄▄█▄███▄███▄█▄▄▄▄█▄▄█▄██▄█▄█████ +█████████████████████████████████████████ +█████████████████████████████████████████ +# To add this OTP key to configuration, run the following commands: +set vpn openconnect authentication local-users username tst otp key 'ebc1c91b13848ce0bb67d9212934546e41803cfa' +``` + +Next it is necessary to configure 2FA for OpenConnect: + +```none +set vpn openconnect authentication mode local password-otp +set vpn openconnect authentication local-users username tst otp key 'ebc1c91b13848ce0bb67d9212934546e41803cfa' +``` + +Now when connecting the user will first be asked for the password +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: + +```none +show openconnect-server user <username> otp <full|key-b32|key-hex|qrcode|uri> +``` + + +### Identity Based Configuration + +OpenConnect supports a subset of it's configuration options to be applied on a +per user/group basis, for configuration purposes we refer to this functionality +as "Identity based config". The following [OpenConnect Server Manual](https://ocserv.gitlab.io/www/manual.html#:~:text=Configuration%20files%20that%20will%20be%20applied%20per%20user%20connection%20or%0A%23%20per%20group) +outlines the set of configuration options that are allowed. This can be +leveraged to apply different sets of configs to different users or groups of +users. + +```none +sudo mkdir -p /config/auth/ocserv/config-per-user +sudo touch /config/auth/ocserv/default-user.conf + +set vpn openconnect authentication identity-based-config mode user +set vpn openconnect authentication identity-based-config directory /config/auth/ocserv/config-per-user +set vpn openconnect authentication identity-based-config default-config /config/auth/ocserv/default-user.conf +``` + +:::{warning} +The above directory and default-config must be a child directory +of /config/auth, since files outside this directory are not persisted after an +image upgrade. +::: + +Once you commit the above changes you can create a config file in the +/config/auth/ocserv/config-per-user directory that matches a username of a +user you have created e.g. "tst". Now when logging in with the "tst" user the +config options you set in this file will be loaded. + +Be sure to set a sane default config in the default config file, this will be +loaded in the case that a user is authenticated and no file is found in the +configured directory matching the users username/group. + +```none +sudo nano /config/auth/ocserv/config-per-user/tst +``` + +The same configuration options apply when Identity based config is configured +in group mode except that group mode can only be used with RADIUS +authentication. + +:::{warning} +OpenConnect server matches the filename in a case sensitive +manner, make sure the username/group name you configure matches the +filename exactly. +::: + +### 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: + +```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: + +```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/pptp.md b/docs/configuration/vpn/pptp.md new file mode 100644 index 00000000..34f883cc --- /dev/null +++ b/docs/configuration/vpn/pptp.md @@ -0,0 +1,594 @@ +(pptp)= + +# PPTP-Server + +The Point-to-Point Tunneling Protocol (PPTP) has been implemented in VyOS only +for backwards compatibility. PPTP has many well known security issues and you +should use one of the many other new VPN implementations. + +## Configuring PPTP Server + +```none +set vpn pptp remote-access authentication mode local +set vpn pptp remote-access authentication local-users username test password 'test' +set vpn pptp remote-access client-ip-pool PPTP-POOL range 192.168.255.2-192.168.255.254 +set vpn pptp remote-access default-pool 'PPTP-POOL' +set vpn pptp remote-access outside-address 192.0.2.2 +set vpn pptp remote-access gateway-address 192.168.255.1 +``` + +```{cfgcmd} set vpn pptp remote-access authentication mode \<local | radius\> + +Set authentication backend. The configured authentication backend is used +for all queries. +* **radius**: All authentication queries are handled by a configured RADIUS +server. +* **local**: All authentication queries are handled locally. +* **noauth**: Authentication disabled. +``` + +```{cfgcmd} set vpn pptp remote-access authentication local-users username \<user\> password \<pass\> + +Create `<user>` for local authentication on this system. The users password +will be set to `<pass>`. +``` + +```{cfgcmd} set vpn pptp remote-access client-ip-pool \<POOL-NAME\> range \<x.x.x.x-x.x.x.x | x.x.x.x/x\> + +Use this command to define the first IP address of a pool of +addresses to be given to PPTP clients. If notation ``x.x.x.x-x.x.x.x``, +it must be within a /24 subnet. If notation ``x.x.x.x/x`` is +used there is possibility to set host/netmask. +``` + +```{cfgcmd} set vpn pptp remote-access default-pool \<POOL-NAME\> + +Use this command to define default address pool name. +``` + +```{cfgcmd} set vpn pptp remote-access gateway-address \<gateway\> + +Specifies single `<gateway>` IP address to be used as local address of PPP +interfaces. +``` + + +## Configuring RADIUS authentication + +To enable RADIUS based authentication, the authentication mode needs to be +changed within the configuration. Previous settings like the local users, still +exists within the configuration, however they are not used if the mode has been +changed from local to radius. Once changed back to local, it will use all local +accounts again. + +```none +set vpn pptp remote-access authentication mode radius +``` + +```{cfgcmd} set vpn pptp remote-access authentication radius server \<server\> key \<secret\> + +Configure RADIUS `<server>` and its required shared `<secret>` for +communicating with the RADIUS server. +``` + +Since the RADIUS server would be a single point of failure, multiple RADIUS +servers can be setup and will be used subsequentially. +For example: + +```none +set vpn pptp remote-access authentication radius server 10.0.0.1 key 'foo' +set vpn pptp remote-access authentication radius server 10.0.0.2 key 'foo' +``` + +:::{note} +Some RADIUS severs use an access control list which allows or denies +queries, make sure to add your VyOS router to the allowed client list. +::: + +### RADIUS source address + +If you are using OSPF as IGP, always the closest interface connected to the +RADIUS server is used. You can bind all outgoing RADIUS requests +to a single source IP e.g. the loopback interface. + +```{cfgcmd} set vpn pptp remote-access authentication radius source-address \<address\> + +Source IPv4 address used in all RADIUS server queries. +``` + +:::{note} +Some RADIUS severs use an access control list which allows or denies +queries, make sure to add your VyOS router to the allowed client list. +::: + +### RADIUS advanced options + +```{cfgcmd} set vpn pptp remote-access authentication radius server \<server\> port \<port\> + +Configure RADIUS `<server>` and its required port for authentication requests. +``` + +```{cfgcmd} set vpn pptp remote-access authentication radius server \<server\> fail-time \<time\> + +Mark RADIUS server as offline for this given `<time>` in seconds. +``` + +```{cfgcmd} set vpn pptp remote-access authentication radius server \<server\> disable + +Temporary disable this RADIUS server. +``` + +```{cfgcmd} set vpn pptp remote-access authentication radius acct-timeout \<timeout\> + +Timeout to wait reply for Interim-Update packets. (default 3 seconds) +``` + +```{cfgcmd} set vpn pptp remote-access authentication radius dynamic-author server \<address\> + +Specifies IP address for Dynamic Authorization Extension server (DM/CoA). +This IP must exist on any VyOS interface or it can be ``0.0.0.0``. +``` + +```{cfgcmd} set vpn pptp remote-access authentication radius dynamic-author port \<port\> + +UDP port for Dynamic Authorization Extension server (DM/CoA) +``` + +```{cfgcmd} set vpn pptp remote-access authentication radius dynamic-author key \<secret\> + +Secret for Dynamic Authorization Extension server (DM/CoA) +``` + +```{cfgcmd} set vpn pptp remote-access authentication radius max-try \<number\> + +Maximum number of tries to send Access-Request/Accounting-Request queries +``` + +```{cfgcmd} set vpn pptp remote-access authentication radius timeout \<timeout\> + +Timeout to wait response from server (seconds) +``` + +```{cfgcmd} set vpn pptp remote-access authentication radius nas-identifier \<identifier\> + +Value to send to RADIUS server in NAS-Identifier attribute and to be matched +in DM/CoA requests. +``` + +```{cfgcmd} set vpn pptp remote-access authentication radius nas-ip-address \<address\> + +Value to send to RADIUS server in NAS-IP-Address attribute and to be matched +in DM/CoA requests. Also DM/CoA server will bind to that address. +``` + +```{cfgcmd} set vpn pptp remote-access authentication radius source-address \<address\> + +Source IPv4 address used in all RADIUS server queries. +``` + +```{cfgcmd} set vpn pptp remote-access authentication radius rate-limit attribute \<attribute\> + +Specifies which RADIUS server attribute contains the rate limit information. +The default attribute is `Filter-Id`. +``` + +:::{note} +If you set a custom RADIUS attribute you must define it on both +dictionaries at RADIUS server and client. +::: + +```{cfgcmd} set vpn pptp remote-access authentication radius rate-limit enable + +Enables bandwidth shaping via RADIUS. +``` + +```{cfgcmd} set vpn pptp remote-access authentication radius rate-limit vendor + +Specifies the vendor dictionary, dictionary needs to be in +/usr/share/accel-ppp/radius. +``` + +Received RADIUS attributes have a higher priority than parameters defined within +the CLI configuration, refer to the explanation below. + +### Allocation clients ip addresses by RADIUS + +If the RADIUS server sends the attribute `Framed-IP-Address` then this IP +address will be allocated to the client and the option `default-pool` within the CLI +config is being ignored. + +If the RADIUS server sends the attribute `Framed-Pool`, IP address will be allocated +from a predefined IP pool whose name equals the attribute value. + +If the RADIUS server sends the attribute `Stateful-IPv6-Address-Pool`, IPv6 address +will be allocated from a predefined IPv6 pool `prefix` whose name equals the attribute value. + +If the RADIUS server sends the attribute `Delegated-IPv6-Prefix-Pool`, IPv6 +delegation prefix will be allocated from a predefined IPv6 pool `delegate` +whose name equals the attribute value. + +:::{note} +`Stateful-IPv6-Address-Pool` and `Delegated-IPv6-Prefix-Pool` are defined in +RFC6911. If they are not defined in your RADIUS server, add new [dictionary]. +::: + +User interface can be put to VRF context via RADIUS Access-Accept packet, or change +it via RADIUS CoA. `Accel-VRF-Name` is used from these purposes. It is custom [ACCEL-PPP attribute]. +Define it in your RADIUS server. + +### Renaming clients interfaces by RADIUS + +If the RADIUS server uses the attribute `NAS-Port-Id`, ppp tunnels will be +renamed. + +:::{note} +The value of the attribute `NAS-Port-Id` must be less than 16 +characters, otherwise the interface won't be renamed. +::: + +## IPv6 + +```{cfgcmd} set vpn pptp remote-access ppp-options ipv6 \<require | prefer | allow | deny\> + +Specifies IPv6 negotiation preference. +* **require** - Require IPv6 negotiation +* **prefer** - Ask client for IPv6 negotiation, do not fail if it rejects +* **allow** - Negotiate IPv6 only if client requests +* **deny** - Do not negotiate IPv6 (default value) +``` + +```{cfgcmd} set vpn pptp remote-access client-ipv6-pool \<IPv6-POOL-NAME\> prefix \<address\> mask \<number-of-bits\> + +Use this command to set the IPv6 address pool from which a PPTP client +will get an IPv6 prefix of your defined length (mask) to terminate the +PPTP endpoint at their side. The mask length can be set from 48 to 128 +bit long, the default value is 64. +``` + +```{cfgcmd} set vpn pptp remote-access client-ipv6-pool \<IPv6-POOL-NAME\> delegate \<address\> delegation-prefix \<number-of-bits\> + +Use this command to configure DHCPv6 Prefix Delegation (RFC3633) on +PPTP. You will have to set your IPv6 pool and the length of the +delegation prefix. From the defined IPv6 pool you will be handing out +networks of the defined length (delegation-prefix). The length of the +delegation prefix can be set from 32 to 64 bit long. +``` + +```{cfgcmd} set vpn pptp remote-access default-ipv6-pool \<IPv6-POOL-NAME\> + +Use this command to define default IPv6 address pool name. +``` + +```none +set vpn pptp remote-access ppp-options ipv6 allow +set vpn pptp remote-access client-ipv6-pool IPv6-POOL delegate '2001:db8:8003::/48' delegation-prefix '56' +set vpn pptp remote-access client-ipv6-pool IPv6-POOL prefix '2001:db8:8002::/48' mask '64' +set vpn pptp remote-access default-ipv6-pool IPv6-POOL +``` + + +### IPv6 Advanced Options + +```{cfgcmd} set vpn pptp remote-access ppp-options ipv6-accept-peer-interface-id + +Accept peer interface identifier. By default is not defined. +``` + +```{cfgcmd} set vpn pptp remote-access ppp-options ipv6-interface-id \<random | x:x:x:x\> + +Specifies fixed or random interface identifier for IPv6. +By default is fixed. +* **random** - Random interface identifier for IPv6 +* **x:x:x:x** - Specify interface identifier for IPv6 +``` + +```{cfgcmd} set vpn pptp remote-access ppp-options ipv6-interface-id \<random | x:x:x:x\> + +Specifies peer interface identifier for IPv6. By default is fixed. +* **random** - Random interface identifier for IPv6 +* **x:x:x:x** - Specify interface identifier for IPv6 +* **ipv4-addr** - Calculate interface identifier from IPv4 address. +* **calling-sid** - Calculate interface identifier from calling-station-id. +``` + + +## Scripting + +```{cfgcmd} set vpn pptp remote-access extended-scripts on-change \<path_to_script\> + +Script to run when session interface changed by RADIUS CoA handling +``` + +```{cfgcmd} set vpn pptp remote-access extended-scripts on-down \<path_to_script\> + +Script to run when session interface going to terminate +``` + +```{cfgcmd} set vpn pptp remote-access extended-scripts on-pre-up \<path_to_script\> + +Script to run before session interface comes up +``` + +```{cfgcmd} set vpn pptp remote-access extended-scripts on-up \<path_to_script\> + +Script to run when session interface is completely configured and started +``` + + +## Advanced Options + +### Authentication Advanced Options + +```{cfgcmd} set vpn pptp remote-access authentication local-users username \<user\> disable + +Disable `<user>` account. +``` + +```{cfgcmd} set vpn pptp remote-access authentication local-users username \<user\> static-ip \<address\> + +Assign static IP address to `<user>` account. +``` + +```{cfgcmd} set vpn pptp remote-access authentication local-users username \<user\> rate-limit download \<bandwidth\> + +Download bandwidth limit in kbit/s for `<user>`. +``` + +```{cfgcmd} set vpn pptp remote-access authentication local-users username \<user\> rate-limit upload \<bandwidth\> + +Upload bandwidth limit in kbit/s for `<user>`. +``` + +```{cfgcmd} set vpn pptp remote-access authentication protocols \<pap | chap | mschap | mschap-v2\> + +Require the peer to authenticate itself using one of the following protocols: +pap, chap, mschap, mschap-v2. +``` + + +### Client IP Pool Advanced Options + +```{cfgcmd} set vpn pptp remote-access client-ip-pool \<POOL-NAME\> next-pool \<NEXT-POOL-NAME\> + +Use this command to define the next address pool name. +``` + + +### PPP Advanced Options + +```{cfgcmd} set vpn pptp remote-access ppp-options disable-ccp + +Disable Compression Control Protocol (CCP). +CCP is enabled by default. +``` + +```{cfgcmd} set vpn pptp remote-access ppp-options interface-cache \<number\> + +Specifies number of interfaces to keep in cache. It means that don’t +destroy interface after corresponding session is destroyed, instead +place it to cache and use it later for new sessions repeatedly. +This should reduce kernel-level interface creation/deletion rate lack. +Default value is **0**. +``` + +```{cfgcmd} set vpn pptp remote-access ppp-options ipv4 \<require | prefer | allow | deny\> + +Specifies IPv4 negotiation preference. +* **require** - Require IPv4 negotiation +* **prefer** - Ask client for IPv4 negotiation, do not fail if it rejects +* **allow** - Negotiate IPv4 only if client requests (Default value) +* **deny** - Do not negotiate IPv4 +``` + +```{cfgcmd} set vpn pptp remote-access ppp-options lcp-echo-failure \<number\> + +Defines the maximum `<number>` of unanswered echo requests. Upon reaching the +value `<number>`, the session will be reset. Default value is **3**. +``` + +```{cfgcmd} set vpn pptp remote-access ppp-options lcp-echo-interval \<interval\> + +If this option is specified and is greater than 0, then the PPP module will +send LCP pings of the echo request every `<interval>` seconds. +Default value is **30**. +``` + +```{cfgcmd} set vpn pptp remote-access ppp-options lcp-echo-timeout + +Specifies timeout in seconds to wait for any peer activity. If this option +specified it turns on adaptive lcp echo functionality and "lcp-echo-failure" +is not used. Default value is **0**. +``` + +```{cfgcmd} set vpn pptp remote-access ppp-options min-mtu \<number\> + +Defines minimum acceptable MTU. If client will try to negotiate less then +specified MTU then it will be NAKed or disconnected if rejects greater MTU. +Default value is **100**. +``` + +```{cfgcmd} set vpn pptp remote-access ppp-options mppe \<require | prefer | deny\> + +Specifies {abbr}`MPPE (Microsoft Point-to-Point Encryption)` negotiation +preference. +* **require** - ask client for mppe, if it rejects drop connection +* **prefer** - ask client for mppe, if it rejects don't fail. (Default value) +* **deny** - deny mppe + +Default behavior - don't ask client for mppe, but allow it if client wants. +Please note that RADIUS may override this option by MS-MPPE-Encryption-Policy +attribute. +``` + +```{cfgcmd} set vpn pptp remote-access ppp-options mru \<number\> + +Defines preferred MRU. By default is not defined. +``` + + +### Global Advanced options + +```{cfgcmd} set vpn pptp remote-access description \<description\> + +Set description. +``` + +```{cfgcmd} set vpn pptp remote-access limits burst \<value\> + +Burst count +``` + +```{cfgcmd} set vpn pptp remote-access limits connection-limit \<value\> + +Acceptable rate of connections (e.g. 1/min, 60/sec) +``` + +```{cfgcmd} set vpn pptp remote-access limits timeout \<value\> + +Timeout in seconds +``` + +```{cfgcmd} set vpn pptp remote-access mtu + +Maximum Transmission Unit (MTU) (default: **1436**) +``` + +```{cfgcmd} set vpn pptp remote-access max-concurrent-sessions + +Maximum number of concurrent session start attempts +``` + +```{cfgcmd} set vpn pptp remote-access name-server \<address\> + +Connected client should use `<address>` as their DNS server. This +command accepts both IPv4 and IPv6 addresses. Up to two nameservers +can be configured for IPv4, up to three for IPv6. +``` + +```{cfgcmd} set vpn pptp remote-access shaper fwmark \<1-2147483647\> + +Match firewall mark value +``` + +```{cfgcmd} set vpn pptp remote-access snmp master-agent + +Enable SNMP +``` + +```{cfgcmd} set vpn pptp remote-access wins-server \<address\> + +Windows Internet Name Service (WINS) servers propagated to client +``` + + +## Monitoring + +```{opcmd} show pptp-server sessions + +Use this command to locally check the active sessions in the PPTP +server. +``` + +```none +vyos@vyos:~$ show pptp-server sessions + ifname | username | ip | ip6 | ip6-dp | calling-sid | rate-limit | state | uptime | rx-bytes | tx-bytes +--------+----------+----------+-----+--------+----------------+------------+--------+----------+----------+---------- + pptp0 | test | 10.0.0.2 | | | 192.168.10.100 | | active | 00:01:26 | 6.9 KiB | 220 B +``` + +```none +vyos@vyos:~$ show pptp-server statistics + uptime: 0.00:04:52 +cpu: 0% +mem(rss/virt): 5504/100176 kB +core: + mempool_allocated: 152007 + mempool_available: 149007 + thread_count: 1 + thread_active: 1 + context_count: 6 + context_sleeping: 0 + context_pending: 0 + md_handler_count: 6 + md_handler_pending: 0 + timer_count: 2 + timer_pending: 0 +sessions: + starting: 0 + active: 1 + finishing: 0 +pptp: + starting: 0 + active: 1 +``` + + +## Troubleshooting + +```none +vyos@vyos:~$sudo journalctl -u accel-ppp@pptp -b 0 + +Feb 29 14:58:57 vyos accel-pptp[4629]: pptp: new connection from 192.168.10.100 +Feb 29 14:58:57 vyos accel-pptp[4629]: :: recv [PPTP Start-Ctrl-Conn-Request <Version 1> <Framing 1> <Bearer 1> <Max-Chan 0>] +Feb 29 14:58:57 vyos accel-pptp[4629]: :: send [PPTP Start-Ctrl-Conn-Reply <Version 1> <Result 1> <Error 0> <Framing 3> <Bearer 3> <Max-Chan 1>] +Feb 29 14:58:57 vyos accel-pptp[4629]: :: recv [PPTP Outgoing-Call-Request <Call-ID 2961> <Call-Serial 2> <Min-BPS 300> <Max-BPS 100000000> <Bearer 3> <Framing 3> <Window-Size 64> <Delay 0>] +Feb 29 14:58:57 vyos accel-pptp[4629]: :: send [PPTP Outgoing-Call-Reply <Call-ID 2> <Peer-Call-ID 2961> <Result 1> <Error 0> <Cause 0> <Speed 100000000> <Window-Size 64> <Delay 0> <Channel 0>] +Feb 29 14:58:57 vyos accel-pptp[4629]: :: lcp_layer_init +Feb 29 14:58:57 vyos accel-pptp[4629]: :: auth_layer_init +Feb 29 14:58:57 vyos accel-pptp[4629]: :: ccp_layer_init +Feb 29 14:58:57 vyos accel-pptp[4629]: :: ipcp_layer_init +Feb 29 14:58:57 vyos accel-pptp[4629]: :: ipv6cp_layer_init +Feb 29 14:58:57 vyos accel-pptp[4629]: :: ppp establishing +Feb 29 14:58:57 vyos accel-pptp[4629]: :: lcp_layer_start +Feb 29 14:58:57 vyos accel-pptp[4629]: :: send [LCP ConfReq id=75 <auth PAP> <mru 1436> <magic 483920bd>] +Feb 29 14:58:57 vyos accel-pptp[4629]: :: recv [PPTP Set-Link-Info] +Feb 29 14:58:57 vyos accel-pptp[4629]: :: recv [LCP ConfReq id=0 <mru 1400> <magic 0142785a> <pcomp> <accomp> < d 3 6 >] +Feb 29 14:58:57 vyos accel-pptp[4629]: :: send [LCP ConfRej id=0 <pcomp> <accomp> < d 3 6 >] +Feb 29 14:58:57 vyos accel-pptp[4629]: :: recv [LCP ConfReq id=1 <mru 1400> <magic 0142785a>] +Feb 29 14:58:57 vyos accel-pptp[4629]: :: send [LCP ConfAck id=1] +Feb 29 14:59:00 vyos accel-pptp[4629]: :: fsm timeout 9 +Feb 29 14:59:00 vyos accel-pptp[4629]: :: send [LCP ConfReq id=75 <auth PAP> <mru 1436> <magic 483920bd>] +Feb 29 14:59:00 vyos accel-pptp[4629]: :: recv [LCP ConfNak id=75 <auth MSCHAP-v2>] +Feb 29 14:59:00 vyos accel-pptp[4629]: :: send [LCP ConfReq id=76 <auth CHAP-md5> <mru 1436> <magic 483920bd>] +Feb 29 14:59:00 vyos accel-pptp[4629]: :: recv [LCP ConfNak id=76 <auth MSCHAP-v2>] +Feb 29 14:59:00 vyos accel-pptp[4629]: :: send [LCP ConfReq id=77 <auth MSCHAP-v1> <mru 1436> <magic 483920bd>] +Feb 29 14:59:00 vyos accel-pptp[4629]: :: recv [LCP ConfNak id=77 <auth MSCHAP-v2>] +Feb 29 14:59:00 vyos accel-pptp[4629]: :: send [LCP ConfReq id=78 <auth MSCHAP-v2> <mru 1436> <magic 483920bd>] +Feb 29 14:59:00 vyos accel-pptp[4629]: :: recv [LCP ConfAck id=78 <auth MSCHAP-v2> <mru 1436> <magic 483920bd>] +Feb 29 14:59:00 vyos accel-pptp[4629]: :: lcp_layer_started +Feb 29 14:59:00 vyos accel-pptp[4629]: :: auth_layer_start +Feb 29 14:59:00 vyos accel-pptp[4629]: :: send [MSCHAP-v2 Challenge id=1 <8aa758781676e6a8e85c11963ee010>] +Feb 29 14:59:00 vyos accel-pptp[4629]: :: recv [LCP Ident id=2 <MSRASV5.20>] +Feb 29 14:59:00 vyos accel-pptp[4629]: :: recv [LCP Ident id=3 <MSRAS-0-MSEDGEWIN10>] +Feb 29 14:59:00 vyos accel-pptp[4629]: [43B blob data] +Feb 29 14:59:00 vyos accel-pptp[4629]: :: recv [PPTP Set-Link-Info] +Feb 29 14:59:00 vyos accel-pptp[4629]: :: recv [MSCHAP-v2 Response id=1 <90c21af1091f745e8bf22388b058>, <e695ae5aae274c88a3fa1ee3dc9057aece4d53c87b9fea>, F=0, name="test"] +Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: connect: ppp0 <--> pptp(192.168.10.100) +Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: ppp connected +Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: send [MSCHAP-v2 Success id=1 "S=347F417CF04BEBBC7F75CFA7F43474C36FB218F9 M=Authentication succeeded"] +Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: test: authentication succeeded +Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: auth_layer_started +Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: ccp_layer_start +Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: send [CCP ConfReq id=b9 <mppe +H -M +S -L -D -C>] +Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: ipcp_layer_start +Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: ipv6cp_layer_start +Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: IPV6CP: discarding packet +Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: send [LCP ProtoRej id=122 <8057>] +Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: recv [IPCP ConfReq id=6 <addr 0.0.0.0> <dns1 0.0.0.0> <wins1 0.0.0.0> <dns2 0.0.0.0> <wins2 0.0.0.0>] +Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: send [IPCP ConfReq id=3b <addr 10.0.0.1>] +Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: send [IPCP ConfRej id=6 <dns1 0.0.0.0> <wins1 0.0.0.0> <dns2 0.0.0.0> <wins2 0.0.0.0>] +Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: recv [LCP ProtoRej id=7 <80fd>] +Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: ccp_layer_finished +Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: recv [IPCP ConfAck id=3b <addr 10.0.0.1>] +Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: recv [IPCP ConfReq id=8 <addr 0.0.0.0>] +Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: send [IPCP ConfNak id=8 <addr 10.0.0.2>] +Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: recv [IPCP ConfReq id=9 <addr 10.0.0.2>] +Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: send [IPCP ConfAck id=9] +Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: ipcp_layer_started +Feb 29 14:59:00 vyos accel-pptp[4629]: ppp0:test: rename interface to 'pptp0' +Feb 29 14:59:00 vyos accel-pptp[4629]: pptp0:test: pptp: ppp started +``` + +[accel-ppp]: https://accel-ppp.org/ +[accel-ppp attribute]: https://github.com/accel-ppp/accel-ppp/blob/master/accel-pppd/radius/dict/dictionary.accel +[dictionary]: https://github.com/accel-ppp/accel-ppp/blob/master/accel-pppd/radius/dict/dictionary.rfc6911 diff --git a/docs/configuration/vpn/rsa-keys.md b/docs/configuration/vpn/rsa-keys.md new file mode 100644 index 00000000..875ba91b --- /dev/null +++ b/docs/configuration/vpn/rsa-keys.md @@ -0,0 +1,114 @@ +# RSA-Keys + +```{todo} +Convert raw command blocks in this file to cfgcmd/opcmd +directives for command coverage tracking. +``` + +RSA can be used for services such as key exchanges and for encryption purposes. +To make IPSec work with dynamic address on one/both sides, we will have to use +RSA keys for authentication. They are very fast and easy to setup. + +First, on both routers run the operational command "generate pki key-pair +install \<key-pair name>". You may choose different length than 2048 of course. + +```none +vyos@left# run generate pki key-pair install ipsec-LEFT +Enter private key type: [rsa, dsa, ec] (Default: rsa) +Enter private key bits: (Default: 2048) +Note: If you plan to use the generated key on this router, do not encrypt the private key. +Do you want to encrypt the private key with a passphrase? [y/N] N +Configure mode commands to install key pair: +Do you want to install the public key? [Y/n] Y +set pki key-pair ipsec-LEFT public key 'MIIBIjANBgkqh...' +Do you want to install the private key? [Y/n] Y +set pki key-pair ipsec-LEFT private key 'MIIEvgIBADAN...' +[edit] +``` + +Configuration commands will display. +Note the command with the public key +(set pki key-pair ipsec-LEFT public key 'MIIBIjANBgkqh...'). +Then do the same on the opposite router: + +```none +vyos@left# run generate pki key-pair install ipsec-RIGHT +``` + +Note the command with the public key +(set pki key-pair ipsec-RIGHT public key 'FAAOCAQ8AMII...'). + +The noted public keys should be entered on the opposite routers. + +On the LEFT: + +```none +set pki key-pair ipsec-RIGHT public key 'FAAOCAQ8AMII...' +``` + +On the RIGHT: + +```none +set pki key-pair ipsec-LEFT public key 'MIIBIjANBgkqh...' +``` + +Now you are ready to setup IPsec. The key points: +1. Since both routers do not know their effective public addresses, + we set the local-address of the peer to "any". +2. On the initiator, we set the peer address to its public address, + but on the responder we only set the id. +3. On the initiator, we need to set the remote-id option so that it + can identify IKE traffic from the responder correctly. +4. On the responder, we need to set the local id so that initiator + can know who's talking to it for the point #3 to work. + +On the LEFT (static address): + +```none +set vpn ipsec interface eth0 + +set vpn ipsec esp-group MyESPGroup proposal 1 encryption aes128 +set vpn ipsec esp-group MyESPGroup proposal 1 hash sha1 + +set vpn ipsec ike-group MyIKEGroup proposal 1 dh-group 2 +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 none +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): + +```none +set vpn ipsec interface eth0 + +set vpn ipsec esp-group MyESPGroup proposal 1 encryption aes128 +set vpn ipsec esp-group MyESPGroup proposal 1 hash sha1 + +set vpn ipsec ike-group MyIKEGroup proposal 1 dh-group 2 +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 +``` + diff --git a/docs/configuration/vpn/dmvpn.rst b/docs/configuration/vpn/rst-dmvpn.rst index 30398a25..30398a25 100644 --- a/docs/configuration/vpn/dmvpn.rst +++ b/docs/configuration/vpn/rst-dmvpn.rst diff --git a/docs/configuration/vpn/index.rst b/docs/configuration/vpn/rst-index.rst index 6d38e5b5..6d38e5b5 100644 --- a/docs/configuration/vpn/index.rst +++ b/docs/configuration/vpn/rst-index.rst diff --git a/docs/configuration/vpn/l2tp.rst b/docs/configuration/vpn/rst-l2tp.rst index 7fdf8599..7fdf8599 100644 --- a/docs/configuration/vpn/l2tp.rst +++ b/docs/configuration/vpn/rst-l2tp.rst diff --git a/docs/configuration/vpn/openconnect.rst b/docs/configuration/vpn/rst-openconnect.rst index 0262b3f2..0262b3f2 100644 --- a/docs/configuration/vpn/openconnect.rst +++ b/docs/configuration/vpn/rst-openconnect.rst diff --git a/docs/configuration/vpn/pptp.rst b/docs/configuration/vpn/rst-pptp.rst index 194ec771..194ec771 100644 --- a/docs/configuration/vpn/pptp.rst +++ b/docs/configuration/vpn/rst-pptp.rst diff --git a/docs/configuration/vpn/rsa-keys.rst b/docs/configuration/vpn/rst-rsa-keys.rst index e7584563..e7584563 100644 --- a/docs/configuration/vpn/rsa-keys.rst +++ b/docs/configuration/vpn/rst-rsa-keys.rst diff --git a/docs/configuration/vpn/sstp.rst b/docs/configuration/vpn/rst-sstp.rst index b65aecca..b65aecca 100644 --- a/docs/configuration/vpn/sstp.rst +++ b/docs/configuration/vpn/rst-sstp.rst diff --git a/docs/configuration/vpn/sstp.md b/docs/configuration/vpn/sstp.md new file mode 100644 index 00000000..38596153 --- /dev/null +++ b/docs/configuration/vpn/sstp.md @@ -0,0 +1,698 @@ +(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 +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 allows SSTP to pass through virtually all firewalls +and proxy servers except for authenticated web proxies. + +SSTP is available for Linux, BSD, and Windows. + +VyOS utilizes [accel-ppp](https://accel-ppp.org/) to provide SSTP server functionality. We support both +local and RADIUS authentication. + +As SSTP provides PPP via a SSL/TLS channel the use of either publicly signed +certificates or private PKI is required. + +## Configuring SSTP Server + +### Certificates + +Using our documentation chapter - {ref}`pki` generate and install CA and Server certificate + +```none +vyos@vyos:~$ generate pki ca install CA +``` + +```none +vyos@vyos:~$ generate pki certificate sign CA install Server +``` + + +### Configuration + +```none +set vpn sstp authentication local-users username test password 'test' +set vpn sstp authentication mode 'local' +set vpn sstp client-ip-pool SSTP-POOL range '10.0.0.2-10.0.0.100' +set vpn sstp default-pool 'SSTP-POOL' +set vpn sstp gateway-address '10.0.0.1' +set vpn sstp ssl ca-certificate 'CA1' +set vpn sstp ssl certificate 'Server' +``` + +```{cfgcmd} set vpn sstp authentication mode \<local | radius\> + +Set authentication backend. The configured authentication backend is used +for all queries. +* **radius**: All authentication queries are handled by a configured RADIUS +server. +* **local**: All authentication queries are handled locally. +``` + +```{cfgcmd} set vpn sstp authentication local-users username \<user\> password \<pass\> + +Create `<user>` for local authentication on this system. The users password +will be set to `<pass>`. +``` + +```{cfgcmd} set vpn sstp client-ip-pool \<POOL-NAME\> range \<x.x.x.x-x.x.x.x | x.x.x.x/x\> + +Use this command to define the first IP address of a pool of +addresses to be given to SSTP clients. If notation ``x.x.x.x-x.x.x.x``, +it must be within a /24 subnet. If notation ``x.x.x.x/x`` is +used there is possibility to set host/netmask. +``` + +```{cfgcmd} set vpn sstp default-pool \<POOL-NAME\> + +Use this command to define default address pool name. +``` + +```{cfgcmd} set vpn sstp gateway-address \<gateway\> + +Specifies single `<gateway>` IP address to be used as local address of PPP +interfaces. +``` + +```{cfgcmd} set vpn sstp ssl ca-certificate \<file\> + +Name of installed certificate authority certificate. +``` + +```{cfgcmd} set vpn sstp ssl certificate \<file\> + +Name of installed server certificate. +``` + + +## Configuring RADIUS authentication + +To enable RADIUS based authentication, the authentication mode needs to be +changed within the configuration. Previous settings like the local users still +exist within the configuration, however they are not used if the mode has been +changed from local to radius. Once changed back to local, it will use all local +accounts again. + +```none +set vpn sstp authentication mode radius +``` + +```{cfgcmd} set vpn sstp authentication radius server \<server\> key \<secret\> + +Configure RADIUS `<server>` and its required shared `<secret>` for +communicating with the RADIUS server. +``` + +Since the RADIUS server would be a single point of failure, multiple RADIUS +servers can be setup and will be used subsequentially. +For example: + +```none +set vpn sstp authentication radius server 10.0.0.1 key 'foo' +set vpn sstp authentication radius server 10.0.0.2 key 'foo' +``` + +:::{note} +Some RADIUS severs use an access control list which allows or denies +queries, make sure to add your VyOS router to the allowed client list. +::: + +### RADIUS source address + +If you are using OSPF as your IGP, use the interface connected closest to the +RADIUS server. You can bind all outgoing RADIUS requests to a single source IP +e.g. the loopback interface. + +```{cfgcmd} set vpn sstp authentication radius source-address \<address\> + +Source IPv4 address used in all RADIUS server queries. +``` + +:::{note} +The `source-address` must be configured to that of an interface. +Best practice would be a loopback or dummy interface. +::: + +### RADIUS advanced options + +```{cfgcmd} set vpn sstp authentication radius server \<server\> port \<port\> + +Configure RADIUS `<server>` and its required port for authentication requests. +``` + +```{cfgcmd} set vpn sstp authentication radius server \<server\> fail-time \<time\> + +Mark RADIUS server as offline for this given `<time>` in seconds. +``` + +```{cfgcmd} set vpn sstp authentication radius server \<server\> disable + +Temporary disable this RADIUS server. +``` + +```{cfgcmd} set vpn sstp authentication radius acct-timeout \<timeout\> + +Timeout to wait reply for Interim-Update packets. (default 3 seconds) +``` + +```{cfgcmd} set vpn sstp authentication radius dynamic-author server \<address\> + +Specifies IP address for Dynamic Authorization Extension server (DM/CoA). +This IP must exist on any VyOS interface or it can be ``0.0.0.0``. +``` + +```{cfgcmd} set vpn sstp authentication radius dynamic-author port \<port\> + +UDP port for Dynamic Authorization Extension server (DM/CoA) +``` + +```{cfgcmd} set vpn sstp authentication radius dynamic-author key \<secret\> + +Secret for Dynamic Authorization Extension server (DM/CoA) +``` + +```{cfgcmd} set vpn sstp authentication radius max-try \<number\> + +Maximum number of tries to send Access-Request/Accounting-Request queries +``` + +```{cfgcmd} set vpn sstp authentication radius timeout \<timeout\> + +Timeout to wait response from server (seconds) +``` + +```{cfgcmd} set vpn sstp authentication radius nas-identifier \<identifier\> + +Value to send to RADIUS server in NAS-Identifier attribute and to be matched +in DM/CoA requests. +``` + +```{cfgcmd} set vpn sstp authentication radius nas-ip-address \<address\> + +Value to send to RADIUS server in NAS-IP-Address attribute and to be matched +in DM/CoA requests. Also DM/CoA server will bind to that address. +``` + +```{cfgcmd} set vpn sstp authentication radius source-address \<address\> + +Source IPv4 address used in all RADIUS server queries. +``` + +```{cfgcmd} set vpn sstp authentication radius rate-limit attribute \<attribute\> + +Specifies which RADIUS server attribute contains the rate limit information. +The default attribute is `Filter-Id`. +``` + +:::{note} +If you set a custom RADIUS attribute you must define it on both +dictionaries on the RADIUS server and client. +::: + +```{cfgcmd} set vpn sstp authentication radius rate-limit enable + +Enables bandwidth shaping via RADIUS. +``` + +```{cfgcmd} set vpn sstp authentication radius rate-limit vendor + +Specifies the vendor dictionary, This dictionary needs to be present in +/usr/share/accel-ppp/radius. +``` + +Received RADIUS attributes have a higher priority than parameters defined within +the CLI configuration, refer to the explanation below. + +### Allocation clients ip addresses by RADIUS + +If the RADIUS server sends the attribute `Framed-IP-Address` then this IP +address will be allocated to the client and the option `default-pool` within +the CLI config will being ignored. + +If the RADIUS server sends the attribute `Framed-Pool`, then the IP address +will be allocated from a predefined IP pool whose name equals the attribute +value. + +If the RADIUS server sends the attribute `Stateful-IPv6-Address-Pool`, the +IPv6 address will be allocated from a predefined IPv6 pool `prefix` whose +name equals the attribute value. + +If the RADIUS server sends the attribute `Delegated-IPv6-Prefix-Pool`, an +IPv6 delegation prefix will be allocated from a predefined IPv6 pool `delegate` +whose name equals the attribute value. + +:::{note} +`Stateful-IPv6-Address-Pool` and `Delegated-IPv6-Prefix-Pool` are defined in +RFC6911. If they are not defined in your RADIUS server, add new [dictionary]. +::: + +The client's interface can be put into a VRF context via a RADIUS Access-Accept +packet, or changed via RADIUS CoA. `Accel-VRF-Name` is used for these +purposes. This is a custom [ACCEL-PPP attribute]. Define it in your RADIUS +server. + +### Renaming clients interfaces by RADIUS + +If the RADIUS server uses the attribute `NAS-Port-Id`, ppp tunnels will be +renamed. + +:::{note} +The value of the attribute `NAS-Port-Id` must be less than 16 +characters, otherwise the interface won't be renamed. +::: + +## IPv6 + +```{cfgcmd} set vpn sstp ppp-options ipv6 \<require | prefer | allow | deny\> + +Specifies IPv6 negotiation preference. +* **require** - Require IPv6 negotiation +* **prefer** - Ask client for IPv6 negotiation, do not fail if it rejects +* **allow** - Negotiate IPv6 only if client requests +* **deny** - Do not negotiate IPv6 (default value) +``` + +```{cfgcmd} set vpn sstp client-ipv6-pool \<IPv6-POOL-NAME\> prefix \<address\> mask \<number-of-bits\> + +Use this command to set the IPv6 address pool from which an SSTP client will +get an IPv6 prefix of your defined length (mask) to terminate the SSTP +endpoint at their side. The mask length can be set between 48 and 128 bits +long, the default value is 64. +``` + +```{cfgcmd} set vpn sstp client-ipv6-pool \<IPv6-POOL-NAME\> delegate \<address\> delegation-prefix \<number-of-bits\> + +Use this command to configure DHCPv6 Prefix Delegation (RFC3633) on SSTP. You +will have to set your IPv6 pool and the length of the delegation prefix. From +the defined IPv6 pool you will be handing out networks of the defined length +(delegation-prefix). The length of the delegation prefix can be set between +32 and 64 bits long. +``` + +```{cfgcmd} set vpn sstp default-ipv6-pool \<IPv6-POOL-NAME\> + +Use this command to define default IPv6 address pool name. +``` + +```none +set vpn sstp ppp-options ipv6 allow +set vpn sstp client-ipv6-pool IPv6-POOL delegate '2001:db8:8003::/48' delegation-prefix '56' +set vpn sstp client-ipv6-pool IPv6-POOL prefix '2001:db8:8002::/48' mask '64' +set vpn sstp default-ipv6-pool IPv6-POOL +``` + + +### IPv6 Advanced Options + +```{cfgcmd} set vpn sstp ppp-options ipv6-accept-peer-interface-id + +Accept peer interface identifier. By default this is not defined. +``` + +```{cfgcmd} set vpn sstp ppp-options ipv6-interface-id \<random | x:x:x:x\> + +Specifies if a fixed or random interface identifier is used for IPv6. The +default is fixed. +* **random** - Random interface identifier for IPv6 +* **x:x:x:x** - Specify interface identifier for IPv6 +``` + +```{cfgcmd} set vpn sstp ppp-options ipv6-interface-id \<random | x:x:x:x\> + +Specifies the peer interface identifier for IPv6. The default is fixed. +* **random** - Random interface identifier for IPv6 +* **x:x:x:x** - Specify interface identifier for IPv6 +* **ipv4-addr** - Calculate interface identifier from IPv4 address. +* **calling-sid** - Calculate interface identifier from calling-station-id. +``` + + +## Scripting + +```{cfgcmd} set vpn sstp extended-scripts on-change \<path_to_script\> + +Script to run when the session interface is changed by RADIUS CoA handling +``` + +```{cfgcmd} set vpn sstp extended-scripts on-down \<path_to_script\> + +Script to run when the session interface about to terminate +``` + +```{cfgcmd} set vpn sstp extended-scripts on-pre-up \<path_to_script\> + +Script to run before the session interface comes up +``` + +```{cfgcmd} set vpn sstp extended-scripts on-up \<path_to_script\> + +Script to run when the session interface is completely configured and started +``` + + +## Advanced Options + +### Authentication Advanced Options + +```{cfgcmd} set vpn sstp authentication local-users username \<user\> disable + +Disable `<user>` account. +``` + +```{cfgcmd} set vpn sstp authentication local-users username \<user\> static-ip \<address\> + +Assign a static IP address to `<user>` account. +``` + +```{cfgcmd} set vpn sstp authentication local-users username \<user\> rate-limit download \<bandwidth\> + +Rate limit the download bandwidth for `<user>` to `<bandwidth>` kbit/s. +``` + +```{cfgcmd} set vpn sstp authentication local-users username \<user\> rate-limit upload \<bandwidth\> + +Rate limit the upload bandwidth for `<user>` to `<bandwidth>` kbit/s. +``` + +```{cfgcmd} set vpn sstp authentication protocols \<pap | chap | mschap | mschap-v2\> + +Require the peer to authenticate itself using one of the following protocols: +pap, chap, mschap, mschap-v2. +``` + + +### Client IP Pool Advanced Options + +```{cfgcmd} set vpn sstp client-ip-pool \<POOL-NAME\> next-pool \<NEXT-POOL-NAME\> + +Use this command to define the next address pool name. +``` + + +### PPP Advanced Options + +```{cfgcmd} set vpn sstp ppp-options disable-ccp + +Disable Compression Control Protocol (CCP). +CCP is enabled by default. +``` + +```{cfgcmd} set vpn sstp ppp-options interface-cache \<number\> + +Specifies number of interfaces to cache. This prevents interfaces from being +removed once the corresponding session is destroyed. Instead, interfaces are +cached for later use in new sessions. This should reduce the kernel-level +interface creation/deletion rate. +Default value is **0**. +``` + +```{cfgcmd} set vpn sstp ppp-options ipv4 \<require | prefer | allow | deny\> + +Specifies IPv4 negotiation preference. +* **require** - Require IPv4 negotiation +* **prefer** - Ask client for IPv4 negotiation, do not fail if it rejects +* **allow** - Negotiate IPv4 only if client requests (Default value) +* **deny** - Do not negotiate IPv4 +``` + +```{cfgcmd} set vpn sstp ppp-options lcp-echo-failure \<number\> + +Defines the maximum `<number>` of unanswered echo requests. Upon reaching the +value `<number>`, the session will be reset. Default value is **3**. +``` + +```{cfgcmd} set vpn sstp ppp-options lcp-echo-interval \<interval\> + +If this option is specified and is greater than 0, then the PPP module will +send LCP echo requests every `<interval>` seconds. +Default value is **30**. +``` + +```{cfgcmd} set vpn sstp ppp-options lcp-echo-timeout + +Specifies timeout in seconds to wait for any peer activity. If this option is +specified it turns on adaptive lcp echo functionality and "lcp-echo-failure" +is not used. Default value is **0**. +``` + +```{cfgcmd} set vpn sstp ppp-options min-mtu \<number\> + +Defines the minimum acceptable MTU. If a client tries to negotiate an MTU +lower than this it will be NAKed, and disconnected if it rejects a greater +MTU. +Default value is **100**. +``` + +```{cfgcmd} set vpn sstp ppp-options mppe \<require | prefer | deny\> + +Specifies {abbr}`MPPE (Microsoft Point-to-Point Encryption)` negotiation +preference. +* **require** - ask client for mppe, if it rejects drop connection +* **prefer** - ask client for mppe, if it rejects don't fail. (Default value) +* **deny** - deny mppe + +Default behavior - don't ask the client for mppe, but allow it if the client +wants. Please note that RADIUS may override this option by MS-MPPE-Encryption-Policy +attribute. +``` + +```{cfgcmd} set vpn sstp ppp-options mru \<number\> + +Defines preferred MRU. By default is not defined. +``` + + +### Global Advanced options + +```{cfgcmd} set vpn sstp description \<description\> + +Set description. +``` + +```{cfgcmd} set vpn sstp limits burst \<value\> + +Burst count +``` + +```{cfgcmd} set vpn sstp limits connection-limit \<value\> + +Maximum accepted connection rate (e.g. 1/min, 60/sec) +``` + +```{cfgcmd} set vpn sstp limits timeout \<value\> + +Timeout in seconds +``` + +```{cfgcmd} set vpn sstp mtu + +Maximum Transmission Unit (MTU) (default: **1500**) +``` + +```{cfgcmd} set vpn sstp max-concurrent-sessions + +Maximum number of concurrent session start attempts +``` + +```{cfgcmd} set vpn sstp name-server \<address\> + +Connected clients should use `<address>` as their DNS server. This command +accepts both IPv4 and IPv6 addresses. Up to two nameservers can be configured +for IPv4, up to three for IPv6. +``` + +```{cfgcmd} set vpn sstp shaper fwmark \<1-2147483647\> + +Match firewall mark value +``` + +```{cfgcmd} set vpn sstp snmp master-agent + +Enable SNMP +``` + +```{cfgcmd} set vpn sstp wins-server \<address\> + +Windows Internet Name Service (WINS) servers propagated to client +``` + +```{cfgcmd} set vpn sstp host-name \<hostname\> + +If this option is given, only SSTP connections to the specified host +and with the same TLS SNI will be allowed. +``` + + +## Configuring SSTP client + +Once you have setup your SSTP server there comes the time to do some basic +testing. The Linux client used for testing is called [sstpc]. [sstpc] requires a +PPP configuration/peer file. + +If you use a self-signed certificate, do not forget to install CA on the client side. + +The following PPP configuration tests MSCHAP-v2: + +```none +$ cat /etc/ppp/peers/vyos +usepeerdns +#require-mppe +#require-pap +require-mschap-v2 +noauth +lock +refuse-pap +refuse-eap +refuse-chap +refuse-mschap +#refuse-mschap-v2 +nobsdcomp +nodeflate +debug +``` + +You can now "dial" the peer with the following command: `sstpc --log-level 4 +--log-stderr --user vyos --password vyos vpn.example.com -- call vyos`. + +A connection attempt will be shown as: + +```none +$ sstpc --log-level 4 --log-stderr --user vyos --password vyos vpn.example.com -- call vyos + +Mar 22 13:29:12 sstpc[12344]: Resolved vpn.example.com to 192.0.2.1 +Mar 22 13:29:12 sstpc[12344]: Connected to vpn.example.com +Mar 22 13:29:12 sstpc[12344]: Sending Connect-Request Message +Mar 22 13:29:12 sstpc[12344]: SEND SSTP CRTL PKT(14) +Mar 22 13:29:12 sstpc[12344]: TYPE(1): CONNECT REQUEST, ATTR(1): +Mar 22 13:29:12 sstpc[12344]: ENCAP PROTO(1): 6 +Mar 22 13:29:12 sstpc[12344]: RECV SSTP CRTL PKT(48) +Mar 22 13:29:12 sstpc[12344]: TYPE(2): CONNECT ACK, ATTR(1): +Mar 22 13:29:12 sstpc[12344]: CRYPTO BIND REQ(4): 40 +Mar 22 13:29:12 sstpc[12344]: Started PPP Link Negotiation +Mar 22 13:29:15 sstpc[12344]: Sending Connected Message +Mar 22 13:29:15 sstpc[12344]: SEND SSTP CRTL PKT(112) +Mar 22 13:29:15 sstpc[12344]: TYPE(4): CONNECTED, ATTR(1): +Mar 22 13:29:15 sstpc[12344]: CRYPTO BIND(3): 104 +Mar 22 13:29:15 sstpc[12344]: Connection Established + +$ ip addr show ppp0 +164: ppp0: <POINTOPOINT,MULTICAST,NOARP,UP,LOWER_UP> mtu 1452 qdisc fq_codel state UNKNOWN group default qlen 3 + link/ppp promiscuity 0 + inet 100.64.2.2 peer 100.64.1.1/32 scope global ppp0 + valid_lft forever preferred_lft forever +``` + + +## Monitoring + +```{opcmd} show sstp-server sessions + +Use this command to locally check the active sessions in the SSTP +server. +``` + +```none +vyos@vyos:~$ show sstp-server sessions + ifname | username | ip | ip6 | ip6-dp | calling-sid | rate-limit | state | uptime | rx-bytes | tx-bytes +--------+----------+----------+-----+--------+----------------+------------+--------+----------+----------+---------- + sstp0 | test | 10.0.0.2 | | | 192.168.10.100 | | active | 00:15:46 | 16.3 KiB | 210 B +``` + +```none +vyos@vyos:~$ show sstp-server statistics + uptime: 0.01:21:54 +cpu: 0% +mem(rss/virt): 6688/100464 kB +core: + mempool_allocated: 149420 + mempool_available: 146092 + thread_count: 1 + thread_active: 1 + context_count: 6 + context_sleeping: 0 + context_pending: 0 + md_handler_count: 7 + md_handler_pending: 0 + timer_count: 2 + timer_pending: 0 +sessions: + starting: 0 + active: 1 + finishing: 0 +sstp: + starting: 0 + active: 1 +``` + + +## Troubleshooting + +```none +vyos@vyos:~$sudo journalctl -u accel-ppp@sstp -b 0 + +Feb 28 17:03:04 vyos accel-sstp[2492]: sstp: new connection from 192.168.10.100:49852 +Feb 28 17:03:04 vyos accel-sstp[2492]: sstp: starting +Feb 28 17:03:04 vyos accel-sstp[2492]: sstp: started +Feb 28 17:03:04 vyos accel-sstp[2492]: :: recv [HTTP <SSTP_DUPLEX_POST /sra_{BA195980-CD49-458b-9E23-C84EE0ADCD75}/ HTTP/1.1>] +Feb 28 17:03:04 vyos accel-sstp[2492]: :: recv [HTTP <SSTPCORRELATIONID: {48B82435-099A-4158-A987-052E7570CFAA}>] +Feb 28 17:03:04 vyos accel-sstp[2492]: :: recv [HTTP <Content-Length: 18446744073709551615>] +Feb 28 17:03:04 vyos accel-sstp[2492]: :: recv [HTTP <Host: vyos.io>] +Feb 28 17:03:04 vyos accel-sstp[2492]: :: send [HTTP <HTTP/1.1 200 OK>] +Feb 28 17:03:04 vyos accel-sstp[2492]: :: send [HTTP <Date: Wed, 28 Feb 2024 17:03:04 GMT>] +Feb 28 17:03:04 vyos accel-sstp[2492]: :: send [HTTP <Content-Length: 18446744073709551615>] +Feb 28 17:03:04 vyos accel-sstp[2492]: :: recv [SSTP SSTP_MSG_CALL_CONNECT_REQUEST] +Feb 28 17:03:04 vyos accel-sstp[2492]: :: send [SSTP SSTP_MSG_CALL_CONNECT_ACK] +Feb 28 17:03:04 vyos accel-sstp[2492]: :: lcp_layer_init +Feb 28 17:03:04 vyos accel-sstp[2492]: :: auth_layer_init +Feb 28 17:03:04 vyos accel-sstp[2492]: :: ccp_layer_init +Feb 28 17:03:04 vyos accel-sstp[2492]: :: ipcp_layer_init +Feb 28 17:03:04 vyos accel-sstp[2492]: :: ipv6cp_layer_init +Feb 28 17:03:04 vyos accel-sstp[2492]: :: ppp establishing +Feb 28 17:03:04 vyos accel-sstp[2492]: :: lcp_layer_start +Feb 28 17:03:04 vyos accel-sstp[2492]: :: send [LCP ConfReq id=56 <auth PAP> <mru 1452> <magic 1cd9ad05>] +Feb 28 17:03:04 vyos accel-sstp[2492]: :: recv [LCP ConfReq id=0 <mru 4091> <magic 345f64ca> <pcomp> <accomp> < d 3 6 >] +Feb 28 17:03:04 vyos accel-sstp[2492]: :: send [LCP ConfRej id=0 <pcomp> <accomp> < d 3 6 >] +Feb 28 17:03:04 vyos accel-sstp[2492]: :: recv [LCP ConfReq id=1 <mru 4091> <magic 345f64ca>] +Feb 28 17:03:04 vyos accel-sstp[2492]: :: send [LCP ConfNak id=1 <mru 1452>] +Feb 28 17:03:04 vyos accel-sstp[2492]: :: recv [LCP ConfReq id=2 <mru 1452> <magic 345f64ca>] +Feb 28 17:03:04 vyos accel-sstp[2492]: :: send [LCP ConfAck id=2] +Feb 28 17:03:07 vyos accel-sstp[2492]: :: fsm timeout 9 +Feb 28 17:03:07 vyos accel-sstp[2492]: :: send [LCP ConfReq id=56 <auth PAP> <mru 1452> <magic 1cd9ad05>] +Feb 28 17:03:07 vyos accel-sstp[2492]: :: recv [LCP ConfAck id=56 <auth PAP> <mru 1452> <magic 1cd9ad05>] +Feb 28 17:03:07 vyos accel-sstp[2492]: :: lcp_layer_started +Feb 28 17:03:07 vyos accel-sstp[2492]: :: auth_layer_start +Feb 28 17:03:07 vyos accel-sstp[2492]: :: recv [LCP Ident id=3 <MSRASV5.20>] +Feb 28 17:03:07 vyos accel-sstp[2492]: :: recv [LCP Ident id=4 <MSRAS-0-MSEDGEWIN10>] +Feb 28 17:03:07 vyos accel-sstp[2492]: [50B blob data] +Feb 28 17:03:07 vyos accel-sstp[2492]: :: recv [PAP AuthReq id=3] +Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: connect: ppp0 <--> sstp(192.168.10.100:49852) +Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: ppp connected +Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: send [PAP AuthAck id=3 "Authentication succeeded"] +Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: test: authentication succeeded +Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: auth_layer_started +Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: ccp_layer_start +Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: ipcp_layer_start +Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: ipv6cp_layer_start +Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: recv [SSTP SSTP_MSG_CALL_CONNECTED] +Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: IPV6CP: discarding packet +Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: send [LCP ProtoRej id=88 <8057>] +Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: recv [IPCP ConfReq id=7 <addr 0.0.0.0> <dns1 0.0.0.0> <wins1 0.0.0.0> <dns2 0.0.0.0> <wins2 0.0.0.0>] +Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: send [IPCP ConfReq id=25 <addr 10.0.0.1>] +Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: send [IPCP ConfRej id=7 <dns1 0.0.0.0> <wins1 0.0.0.0> <dns2 0.0.0.0> <wins2 0.0.0.0>] +Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: recv [IPCP ConfAck id=25 <addr 10.0.0.1>] +Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: recv [IPCP ConfReq id=8 <addr 0.0.0.0>] +Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: send [IPCP ConfNak id=8 <addr 10.0.0.5>] +Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: recv [IPCP ConfReq id=9 <addr 10.0.0.5>] +Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: send [IPCP ConfAck id=9] +Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: ipcp_layer_started +Feb 28 17:03:07 vyos accel-sstp[2492]: ppp0:test: rename interface to 'sstp0' +Feb 28 17:03:07 vyos accel-sstp[2492]: sstp0:test: sstp: ppp: started +``` + +[accel-ppp attribute]: https://github.com/accel-ppp/accel-ppp/blob/master/accel-pppd/radius/dict/dictionary.accel +[dictionary]: https://github.com/accel-ppp/accel-ppp/blob/master/accel-pppd/radius/dict/dictionary.rfc6911 +[sstpc]: https://github.com/reliablehosting/sstp-client diff --git a/docs/configuration/vrf/index.md b/docs/configuration/vrf/index.md new file mode 100644 index 00000000..c9b2cfd8 --- /dev/null +++ b/docs/configuration/vrf/index.md @@ -0,0 +1,646 @@ +--- +lastproofread: '2021-07-07' +--- + +(vrf)= + +# VRF + +{abbr}`VRF (Virtual Routing and Forwarding)` devices combined with ip rules +provides the ability to create virtual routing and forwarding domains (aka +VRFs, VRF-lite to be specific) in the Linux network stack. One use case is the +multi-tenancy problem where each tenant has their own unique routing tables and +in the very least need different default gateways. + +## Configuration + +A VRF device is created with an associated route table. Network interfaces are +then enslaved to a VRF device. + +```{cfgcmd} set vrf name \<name\> table \<id\> + +Create a new VRF instance with `<name>` and `<id>`. The name is used when placing +individual interfaces into the VRF. + +:::{note} +A routing table ID can not be modified once it is assigned. It can +only be changed by deleting and re-adding the VRF instance. +::: +``` + +```{cfgcmd} set vrf bind-to-all + +By default the scope of the port bindings for unbound sockets is limited to +the default VRF. That is, it will not be matched by packets arriving on +interfaces enslaved to a VRF and processes may bind to the same port if +they bind to a VRF. + +TCP & UDP services running in the default VRF context (ie., not bound to any +VRF device) can work across all VRF domains by enabling this option. +``` + +### Zebra/Kernel route filtering + + +Zebra supports prefix-lists and Route Maps to match routes received from +other FRR components. The permit/deny facilities provided by these commands +can be used to filter which routes zebra will install in the kernel. + +```{cfgcmd} set vrf \<name\> ip protocol \<protocol\> route-map \<route-map\> + +Apply a route-map filter to routes for the specified protocol. + +The following protocols can be used: any, babel, bgp, eigrp, +isis, ospf, rip, static + +:::{note} +If you choose any as the option that will cause all protocols that +are sending routes to zebra. +::: +``` + + +```{cfgcmd} set vrf \<name\> ipv6 protocol \<protocol\> route-map \<route-map\> + +Apply a route-map filter to routes for the specified protocol. + +The following protocols can be used: any, babel, bgp, isis, +ospfv3, ripng, static + +:::{note} +If you choose any as the option that will cause all protocols that +are sending routes to zebra. +::: +``` + +### Nexthop Tracking + + +Nexthop tracking resolve nexthops via the default route by default. This is enabled +by default for a traditional profile of FRR which we use. It and can be disabled if +you do not want to e.g. allow BGP to peer across the default route. + +```{cfgcmd} set vrf name \<name\> ip nht no-resolve-via-default + +Do not allow IPv4 nexthop tracking to resolve via the default route. This +parameter is configured per-VRF, so the command is also available in the VRF +subnode. +``` + + +```{cfgcmd} set vrf name \<name\> ipv6 nht no-resolve-via-default + +Do not allow IPv6 nexthop tracking to resolve via the default route. This +parameter is configured per-VRF, so the command is also available in the VRF +subnode. +``` + +### Interfaces + + +When VRFs are used it is not only mandatory to create a VRF but also the VRF +itself needs to be assigned to an interface. + +```{cfgcmd} set interfaces \<dummy | ethernet | bonding | bridge | pppoe\> \<interface\> vrf \<name\> + +Assign interface identified by `<interface>` to VRF named `<name>`. +``` + +### Routing + + +:::{note} +VyOS 1.4 (sagitta) introduced dynamic routing support for VRFs. +::: + + +Currently dynamic routing is supported for the following protocols: + + +- {ref}`routing-bgp` +- {ref}`routing-isis` +- {ref}`routing-ospf` +- {ref}`routing-ospfv3` +- {ref}`routing-static` + + +The CLI configuration is same as mentioned in above articles. The only +difference is, that each routing protocol used, must be prefixed with the `vrf +name <name>` command. + + +#### Example + + +The following commands would be required to set options for a given dynamic +routing protocol inside a given vrf: + + +- {ref}`routing-bgp`: `set vrf name <name> protocols bgp ...` +- {ref}`routing-isis`: `set vrf name <name> protocols isis ...` +- {ref}`routing-ospf`: `set vrf name <name> protocols ospf ...` +- {ref}`routing-ospfv3`: `set vrf name <name> protocols ospfv3 ...` +- {ref}`routing-static`: `set vrf name <name> protocols static ...` + + +### Services + + +Currently the following services can be created isolated in VRFs + + +- {ref}`dhcp-server` + + +The CLI configuration is same as mentioned in above articles. The only +difference is, that each service used, must be prefixed with the `vrf +name <name>` command. + + +#### Example + + +The following commands would be required to set options for a given service +inside a given vrf: + + +- {ref}`dhcp-server`: `set vrf name <name> service dhcp-server ...` +- {ref}`dhcp-server`: `set vrf name <name> service dhcpv6-server ...` + + +## Operation + + +It is not sufficient to only configure a VRF but VRFs must be maintained, too. +For VRF maintenance the following operational commands are in place. + +```{opcmd} show vrf + +Lists VRFs that have been created + +:::{code-block} none +vyos@vyos:~$ show vrf +VRF name state mac address flags interfaces +-------- ----- ----------- ----- ---------- +blue up 00:53:12:d8:74:24 noarp,master,up,lower_up dum200,eth0.302 +red up 00:53:de:02:df:aa noarp,master,up,lower_up dum100,eth0.300,bond0.100,peth0 +::: +:::{note} +Command should probably be extended to list also the real +interfaces assigned to this one VRF to get a better overview. +::: +``` + + +```{opcmd} show vrf \<name\> + +:::{code-block} none +vyos@vyos:~$ show vrf name blue +VRF name state mac address flags interfaces +-------- ----- ----------- ----- ---------- +blue up 00:53:12:d8:74:24 noarp,master,up,lower_up dum200,eth0.302 +::: +``` + + +```{opcmd} show ip route vrf \<name\> + +Display IPv4 routing table for VRF identified by `<name>`. + +:::{code-block} none +vyos@vyos:~$ show ip route vrf blue +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, + F - PBR, f - OpenFabric, + > - selected route, * - FIB route, q - queued route, r - rejected route + +VRF blue: +K 0.0.0.0/0 [255/8192] unreachable (ICMP unreachable), 00:00:50 +S>* 172.16.0.0/16 [1/0] via 192.0.2.1, dum1, 00:00:02 +C>* 192.0.2.0/24 is directly connected, dum1, 00:00:06 +::: +``` +```{opcmd} show ipv6 route vrf \<name\> + +Display IPv6 routing table for VRF identified by `<name>`. + +:::{code-block} none +vyos@vyos:~$ show ipv6 route vrf red +Codes: K - kernel route, C - connected, S - static, R - RIPng, + O - OSPFv3, I - IS-IS, B - BGP, N - NHRP, T - Table, + v - VNC, V - VNC-Direct, A - Babel, D - SHARP, F - PBR, + f - OpenFabric, + > - selected route, * - FIB route, q - queued route, r - rejected route + +VRF red: +K ::/0 [255/8192] unreachable (ICMP unreachable), 00:43:20 +C>* 2001:db8::/64 is directly connected, dum1, 00:02:19 +C>* fe80::/64 is directly connected, dum1, 00:43:19 +K>* ff00::/8 [0/256] is directly connected, dum1, 00:43:19 +::: +``` +```{opcmd} ping \<host\> vrf \<name\> + + The ping command is used to test whether a network host is reachable or not. + + Ping uses ICMP protocol's mandatory ECHO_REQUEST datagram to elicit an + ICMP ECHO_RESPONSE from a host or gateway. ECHO_REQUEST datagrams (pings) + will have an IP and ICMP header, followed by "struct timeval" and an + arbitrary number of pad bytes used to fill out the packet. + + When doing fault isolation with ping, you should first run it on the local + host, to verify that the local network interface is up and running. Then, + continue with hosts and gateways further down the road towards your + destination. Round-trip time and packet loss statistics are computed. + + Duplicate packets are not included in the packet loss calculation, although + the round-trip time of these packets is used in calculating the minimum/ + average/maximum round-trip time numbers. + + :::{note} + Ping command can be interrupted at any given time using ``<Ctrl>+c``. + A brief statistic is shown afterwards. + ::: + + :::{code-block} none + vyos@vyos:~$ ping 192.0.2.1 vrf red + PING 192.0.2.1 (192.0.2.1) 56(84) bytes of data. + 64 bytes from 192.0.2.1: icmp_seq=1 ttl=64 time=0.070 ms + 64 bytes from 192.0.2.1: icmp_seq=2 ttl=64 time=0.078 ms + ^C + --- 192.0.2.1 ping statistics --- + 2 packets transmitted, 2 received, 0% packet loss, time 4ms + rtt min/avg/max/mdev = 0.070/0.074/0.078/0.004 ms + ::: +``` + + +```{opcmd} traceroute vrf \<name\> [ipv4 | ipv6] \<host\> + +Displays the route packets taken to a network host utilizing VRF instance +identified by `<name>`. When using the IPv4 or IPv6 option, displays the +route packets taken to the given hosts IP address family. This option is +useful when the host is specified as a hostname rather than an IP address. +``` + + +```{opcmd} force vrf \<name\> + +Join a given VRF. This will open a new subshell within the specified VRF. + +The prompt is adjusted to reflect this change in both config and op-mode. + +:::{code-block} none +vyos@vyos:~$ force vrf blue +vyos@vyos(vrf:blue):~$ +::: +``` + +(vrf-example)= + + +## Example + + +### VRF route leaking + + +The following example topology was built using EVE-NG. + + +```{eval-rst} +.. figure:: /_static/images/vrf-example-topology-01.webp + :alt: VRF topology example + + + VRF route leaking +``` + + +- PC1 is in the `default` VRF and acting as e.g. a "fileserver" +- PC2 is in VRF `blue` which is the development department +- PC3 and PC4 are connected to a bridge device on router `R1` which is in VRF + `red`. Say this is the HR department. +- R1 is managed through an out-of-band network that resides in VRF `mgmt` + + +(vrf-example-configuration)= + + +#### Configuration + + +```none +set interfaces bridge br10 address '10.30.0.254/24' +set interfaces bridge br10 member interface eth3 +set interfaces bridge br10 member interface eth4 +set interfaces bridge br10 vrf 'red' + +set interfaces ethernet eth0 address 'dhcp' +set interfaces ethernet eth0 vrf 'mgmt' +set interfaces ethernet eth1 address '10.0.0.254/24' +set interfaces ethernet eth2 address '10.20.0.254/24' +set interfaces ethernet eth2 vrf 'blue' + +set protocols static route 10.20.0.0/24 interface eth2 vrf 'blue' +set protocols static route 10.30.0.0/24 interface br10 vrf 'red' + +set service ssh disable-host-validation +set service ssh vrf 'mgmt' + +set system name-server 'eth0' + +set vrf name blue protocols static route 10.0.0.0/24 interface eth1 vrf 'default' +set vrf name blue table '3000' +set vrf name mgmt table '1000' +set vrf name red protocols static route 10.0.0.0/24 interface eth1 vrf 'default' +set vrf name red table '2000' +``` + +### VRF and NAT + + +(vrf-nat-configuration)= + + +#### Configuration + + +```none +set interfaces ethernet eth0 address '172.16.50.12/24' +set interfaces ethernet eth0 vrf 'red' + +set interfaces ethernet eth1 address '192.168.130.100/24' +set interfaces ethernet eth1 vrf 'blue' + +set nat destination rule 110 description 'NAT ssh- INSIDE' +set nat destination rule 110 destination port '2022' +set nat destination rule 110 inbound-interface name 'eth0' +set nat destination rule 110 protocol 'tcp' +set nat destination rule 110 translation address '192.168.130.40' + +set nat source rule 100 outbound-interface name 'eth0' +set nat source rule 100 protocol 'all' +set nat source rule 100 source address '192.168.130.0/24' +set nat source rule 100 translation address 'masquerade' + +set service ssh vrf 'red' + +set vrf bind-to-all +set vrf name blue protocols static route 0.0.0.0/0 next-hop 172.16.50.1 vrf 'red' +set vrf name blue protocols static route 172.16.50.0/24 interface eth0 vrf 'red' +set vrf name blue table '1010' + +set vrf name red protocols static route 0.0.0.0/0 next-hop 172.16.50.1 +set vrf name red protocols static route 192.168.130.0/24 interface eth1 vrf 'blue' +set vrf name red table '2020' +``` + +(vrf-example-operation)= + + +#### Operation + + +After committing the configuration we can verify all leaked routes are +installed, and try to ICMP ping PC1 from PC3. + + +```none +PCS> ping 10.0.0.1 + +84 bytes from 10.0.0.1 icmp_seq=1 ttl=63 time=1.943 ms +84 bytes from 10.0.0.1 icmp_seq=2 ttl=63 time=1.618 ms +84 bytes from 10.0.0.1 icmp_seq=3 ttl=63 time=1.745 ms +``` + +```none +VPCS> show ip +NAME : VPCS[1] +IP/MASK : 10.30.0.1/24 +GATEWAY : 10.30.0.254 +DNS : +MAC : 00:50:79:66:68:0f +``` + +###### VRF default routing table + + +```none +vyos@R1:~$ show ip route +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, + F - PBR, f - OpenFabric, + > - selected route, * - FIB route, q - queued, r - rejected, b - backup + +C>* 10.0.0.0/24 is directly connected, eth1, 00:07:44 +S>* 10.20.0.0/24 [1/0] is directly connected, eth2 (vrf blue), weight 1, 00:07:38 +S>* 10.30.0.0/24 [1/0] is directly connected, br10 (vrf red), weight 1, 00:07:38 +``` + +###### VRF red routing table + + +```none +vyos@R1:~$ show ip route vrf red +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, + F - PBR, f - OpenFabric, + > - selected route, * - FIB route, q - queued, r - rejected, b - backup + +VRF red: +K>* 0.0.0.0/0 [255/8192] unreachable (ICMP unreachable), 00:07:57 +S>* 10.0.0.0/24 [1/0] is directly connected, eth1 (vrf default), weight 1, 00:07:40 +C>* 10.30.0.0/24 is directly connected, br10, 00:07:54 +``` + +###### VRF blue routing table + + +```none +vyos@R1:~$ show ip route vrf blue +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, + F - PBR, f - OpenFabric, + > - selected route, * - FIB route, q - queued, r - rejected, b - backup + +VRF blue: +K>* 0.0.0.0/0 [255/8192] unreachable (ICMP unreachable), 00:08:00 +S>* 10.0.0.0/24 [1/0] is directly connected, eth1 (vrf default), weight 1, 00:07:44 +C>* 10.20.0.0/24 is directly connected, eth2, 00:07:53 +``` + +# L3VPN VRFs + + +{abbr}`L3VPN VRFs ( Layer 3 Virtual Private Networks )` bgpd supports for +IPv4 RFC 4364 and IPv6 RFC 4659. L3VPN routes, and their associated VRF +MPLS labels, can be distributed to VPN SAFI neighbors in the default, i.e., +non VRF, BGP instance. VRF MPLS labels are reached using core MPLS labels +which are distributed using LDP or BGP labeled unicast. +bgpd also supports inter-VRF route leaking. + + +(l3vpn-vrf-route-leaking)= + + +## 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 +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 intermediary. +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 +the point of view of an individual VRF: import refers to routes leaked from VPN +to a unicast VRF, whereas export refers to routes leaked from a unicast VRF to +VPN. + + +:::{note} +Routes exported from a unicast VRF to the VPN RIB must be augmented +by two parameters: + + +> an RD / RTLIST + + +Configuration for these exported routes must, at a minimum, specify +these two parameters. +::: + + +(l3vpn-vrf-example-configuration)= + + +## Configuration + + +Configuration of route leaking between a unicast VRF RIB and the VPN SAFI RIB +of the default VRF is accomplished via commands in the context of a VRF +address-family. + +```{cfgcmd} set vrf name \<name\> protocols bgp address-family \<ipv4-unicast|ipv6-unicast\> rd vpn export \<asn:nn|address:nn\> + +Specifies the route distinguisher to be added to a route exported from the +current unicast VRF to VPN. +``` + + +```{cfgcmd} set vrf name \<name\> protocols bgp address-family \<ipv4-unicast|ipv6-unicast\> route-target vpn \<import|export|both\> [RTLIST] + +Specifies the route-target list to be attached to a route (export) or the +route-target list to match against (import) when exporting/importing +between the current unicast VRF and VPN.The RTLIST is a space-separated +list of route-targets, which are BGP extended community values as +described in Extended Communities Attribute. +``` + + +```{cfgcmd} set vrf name \<name\> protocols bgp address-family \<ipv4-unicast|ipv6-unicast\> label vpn export \<0-1048575|auto\> + +Enables an MPLS label to be attached to a route exported from the current +unicast VRF to VPN. If the value specified is auto, the label value is +automatically assigned from a pool maintained. +``` + + +```{cfgcmd} set vrf name \<name\> protocols bgp address-family \<ipv4-unicast|ipv6-unicast\> label vpn allocation-mode per-nexthop + +Select how labels are allocated in the given VRF. By default, the per-vrf +mode is selected, and one label is used for all prefixes from the VRF. The +per-nexthop will use a unique label for all prefixes that are reachable via +the same nexthop. +``` + + +```{cfgcmd} set vrf name \<name\> protocols bgp address-family \<ipv4-unicast|ipv6-unicast\> route-map vpn \<import|export\> [route-map \<name\>] + +Specifies an optional route-map to be applied to routes imported or +exported between the current unicast VRF and VPN. +``` + + +```{cfgcmd} set vrf name \<name\> protocols bgp address-family \<ipv4-unicast|ipv6-unicast\> \<import|export\> vpn + +Enables import or export of routes between the current unicast VRF and VPN. +``` + + +```{cfgcmd} set vrf name \<name\> protocols bgp address-family \<ipv4-unicast|ipv6-unicast\> import vrf \<name\> + +Shortcut syntax for specifying automatic leaking from vrf VRFNAME to the +current VRF using the VPN RIB as intermediary. The RD and RT are auto +derived and should not be specified explicitly for either the source or +destination VRF’s. +``` + + +```{cfgcmd} set vrf name \<name\> protocols bgp address-family \<ipv4-unicast|ipv6-unicast\> route-map vrf import [route-map \<name\>] + +Specifies an optional route-map to be applied to routes imported from VRFs. +``` + + +```{cfgcmd} set vrf name \<name\> protocols bgp interface \<interface\> mpls forwarding + +It is possible to permit BGP install VPN prefixes without transport labels. +This configuration will install VPN prefixes originated from an e-bgp session, +and with the next-hop directly connected. +``` + +(l3vpn-vrf-example-operation)= + + +## Operation + + +It is not sufficient to only configure a L3VPN VRFs but L3VPN VRFs must be +maintained, too.For L3VPN VRF maintenance the following operational commands +are in place. + +```{opcmd} show bgp \<ipv4|ipv6\> vpn + + Print active IPV4 or IPV6 routes advertised via the VPN SAFI. + +:::{code-block} none +BGP table version is 2, local router ID is 10.0.1.1, vrf id 0 +Default local pref 100, local AS 65001 +Status codes: s suppressed, d damped, h history, * valid, > best, = multipath, +i internal, r RIB-failure, S Stale, R Removed +Nexthop codes: @NNN nexthop's vrf id, < announce-nh-self +Origin codes: i - IGP, e - EGP, ? - incomplete + +Network Next Hop Metric LocPrf Weight Path +Route Distinguisher: 10.50.50.1:1011 +*>i10.50.50.0/24 10.0.0.7 0 100 0 i +UN=10.0.0.7 EC{65035:1011} label=80 type=bgp, subtype=0 +Route Distinguisher: 10.60.60.1:1011 +*>i10.60.60.0/24 10.0.0.10 0 100 0 i +UN=10.0.0.10 EC{65035:1011} label=80 type=bgp, subtype=0 +::: +``` + + +```{opcmd} show bgp \<ipv4|ipv6\> vpn summary + +Print a summary of neighbor connections for the specified AFI/SAFI +combination. + +:::{code-block} none +BGP router identifier 10.0.1.1, local AS number 65001 vrf-id 0 +BGP table version 0 +RIB entries 9, using 1728 bytes of memory +Peers 4, using 85 KiB of memory +Peer groups 1, using 64 bytes of memory + +Neighbor V AS MsgRcvd MsgSent TblVer InQ OutQ Up/Down State/PfxRcd PfxSnt +10.0.0.7 4 65001 2860 2870 0 0 0 1d23h34m 2 10 +::: +``` diff --git a/docs/configuration/vrf/index.rst b/docs/configuration/vrf/rst-index.rst index 5965f857..5965f857 100644 --- a/docs/configuration/vrf/index.rst +++ b/docs/configuration/vrf/rst-index.rst |