From dfea790b36ddab4c6661436c8eed3cea7af5bd3a Mon Sep 17 00:00:00 2001 From: Daniil Baturin Date: Wed, 6 May 2026 14:08:24 +0100 Subject: Revert "Add incremental RST-to-MyST swap mechanism (#1857)" (#1892) This reverts commit 4b36114e053ee11d0cb264a1e4cfe4692d78f194. --- docs/configuration/container/md-index.md | 479 ------ docs/configuration/firewall/md-bridge.md | 685 --------- docs/configuration/firewall/md-flowtables.md | 176 --- docs/configuration/firewall/md-global-options.md | 186 --- docs/configuration/firewall/md-groups.md | 477 ------ docs/configuration/firewall/md-index.md | 278 ---- docs/configuration/firewall/md-ipv4.md | 1517 ------------------- docs/configuration/firewall/md-ipv6.md | 1567 -------------------- docs/configuration/firewall/md-zone.md | 201 --- docs/configuration/highavailability/md-index.md | 561 ------- docs/configuration/interfaces/md-bonding.md | 764 ---------- docs/configuration/interfaces/md-bridge.md | 431 ------ docs/configuration/interfaces/md-dummy.md | 87 -- docs/configuration/interfaces/md-ethernet.md | 515 ------- docs/configuration/interfaces/md-geneve.md | 105 -- docs/configuration/interfaces/md-index.md | 26 - docs/configuration/interfaces/md-l2tpv3.md | 170 --- docs/configuration/interfaces/md-loopback.md | 67 - docs/configuration/interfaces/md-macsec.md | 319 ---- .../interfaces/md-openvpn-examples.md | 769 ---------- docs/configuration/interfaces/md-openvpn.md | 614 -------- docs/configuration/interfaces/md-pppoe.md | 419 ------ .../configuration/interfaces/md-pseudo-ethernet.md | 52 - docs/configuration/interfaces/md-sstp-client.md | 170 --- docs/configuration/interfaces/md-tunnel.md | 309 ---- .../interfaces/md-virtual-ethernet.md | 119 -- docs/configuration/interfaces/md-vti.md | 121 -- docs/configuration/interfaces/md-vxlan.md | 373 ----- docs/configuration/interfaces/md-wireguard.md | 434 ------ docs/configuration/interfaces/md-wireless.md | 923 ------------ docs/configuration/interfaces/md-wwan.md | 355 ----- docs/configuration/loadbalancing/md-haproxy.md | 510 ------- docs/configuration/loadbalancing/md-index.md | 15 - docs/configuration/loadbalancing/md-wan.md | 306 ---- docs/configuration/md-index.md | 23 - docs/configuration/nat/md-cgnat.md | 200 --- docs/configuration/nat/md-index.md | 13 - docs/configuration/nat/md-nat44.md | 788 ---------- docs/configuration/nat/md-nat64.md | 73 - docs/configuration/nat/md-nat66.md | 243 --- docs/configuration/pki/md-index.md | 583 -------- docs/configuration/policy/md-access-list.md | 70 - docs/configuration/policy/md-as-path-list.md | 29 - docs/configuration/policy/md-community-list.md | 29 - docs/configuration/policy/md-examples.md | 205 --- docs/configuration/policy/md-extcommunity-list.md | 33 - docs/configuration/policy/md-index.md | 53 - .../policy/md-large-community-list.md | 29 - docs/configuration/policy/md-local-route.md | 100 -- docs/configuration/policy/md-prefix-list.md | 152 -- docs/configuration/policy/md-route-map.md | 439 ------ docs/configuration/policy/md-route.md | 424 ------ docs/configuration/protocols/md-arp.md | 72 - docs/configuration/protocols/md-babel.md | 296 ---- docs/configuration/protocols/md-bfd.md | 205 --- docs/configuration/protocols/md-bgp.md | 1414 ------------------ docs/configuration/protocols/md-failover.md | 237 --- docs/configuration/protocols/md-igmp-proxy.md | 79 - docs/configuration/protocols/md-index.md | 25 - docs/configuration/protocols/md-isis.md | 746 ---------- docs/configuration/protocols/md-mpls.md | 285 ---- docs/configuration/protocols/md-multicast.md | 31 - docs/configuration/protocols/md-openfabric.md | 242 --- docs/configuration/protocols/md-ospf.md | 1504 ------------------- docs/configuration/protocols/md-pim.md | 282 ---- docs/configuration/protocols/md-pim6.md | 100 -- docs/configuration/protocols/md-rip.md | 294 ---- docs/configuration/protocols/md-rpki.md | 210 --- docs/configuration/protocols/md-segment-routing.md | 359 ----- docs/configuration/protocols/md-static.md | 298 ---- .../protocols/md-traffic-engineering.md | 54 - docs/configuration/service/md-broadcast-relay.md | 70 - docs/configuration/service/md-config-sync.md | 164 -- docs/configuration/service/md-conntrack-sync.md | 321 ---- docs/configuration/service/md-console-server.md | 139 -- docs/configuration/service/md-dhcp-relay.md | 205 --- docs/configuration/service/md-dhcp-server.md | 1178 --------------- docs/configuration/service/md-dns.md | 582 -------- docs/configuration/service/md-eventhandler.md | 130 -- docs/configuration/service/md-https.md | 138 -- docs/configuration/service/md-index.md | 29 - docs/configuration/service/md-ipoe-server.md | 512 ------- docs/configuration/service/md-lldp.md | 154 -- docs/configuration/service/md-mdns.md | 131 -- docs/configuration/service/md-monitoring.md | 334 ----- docs/configuration/service/md-ntp.md | 202 --- docs/configuration/service/md-pppoe-server.md | 753 ---------- docs/configuration/service/md-router-advert.md | 121 -- docs/configuration/service/md-salt-minion.md | 51 - docs/configuration/service/md-snmp.md | 258 ---- docs/configuration/service/md-ssh.md | 366 ----- docs/configuration/service/md-suricata.md | 93 -- docs/configuration/service/md-tftp-server.md | 78 - docs/configuration/service/md-webproxy.md | 459 ------ docs/configuration/system/md-acceleration.md | 158 -- docs/configuration/system/md-conntrack.md | 218 --- docs/configuration/system/md-console.md | 59 - docs/configuration/system/md-default-route.md | 40 - docs/configuration/system/md-flow-accounting.md | 209 --- docs/configuration/system/md-frr.md | 45 - docs/configuration/system/md-host-name.md | 70 - docs/configuration/system/md-index.md | 34 - docs/configuration/system/md-ip.md | 126 -- docs/configuration/system/md-ipv6.md | 193 --- docs/configuration/system/md-lcd.md | 41 - docs/configuration/system/md-login.md | 604 -------- docs/configuration/system/md-name-server.md | 65 - docs/configuration/system/md-option.md | 190 --- docs/configuration/system/md-proxy.md | 27 - docs/configuration/system/md-sflow.md | 66 - docs/configuration/system/md-sysctl.md | 16 - docs/configuration/system/md-syslog.md | 450 ------ docs/configuration/system/md-task-scheduler.md | 45 - docs/configuration/system/md-time-zone.md | 17 - docs/configuration/system/md-updates.md | 36 - docs/configuration/system/md-watchdog.md | 212 --- docs/configuration/trafficpolicy/md-index.md | 1299 ---------------- docs/configuration/vpn/ipsec/md-index.md | 11 - docs/configuration/vpn/ipsec/md-ipsec_general.md | 407 ----- .../vpn/ipsec/md-remoteaccess_ipsec.md | 186 --- docs/configuration/vpn/ipsec/md-site2site_ipsec.md | 780 ---------- .../vpn/ipsec/md-troubleshooting_ipsec.md | 313 ---- docs/configuration/vpn/md-dmvpn.md | 431 ------ docs/configuration/vpn/md-index.md | 14 - docs/configuration/vpn/md-l2tp.md | 624 -------- docs/configuration/vpn/md-openconnect.md | 330 ----- docs/configuration/vpn/md-pptp.md | 594 -------- docs/configuration/vpn/md-rsa-keys.md | 114 -- docs/configuration/vpn/md-sstp.md | 698 --------- docs/configuration/vrf/md-index.md | 646 -------- 130 files changed, 40155 deletions(-) delete mode 100644 docs/configuration/container/md-index.md delete mode 100644 docs/configuration/firewall/md-bridge.md delete mode 100644 docs/configuration/firewall/md-flowtables.md delete mode 100644 docs/configuration/firewall/md-global-options.md delete mode 100644 docs/configuration/firewall/md-groups.md delete mode 100644 docs/configuration/firewall/md-index.md delete mode 100644 docs/configuration/firewall/md-ipv4.md delete mode 100644 docs/configuration/firewall/md-ipv6.md delete mode 100644 docs/configuration/firewall/md-zone.md delete mode 100644 docs/configuration/highavailability/md-index.md delete mode 100644 docs/configuration/interfaces/md-bonding.md delete mode 100644 docs/configuration/interfaces/md-bridge.md delete mode 100644 docs/configuration/interfaces/md-dummy.md delete mode 100644 docs/configuration/interfaces/md-ethernet.md delete mode 100644 docs/configuration/interfaces/md-geneve.md delete mode 100644 docs/configuration/interfaces/md-index.md delete mode 100644 docs/configuration/interfaces/md-l2tpv3.md delete mode 100644 docs/configuration/interfaces/md-loopback.md delete mode 100644 docs/configuration/interfaces/md-macsec.md delete mode 100644 docs/configuration/interfaces/md-openvpn-examples.md delete mode 100644 docs/configuration/interfaces/md-openvpn.md delete mode 100644 docs/configuration/interfaces/md-pppoe.md delete mode 100644 docs/configuration/interfaces/md-pseudo-ethernet.md delete mode 100644 docs/configuration/interfaces/md-sstp-client.md delete mode 100644 docs/configuration/interfaces/md-tunnel.md delete mode 100644 docs/configuration/interfaces/md-virtual-ethernet.md delete mode 100644 docs/configuration/interfaces/md-vti.md delete mode 100644 docs/configuration/interfaces/md-vxlan.md delete mode 100644 docs/configuration/interfaces/md-wireguard.md delete mode 100644 docs/configuration/interfaces/md-wireless.md delete mode 100644 docs/configuration/interfaces/md-wwan.md delete mode 100644 docs/configuration/loadbalancing/md-haproxy.md delete mode 100644 docs/configuration/loadbalancing/md-index.md delete mode 100644 docs/configuration/loadbalancing/md-wan.md delete mode 100644 docs/configuration/md-index.md delete mode 100644 docs/configuration/nat/md-cgnat.md delete mode 100644 docs/configuration/nat/md-index.md delete mode 100644 docs/configuration/nat/md-nat44.md delete mode 100644 docs/configuration/nat/md-nat64.md delete mode 100644 docs/configuration/nat/md-nat66.md delete mode 100644 docs/configuration/pki/md-index.md delete mode 100644 docs/configuration/policy/md-access-list.md delete mode 100644 docs/configuration/policy/md-as-path-list.md delete mode 100644 docs/configuration/policy/md-community-list.md delete mode 100644 docs/configuration/policy/md-examples.md delete mode 100644 docs/configuration/policy/md-extcommunity-list.md delete mode 100644 docs/configuration/policy/md-index.md delete mode 100644 docs/configuration/policy/md-large-community-list.md delete mode 100644 docs/configuration/policy/md-local-route.md delete mode 100644 docs/configuration/policy/md-prefix-list.md delete mode 100644 docs/configuration/policy/md-route-map.md delete mode 100644 docs/configuration/policy/md-route.md delete mode 100644 docs/configuration/protocols/md-arp.md delete mode 100644 docs/configuration/protocols/md-babel.md delete mode 100644 docs/configuration/protocols/md-bfd.md delete mode 100644 docs/configuration/protocols/md-bgp.md delete mode 100644 docs/configuration/protocols/md-failover.md delete mode 100644 docs/configuration/protocols/md-igmp-proxy.md delete mode 100644 docs/configuration/protocols/md-index.md delete mode 100644 docs/configuration/protocols/md-isis.md delete mode 100644 docs/configuration/protocols/md-mpls.md delete mode 100644 docs/configuration/protocols/md-multicast.md delete mode 100644 docs/configuration/protocols/md-openfabric.md delete mode 100644 docs/configuration/protocols/md-ospf.md delete mode 100644 docs/configuration/protocols/md-pim.md delete mode 100644 docs/configuration/protocols/md-pim6.md delete mode 100644 docs/configuration/protocols/md-rip.md delete mode 100644 docs/configuration/protocols/md-rpki.md delete mode 100644 docs/configuration/protocols/md-segment-routing.md delete mode 100644 docs/configuration/protocols/md-static.md delete mode 100644 docs/configuration/protocols/md-traffic-engineering.md delete mode 100644 docs/configuration/service/md-broadcast-relay.md delete mode 100644 docs/configuration/service/md-config-sync.md delete mode 100644 docs/configuration/service/md-conntrack-sync.md delete mode 100644 docs/configuration/service/md-console-server.md delete mode 100644 docs/configuration/service/md-dhcp-relay.md delete mode 100644 docs/configuration/service/md-dhcp-server.md delete mode 100644 docs/configuration/service/md-dns.md delete mode 100644 docs/configuration/service/md-eventhandler.md delete mode 100644 docs/configuration/service/md-https.md delete mode 100644 docs/configuration/service/md-index.md delete mode 100644 docs/configuration/service/md-ipoe-server.md delete mode 100644 docs/configuration/service/md-lldp.md delete mode 100644 docs/configuration/service/md-mdns.md delete mode 100644 docs/configuration/service/md-monitoring.md delete mode 100644 docs/configuration/service/md-ntp.md delete mode 100644 docs/configuration/service/md-pppoe-server.md delete mode 100644 docs/configuration/service/md-router-advert.md delete mode 100644 docs/configuration/service/md-salt-minion.md delete mode 100644 docs/configuration/service/md-snmp.md delete mode 100644 docs/configuration/service/md-ssh.md delete mode 100644 docs/configuration/service/md-suricata.md delete mode 100644 docs/configuration/service/md-tftp-server.md delete mode 100644 docs/configuration/service/md-webproxy.md delete mode 100644 docs/configuration/system/md-acceleration.md delete mode 100644 docs/configuration/system/md-conntrack.md delete mode 100644 docs/configuration/system/md-console.md delete mode 100644 docs/configuration/system/md-default-route.md delete mode 100644 docs/configuration/system/md-flow-accounting.md delete mode 100644 docs/configuration/system/md-frr.md delete mode 100644 docs/configuration/system/md-host-name.md delete mode 100644 docs/configuration/system/md-index.md delete mode 100644 docs/configuration/system/md-ip.md delete mode 100644 docs/configuration/system/md-ipv6.md delete mode 100644 docs/configuration/system/md-lcd.md delete mode 100644 docs/configuration/system/md-login.md delete mode 100644 docs/configuration/system/md-name-server.md delete mode 100644 docs/configuration/system/md-option.md delete mode 100644 docs/configuration/system/md-proxy.md delete mode 100644 docs/configuration/system/md-sflow.md delete mode 100644 docs/configuration/system/md-sysctl.md delete mode 100644 docs/configuration/system/md-syslog.md delete mode 100644 docs/configuration/system/md-task-scheduler.md delete mode 100644 docs/configuration/system/md-time-zone.md delete mode 100644 docs/configuration/system/md-updates.md delete mode 100644 docs/configuration/system/md-watchdog.md delete mode 100644 docs/configuration/trafficpolicy/md-index.md delete mode 100644 docs/configuration/vpn/ipsec/md-index.md delete mode 100644 docs/configuration/vpn/ipsec/md-ipsec_general.md delete mode 100644 docs/configuration/vpn/ipsec/md-remoteaccess_ipsec.md delete mode 100644 docs/configuration/vpn/ipsec/md-site2site_ipsec.md delete mode 100644 docs/configuration/vpn/ipsec/md-troubleshooting_ipsec.md delete mode 100644 docs/configuration/vpn/md-dmvpn.md delete mode 100644 docs/configuration/vpn/md-index.md delete mode 100644 docs/configuration/vpn/md-l2tp.md delete mode 100644 docs/configuration/vpn/md-openconnect.md delete mode 100644 docs/configuration/vpn/md-pptp.md delete mode 100644 docs/configuration/vpn/md-rsa-keys.md delete mode 100644 docs/configuration/vpn/md-sstp.md delete mode 100644 docs/configuration/vrf/md-index.md (limited to 'docs/configuration') diff --git a/docs/configuration/container/md-index.md b/docs/configuration/container/md-index.md deleted file mode 100644 index db46db38..00000000 --- a/docs/configuration/container/md-index.md +++ /dev/null @@ -1,479 +0,0 @@ ---- -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 \ 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 ` 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 \ entrypoint \ - -Override the default entrypoint from the image for a container. -``` - - -```{cfgcmd} set container name \ command \ - -Override the default command from the image for a container. -``` - - -```{cfgcmd} set container name \ arguments \ - -Set the command arguments for a container. -``` - - -```{cfgcmd} set container name \ host-name \ - -Set the host name for a container. -``` - - -```{cfgcmd} set container 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 \ 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 \ network \ - -Attaches user-defined network to a container. -Only one network must be specified and must already exist. -``` - - -```{cfgcmd} set container name \ network \ 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-server \ - -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 \ description \ - -Set a container description -``` - - -```{cfgcmd} set container name \ environment \ 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 \ port \ source \ - -``` -```{cfgcmd} set container name \ port \ destination \ -``` - -```{cfgcmd} set container name \ port \ protocol \ - -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 \ volume \ source \ -``` - -```{cfgcmd} set container name \ volume \ destination \ - -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 \ volume \ mode \ - -Volume is either mounted as rw (read-write - default) or ro (read-only) -``` - -```{cfgcmd} set container name \ tmpfs \ destination \ - -Mount a tmpfs *(ramdisk)* filesystem to the given path within the container. -``` - -```{cfgcmd} set container name \ tmpfs \ size \ - -Size in MB for tmpfs filesystem, maximum size is 64GB or 50% of the -systems total available memory. -``` - -```{cfgcmd} set container name \ uid \ -``` - -```{cfgcmd} set container name \ gid \ - -Set the User ID or Group ID of the container -``` - -```{cfgcmd} set container 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 \ cpu-quota \ - -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=\" when the container is created. -``` - -```{cfgcmd} set container name \ memory \ - -Constrain the memory available to the container. - -Default is 512 MB. Use 0 MB for unlimited memory. -``` - -```{cfgcmd} set container name \ device \ source \ -``` - -```{cfgcmd} set container name \ device \ destination \ - -Add a host device to the container. -``` - -```{cfgcmd} set container name \ capability \ - -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 \ sysctl parameter \ 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 \ label \ value \ - -Add metadata label for this container. -``` - -```{cfgcmd} set container 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 \ health-check - -Default health check is run for the container if defined by the image. -``` - -```{cfgcmd} set container name \ health-check command \ - -Override the default health check command from the image for a container. -``` - -```{cfgcmd} set container name \ health-check interval \ - -Override the default health-check interval. For example: `60` -``` - -```{cfgcmd} set container name \ health-check timeout \ - -Override the default health-check timeout. For example: `10` -``` - -```{cfgcmd} set container name \ health-check retries \ - -Number of health check retries before container is considered unhealthy. For example: `1` -``` - -### Container Networks - -```{cfgcmd} set container network \ - -Creates a named container network -``` - -```{cfgcmd} set container network \ description - -A brief description what this network is all about. -``` - -```{cfgcmd} set container network \ prefix \ - -Define IPv4 and/or IPv6 prefix for a given network name. -Both IPv4 and IPv6 can be used in parallel. -``` - -```{cfgcmd} set container network \ mtu \ - -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 \ no-name-server - -Disable Domain Name System (DNS) plugin for this network. -``` - -```{cfgcmd} set container network \ vrf \ - -Bind container network to a given VRF instance. -``` - -### Container Registry - -```{cfgcmd} set container registry \ - -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 \ disable - -Disable a given container registry -``` - -```{cfgcmd} set container registry \ authentication username -``` - -```{cfgcmd} set container registry \ 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 \ insecure - -Allow registry access over unencrypted HTTP or TLS connections with -untrusted certificates. -``` - -```{cfgcmd} set container registry \ mirror address \ -``` - -```{cfgcmd} set container registry \ mirror host-name \ -``` - -```{cfgcmd} set container registry \ mirror port \ -``` - -```{cfgcmd} set container registry \ mirror 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 \ 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 \ - -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 \ - -Show logs from a given container -``` -```{opcmd} show container network - -Show a list available container networks -``` -```{opcmd} restart container \ - -Restart a given container -``` -```{opcmd} update container image \ - -Update container image -``` -```{opcmd} delete container image \ [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/firewall/md-bridge.md b/docs/configuration/firewall/md-bridge.md deleted file mode 100644 index f0e94f9e..00000000 --- a/docs/configuration/firewall/md-bridge.md +++ /dev/null @@ -1,685 +0,0 @@ ---- -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 \ -``` - -From the main structure defined in -{doc}`Firewall Overview` -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` 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 ...`. 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 \ 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 \ -``` - -```{cfgcmd} set firewall bridge input filter rule \<1-999999\> jump-target \ -``` - -```{cfgcmd} set firewall bridge output filter rule \<1-999999\> jump-target \ -``` - -```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> jump-target \ -``` - -```{cfgcmd} set firewall bridge name \ rule \<1-999999\> jump-target \ -``` - -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 \ 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 \ 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 \ 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 \ 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 \ default-jump-target \ - -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 \ 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 \ 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 \ 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 \ 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 \ 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 \ 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 \ description \ - -Provide a rule-set description to a custom firewall chain. -``` - -```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> description \ -``` - -```{cfgcmd} set firewall bridge input filter rule \<1-999999\> description \ -``` - -```{cfgcmd} set firewall bridge output filter rule \<1-999999\> description \ -``` - -```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> description \ -``` - -```{cfgcmd} set firewall bridge name \ rule \<1-999999\> description \ - -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 \ 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` and -{doc}`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 \ 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 \ 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 \ 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 \ 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 \ -``` - -```{opcmd} show firewall bridge name \ -``` - -```{opcmd} show firewall bridge name \ 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 \ -``` - -```{opcmd} show log firewall bridge forward filter rule \ -``` - -```{opcmd} show log firewall bridge name \ 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/md-flowtables.md b/docs/configuration/firewall/md-flowtables.md deleted file mode 100644 index 24d0675e..00000000 --- a/docs/configuration/firewall/md-flowtables.md +++ /dev/null @@ -1,176 +0,0 @@ ---- -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 `. - -```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:** - -::: - -## 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 \ interface \ - -Specify interfaces to use in the flowtable. -``` - -```{cfgcmd} set firewall flowtable \ description \ -``` - -Provide a description for the flow table. - -```{cfgcmd} set firewall flowtable \ offload \ - -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 \ - -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/md-global-options.md b/docs/configuration/firewall/md-global-options.md deleted file mode 100644 index 0f6d91ac..00000000 --- a/docs/configuration/firewall/md-global-options.md +++ /dev/null @@ -1,186 +0,0 @@ ---- -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/md-groups.md b/docs/configuration/firewall/md-groups.md deleted file mode 100644 index 817f610e..00000000 --- a/docs/configuration/firewall/md-groups.md +++ /dev/null @@ -1,477 +0,0 @@ ---- -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 \ address [address | address range] - -``` -```{cfgcmd} set firewall group ipv6-address-group \ 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 \ description \ -``` - -```{cfgcmd} set firewall group ipv6-address-group \ description \ - -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 \ url \ - -Specify a remote list of IPv4 and/or IPv6 addresses, ranges, and CIDRs -to fetch. -``` - -```{cfgcmd} set firewall group remote-group \ description \ - -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 \ network \ -``` - -```{cfgcmd} set firewall group ipv6-network-group \ network \ - -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 \ description \ -``` - -```{cfgcmd} set firewall group ipv6-network-group \ description \ - -Provide an IPv4 or IPv6 network group description. -``` - -### Interface Groups - -An **interface group** represents a collection of interfaces. - -```{cfgcmd} set firewall group interface-group \ interface \ - -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 \ description \ - -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 \ 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 \ description \ - -Provide a port group description. -``` - -### MAC Groups - -A **mac group** represents a collection of mac addresses. - -```{cfgcmd} set firewall group mac-group \ 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 \ description \ - -Provide a MAC group description. -``` - -### Domain Groups - -A **domain group** represents a collection of domains. - -```{cfgcmd} set firewall group domain-group \ address \ - -Define a domain group. -``` - -```none -set firewall group domain-group DOM address example.com -``` - -```{cfgcmd} set firewall group domain-group \ description \ - -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 \ -``` - -```{cfgcmd} set firewall group dynamic-group ipv6-address-group \ -``` - -Add description to firewall groups: - -```{cfgcmd} set firewall group dynamic-group address-group \ description \ -``` - -```{cfgcmd} set firewall group dynamic-group ipv6-address-group \ description \ -``` - -#### 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 \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> add-address-to-group destination-address address-group \ -``` - -```{cfgcmd} set firewall ipv6 [forward | input | output] filter rule \<1-999999\> add-address-to-group destination-address address-group \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> add-address-to-group destination-address address-group \ -``` - -- 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 \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> add-address-to-group source-address address-group \ -``` - -```{cfgcmd} set firewall ipv6 [forward | input | output] filter rule \<1-999999\> add-address-to-group source-address address-group \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> add-address-to-group source-address address-group \ -``` - -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 \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> add-address-to-group [destination-address | source-address] timeout \ -``` - -```{cfgcmd} set firewall ipv6 [forward | input | output] filter rule \<1-999999\> add-address-to-group [destination-address | source-address] timeout \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> add-address-to-group [destination-address | source-address] 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: -s Timeout value in seconds -m Timeout value in minutes -h Timeout value in hours -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 \ - -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/md-index.md b/docs/configuration/firewall/md-index.md deleted file mode 100644 index 9108a800..00000000 --- a/docs/configuration/firewall/md-index.md +++ /dev/null @@ -1,278 +0,0 @@ ---- -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]() -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 `. - -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/md-ipv4.md b/docs/configuration/firewall/md-ipv4.md deleted file mode 100644 index 2107065d..00000000 --- a/docs/configuration/firewall/md-ipv4.md +++ /dev/null @@ -1,1517 +0,0 @@ ---- -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 `. - -```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`: `set system - conntrack ignore ipv4...` -- {doc}`Policy Route`: commands found under - `set policy route ...` -- {doc}`Destination NAT`: 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 ...`. 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 \ 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 \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> jump-target \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> jump-target \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> jump-target \ - -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 \ 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 \ 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 \ 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 \ 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 \ default-jump-target \ - -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 \ 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 \ 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 \ 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 \ 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 \ 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 \ 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 \ description \ - -Provide a rule-set description for a custom firewall chain. -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> description \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> description \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> description \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> description \ - -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 \ 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 \ 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 \ rule \<1-999999\> connection-mark \<1-2147483647\> - -Match based on connection mark. -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> conntrack-helper \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> conntrack-helper \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> conntrack-helper \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> conntrack-helper \ - -Match based on connection tracking protocol helper module to secure use of -that helper module. See below for possible completions \. - -:::{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 \ 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 \ 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 \ 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 \ 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 \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> source fqdn \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> source fqdn \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> source fqdn \ -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> destination fqdn \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> destination fqdn \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> destination fqdn \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> destination 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 \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> source geoip country-code \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> source geoip country-code \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> source geoip country-code \ -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> destination geoip country-code \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> destination geoip country-code \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> destination geoip country-code \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> destination geoip country-code \ -``` - -```{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 \ 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 \ 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 \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> source mac-address \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> source mac-address \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> source 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 \ 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 \ 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 \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> source group address-group \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> source group address-group \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> source group address-group \ -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> destination group address-group \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> destination group address-group \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> destination group address-group \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> destination group address-group \ - -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 \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> source group dynamic-address-group \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> source group dynamic-address-group \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> source group dynamic-address-group \ -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> destination group dynamic-address-group \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> destination group dynamic-address-group \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> destination group dynamic-address-group \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> destination group dynamic-address-group \ - -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 \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> source group network-group \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> source group network-group \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> source group network-group \ -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> destination group network-group \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> destination group network-group \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> destination group network-group \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> destination group network-group \ - -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 \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> source group port-group \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> source group port-group \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> source group port-group \ -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> destination group port-group \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> destination group port-group \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> destination group port-group \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> destination group port-group \ - -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 \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> source group domain-group \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> source group domain-group \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> source group domain-group \ -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> destination group domain-group \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> destination group domain-group \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> destination group domain-group \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> destination group domain-group \ - -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 \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> source group mac-group \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> source group mac-group \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> source group mac-group \ -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> destination group mac-group \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> destination group mac-group \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> destination group mac-group \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> destination group mac-group \ - -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 \ 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 \ 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 \ 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 \ 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 \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> icmp type-name \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> icmp type-name \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> icmp type-name \ - -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 \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> inbound-interface name \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> inbound-interface name \ - -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 \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> inbound-interface group \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> inbound-interface 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 \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> outbound-interface name \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> outbound-interface name \ - -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 \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> outbound-interface group \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> outbound-interface 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 \ 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 \ 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 \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> limit rate \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> limit rate \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> limit rate \ - -Specify the maximum average rate as **integer/unit**. For example: -**5/minutes** -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> packet-length \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> packet-length \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> packet-length \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> packet-length \ -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> packet-length-exclude \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> packet-length-exclude \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> packet-length-exclude \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> packet-length-exclude \ - -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 \ 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 [\ | \<0-255\> | all | tcp_udp] -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> protocol [\ | \<0-255\> | all | tcp_udp] -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> protocol [\ | \<0-255\> | all | tcp_udp] -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> protocol [\ | \<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 \ 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 \ 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] \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> tcp flags [not] \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> tcp flags [not] \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> tcp flags [not] \ - -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 \ 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 \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> time startdate \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> time startdate \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> time startdate \ -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> time starttime \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> time starttime \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> time starttime \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> time starttime \ -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> time stopdate \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> time stopdate \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> time stopdate \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> time stopdate \ -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> time stoptime \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> time stoptime \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> time stoptime \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> time stoptime \ -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> time weekdays \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> time weekdays \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> time weekdays \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> time weekdays \ - -Time to match the defined rule. -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> ttl \ \<0-255\> -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> ttl \ \<0-255\> -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> ttl \ \<0-255\> -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> ttl \ \<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_ADRESSES 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 \ - -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 \ 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 \ -``` - -```{opcmd} show log firewall ipv4 [forward | input | output] filter rule \ -``` - -```{opcmd} show log firewall ipv4 name \ 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/md-ipv6.md b/docs/configuration/firewall/md-ipv6.md deleted file mode 100644 index 770cb146..00000000 --- a/docs/configuration/firewall/md-ipv6.md +++ /dev/null @@ -1,1567 +0,0 @@ ---- -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 `. - -```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`: `set system - conntrack ignore ipv6...` -- {doc}`Policy Route`: commands found under - `set policy route6 ...` -- {doc}`Destination NAT`: 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 ...`. 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 \ 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 \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> jump-target \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> jump-target \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> jump-target \ - -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 \ 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 \ 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 \ 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 \ 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 \ default-jump-target \ - -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 \ 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 \ 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 \ 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 \ 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 \ 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 \ 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 \ description \ - -Provide a rule-set description to a custom firewall chain. -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> description \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> description \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> description \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> description \ - -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 \ 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 \ 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 \ 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 \ 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 \ 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 \ 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 \ 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 \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> source fqdn \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> source fqdn \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> source fqdn \ -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> destination fqdn \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> destination fqdn \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> destination fqdn \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> destination 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 \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> source geoip country-code \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> source geoip country-code \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> source geoip country-code \ -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> destination geoip country-code \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> destination geoip country-code \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> destination geoip country-code \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> destination geoip country-code \ -``` - -```{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 \ 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 \ 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 \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> source mac-address \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> source mac-address \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> source 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 \ 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 \ 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 \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> source group address-group \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> source group address-group \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> source group address-group \ -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> destination group address-group \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> destination group address-group \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> destination group address-group \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> destination group address-group \ - -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 \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> source group dynamic-address-group \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> source group dynamic-address-group \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> source group dynamic-address-group \ -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> destination group dynamic-address-group \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> destination group dynamic-address-group \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> destination group dynamic-address-group \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> destination group dynamic-address-group \ - -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 \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> source group network-group \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> source group network-group \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> source group network-group \ -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> destination group network-group \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> destination group network-group \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> destination group network-group \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> destination group network-group \ - -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 \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> source group port-group \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> source group port-group \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> source group port-group \ -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> destination group port-group \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> destination group port-group \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> destination group port-group \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> destination group port-group \ - -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 \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> source group domain-group \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> source group domain-group \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> source group domain-group \ -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> destination group domain-group \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> destination group domain-group \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> destination group domain-group \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> destination group domain-group \ - -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 \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> source group mac-group \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> source group mac-group \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> source group mac-group \ -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> destination group mac-group \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> destination group mac-group \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> destination group mac-group \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> destination group mac-group \ - -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 \ 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 \ 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 \ 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 \ 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 \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> icmpv6 type-name \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> icmpv6 type-name \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> icmpv6 type-name \ - -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 \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> inbound-interface name \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> inbound-interface name \ - -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 \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> inbound-interface group \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> inbound-interface 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 \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> outbound-interface name \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> outbound-interface name \ - -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 \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> outbound-interface group \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> outbound-interface 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 \ 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 \ 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 \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> limit rate \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> limit rate \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> limit rate \ - -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 \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> packet-length \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> packet-length \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> packet-length \ -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> packet-length-exclude \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> packet-length-exclude \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> packet-length-exclude \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> packet-length-exclude \ - -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 \ rule \<1-999999\> packet-type [broadcast | host | multicast | other] - -Match based on packet type. -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> protocol [\ | \<0-255\> | all | tcp_udp] -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> protocol [\ | \<0-255\> | all | tcp_udp] -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> protocol [\ | \<0-255\> | all | tcp_udp] -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> protocol [\ | \<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 \ 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 \ 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] \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> tcp flags [not] \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> tcp flags [not] \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> tcp flags [not] \ - -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 \ rule \<1-999999\> state [established | invalid | new | related] - -Match based on packet state. -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> time startdate \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> time startdate \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> time startdate \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> time startdate \ -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> time starttime \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> time starttime \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> time starttime \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> time starttime \ -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> time stopdate \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> time stopdate \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> time stopdate \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> time stopdate \ -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> time stoptime \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> time stoptime \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> time stoptime \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> time stoptime \ -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> time weekdays \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> time weekdays \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> time weekdays \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> time weekdays \ - -Match packets based on time criteria. -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> hop-limit \ \<0-255\> -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> hop-limit \ \<0-255\> -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> hop-limit \ \<0-255\> -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> hop-limit \ \<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 \ rule \<1-999999\> recent count \<1-255\> -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> recent time \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> recent time \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> recent time \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> recent time \ - -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_ADRESSES 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 \ - -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 \ rule \<1-999999\> -``` - -```{opcmd} show firewall ipv6 ipv6-name \ rule \<1-999999\> - -This command will give an overview of a rule in a single rule-set -``` - -```{opcmd} show firewall group \ - -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 \ -``` - -```{opcmd} show log firewall ipv6 [forward | input | output] filter rule \ -``` - -```{opcmd} show log firewall ipv6 name \ 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/md-zone.md b/docs/configuration/firewall/md-zone.md deleted file mode 100644 index bbb93993..00000000 --- a/docs/configuration/firewall/md-zone.md +++ /dev/null @@ -1,201 +0,0 @@ ---- -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 `. - -```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 `` to -``firewall zone ``. -::: - -## 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 \ 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 \ 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 \ 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 \ default-log - -Enable logging of packets that match this zone's default-action (disabled -by default). -``` - -```{cfgcmd} set firewall zone \ 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`: - `set firewall ipv4 name ...` -- For {ref}`IPv6`: - `set firewall ipv6 name ...` - -It is helpful to name the rule-sets in the format -`--` 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 \ from \ firewall name \ -``` - -```{cfgcmd} set firewall zone \ from \ firewall ipv6-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` - -```{cfgcmd} set firewall zone \ default-firewall name \ -``` - -```{cfgcmd} set firewall zone \ default-firewall ipv6-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 \ - -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/md-index.md b/docs/configuration/highavailability/md-index.md deleted file mode 100644 index e26f5791..00000000 --- a/docs/configuration/highavailability/md-index.md +++ /dev/null @@ -1,561 +0,0 @@ ---- -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: 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 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 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 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 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 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 -``` - -% 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/interfaces/md-bonding.md b/docs/configuration/interfaces/md-bonding.md deleted file mode 100644 index 7a07a27c..00000000 --- a/docs/configuration/interfaces/md-bonding.md +++ /dev/null @@ -1,764 +0,0 @@ ---- -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 \ member interface \ - -**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 \ 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 \ 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 \ lacp-rate \ - -**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 \ system-mac \ - -**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 \ hash-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 \ primary \ - -**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 \ arp-monitor interval \ - -**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 \ arp-monitor target \ - -**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 \ evpn es-id \<1-16777215|10-byte ID\> - -``` -```{cfgcmd} set interfaces bonding \ evpn es-sys-mac \ - -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 \ 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 \ - -Show detailed interface information. - -:::{code-block} none -vyos@vyos:~$ show interfaces bonding bond5 -bond5: 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 \ 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/md-bridge.md b/docs/configuration/interfaces/md-bridge.md deleted file mode 100644 index 77775767..00000000 --- a/docs/configuration/interfaces/md-bridge.md +++ /dev/null @@ -1,431 +0,0 @@ ---- -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 \ member interface \ - -**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 \ member interface \ 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 \ member interface \ 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 \ member interface \ 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 \ aging \ - -**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 \ max-age \ - -**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 \ 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 \ 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 \ stp - -Enable {abbr}`STP (Spanning Tree Protocol)` on the bridge interface. -``` - -```{cfgcmd} set interfaces bridge \ forwarding-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 \ hello-time \ - -**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 \ 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 \ 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 \ member interface \ native-vlan \ - -**Configure the native VLAN ID for a specific member interface within a -VLAN-aware bridge.** - -This assigns the specified ```` 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 \ member interface \ allowed-vlan \ - -**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: mtu 1500 master br0 state forwarding -priority 32 cost 100 -4: eth2: mtu 1500 master br0 state forwarding -priority 32 cost 100 -::: -``` - -```{opcmd} show bridge \ 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 \ 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 \ 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/md-dummy.md b/docs/configuration/interfaces/md-dummy.md deleted file mode 100644 index d2d27c5d..00000000 --- a/docs/configuration/interfaces/md-dummy.md +++ /dev/null @@ -1,87 +0,0 @@ ---- -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 \ - -Show detailed interface information. - -:::{code-block} none -vyos@vyos:~$ show interfaces dummy dum0 -dum0: 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/md-ethernet.md b/docs/configuration/interfaces/md-ethernet.md deleted file mode 100644 index eac0b443..00000000 --- a/docs/configuration/interfaces/md-ethernet.md +++ /dev/null @@ -1,515 +0,0 @@ ---- -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 \ 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 \ duplex \ - -**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 \ speed \ - -**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 \ ring-buffer rx \ - -**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 -``` - -```{cfgcmd} set interfaces ethernet \ ring-buffer tx \ - -**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 -``` - - -#### 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 ` -to verify which settings are supported by your hardware and driver. -::: - -**Basic adaptive coalescing** - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing adaptive-rx - -``` -```{cfgcmd} set interfaces ethernet \ 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 \ interrupt-coalescing rx-usecs \<0-16384\> -``` - -```{cfgcmd} set interfaces ethernet \ 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 \ interrupt-coalescing rx-frames \ -``` - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing tx-frames \ - -Generate an RX/TX interrupt only after the specified number of packets -have been received or transmitted. -``` - -**IRQ-specific coalescing** - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing rx-usecs-irq \ -``` - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing rx-frames-irq \ -``` - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing tx-usecs-irq \ -``` - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing tx-frames-irq \ - -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 \ interrupt-coalescing pkt-rate-low \ -``` - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing pkt-rate-high \ - -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 \ interrupt-coalescing rx-usecs-low \ -``` - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing rx-frame-low \ -``` - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing tx-usecs-low \ -``` - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing tx-frame-low \ - -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 \ interrupt-coalescing rx-usecs-high \ -``` - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing rx-frame-high \ -``` - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing tx-usecs-high \ -``` - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing tx-frame-high \ - -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 \ interrupt-coalescing stats-block-usecs \ -``` - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing sample-interval \ - -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 \ interrupt-coalescing cqe-mode-rx -``` - -```{cfgcmd} set interfaces ethernet \ 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 \ interrupt-coalescing tx-aggr-max-bytes \ -``` - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing tx-aggr-max-frames \ -``` - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing tx-aggr-time-usecs \ - -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 \ offload \ - -**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 \ - -Show detailed interface information. - -:::{code-block} none -vyos@vyos:~$ show interfaces ethernet eth0 -eth0: 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 \ 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 \ 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 \ 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/md-geneve.md b/docs/configuration/interfaces/md-geneve.md deleted file mode 100644 index 1fce1119..00000000 --- a/docs/configuration/interfaces/md-geneve.md +++ /dev/null @@ -1,105 +0,0 @@ ---- -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 \ - -Configure the remote endpoint IP address for the Geneve tunnel. -``` - -```{cfgcmd} set interfaces geneve gnv0 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 \ 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/md-index.md b/docs/configuration/interfaces/md-index.md deleted file mode 100644 index 9082cd80..00000000 --- a/docs/configuration/interfaces/md-index.md +++ /dev/null @@ -1,26 +0,0 @@ -# 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/md-l2tpv3.md b/docs/configuration/interfaces/md-l2tpv3.md deleted file mode 100644 index 324840fa..00000000 --- a/docs/configuration/interfaces/md-l2tpv3.md +++ /dev/null @@ -1,170 +0,0 @@ ---- -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 \ encapsulation \ - -**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 \ source-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 \ remote \ - -**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 \ session-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 \ peer-session-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 \ tunnel-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 \ peer-tunnel-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/md-loopback.md b/docs/configuration/interfaces/md-loopback.md deleted file mode 100644 index 72f14c16..00000000 --- a/docs/configuration/interfaces/md-loopback.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -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: 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/md-macsec.md b/docs/configuration/interfaces/md-macsec.md deleted file mode 100644 index b3c70362..00000000 --- a/docs/configuration/interfaces/md-macsec.md +++ /dev/null @@ -1,319 +0,0 @@ ---- -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 \ security cipher \ - -**Configure the cipher suite for the MACsec interface.** - -This configuration parameter is mandatory. -``` - -```{cfgcmd} set interfaces macsec \ 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 \ source-interface \ - -**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 \ security static 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 \ security static peer \ mac \ - -**Configure the MAC address associated with the MACsec peer.** -``` - -```{cfgcmd} set interfaces macsec \ security static peer \ 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 \ security static 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 \ security mka cak \ - -**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 \ security mka ckn \ - -Configure the {abbr}`CKN (MACsec Connectivity Association Key Name)` for the -MACsec interface. -``` - -```{cfgcmd} set interfaces macsec \ security mka 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 \ security replay-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 \ - -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 \ - -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/md-openvpn-examples.md b/docs/configuration/interfaces/md-openvpn-examples.md deleted file mode 100644 index 817e6868..00000000 --- a/docs/configuration/interfaces/md-openvpn-examples.md +++ /dev/null @@ -1,769 +0,0 @@ -# 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. - -![](/_static/images/openvpn_site2site_diagram.webp) - -## 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 `. 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 # The output of 'run show pki certificate 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 # The output of 'run show pki certificate 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 ` 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 -``` - -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 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 - - - -# 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 - -``` - - -### Active Directory - -A sample configuration file is shown below: - -``` none - - # 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 - - - - # 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 - - BaseDN "OU=Groups,DC=example,DC=com" - SearchFilter "(|(cn=VPN))" - MemberAttribute memberOf - - -``` - -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 - - URL ldap://dc01.example.com - BindDN CN=SA_OPENVPN,OU=ServiceAccounts,DC=example,DC=com - Password ThisIsTopSecret - Timeout 15 - TLSEnable no - FollowReferrals no - - - - BaseDN "DC=example,DC=com" - SearchFilter "sAMAccountName=%u" - RequireGroup false - -``` - -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`. - -### 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 - - - ------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----- - - - - ------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----- - - - - ------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----- - - -``` - -When prompted, log in with the username and password. diff --git a/docs/configuration/interfaces/md-openvpn.md b/docs/configuration/interfaces/md-openvpn.md deleted file mode 100644 index 170c585d..00000000 --- a/docs/configuration/interfaces/md-openvpn.md +++ /dev/null @@ -1,614 +0,0 @@ -(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 \ authentication password \ - - **Configure the password for the** ``auth-user-pass`` **authentication method.** - - This option applies only to OpenVPN clients. -``` - - -```{cfgcmd} set interfaces openvpn \ authentication username \ - -**Configure the username for the** ``auth-user-pass`` **authentication method.** - -This option applies only to OpenVPN clients. -``` - - -```{cfgcmd} set interfaces openvpn \ description \ - -Configure the description for the OpenVPN interface. -``` - - -```{cfgcmd} set interfaces openvpn \ device-type \ - -**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 \ disable - -Disable the specific OpenVPN interface. -``` - - -```{cfgcmd} set interfaces openvpn \ 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 \ 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 \ 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 \ hash \ - -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 \ keep-alive failure-count \ - -**Configure the number of tolerated keepalive packet failures.** - -Default: 60 consecutive failures. -``` - - -```{cfgcmd} set interfaces openvpn \ keep-alive interval \ - -**Configure the frequency, in seconds, at which keepalive packets are sent.** - -Default: 10 seconds. -``` - - -```{cfgcmd} set interfaces openvpn \ local-address \ - -Configure the local tunnel IP address for ``site-to-site`` mode. -``` - - -```{cfgcmd} set interfaces openvpn \ local-host \ - -**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 \ local-port \ - -Configure the local port to accept connections. -``` - - -```{cfgcmd} set interfaces openvpn \ mirror egress \ - -Configure mirroring of outgoing traffic from this OpenVPN interface to the -designated monitor interface. -``` - - -```{cfgcmd} set interfaces openvpn \ mirror ingress \ - -Configure mirroring of incoming traffic from this OpenVPN interface to the -designated monitor interface. -``` - - -```{cfgcmd} set interfaces openvpn \ mode \ - -**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: - -- {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 \ 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 \ openvpn-option \ - -**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 \ 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 \ protocol \ - -**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 \ redirect \ - -Enable redirection of incoming packets to the specified interface. -``` - - -```{cfgcmd} set interfaces openvpn \ remote-address \ - -Configure the remote tunnel IP address for site-to-site mode. -``` - - -```{cfgcmd} set interfaces openvpn \ remote-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 \ remote-port \ - -Configure the remote port to connect to the server. -``` - - -```{cfgcmd} set interfaces openvpn \ replace-default-route - -Configure the OpenVPN tunnel as the default route. -``` - - -```{cfgcmd} set interfaces openvpn \ server bridge disable - -Disable the given instance. -``` - - -```{cfgcmd} set interfaces openvpn \ server bridge gateway \ - -Configure the gateway IP address. -``` - - -```{cfgcmd} set interfaces openvpn \ server bridge start \ - -Configure the first IP address in the pool to allocate to connecting clients. -``` - - -```{cfgcmd} set interfaces openvpn \ server bridge stop \ - -Configure the last IP address in the pool to allocate to connecting clients. -``` - - -```{cfgcmd} set interfaces openvpn \ server bridge subnet-mask \ - -Configure the subnet mask pushed to dynamic clients. -``` - - -```{cfgcmd} set interfaces openvpn \ server client \ - -Configure the Common Name (CN) specified in the client certificate. -``` - - -```{cfgcmd} set interfaces openvpn \ server client \ disable - -Disable the client connection. -``` - - -```{cfgcmd} set interfaces openvpn \ server client \ ip \ - -Configure the IPv4/IPv6 address for the client. -``` - - -```{cfgcmd} set interfaces openvpn \ server client \ push-route \ - -Configure a route to be pushed to the specific client. -``` - - -```{cfgcmd} set interfaces openvpn \ server client \ 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 \ server client-ip-pool start \ - -Configure the first IP address in the subnet's IPv4 pool to be dynamically -allocated to connecting clients. -``` - - -```{cfgcmd} set interfaces openvpn \ server client-ip-pool stop \ - -Configure the last IP address in the subnet's IPv4 pool to be dynamically -allocated to connecting clients. -``` - - -```{cfgcmd} set interfaces openvpn \ server client-ip-pool subnet \ - -**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 \ server client-ipv6-pool base \ - -Configure the IPv6 address pool for dynamic assignment to clients. -``` - - -```{cfgcmd} set interfaces openvpn \ server domain-name \ - -Configure the DNS suffix to be pushed to all clients. -``` - - -```{cfgcmd} set interfaces openvpn \ server max-connections \<1-4096\> - -Configure the maximum number of client connections. -``` - - -```{cfgcmd} set interfaces openvpn \ server mfa totp challenge \ - -If enabled, openvpn-otp expects a password as a result of the challenge/ -response protocol. -``` - - -```{cfgcmd} set interfaces openvpn \ 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 \ server mfa totp drift \<1-65535\> - -**Configure the time drift in seconds.** - -Default: 0. -``` - - -```{cfgcmd} set interfaces openvpn \ server mfa totp slop \<1-65535\> - -**Configure the allowed clock slop in seconds.** - -Default: 180. -``` - - -```{cfgcmd} set interfaces openvpn \ 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 \ server name-server \ - -Define the client DNS configuration to be used with the connection. -``` - - -```{cfgcmd} set interfaces openvpn \ server push-route \ - -Configure the route to be pushed to all clients. -``` - - -```{cfgcmd} set interfaces openvpn \ server reject-unconfigured-client - -Reject connections from clients that are not explicitly configured. -``` - - -```{cfgcmd} set interfaces openvpn \ server subnet \ - -**Configure the IPv4 or IPv6 network.** - -This parameter is mandatory when operating in server mode. -``` - - -```{cfgcmd} set interfaces openvpn \ 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 \ shared-secret-key \ - -Configure the static secret key for a site-to-site OpenVPN connection. -``` -```{cfgcmd} set interfaces openvpn \ tls auth-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 `` to generate -the key. -``` -```{cfgcmd} set interfaces openvpn \ tls ca-certificate \ - -Configure the Certificate Authority chain in the PKI configuration. -``` -```{cfgcmd} set interfaces openvpn \ tls certificate \ - -Configure the certificate name in the PKI configuration. -``` -```{cfgcmd} set interfaces openvpn \ 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 \ tls dh-params - -Configure Diffie-Hellman parameters for server mode. -``` -```{cfgcmd} set interfaces openvpn \ tls peer-fingerprint \ - -Configure the peer certificate SHA256 fingerprint for site-to-site mode. -``` -```{cfgcmd} set interfaces openvpn \ tls role \ - -**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 \ 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 \ use-lzo-compression - -Configure fast LZO compression on this TUN/TAP interface. -``` -```{cfgcmd} set interfaces openvpn \ vrf \ - -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 \ - -Show logs for the specific OpenVPN interface. -``` -```{opcmd} reset openvpn client \ - -Reset the specified OpenVPN client. -``` -```{opcmd} reset openvpn interface \ - -Reset the OpenVPN process on the specified interface. -``` -```{opcmd} generate openvpn client-config interface \ ca \ certificate \ - -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/md-pppoe.md b/docs/configuration/interfaces/md-pppoe.md deleted file mode 100644 index b79f41a2..00000000 --- a/docs/configuration/interfaces/md-pppoe.md +++ /dev/null @@ -1,419 +0,0 @@ ---- -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 \ access-concentrator \ - -**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 \ authentication 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 \ authentication 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 \ 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 \ 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 \ default-route-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 \ 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 \ idle-timeout \ - -**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 \ holdoff \ - -**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 \ local-address \ - -**Configure the local endpoint IP address for PPPoE sessions.** - -By default, this IP address is negotiated. -``` - -```{cfgcmd} set interfaces pppoe \ no-peer-dns - -Disable the installation of advertised DNS nameservers on the local system. -``` - -```{cfgcmd} set interfaces pppoe \ remote-address \ - -**Configure the remote endpoint IP address for PPPoE sessions.** - -By default, this IP address is negotiated. -``` - -```{cfgcmd} set interfaces pppoe \ service-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 \ 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 \ ip adjust-mss \ - -**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 adjust-mss `` syntax. -::: -``` - -```{cfgcmd} set interfaces pppoe \ 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 \ ip source-validation \ - -**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 \ ipv6 address autoconf - -Enable IPv6 address assignment via {abbr}`SLAAC (Stateless Address -Auto-Configuration)` on this interface. -``` - -```{cfgcmd} set interfaces pppoe \ ipv6 adjust-mss \ - -**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 adjust-mss `` syntax. -::: -``` - -```{cfgcmd} set interfaces pppoe \ 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 \ - -Show detailed information about a specific PPPoE interface. - -:::{code-block} none -vyos@vyos:~$ show interfaces pppoe pppoe0 -pppoe0: 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 \ 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 \ - -Disconnect the specified interface. -``` - -```{opcmd} connect 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 `::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/md-pseudo-ethernet.md b/docs/configuration/interfaces/md-pseudo-ethernet.md deleted file mode 100644 index fc8833eb..00000000 --- a/docs/configuration/interfaces/md-pseudo-ethernet.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -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 \ source-interface \ - -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/md-sstp-client.md b/docs/configuration/interfaces/md-sstp-client.md deleted file mode 100644 index da98aecd..00000000 --- a/docs/configuration/interfaces/md-sstp-client.md +++ /dev/null @@ -1,170 +0,0 @@ ---- -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 \ 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 \ default-route-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 \ no-peer-dns - -Disable the installation of advertised DNS nameservers on the local system. -``` - -```{cfgcmd} set interfaces sstpc \ server \ - -**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 \ ip adjust-mss \ - -**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 adjust-mss `` syntax. -::: -``` - -```{cfgcmd} set interfaces sstpc \ 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 \ ip source-validation \ - -**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 \ - -Show detailed information about the specified interface. - -:::{code-block} none -vyos@vyos:~$ show interfaces sstpc sstpc10 -sstpc10: 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 \ - -Disconnect the specified interface. -``` - -```{opcmd} connect interface \ - -Initiate a session on the specified interface. -``` \ No newline at end of file diff --git a/docs/configuration/interfaces/md-tunnel.md b/docs/configuration/interfaces/md-tunnel.md deleted file mode 100644 index 9c9885d2..00000000 --- a/docs/configuration/interfaces/md-tunnel.md +++ /dev/null @@ -1,309 +0,0 @@ ---- -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) ` 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: 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/md-virtual-ethernet.md b/docs/configuration/interfaces/md-virtual-ethernet.md deleted file mode 100644 index dee1b332..00000000 --- a/docs/configuration/interfaces/md-virtual-ethernet.md +++ /dev/null @@ -1,119 +0,0 @@ ---- -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 \ - -Show detailed interface information. - -:::{code-block} none -vyos@vyos:~$ show interfaces virtual-ethernet veth11 -10: veth11@veth10: 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/md-vti.md b/docs/configuration/interfaces/md-vti.md deleted file mode 100644 index dbd2c88c..00000000 --- a/docs/configuration/interfaces/md-vti.md +++ /dev/null @@ -1,121 +0,0 @@ -(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 \ mirror egress \ - -Configure mirroring of outgoing traffic from the specified VTI to the -designated monitor interface. -``` - -```{cfgcmd} set interfaces vti \ mirror ingress \ - -Configure mirroring of incoming traffic from the specified VTI to the -designated monitor interface. -``` - -```{cfgcmd} set interfaces vti \ redirect \ - -Enable redirection of incoming packets to the specified interface. -``` - -```{cmdincludemd} /_include/interface-vrf.txt -:var0: vti -:var1: vti0 -``` - - -## Operation - -```{opcmd} show interfaces vti \ - -Show the operational status and traffic statistics for the specified VTI. -``` - -```{opcmd} show interfaces vti \ 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: - - -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/md-vxlan.md b/docs/configuration/interfaces/md-vxlan.md deleted file mode 100644 index 8dae75ff..00000000 --- a/docs/configuration/interfaces/md-vxlan.md +++ /dev/null @@ -1,373 +0,0 @@ ---- -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 \ vni \ - -**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 \ 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 \ source-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 \ 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 \ 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 \ 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 \ parameters nolearning - -Disable {abbr}`SLLA (Source Link-Layer Address)` and IP address learning on -the VXLAN interface. -``` - -```{cfgcmd} set interfaces vxlan \ 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 \ remote \ - -**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 \ source-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 \ group \ - -**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 \ vlan-to-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 port `. diff --git a/docs/configuration/interfaces/md-wireguard.md b/docs/configuration/interfaces/md-wireguard.md deleted file mode 100644 index 121d1df0..00000000 --- a/docs/configuration/interfaces/md-wireguard.md +++ /dev/null @@ -1,434 +0,0 @@ ---- -lastproofread: '2026-03-02' ---- - -(wireguard)= - -# WireGuard - -WireGuard is an extremely simple, fast, and modern VPN that utilizes -state-of-the-art cryptography. See 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 \ - -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 \ 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 \ 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 \ 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: -endpoint: -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 \ - -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 \ interface \ server \ address \ - -**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 ```` 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/md-wireless.md b/docs/configuration/interfaces/md-wireless.md deleted file mode 100644 index 9e6b7c99..00000000 --- a/docs/configuration/interfaces/md-wireless.md +++ /dev/null @@ -1,923 +0,0 @@ ---- -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 \ - -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 \ channel \ - -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 \ 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 \ 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 \ 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 \ max-stations \ - -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 \ 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 \ 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 \ mode \ - -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 \ physical-device \ - -Wireless hardware device used as underlay radio. - -This defaults to phy0. -``` - -```{cfgcmd} set interfaces wireless \ reduce-transmit-power \ - -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 \ ssid \ - -SSID to be used in IEEE 802.11 management frames -``` - -```{cfgcmd} set interfaces wireless \ type \ - -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 \ capabilities require-ht - -``` -```{cfgcmd} set interfaces wireless \ capabilities require-vht -``` - -```{cfgcmd} set interfaces wireless \ 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 \ capabilities ht 40mhz-incapable - -Device is incapable of 40 MHz, do not advertise. This sets ``[40-INTOLERANT]`` -``` - -```{cfgcmd} set interfaces wireless \ capabilities ht auto-powersave - -WMM-PS Unscheduled Automatic Power Save Delivery [U-APSD] -``` - -```{cfgcmd} set interfaces wireless \ capabilities ht channel-set-width \ - -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 \ capabilities ht delayed-block-ack - -Enable HT-delayed Block Ack ``[DELAYED-BA]`` -``` - -```{cfgcmd} set interfaces wireless \ capabilities ht dsss-cck-40 - -DSSS/CCK Mode in 40 MHz, this sets ``[DSSS_CCK-40]`` -``` - -```{cfgcmd} set interfaces wireless \ capabilities ht greenfield - -This enables the greenfield option which sets the ``[GF]`` option -``` - -```{cfgcmd} set interfaces wireless \ capabilities ht ldpc - -Enable LDPC coding capability -``` - -```{cfgcmd} set interfaces wireless \ capabilities ht lsig-protection - -Enable L-SIG TXOP protection capability -``` - -```{cfgcmd} set interfaces wireless \ capabilities ht max-amsdu \<3839 | 7935\> - -Maximum A-MSDU length 3839 (default) or 7935 octets -``` - -```{cfgcmd} set interfaces wireless \ capabilities ht short-gi \<20 | 40\> - -Short GI capabilities for 20 and 40 MHz -``` - -```{cfgcmd} set interfaces wireless \ capabilities ht smps \ - -Spatial Multiplexing Power Save (SMPS) settings -``` - -```{cfgcmd} set interfaces wireless \ capabilities ht stbc rx \ - -Enable receiving PPDU using STBC (Space Time Block Coding) -``` - -```{cfgcmd} set interfaces wireless \ capabilities ht stbc tx - -Enable sending PPDU using STBC (Space Time Block Coding) -``` - -##### VHT (Very High Throughput) capabilities (802.11ac) - -```{cfgcmd} set interfaces wireless \ capabilities vht antenna-count \ -``` - -% -% Number of antennas on this card - -```{cfgcmd} set interfaces wireless \ capabilities vht antenna-pattern-fixed - -Set if antenna pattern does not change during the lifetime of an association -``` - -```{cfgcmd} set interfaces wireless \ capabilities vht beamform \ - -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 \ capabilities vht center-channel-freq \ \ - -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) - -\ must be from 34 - 173. For 80 MHz channels it should be channel + 6. -``` - -```{cfgcmd} set interfaces wireless \ 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 \ capabilities vht ldpc - -Enable LDPC (Low Density Parity Check) coding capability -``` - -```{cfgcmd} set interfaces wireless \ capabilities vht link-adaptation - -VHT link adaptation capabilities -``` - -```{cfgcmd} set interfaces wireless \ capabilities vht max-mpdu \ - -Increase Maximum MPDU length to 7991 or 11454 octets (default 3895 octets) -``` - -```{cfgcmd} set interfaces wireless \ capabilities vht max-mpdu-exp \ - -Set the maximum length of A-MPDU pre-EOF padding that the station can -receive -``` - -```{cfgcmd} set interfaces wireless \ capabilities vht short-gi \<80 | 160\> - -Short GI capabilities -``` - -```{cfgcmd} set interfaces wireless \ capabilities vht stbc rx \ - -Enable receiving PPDU using STBC (Space Time Block Coding) -``` - -```{cfgcmd} set interfaces wireless \ capabilities vht stbc tx - -Enable sending PPDU using STBC (Space Time Block Coding) -``` - -```{cfgcmd} set interfaces wireless \ capabilities vht tx-powersave - -Enable VHT TXOP Power Save Mode -``` - -```{cfgcmd} set interfaces wireless \ capabilities vht vht-cf - -Station supports receiving VHT variant HT Control field -``` - -##### HE (High Efficiency) capabilities (802.11ax) - -```{cfgcmd} set interfaces wireless \ 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 \ capabilities he beamform \ - -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 \ capabilities he bss-color \ - -BSS coloring helps to prevent channel jamming when multiple APs use -the same channels. - -Valid values are 1..63 -``` - -```{cfgcmd} set interfaces wireless \ capabilities he center-channel-freq \ \ - -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) - -\ 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 \ capabilities he channel-set-width \ - -\ 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 \ capabilities he coding-scheme \ - -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. - -\ 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: 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: 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 \ -``` - -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: 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 \ 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 \ 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 \ 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/md-wwan.md b/docs/configuration/interfaces/md-wwan.md deleted file mode 100644 index e8121f28..00000000 --- a/docs/configuration/interfaces/md-wwan.md +++ /dev/null @@ -1,355 +0,0 @@ ---- -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 \ 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 \ - -Show the operational status and traffic statistics for the specified WWAN -interface. - -:::{code-block} none -vyos@vyos:~$ show interfaces wwan wwan0 -wwan0: 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 \ 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 \ 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 \ 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 \ 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 \ 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 \ model - -Show WWAN module model. - -:::{code-block} none -vyos@vyos:~$ show interfaces wwan wwan0 model -Model: 'MC7710' -::: -``` - -```{opcmd} show interfaces wwan \ 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 \ 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 \ 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 \ 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/md-haproxy.md b/docs/configuration/loadbalancing/md-haproxy.md deleted file mode 100644 index d60c5248..00000000 --- a/docs/configuration/loadbalancing/md-haproxy.md +++ /dev/null @@ -1,510 +0,0 @@ ---- -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 \ listen-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 \ port \ - -Create service ** to listen on \ -``` - -```{cfgcmd} set load-balancing haproxy service \ mode \ - -Configure service ** mode TCP or HTTP -``` - -```{cfgcmd} set load-balancing haproxy service \ backend \ - -Configure service ** to use the backend \ -``` - -```{cfgcmd} set load-balancing haproxy service \ ssl certificate \ - -Set the SSL certificate \ for service \. You can define -multiple certificates. -``` - -```{cfgcmd} set load-balancing haproxy service \ http-response-headers \ value \ - -Set custom HTTP headers to include in all responses. -``` - -```{cfgcmd} set load-balancing haproxy service \ logging facility \ 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 \ timeout client \ - -Set the maximum inactivity time on the client side for this service. -Value range 1-3600 seconds. -``` - -```{cfgcmd} set load-balancing haproxy service \ http-compression algorithm \ - -Set the compression algorithm to be used when compressing HTTP responses. -``` - -```{cfgcmd} set load-balancing haproxy service \ http-compression 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 \ rule \ domain-name \ - -Match domain name -``` - -````{cfgcmd} set load-balancing haproxy service \ rule \ ssl \ - -```{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 \ rule \ url-path \ \ - -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 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 \ rule \ set backend \ - -Assign a specific backend to a rule -``` - -```{cfgcmd} set load-balancing haproxy service \ rule \ redirect-location \ - -Redirect URL to a new location. -``` - -### Backend - -````{cfgcmd} set load-balancing haproxy backend \ 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 \ mode \ - -Configure backend ** mode TCP or HTTP. -``` - -```{cfgcmd} set load-balancing haproxy backend \ server \ address \ - -Set the address of the backend server that receives incoming traffic. -``` - -```{cfgcmd} set load-balancing haproxy backend \ server \ port \ - -Set the address of the backend port. -``` - -```{cfgcmd} set load-balancing haproxy backend \ server \ check - -Active health check backend server. -``` - -```{cfgcmd} set load-balancing haproxy backend \ server \ check 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 \ server \ send-proxy - -Send a Proxy Protocol version 1 header (text format). -``` - -```{cfgcmd} set load-balancing haproxy backend \ server \ send-proxy-v2 - -Send a Proxy Protocol version 2 header (binary format). -``` - -```{cfgcmd} set load-balancing haproxy backend \ ssl ca-certificate \ - -Use SSL encryption for backend requests and authenticate the backend -against ````. -``` - -```{cfgcmd} set load-balancing haproxy backend \ ssl no-verify - -Use SSL encryption for backend requests without validating the server -certificate. -``` - -```{cfgcmd} set load-balancing haproxy backend \ http-response-headers \ value \ - -Set custom HTTP headers to include in all responses from the backend. -``` - -```{cfgcmd} set load-balancing haproxy backend \ logging facility \ 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 \ timeout check \ - -Set the timeout in seconds for established connections. -Value range 1-3600 seconds. -``` -```{cfgcmd} set load-balancing haproxy backend \ timeout connect \ - -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 \ timeout server \ - -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 \ - -Limit maximum number of connections -``` - - -```{cfgcmd} set load-balancing haproxy global-parameters ssl-bind-ciphers \ - -Limit the cipher algorithms allowed during SSL/TLS handshake. -``` - - -```{cfgcmd} set load-balancing haproxy global-parameters tls-version-min \ - -Specify the minimum required TLS version 1.2 or 1.3 -``` - - -```{cfgcmd} set load-balancing haproxy global-parameters logging facility \ 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 \ - -Set the timeout in seconds for established connections. -Value range 1-3600 seconds. Default is 5 seconds. -``` - - -```{cfgcmd} set load-balancing haproxy timeout client \ - -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 \ - -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 \ - -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 \ 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 \ http-check method \ - -Set the HTTP method: ``OPTION``, ``GET``, ``POST``, or ``PUT``. -``` - - -```{cfgcmd} set load-balancing haproxy backend \ http-check uri \ - -Set the endpoint to use for health checks. -``` - - -````{cfgcmd} set load-balancing haproxy backend \ http-check expect \ - -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 \ health-check \ - -```{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/md-index.md b/docs/configuration/loadbalancing/md-index.md deleted file mode 100644 index 3241edb7..00000000 --- a/docs/configuration/loadbalancing/md-index.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -lastproofread: '2026-04-06' ---- - -(load-balancing)= - -# Load-balancing - -```{toctree} -:includehidden: true -:maxdepth: 1 - -wan -haproxy -``` diff --git a/docs/configuration/loadbalancing/md-wan.md b/docs/configuration/loadbalancing/md-wan.md deleted file mode 100644 index a19bbfae..00000000 --- a/docs/configuration/loadbalancing/md-wan.md +++ /dev/null @@ -1,306 +0,0 @@ ---- -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 limit -``` - -- `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 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 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 -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 nexthop -``` - -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 failure-count -set load-balancing wan interface-health success-count -``` - -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 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/md-index.md b/docs/configuration/md-index.md deleted file mode 100644 index 3e215502..00000000 --- a/docs/configuration/md-index.md +++ /dev/null @@ -1,23 +0,0 @@ -# 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/nat/md-cgnat.md b/docs/configuration/nat/md-cgnat.md deleted file mode 100644 index 914a466b..00000000 --- a/docs/configuration/nat/md-cgnat.md +++ /dev/null @@ -1,200 +0,0 @@ -(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 \ external-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 \ per-user-limit port \ - -Set external source port limits that will be allocated to each subscriber -individually. The default value is 2000. -``` - - -```{cfgcmd} set nat cgnat pool external \ 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 \ range [address range | network] - -Set the range of internal IP addresses for the CGNAT pool. -``` - - -```{cfgcmd} set nat cgnat rule \ source pool \ - -Set the rule for the source pool. -``` - - -```{cfgcmd} set nat cgnat rule \ translation pool \ - -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 \ - -Show all allocations for an external IP address -``` - -```{opcmd} show nat cgnat allocation internal-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/md-index.md b/docs/configuration/nat/md-index.md deleted file mode 100644 index 35e5d32b..00000000 --- a/docs/configuration/nat/md-index.md +++ /dev/null @@ -1,13 +0,0 @@ -(nat)= - -# NAT - -```{toctree} -:includehidden: true -:maxdepth: 1 - -nat44 -nat64 -nat66 -cgnat -``` diff --git a/docs/configuration/nat/md-nat44.md b/docs/configuration/nat/md-nat44.md deleted file mode 100644 index 4f5bd580..00000000 --- a/docs/configuration/nat/md-nat44.md +++ /dev/null @@ -1,788 +0,0 @@ -(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 \ load-balance hash [source-address | destination-address | source-port | destination-port | random] -``` - -```{cfgcmd} set nat [source | destination] rule \ load-balance backend \ 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: - - -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 comming 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/md-nat64.md b/docs/configuration/nat/md-nat64.md deleted file mode 100644 index c1b1c994..00000000 --- a/docs/configuration/nat/md-nat64.md +++ /dev/null @@ -1,73 +0,0 @@ -(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/md-nat66.md b/docs/configuration/nat/md-nat66.md deleted file mode 100644 index 1cbe3317..00000000 --- a/docs/configuration/nat/md-nat66.md +++ /dev/null @@ -1,243 +0,0 @@ -(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/pki/md-index.md b/docs/configuration/pki/md-index.md deleted file mode 100644 index e7d793de..00000000 --- a/docs/configuration/pki/md-index.md +++ /dev/null @@ -1,583 +0,0 @@ ---- -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 \ - -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 \ - -Create a new subordinate {abbr}`CA (Certificate Authority)` and sign it using -the private key referenced by ca-name. -``` - -```{opcmd} generate pki ca sign \ install \ - -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 \ - -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 \ - -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 \ - -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 \ install \ - -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 \ - -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 \ - -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 \ - -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 \ - -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 \ 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 \ crl - -Certificate revocation list in PEM format. -``` - -```{cfgcmd} set pki ca \ description - -A human readable description what this CA is about. -``` - -```{cfgcmd} set pki ca \ 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 \ 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 \ 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 \ description - -A human readable description what this certificate is about. -``` - -```{cfgcmd} set pki certificate \ 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 \ 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 \ 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 \ file \ - -Import the public CA certificate from the defined file to VyOS CLI. -``` - -```{opcmd} import pki ca \ 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 \ file \ - -Import the certificate from the file to VyOS CLI. -``` - -```{opcmd} import pki certificate \ key-file \ - -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 \ file \ - -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 \ acme domain-name \ - -Domain names to apply, multiple domain-names can be specified. - -This is a mandatory option -``` - -```{cfgcmd} set pki certificate \ acme email \ - -Email used for registration and recovery contact. - -This is a mandatory option -``` - -```{cfgcmd} set pki certificate \ acme listen-address \ - -The address the server listens to during http-01 challenge -``` - -```{cfgcmd} set pki certificate \ acme rsa-key-size \<2048 | 3072 | 4096\> - -Size of the RSA key. - -This options defaults to 2048 -``` - -```{cfgcmd} set pki certificate \ acme 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 \ - -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 \ - -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/policy/md-access-list.md b/docs/configuration/policy/md-access-list.md deleted file mode 100644 index c3a92e56..00000000 --- a/docs/configuration/policy/md-access-list.md +++ /dev/null @@ -1,70 +0,0 @@ -# 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 \ - -This command creates the new access list policy, where `` must be -a number from 1 to 2699. -``` - -```{cfgcmd} set policy access-list \ description \ - -Set description for the access list. -``` - -```{cfgcmd} set policy access-list \ rule \<1-65535\> action \ - -This command creates a new rule in the access list and defines an action. -``` - -```{cfgcmd} set policy access-list \ rule \<1-65535\> \ \ - -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 \ - -This command creates the new IPv6 access list, identified by `` -``` - -```{cfgcmd} set policy access-list6 \ description \ - -Set description for the IPv6 access list. -``` - -```{cfgcmd} set policy access-list6 \ rule \<1-65535\> action \ - -This command creates a new rule in the IPv6 access list and defines an -action. -``` - -```{cfgcmd} set policy access-list6 \ rule \<1-65535\> source \ - -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/md-as-path-list.md b/docs/configuration/policy/md-as-path-list.md deleted file mode 100644 index 1fcece91..00000000 --- a/docs/configuration/policy/md-as-path-list.md +++ /dev/null @@ -1,29 +0,0 @@ -# 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 \ - -Create as-path-policy identified by name ``. -``` -```{cfgcmd} set policy as-path-list \ description \ - -Set description for as-path-list policy. -``` -```{cfgcmd} set policy as-path-list \ rule \<1-65535\> action \ - -Set action to take on entries matching this rule. -``` -```{cfgcmd} set policy as-path-list \ rule \<1-65535\> description \ - -Set description for rule. -``` -```{cfgcmd} set policy as-path-list \ rule \<1-65535\> regex \ - -Regular expression to match against an AS path. For example "64501 64502". -``` \ No newline at end of file diff --git a/docs/configuration/policy/md-community-list.md b/docs/configuration/policy/md-community-list.md deleted file mode 100644 index bdcf4140..00000000 --- a/docs/configuration/policy/md-community-list.md +++ /dev/null @@ -1,29 +0,0 @@ -# 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 \ - -Creat community-list policy identified by name ``. -``` -```{cfgcmd} set policy community-list \ description \ - -Set description for community-list policy. -``` -```{cfgcmd} set policy community-list \ rule \<1-65535\> action \ - -Set action to take on entries matching this rule. -``` -```{cfgcmd} set policy community-list \ rule \<1-65535\> description \ - -Set description for rule. -``` -```{cfgcmd} set policy community-list \ rule \<1-65535\> regex \ - -Regular expression to match against a community-list. -``` \ No newline at end of file diff --git a/docs/configuration/policy/md-examples.md b/docs/configuration/policy/md-examples.md deleted file mode 100644 index 2b5d54d2..00000000 --- a/docs/configuration/policy/md-examples.md +++ /dev/null @@ -1,205 +0,0 @@ -# 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 addreess on VyOS eth1 from ISP1 -- `192.168.2.254` IP addreess 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/md-extcommunity-list.md b/docs/configuration/policy/md-extcommunity-list.md deleted file mode 100644 index 5247c13c..00000000 --- a/docs/configuration/policy/md-extcommunity-list.md +++ /dev/null @@ -1,33 +0,0 @@ -# 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 \ - -Creat extcommunity-list policy identified by name \. -``` -```{cfgcmd} set policy extcommunity-list \ description \ - -Set description for extcommunity-list policy. -``` -```{cfgcmd} set policy extcommunity-list \ rule \<1-65535\> action \ - -Set action to take on entries matching this rule. -``` -```{cfgcmd} set policy extcommunity-list \ rule \<1-65535\> description \ - -Set description for rule. -``` -```{cfgcmd} set policy extcommunity-list \ rule \<1-65535\> regex \ - -Regular expression to match against an extended community list, where text -could be: -* \: Extended community list regular expression. -* \: Route Target regular expression. -* \: Site of Origin regular expression. -``` \ No newline at end of file diff --git a/docs/configuration/policy/md-index.md b/docs/configuration/policy/md-index.md deleted file mode 100644 index f919e70a..00000000 --- a/docs/configuration/policy/md-index.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -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 - -## 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/md-large-community-list.md b/docs/configuration/policy/md-large-community-list.md deleted file mode 100644 index 23b9a85a..00000000 --- a/docs/configuration/policy/md-large-community-list.md +++ /dev/null @@ -1,29 +0,0 @@ -# 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 \ - -Create large-community-list policy identified by name ``. -``` -```{cfgcmd} set policy large-community-list \ description \ - -Set description for large-community-list policy. -``` -```{cfgcmd} set policy large-community-list \ rule \<1-65535\> action \ - -Set action to take on entries matching this rule. -``` -```{cfgcmd} set policy large-community-list \ rule \<1-65535\> description \ - -Set description for rule. -``` -```{cfgcmd} set policy large-community-list \ rule \<1-65535\> regex \ - -Regular expression to match against a large community list. -``` \ No newline at end of file diff --git a/docs/configuration/policy/md-local-route.md b/docs/configuration/policy/md-local-route.md deleted file mode 100644 index 527a2380..00000000 --- a/docs/configuration/policy/md-local-route.md +++ /dev/null @@ -1,100 +0,0 @@ -# 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 \ - -Set the VRF to use for forwarding matching packets. -``` - -```{cfgcmd} set policy local-route rule \<1-32765\> 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 \ - -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 \ - -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 \ - -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 \ - -Set the VRF to use for forwarding matching packets. -``` - -```{cfgcmd} set policy local-route6 rule \<1-32765\> 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 \ - -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 \ - -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 \ - -Match specified inbound interface. -``` \ No newline at end of file diff --git a/docs/configuration/policy/md-prefix-list.md b/docs/configuration/policy/md-prefix-list.md deleted file mode 100644 index eb827c77..00000000 --- a/docs/configuration/policy/md-prefix-list.md +++ /dev/null @@ -1,152 +0,0 @@ -# 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 \ - -This command creates the new prefix-list policy, identified by ``. -``` - -```{cfgcmd} set policy prefix-list \ description \ - -Set description for the prefix-list policy. -``` - -```{cfgcmd} set policy prefix-list \ rule \<1-65535\> action \ - -This command creates a new rule in the prefix-list and defines an action. -``` - -```{cfgcmd} set policy prefix-list \ rule \<1-65535\> description \ - -Set description for rule in the prefix-list. -``` - -```{cfgcmd} set policy prefix-list \ rule \<1-65535\> prefix \ - -Prefix to match against. -``` - -```{cfgcmd} set policy prefix-list \ rule \<1-65535\> ge \<0-32\> - -Netmask greater than length. -``` - -```{cfgcmd} set policy prefix-list \ 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 \ - -This command creates the new IPv6 prefix-list policy, identified by ``. -``` - -```{cfgcmd} set policy prefix-list6 \ description \ - -Set description for the IPv6 prefix-list policy. -``` - -```{cfgcmd} set policy prefix-list6 \ rule \<1-65535\> action \ - -This command creates a new rule in the IPv6 prefix-list and defines an -action. -``` - -```{cfgcmd} set policy prefix-list6 \ rule \<1-65535\> description \ - -Set description for rule in IPv6 prefix-list. -``` - -```{cfgcmd} set policy prefix-list6 \ rule \<1-65535\> prefix \ - -IPv6 prefix. -``` - -```{cfgcmd} set policy prefix-list6 \ rule \<1-65535\> ge \<0-128\> - -Netmask greater than length. -``` - -```{cfgcmd} set policy prefix-list6 \ 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/md-route-map.md b/docs/configuration/policy/md-route-map.md deleted file mode 100644 index 624b542c..00000000 --- a/docs/configuration/policy/md-route-map.md +++ /dev/null @@ -1,439 +0,0 @@ -# Route Map Policy - -Route map is a powerfull command, that gives network administrators a very -useful and flexible tool for traffic manipulation. - -## Configuration - -### Route Map - -```{cfgcmd} set policy route-map \ - - This command creates a new route-map policy, identified by \. -``` - - -```{cfgcmd} set policy route-map \ description \ - -Set description for the route-map policy. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> action \ - -Set action for the route-map policy. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> call \ - -Call another route-map policy on match. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> continue \<1-65535\> - -Jump to a different rule in this route-map on a match. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> description \ - -Set description for the rule in the route-map policy. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> match as-path \ - -BGP as-path list to match. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> match community community-list \ - -BGP community-list to match. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> match community exact-match - -Set BGP community-list to exactly match. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> match extcommunity \ - -BGP extended community to match. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> match interface \ - -First hop interface of a route to match. -``` - - -```{cfgcmd} set policy route-map \ 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 \ rule \<1-65535\> match ip address prefix-list \ - -IP address of route to match, based on prefix-list. -``` - - -```{cfgcmd} set policy route-map \ 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 \ 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 \ rule \<1-65535\> match ip nexthop address \ - -IP next-hop of route to match, based on ip address. -``` - - -```{cfgcmd} set policy route-map \ 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 \ rule \<1-65535\> match ip nexthop prefix-list \ - -IP next-hop of route to match, based on prefix-list. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> match ip nexthop type \ - -IP next-hop of route to match, based on type. -``` - - -```{cfgcmd} set policy route-map \ 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 \ rule \<1-65535\> match ip route-source prefix-list \ - -IP route source of route to match, based on prefix-list. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> match ipv6 address access-list \ - -IPv6 address of route to match, based on IPv6 access-list. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> match ipv6 address prefix-list \ - -IPv6 address of route to match, based on IPv6 prefix-list. -``` - - -```{cfgcmd} set policy route-map \ 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 \ rule \<1-65535\> match ipv6 nexthop \ - -Nexthop IPv6 address to match. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> match large-community large-community-list \ - -Match BGP large communities. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> match local-preference \<0-4294967295\> - -Match local preference. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> match metric \<1-65535\> - -Match route metric. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> match origin \ - -Boarder Gateway Protocol (BGP) origin code to match. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> match peer \ - -Peer IP address to match. -``` - - -````{cfgcmd} set policy route-map \ rule \<1-65535\> match 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 \ rule \<1-65535\> match rpki \ - -Match RPKI validation result. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> match source-vrf \ - -Source VRF to match. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> match tag \<1-65535\> - -Route tag to match. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> on-match goto \<1-65535\> - -Exit policy on match: go to rule <1-65535> -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> on-match next - -Exit policy on match: go to next sequence number. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> set aggregator \ \<1-4294967295|x.x.x.x\> - -BGP aggregator attribute: AS number or IP address of an aggregation. -``` - - -```{cfgcmd} set policy route-map \ 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 \ 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 \ rule \<1-65535\> set as-path prepend-last-as \ - -Prepend the existing last AS number (the leftmost ASN) to the AS_PATH. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> set atomic-aggregate - -BGP atomic aggregate attribute. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> set community \ \ - -Add or replace BGP community attribute in format ``<0-65535:0-65535>`` -or from well-known community list -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> set community none - -Delete all BGP communities -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> set community delete \ - -Delete BGP communities matching the community-list. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> set large-community \ \ - -Add or replace BGP large-community attribute in format -``<0-4294967295:0-4294967295:0-4294967295>`` -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> set large-community none - -Delete all BGP large-communities -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> set large-community delete \ - -Delete BGP communities matching the large-community-list. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> set extcommunity bandwidth \<1-25600|cumulative|num-multipaths\> - -Set extcommunity bandwidth -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> set extcommunity bandwidth-non-transitive - -The link bandwidth extended community is encoded as non-transitive -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> set extcommunity rt \ - -Set route target value in format ``<0-65535:0-4294967295>`` or ````. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> set extcommunity soo \ - -Set site of origin value in format ``<0-65535:0-4294967295>`` or ````. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> set extcommunity none - -Clear all BGP extcommunities. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> set distance \<0-255\> - -Locally significant administrative distance. -``` -```{cfgcmd} set policy route-map \ rule \<1-65535\> set ip-next-hop \ - -Nexthop IP address. -``` -```{cfgcmd} set policy route-map \ 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 \ 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 \ rule \<1-65535\> set ipv6-next-hop \ \ - -Nexthop IPv6 address. -``` -```{cfgcmd} set policy route-map \ 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 \ 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 \ rule \<1-65535\> set local-preference \<0-4294967295\> - -Set BGP local preference attribute. -``` -```{cfgcmd} set policy route-map \ 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 \ rule \<1-65535\> set metric-type \ - -Set OSPF external metric-type. -``` -```{cfgcmd} set policy route-map \ rule \<1-65535\> set origin \ - -Set BGP origin code. -``` -```{cfgcmd} set policy route-map \ rule \<1-65535\> set originator-id \ - -Set BGP originator ID attribute. -``` -```{cfgcmd} set policy route-map \ rule \<1-65535\> set src \ - -Set source IP/IPv6 address for route. -``` -```{cfgcmd} set policy route-map \ rule \<1-65535\> set table \<1-200\> - -Set prefixes to table. -``` -```{cfgcmd} set policy route-map \ rule \<1-65535\> set tag \<1-65535\> - -Set tag value for routing protocol. -``` -```{cfgcmd} set policy route-map \ 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/md-route.md b/docs/configuration/policy/md-route.md deleted file mode 100644 index 828bd0f1..00000000 --- a/docs/configuration/policy/md-route.md +++ /dev/null @@ -1,424 +0,0 @@ -# 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 \ description \ - -``` -```{cfgcmd} set policy route6 \ description \ - -Provide a rule-set description. -``` - -```{cfgcmd} set policy route \ default-log -``` - -```{cfgcmd} set policy route6 \ default-log - -Option to log packets hitting default-action. -``` - -```{cfgcmd} set policy route \ interface \ -``` - -```{cfgcmd} set policy route6 \ interface \ - -Apply routing policy to interface -``` - -```{cfgcmd} set policy route \ rule \ description \ -``` - -```{cfgcmd} set policy route6 \ rule \ description \ - -Provide a description for each rule. -``` - -```{cfgcmd} set policy route \ rule \ log \ -``` - -```{cfgcmd} set policy route6 \ rule \ log \ - -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 \ rule \ connection-mark \<1-2147483647\> -``` - -```{cfgcmd} set policy route6 \ rule \ connection-mark \<1-2147483647\> - -Set match criteria based on connection mark. -``` - -```{cfgcmd} set policy route \ rule \ mark \ -``` - -```{cfgcmd} set policy route6 \ rule \ mark \ - -Match based on the firewall mark (fwmark), where \ 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 \ rule \ source address \ -``` - -```{cfgcmd} set policy route \ rule \ destination address \ -``` - -```{cfgcmd} set policy route6 \ rule \ source address \ -``` - -```{cfgcmd} set policy route6 \ rule \ destination address \ - -Set match criteria based on source or destination ipv4|ipv6 address, where -<match_criteria> could be: -``` - -For ipv4: -: - \: IP address to match. - - \: Subnet to match. - - \-\: IP range to match. - - !\: Match everything except the specified address. - - !\: Match everything except the specified subnet. - - !\-\: Match everything except the specified range. - -And for ipv6: -: - \: IPv6 address to match. - - \: IPv6 prefix to match. - - \-\: IPv6 range to match. - - !\: Match everything except the specified address. - - !\: Match everything except the specified prefix. - - !\-\: Match everything except the - specified range. - -```{cfgcmd} set policy route \ rule \ source group \ \ -``` - -```{cfgcmd} set policy route \ rule \ destination group \ \ -``` - -```{cfgcmd} set policy route6 \ rule \ source group \ \ -``` - -```{cfgcmd} set policy route6 \ rule \ destination group \ \ - -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 \ rule \ destination port \ -``` - -```{cfgcmd} set policy route6 \ rule \ destination port \ - -Set match criteria based on destination port, where \ 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 \ rule \ disable -``` - -```{cfgcmd} set policy route6 \ rule \ disable - -Option to disable rule. -``` - -```{cfgcmd} set policy route \ rule \ dscp \ -``` - -```{cfgcmd} set policy route6 \ rule \ dscp \ -``` - -```{cfgcmd} set policy route \ rule \ dscp-exclude \ -``` - -```{cfgcmd} set policy route6 \ rule \ dscp-exclude \ - -Match based on dscp value criteria. Multiple values from 0 to 63 -and ranges are supported. -``` - -```{cfgcmd} set policy route \ rule \ fragment \ -``` - -```{cfgcmd} set policy route6 \ rule \ fragment \ - -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 \ rule \ icmp \ -``` - -```{cfgcmd} set policy route6 \ rule \ icmpv6 \ - -Match based on icmp|icmpv6 code and type. -``` - -```{cfgcmd} set policy route \ rule \ icmp type-name \ -``` - -```{cfgcmd} set policy route6 \ rule \ icmpv6 type-name \ - -Match based on icmp|icmpv6 type-name criteria. Use tab for information -about what type-name criteria are supported. -``` - -```{cfgcmd} set policy route \ rule \ ipsec \ -``` - -```{cfgcmd} set policy route6 \ rule \ ipsec \ - -Set IPSec inbound match criterias, where: -* match-ipsec: match inbound IPsec packets. -* match-none: match inbound non-IPsec packets. -``` - -```{cfgcmd} set policy route \ rule \ limit burst \<0-4294967295\> -``` - -```{cfgcmd} set policy route6 \ rule \ limit burst \<0-4294967295\> - -Set maximum number of packets to alow in excess of rate. -``` - -```{cfgcmd} set policy route \ rule \ limit rate \ -``` - -```{cfgcmd} set policy route6 \ rule \ limit rate \ - -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 \ rule \ protocol \ -``` - -```{cfgcmd} set policy route6 \ rule \ protocol \ - -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 \ rule \ packet-length \ -``` - -```{cfgcmd} set policy route6 \ rule \ packet-length \ -``` - -```{cfgcmd} set policy route \ rule \ packet-length-exclude \ -``` - -```{cfgcmd} set policy route6 \ rule \ packet-length-exclude \ - -Match based on packet length criteria. Multiple values from 1 to 65535 -and ranges are supported. -``` - -```{cfgcmd} set policy route \ rule \ packet-type \[broadcast | host | multicast | other\] -``` - -```{cfgcmd} set policy route6 \ rule \ packet-type \[broadcast | host | multicast | other\] - -Match based on packet type criteria. -``` - -```{cfgcmd} set policy route \ rule \ recent count \<1-255\> -``` - -```{cfgcmd} set policy route6 \ rule \ recent count \<1-255\> -``` - -```{cfgcmd} set policy route \ rule \ recent time \<1-4294967295\> -``` - -```{cfgcmd} set policy route6 \ rule \ 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 \ rule \ state \ -``` - -```{cfgcmd} set policy route6 \ rule \ state \ - -Set match criteria based on session state. -``` - -```{cfgcmd} set policy route \ rule \ tcp flags \ -``` - -```{cfgcmd} set policy route6 \ rule \ tcp flags \ - -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 \ rule \ time monthdays \ -``` - -```{cfgcmd} set policy route6 \ rule \ time monthdays \ -``` - -```{cfgcmd} set policy route \ rule \ time startdate \ -``` - -```{cfgcmd} set policy route6 \ rule \ time startdate \ -``` - -```{cfgcmd} set policy route \ rule \ time starttime \ -``` - -```{cfgcmd} set policy route6 \ rule \ time starttime \ -``` - -```{cfgcmd} set policy route \ rule \ time stopdate \ -``` - -```{cfgcmd} set policy route6 \ rule \ time stopdate \ -``` - -```{cfgcmd} set policy route \ rule \ time stoptime \ -``` - -```{cfgcmd} set policy route6 \ rule \ time stoptime \ -``` - -```{cfgcmd} set policy route \ rule \ time weekdays \ -``` - -```{cfgcmd} set policy route6 \ rule \ time weekdays \ -``` - -```{cfgcmd} set policy route \ rule \ time utc -``` - -```{cfgcmd} set policy route6 \ rule \ time utc - -Time to match the defined rule. -``` - -```{cfgcmd} set policy route rule \ ttl \ \<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 \ hop-limit \ \<0-255\> - -Match hop-limit parameter, where 'eq' stands for 'equal'; 'gt' stands for -'greater than', and 'lt' stands for 'less than'. -``` - -### Actions - -When mathcing all patterns defined in a rule, then different actions can -be made. This includes droping the packet, modifying certain data, or -setting a different routing table. - -```{cfgcmd} set policy route \ rule \ action drop -``` - -```{cfgcmd} set policy route6 \ rule \ action drop - -Set rule action to drop. -``` - -```{cfgcmd} set policy route \ rule \ set connection-mark \<1-2147483647\> -``` - -```{cfgcmd} set policy route6 \ rule \ set connection-mark \<1-2147483647\> - -Set a specific connection mark. -``` - -```{cfgcmd} set policy route \ rule \ set dscp \<0-63\> -``` - -```{cfgcmd} set policy route6 \ rule \ set dscp \<0-63\> - -Set packet modifications: Packet Differentiated Services Codepoint (DSCP) -``` - -```{cfgcmd} set policy route \ rule \ set mark \<1-2147483647\> -``` - -```{cfgcmd} set policy route6 \ rule \ set mark \<1-2147483647\> - -Set a specific packet mark. -``` - -```{cfgcmd} set policy route \ rule \ set table \
-``` - -```{cfgcmd} set policy route6 \ rule \ set table \
- -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 \ rule \ set tcp-mss \<500-1460\> -``` - -```{cfgcmd} set policy route6 \ rule \ set tcp-mss \<500-1460\> - -Set packet modifications: Explicitly set TCP Maximum segment size value. -``` - -```{cfgcmd} set policy route \ rule \ set vrf \ -``` - -```{cfgcmd} set policy route6 \ rule \ set vrf \ - -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/protocols/md-arp.md b/docs/configuration/protocols/md-arp.md deleted file mode 100644 index 7d9bf4f9..00000000 --- a/docs/configuration/protocols/md-arp.md +++ /dev/null @@ -1,72 +0,0 @@ -```{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 address 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 - - 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/md-babel.md b/docs/configuration/protocols/md-babel.md deleted file mode 100644 index b03e9fa4..00000000 --- a/docs/configuration/protocols/md-babel.md +++ /dev/null @@ -1,296 +0,0 @@ -```{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 \ - -**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 \ type \ - -**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 \ split-horizon \ - -**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 \ 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 \ 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 \ 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 \ 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 \ 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 \ 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 \ 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 \ 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 \ 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 \ \ - -**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 \ access-list \ \ - -**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 \ interface \ access-list \ \ - -**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 \ prefix-list \ \ - -**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 \ interface \ prefix-list \ \ - -**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/md-bfd.md b/docs/configuration/protocols/md-bfd.md deleted file mode 100644 index 59541abc..00000000 --- a/docs/configuration/protocols/md-bfd.md +++ /dev/null @@ -1,205 +0,0 @@ ---- -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 \ - -Set BFD peer IPv4 address or IPv6 address -``` - -```{cfgcmd} set protocols bfd peer \ echo-mode - -Enables the echo transmission mode -``` - -```{cfgcmd} set protocols bfd peer \ multihop - -Allow this BFD peer to not be directly connected -``` - -```{cfgcmd} set protocols bfd peer \ source [address \ | interface \] - -Bind listener to specific interface/address, mandatory for IPv6 -``` - -```{cfgcmd} set protocols bfd peer \ interval echo-interval \<10-60000\> - -The minimal echo receive transmission interval that this system is -capable of handling -``` - -```{cfgcmd} set protocols bfd peer \ interval multiplier \<2-255\> - -Remote transmission interval will be multiplied by this value -``` - -```{cfgcmd} set protocols bfd peer \ interval [receive | transmit] \<10-60000\> - -Interval in milliseconds -``` - -```{cfgcmd} set protocols bfd peer \ shutdown - -Disable a BFD peer -``` - -```{cfgcmd} set protocols bfd peer \ 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 \ bfd - -Enable BFD on a single BGP neighbor -``` - -```{cfgcmd} set protocols bgp peer-group \ bfd - -Enable BFD on a BGP peer group -``` - -### Enable BFD in OSPF - -```{cfgcmd} set protocols ospf interface \ bfd - - Enable BFD for OSPF on an interface - -``` - -```{cfgcmd} set protocols ospfv3 interface \ bfd - -Enable BFD for OSPFv3 on an interface -``` - -### Enable BFD in ISIS - -```{cfgcmd} set protocols isis \ 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 \ next-hop \ bfd profile \ - -Configure a static route for \ using gateway \ -and use the gateway address as BFD peer destination address. -``` - -```{cfgcmd} set protocols static route \ next-hop \ bfd multi-hop source \ profile \ - -Configure a static route for \ using gateway \, -use source address to indentify the peer when is multi-hop session -and the gateway address as BFD peer destination address. -``` - -```{cfgcmd} set protocols static route6 \ next-hop \ bfd profile \ - -Configure a static route for \ using gateway \ -and use the gateway address as BFD peer destination address. -``` - -```{cfgcmd} set protocols static route6 \ next-hop \ bfd multi-hop source \ profile \ - -Configure a static route for \ using gateway \, -use source address to indentify 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/md-bgp.md b/docs/configuration/protocols/md-bgp.md deleted file mode 100644 index 0af79f6e..00000000 --- a/docs/configuration/protocols/md-bgp.md +++ /dev/null @@ -1,1414 +0,0 @@ -(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 \ - -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 \ - -Set local autonomous system number that this router represents. This is a -mandatory option! -``` - -#### Peers Configuration - - -##### Defining Peers - -```{cfgcmd} set protocols bgp neighbor \ remote-as \ - -This command creates a new neighbor whose remote-as is \. 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 \ 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 ` command the connection will be denied. -``` - - -```{cfgcmd} set protocols bgp neighbor \ 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 ` command the connection will be denied. -``` - - -```{cfgcmd} set protocols bgp neighbor \ 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 \ local-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 \ 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 \ description \ - -Set description of the peer or peer group. -``` - - -```{cfgcmd} set protocols bgp neighbor \ update-source \ - -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 \ capability dynamic - -This command would allow the dynamic update of capabilities over an -established BGP session. -``` - - -```{cfgcmd} set protocols bgp neighbor \ 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 \ 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 \ 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 \ 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-family \ allowas-in 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 - occurences 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-family \ 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-family \ attribute-unchanged \ - -This command specifies attributes to be left unchanged for -advertisements sent to a peer or peer group. -``` - - -```{cfgcmd} set protocols bgp neighbor \ address-family \ maximum-prefix \ - -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-family \ 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-family \ 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-family \ 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-family \ weight \ - -This command specifies a default weight value for the neighbor’s -routes. The number range is 1 to 65535. -``` - - -```{cfgcmd} set protocols bgp neighbor \ advertisement-interval \ - -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 \ 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 \ disable-send-community \ - -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 \ ebgp-multihop \ - -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 \ local-as \ [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 \ 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 \ password \ - -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 \ ttl-security hops \ - -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 \ - - 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 \ peer-group \ - -This command bind specific peer to peer group with a given name. -``` - -#### Network Advertisement Configuration - -```{cfgcmd} set protocols bgp address-family \ network \ - -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-family \ default-originate [route-map \] - -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 \ aggregate-address \ - -This command specifies an aggregate address. The router will also -announce longer-prefixes inside of the aggregate address. -``` - - -```{cfgcmd} set protocols bgp address-family \ aggregate-address \ 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 \ aggregate-address \ 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-family \ unsuppress-map \ - -This command applies route-map to selectively unsuppress prefixes -suppressed by summarisation. -``` - -#### Redistribution Configuration - -```{cfgcmd} set protocols bgp address-family \ redistribute - -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 \ redistribute metric \ - -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 \ redistribute route-map \ - -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 \ - -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 \ maximum-paths \ \ - -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 \ peer-group \ - -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 \ - -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 \ - -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 \ \ - -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 \ 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 \ - - 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 \ - -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 \ - -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 \ - -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 \ - -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 \ - -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 - -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 \ 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-family \ distribute-list \ \ - -This command applies the access list filters named in \ 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-family \ prefix-list \ \ - -This command applies the prfefix list filters named in \ 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-family \ route-map \ \ - -This command applies the route map named in \ 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-family \ filter-list \ \ - -This command applies the AS path access list filters named in \ 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-family \ capability orf \ - -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 \ 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-family \ route-reflector-client - -This command specifies the given neighbor as route reflector client. -``` - - -```{cfgcmd} set protocols bgp parameters cluster-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 \ - -This command specifies a BGP confederation identifier. \ is the number -of the autonomous system that internally includes multiple sub-autonomous -systems (a confederation). -``` - - -```{cfgcmd} set protocols bgp parameters confederation peers \ - -This command sets other confederations \ as members of autonomous -system specified by {cfgcmd}`confederation identifier `. -``` - -## Operational Mode Commands -### Show - -```{opcmd} show bgp \ - - 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 \ \ - -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 \ community \ - -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 \ community-list \ - -This command displays routes that are permitted by the BGP -community list. -``` - - -```{opcmd} show bgp \ dampening dampened-paths - -This command displays BGP dampened routes. -``` - - -```{opcmd} show bgp \ dampening flap-statistics - -This command displays information about flapping BGP routes. -``` - - -```{opcmd} show bgp \ filter-list \ - -This command displays BGP routes allowed by the specified AS Path -access list. -``` - - -```{opcmd} show bgp \ neighbors \ advertised-routes - -This command displays BGP routes advertised to a neighbor. -``` - - -```{opcmd} show bgp \ neighbors \ 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 \ neighbors \ routes - -This command displays BGP received-routes that are accepted after filtering. -``` - - -```{opcmd} show bgp \ neighbors \ dampened-routes - -This command displays dampened routes received from BGP neighbor. -``` - - -```{opcmd} show bgp \ regexp \ - -This command displays information about BGP routes whose AS path -matches the specified regular expression. -``` - - -```{opcmd} show bgp \ 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 \ \ [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 \ external - -This command resets all external BGP peers of given router. -``` - - -```{opcmd} reset bgp \ peer-group \ [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/md-failover.md b/docs/configuration/protocols/md-failover.md deleted file mode 100644 index 96374d11..00000000 --- a/docs/configuration/protocols/md-failover.md +++ /dev/null @@ -1,237 +0,0 @@ ---- -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 -`` reachable via next-hop `
`. - -```{eval-rst} -.. cfgcmd:: set protocols failover route next-hop
check target - - **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 next-hop
check 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 next-hop
check type - - **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 next-hop
check 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 next-hop
check 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 next-hop
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 next-hop
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 next-hop
onlink - - Configure the next-hop to be reachable via the assigned interface, even - when ``
`` 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/md-igmp-proxy.md b/docs/configuration/protocols/md-igmp-proxy.md deleted file mode 100644 index 961f921b..00000000 --- a/docs/configuration/protocols/md-igmp-proxy.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -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 \ role \ - -* **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 \ alt-subnet \ - -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/md-index.md b/docs/configuration/protocols/md-index.md deleted file mode 100644 index 5f190ce1..00000000 --- a/docs/configuration/protocols/md-index.md +++ /dev/null @@ -1,25 +0,0 @@ -# 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/md-isis.md b/docs/configuration/protocols/md-isis.md deleted file mode 100644 index ac6db346..00000000 --- a/docs/configuration/protocols/md-isis.md +++ /dev/null @@ -1,746 +0,0 @@ -```{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 \ - -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 \ - -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 \ - -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 \ - -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 \ - -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 \ level-1 - -This command will generate a default-route in L1 database. -``` - -```{cfgcmd} set protocols isis default-information originate \ 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 \ - -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 \ circuit-type \ - -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 \ hello-interval \ - -This command sets hello interval in seconds on a given interface. -The range is 1 to 600. -``` - -```{cfgcmd} set protocols isis interface \ hello-multiplier \ - -This command sets multiplier for hello holding time on a given -interface. The range is 2 to 100. -``` - -```{cfgcmd} set protocols isis 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 \ 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 \ network point-to-point - -This command specifies network type to Point-to-Point. The default -network type is broadcast. -``` - -```{cfgcmd} set protocols isis interface \ passive - -This command configures the passive mode for this interface. -``` - -```{cfgcmd} set protocols isis interface \ password plaintext-password \ - -This command configures the authentication password for the interface. -``` - -```{cfgcmd} set protocols isis interface \ priority \ - -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 \ psnp-interval \ - -This command sets PSNP interval in seconds. The interval range is 0 -to 127. -``` - -```{cfgcmd} set protocols isis 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 \ ldp-sync disable - -This command disables IGP-LDP sync for this specific interface. -``` - -```{cfgcmd} set protocols isis interface \ ldp-sync holddown \ - -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 \ fast-reroute lfa [level-1 | level-2] enable - -This command enables per-prefix local LFA fast reroute link protection. -``` - -```{cfgcmd} set protocols isis 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 \ 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 \ fast-reroute remote-lfa [level-1 | level-2] maximum-metric \ - -This command limits Remote LFA PQ node selection within the specified metric. Metric value range (1-16777215). -``` - -```{cfgcmd} set protocols isis 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 \ 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 \ 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 \ \ metric \ - -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-map \ - -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 \ - -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 \ - -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 \ - -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 \ - -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 \ -``` - -```{cfgcmd} set protocols isis spf-delay-ietf init-delay \ -``` - -```{cfgcmd} set protocols isis spf-delay-ietf long-delay \ -``` - -```{cfgcmd} set protocols isis spf-delay-ietf short-delay \ -``` - -```{cfgcmd} set protocols isis spf-delay-ietf time-to-learn \ - -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 \ \ - -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 \ - -This command disables the load sharing across multiple LFA backups. -``` - -```{cfgcmd} set protocols isis fast-reroute lfa local tiebreaker \ index \ \ - -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 \ \ - -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 \ - -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 \ - -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/md-mpls.md b/docs/configuration/protocols/md-mpls.md deleted file mode 100644 index 71b14be2..00000000 --- a/docs/configuration/protocols/md-mpls.md +++ /dev/null @@ -1,285 +0,0 @@ -(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 \ - -Use this command to enable MPLS processing on the interface you define. -``` - - -```{cfgcmd} set protocols mpls ldp interface \ - -Use this command to enable LDP on the interface you define. -``` - - -```{cfgcmd} set protocols mpls ldp router-id \ - -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 \ - -``` -```{cfgcmd} set protocols mpls ldp discovery transport-ipv6-address \ - -Use this command to set the IPv4 or IPv6 transport-address used by LDP. -``` - -```{cfgcmd} set protocols mpls ldp neighbor \ 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 \ session-holdtime \ - -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 \ ttl-security \ - -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 -.. cfgcmd:: set protocols mpls ldp discovery hello-ipv4-holdtime -.. cfgcmd:: set protocols mpls ldp discovery hello-ipv6-interval -.. cfgcmd:: set protocols mpls ldp discovery hello-ipv6-holdtime - - 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 -.. cfgcmd:: set protocols mpls ldp discovery session-ipv6-holdtime - - 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 - -.. cfgcmd:: set protocols mpls ldp import ipv6 import-filter filter-access-list6 - - - 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 - -.. cfgcmd:: set protocols mpls ldp export ipv6 export-filter filter-access-list6 - - - 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 -.. cfgcmd:: set protocols mpls ldp allocation ipv6 access-list6 - - 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 \ -``` - -```{cfgcmd} set protocols mpls ldp targeted-neighbor ipv6 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 \ -``` - -```{cfgcmd} set protocols mpls ldp targeted-neighbor ipv4 hello-interval \ -``` - -```{cfgcmd} set protocols mpls ldp targeted-neighbor ipv6 hello-holdtime \ -``` - -```{cfgcmd} set protocols mpls ldp targeted-neighbor ipv6 hello-interval \ - -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 \ - -Use this command to reset an LDP neighbor/TCP session that is established -``` - -[wikipedia (mpls)]: diff --git a/docs/configuration/protocols/md-multicast.md b/docs/configuration/protocols/md-multicast.md deleted file mode 100644 index 27150a29..00000000 --- a/docs/configuration/protocols/md-multicast.md +++ /dev/null @@ -1,31 +0,0 @@ -(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 \ next-hop \ [distance \] - -Insert into the Multicast RIB Route `` with specified next-hop. -The distance can be specified as well if desired. -``` -```{cfgcmd} set protocols static mroute \ next-hop \ disable - -Do not install route for `` into the Multicast RIB. -``` -```{cfgcmd} set protocols static mroute \ interface \ [distance \] - -Insert into the Multicast RIB Route `` with specified ``. -The distance can be specified as well if desired. -``` -```{cfgcmd} set protocols static mroute \ interface \ disable - -Do not install route for `` into the Multicast RIB. -``` \ No newline at end of file diff --git a/docs/configuration/protocols/md-openfabric.md b/docs/configuration/protocols/md-openfabric.md deleted file mode 100644 index 09ff5900..00000000 --- a/docs/configuration/protocols/md-openfabric.md +++ /dev/null @@ -1,242 +0,0 @@ -(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 \ - -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 \ interface \ address-family \ - -This command enables OpenFabric instance with \ 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 \ \ - -This command configures the authentication password for a routing domain, -as clear text or md5 one. -``` - - -```{cfgcmd} set protocols openfabric domain \ purge-originator - -This command enables {rfc}`6232` purge originator identification. -``` - - -```{cfgcmd} set protocols openfabric domain \ set-overload-bit - -This command sets overload bit to avoid any transit traffic through this -router. -``` - - -```{cfgcmd} set protocols openfabric domain \ log-adjacency-changes - -Log changes in adjacency state. -``` - - -```{cfgcmd} set protocols openfabric domain \ fabric-tier \ - -This command sets a static tier number to advertise as location -in the fabric. -``` - -#### Interface Configuration - -```{cfgcmd} set protocols openfabric interface \ hello-interval \ - -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 \ interface \ hello-multiplier \ - -This command sets multiplier for hello holding time on a given -interface. The range is 2 to 100. -``` - - -```{cfgcmd} set protocols openfabric domain \ interface \ metric \ - -This command sets default metric for circuit. -The metric range is 1 to 16777215. -``` - - -```{cfgcmd} set protocols openfabric interface \ passive - -This command enables the passive mode for this interface. -``` - - -```{cfgcmd} set protocols openfabric domain \ interface \ password plaintext-password \ - -This command sets the authentication password for the interface. -``` - - -```{cfgcmd} set protocols openfabric domain \ interface \ csnp-interval \ - -This command sets Complete Sequence Number Packets (CSNP) interval in seconds. -The interval range is 1 to 600. -``` - - -```{cfgcmd} set protocols openfabric domain \ interface \ psnp-interval \ - -This command sets Partial Sequence Number Packets (PSNP) interval in seconds. -The interval range is 1 to 120. -``` - -#### Timers - -```{cfgcmd} set protocols openfabric domain \ lsp-gen-interval \ - -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 \ lsp-refresh-interval \ - -This command sets LSP refresh interval in seconds. The interval range -is 1 to 65235. -``` - - -```{cfgcmd} set protocols openfabric domain \ max-lsp-lifetime \ - -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 \ spf-interval \ - -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/md-ospf.md b/docs/configuration/protocols/md-ospf.md deleted file mode 100644 index 72fefb84..00000000 --- a/docs/configuration/protocols/md-ospf.md +++ /dev/null @@ -1,1504 +0,0 @@ -(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 \ network \ - - 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 area ` -``` - - -```{cfgcmd} set protocols ospf auto-cost reference-bandwidth \ - -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 \ - -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 \] [metric-type \<1|2\>] [route-map \] - -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 \ - -This command change distance value of OSPF globally. -The distance range is 1 to 255. -``` - - -```{cfgcmd} set protocols ospf distance ospf \ \ - -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 \|on-startup \> - -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 ` command -and/or for a period of seconds prior to shutdown with the -{cfgcmd}`on-shutdown ` command. The time range is 5 to 86400. -``` - - -```{cfgcmd} set protocols ospf parameters abr-type \ - -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 \ 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 \ - -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 \ \ - -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 \ - -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 \ 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 \ 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 \ area-type stub default-cost \ - -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 \ 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 \ 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 \ area-type nssa default-cost \ - -This command sets the default cost of LSAs announced to NSSA areas. -The cost range is 0 to 16777215. -``` - - -```{cfgcmd} set protocols ospf area \ area-type nssa translate \ - -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 \ 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 \ 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 \ range \ [cost \] - -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 \ range \ 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 \ export-list \ - -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 \ import-list \ - -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 \ range \ substitute \ - -One Type-3 summary-LSA with routing info 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 . -This command makes sense in ABR only. -``` - - -```{cfgcmd} set protocols ospf area \ shortcut \ - -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 \ virtual-link \ - -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. - -\ – area identifier through which a virtual link goes. -\ – 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 \ area \ - - 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 \ authentication plaintext-password \ - -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 \ authentication md5 key-id \ md5-key \ - -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 \ bandwidth \ - -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 \ cost \ - -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 \ dead-interval \ - -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 \ hello-multiplier \ - -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 \ hello-interval \ - -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 \ bfd - -This command enables {abbr}`BFD (Bidirectional Forwarding Detection)` on -this OSPF link interface. -``` - - -```{cfgcmd} set protocols ospf 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 \ network \ - -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 \ priority \ - -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 \ retransmit-interval \ - -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 \ transmit-delay \ - -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 \ ldp-sync disable - -This command disables IGP-LDP sync for this specific interface. -``` - - -```{cfgcmd} set protocols ospf interface \ ldp-sync holddown \ - -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 \ - -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 \ - -This command specifies the IP address of the neighboring device. -``` - - -```{cfgcmd} set protocols ospf neighbor \ poll-interval \ - -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 \ priority \ - -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 \ - - 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 \ - -This command specifies the default metric value of redistributed routes. -The metric range is 0 to 16777214. -``` - - -```{cfgcmd} set protocols ospf redistribute \ metric \ - -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 \ 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-map \ - -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 \ - -This command displays the neighbors information in a detailed form for a -neighbor whose IP address is specified. -``` - - -```{opcmd} show ip ospf neighbor \ - -This command displays the neighbors status for a neighbor on the specified -interface. -``` - - -```{opcmd} show ip ospf 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 - 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 - 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 "\/\" 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 \ [A.B.C.D] [adv-router \|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 ` – 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 \ area \ - - 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 \ - -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 \ - -This command change distance value of OSPFv3 globally. -The distance range is 1 to 255. -``` -```{cfgcmd} set protocols ospfv3 distance ospfv3 \ \ - -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 \ range \ - -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 \ range \ 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 \ ipv6 cost \ - -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 \ dead-interval \ - -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 \ hello-interval \ - -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 \ 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 \ network \ - -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 \ priority \ - -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 \ 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 \ retransmit-interval \ - -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 \ transmit-delay \ - -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 \ - -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-map \ - -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]|[\ [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 \ [A.B.C.D] [adv-router \|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/md-pim.md b/docs/configuration/protocols/md-pim.md deleted file mode 100644 index db8c9fb7..00000000 --- a/docs/configuration/protocols/md-pim.md +++ /dev/null @@ -1,282 +0,0 @@ ---- -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 \ - -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 \ - -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 \ - -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 \ - -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 \ - -Modify the time that pim will register suppress a FHR will send register -notifications to the kernel. -``` - -```{cfgcmd} set protocols pim rp \ 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 \ - -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 \] - -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 \ - -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 \ bfd [profile \] - -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 \ dr-priority \ - -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 \ hello \ - -Set the PIM hello and hold interval for a interface. -``` - -```{cfgcmd} set protocols pim interface \ no-bsm - -Tell PIM that we would not like to use this interface to process -bootstrap messages. -``` - -```{cfgcmd} set protocols pim 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 \ passive - -Disable sending and receiving PIM control packets on the interface. -``` - -```{cfgcmd} set protocols pim interface \ source-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 \ - -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 \ igmp join \ source-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 \ igmp query-interval \ - -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 \ igmp query-max-response-time \ - -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 \ igmp version \ - -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/md-pim6.md b/docs/configuration/protocols/md-pim6.md deleted file mode 100644 index 707ae606..00000000 --- a/docs/configuration/protocols/md-pim6.md +++ /dev/null @@ -1,100 +0,0 @@ -(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 \ - - 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 \ 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 \ mld interval \ - -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 \ mld join \ - -Use this command to allow the selected interface to join a multicast group. -``` - -```{cfgcmd} set protocols pim6 interface \ mld join \ source \ - -Use this command to allow the selected interface to join a source-specific multicast -group. -``` - -```{cfgcmd} set protocols pim6 interface \ mld last-member-query-count \ - -Set the MLD last member query count. The default value is 2. -``` - -```{cfgcmd} set protocols pim6 interface \ mld last-member-query-interval \ - -Set the MLD last member query interval in milliseconds (100-6553500). The default value is 1000 milliseconds. -``` - -```{cfgcmd} set protocols pim6 interface \ mld max-response-time \ - -Set the MLD query response timeout in milliseconds (100-6553500). The default value is 10000 milliseconds. -``` - -```{cfgcmd} set protocols pim6 interface \ mld version \ - -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/md-rip.md b/docs/configuration/protocols/md-rip.md deleted file mode 100644 index 684337d6..00000000 --- a/docs/configuration/protocols/md-rip.md +++ /dev/null @@ -1,294 +0,0 @@ ---- -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 \ - -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 \ - -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 \ - -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 \ - -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 \ - -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 \ 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 \ access-list \ - -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 \ \ - -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 \ access-list \ \ - -This command allows you apply access lists to a chosen interface to -filter the RIP path. -``` - - -```{cfgcmd} set protocols rip distribute-list prefix-list \ \ - -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 \ prefix-list \ \ - -This command allows you apply prefix lists to a chosen interface to -filter the RIP path. -``` - - -```{cfgcmd} set protocols rip route \ - -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 \ - -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 \ - -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 \ - -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 \ - -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 \ 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-map \ - -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 \ - -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 \ \ ip rip authentication plaintext-password \ - -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 \ \ ip rip authentication md5 \ password \ - -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 \ \ 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 \ \ 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/md-rpki.md b/docs/configuration/protocols/md-rpki.md deleted file mode 100644 index 1f4cf5bf..00000000 --- a/docs/configuration/protocols/md-rpki.md +++ /dev/null @@ -1,210 +0,0 @@ -(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 \ 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 \ 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 \ ssh username \ - -SSH username to establish an SSH connection to the cache server. -``` - -```{cfgcmd} set protocols rpki cache \ ssh private-key-file \ - -Local path that includes the private key file of the router. -``` - -```{cfgcmd} set protocols rpki cache \ ssh public-key-file \ - -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]: diff --git a/docs/configuration/protocols/md-segment-routing.md b/docs/configuration/protocols/md-segment-routing.md deleted file mode 100644 index 45c89a41..00000000 --- a/docs/configuration/protocols/md-segment-routing.md +++ /dev/null @@ -1,359 +0,0 @@ -(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 \ - -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 \ - -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 \ - -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 \ - -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 \ 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 -indentify it -``` - - -```{cfgcmd} set protocols isis segment-routing prefix \ index \ - -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 \ - -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 \ - -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 \ - -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 \ - -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 \ 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 -indentify it -``` - -```{cfgcmd} set protocols ospf segment-routing prefix \ index \ - -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/md-static.md b/docs/configuration/protocols/md-static.md deleted file mode 100644 index 357f7076..00000000 --- a/docs/configuration/protocols/md-static.md +++ /dev/null @@ -1,298 +0,0 @@ -(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 \ next-hop \ - -Configure next-hop *\* for an IPv4 static route. Multiple static -routes can be created. -``` - -```{cfgcmd} set protocols static route \ next-hop \ disable - -Disable this IPv4 static route entry. -``` - -```{cfgcmd} set protocols static route \ next-hop \ 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 \ interface \ - -Allows you to configure the next-hop interface for an interface-based IPv4 -static route. *\* will be the next-hop interface where traffic is -routed for the given *\*. -``` - -```{cfgcmd} set protocols static route \ interface \ disable - -Disables interface-based IPv4 static route. -``` - -```{cfgcmd} set protocols static route \ interface \ 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 \ next-hop \ bfd - -Configure a static route for *\* using gateway *\* and use the -gateway address as BFD peer destination address. -``` - -```{cfgcmd} set protocols static route \ next-hop \ bfd profile \ - -Configure a static route for *\* using gateway *\* and use the -gateway address as BFD peer destination address with BFD profile *\*. -``` - -```{cfgcmd} set protocols static route \ next-hop \ bfd multi-hop source-address \ - -Configure a static route for *\* using gateway *\* and use the -gateway address as BFD peer destination address with source address -*\* but initiate a multi-hop session. -``` - - -### DHCP Interface Routes - -```{cfgcmd} set protocols static route \ dhcp-interface \ - -Defines route with DHCP interface supplying next-hop IP address. -``` - - -### IPv4 Reject Routes - -```{cfgcmd} set protocol static route \ reject - -Defines route which emits an ICMP unreachable when matched. -``` - -```{cfgcmd} set protocols static route \ reject 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 \ reject tag \ - -Sets a tag for this route. -``` - -```{cfgcmd} set protocol static route6 \ reject - -Defines route which emits an ICMP unreachable when matched. -``` - - -### IPv4 Blackhole Routes - -```{cfgcmd} set protocols static route \ 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 \ blackhole 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 \ blackhole tag \ - -Sets a tag for this route. -``` - - -## IPv6 Unicast Routes - -```{cfgcmd} set protocols static route6 \ next-hop \ - -Configure next-hop *\* for an IPv6 static route. Multiple static -routes can be created. -``` - -```{cfgcmd} set protocols static route6 \ next-hop \ disable - -Disable this IPv6 static route entry. -``` - -```{cfgcmd} set protocols static route6 \ next-hop \ 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 \ next-hop \ 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 \ interface \ - -Allows you to configure the next-hop interface for an interface-based IPv6 -static route. *\* will be the next-hop interface where traffic is -routed for the given *\*. -``` - -```{cfgcmd} set protocols static route6 \ interface \ disable - -Disables interface-based IPv6 static route. -``` - -```{cfgcmd} set protocols static route6 \ interface \ 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 \ interface \ 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 \ next-hop \ bfd - -Configure a static route for *\* using gateway *\* and use the -gateway address as BFD peer destination address. -``` - -```{cfgcmd} set protocols static route6 \ next-hop \ bfd profile \ - -Configure a static route for *\* using gateway *\* and use the -gateway address as BFD peer destination address with BFD profile *\*. -``` - -```{cfgcmd} set protocols static route6 \ next-hop \ bfd multi-hop source-address \ - -Configure a static route for *\* using gateway *\* and use the -gateway address as BFD peer destination address with source address -*\* but initiate a multi-hop session. -``` - - -### IPv6 Reject Routes - -```{cfgcmd} set protocol static route6 \ reject - -Defines route which emits an ICMP unreachable when matched. -``` - -```{cfgcmd} set protocols static route6 \ reject 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 \ reject tag \ - -Sets a tag for this route. -``` - - -### IPv6 Blackhole Routes - -```{cfgcmd} set protocols static route6 \ 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 \ blackhole 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 \ blackhole 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/md-traffic-engineering.md b/docs/configuration/protocols/md-traffic-engineering.md deleted file mode 100644 index 832023a7..00000000 --- a/docs/configuration/protocols/md-traffic-engineering.md +++ /dev/null @@ -1,54 +0,0 @@ -(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 \ bit-position \ - -Create Administrative group and assosiate bit position with it. These groups can be -used in the following commands. - -\ can have value 0-31. There cannot be two groups with same bit position. -``` - - -```{cfgcmd} set protocols traffic-engineering interface \ admin-group \ - -Set administrative group for interface \. Multiple values can be provided. -``` - - -```{cfgcmd} set protocols traffic-engineering interface \ max-bandwidth \ - -Set maximum bandwidth for interface \. Value given in Mbits per second. -``` - - -```{cfgcmd} set protocols traffic-engineering interface \ max-reservable-bandwidth \ - -Set maximum reservable bandwidth for interface \. 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 \ - -Configure IPv4 address for MPLS-TE. -``` \ No newline at end of file diff --git a/docs/configuration/service/md-broadcast-relay.md b/docs/configuration/service/md-broadcast-relay.md deleted file mode 100644 index 4202ad6b..00000000 --- a/docs/configuration/service/md-broadcast-relay.md +++ /dev/null @@ -1,70 +0,0 @@ -(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 \ 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 \ 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 \ address \ - -Set the source IP of forwarded packets, otherwise original senders address -is used. -``` - -```{cfgcmd} set service broadcast-relay id \ port \ - -The UDP port number used by your application. It is mandatory for this kind -of operation. -``` - -```{cfgcmd} set service broadcast-relay id \ 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/md-config-sync.md b/docs/configuration/service/md-config-sync.md deleted file mode 100644 index a575f947..00000000 --- a/docs/configuration/service/md-config-sync.md +++ /dev/null @@ -1,164 +0,0 @@ -(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 \ - -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 \ - -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 \ - -Two options are available for *mode*: either *load* and replace or *set* -the configuration section. -``` - -```none -Supported options for
include: - firewall - interfaces - nat - nat66 - pki - policy - protocols - qos - service - system - vpn - vrf -``` - - -## Operational Commands - -````{opcmd} show configuration secondary sync [commands] [running | candidate | saved] [\] - -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/md-conntrack-sync.md b/docs/configuration/service/md-conntrack-sync.md deleted file mode 100644 index 47a0ae2f..00000000 --- a/docs/configuration/service/md-conntrack-sync.md +++ /dev/null @@ -1,321 +0,0 @@ -(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" keywork 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 \ - -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 \ - -Protocol for which expect entries need to be synchronized. -``` - - -```{cfgcmd} set service conntrack-sync failover-mechanism vrrp sync-group \ - -Failover mechanism to use for conntrack-sync. - -Only VRRP is supported. Required option. -``` - - -```{cfgcmd} set service conntrack-sync ignore-address \ - -IP addresses or networks for which local conntrack entries will not be synced -``` - - -```{cfgcmd} set service conntrack-sync interface \ - -Interface to use for syncing conntrack entries. -``` - - -```{cfgcmd} set service conntrack-sync interface \ port \ - -Port number used by connection. -``` - - -```{cfgcmd} set service conntrack-sync listen-address \ - -Local IPv4 addresses for service to listen on. -``` - - -```{cfgcmd} set service conntrack-sync mcast-group \ - -Multicast group to use for syncing conntrack entries. - -Defaults to 225.0.0.50. -``` - - -```{cfgcmd} set service conntrack-sync interface \ peer \ - -Peer to send unicast UDP conntrack sync entires to, if not using Multicast -configuration from above above. -``` - - -```{cfgcmd} set service conntrack-sync sync-queue-size \ - -Queue size for syncing conntrack entries in MB. -``` - - -```{cfgcmd} set service conntrack-sync disable-external-cache - -This diable the external cache and directly injects the flow-states into the -in-kernel Connection Tracking System of the backup firewall. -``` - - -```{cfgcmd} set service conntrack-sync purge-timeout \ - -Timeout (in seconds) for purging synchronized entries on handover events. - -On handover, ``conntrackd -t`` is invoked, which schedules a conntrack table -flush after ```` 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/md-console-server.md b/docs/configuration/service/md-console-server.md deleted file mode 100644 index 9402e935..00000000 --- a/docs/configuration/service/md-console-server.md +++ /dev/null @@ -1,139 +0,0 @@ -(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 \ data-bits [7 | 8] - -Configure either seven or eight data bits. This defaults to eight data -bits if left unconfigured. -``` - - -```{cfgcmd} set service console-server device \ description \ - -A user friendly description identifying the connected peripheral. -``` - - -```{cfgcmd} set service console-server device \ alias \ - -A user friendly alias for this connection. Can be used instead of the -device name when connecting. -``` - - -```{cfgcmd} set service console-server device \ parity [even | odd | none] - -Set the parity option for the console. If unset this will default to none. -``` - - -```{cfgcmd} set service console-server device \ stop-bits [1 | 2] - -Configure either one or two stop bits. This defaults to one stop bits if -left unconfigured. -``` - - -```{cfgcmd} set service console-server 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 \ ssh port \ - -Accept SSH connections for the given `` on TCP port ``. -After successfull 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 \ - -Locally connect to serial port identified by ``. - -:::{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/md-dhcp-relay.md b/docs/configuration/service/md-dhcp-relay.md deleted file mode 100644 index a4a10109..00000000 --- a/docs/configuration/service/md-dhcp-relay.md +++ /dev/null @@ -1,205 +0,0 @@ -(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 \ - -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 for DHCP Relay Agent to listen for requests. -``` - -```{cfgcmd} set service dhcp-relay upstream-interface \ - -Interface for DHCP Relay Agent to forward requests out. -``` - -```{cfgcmd} set service dhcp-relay server \ - -Configure IP address of the DHCP `` 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 \ - -Set the maximum hop `` before packets are discarded. Range 0...255, -default 10. -``` - -```{cfgcmd} set service dhcp-relay relay-options max-size \ - -Set maximum `` 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 \ - -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 \ - -Set eth1 to be the listening interface for the DHCPv6 relay. - -Multiple interfaces may be specified. -``` - -```{cfgcmd} set service dhcpv6-relay upstream-interface \ address \ - -Specifies an upstream network `` from which replies from -`` 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 \ - -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/md-dhcp-server.md b/docs/configuration/service/md-dhcp-server.md deleted file mode 100644 index 96c375da..00000000 --- a/docs/configuration/service/md-dhcp-server.md +++ /dev/null @@ -1,1178 +0,0 @@ -(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: `_.` -``` - - -```{cfgcmd} set service dhcp-server shared-network-name \ option 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 \ option domain-search \ - -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 \ option name-server \ - -Inform client that the DNS server can be found at `
`. - -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 \ option vendor-option \ - -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 \ - -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 \ 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 \ subnet \ subnet-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 \ subnet \ option default-router \ - -This is a configuration parameter for the ``, saying that as part of -the response, tell the client that the default gateway can be reached at -`
`. -``` - - -```{cfgcmd} set service dhcp-server shared-network-name \ subnet \ option name-server \ - -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 `
`. - -Multiple DNS servers can be defined. -``` - - -```{cfgcmd} set service dhcp-server shared-network-name \ subnet \ lease \ - -Assign the IP address to this machine for `