From 5a35f4d30e5c16bd85e811176cffa86b721112b7 Mon Sep 17 00:00:00 2001 From: Yuriy Andamasov Date: Sat, 2 May 2026 18:59:58 +0300 Subject: refactor(swap): rename imported .md files to md- prefix for swap mechanism MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Restore the canary file naming convention that swap_sources.py expects: the imported MyST pages now live as docs//md-.md alongside the existing docs//.rst, so swap_sources.py --swap can rename them into place at build time. - 254 .md files renamed (every page with a matching .rst counterpart) - 2 MyST-only pages left at their final names (no .rst exists, no swap needed): docs/copyright.md, docs/automation/terraform/terraformvyos.md All 114 stems listed in docs/_swap.txt now have a corresponding md-.md source file ready to swap in. 🤖 Generated by [robots](https://vyos.io) --- docs/configuration/container/index.md | 479 ------ docs/configuration/container/md-index.md | 479 ++++++ docs/configuration/firewall/bridge.md | 685 --------- docs/configuration/firewall/flowtables.md | 176 --- docs/configuration/firewall/global-options.md | 186 --- docs/configuration/firewall/groups.md | 477 ------ docs/configuration/firewall/index.md | 278 ---- docs/configuration/firewall/ipv4.md | 1544 ------------------- docs/configuration/firewall/ipv6.md | 1567 -------------------- 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 | 1544 +++++++++++++++++++ docs/configuration/firewall/md-ipv6.md | 1567 ++++++++++++++++++++ docs/configuration/firewall/md-zone.md | 201 +++ docs/configuration/firewall/zone.md | 201 --- docs/configuration/highavailability/index.md | 561 ------- docs/configuration/highavailability/md-index.md | 561 +++++++ docs/configuration/index.md | 23 - docs/configuration/interfaces/bonding.md | 764 ---------- docs/configuration/interfaces/bridge.md | 431 ------ docs/configuration/interfaces/dummy.md | 87 -- docs/configuration/interfaces/ethernet.md | 515 ------- docs/configuration/interfaces/geneve.md | 105 -- docs/configuration/interfaces/index.md | 26 - docs/configuration/interfaces/l2tpv3.md | 170 --- docs/configuration/interfaces/loopback.md | 67 - docs/configuration/interfaces/macsec.md | 319 ---- 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/interfaces/openvpn-examples.md | 769 ---------- docs/configuration/interfaces/openvpn.md | 614 -------- docs/configuration/interfaces/pppoe.md | 419 ------ docs/configuration/interfaces/pseudo-ethernet.md | 52 - docs/configuration/interfaces/sstp-client.md | 170 --- docs/configuration/interfaces/tunnel.md | 309 ---- docs/configuration/interfaces/virtual-ethernet.md | 119 -- docs/configuration/interfaces/vti.md | 121 -- docs/configuration/interfaces/vxlan.md | 373 ----- docs/configuration/interfaces/wireguard.md | 434 ------ docs/configuration/interfaces/wireless.md | 923 ------------ docs/configuration/interfaces/wwan.md | 355 ----- docs/configuration/loadbalancing/haproxy.md | 510 ------- docs/configuration/loadbalancing/index.md | 15 - docs/configuration/loadbalancing/md-haproxy.md | 510 +++++++ docs/configuration/loadbalancing/md-index.md | 15 + docs/configuration/loadbalancing/md-wan.md | 306 ++++ docs/configuration/loadbalancing/wan.md | 306 ---- docs/configuration/md-index.md | 23 + docs/configuration/nat/cgnat.md | 200 --- docs/configuration/nat/index.md | 13 - 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/nat/nat44.md | 788 ---------- docs/configuration/nat/nat64.md | 73 - docs/configuration/nat/nat66.md | 243 --- docs/configuration/pki/index.md | 583 -------- docs/configuration/pki/md-index.md | 583 ++++++++ docs/configuration/policy/access-list.md | 70 - docs/configuration/policy/as-path-list.md | 29 - docs/configuration/policy/community-list.md | 29 - docs/configuration/policy/examples.md | 205 --- docs/configuration/policy/extcommunity-list.md | 33 - docs/configuration/policy/index.md | 53 - docs/configuration/policy/large-community-list.md | 29 - docs/configuration/policy/local-route.md | 100 -- 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/policy/prefix-list.md | 152 -- docs/configuration/policy/route-map.md | 439 ------ docs/configuration/policy/route.md | 424 ------ docs/configuration/protocols/arp.md | 72 - docs/configuration/protocols/babel.md | 296 ---- docs/configuration/protocols/bfd.md | 205 --- docs/configuration/protocols/bgp.md | 1414 ------------------ docs/configuration/protocols/failover.md | 237 --- docs/configuration/protocols/igmp-proxy.md | 79 - docs/configuration/protocols/index.md | 25 - docs/configuration/protocols/isis.md | 746 ---------- 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/protocols/mpls.md | 285 ---- docs/configuration/protocols/multicast.md | 31 - docs/configuration/protocols/openfabric.md | 242 --- docs/configuration/protocols/ospf.md | 1504 ------------------- docs/configuration/protocols/pim.md | 282 ---- docs/configuration/protocols/pim6.md | 100 -- docs/configuration/protocols/rip.md | 294 ---- docs/configuration/protocols/rpki.md | 210 --- docs/configuration/protocols/segment-routing.md | 359 ----- docs/configuration/protocols/static.md | 298 ---- .../configuration/protocols/traffic-engineering.md | 54 - docs/configuration/service/broadcast-relay.md | 70 - docs/configuration/service/config-sync.md | 164 -- docs/configuration/service/conntrack-sync.md | 321 ---- docs/configuration/service/console-server.md | 139 -- docs/configuration/service/dhcp-relay.md | 205 --- docs/configuration/service/dhcp-server.md | 1178 --------------- docs/configuration/service/dns.md | 582 -------- docs/configuration/service/eventhandler.md | 130 -- docs/configuration/service/https.md | 138 -- docs/configuration/service/index.md | 29 - docs/configuration/service/ipoe-server.md | 512 ------- docs/configuration/service/lldp.md | 154 -- 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/service/mdns.md | 131 -- docs/configuration/service/monitoring.md | 334 ----- docs/configuration/service/ntp.md | 202 --- docs/configuration/service/pppoe-server.md | 753 ---------- docs/configuration/service/router-advert.md | 121 -- docs/configuration/service/salt-minion.md | 51 - docs/configuration/service/snmp.md | 258 ---- docs/configuration/service/ssh.md | 366 ----- docs/configuration/service/suricata.md | 93 -- docs/configuration/service/tftp-server.md | 78 - docs/configuration/service/webproxy.md | 459 ------ docs/configuration/system/acceleration.md | 158 -- docs/configuration/system/conntrack.md | 218 --- docs/configuration/system/console.md | 59 - docs/configuration/system/default-route.md | 40 - docs/configuration/system/flow-accounting.md | 209 --- docs/configuration/system/frr.md | 45 - docs/configuration/system/host-name.md | 70 - docs/configuration/system/index.md | 34 - docs/configuration/system/ip.md | 126 -- docs/configuration/system/ipv6.md | 193 --- docs/configuration/system/lcd.md | 41 - docs/configuration/system/login.md | 604 -------- 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/system/name-server.md | 65 - docs/configuration/system/option.md | 190 --- docs/configuration/system/proxy.md | 27 - docs/configuration/system/sflow.md | 66 - docs/configuration/system/sysctl.md | 16 - docs/configuration/system/syslog.md | 450 ------ docs/configuration/system/task-scheduler.md | 45 - docs/configuration/system/time-zone.md | 17 - docs/configuration/system/updates.md | 36 - docs/configuration/system/watchdog.md | 212 --- docs/configuration/trafficpolicy/index.md | 1299 ---------------- docs/configuration/trafficpolicy/md-index.md | 1299 ++++++++++++++++ docs/configuration/vpn/dmvpn.md | 431 ------ docs/configuration/vpn/index.md | 14 - docs/configuration/vpn/ipsec/index.md | 11 - docs/configuration/vpn/ipsec/ipsec_general.md | 407 ----- 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/ipsec/remoteaccess_ipsec.md | 186 --- docs/configuration/vpn/ipsec/site2site_ipsec.md | 780 ---------- .../vpn/ipsec/troubleshooting_ipsec.md | 313 ---- docs/configuration/vpn/l2tp.md | 624 -------- 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/vpn/openconnect.md | 330 ----- docs/configuration/vpn/pptp.md | 594 -------- docs/configuration/vpn/rsa-keys.md | 114 -- docs/configuration/vpn/sstp.md | 698 --------- docs/configuration/vrf/index.md | 646 -------- docs/configuration/vrf/md-index.md | 646 ++++++++ 260 files changed, 40182 insertions(+), 40182 deletions(-) delete mode 100644 docs/configuration/container/index.md create mode 100644 docs/configuration/container/md-index.md delete mode 100644 docs/configuration/firewall/bridge.md delete mode 100644 docs/configuration/firewall/flowtables.md delete mode 100644 docs/configuration/firewall/global-options.md delete mode 100644 docs/configuration/firewall/groups.md delete mode 100644 docs/configuration/firewall/index.md delete mode 100644 docs/configuration/firewall/ipv4.md delete mode 100644 docs/configuration/firewall/ipv6.md create mode 100644 docs/configuration/firewall/md-bridge.md create mode 100644 docs/configuration/firewall/md-flowtables.md create mode 100644 docs/configuration/firewall/md-global-options.md create mode 100644 docs/configuration/firewall/md-groups.md create mode 100644 docs/configuration/firewall/md-index.md create mode 100644 docs/configuration/firewall/md-ipv4.md create mode 100644 docs/configuration/firewall/md-ipv6.md create mode 100644 docs/configuration/firewall/md-zone.md delete mode 100644 docs/configuration/firewall/zone.md delete mode 100644 docs/configuration/highavailability/index.md create mode 100644 docs/configuration/highavailability/md-index.md delete mode 100644 docs/configuration/index.md delete mode 100644 docs/configuration/interfaces/bonding.md delete mode 100644 docs/configuration/interfaces/bridge.md delete mode 100644 docs/configuration/interfaces/dummy.md delete mode 100644 docs/configuration/interfaces/ethernet.md delete mode 100644 docs/configuration/interfaces/geneve.md delete mode 100644 docs/configuration/interfaces/index.md delete mode 100644 docs/configuration/interfaces/l2tpv3.md delete mode 100644 docs/configuration/interfaces/loopback.md delete mode 100644 docs/configuration/interfaces/macsec.md create mode 100644 docs/configuration/interfaces/md-bonding.md create mode 100644 docs/configuration/interfaces/md-bridge.md create mode 100644 docs/configuration/interfaces/md-dummy.md create mode 100644 docs/configuration/interfaces/md-ethernet.md create mode 100644 docs/configuration/interfaces/md-geneve.md create mode 100644 docs/configuration/interfaces/md-index.md create mode 100644 docs/configuration/interfaces/md-l2tpv3.md create mode 100644 docs/configuration/interfaces/md-loopback.md create mode 100644 docs/configuration/interfaces/md-macsec.md create mode 100644 docs/configuration/interfaces/md-openvpn-examples.md create mode 100644 docs/configuration/interfaces/md-openvpn.md create mode 100644 docs/configuration/interfaces/md-pppoe.md create mode 100644 docs/configuration/interfaces/md-pseudo-ethernet.md create mode 100644 docs/configuration/interfaces/md-sstp-client.md create mode 100644 docs/configuration/interfaces/md-tunnel.md create mode 100644 docs/configuration/interfaces/md-virtual-ethernet.md create mode 100644 docs/configuration/interfaces/md-vti.md create mode 100644 docs/configuration/interfaces/md-vxlan.md create mode 100644 docs/configuration/interfaces/md-wireguard.md create mode 100644 docs/configuration/interfaces/md-wireless.md create mode 100644 docs/configuration/interfaces/md-wwan.md delete mode 100644 docs/configuration/interfaces/openvpn-examples.md delete mode 100644 docs/configuration/interfaces/openvpn.md delete mode 100644 docs/configuration/interfaces/pppoe.md delete mode 100644 docs/configuration/interfaces/pseudo-ethernet.md delete mode 100644 docs/configuration/interfaces/sstp-client.md delete mode 100644 docs/configuration/interfaces/tunnel.md delete mode 100644 docs/configuration/interfaces/virtual-ethernet.md delete mode 100644 docs/configuration/interfaces/vti.md delete mode 100644 docs/configuration/interfaces/vxlan.md delete mode 100644 docs/configuration/interfaces/wireguard.md delete mode 100644 docs/configuration/interfaces/wireless.md delete mode 100644 docs/configuration/interfaces/wwan.md delete mode 100644 docs/configuration/loadbalancing/haproxy.md delete mode 100644 docs/configuration/loadbalancing/index.md create mode 100644 docs/configuration/loadbalancing/md-haproxy.md create mode 100644 docs/configuration/loadbalancing/md-index.md create mode 100644 docs/configuration/loadbalancing/md-wan.md delete mode 100644 docs/configuration/loadbalancing/wan.md create mode 100644 docs/configuration/md-index.md delete mode 100644 docs/configuration/nat/cgnat.md delete mode 100644 docs/configuration/nat/index.md create mode 100644 docs/configuration/nat/md-cgnat.md create mode 100644 docs/configuration/nat/md-index.md create mode 100644 docs/configuration/nat/md-nat44.md create mode 100644 docs/configuration/nat/md-nat64.md create mode 100644 docs/configuration/nat/md-nat66.md delete mode 100644 docs/configuration/nat/nat44.md delete mode 100644 docs/configuration/nat/nat64.md delete mode 100644 docs/configuration/nat/nat66.md delete mode 100644 docs/configuration/pki/index.md create mode 100644 docs/configuration/pki/md-index.md delete mode 100644 docs/configuration/policy/access-list.md delete mode 100644 docs/configuration/policy/as-path-list.md delete mode 100644 docs/configuration/policy/community-list.md delete mode 100644 docs/configuration/policy/examples.md delete mode 100644 docs/configuration/policy/extcommunity-list.md delete mode 100644 docs/configuration/policy/index.md delete mode 100644 docs/configuration/policy/large-community-list.md delete mode 100644 docs/configuration/policy/local-route.md create mode 100644 docs/configuration/policy/md-access-list.md create mode 100644 docs/configuration/policy/md-as-path-list.md create mode 100644 docs/configuration/policy/md-community-list.md create mode 100644 docs/configuration/policy/md-examples.md create mode 100644 docs/configuration/policy/md-extcommunity-list.md create mode 100644 docs/configuration/policy/md-index.md create mode 100644 docs/configuration/policy/md-large-community-list.md create mode 100644 docs/configuration/policy/md-local-route.md create mode 100644 docs/configuration/policy/md-prefix-list.md create mode 100644 docs/configuration/policy/md-route-map.md create mode 100644 docs/configuration/policy/md-route.md delete mode 100644 docs/configuration/policy/prefix-list.md delete mode 100644 docs/configuration/policy/route-map.md delete mode 100644 docs/configuration/policy/route.md delete mode 100644 docs/configuration/protocols/arp.md delete mode 100644 docs/configuration/protocols/babel.md delete mode 100644 docs/configuration/protocols/bfd.md delete mode 100644 docs/configuration/protocols/bgp.md delete mode 100644 docs/configuration/protocols/failover.md delete mode 100644 docs/configuration/protocols/igmp-proxy.md delete mode 100644 docs/configuration/protocols/index.md delete mode 100644 docs/configuration/protocols/isis.md create mode 100644 docs/configuration/protocols/md-arp.md create mode 100644 docs/configuration/protocols/md-babel.md create mode 100644 docs/configuration/protocols/md-bfd.md create mode 100644 docs/configuration/protocols/md-bgp.md create mode 100644 docs/configuration/protocols/md-failover.md create mode 100644 docs/configuration/protocols/md-igmp-proxy.md create mode 100644 docs/configuration/protocols/md-index.md create mode 100644 docs/configuration/protocols/md-isis.md create mode 100644 docs/configuration/protocols/md-mpls.md create mode 100644 docs/configuration/protocols/md-multicast.md create mode 100644 docs/configuration/protocols/md-openfabric.md create mode 100644 docs/configuration/protocols/md-ospf.md create mode 100644 docs/configuration/protocols/md-pim.md create mode 100644 docs/configuration/protocols/md-pim6.md create mode 100644 docs/configuration/protocols/md-rip.md create mode 100644 docs/configuration/protocols/md-rpki.md create mode 100644 docs/configuration/protocols/md-segment-routing.md create mode 100644 docs/configuration/protocols/md-static.md create mode 100644 docs/configuration/protocols/md-traffic-engineering.md delete mode 100644 docs/configuration/protocols/mpls.md delete mode 100644 docs/configuration/protocols/multicast.md delete mode 100644 docs/configuration/protocols/openfabric.md delete mode 100644 docs/configuration/protocols/ospf.md delete mode 100644 docs/configuration/protocols/pim.md delete mode 100644 docs/configuration/protocols/pim6.md delete mode 100644 docs/configuration/protocols/rip.md delete mode 100644 docs/configuration/protocols/rpki.md delete mode 100644 docs/configuration/protocols/segment-routing.md delete mode 100644 docs/configuration/protocols/static.md delete mode 100644 docs/configuration/protocols/traffic-engineering.md delete mode 100644 docs/configuration/service/broadcast-relay.md delete mode 100644 docs/configuration/service/config-sync.md delete mode 100644 docs/configuration/service/conntrack-sync.md delete mode 100644 docs/configuration/service/console-server.md delete mode 100644 docs/configuration/service/dhcp-relay.md delete mode 100644 docs/configuration/service/dhcp-server.md delete mode 100644 docs/configuration/service/dns.md delete mode 100644 docs/configuration/service/eventhandler.md delete mode 100644 docs/configuration/service/https.md delete mode 100644 docs/configuration/service/index.md delete mode 100644 docs/configuration/service/ipoe-server.md delete mode 100644 docs/configuration/service/lldp.md create mode 100644 docs/configuration/service/md-broadcast-relay.md create mode 100644 docs/configuration/service/md-config-sync.md create mode 100644 docs/configuration/service/md-conntrack-sync.md create mode 100644 docs/configuration/service/md-console-server.md create mode 100644 docs/configuration/service/md-dhcp-relay.md create mode 100644 docs/configuration/service/md-dhcp-server.md create mode 100644 docs/configuration/service/md-dns.md create mode 100644 docs/configuration/service/md-eventhandler.md create mode 100644 docs/configuration/service/md-https.md create mode 100644 docs/configuration/service/md-index.md create mode 100644 docs/configuration/service/md-ipoe-server.md create mode 100644 docs/configuration/service/md-lldp.md create mode 100644 docs/configuration/service/md-mdns.md create mode 100644 docs/configuration/service/md-monitoring.md create mode 100644 docs/configuration/service/md-ntp.md create mode 100644 docs/configuration/service/md-pppoe-server.md create mode 100644 docs/configuration/service/md-router-advert.md create mode 100644 docs/configuration/service/md-salt-minion.md create mode 100644 docs/configuration/service/md-snmp.md create mode 100644 docs/configuration/service/md-ssh.md create mode 100644 docs/configuration/service/md-suricata.md create mode 100644 docs/configuration/service/md-tftp-server.md create mode 100644 docs/configuration/service/md-webproxy.md delete mode 100644 docs/configuration/service/mdns.md delete mode 100644 docs/configuration/service/monitoring.md delete mode 100644 docs/configuration/service/ntp.md delete mode 100644 docs/configuration/service/pppoe-server.md delete mode 100644 docs/configuration/service/router-advert.md delete mode 100644 docs/configuration/service/salt-minion.md delete mode 100644 docs/configuration/service/snmp.md delete mode 100644 docs/configuration/service/ssh.md delete mode 100644 docs/configuration/service/suricata.md delete mode 100644 docs/configuration/service/tftp-server.md delete mode 100644 docs/configuration/service/webproxy.md delete mode 100644 docs/configuration/system/acceleration.md delete mode 100644 docs/configuration/system/conntrack.md delete mode 100644 docs/configuration/system/console.md delete mode 100644 docs/configuration/system/default-route.md delete mode 100644 docs/configuration/system/flow-accounting.md delete mode 100644 docs/configuration/system/frr.md delete mode 100644 docs/configuration/system/host-name.md delete mode 100644 docs/configuration/system/index.md delete mode 100644 docs/configuration/system/ip.md delete mode 100644 docs/configuration/system/ipv6.md delete mode 100644 docs/configuration/system/lcd.md delete mode 100644 docs/configuration/system/login.md create mode 100644 docs/configuration/system/md-acceleration.md create mode 100644 docs/configuration/system/md-conntrack.md create mode 100644 docs/configuration/system/md-console.md create mode 100644 docs/configuration/system/md-default-route.md create mode 100644 docs/configuration/system/md-flow-accounting.md create mode 100644 docs/configuration/system/md-frr.md create mode 100644 docs/configuration/system/md-host-name.md create mode 100644 docs/configuration/system/md-index.md create mode 100644 docs/configuration/system/md-ip.md create mode 100644 docs/configuration/system/md-ipv6.md create mode 100644 docs/configuration/system/md-lcd.md create mode 100644 docs/configuration/system/md-login.md create mode 100644 docs/configuration/system/md-name-server.md create mode 100644 docs/configuration/system/md-option.md create mode 100644 docs/configuration/system/md-proxy.md create mode 100644 docs/configuration/system/md-sflow.md create mode 100644 docs/configuration/system/md-sysctl.md create mode 100644 docs/configuration/system/md-syslog.md create mode 100644 docs/configuration/system/md-task-scheduler.md create mode 100644 docs/configuration/system/md-time-zone.md create mode 100644 docs/configuration/system/md-updates.md create mode 100644 docs/configuration/system/md-watchdog.md delete mode 100644 docs/configuration/system/name-server.md delete mode 100644 docs/configuration/system/option.md delete mode 100644 docs/configuration/system/proxy.md delete mode 100644 docs/configuration/system/sflow.md delete mode 100644 docs/configuration/system/sysctl.md delete mode 100644 docs/configuration/system/syslog.md delete mode 100644 docs/configuration/system/task-scheduler.md delete mode 100644 docs/configuration/system/time-zone.md delete mode 100644 docs/configuration/system/updates.md delete mode 100644 docs/configuration/system/watchdog.md delete mode 100644 docs/configuration/trafficpolicy/index.md create mode 100644 docs/configuration/trafficpolicy/md-index.md delete mode 100644 docs/configuration/vpn/dmvpn.md delete mode 100644 docs/configuration/vpn/index.md delete mode 100644 docs/configuration/vpn/ipsec/index.md delete mode 100644 docs/configuration/vpn/ipsec/ipsec_general.md create mode 100644 docs/configuration/vpn/ipsec/md-index.md create mode 100644 docs/configuration/vpn/ipsec/md-ipsec_general.md create mode 100644 docs/configuration/vpn/ipsec/md-remoteaccess_ipsec.md create mode 100644 docs/configuration/vpn/ipsec/md-site2site_ipsec.md create mode 100644 docs/configuration/vpn/ipsec/md-troubleshooting_ipsec.md delete mode 100644 docs/configuration/vpn/ipsec/remoteaccess_ipsec.md delete mode 100644 docs/configuration/vpn/ipsec/site2site_ipsec.md delete mode 100644 docs/configuration/vpn/ipsec/troubleshooting_ipsec.md delete mode 100644 docs/configuration/vpn/l2tp.md create mode 100644 docs/configuration/vpn/md-dmvpn.md create mode 100644 docs/configuration/vpn/md-index.md create mode 100644 docs/configuration/vpn/md-l2tp.md create mode 100644 docs/configuration/vpn/md-openconnect.md create mode 100644 docs/configuration/vpn/md-pptp.md create mode 100644 docs/configuration/vpn/md-rsa-keys.md create mode 100644 docs/configuration/vpn/md-sstp.md delete mode 100644 docs/configuration/vpn/openconnect.md delete mode 100644 docs/configuration/vpn/pptp.md delete mode 100644 docs/configuration/vpn/rsa-keys.md delete mode 100644 docs/configuration/vpn/sstp.md delete mode 100644 docs/configuration/vrf/index.md create mode 100644 docs/configuration/vrf/md-index.md (limited to 'docs/configuration') diff --git a/docs/configuration/container/index.md b/docs/configuration/container/index.md deleted file mode 100644 index 6cb64225..00000000 --- a/docs/configuration/container/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 deamonless 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/container/md-index.md b/docs/configuration/container/md-index.md new file mode 100644 index 00000000..6cb64225 --- /dev/null +++ b/docs/configuration/container/md-index.md @@ -0,0 +1,479 @@ +--- +lastproofread: '2024-07-03' +--- + +# Container + +The VyOS container implementation is based on [Podman](https://podman.io/) as +a deamonless 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/bridge.md b/docs/configuration/firewall/bridge.md deleted file mode 100644 index 58acd531..00000000 --- a/docs/configuration/firewall/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 feaure 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/flowtables.md b/docs/configuration/firewall/flowtables.md deleted file mode 100644 index 24d0675e..00000000 --- a/docs/configuration/firewall/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/global-options.md b/docs/configuration/firewall/global-options.md deleted file mode 100644 index 0f6d91ac..00000000 --- a/docs/configuration/firewall/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/groups.md b/docs/configuration/firewall/groups.md deleted file mode 100644 index 817f610e..00000000 --- a/docs/configuration/firewall/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/index.md b/docs/configuration/firewall/index.md deleted file mode 100644 index 81699154..00000000 --- a/docs/configuration/firewall/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 - filter ...``. 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] - destination...``. -``` - -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/ipv4.md b/docs/configuration/firewall/ipv4.md deleted file mode 100644 index 04c4fc70..00000000 --- a/docs/configuration/firewall/ipv4.md +++ /dev/null @@ -1,1544 +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 input filter 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'. -``` - -```{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 \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> recent time \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> recent time \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> recent time \ - -Match when 'count' amount of connections appear within 'time'. Use these -matching criteria to block brute-force attempts. -``` - -### 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/ipv6.md b/docs/configuration/firewall/ipv6.md deleted file mode 100644 index 0ba30110..00000000 --- a/docs/configuration/firewall/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 ipv4 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-bridge.md b/docs/configuration/firewall/md-bridge.md new file mode 100644 index 00000000..58acd531 --- /dev/null +++ b/docs/configuration/firewall/md-bridge.md @@ -0,0 +1,685 @@ +--- +lastproofread: '2026-03-28' +--- + +(firewall-configuration)= + +# Bridge Firewall Configuration + +## Overview + +Learn more about bridge firewall configuration +and related op-mode commands. + +The following commands are covered in this section: + +```{cfgcmd} set firewall bridge \ +``` + +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 feaure 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 new file mode 100644 index 00000000..24d0675e --- /dev/null +++ b/docs/configuration/firewall/md-flowtables.md @@ -0,0 +1,176 @@ +--- +lastproofread: '2026-03-30' +--- + +(firewall-flowtables-configuration)= + +# Flowtables Firewall Configuration + +```{include} /_include/need_improvement.txt +``` + + +## Overview + +This section provides information on firewall configuration for flowtables. + +```{cfgcmd} set firewall flowtable ... +``` + +To learn about the general traffic flow in VyOS firewalls, +see {doc}`Firewall `. + +```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 new file mode 100644 index 00000000..0f6d91ac --- /dev/null +++ b/docs/configuration/firewall/md-global-options.md @@ -0,0 +1,186 @@ +--- +lastproofread: '2026-03-30' +--- + +(firewall-global-options-configuration)= + +# Global Options Firewall Configuration + +## Overview + +Some firewall settings are global and affect the entire system. This section +provides information about these global options that you can configure using +the VyOS CLI. + +Configuration commands covered in this section: + +```{cfgcmd} set firewall global-options ... +``` + +## Configuration + +```{cfgcmd} set firewall global-options all-ping [enable | disable] + +By default, when VyOS receives an ICMP echo request packet destined for +itself, it answers with an ICMP echo reply, unless your firewall prevents +it. + +You can set firewall rules to accept, drop, or reject ICMP in, out, or +local traffic. You can also use the **firewall global-options all-ping** +command. This command affects only LOCAL traffic (packets destined for your +VyOS system), not IN or OUT traffic. + +:::{note} +**firewall global-options all-ping** affects only LOCAL traffic +and always behaves in the most restrictive way +::: +:::{code-block} none +set firewall global-options all-ping enable +::: +When you set this command, VyOS answers every ICMP echo request addressed +to itself, but that response occurs only if no other rule drops or rejects +local echo requests. In case of conflict, VyOS does not answer ICMP echo +requests. + +:::{code-block} none +set firewall global-options all-ping disable +::: +When you set this command, VyOS answers no ICMP echo requests addressed to +itself, regardless of where they come from or what specific rules accept +them. +``` + +```{cfgcmd} set firewall global-options apply-to-bridged-traffic [ipv4 | ipv6] + +Apply IPv4 or IPv6 firewall rules to bridged traffic. +``` + +```{cfgcmd} set firewall global-options broadcast-ping [enable | disable] + +Enable or disable the response to ICMP broadcast messages. The system +alters the following parameter: +* ``net.ipv4.icmp_echo_ignore_broadcasts`` +``` + +```{cfgcmd} set firewall global-options ip-src-route [enable | disable] +``` + +```{cfgcmd} set firewall global-options ipv6-src-route [enable | disable] + +Set whether VyOS accepts packets with a source route option. +The following sysctl parameters will be changed: +* ``net.ipv4.conf.all.accept_source_route`` +* ``net.ipv6.conf.all.accept_source_route`` +``` + +```{cfgcmd} set firewall global-options receive-redirects [enable | disable] +``` + +```{cfgcmd} set firewall global-options ipv6-receive-redirects [enable | disable] + +Allow VyOS to accept ICMPv4 and ICMPv6 redirect messages. +The following sysctl parameters will be changed: +* ``net.ipv4.conf.all.accept_redirects`` +* ``net.ipv6.conf.all.accept_redirects`` +``` + +```{cfgcmd} set firewall global-options send-redirects [enable | disable] + +Allow VyOS to send ICMPv4 redirect messages. +The following sysctl parameter will be changed: +* ``net.ipv4.conf.all.send_redirects`` +``` + +```{cfgcmd} set firewall global-options log-martians [enable | disable] + +Allow VyOS to log martian IPv4 packets. +The following sysctl parameter will be changed: +* ``net.ipv4.conf.all.log_martians`` +``` + +```{cfgcmd} set firewall global-options source-validation [strict | loose | disable] + +Set the IPv4 source validation mode. +The following sysctl parameter will be changed: +* ``net.ipv4.conf.all.rp_filter`` +``` + +```{cfgcmd} set firewall global-options syn-cookies [enable | disable] + +Allow VyOS to use IPv4 TCP SYN Cookies. +The following sysctl parameter will be changed: +* ``net.ipv4.tcp_syncookies`` +``` + +```{cfgcmd} set firewall global-options twa-hazards-protection [enable | disable] + +Enable or disable VyOS {rfc}`1337` conformance. +The following sysctl parameter will be changed: +* ``net.ipv4.tcp_rfc1337`` +``` + +```{cfgcmd} set firewall global-options state-policy established action [accept | drop | reject] +``` + +```{cfgcmd} set firewall global-options state-policy established log +``` + +```{cfgcmd} set firewall global-options state-policy established log-level [emerg | alert | crit | err | warn | notice | info | debug] + +Set the global setting for an established connection. +``` + +```{cfgcmd} set firewall global-options state-policy invalid action [accept | drop | reject] +``` + +```{cfgcmd} set firewall global-options state-policy invalid log +``` + +```{cfgcmd} set firewall global-options state-policy invalid log-level [emerg | alert | crit | err | warn | notice | info | debug] + +Set the global setting for invalid packets. +``` + +```{cfgcmd} set firewall global-options state-policy related action [accept | drop | reject] +``` + +```{cfgcmd} set firewall global-options state-policy related log +``` + +```{cfgcmd} set firewall global-options state-policy related log-level [emerg | alert | crit | err | warn | notice | info | debug] + +Set the global setting for related connections. +``` + +VyOS supports setting timeouts for connections by connection type. You can +set timeout values for generic connections, ICMP connections, UDP +connections, or TCP connections in various states. + +```{eval-rst} +.. cfgcmd:: set firewall global-options timeout icmp <1-21474836> + :defaultvalue: +.. cfgcmd:: set firewall global-options timeout other <1-21474836> + :defaultvalue: +.. cfgcmd:: set firewall global-options timeout tcp close <1-21474836> + :defaultvalue: +.. cfgcmd:: set firewall global-options timeout tcp close-wait <1-21474836> + :defaultvalue: +.. cfgcmd:: set firewall global-options timeout tcp established <1-21474836> + :defaultvalue: +.. cfgcmd:: set firewall global-options timeout tcp fin-wait <1-21474836> + :defaultvalue: +.. cfgcmd:: set firewall global-options timeout tcp last-ack <1-21474836> + :defaultvalue: +.. cfgcmd:: set firewall global-options timeout tcp syn-recv <1-21474836> + :defaultvalue: +.. cfgcmd:: set firewall global-options timeout tcp syn-sent <1-21474836> + :defaultvalue: +.. cfgcmd:: set firewall global-options timeout tcp time-wait <1-21474836> + :defaultvalue: +.. cfgcmd:: set firewall global-options timeout udp other <1-21474836> + :defaultvalue: +.. cfgcmd:: set firewall global-options timeout udp stream <1-21474836> + :defaultvalue: + + Set the timeout in seconds for a protocol or state. +``` \ No newline at end of file diff --git a/docs/configuration/firewall/md-groups.md b/docs/configuration/firewall/md-groups.md new file mode 100644 index 00000000..817f610e --- /dev/null +++ b/docs/configuration/firewall/md-groups.md @@ -0,0 +1,477 @@ +--- +lastproofread: '2026-03-30' +--- + +(firewall-groups-configuration)= + +# Firewall groups + +## Configuration + +Firewall groups represent collections of IP addresses, networks, ports, +MAC addresses, domains, or interfaces. You can reference a group in firewall, +NAT, and policy route rules as either a source or destination matcher, and/or +as inbound or outbound in the case of interface groups. + +### Address Groups + +An **address group** contains a single IP address or IP address range. + +```{cfgcmd} set firewall group address-group \ 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 new file mode 100644 index 00000000..81699154 --- /dev/null +++ b/docs/configuration/firewall/md-index.md @@ -0,0 +1,278 @@ +--- +lastproofread: '2026-03-30' +--- + +# Firewall + +:::{warning} +Due to a boot-time race condition, all interfaces initialize +before the firewall. This temporarily leaves the system open to all traffic +and poses a security risk. +::: + +VyOS uses Netfilter. The Netfilter +project developed `iptables` and its successor `nftables` for the Linux +kernel to process packet data flows directly. This extends the concept of +zone-based security to let you manipulate data at multiple stages after the +network interface and driver accept it, and before sending it to its +destination (for example, a web server or another device). + +The following is a simplified traffic flow diagram based on Netfilter +packet flow. +This diagram provides an overview of how packets are processed and the +possible paths traffic can take. + +:::{figure} /_static/images/firewall-gral-packet-flow.webp +::: + +The main points regarding packet flow and terminology in VyOS firewall +are: + +- **Bridge Port?**: Choose the appropriate path based on whether the + interface where the packet was received is part of a bridge. + +If the interface where the packet was received is not part of a bridge, the +packet is processed at the **IP Layer**: + +```{eval-rst} + * **Prerouting**: The router processes all packets in this stage, + regardless of the destination. You can perform several actions in + this stage, and these actions are also defined in different parts of the + VyOS configuration. Order is important. The relevant configuration that + applies in this stage includes: + + * **Firewall prerouting**: Rules you define under ``set firewall + [ipv4 | ipv6] prerouting raw...``. The system processes all rules in + this section before the connection tracking subsystem. + + * **Conntrack Ignore**: Rules you define under ``set system conntrack + ignore [ipv4 | ipv6] ...``. You can configure this section with + ``firewall [ipv4 | ipv6] prerouting ...``. For compatibility reasons, + this feature is supported, but will be deprecated in the future. + + * **Policy Route**: Rules you define under ``set policy [route | + route6] ...``. + + * **Destination NAT**: Rules you define under ``set [nat | nat66] + destination...``. + + * **Destination is the router?**: Choose the appropriate path based on the + destination IP address. Transit traffic continues to **forward**, while + traffic destined for the router continues to **input**. + + * **Input**: The stage where you filter and control traffic destined for + the router itself. This is where you enforce all rules for securing the + router. This includes IPv4 and IPv6 filtering rules, defined in: + + * ``set firewall ipv4 input filter ...``. + + * ``set firewall ipv6 input filter ...``. + + * **Forward**: The stage where you filter and control transit traffic. + This includes IPv4 and IPv6 filtering rules, defined in: + + * ``set firewall ipv4 forward filter ...``. + + * ``set firewall ipv6 forward filter ...``. + + * **Output**: The stage where you filter and control traffic that the + router originates. Note that this traffic comes from either a new + connection that an internal process on the VyOS router (such as NTP) + originates or a response to traffic the router receives externally through + **input** (for example, a response to an SSH login attempt). This includes + IPv4 and IPv6 rules, and two different sections apply: + + * **Output Prerouting**: ``set firewall [ipv4 | ipv6] output + filter ...``. 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] + destination...``. +``` + +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 new file mode 100644 index 00000000..04c4fc70 --- /dev/null +++ b/docs/configuration/firewall/md-ipv4.md @@ -0,0 +1,1544 @@ +--- +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 input filter 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'. +``` + +```{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 \ +``` + +```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> recent time \ +``` + +```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> recent time \ +``` + +```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> recent time \ + +Match when 'count' amount of connections appear within 'time'. Use these +matching criteria to block brute-force attempts. +``` + +### 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 new file mode 100644 index 00000000..0ba30110 --- /dev/null +++ b/docs/configuration/firewall/md-ipv6.md @@ -0,0 +1,1567 @@ +--- +lastproofread: '2026-04-01' +--- + +(firewall-ipv6-configuration)= + +# IPv6 Firewall Configuration + +## Overview + +This section covers useful information about IPv6 firewall configuration and +appropriate operation-mode commands. + +This section describes the following configuration commands: + +```{cfgcmd} set firewall ipv6 ... +``` + +To learn about the general traffic flow in VyOS firewalls, see {doc}`Firewall `. + +```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 ipv4 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 new file mode 100644 index 00000000..bbb93993 --- /dev/null +++ b/docs/configuration/firewall/md-zone.md @@ -0,0 +1,201 @@ +--- +lastproofread: '2026-03-30' +--- + +(firewall-zone)= + +# Zone-Based Firewall + +## Overview + +:::{note} +All VyOS versions built after 2023-10-22 (VyOS 1.4 and 1.5) support +this feature. +::: + +This section provides information on firewall configuration for the +zone-based firewall. This section covers the following configuration +commands: + +```{cfgcmd} set firewall zone ... +``` + +To learn about the general traffic flow in VyOS firewalls, +see {doc}`Firewall `. + +```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/firewall/zone.md b/docs/configuration/firewall/zone.md deleted file mode 100644 index bbb93993..00000000 --- a/docs/configuration/firewall/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/index.md b/docs/configuration/highavailability/index.md deleted file mode 100644 index e26f5791..00000000 --- a/docs/configuration/highavailability/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/highavailability/md-index.md b/docs/configuration/highavailability/md-index.md new file mode 100644 index 00000000..e26f5791 --- /dev/null +++ b/docs/configuration/highavailability/md-index.md @@ -0,0 +1,561 @@ +--- +lastproofread: '2021-06-30' +--- + +(high-availability)= + +# High availability + +VRRP (Virtual Router Redundancy Protocol) provides active/backup redundancy for +routers. Every VRRP router has a physical IP/IPv6 address, and a virtual +address. On startup, routers elect the master, and the router with the highest +priority becomes the master and assigns the virtual address to its interface. +All routers with lower priorities become backup routers. The master then starts +sending keepalive packets to notify other routers that it's available. If the +master fails and stops sending keepalive packets, the router with the next +highest priority becomes the new master and takes over the virtual address. + +VRRP keepalive packets use multicast, and VRRP setups are limited to a single +datalink layer segment. You can setup multiple VRRP groups +(also called virtual routers). Virtual routers are identified by a +VRID (Virtual Router IDentifier). If you setup multiple groups on the same +interface, their VRIDs must be unique if they use the same address family, +but it's possible (even if not recommended for readability reasons) to use +duplicate VRIDs on different interfaces. + +## Basic setup + +VRRP groups are created with the +`set high-availability vrrp group $GROUP_NAME` commands. The required +parameters are interface, vrid, and address. + +minimal config + +```none +set high-availability vrrp group Foo vrid 10 +set high-availability vrrp group Foo interface eth0 +set high-availability vrrp group Foo address 192.0.2.1/24 +``` + +You can verify your VRRP group status with the operational mode +`run show vrrp` command: + +```none +vyos@vyos# run show vrrp +Name Interface VRID State Last Transition +---------- ----------- ------ ------- ----------------- +Foo eth1 10 MASTER 2s +``` + +## IPv6 support + +The `address` parameter can be either an IPv4 or IPv6 address, but you can +not mix IPv4 and IPv6 in the same group, and will need to create groups with +different VRIDs specially for IPv4 and IPv6. +If you want to use IPv4 + IPv6 address you can use option `excluded-address` + +## Address + +The `address` can be configured either on the VRRP interface or on not VRRP +interface. + +```none +set high-availability vrrp group Foo address 192.0.2.1/24 +set high-availability vrrp group Foo address 203.0.113.22/24 interface eth2 +set high-availability vrrp group Foo address 198.51.100.33/24 interface eth3 +``` + +## Disabling a VRRP group + +You can disable a VRRP group with `disable` option: + +```none +set high-availability vrrp group Foo disable +``` + +A disabled group will be removed from the VRRP process and your router will not +participate in VRRP for that VRID. It will disappear from operational mode +commands output, rather than enter the backup state. + +## Exclude address + +Exclude IP addresses from `VRRP packets`. This option `excluded-address` is +used when you want to set IPv4 + IPv6 addresses on the same virtual interface +or when used more than 20 IP addresses. + +```none +set high-availability vrrp group Foo excluded-address '203.0.113.254/24' +set high-availability vrrp group Foo excluded-address '2001:db8:aa::1/64' +set high-availability vrrp group Foo excluded-address '2001:db8:22::1/64' +``` + +## Setting VRRP group priority + +VRRP priority can be set with `priority` option: + +```none +set high-availability vrrp group Foo priority 200 +``` + +The priority must be an integer number from 1 to 255. Higher priority value +increases router's precedence in the master elections. + +## Sync groups + +A sync group allows VRRP groups to transition together. + +```none +edit high-availability vrrp +set sync-group MAIN member VLAN9 +set sync-group MAIN member VLAN20 +``` + +In the following example, when VLAN9 transitions, VLAN20 will also transition: + +```none +vrrp { + group VLAN9 { + interface eth0.9 + address 10.9.1.1/24 + priority 200 + vrid 9 + } + group VLAN20 { + interface eth0.20 + priority 200 + address 10.20.20.1/24 + vrid 20 + } + sync-group MAIN { + member VLAN20 + member VLAN9 + } +} +``` + +:::{warning} +All items in a sync group should be similarly configured. +If one VRRP group is set to a different preemption delay or priority, +it would result in an endless transition loop. +::: + +## Preemption + +VRRP can use two modes: preemptive and non-preemptive. In the preemptive mode, +if a router with a higher priority fails and then comes back, routers with lower +priority will give up their master status. In non-preemptive mode, the newly +elected master will keep the master status and the virtual address indefinitely. + +By default VRRP uses preemption. You can disable it with the "no-preempt" +option: + +```none +set high-availability vrrp group Foo no-preempt +``` + +You can also configure the time interval for preemption with the "preempt-delay" +option. For example, to set the higher priority router to take over in 180 +seconds, use: + +```none +set high-availability vrrp group Foo preempt-delay 180 +``` + +## Track + +Track option to track non VRRP interface states. VRRP changes status to +`FAULT` if one of the track interfaces in state `down`. + +```none +set high-availability vrrp group Foo track interface eth0 +set high-availability vrrp group Foo track interface eth1 +``` + +Ignore VRRP main interface faults + +```none +set high-availability vrrp group Foo track exclude-vrrp-interface +``` + +## Unicast VRRP + +By default VRRP uses multicast packets. If your network does not support +multicast for whatever reason, you can make VRRP use unicast communication +instead. + +```none +set high-availability vrrp group Foo peer-address 192.0.2.10 +set high-availability vrrp group Foo hello-source-address 192.0.2.15 +``` + +## rfc3768-compatibility + +RFC 3768 defines a virtual MAC address to each VRRP virtual router. +This virtual router MAC address will be used as the source in all periodic VRRP +messages sent by the active node. When the rfc3768-compatibility option is set, +a new VRRP interface is created, to which the MAC address and the virtual IP +address is automatically assigned. + +```none +set high-availability vrrp group Foo rfc3768-compatibility +``` + +Verification + +```none +$show interfaces ethernet eth0v10 +eth0v10@eth0: 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/index.md b/docs/configuration/index.md deleted file mode 100644 index 3e215502..00000000 --- a/docs/configuration/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/interfaces/bonding.md b/docs/configuration/interfaces/bonding.md deleted file mode 100644 index 7a07a27c..00000000 --- a/docs/configuration/interfaces/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/bridge.md b/docs/configuration/interfaces/bridge.md deleted file mode 100644 index 77775767..00000000 --- a/docs/configuration/interfaces/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/dummy.md b/docs/configuration/interfaces/dummy.md deleted file mode 100644 index d2d27c5d..00000000 --- a/docs/configuration/interfaces/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/ethernet.md b/docs/configuration/interfaces/ethernet.md deleted file mode 100644 index eac0b443..00000000 --- a/docs/configuration/interfaces/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/geneve.md b/docs/configuration/interfaces/geneve.md deleted file mode 100644 index 1fce1119..00000000 --- a/docs/configuration/interfaces/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/index.md b/docs/configuration/interfaces/index.md deleted file mode 100644 index 9082cd80..00000000 --- a/docs/configuration/interfaces/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/l2tpv3.md b/docs/configuration/interfaces/l2tpv3.md deleted file mode 100644 index 324840fa..00000000 --- a/docs/configuration/interfaces/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/loopback.md b/docs/configuration/interfaces/loopback.md deleted file mode 100644 index 72f14c16..00000000 --- a/docs/configuration/interfaces/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/macsec.md b/docs/configuration/interfaces/macsec.md deleted file mode 100644 index b3c70362..00000000 --- a/docs/configuration/interfaces/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-bonding.md b/docs/configuration/interfaces/md-bonding.md new file mode 100644 index 00000000..7a07a27c --- /dev/null +++ b/docs/configuration/interfaces/md-bonding.md @@ -0,0 +1,764 @@ +--- +lastproofread: '2025-12-09' +--- + +(bond-interface)= + +# Bond / link aggregation + +A **bonding interface** aggregates multiple network interfaces into a single +logical interface (referred to as a bond, {abbr}`LAG (Link Aggregation Group)`, +EtherChannel, or port-channel). + +The behavior of a bonding interface depends on the selected mode. Modes provide +either fault tolerance or a combination of load balancing and fault tolerance. +Additionally, the bonding interface can be configured for link integrity +monitoring. + +## Configuration + +### Common interface configuration + +```{cmdincludemd} /_include/interface-common-with-dhcp.txt +:var0: bonding +:var1: bond0 +``` + +### Member interfaces + +```{cfgcmd} set interfaces bonding \ 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 new file mode 100644 index 00000000..77775767 --- /dev/null +++ b/docs/configuration/interfaces/md-bridge.md @@ -0,0 +1,431 @@ +--- +lastproofread: '2025-12-22' +--- + +(bridge-interface)= + +# Bridge + +VyOS bridges connect Ethernet segments by grouping multiple interfaces into a +single bridge interface, which acts as a virtual software switch. Unlike +routers, which forward traffic based on Layer 3 IP addresses, bridges operate +at Layer 2 and forward traffic based on MAC addresses. Operating at Layer 2, +bridges are protocol-agnostic and transparently forward all Ethernet- +encapsulated traffic, whether it is IPv4, IPv6, or specialized industrial +protocols. + +This implementation utilizes the Linux bridge subsystem to support a subset of +the ANSI/IEEE 802.1d standard for transparent bridging and MAC address learning. + +:::{note} +{abbr}`STP (Spanning Tree Protocol)` is disabled by default in VyOS +and must be explicitly enabled if required. See {ref}`stp` for details. +::: + +## Configuration + +### Common interface configuration + +```{cmdincludemd} /_include/interface-common-with-dhcp.txt +:var0: bridge +:var1: br0 +``` + + +### Member interfaces + +```{cfgcmd} set interfaces bridge \ 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 new file mode 100644 index 00000000..d2d27c5d --- /dev/null +++ b/docs/configuration/interfaces/md-dummy.md @@ -0,0 +1,87 @@ +--- +lastproofread: '2026-01-23' +--- + +(dummy-interface)= + +# Dummy + +A dummy interface is a virtual network interface that operates like the +loopback interface, accepting traffic and routing it back to the local host. +Unlike the loopback interface, which is limited to one per system and reserved +for internal system use, multiple dummy interfaces can be created, removed, and +managed without impacting core operations. + +As a software-based interface, the dummy interface does not depend on physical +link state and remains active as long as the operating system is running. + +Dummy interfaces are commonly used in environments with multiple redundant +uplinks (e.g., a server connected to two different switches), where assigning a +management IP address to a specific physical interface is risky. If that +interface fails, the management IP address becomes unreachable. + +Assigning the management IP address to a dummy interface and advertising it +over all available physical links ensures the address remains reachable as long +as at least one physical path is active. + +Dummy interfaces are also used for testing and simulation purposes. + +## Configuration + +### Common interface configuration + +```{cmdincludemd} /_include/interface-address.txt +:var0: dummy +:var1: dum0 +``` + +```{cmdincludemd} /_include/interface-description.txt +:var0: dummy +:var1: dum0 +``` + +```{cmdincludemd} /_include/interface-disable.txt +:var0: dummy +:var1: dum0 +``` + +```{cmdincludemd} /_include/interface-vrf.txt +:var0: dummy +:var1: dum0 +``` + + +## Operation + +```{opcmd} show interfaces dummy + +Show brief interface information. + +:::{code-block} none +vyos@vyos:~$ show interfaces dummy +Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down +Interface IP Address S/L Description +--------- ---------- --- ----------- +dum0 172.18.254.201/32 u/u +::: +``` + +```{opcmd} show interfaces dummy \ + +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 new file mode 100644 index 00000000..eac0b443 --- /dev/null +++ b/docs/configuration/interfaces/md-ethernet.md @@ -0,0 +1,515 @@ +--- +lastproofread: '2026-01-19' +--- + +(ethernet-interface)= + +# Ethernet + +Ethernet interfaces (e.g., `eth0`, `eth1`) represent the host's physical +or virtual network ports. + +They are the most common interface type, serving as the base layer upon which +IP addresses, VLANs, and tunnels are configured to carry traffic across both +LANs and WANs. + +## Configuration + +### Common interface configuration + +```{cmdincludemd} /_include/interface-common-with-dhcp.txt +:var0: ethernet +:var1: eth0 +``` + +```{cfgcmd} set interfaces ethernet \ 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 new file mode 100644 index 00000000..1fce1119 --- /dev/null +++ b/docs/configuration/interfaces/md-geneve.md @@ -0,0 +1,105 @@ +--- +lastproofread: '2026-02-02' +--- + +(geneve-interface)= + +# Geneve + +{abbr}`Geneve (Generic Network Virtualization Encapsulation)` interfaces +operate as virtual network ports. Administrators can apply standard network +configurations on them, such as IP addressing, bridging, or firewall rules, +just as they would on physical Ethernet ports. + +The Geneve protocol encapsulates Layer 2 Ethernet frames originating from +endpoints such as virtual machines, containers, or physical servers inside UDP +packets. It unifies the features of earlier encapsulation protocols, including +VXLAN, NVGRE, and STT, and addresses their limitations, such as fixed header +structures and a lack of metadata support. Because of its extensibility, Geneve +may eventually replace those older protocols. + +Geneve tunnels are used to connect virtual switches residing within +hypervisors, physical switches, middleboxes, and other network appliances. + +Geneve tunnels operate over any standard IP network. In larger deployments, +the underlying network (underlay) is often built using a **Clos** topology, +also known as a *leaf-and-spine* or *fat-tree* topology. + +Geneve header: + +```none ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +|Ver| Opt Len |O|C| Rsvd. | Protocol Type | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +| Virtual Network Identifier (VNI) | Reserved | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +| Variable Length Options | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +``` + + +## Configuration + +### Common interface configuration + +```{cmdincludemd} /_include/interface-address.txt +:var0: geneve +:var1: gnv0 +``` + +```{cmdincludemd} /_include/interface-description.txt +:var0: geneve +:var1: gnv0 +``` + +```{cmdincludemd} /_include/interface-disable.txt +:var0: geneve +:var1: gnv0 +``` + +```{cmdincludemd} /_include/interface-mac.txt +:var0: geneve +:var1: gnv0 +``` + +```{cmdincludemd} /_include/interface-mtu.txt +:var0: geneve +:var1: gnv0 +``` + +```{cmdincludemd} /_include/interface-ip.txt +:var0: geneve +:var1: gnv0 +``` + +```{cmdincludemd} /_include/interface-ipv6.txt +:var0: geneve +:var1: gnv0 +``` + + +### Geneve options + +```{cfgcmd} set interfaces geneve gnv0 remote \ + +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 new file mode 100644 index 00000000..9082cd80 --- /dev/null +++ b/docs/configuration/interfaces/md-index.md @@ -0,0 +1,26 @@ +# Interfaces + +```{toctree} +:includehidden: true +:maxdepth: 1 + +bonding +bridge +dummy +ethernet +geneve +l2tpv3 +loopback +macsec +openvpn +wireguard +pppoe +pseudo-ethernet +sstp-client +tunnel +virtual-ethernet +vti +vxlan +wireless +wwan +``` diff --git a/docs/configuration/interfaces/md-l2tpv3.md b/docs/configuration/interfaces/md-l2tpv3.md new file mode 100644 index 00000000..324840fa --- /dev/null +++ b/docs/configuration/interfaces/md-l2tpv3.md @@ -0,0 +1,170 @@ +--- +lastproofread: '2026-02-05' +--- + +(l2tpv3-interface)= + +# L2TPv3 + +{abbr}`L2TPv3 (Layer 2 Tunneling Protocol version 3)` interfaces let you +establish L2TPv3 tunnels to transport Layer 2 traffic over IP networks. + +The L2TPv3 protocol (defined in RFC 3931) wraps Layer 2 frames (e.g., Ethernet, +Frame Relay, HDLC) within IP packets, allowing them to traverse the underlying +IP infrastructure. + +Unlike L2TPv2, which strictly requires UDP encapsulation, the L2TPv3 protocol +is more flexible and supports two encapsulation types: + +> - **Direct IP:** Tunnel data is encapsulated directly inside IP packets +> (Protocol 115) for lower overhead. +> - **UDP:** Tunnel data is encapsulated inside a UDP datagram. This allows the +> tunnel to traverse NAT more easily. + +L2TPv3 tunnels connect geographically separated sites, serving as a simpler +alternative to {ref}`mpls` by operating over basic IP connectivity rather than +requiring a full MPLS infrastructure. + +L2TPv3 tunnels can be established over both IPv4 and IPv6 underlying networks. + +## Configuration + +### Common interface configuration + +```{cmdincludemd} /_include/interface-common-without-dhcp.txt +:var0: l2tpv3 +:var1: l2tpeth0 +``` + + +### L2TPv3 options + +Use the following commands to configure the L2TPv3 tunnel's specific parameters. + +```{cfgcmd} set interfaces l2tpv3 \ 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 new file mode 100644 index 00000000..72f14c16 --- /dev/null +++ b/docs/configuration/interfaces/md-loopback.md @@ -0,0 +1,67 @@ +--- +lastproofread: '2026-01-23' +--- + +(loopback-interface)= + +# Loopback + +The loopback interface is a virtual, software-based network interface. All +traffic sent to it loops back and only targets services on the local host. + +:::{note} +Only one loopback `lo` interface is allowed per operating system. +If you require multiple virtual interfaces, use the {ref}`dummy-interface` +interface type. +::: + +## Configuration + +### Common interface configuration + +```{cmdincludemd} /_include/interface-address.txt +:var0: loopback +:var1: lo +``` + +```{cmdincludemd} /_include/interface-description.txt +:var0: loopback +:var1: lo +``` + + +## Operation + +```{opcmd} show interfaces loopback + +Show brief interface information. + +:::{code-block} none +vyos@vyos:~$ show interfaces loopback +Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down +Interface IP Address S/L Description +--------- ---------- --- ----------- +lo 127.0.0.1/8 u/u + ::1/128 +::: +``` + +```{opcmd} show interfaces loopback lo + +Show detailed interface information. + +:::{code-block} none +vyos@vyos:~$ show interfaces loopback lo +lo: 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 new file mode 100644 index 00000000..b3c70362 --- /dev/null +++ b/docs/configuration/interfaces/md-macsec.md @@ -0,0 +1,319 @@ +--- +lastproofread: '2026-02-13' +--- + +(macsec-interface)= + +# MACsec + +MACsec is an IEEE standard (IEEE 802.1AE) for MAC security, introduced in +2006\. It enables protocol-independent connectivity between two hosts, providing +data confidentiality, authenticity, and integrity using GCM-AES ciphers. MACsec +operates at the Ethernet layer as a Layer 2 protocol and secures traffic within +Layer 2 networks, including DHCP and ARP requests. It does not compete with +other security solutions, such as IPsec (Layer 3) or TLS (Layer 4), as each +addresses distinct use cases. + +## Configuration + +### Common interface configuration + +```{cmdincludemd} /_include/interface-common-with-dhcp.txt +:var0: macsec +:var1: macsec0 +``` + + +### MACsec options + +```{cfgcmd} set interfaces macsec \ 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 new file mode 100644 index 00000000..817e6868 --- /dev/null +++ b/docs/configuration/interfaces/md-openvpn-examples.md @@ -0,0 +1,769 @@ +# Site-to-site + +:::{todo} +Convert raw command blocks in this file to cfgcmd/opcmd directives for command coverage tracking. +::: + +OpenVPN is popular for client-server setups, but its site-to-site mode is less common and often not supported by router appliances. Despite limited support, it is effective for quickly establishing tunnels between routers. + +As of VyOS 1.4, OpenVPN site-to-site mode can use either pre-shared keys or x.509 certificates. + +Pre-shared key mode is now deprecated and will be removed from future OpenVPN versions. VyOS will also discontinue support for this option because pre-shared keys are significantly less secure than TLS. + +We will configure OpenVPN with self-signed certificates, and then discuss the legacy pre-shared key mode. + +In both cases, we will use the following settings: + +- The public IP address of the local VPN endpoint is 198.51.100.10. +- The public IP address of the remote VPN endpoint is 203.0.113.11. +- The tunnel uses 10.255.1.1 for the local IP address and 10.255.1.2 for the remote IP address. +- The local site has a subnet of 10.0.0.0/16. +- The remote site has a subnet of 10.1.0.0/16. +- The official OpenVPN port 1194 is reserved for client VPN. For site-to-site VPN, port 1195 is used. +- The `persistent-tunnel` directive allows us to configure tunnel-related attributes, such as firewall policy, as we would on any standard network interface. +- If known, the remote router\'s IP address can be configured using the `remote-host` directive. If unknown, it can be omitted. We assume the remote router has a dynamic IP address. + +![](/_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 new file mode 100644 index 00000000..170c585d --- /dev/null +++ b/docs/configuration/interfaces/md-openvpn.md @@ -0,0 +1,614 @@ +(openvpn)= + +# OpenVPN + +Traditionally, hardware routers use IPsec exclusively because it is easy to +implement in hardware, and their CPUs lack sufficient power for software-based +encryption. This limitation is less relevant for VyOS, as it is a software +router. + +OpenVPN has been widely used on UNIX platforms for a long time and is a popular +choice for remote-access VPNs. It also supports site-to-site connections. + +OpenVPN offers the following advantages: + +- It uses a single TCP or UDP connection and does not rely on packet source + addresses, so it works even through double NAT. This makes it well-suited for + public hotspots. +- It is easy to set up and offers very flexible split tunneling. +- A variety of client GUI frontends are available for any platform. + +Disadvantages include: + +- It is slower than IPsec due to higher protocol overhead and because it runs + in user mode, while IPsec on Linux runs in kernel mode. +- No operating system includes OpenVPN client software by default. + +In the VyOS CLI, OpenVPN is configured as a network interface using `set +interfaces openvpn` rather than `set vpn`, which is often overlooked. + +## Configuration + +```{cfgcmd} set interfaces openvpn \ 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 new file mode 100644 index 00000000..b79f41a2 --- /dev/null +++ b/docs/configuration/interfaces/md-pppoe.md @@ -0,0 +1,419 @@ +--- +lastproofread: '2026-03-03' +--- + +(pppoe-interface)= + +# PPPoE + +{abbr}`PPPoE (Point-to-Point Protocol over Ethernet)` is a network protocol +that encapsulates PPP frames within Ethernet frames. +It's often used for connecting ISP clients to a broadband access server. + +## Configuration + +### Common interface configuration + +```{cmdincludemd} /_include/interface-description.txt +:var0: pppoe +:var1: pppoe0 +``` + +```{cmdincludemd} /_include/interface-disable.txt +:var0: pppoe +:var1: pppoe0 +``` + +```{cmdincludemd} /_include/interface-mtu.txt +:var0: pppoe +:var1: pppoe0 +``` + +```{cmdincludemd} /_include/interface-vrf.txt +:var0: pppoe +:var1: pppoe0 +``` + + +### PPPoE options + +```{cfgcmd} set interfaces pppoe \ 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 new file mode 100644 index 00000000..fc8833eb --- /dev/null +++ b/docs/configuration/interfaces/md-pseudo-ethernet.md @@ -0,0 +1,52 @@ +--- +lastproofread: '2026-03-05' +--- + +(pseudo-ethernet-interface)= + +# MACVLAN (pseudo-Ethernet) + +MACVLAN, or pseudo-Ethernet interfaces, operate as logical subinterfaces of +standard Ethernet interfaces. Each subinterface has a unique MAC address but +shares a single physical Ethernet port. +That allows the user to send packets from different source IPv4 or IPv6 addresses +using a different MAC address. + +Pseudo-Ethernet interfaces behave like physical Ethernet interfaces. They +support IPv4 and IPv6 addressing, can obtain IP addresses through DHCP or +DHCPv6, and are mapped to a physical Ethernet port. They inherit +characteristics such as speed and duplex from their parent interface and can +be referenced like standard Ethernet interfaces once created. + +```{eval-rst} +Pseudo-Ethernet interfaces may not work in environments that require a + :abbr:`NIC (Network Interface Card)` to have only one MAC address. + This includes: + + * VMware machines with default settings. + * Network switches that permit only a single MAC address. + * xDSL modems that learn the NIC's MAC address. +``` + +## Configuration + +### Common interface configuration + +```{cmdincludemd} /_include/interface-common-with-dhcp.txt +:var0: pseudo-ethernet +:var1: peth0 +``` + +### MACVLAN (pseudo-Ethernet) options + +```{cfgcmd} set interfaces pseudo-ethernet \ 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 new file mode 100644 index 00000000..da98aecd --- /dev/null +++ b/docs/configuration/interfaces/md-sstp-client.md @@ -0,0 +1,170 @@ +--- +lastproofread: '2026-03-16' +--- + +(sstp-client-interface)= + +# SSTP client + +{abbr}`SSTP (Secure Socket Tunneling Protocol)` transports PPP traffic over an +SSL/TLS channel, providing transport-level security through key negotiation, +encryption, and traffic integrity checking. The use of SSL/TLS over TCP port +443 (by default, the port can be changed) allows SSTP to pass through virtually +all firewalls and proxy servers, except for authenticated web proxies. + +:::{note} +VyOS includes a built-in SSTP server. For more information, see +{ref}`sstp`. +::: + +## Configuration + +### Common interface configuration + +```{cmdincludemd} /_include/interface-description.txt +:var0: sstpc +:var1: sstpc0 +``` + +```{cmdincludemd} /_include/interface-disable.txt +:var0: sstpc +:var1: sstpc0 +``` + +```{cmdincludemd} /_include/interface-mtu.txt +:var0: sstpc +:var1: sstpc0 +``` + +```{cmdincludemd} /_include/interface-vrf.txt +:var0: sstpc +:var1: sstpc0 +``` + + +### SSTP client options + +```{cfgcmd} set interfaces sstpc \ 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 new file mode 100644 index 00000000..9c9885d2 --- /dev/null +++ b/docs/configuration/interfaces/md-tunnel.md @@ -0,0 +1,309 @@ +--- +lastproofread: '2026-01-23' +--- + +(tunnel-interface)= + +# Tunnel + +Tunnel interfaces are virtual links that transmit encapsulated traffic between +private networks or hosts across public infrastructure, such as the Internet. +They operate using encapsulation protocols to wrap original traffic for +transport. The supported protocols include {abbr}`GRE (Generic Routing +Encapsulation)`, IPIP, IPIP6, IP6IP6, and 6in4 (SIT). + +While {abbr}`GRE (Generic Routing Encapsulation)` is often the preferred +one-size-fits-all solution due to its versatility, other encapsulation +protocols may be better suited for specific use cases. + +VyOS uses a single tunnel interface type for all of these protocols. There are +no separate {abbr}`GRE (Generic Routing Encapsulation)`, IPIP, or IP6IP6 +interface types; instead, the desired encapsulation protocol is selected within +the `set interfaces tunnel` configuration. + +Configuration options for each protocol are described below. + +:::{warning} +Do not change the encapsulation type for already configured tunnel +interfaces, as this may break their dependent configurations. +::: + +## Common interface configuration + +```{cmdincludemd} /_include/interface-address.txt +:var0: tunnel +:var1: tun0 +``` + +```{cmdincludemd} /_include/interface-common-without-mac.txt +:var0: tunnel +:var1: tun0 +``` + + +## IPIP + +IPIP is a straightforward encapsulation protocol defined in RFC 2003. It +encapsulates one IPv4 packet inside another IPv4 packet. + +Tunnels with IPIP encapsulation do not have protocol-specific configuration +options except for explicitly defining the encapsulation type as IPIP (see +the example below). + +Example: + +```none +set interfaces tunnel tun0 encapsulation ipip +set interfaces tunnel tun0 source-address 192.0.2.10 +set interfaces tunnel tun0 remote 203.0.113.20 +set interfaces tunnel tun0 address 192.168.100.200/24 +``` + + +## IP6IP6 + +IP6IP6 is the IPv6 counterpart to IPIP. It encapsulates one IPv6 packet inside +another IPv6 packet. + +Similar to their IPIP counterparts, tunnels with IP6IP6 encapsulation do not +have protocol-specific configuration options except for explicitly defining +the encapsulation type as IP6IP6. + +Example: + +```none +set interfaces tunnel tun0 encapsulation ip6ip6 +set interfaces tunnel tun0 source-address 2001:db8:aa::1 +set interfaces tunnel tun0 remote 2001:db8:aa::2 +set interfaces tunnel tun0 address 2001:db8:bb::1/64 +``` + + +## IPIP6 + +IPIP6 is an encapsulation protocol that wraps IPv4 packets inside IPv6 packets. + +Similar to IPIP and IP6IP6, protocol-specific configuration for tunnels with +IPIP6 encapsulation only requires defining the encapsulation type as IP6IP6. + +Example: + +```none +set interfaces tunnel tun0 encapsulation ipip6 +set interfaces tunnel tun0 source-address 2001:db8:aa::1 +set interfaces tunnel tun0 remote 2001:db8:aa::2 +set interfaces tunnel tun0 address 192.168.70.80/24 +``` + + +## 6in4 (SIT) + +6in4, also known as {abbr}`SIT (Simple Internet Transition)`, is an +encapsulation protocol defined in {rfc}`4213` that wraps IPv6 packets +inside IPv4 packets. The encapsulating IPv4 headers use IP protocol number 41, +which is reserved exclusively for IPv6 encapsulation. + +The encapsulation process adds a 20-byte IPv4 header to each IPv6 packet. +Consequently, 6in4 tunnel interfaces can transmit IPv6 packets up to 1480 bytes +over an underlying network with a standard MTU of 1500 bytes without +fragmentation. + +6in4 tunnel interfaces are frequently used by IPv6 tunnel brokers (such as +[Hurricane Electric]) to connect isolated IPv6 networks or individual hosts to +the IPv6 internet. + +Example: + +```none +set interfaces tunnel tun0 encapsulation sit +set interfaces tunnel tun0 source-address 192.0.2.10 +set interfaces tunnel tun0 remote 192.0.2.20 +set interfaces tunnel tun0 address 2001:db8:bb::1/64 +``` + +:::{seealso} +For a practical configuration example, see the +{ref}`Tunnelbroker.net (IPv6) ` 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 new file mode 100644 index 00000000..dee1b332 --- /dev/null +++ b/docs/configuration/interfaces/md-virtual-ethernet.md @@ -0,0 +1,119 @@ +--- +lastproofread: '2026-01-26' +--- + +(virtual-ethernet)= + +# Virtual Ethernet + +Virtual Ethernet (veth) interfaces are software-based interfaces that operate +in pairs, creating a tunnel between each other. Traffic transmitted into one +interface of the pair (e.g., `veth0`) is delivered directly to its peer +interface (e.g., `veth1`). + +Veth interfaces are commonly used to connect network namespaces or VRFs, but +they can also function as standalone virtual network interfaces. + +:::{note} +Veth interfaces must be created in pairs, where each interface acts +as the peer of the other. +::: + +## Configuration + +### Common interface configuration + +```{cmdincludemd} /_include/interface-address-with-dhcp.txt +:var0: virtual-ethernet +:var1: veth0 +``` + +```{cmdincludemd} /_include/interface-description.txt +:var0: virtual-ethernet +:var1: veth0 +``` + + +### VLAN + +#### Regular VLANs (802.1q) + +```{cmdincludemd} /_include/interface-vlan-8021q.txt +:var0: virtual-ethernet +:var1: veth0 +``` + + +#### 802.1ad (QinQ) + +```{cmdincludemd} /_include/interface-vlan-8021ad.txt +:var0: virtual-ethernet +:var1: veth0 +``` + +```{cmdincludemd} /_include/interface-disable.txt +:var0: virtual-ethernet +:var1: veth0 +``` + +```{cmdincludemd} /_include/interface-vrf.txt +:var0: virtual-ethernet +:var1: veth0 +``` + + +## Operation + +```{opcmd} show interfaces virtual-ethernet + +Show brief interface information. + +:::{code-block} none +vyos@vyos:~$ show interfaces virtual-ethernet +Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down +Interface IP Address S/L Description +--------- ---------- --- ----------- +veth10 100.64.0.0/31 u/u +veth11 100.64.0.1/31 u/u +::: +``` + +```{opcmd} show interfaces virtual-ethernet \ + +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 new file mode 100644 index 00000000..dbd2c88c --- /dev/null +++ b/docs/configuration/interfaces/md-vti.md @@ -0,0 +1,121 @@ +(vti-interface)= + +# VTI (virtual tunnel interface) + +{abbr}`VTIs (virtual tunnel interfaces)` let you create secure, encrypted +tunnels between private networks or hosts across public infrastructure, such as +the Internet. They operate alongside an underlying IPsec tunnel, which handles +encapsulation and encryption, while VTIs function exclusively as routing +interfaces. + +## Configuration + +### Common interface configuration + +```{cmdincludemd} /_include/interface-address.txt +:var0: vti +:var1: vti0 +``` + +```{cmdincludemd} /_include/interface-description.txt +:var0: vti +:var1: vti0 +``` + +```{cmdincludemd} /_include/interface-disable.txt +:var0: vti +:var1: vti0 +``` + +```{cmdincludemd} /_include/interface-ip.txt +:var0: vti +:var1: vti0 +``` + +```{cmdincludemd} /_include/interface-ipv6.txt +:var0: vti +:var1: vti0 +``` + +```{cmdincludemd} /_include/interface-mtu.txt +:var0: vti +:var1: vti0 +``` + +```{cfgcmd} set interfaces vti \ 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 new file mode 100644 index 00000000..8dae75ff --- /dev/null +++ b/docs/configuration/interfaces/md-vxlan.md @@ -0,0 +1,373 @@ +--- +lastproofread: '2026-03-16' +--- + +(vxlan-interface)= + +# VXLAN + +{abbr}`VXLAN (Virtual Extensible LAN)` is a network virtualization technology +that addresses scalability challenges in large cloud computing environments. +It encapsulates Ethernet frames (Layer 2) within UDP datagrams (Layer 4), which +are then transmitted via UDP port 4789, as assigned by IANA. VXLAN endpoints, +called {abbr}`VTEPs (VXLAN tunnel endpoints)`, terminate VXLAN tunnels and can +be either virtual or physical switch ports. + +VXLAN supports up to 16 million logical networks and enables Layer 2 adjacency +across Layer 3 IP networks. It uses multicast or unicast with head-end +replication (HER) to flood broadcast, unknown unicast, and multicast (BUM) +traffic. + +The VXLAN specification was initially developed by VMware, Arista Networks, and +Cisco. Other supporters include Huawei, Broadcom, Citrix, Pica8, Big Switch +Networks, Cumulus Networks, Dell EMC, Ericsson, Mellanox, FreeBSD, OpenBSD, Red +Hat, Joyent, and Juniper Networks. + +VXLAN is officially documented by the IETF in {rfc}`7348`. + +When configuring VXLAN in a VyOS virtual machine, ensure that MAC spoofing +(Hyper-V) or Forged Transmits (ESX) are permitted. Otherwise, the hypervisor +may block forwarded frames. + +:::{note} +Although the IANA-assigned VXLAN port is **4789**, VyOS uses the +Linux default UDP port **8472** for VXLAN interfaces. To ensure compatibility +with other vendors, set the port to the IANA standard **4789**. +::: + +## Configuration + +### Common interface configuration + +```{cmdincludemd} /_include/interface-common-without-dhcp.txt +:var0: vxlan +:var1: vxlan0 +``` + + +### VXLAN-specific options + +```{cfgcmd} set interfaces vxlan \ 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 new file mode 100644 index 00000000..121d1df0 --- /dev/null +++ b/docs/configuration/interfaces/md-wireguard.md @@ -0,0 +1,434 @@ +--- +lastproofread: '2026-03-02' +--- + +(wireguard)= + +# WireGuard + +WireGuard is an extremely simple, fast, and modern VPN that utilizes +state-of-the-art cryptography. See 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 new file mode 100644 index 00000000..9e6b7c99 --- /dev/null +++ b/docs/configuration/interfaces/md-wireless.md @@ -0,0 +1,923 @@ +--- +lastproofread: '2026-03-23' +--- + +(wireless-interface)= + +# Wireless LAN / Wi-Fi + +{abbr}`WLAN (Wireless LAN)` interfaces provide 802.11 (a/b/g/n/ac) wireless +connectivity, referred to as Wi-Fi, and operate in one of the following +modes: + +- {abbr}`WAP (Wireless Access-Point)` mode provides network access to connecting + stations if the physical hardware supports acting as a WAP +- Station mode acts as a Wi-Fi client accessing the network through an available + WAP +- Monitor mode lets the system passively monitor wireless traffic + +If the system detects an unconfigured wireless device, it will be automatically +added to the configuration tree, specifying any detected settings (for example, +its MAC address) and configured to run in monitor mode. + +## Configuration + +### Common interface configuration + +```{cmdincludemd} /_include/interface-common-with-dhcp.txt +:var0: wireless +:var1: wlan0 +``` + + +### System-wide configuration + +```{cfgcmd} set system wireless country-code \ + +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 new file mode 100644 index 00000000..e8121f28 --- /dev/null +++ b/docs/configuration/interfaces/md-wwan.md @@ -0,0 +1,355 @@ +--- +lastproofread: '2026-03-30' +--- + +(wwan-interface)= + +# WWAN + +{abbr}`WWAN (Wireless Wide Area Network)` interfaces provide access to cellular +networks via a cellular modem or card. + +Configure these interfaces under the `interfaces wwan` node. + +## Configuration + +### Common interface configuration + +```{cmdincludemd} /_include/interface-address-with-dhcp.txt +:var0: wwan +:var1: wwan0 +``` + +```{cmdincludemd} /_include/interface-description.txt +:var0: wwan +:var1: wwan0 +``` + +```{cmdincludemd} /_include/interface-disable.txt +:var0: wwan +:var1: wwan0 +``` + +```{cmdincludemd} /_include/interface-disable-link-detect.txt +:var0: wwan +:var1: wwan0 +``` + +```{cmdincludemd} /_include/interface-mtu.txt +:var0: wwan +:var1: wwan0 +``` + +```{cmdincludemd} /_include/interface-ip.txt +:var0: wwan +:var1: wwan0 +``` + +```{cmdincludemd} /_include/interface-ipv6.txt +:var0: wwan +:var1: wwan0 +``` + +```{cmdincludemd} /_include/interface-vrf.txt +:var0: wwan +:var1: wwan0 +``` + +**DHCP(v6)** + +```{cmdincludemd} /_include/interface-dhcp-options.txt +:var0: wwan +:var1: wwan0 +``` + +```{cmdincludemd} /_include/interface-dhcpv6-options.txt +:var0: wwan +:var1: wwan0 +``` + +```{cmdincludemd} /_include/interface-dhcpv6-prefix-delegation.txt +:var0: wwan +:var1: wwan0 +``` + + +### WWAN options + +```{cfgcmd} set interfaces wwan \ 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/interfaces/openvpn-examples.md b/docs/configuration/interfaces/openvpn-examples.md deleted file mode 100644 index 817e6868..00000000 --- a/docs/configuration/interfaces/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/openvpn.md b/docs/configuration/interfaces/openvpn.md deleted file mode 100644 index 170c585d..00000000 --- a/docs/configuration/interfaces/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/pppoe.md b/docs/configuration/interfaces/pppoe.md deleted file mode 100644 index b79f41a2..00000000 --- a/docs/configuration/interfaces/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/pseudo-ethernet.md b/docs/configuration/interfaces/pseudo-ethernet.md deleted file mode 100644 index fc8833eb..00000000 --- a/docs/configuration/interfaces/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/sstp-client.md b/docs/configuration/interfaces/sstp-client.md deleted file mode 100644 index da98aecd..00000000 --- a/docs/configuration/interfaces/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/tunnel.md b/docs/configuration/interfaces/tunnel.md deleted file mode 100644 index 9c9885d2..00000000 --- a/docs/configuration/interfaces/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/virtual-ethernet.md b/docs/configuration/interfaces/virtual-ethernet.md deleted file mode 100644 index dee1b332..00000000 --- a/docs/configuration/interfaces/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/vti.md b/docs/configuration/interfaces/vti.md deleted file mode 100644 index dbd2c88c..00000000 --- a/docs/configuration/interfaces/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/vxlan.md b/docs/configuration/interfaces/vxlan.md deleted file mode 100644 index 8dae75ff..00000000 --- a/docs/configuration/interfaces/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/wireguard.md b/docs/configuration/interfaces/wireguard.md deleted file mode 100644 index 121d1df0..00000000 --- a/docs/configuration/interfaces/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/wireless.md b/docs/configuration/interfaces/wireless.md deleted file mode 100644 index 9e6b7c99..00000000 --- a/docs/configuration/interfaces/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/wwan.md b/docs/configuration/interfaces/wwan.md deleted file mode 100644 index e8121f28..00000000 --- a/docs/configuration/interfaces/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/haproxy.md b/docs/configuration/loadbalancing/haproxy.md deleted file mode 100644 index d60c5248..00000000 --- a/docs/configuration/loadbalancing/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/index.md b/docs/configuration/loadbalancing/index.md deleted file mode 100644 index 3241edb7..00000000 --- a/docs/configuration/loadbalancing/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-haproxy.md b/docs/configuration/loadbalancing/md-haproxy.md new file mode 100644 index 00000000..d60c5248 --- /dev/null +++ b/docs/configuration/loadbalancing/md-haproxy.md @@ -0,0 +1,510 @@ +--- +lastproofread: '2026-04-06' +--- + +# HAproxy + +```{include} /_include/need_improvement.txt +``` + +HAProxy is a load balancer and proxy server that provides +high-availability, load balancing, and proxying for TCP (level 4) and +HTTP-based (level 7) applications. + +## Configuration + +Service configuration specifies the port to bind to. Backend +configuration defines the load balancing method and specifies the backend +servers. + +### Service + +```{cfgcmd} set load-balancing haproxy service \ 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 new file mode 100644 index 00000000..3241edb7 --- /dev/null +++ b/docs/configuration/loadbalancing/md-index.md @@ -0,0 +1,15 @@ +--- +lastproofread: '2026-04-06' +--- + +(load-balancing)= + +# Load-balancing + +```{toctree} +:includehidden: true +:maxdepth: 1 + +wan +haproxy +``` diff --git a/docs/configuration/loadbalancing/md-wan.md b/docs/configuration/loadbalancing/md-wan.md new file mode 100644 index 00000000..a19bbfae --- /dev/null +++ b/docs/configuration/loadbalancing/md-wan.md @@ -0,0 +1,306 @@ +--- +lastproofread: '2026-04-06' +--- + +# WAN load balancing + +```{todo} +Convert raw command blocks in this file to cfgcmd/opcmd +directives for command coverage tracking. +``` + +The load balancer distributes outbound traffic across two or more +interfaces. If a path fails, the load balancer balances traffic across the +remaining healthy paths. When a path recovers, it is automatically added back +to the routing table. The load balancer adds routes for each path and +distributes traffic based on interface health and weight. + +In a minimal configuration, the following must be provided: +> - An interface with a `nexthop`. +> - One rule with a LAN (inbound-interface) and the WAN (interface). + +The following examples uses two DHCP WAN interfaces and one LAN (`eth2`): + +```none +set load-balancing wan interface-health eth0 nexthop 'dhcp' +set load-balancing wan interface-health eth1 nexthop 'dhcp' +set load-balancing wan rule 1 inbound-interface 'eth2' +set load-balancing wan rule 1 interface eth0 +set load-balancing wan rule 1 interface eth1 +``` + +:::{note} +Do not use WAN load balancing with dynamic routing protocols. This +feature creates customized routing tables and firewall rules that are +incompatible with routing protocols. +::: + +## Load balancing rules + +You define interfaces, their weight, and the traffic type to balance in +numbered rule sets. The load balancer executes rules in numerical order +against outgoing packets. When a packet matches a rule, it is sent through the +specified interface. Packets that do not match any rule use the system routing +table. You cannot change rule numbers. + +Create a load balancing rule, it can be a number between 1 and 9999: + +```none +vyos@vyos# set load-balancing wan rule 1 +Possible completions: +description Description for this rule +> destination Destination +exclude Exclude packets matching this rule from wan load balance +failover Enable failover for packets matching this rule from wan load balance +inbound-interface Inbound interface name (e.g., "eth0") [REQUIRED] ++> interface Interface name [REQUIRED] +> limit Enable packet limit for this rule +per-packet-balancing Option to match traffic per-packet instead of the default, per-flow +protocol Protocol to match +> source Source information +``` + + +### Interface weight + +By default, the load balancer distributes outbound +traffic randomly across available interfaces. You can assign weights to +interfaces to influence the distribution. If `eth0` has more bandwidth +than `eth1`, you can assign a higher weight to `eth0` to send more +traffic through it: + +```none +set load-balancing wan rule 1 interface eth0 weight 2 +set load-balancing wan rule 1 interface eth1 weight 1 +``` + +In this example,\`\`eth0\`\` receives 66% of traffic, and `eth1` receives +33% of traffic. + +### Rate limit + +Set a packet rate limit for a rule to apply it to traffic above or below a +specified threshold. To configure rate limiting, use: + +```none +set load-balancing wan rule 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/loadbalancing/wan.md b/docs/configuration/loadbalancing/wan.md deleted file mode 100644 index a19bbfae..00000000 --- a/docs/configuration/loadbalancing/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 new file mode 100644 index 00000000..3e215502 --- /dev/null +++ b/docs/configuration/md-index.md @@ -0,0 +1,23 @@ +# Configuration Guide + +The following structure represents the CLI structure. + +```{toctree} +:includehidden: true +:maxdepth: 1 + +container/index +firewall/index +highavailability/index +interfaces/index +loadbalancing/index +nat/index +policy/index +pki/index +protocols/index +service/index +system/index +trafficpolicy/index +vpn/index +vrf/index +``` diff --git a/docs/configuration/nat/cgnat.md b/docs/configuration/nat/cgnat.md deleted file mode 100644 index 914a466b..00000000 --- a/docs/configuration/nat/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/index.md b/docs/configuration/nat/index.md deleted file mode 100644 index 35e5d32b..00000000 --- a/docs/configuration/nat/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-cgnat.md b/docs/configuration/nat/md-cgnat.md new file mode 100644 index 00000000..914a466b --- /dev/null +++ b/docs/configuration/nat/md-cgnat.md @@ -0,0 +1,200 @@ +(cgnat)= + +# CGNAT + +{abbr}`CGNAT (Carrier-Grade Network Address Translation)` , also known as +Large-Scale NAT (LSN), is a type of network address translation used by +Internet Service Providers (ISPs) to enable multiple private IP addresses to +share a single public IP address. This technique helps to conserve the limited +IPv4 address space. +The 100.64.0.0/10 address block is reserved for use in carrier-grade NAT + +## Overview + +CGNAT works by placing a NAT device within the ISP's network. This device +translates private IP addresses from customer networks to a limited pool of +public IP addresses assigned to the ISP. This allows many customers to share a +smaller number of public IP addresses. + +Not all {rfc}`6888` requirements are implemented in CGNAT. + +Implemented the following {rfc}`6888` requirements: + +- REQ 2: A CGN must have a default "IP address pooling" behavior of "Paired". + CGN must use the same external IP address mapping for all sessions associated + with the same internal IP address, be they TCP, UDP, ICMP, something else, + or a mix of different protocols. +- REQ 3: The CGN function should not have any limitations on the size or the + contiguity of the external address pool. +- REQ 4: A CGN must support limiting the number of external ports (or, + equivalently, "identifiers" for ICMP) that are assigned per subscriber + +### Advantages of CGNAT + +- **IPv4 Address Conservation**: CGNAT helps mitigate the exhaustion of IPv4 addresses by allowing multiple customers to share a single public IP address. +- **Scalability**: ISPs can support more customers without needing a proportional increase in public IP addresses. +- **Cost-Effective**: Reduces the cost associated with acquiring additional public IPv4 addresses. + +### Considerations + +- **Traceability Issues**: Since multiple users share the same public IP address, tracking individual users for security and legal purposes can be challenging. +- **Performance Overheads**: The translation process can introduce latency and potential performance bottlenecks, especially under high load. +- **Application Compatibility**: Some applications and protocols may not work well with CGNAT due to their reliance on unique public IP addresses. +- **Port Allocation Limits**: Each public IP address has a limited number of ports, which can be exhausted, affecting the ability to establish new connections. +- **Port Control Protocol**: PCP is not implemented. + +## Port calculation + +When implementing CGNAT, ensuring that there are enough ports allocated per subscriber is critical. Below is a summary based on RFC 6888. + +1. **Total Ports Available**: + + - Total Ports: 65536 (0 to 65535) + - Reserved Ports: Assume 1024 ports are reserved for well-known services and administrative purposes. + - Usable Ports: 65536 - 1024 = 64512 + +2. **Estimate Ports Needed per Subscriber**: + + - Example: A household might need 1000 ports to ensure smooth operation for multiple devices and applications. + +3. **Calculate the Number of Subscribers per Public IP**: + + - Usable Ports / Ports per Subscriber + - 64512 / 1000 ≈ 64 subscribers per public IP + +## Configuration + +```{cfgcmd} set nat cgnat pool external \ 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 new file mode 100644 index 00000000..35e5d32b --- /dev/null +++ b/docs/configuration/nat/md-index.md @@ -0,0 +1,13 @@ +(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 new file mode 100644 index 00000000..4f5bd580 --- /dev/null +++ b/docs/configuration/nat/md-nat44.md @@ -0,0 +1,788 @@ +(nat44)= + +# NAT44 + +{abbr}`NAT (Network Address Translation)` is a common method of +remapping one IP address space into another by modifying network address +information in the IP header of packets while they are in transit across +a traffic routing device. The technique was originally used as a +shortcut to avoid the need to readdress every host when a network was +moved. It has become a popular and essential tool in conserving global +address space in the face of IPv4 address exhaustion. One +Internet-routable IP address of a NAT gateway can be used for an entire +private network. + +IP masquerading is a technique that hides an entire IP address space, +usually consisting of private IP addresses, behind a single IP address +in another, usually public address space. The hidden addresses are +changed into a single (public) IP address as the source address of the +outgoing IP packets so they appear as originating not from the hidden +host but from the routing device itself. Because of the popularity of +this technique to conserve IPv4 address space, the term NAT has become +virtually synonymous with IP masquerading. + +As network address translation modifies the IP address information in +packets, NAT implementations may vary in their specific behavior in +various addressing cases and their effect on network traffic. The +specifics of NAT behavior are not commonly documented by vendors of +equipment containing NAT implementations. + +The computers on an internal network can use any of the addresses set +aside by the {abbr}`IANA (Internet Assigned Numbers Authority)` for +private addressing (see {rfc}`1918`). These reserved IP addresses are +not in use on the Internet, so an external machine will not directly +route to them. The following addresses are reserved for private use: + +- 10.0.0.0 to 10.255.255.255 (CIDR: 10.0.0.0/8) +- 172.16.0.0 to 172.31.255.255 (CIDR: 172.16.0.0/12) +- 192.168.0.0 to 192.168.255.255 (CIDR: 192.168.0.0/16) + +If an ISP deploys a {abbr}`CGN (Carrier-grade NAT)`, and uses +{rfc}`1918` address space to number customer gateways, the risk of +address collision, and therefore routing failures, arises when the +customer network already uses an {rfc}`1918` address space. + +This prompted some ISPs to develop a policy within the {abbr}`ARIN +(American Registry for Internet Numbers)` to allocate new private +address space for CGNs, but ARIN deferred to the IETF before +implementing the policy indicating that the matter was not a typical +allocation issue but a reservation of addresses for technical purposes +(per {rfc}`2860`). + +IETF published {rfc}`6598`, detailing a shared address space for use in +ISP CGN deployments that can handle the same network prefixes occurring +both on inbound and outbound interfaces. ARIN returned address space to +the {abbr}`IANA (Internet Assigned Numbers Authority)` for this +allocation. + +The allocated address block is 100.64.0.0/10. + +Devices evaluating whether an IPv4 address is public must be updated to +recognize the new address space. Allocating more private IPv4 address +space for NAT devices might prolong the transition to IPv6. + +## Overview + +### Different NAT Types + +(source-nat)= + +#### SNAT + +{abbr}`SNAT (Source Network Address Translation)` is the most common +form of {abbr}`NAT (Network Address Translation)` and is typically +referred to simply as NAT. To be more correct, what most people refer +to as {abbr}`NAT (Network Address Translation)` is actually the process +of {abbr}`PAT (Port Address Translation)`, or NAT overload. SNAT is +typically used by internal users/private hosts to access the Internet +\- the source address is translated and thus kept private. + +(destination-nat)= + +#### DNAT + +{abbr}`DNAT (Destination Network Address Translation)` changes the +destination address of packets passing through the router, while +{ref}`source-nat` changes the source address of packets. DNAT is +typically used when an external (public) host needs to initiate a +session with an internal (private) host. A customer needs to access a +private service behind the routers public IP. A connection is +established with the routers public IP address on a well known port and +thus all traffic for this port is rewritten to address the internal +(private) host. + +(bidirectional-nat)= + +#### Bidirectional NAT + +This is a common scenario where both {ref}`source-nat` and +{ref}`destination-nat` are configured at the same time. It's commonly +used when internal (private) hosts need to establish a connection with +external resources and external systems need to access internal +(private) resources. + +### NAT, Routing, Firewall Interaction + +There is a very nice picture/explanation in the Vyatta documentation +which should be rewritten here. + +### NAT Ruleset + +{abbr}`NAT (Network Address Translation)` is configured entirely on a +series of so called *rules*. Rules are numbered and evaluated by the +underlying OS in numerical order! The rule numbers can be changes by +utilizing the {cfgcmd}`rename` and {cfgcmd}`copy` commands. + +:::{note} +Changes to the NAT system only affect newly established +connections. Already established connections are not affected. +::: + +:::{hint} +When designing your NAT ruleset leave some space between +consecutive rules for later extension. Your ruleset could start with +numbers 10, 20, 30. You thus can later extend the ruleset and place +new rules between existing ones. +::: + +Rules will be created for both {ref}`source-nat` and +{ref}`destination-nat`. + +For {ref}`bidirectional-nat` a rule for both {ref}`source-nat` and +{ref}`destination-nat` needs to be created. + +(traffic-filters)= + +### Traffic Filters + +Traffic Filters are used to control which packets will have the defined +NAT rules applied. Five different filters can be applied within a NAT +rule. + +- **outbound-interface** - applicable only to {ref}`source-nat`. It + configures the interface which is used for the outside traffic that + this translation rule applies to. Interface groups, inverted + selection and wildcard, are also supported. + + Examples: + + ```none + set nat source rule 20 outbound-interface name eth0 + set nat source rule 30 outbound-interface name bond1* + set nat source rule 20 outbound-interface name !vtun2 + set nat source rule 20 outbound-interface group GROUP1 + set nat source rule 20 outbound-interface group !GROUP2 + ``` + +- **inbound-interface** - applicable only to {ref}`destination-nat`. It + configures the interface which is used for the inside traffic the + translation rule applies to. Interface groups, inverted + selection and wildcard, are also supported. + + Example: + + ```none + set nat destination rule 20 inbound-interface name eth0 + set nat destination rule 30 inbound-interface name bond1* + set nat destination rule 20 inbound-interface name !vtun2 + set nat destination rule 20 inbound-interface group GROUP1 + set nat destination rule 20 inbound-interface group !GROUP2 + ``` + +- **protocol** - specify which types of protocols this translation rule + applies to. Only packets matching the specified protocol are NATed. + By default this applies to *all* protocols. + + Example: + + - Set SNAT rule 20 to only NAT TCP and UDP packets + - Set DNAT rule 20 to only NAT UDP packets + + ```none + set nat source rule 20 protocol tcp_udp + set nat destination rule 20 protocol udp + ``` + +- **source** - specifies which packets the NAT translation rule applies + to based on the packets source IP address and/or source port. Only + matching packets are considered for NAT. + + Example: + + - Set SNAT rule 20 to only NAT packets arriving from the 192.0.2.0/24 + network + - Set SNAT rule 30 to only NAT packets arriving from the 203.0.113.0/24 + network with a source port of 80 and 443 + + ```none + set nat source rule 20 source address 192.0.2.0/24 + set nat source rule 30 source address 203.0.113.0/24 + set nat source rule 30 source port 80,443 + ``` + +- **destination** - specify which packets the translation will be + applied to, only based on the destination address and/or port number + configured. + + :::{note} + If no destination is specified the rule will match on any + destination address and port. + ::: + + Example: + + - Configure SNAT rule (40) to only NAT packets with a destination + address of 192.0.2.1. + + ```none + set nat source rule 40 destination address 192.0.2.1 + ``` + +### Address Conversion + +Every NAT rule has a translation command defined. The address defined +for the translation is the address used when the address information in +a packet is replaced. + +#### Source Address + +For {ref}`source-nat` rules the packets source address will be replaced +with the address specified in the translation command. A port +translation can also be specified and is part of the translation +address. + +:::{note} +The translation address must be set to one of the available +addresses on the configured *outbound-interface* or it must be set to +*masquerade* which will use the primary IP address of the +*outbound-interface* as its translation address. +::: + +:::{note} +When using NAT for a large number of host systems it +recommended that a minimum of 1 IP address is used to NAT every 256 +private host systems. This is due to the limit of 65,000 port numbers +available for unique translations and a reserving an average of +200-300 sessions per host system. +::: + +Example: + +- Define a discrete source IP address of 100.64.0.1 for SNAT rule 20 +- Use address *masquerade* (the interfaces primary address) on rule 30 +- For a large amount of private machines behind the NAT your address + pool might to be bigger. Use any address in the range 100.64.0.10 - + 100.64.0.20 on SNAT rule 40 when doing the translation + +```none +set nat source rule 20 translation address 100.64.0.1 +set nat source rule 30 translation address 'masquerade' +set nat source rule 40 translation address 100.64.0.10-100.64.0.20 +``` + +#### Destination Address + +For {ref}`destination-nat` rules the packets destination address will be +replaced by the specified address in the *translation address* command. + +Example: + +- DNAT rule 10 replaces the destination address of an inbound packet + with 192.0.2.10 + +```none +set nat destination rule 10 translation address 192.0.2.10 +``` + +Also, in {ref}`destination-nat`, redirection to localhost is supported. +The redirect statement is a special form of dnat which always translates +the destination address to the local host’s one. + +Example of redirection: + +```none +set nat destination rule 10 translation redirect port 22 +``` + +### NAT Load Balance + +Advanced configuration can be used in order to apply source or destination NAT, +and within a single rule, be able to define multiple translated addresses, +so NAT balances the translations among them. + +NAT Load Balance uses an algorithm that generates a hash and based on it, then +it applies corresponding translation. This hash can be generated randomly, or +can use data from the ip header: source-address, destination-address, +source-port and/or destination-port. By default, it will generate the hash +randomly. + +When defining the translated address, called `backends`, a `weight` must +be configured. This lets the user define load balance distribution according +to their needs. Them sum of all the weights defined for the backends should +be equal to 100. In oder words, the weight defined for the backend is the +percentage of the connections that will receive such backend. + +```{cfgcmd} set nat [source | destination] rule \ 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 new file mode 100644 index 00000000..c1b1c994 --- /dev/null +++ b/docs/configuration/nat/md-nat64.md @@ -0,0 +1,73 @@ +(nat64)= + +# NAT64 + +{abbr}`NAT64 (IPv6-to-IPv4 Prefix Translation)` is a critical component in +modern networking, facilitating communication between IPv6 and IPv4 networks. +This documentation outlines the setup, configuration, and usage of the NAT64 +feature in your project. Whether you are transitioning to IPv6 or need to +seamlessly connect IPv4 and IPv6 devices. +NAT64 is a stateful translation mechanism that translates IPv6 addresses to +IPv4 addresses and IPv4 addresses to IPv6 addresses. NAT64 is used to enable +IPv6-only clients to contact IPv4 servers using unicast UDP, TCP, or ICMP. + +## Overview + +### Different NAT Types + +(source-nat64)= + +#### SNAT64 + +{abbr}`SNAT64 (IPv6-to-IPv4 Source Address Translation)` is a stateful +translation mechanism that translates IPv6 addresses to IPv4 addresses. + +`64:ff9b::/96` is the well-known prefix for IPv4-embedded IPv6 addresses. +The prefix is used to represent IPv4 addresses in an IPv6 address format. +The IPv4 address is encoded in the low-order 32 bits of the IPv6 address. +The high-order 32 bits are set to the well-known prefix 64:ff9b::/96. + +## Configuration Examples + +The following examples show how to configure NAT64 on a VyOS router. +The 192.0.2.10 address is used as the IPv4 address for the translation pool. + +NAT64 server configuration: + +```none +set interfaces ethernet eth0 address '192.0.2.1/24' +set interfaces ethernet eth0 address '192.0.2.10/24' +set interfaces ethernet eth0 description 'WAN' +set interfaces ethernet eth1 address '2001:db8::1/64' +set interfaces ethernet eth1 description 'LAN' + +set service dns forwarding allow-from '2001:db8::/64' +set service dns forwarding dns64-prefix '64:ff9b::/96' +set service dns forwarding listen-address '2001:db8::1' + +set nat64 source rule 100 source prefix '64:ff9b::/96' +set nat64 source rule 100 translation pool 10 address '192.0.2.10' +set nat64 source rule 100 translation pool 10 port '1-65535' +``` + +NAT64 client configuration: + +```none +set interfaces ethernet eth1 address '2001:db8::2/64' +set protocols static route6 64:ff9b::/96 next-hop 2001:db8::1 +set system name-server '2001:db8::1' +``` + +Test from the IPv6 only client: + +```none +vyos@r1:~$ ping 64:ff9b::192.0.2.1 count 2 +PING 64:ff9b::192.0.2.1(64:ff9b::c000:201) 56 data bytes +64 bytes from 64:ff9b::c000:201: icmp_seq=1 ttl=63 time=0.351 ms +64 bytes from 64:ff9b::c000:201: icmp_seq=2 ttl=63 time=0.373 ms + +--- 64:ff9b::192.0.2.1 ping statistics --- +2 packets transmitted, 2 received, 0% packet loss, time 1023ms +rtt min/avg/max/mdev = 0.351/0.362/0.373/0.011 ms +``` + diff --git a/docs/configuration/nat/md-nat66.md b/docs/configuration/nat/md-nat66.md new file mode 100644 index 00000000..1cbe3317 --- /dev/null +++ b/docs/configuration/nat/md-nat66.md @@ -0,0 +1,243 @@ +(nat66)= + +# NAT66(NPTv6) + +```{todo} +Convert raw command blocks in this file to cfgcmd/opcmd +directives for command coverage tracking. +``` + +{abbr}`NPTv6 (IPv6-to-IPv6 Network Prefix Translation)` is an address +translation technology based on IPv6 networks, used to convert an IPv6 +address prefix in an IPv6 message into another IPv6 address prefix. +We call this address translation method NAT66. Devices that support the NAT66 +function are called NAT66 devices, which can provide NAT66 source +and destination address translation functions. + +## Overview + +### Different NAT Types + +(source-nat66)= + +#### SNAT66 + +{abbr}`SNPTv6 (Source IPv6-to-IPv6 Network Prefix Translation)` The conversion +function is mainly used in the following scenarios: +- A single internal network and external network. Use the NAT66 device to + connect a single internal network and public network, and the hosts in + the internal network use IPv6 address prefixes that only support + routing within the local range. When a host in the internal network + accesses the external network, the source IPv6 address prefix in + the message will be converted into a global unicast IPv6 address + prefix by the NAT66 device. +- Redundancy and load sharing. There are multiple NAT66 devices at the edge + of an IPv6 network to another IPv6 network. The path through the NAT66 + device to another IPv6 network forms an equivalent route, and traffic + can be load-shared on these NAT66 devices. In this case, you + can configure the same source address translation rules on these + NAT66 devices, so that any NAT66 device can handle IPv6 traffic between + different sites. +- Multi-homed. In a multi-homed network environment, the NAT66 device + connects to an internal network and simultaneously connects to + different external networks. Address translation can be configured + on each external network side interface of the NAT66 device to + convert the same internal network address into different external + network addresses, and realize the mapping of the same internal + address to multiple external addresses. +(destination-nat66)= + +#### DNAT66 + +The {abbr}`DNPTv6 (Destination IPv6-to-IPv6 Network Prefix Translation)` +destination address translation function is used in scenarios where the +server in the internal network provides services to the external network, +such as providing Web services or FTP services to the external network. +By configuring the mapping relationship between the internal server +address and the external network address on the external network +side interface of the NAT66 device, external network users can +access the internal network server through the designated +external network address. + +### Prefix Conversion + +#### Source Prefix + +Every SNAT66 rule has a translation command defined. The prefix defined +for the translation is the prefix used when the address information in +a packet is replaced.、 + +The {ref}`source-nat66` rule replaces the source address of the packet +and calculates the converted address using the prefix specified in the rule. + +Example: +- Convert the address prefix of a single `fc01::/64` network to `fc00::/64` +- Output from `eth0` network interface + +```none +set nat66 source rule 1 outbound-interface name 'eth0' +set nat66 source rule 1 source prefix 'fc01::/64' +set nat66 source rule 1 translation address 'fc00::/64' +``` + + +#### Destination Prefix + +For the {ref}`destination-nat66` rule, the destination address of +the packet isreplaced by the address calculated from the specified +address or prefix in the `translation address` command + +Example: +- Convert the address prefix of a single `fc00::/64` network + to `fc01::/64` +- Input from `eth0` network interface + +```none +set nat66 destination rule 1 inbound-interface name 'eth0' +set nat66 destination rule 1 destination address 'fc00::/64' +set nat66 destination rule 1 translation address 'fc01::/64' +``` + +For the destination, groups can also be used instead of an address. + +Example: + +```none +set firewall group ipv6-address-group ADR-INSIDE-v6 address fc00::1 + +set nat66 destination rule 1 inbound-interface name 'eth0' +set nat66 destination rule 1 destination group address-group ADR-INSIDE-v6 +set nat66 destination rule 1 translation address 'fc01::/64' +``` + + +## Configuration Examples + +Use the following topology to build a nat66 based isolated +network between internal and external networks (dynamic prefix is +not supported): + +:::{figure} /_static/images/vyos_1_4_nat66_simple.webp +:alt: VyOS NAT66 Simple Configure +::: + +R1: + +```none +set interfaces ethernet eth0 ipv6 address autoconf +set interfaces ethernet eth1 address 'fc01::1/64' +set nat66 destination rule 1 destination address 'fc00:470:f1cd:101::/64' +set nat66 destination rule 1 inbound-interface name 'eth0' +set nat66 destination rule 1 translation address 'fc01::/64' +set nat66 source rule 1 outbound-interface name 'eth0' +set nat66 source rule 1 source prefix 'fc01::/64' +set nat66 source rule 1 translation address 'fc00:470:f1cd:101::/64' +``` + +R2: + +```none +set interfaces bridge br1 address 'fc01::2/64' +set interfaces bridge br1 member interface eth0 +set interfaces bridge br1 member interface eth1 +set protocols static route6 ::/0 next-hop fc01::1 +set service router-advert interface br1 prefix ::/0 +``` + +Use the following topology to translate internal user local addresses +(`fc::/7`) to DHCPv6-PD provided prefixes from an ISP connected to +a VyOS HA pair. + +:::{figure} /_static/images/vyos_1_5_nat66_dhcpv6_wdummy.webp +:alt: VyOS NAT66 DHCPv6 using a dummy interface +::: + +Configure both routers (a and b) for DHCPv6-PD via dummy interface: + +```none +set interfaces dummy dum1 description 'DHCPv6-PD NPT dummy' +set interfaces bonding bond0 vif 20 dhcpv6-options pd 0 interface dum1 address '0' +set interfaces bonding bond0 vif 20 dhcpv6-options pd 1 interface dum1 address '0' +set interfaces bonding bond0 vif 20 dhcpv6-options pd 2 interface dum1 address '0' +set interfaces bonding bond0 vif 20 dhcpv6-options pd 3 interface dum1 address '0' +set interfaces bonding bond0 vif 20 dhcpv6-options rapid-commit +commit +``` + +Get the DHCPv6-PD prefixes from both routers: + +```none +trae@cr01a-vyos# run show interfaces dummy dum1 br +Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down +Interface IP Address S/L Description +--------- ---------- --- ----------- +dum1 2001:db8:123:b008::/64 u/u DHCPv6-PD NPT dummy + 2001:db8:123:b00a::/64 + 2001:db8:123:b00b::/64 + 2001:db8:123:b009::/64 + +trae@cr01b-vyos# run show int dummy dum1 brief +Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down +Interface IP Address S/L Description +--------- ---------- --- ----------- +dum1 2001:db8:123:b00d::/64 u/u DHCPv6-PD NPT dummy + 2001:db8:123:b00c::/64 + 2001:db8:123:b00e::/64 + 2001:db8:123:b00f::/64 +``` + +Configure the A-side router for NPTv6 using the prefixes above: + +```none +set nat66 source rule 10 description 'NPT to VLAN 10' +set nat66 source rule 10 outbound-interface name 'bond0.20' +set nat66 source rule 10 source prefix 'fd52:d62e:8011:a::/64' +set nat66 source rule 10 translation address '2001:db8:123:b008::/64' +set nat66 source rule 20 description 'NPT to VLAN 70' +set nat66 source rule 20 outbound-interface name 'bond0.20' +set nat66 source rule 20 source prefix 'fd52:d62e:8011:46::/64' +set nat66 source rule 20 translation address '2001:db8:123:b009::/64' +set nat66 source rule 30 description 'NPT to VLAN 200' +set nat66 source rule 30 outbound-interface name 'bond0.20' +set nat66 source rule 30 source prefix 'fd52:d62e:8011:c8::/64' +set nat66 source rule 30 translation address '2001:db8:123:b00a::/64' +set nat66 source rule 40 description 'NPT to VLAN 240' +set nat66 source rule 40 outbound-interface name 'bond0.20' +set nat66 source rule 40 source prefix 'fd52:d62e:8011:f0::/64' +set nat66 source rule 40 translation address '2001:db8:123:b00b::/64' +commit +``` + +Configure the B-side router for NPTv6 using the prefixes above: + +```none +set nat66 source rule 10 description 'NPT to VLAN 10' +set nat66 source rule 10 outbound-interface name 'bond0.20' +set nat66 source rule 10 source prefix 'fd52:d62e:8011:a::/64' +set nat66 source rule 10 translation address '2001:db8:123:b00c::/64' +set nat66 source rule 20 description 'NPT to VLAN 70' +set nat66 source rule 20 outbound-interface name 'bond0.20' +set nat66 source rule 20 source prefix 'fd52:d62e:8011:46::/64' +set nat66 source rule 20 translation address '2001:db8:123:b00d::/64' +set nat66 source rule 30 description 'NPT to VLAN 200' +set nat66 source rule 30 outbound-interface name 'bond0.20' +set nat66 source rule 30 source prefix 'fd52:d62e:8011:c8::/64' +set nat66 source rule 30 translation address '2001:db8:123:b00e::/64' +set nat66 source rule 40 description 'NPT to VLAN 240' +set nat66 source rule 40 outbound-interface name 'bond0.20' +set nat66 source rule 40 source prefix 'fd52:d62e:8011:f0::/64' +set nat66 source rule 40 translation address '2001:db8:123:b00f::/64' +commit +``` + +Verify that connections are hitting the rule on both sides: + +```none +trae@cr01a-vyos# run show nat66 source statistics +Rule Packets Bytes Interface +------ --------- ------- ----------- +10 1 104 bond0.20 +20 1 104 bond0.20 +30 8093 669445 bond0.20 +40 2446 216912 bond0.20 +``` diff --git a/docs/configuration/nat/nat44.md b/docs/configuration/nat/nat44.md deleted file mode 100644 index 4f5bd580..00000000 --- a/docs/configuration/nat/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/nat64.md b/docs/configuration/nat/nat64.md deleted file mode 100644 index c1b1c994..00000000 --- a/docs/configuration/nat/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/nat66.md b/docs/configuration/nat/nat66.md deleted file mode 100644 index 1cbe3317..00000000 --- a/docs/configuration/nat/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/index.md b/docs/configuration/pki/index.md deleted file mode 100644 index e7d793de..00000000 --- a/docs/configuration/pki/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/pki/md-index.md b/docs/configuration/pki/md-index.md new file mode 100644 index 00000000..e7d793de --- /dev/null +++ b/docs/configuration/pki/md-index.md @@ -0,0 +1,583 @@ +--- +lastproofread: '2024-01-05' +--- + +```{include} /_include/need_improvement.txt +``` + +(pki)= + +# PKI + +VyOS 1.4 changed the way in how encryption keys or certificates are stored on the +system. In the pre VyOS 1.4 era, certificates got stored under /config and every +service referenced a file. That made copying a running configuration from system +A to system B a bit harder, as you had to copy the files and their permissions +by hand. + +{vytask}`T3642` describes a new CLI subsystem that serves as a "certstore" to +all services requiring any kind of encryption key(s). In short, public and +private certificates are now stored in PKCS#8 format in the regular VyOS CLI. +Keys can now be added, edited, and deleted using the regular set/edit/delete +CLI commands. + +VyOS not only can now manage certificates issued by 3rd party Certificate +Authorities, it can also act as a CA on its own. You can create your own root +CA and sign keys with it by making use of some simple op-mode commands. + +Don't be afraid that you need to re-do your configuration. Key transformation is +handled, as always, by our migration scripts, so this will be a smooth transition +for you! + +## Key Generation + +### Certificate Authority (CA) + +VyOS now also has the ability to create CAs, keys, Diffie-Hellman and other +keypairs from an easy to access operational level command. + +```{opcmd} generate pki ca + +Create a new {abbr}`CA (Certificate Authority)` and output the CAs public and +private key on the console. +``` + +```{opcmd} generate pki ca install \ + +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/access-list.md b/docs/configuration/policy/access-list.md deleted file mode 100644 index c3a92e56..00000000 --- a/docs/configuration/policy/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/as-path-list.md b/docs/configuration/policy/as-path-list.md deleted file mode 100644 index 1fcece91..00000000 --- a/docs/configuration/policy/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/community-list.md b/docs/configuration/policy/community-list.md deleted file mode 100644 index bdcf4140..00000000 --- a/docs/configuration/policy/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/examples.md b/docs/configuration/policy/examples.md deleted file mode 100644 index 2b5d54d2..00000000 --- a/docs/configuration/policy/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/extcommunity-list.md b/docs/configuration/policy/extcommunity-list.md deleted file mode 100644 index 5247c13c..00000000 --- a/docs/configuration/policy/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/index.md b/docs/configuration/policy/index.md deleted file mode 100644 index f919e70a..00000000 --- a/docs/configuration/policy/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/large-community-list.md b/docs/configuration/policy/large-community-list.md deleted file mode 100644 index 23b9a85a..00000000 --- a/docs/configuration/policy/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/local-route.md b/docs/configuration/policy/local-route.md deleted file mode 100644 index 527a2380..00000000 --- a/docs/configuration/policy/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-access-list.md b/docs/configuration/policy/md-access-list.md new file mode 100644 index 00000000..c3a92e56 --- /dev/null +++ b/docs/configuration/policy/md-access-list.md @@ -0,0 +1,70 @@ +# Access List Policy + +Filtering is used for both input and output of the routing information. Once +filtering is defined, it can be applied in any direction. VyOS makes filtering +possible using acls and prefix lists. + +Basic filtering can be done using access-list and access-list6. + +## Configuration + +### Access Lists + +```{cfgcmd} set policy access-list \ + +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 new file mode 100644 index 00000000..1fcece91 --- /dev/null +++ b/docs/configuration/policy/md-as-path-list.md @@ -0,0 +1,29 @@ +# BGP - AS Path Policy + +VyOS provides policies commands exclusively for BGP traffic filtering and +manipulation: **as-path-list** is one of them. + +## Configuration + +### policy as-path-list + +```{cfgcmd} set policy as-path-list \ + +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 new file mode 100644 index 00000000..bdcf4140 --- /dev/null +++ b/docs/configuration/policy/md-community-list.md @@ -0,0 +1,29 @@ +# BGP - Community List + +VyOS provides policies commands exclusively for BGP traffic filtering and +manipulation: **community-list** is one of them. + +## Configuration + +### policy community-list + +```{cfgcmd} set policy community-list \ + +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 new file mode 100644 index 00000000..2b5d54d2 --- /dev/null +++ b/docs/configuration/policy/md-examples.md @@ -0,0 +1,205 @@ +# BGP Example + +**Policy definition:** + +```none +# Create policy +set policy route-map setmet rule 2 action 'permit' +set policy route-map setmet rule 2 set as-path prepend '2 2 2' + +# Apply policy to BGP +set protocols bgp system-as 1 +set protocols bgp neighbor 203.0.113.2 address-family ipv4-unicast route-map import 'setmet' +set protocols bgp neighbor 203.0.113.2 address-family ipv4-unicast soft-reconfiguration 'inbound' +``` + +Using 'soft-reconfiguration' we get the policy update without bouncing the +neighbor. + +**Routes learned before routing policy applied:** + +```none +vyos@vos1:~$ show ip bgp +BGP table version is 0, local router ID is 192.168.56.101 +Status codes: s suppressed, d damped, h history, * valid, > best, i - internal, + r RIB-failure, S Stale, R Removed +Origin codes: i - IGP, e - EGP, ? - incomplete + + Network Next Hop Metric LocPrf Weight Path +*> 198.51.100.3/32 203.0.113.2 1 0 2 i < Path + +Total number of prefixes 1 +``` + +**Routes learned after routing policy applied:** + +```none +vyos@vos1:~$ show ip bgp +BGP table version is 0, local router ID is 192.168.56.101 +Status codes: s suppressed, d damped, h history, * valid, > best, i - internal, + r RIB-failure, S Stale, R Removed +Origin codes: i - IGP, e - EGP, ? - incomplete + + Network Next Hop Metric LocPrf Weight Path +*> 198.51.100.3/32 203.0.113.2 1 0 2 2 2 2 i + +Total number of prefixes 1 +vyos@vos1:~$ +``` + +You now see the longer AS path. + +# Transparent Proxy + +The following example will show how VyOS can be used to redirect web +traffic to an external transparent proxy: + +```none +set policy route FILTER-WEB rule 1000 destination port 80 +set policy route FILTER-WEB rule 1000 protocol tcp +set policy route FILTER-WEB rule 1000 set table 100 +``` + +This creates a route policy called FILTER-WEB with one rule to set the +routing table for matching traffic (TCP port 80) to table ID 100 +instead of the default routing table. + +To create routing table 100 and add a new default gateway to be used by +traffic matching our route policy: + +```none +set protocols static table 100 route 0.0.0.0/0 next-hop 10.255.0.2 +``` + +This can be confirmed using the `show ip route table 100` operational +command. + +Finally, to apply the policy route to ingress traffic on our LAN +interface, we use: + +```none +set policy route FILTER-WEB interface eth1 +``` + + +# Multiple Uplinks + +VyOS Policy-Based Routing (PBR) works by matching source IP address +ranges and forwarding the traffic using different routing tables. + +Routing tables that will be used in this example are: + +- `table 10` Routing table used for VLAN 10 (192.168.188.0/24) +- `table 11` Routing table used for VLAN 11 (192.168.189.0/24) +- `main` Routing table used by VyOS and other interfaces not + participating in PBR + +:::{figure} /_static/images/pbr_example_1.webp +:alt: PBR multiple uplinks +:scale: 80 % + +Policy-Based Routing with multiple ISP uplinks +(source ./draw.io/pbr_example_1.drawio) +::: + +Add default routes for routing `table 10` and `table 11` + +```none +set protocols static table 10 route 0.0.0.0/0 next-hop 192.0.2.1 +set protocols static table 11 route 0.0.0.0/0 next-hop 192.0.2.2 +``` + +Add policy route matching VLAN source addresses + +```none +set policy route PBR rule 20 set table '10' +set policy route PBR rule 20 description 'Route VLAN10 traffic to table 10' +set policy route PBR rule 20 source address '192.168.188.0/24' + +set policy route PBR rule 30 set table '11' +set policy route PBR rule 30 description 'Route VLAN11 traffic to table 11' +set policy route PBR rule 30 source address '192.168.189.0/24' +``` + +Apply routing policy to **inbound** direction of out VLAN interfaces + +```none +set policy route 'PBR' interface eth0.10 +set policy route 'PBR' interface eth0.11 +``` + +**OPTIONAL:** Exclude Inter-VLAN traffic (between VLAN10 and VLAN11) +from PBR + +```none +set firewall group network-group VLANS-GR description 'VLANs networks' +set firewall group network-group VLANS-GR network '192.168.188.0/24' +set firewall group network-group VLANS-GR network '192.168.189.0/24' + +set policy route PBR rule 10 description 'VLAN10 <-> VLAN11 shortcut' +set policy route PBR rule 10 destination group network-group 'VLANS-GR' +set policy route PBR rule 10 set table 'main' +``` + +These commands allow the VLAN10 and VLAN11 hosts to communicate with +each other using the main routing table. + +## Local route + +The following example allows VyOS to use {abbr}`PBR (Policy-Based Routing)` +for traffic, which originated from the router itself. That solution for multiple +ISP's and VyOS router will respond from the same interface that the packet was +received. Also, it used, if we want that one VPN tunnel to be through one +provider, and the second through another. + +- `203.0.113.254` IP 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 new file mode 100644 index 00000000..5247c13c --- /dev/null +++ b/docs/configuration/policy/md-extcommunity-list.md @@ -0,0 +1,33 @@ +# BGP - Extended Community List + +VyOS provides policies commands exclusively for BGP traffic filtering and +manipulation: **extcommunity-list** is one of them. + +## Configuration + +### policy extcommunity-list + +```{cfgcmd} set policy extcommunity-list \ + +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 new file mode 100644 index 00000000..f919e70a --- /dev/null +++ b/docs/configuration/policy/md-index.md @@ -0,0 +1,53 @@ +--- +lastproofread: '2021-07-12' +--- + +```{include} /_include/need_improvement.txt +``` + + +# Policy + +Policies are used for filtering and traffic management. With policies, network +administrators could filter and treat traffic +according to their needs. + +There could be a wide range of routing policies. Some examples are listed +below: +- Filter traffic based on source/destination address. +- Set some metric to routes learned from a particular neighbor. +- Set some attributes (like AS PATH or Community value) to advertised routes + to neighbors. +- Prefer a specific routing protocol routes over another routing protocol + running on the same router. + +Policies, in VyOS, are implemented using FRR filtering and route maps. Detailed +information of FRR could be found in + +## 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 new file mode 100644 index 00000000..23b9a85a --- /dev/null +++ b/docs/configuration/policy/md-large-community-list.md @@ -0,0 +1,29 @@ +# BGP - Large Community List + +VyOS provides policies commands exclusively for BGP traffic filtering and +manipulation: **large-community-list** is one of them. + +## Configuration + +### policy large-community-list + +```{cfgcmd} set policy large-community-list \ + +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 new file mode 100644 index 00000000..527a2380 --- /dev/null +++ b/docs/configuration/policy/md-local-route.md @@ -0,0 +1,100 @@ +# Local Route Policy + +Policies for local traffic are defined in this section. + +## Configuration + +### Local Route IPv4 + +```{cfgcmd} set policy local-route rule \<1-32765\> set table \<1-200|main\> + +Set the routing table to use for forwarding matching packets. +``` + +```{cfgcmd} set policy local-route rule \<1-32765\> set vrf \ + +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 new file mode 100644 index 00000000..eb827c77 --- /dev/null +++ b/docs/configuration/policy/md-prefix-list.md @@ -0,0 +1,152 @@ +# Prefix List Policy + +Prefix lists provides the most powerful prefix based filtering mechanism. In +addition to access-list functionality, ip prefix-list has prefix length range +specification. + +If no ip prefix list is specified, it acts as permit. If ip prefix list is +defined, and no match is found, default deny is applied. + +Prefix filtering can be done using prefix-list and prefix-list6. + +## Configuration + +### IPv4 Prefix Lists (prefix-list) + +```{cfgcmd} set policy prefix-list \ + +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 new file mode 100644 index 00000000..624b542c --- /dev/null +++ b/docs/configuration/policy/md-route-map.md @@ -0,0 +1,439 @@ +# 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 new file mode 100644 index 00000000..828bd0f1 --- /dev/null +++ b/docs/configuration/policy/md-route.md @@ -0,0 +1,424 @@ +# Route and Route6 Policy + +IPv4 route and IPv6 route policies are defined in this section. These route +policies can then be associated to interfaces. + +## Rule-Sets + +A rule-set is a named collection of rules that can be applied to an interface. +Each rule is numbered, has an action to apply if the rule is matched, and the +ability to specify the criteria to match. Data packets go through the rules +from 1 - 999999, at the first match the action of the rule will be executed. + +```{cfgcmd} set policy route \ 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/policy/prefix-list.md b/docs/configuration/policy/prefix-list.md deleted file mode 100644 index eb827c77..00000000 --- a/docs/configuration/policy/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/route-map.md b/docs/configuration/policy/route-map.md deleted file mode 100644 index 624b542c..00000000 --- a/docs/configuration/policy/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/route.md b/docs/configuration/policy/route.md deleted file mode 100644 index 828bd0f1..00000000 --- a/docs/configuration/policy/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/arp.md b/docs/configuration/protocols/arp.md deleted file mode 100644 index 7d9bf4f9..00000000 --- a/docs/configuration/protocols/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/babel.md b/docs/configuration/protocols/babel.md deleted file mode 100644 index b03e9fa4..00000000 --- a/docs/configuration/protocols/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/bfd.md b/docs/configuration/protocols/bfd.md deleted file mode 100644 index 59541abc..00000000 --- a/docs/configuration/protocols/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/bgp.md b/docs/configuration/protocols/bgp.md deleted file mode 100644 index 0af79f6e..00000000 --- a/docs/configuration/protocols/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/failover.md b/docs/configuration/protocols/failover.md deleted file mode 100644 index 96374d11..00000000 --- a/docs/configuration/protocols/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/igmp-proxy.md b/docs/configuration/protocols/igmp-proxy.md deleted file mode 100644 index 961f921b..00000000 --- a/docs/configuration/protocols/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/index.md b/docs/configuration/protocols/index.md deleted file mode 100644 index 5f190ce1..00000000 --- a/docs/configuration/protocols/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/isis.md b/docs/configuration/protocols/isis.md deleted file mode 100644 index ac6db346..00000000 --- a/docs/configuration/protocols/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-arp.md b/docs/configuration/protocols/md-arp.md new file mode 100644 index 00000000..7d9bf4f9 --- /dev/null +++ b/docs/configuration/protocols/md-arp.md @@ -0,0 +1,72 @@ +```{eval-rst} +.. meta:: + :description: The Address Resolution Protocol (ARP) resolves + network-layer addresses to link-layer MAC addresses. + :keywords: arp, network, protocol, mac, address, ipv4, static +``` + +(routing_static_arp)= + +# ARP + +The {abbr}`ARP (Address Resolution Protocol)` resolves IPv4 network layer addresses +to link layer MAC addresses. +addresses. This mapping is essential for communication within the Internet +Protocol suite. ARP was standardized in 1982 by {rfc}`826` (STD 37). + +:::{note} +In Internet Protocol version 6 (IPv6) networks, address resolution is +performed by the Neighbor Discovery Protocol (NDP). +::: + +Use the following commands to configure or view ARP table entries. + +## Configuration + +```{eval-rst} +.. cfgcmd:: set protocols static arp interface 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 new file mode 100644 index 00000000..b03e9fa4 --- /dev/null +++ b/docs/configuration/protocols/md-babel.md @@ -0,0 +1,296 @@ +```{eval-rst} +.. meta:: + :description: The Babel routing protocol provides robust and efficient + routing for wired and wireless mesh networks. + :keywords: babel, routing, protocol, wireless, mesh, network, metric, + ipv4, ipv6 +``` + +(babel)= + +# Babel + +The Babel protocol provides robust and efficient routing for both wired and +wireless mesh networks. By default, Babel uses hop-count metrics on wired links +and a variant of Expected Transmission Count (ETX) on wireless links. +Administrators can configure Babel to account for radio diversity, +automatically compute link latency, and include that latency in the routing +metric. {rfc}`8966` defines the Babel protocol. + +Babel is a dual-stack protocol. A single Babel instance routes both IPv4 and +IPv6 traffic simultaneously. + +## General configuration + +VyOS does not require a specific command to start the Babel process. The system +automatically starts the routing process when you configure the first +Babel-enabled interface. + +```{cfgcmd} set protocols babel interface \ + +**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 new file mode 100644 index 00000000..59541abc --- /dev/null +++ b/docs/configuration/protocols/md-bfd.md @@ -0,0 +1,205 @@ +--- +lastproofread: '2023-01-27' +--- + +```{include} /_include/need_improvement.txt +``` + +(routing-bfd)= + +# BFD + +{abbr}`BFD (Bidirectional Forwarding Detection)` is described and extended by +the following RFCs: {rfc}`5880`, {rfc}`5881` and {rfc}`5883`. + +In the age of very fast networks, a second of unreachability may equal millions of lost packets. +The idea behind BFD is to detect very quickly when a peer is down and take action extremely fast. + +BFD sends lots of small UDP packets very quickly to ensures that the peer is still alive. + +This allows avoiding the timers defined in BGP and OSPF protocol to expires. + +## Configure BFD + +```{cfgcmd} set protocols bfd peer \ + +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 new file mode 100644 index 00000000..0af79f6e --- /dev/null +++ b/docs/configuration/protocols/md-bgp.md @@ -0,0 +1,1414 @@ +(routing-bgp)= + +# BGP + +{abbr}`BGP (Border Gateway Protocol)` is one of the Exterior Gateway Protocols +and the de facto standard interdomain routing protocol. The latest BGP version +is 4. BGP-4 is described in {rfc}`1771` and updated by {rfc}`4271`. {rfc}`2858` +adds multiprotocol support to BGP. + +VyOS makes use of {abbr}`FRR (Free Range Routing)` and we would like to thank +them for their effort! + +## Basic Concepts + +(bgp-autonomous-systems)= + +### Autonomous Systems + +From {rfc}`1930`: + +> An AS is a connected group of one or more IP prefixes run by one or more +> network operators which has a SINGLE and CLEARLY DEFINED routing policy. + +Each {abbr}`AS (Autonomous System)` has an identifying number associated with it +called an {abbr}`ASN (Autonomous System Number)`. This is a two octet value +ranging in value from 1 to 65535. The AS numbers 64512 through 65535 are defined +as private AS numbers. Private AS numbers must not be advertised on the global +Internet. The 2-byte AS number range has been exhausted. 4-byte AS numbers are +specified in {rfc}`6793`, and provide a pool of 4294967296 AS numbers. + +The {abbr}`ASN (Autonomous System Number)` is one of the essential elements of +BGP. BGP is a distance vector routing protocol, and the AS-Path framework +provides distance vector metric and loop detection to BGP. + +```{cfgcmd} set protocols bgp system-as \ + +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 new file mode 100644 index 00000000..96374d11 --- /dev/null +++ b/docs/configuration/protocols/md-failover.md @@ -0,0 +1,237 @@ +--- +description: |- + Failover routes are static routes that are installed in the routing + table only while a configured health-check target responds. VyOS uses them + to switch traffic to a backup path when the primary next hop becomes + unreachable, and to restore the primary path automatically once it recovers. +keywords: |- + failover, failover route, static route, health check, icmp probe, + next hop, route metric +--- + +# Failover + +Failover routes are manually configured network paths used only while their +health-check targets are reachable. If the target stops responding, VyOS +removes the route from the routing table and reinstalls it once the target +recovers. + +## Configuration + +Use the following commands to configure failover routes for a specific remote +`` 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 new file mode 100644 index 00000000..961f921b --- /dev/null +++ b/docs/configuration/protocols/md-igmp-proxy.md @@ -0,0 +1,79 @@ +--- +lastproofread: '2023-11-13' +--- + +(igmp-proxy)= + +# IGMP Proxy + +{abbr}`IGMP (Internet Group Management Protocol)` proxy sends IGMP host messages +on behalf of a connected client. The configuration must define one, and only one +upstream interface, and one or more downstream interfaces. + +## Configuration + +```{cfgcmd} set protocols igmp-proxy interface \ 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 new file mode 100644 index 00000000..5f190ce1 --- /dev/null +++ b/docs/configuration/protocols/md-index.md @@ -0,0 +1,25 @@ +# Protocols + +```{toctree} +:includehidden: true +:maxdepth: 1 + +arp +babel +bfd +bgp +failover +igmp-proxy +isis +mpls +multicast +segment-routing +traffic-engineering +openfabric +ospf +pim +pim6 +rip +rpki +static +``` diff --git a/docs/configuration/protocols/md-isis.md b/docs/configuration/protocols/md-isis.md new file mode 100644 index 00000000..ac6db346 --- /dev/null +++ b/docs/configuration/protocols/md-isis.md @@ -0,0 +1,746 @@ +```{include} /_include/need_improvement.txt +``` + +(routing-isis)= + +# IS-IS + +{abbr}`IS-IS (Intermediate System to Intermediate System)` is a link-state +interior gateway protocol (IGP) which is described in ISO10589, +{rfc}`1195`, {rfc}`5308`. IS-IS runs the Dijkstra shortest-path first (SPF) +algorithm to create a database of the network’s topology, and +from that database to determine the best (that is, lowest cost) path to a +destination. The intermediate systems (the name for routers) exchange topology +information with their directly connected neighbors. IS-IS runs directly on +the data link layer (Layer 2). IS-IS addresses are called +{abbr}`NETs (Network Entity Titles)` and can be 8 to 20 bytes long, but are +generally 10 bytes long. The tree database that is created with IS-IS is +similar to the one that is created with OSPF in that the paths chosen should +be similar. Comparisons to OSPF are inevitable and often are reasonable ones +to make in regards to the way a network will respond with either IGP. + +## General + +### Configuration + +#### Mandatory Settings + +For IS-IS top operate correctly, one must do the equivalent of a Router ID in +CLNS. This Router ID is called the {abbr}`NET (Network Entity Title)`. This +must be unique for each and every router that is operating in IS-IS. It also +must not be duplicated otherwise the same issues that occur within OSPF will +occur within IS-IS when it comes to said duplication. + +```{cfgcmd} set protocols isis net \ + +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 new file mode 100644 index 00000000..71b14be2 --- /dev/null +++ b/docs/configuration/protocols/md-mpls.md @@ -0,0 +1,285 @@ +(mpls)= + +# MPLS + +{abbr}`MPLS (Multi-Protocol Label Switching)` is a packet forwarding paradigm +which differs from regular IP forwarding. Instead of IP addresses being used to +make the decision on finding the exit interface, a router will instead use an +exact match on a 32 bit/4 byte header called the MPLS label. This label is +inserted between the ethernet (layer 2) header and the IP (layer 3) header. +One can statically or dynamically assign label allocations, but we will focus +on dynamic allocation of labels using some sort of label distribution protocol +(such as the aptly named Label Distribution Protocol / LDP, Resource Reservation +Protocol / RSVP, or Segment Routing through OSPF/ISIS). These protocols allow +for the creation of a unidirectional/unicast path called a labeled switched +path (initialized as LSP) throughout the network that operates very much like +a tunnel through the network. An easy way of thinking about how an MPLS LSP +actually forwards traffic throughout a network is to think of a GRE tunnel. +They are not the same in how they operate, but they are the same in how they +handle the tunneled packet. It would be good to think of MPLS as a tunneling +technology that can be used to transport many different types of packets, to +aid in traffic engineering by allowing one to specify paths throughout the +network (using RSVP or SR), and to generally allow for easier intra/inter +network transport of data packets. + +For more information on how MPLS label switching works, please go visit +[Wikipedia (MPLS)]. + +:::{note} +MPLS support in VyOS is not finished yet, and therefore its +functionality is limited. Currently there is no support for MPLS enabled VPN +services such as L2VPNs and mVPNs. RSVP support is also not present as the +underlying routing stack (FRR) does not implement it. Currently VyOS +implements LDP as described in RFC 5036; other LDP standard are the +following ones: RFC 6720, RFC 6667, RFC 5919, RFC 5561, RFC 7552, RFC 4447. +Because MPLS is already available (FRR also supports RFC 3031). +::: + +## Label Distribution Protocol + +The {abbr}`MPLS (Multi-Protocol Label Switching)` architecture does not assume +a single protocol to create MPLS paths. VyOS supports the Label Distribution +Protocol (LDP) as implemented by FRR, based on {rfc}`5036`. + +{abbr}`LDP (Label Distribution Protocol)` is a TCP based MPLS signaling protocol +that distributes labels creating MPLS label switched paths in a dynamic manner. +LDP is not a routing protocol, as it relies on other routing protocols for +forwarding decisions. LDP cannot bootstrap itself, and therefore relies on said +routing protocols for communication with other routers that use LDP. + +In order to allow for LDP on the local router to exchange label advertisements +with other routers, a TCP session will be established between automatically +discovered and statically assigned routers. LDP will try to establish a TCP +session to the **transport address** of other routers. Therefore for LDP to +function properly please make sure the transport address is shown in the +routing table and reachable to traffic at all times. + +It is highly recommended to use the same address for both the LDP router-id and +the discovery transport address, but for VyOS MPLS LDP to work both parameters +must be explicitly set in the configuration. + +Another thing to keep in mind with LDP is that much like BGP, it is a protocol +that runs on top of TCP. It however does not have an ability to do something +like a refresh capability like BGPs route refresh capability. Therefore one +might have to reset the neighbor for a capability change or a configuration +change to work. + +## Configuration Options + +```{cfgcmd} set protocols mpls interface \ + +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 new file mode 100644 index 00000000..27150a29 --- /dev/null +++ b/docs/configuration/protocols/md-multicast.md @@ -0,0 +1,31 @@ +(routing-static)= + +# Multicast + +In order to influence Multicast {abbr}`RPF (Reverse Path Forwarding)` lookup, +it is possible to insert into zebra routes for the Multicast +{abbr}`RIB (Routing Information Base)`. These routes are only used for RPF +lookup and will not be used by ZEBRA for insertion into the kernel or for +normal RIB processing. As such it is possible to create weird states with +these commands. + +Use with caution. Most of the time this will not be necessary. + +```{cfgcmd} set protocols static mroute \ 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 new file mode 100644 index 00000000..09ff5900 --- /dev/null +++ b/docs/configuration/protocols/md-openfabric.md @@ -0,0 +1,242 @@ +(openfabric)= + +# OpenFabric + +OpenFabric, specified in [draft-white-openfabric-06.txt](https://datatracker.ietf.org/doc/html/draft-white-openfabric-06), is +a routing protocol derived from IS-IS, providing link-state routing with +efficient flooding for topologies like spine-leaf networks. + +OpenFabric a dual stack protocol. +A single OpenFabric instance is able to perform routing for both IPv4 and IPv6. + +## General + +### Configuration + +#### Mandatory Settings + +For OpenFabric to operate correctly, one must do the equivalent of a Router ID +in Connectionless Network Service (CLNS). This Router ID is called the +{abbr}`NET (Network Entity Title)`. The system identifier must be unique within +the network + +```{cfgcmd} set protocols openfabric net \ + +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 new file mode 100644 index 00000000..72fefb84 --- /dev/null +++ b/docs/configuration/protocols/md-ospf.md @@ -0,0 +1,1504 @@ +(routing-ospf)= + +# OSPF + +{abbr}`OSPF (Open Shortest Path First)` is a routing protocol for Internet +Protocol (IP) networks. It uses a link state routing (LSR) algorithm and falls +into the group of interior gateway protocols (IGPs), operating within a single +autonomous system (AS). It is defined as OSPF Version 2 in {rfc}`2328` (1998) +for IPv4. Updates for IPv6 are specified as OSPF Version 3 in {rfc}`5340` +(2008). OSPF supports the {abbr}`CIDR (Classless Inter-Domain Routing)` +addressing model. + +OSPF is a widely used IGP in large enterprise networks. + +## OSPFv2 (IPv4) + +### Configuration + +#### General + +VyOS does not have a special command to start the OSPF process. The OSPF process +starts when the first ospf enabled interface is configured. + +```{cfgcmd} set protocols ospf area \ 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 new file mode 100644 index 00000000..db8c9fb7 --- /dev/null +++ b/docs/configuration/protocols/md-pim.md @@ -0,0 +1,282 @@ +--- +lastproofread: '2023-11-13' +--- + +(pim)= + +# PIM – Protocol Independent Multicast + +VyOS supports {abbr}`PIM-SM (PIM Sparse Mode)` as well as +{abbr}`IGMP (Internet Group Management Protocol)` v2 and v3 + +{abbr}`PIM (Protocol Independent Multicast)` must be configured in every +interface of every participating router. Every router must also have the +location of the Rendevouz Point manually configured. Then, unidirectional +shared trees rooted at the Rendevouz Point will automatically be built +for multicast distribution. + +Traffic from multicast sources will go to the Rendezvous Point, and +receivers will pull it from a shared tree using {abbr}`IGMP (Internet +Group Management Protocol)`. + +Multicast receivers will talk IGMP to their local router, so, besides +having PIM configured in every router, IGMP must also be configured in +any router where there could be a multicast receiver locally connected. + +VyOS supports both IGMP version 2 and version 3 (which allows +source-specific multicast). + +## PIM-SM - PIM Sparse Mode + +```{cfgcmd} set protocols pim ecmp + +If PIM has the a choice of ECMP nexthops for a particular +{abbr}`RPF (Reverse Path Forwarding)`, PIM will cause S,G flows to be +spread out amongst the nexthops. If this command is not specified then +the first nexthop found will be used. +``` + +```{cfgcmd} set protocols pim ecmp rebalance + +If PIM is using ECMP and an interface goes down, cause PIM to rebalance all +S,G flows across the remaining nexthops. If this command is not configured +PIM only modifies those S,G flows that were using the interface that went +down. +``` + +```{cfgcmd} set protocols pim join-prune-interval \ + +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 new file mode 100644 index 00000000..707ae606 --- /dev/null +++ b/docs/configuration/protocols/md-pim6.md @@ -0,0 +1,100 @@ +(pim6)= + +# PIM6 - Protocol Independent Multicast for IPv6 + +VyOS facilitates IPv6 Multicast by supporting **PIMv6** and **MLD**. + +PIMv6 (Protocol Independent Multicast for IPv6) must be configured in every +interface of every participating router. Every router must also have the +location of the Rendevouz Point manually configured. +Then, unidirectional shared trees rooted at the Rendevouz Point will +automatically be built for multicast distribution. + +Traffic from multicast sources will go to the Rendezvous Point, and receivers +will pull it from a shared tree using MLD (Multicast Listener Discovery). + +Multicast receivers will talk MLD to their local router, so, besides having +PIMv6 configured in every router, MLD must also be configured in any router +where there could be a multicast receiver locally connected. + +VyOS supports both MLD version 1 and version 2 +(which allows source-specific multicast). + +## Basic commands + +These are the commands for a basic setup. + +```{cfgcmd} set protocols pim6 interface \ + + 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 new file mode 100644 index 00000000..684337d6 --- /dev/null +++ b/docs/configuration/protocols/md-rip.md @@ -0,0 +1,294 @@ +--- +lastproofread: '2021-10-04' +--- + +(rip)= + +# RIP + +{abbr}`RIP (Routing Information Protocol)` is a widely deployed interior gateway +protocol. RIP was developed in the 1970s at Xerox Labs as part of the XNS +routing protocol. RIP is a distance-vector protocol and is based on the +Bellman-Ford algorithms. As a distance-vector protocol, RIP router send updates +to its neighbors periodically, thus allowing the convergence to a known +topology. In each update, the distance to any given network will be broadcast +to its neighboring router. + +Supported versions of RIP are: + +> - RIPv1 as described in {rfc}`1058` +> - RIPv2 as described in {rfc}`2453` + +## General Configuration + +```{cfgcmd} set protocols rip network \ + +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 new file mode 100644 index 00000000..1f4cf5bf --- /dev/null +++ b/docs/configuration/protocols/md-rpki.md @@ -0,0 +1,210 @@ +(rpki)= + +# RPKI + +:::{pull-quote} + +There are two types of Network Admins who deal with BGP, those who have +created an international incident and/or outage, and those who are lying + +-- [tweet by EvilMog](https://twitter.com/Evil_Mog/status/1230924170508169216), 2020-02-21 +::: + +{abbr}`RPKI (Resource Public Key Infrastructure)` is a framework designed to +secure the Internet routing infrastructure. It associates BGP route +announcements with the correct originating {abbr}`ASN (Autonomus System +Number)` which BGP routers can then use to check each route against the +corresponding {abbr}`ROA (Route Origin Authorisation)` for validity. RPKI is +described in {rfc}`6480`. + +A BGP-speaking router like VyOS can retrieve ROA information from RPKI +"Relying Party software" (often just called an "RPKI server" or "RPKI +validator") by using {abbr}`RTR (RPKI to Router)` protocol. There are several +open source implementations to choose from, such as NLNetLabs' [Routinator] +(written in Rust), OpenBSD's [rpki-client] (written in C), and [StayRTR] (written +in Go). The RTR protocol is described in {rfc}`8210`. + +:::{tip} +If you are new to these routing security technologies then there is an +[excellent guide to RPKI] by NLnet Labs which will get you up to speed +very quickly. Their documentation explains everything from what RPKI is to +deploying it in production. It also has some +[help and operational guidance] including "What can I do about my route +having an Invalid state?" +::: + +## Getting started + +First you will need to deploy an RPKI validator for your routers to use. NLnet +Labs provides a collection of [software] you can compare and settle on one. +Once your server is running you can start validating announcements. + +Imported prefixes during the validation may have values: + +> valid +> +> : The prefix and ASN that originated it match a signed ROA. These are +> probably trustworthy route announcements. +> +> invalid +> +> : The prefix or prefix length and ASN that originated it doesn't +> match any existing ROA. This could be the result of a prefix hijack, or +> merely a misconfiguration, but should probably be treated as +> untrustworthy route announcements. +> +> notfound +> +> : No ROA exists which covers that prefix. Unfortunately this is the case for +> about 40%-50% of the prefixes which were announced to the {abbr}`DFZ +> (default-free zone)` at the start of 2024. + +:::{note} +If you are responsible for the global addresses assigned to your +network, please make sure that your prefixes have ROAs associated with them +to avoid being `notfound` by RPKI. For most ASNs this will involve +publishing ROAs via your {abbr}`RIR (Regional Internet Registry)` (RIPE +NCC, APNIC, ARIN, LACNIC, or AFRINIC), and is something you are encouraged +to do whenever you plan to announce addresses into the DFZ. + +Particularly large networks may wish to run their own RPKI certificate +authority and publication server instead of publishing ROAs via their RIR. +This is a subject far beyond the scope of VyOS' documentation. Consider +reading about [Krill] if this is a rabbit hole you need or especially want +to dive down. +::: + +### Features of the Current Implementation + +In a nutshell, the current implementation provides the following features: + +- The BGP router can connect to one or more RPKI cache servers to receive + validated prefix to origin AS mappings. Advanced failover can be implemented + by server sockets with different preference values. +- If no connection to an RPKI cache server can be established after a + pre-defined timeout, the router will process routes without prefix origin + validation. It still will try to establish a connection to an RPKI cache + server in the background. +- By default, enabling RPKI does not change best path selection. In particular, + invalid prefixes will still be considered during best path selection. However, + the router can be configured to ignore all invalid prefixes. +- Route maps can be configured to match a specific RPKI validation state. This + allows the creation of local policies, which handle BGP routes based on the + outcome of the Prefix Origin Validation. +- Updates from the RPKI cache servers are directly applied and path selection is + updated accordingly. (Soft reconfiguration must be enabled for this to work). + +## Configuration + +```{cfgcmd} set protocols rpki polling-period \<1-86400\> + +Define the time interval to update the local cache + +The default value is 300 seconds. +``` + +```{cfgcmd} set protocols rpki expire-interval \<600-172800\> + +Set the number of seconds the router waits until the router +expires the cache. + +The default value is 7200 seconds. +``` + +```{cfgcmd} set protocols rpki retry-interval \<1-7200\> + +Set the number of seconds the router waits until retrying to connect +to the cache server. + +The default value is 600 seconds. +``` + +```{cfgcmd} set protocols rpki cache \ 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 new file mode 100644 index 00000000..45c89a41 --- /dev/null +++ b/docs/configuration/protocols/md-segment-routing.md @@ -0,0 +1,359 @@ +(segment-routing)= + +# Segment Routing + +Segment Routing (SR) is a network architecture that is similar to source-routing +. In this architecture, the ingress router adds a list of segments, known as +SIDs, to the packet as it enters the network. These segments represent different +portions of the network path that the packet will take. + +The SR segments are portions of the network path taken by the packet, and are +called SIDs. At each node, the first SID of the list is read, executed as a +forwarding function, and may be popped to let the next node read the next SID of +the list. The SID list completely determines the path where the packet is +forwarded. + +Segment Routing can be applied to an existing MPLS-based data plane and defines +a control plane network architecture. In MPLS networks, segments are encoded as +MPLS labels and are added at the ingress router. These MPLS labels are then +exchanged and populated by Interior Gateway Protocols (IGPs) like IS-IS or OSPF +which are running on most ISPs. + +:::{note} +Segment routing defines a control plane network architecture and +can be applied to an existing MPLS based dataplane. In the MPLS networks, +segments are encoded as MPLS labels and are imposed at the ingress router. +MPLS labels are exchanged and populated by IGPs like IS-IS.Segment Routing +as per RFC8667 for MPLS dataplane. It supports IPv4, IPv6 and ECMP and has +been tested against Cisco & Juniper routers.however,this deployment is still +EXPERIMENTAL for FRR. +::: + +## IS-IS SR Configuration + +Segment routing (SR) is used by the IGP protocols to interconnect network +devices, below configuration shows how to enable SR on IS-IS: + +:::{note} +``Known limitations:`` + +No support for level redistribution (L1 to L2 or L2 to L1) + +No support for binding SID + +No support for SRLB + +Only one SRGB and default SPF Algorithm is supported +::: + +```{cfgcmd} set protocols isis segment-routing global-block high-label-value \ + +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 new file mode 100644 index 00000000..357f7076 --- /dev/null +++ b/docs/configuration/protocols/md-static.md @@ -0,0 +1,298 @@ +(routing-static)= + +# Static + +Static routes are manually configured routes, which, in general, cannot be +updated dynamically from information VyOS learns about the network topology from +other routing protocols. However, if a link fails, the router will remove +routes, including static routes, from the {abbr}`RIPB (Routing Information +Base)` that used this interface to reach the next hop. In general, static +routes should only be used for very simple network topologies, or to override +the behavior of a dynamic routing protocol for a small number of routes. The +collection of all routes the router has learned from its configuration or from +its dynamic routing protocols is stored in the RIB. Unicast routes are directly +used to determine the forwarding table used for unicast packet forwarding. + +## IPv4 Unicast Routes + +```{cfgcmd} set protocols static route \ 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 new file mode 100644 index 00000000..832023a7 --- /dev/null +++ b/docs/configuration/protocols/md-traffic-engineering.md @@ -0,0 +1,54 @@ +(traffic-engineering)= + +# Traffic Engineering + +Traffic Engineering (TE) is possibility to send traffic from node to node using +alternative path. + +## Common link parameters + +Traffic Engineering parameters are used for both IS-IS and OSPF (not supported yet). + +```{cfgcmd} set protocols traffic-engineering admin-group \ 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/protocols/mpls.md b/docs/configuration/protocols/mpls.md deleted file mode 100644 index 71b14be2..00000000 --- a/docs/configuration/protocols/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/multicast.md b/docs/configuration/protocols/multicast.md deleted file mode 100644 index 27150a29..00000000 --- a/docs/configuration/protocols/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/openfabric.md b/docs/configuration/protocols/openfabric.md deleted file mode 100644 index 09ff5900..00000000 --- a/docs/configuration/protocols/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/ospf.md b/docs/configuration/protocols/ospf.md deleted file mode 100644 index 72fefb84..00000000 --- a/docs/configuration/protocols/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/pim.md b/docs/configuration/protocols/pim.md deleted file mode 100644 index db8c9fb7..00000000 --- a/docs/configuration/protocols/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/pim6.md b/docs/configuration/protocols/pim6.md deleted file mode 100644 index 707ae606..00000000 --- a/docs/configuration/protocols/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/rip.md b/docs/configuration/protocols/rip.md deleted file mode 100644 index 684337d6..00000000 --- a/docs/configuration/protocols/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/rpki.md b/docs/configuration/protocols/rpki.md deleted file mode 100644 index 1f4cf5bf..00000000 --- a/docs/configuration/protocols/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/segment-routing.md b/docs/configuration/protocols/segment-routing.md deleted file mode 100644 index 45c89a41..00000000 --- a/docs/configuration/protocols/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/static.md b/docs/configuration/protocols/static.md deleted file mode 100644 index 357f7076..00000000 --- a/docs/configuration/protocols/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/traffic-engineering.md b/docs/configuration/protocols/traffic-engineering.md deleted file mode 100644 index 832023a7..00000000 --- a/docs/configuration/protocols/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/broadcast-relay.md b/docs/configuration/service/broadcast-relay.md deleted file mode 100644 index 4202ad6b..00000000 --- a/docs/configuration/service/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/config-sync.md b/docs/configuration/service/config-sync.md deleted file mode 100644 index a575f947..00000000 --- a/docs/configuration/service/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/conntrack-sync.md b/docs/configuration/service/conntrack-sync.md deleted file mode 100644 index 47a0ae2f..00000000 --- a/docs/configuration/service/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/console-server.md b/docs/configuration/service/console-server.md deleted file mode 100644 index 9402e935..00000000 --- a/docs/configuration/service/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/dhcp-relay.md b/docs/configuration/service/dhcp-relay.md deleted file mode 100644 index a4a10109..00000000 --- a/docs/configuration/service/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/dhcp-server.md b/docs/configuration/service/dhcp-server.md deleted file mode 100644 index 96c375da..00000000 --- a/docs/configuration/service/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 `