From dfea790b36ddab4c6661436c8eed3cea7af5bd3a Mon Sep 17 00:00:00 2001 From: Daniil Baturin Date: Wed, 6 May 2026 14:08:24 +0100 Subject: Revert "Add incremental RST-to-MyST swap mechanism (#1857)" (#1892) This reverts commit 4b36114e053ee11d0cb264a1e4cfe4692d78f194. --- docs/Makefile | 42 +- docs/_ext/vyos.py | 14 +- docs/_static/images/1u_vyos_back.jpg | Bin 0 -> 586620 bytes docs/_static/images/1u_vyos_front.jpg | Bin 0 -> 363840 bytes docs/_static/images/1u_vyos_front_10ge_open_1.jpg | Bin 0 -> 1853769 bytes docs/_static/images/1u_vyos_front_10ge_open_2.jpg | Bin 0 -> 2294504 bytes docs/_static/images/1u_vyos_front_10ge_open_3.jpg | Bin 0 -> 2067314 bytes docs/_static/images/1u_vyos_front_10ge_open_4.jpg | Bin 0 -> 2447196 bytes docs/_static/images/1u_vyos_front_open_1.jpg | Bin 0 -> 956435 bytes docs/_static/images/1u_vyos_front_open_2.jpg | Bin 0 -> 1225208 bytes docs/_static/images/1u_vyos_front_open_3.jpg | Bin 0 -> 1337822 bytes .../images/480px-Acrosser_ANDJ190N1_Back.jpg | Bin 0 -> 11340 bytes .../images/480px-Acrosser_ANDJ190N1_Front.jpg | Bin 0 -> 11138 bytes docs/_static/images/600px-Partaker-i5.jpg | Bin 0 -> 31015 bytes docs/_static/images/ESP_AH.png | Bin 0 -> 35607 bytes .../_static/images/IPSec_close_action_settings.png | Bin 0 -> 22371 bytes docs/_static/images/L3VPN_hub_and_spoke.png | Bin 0 -> 134458 bytes docs/_static/images/PA-ESP-group.png | Bin 0 -> 27516 bytes docs/_static/images/PA-IKE-GW-1.png | Bin 0 -> 31121 bytes docs/_static/images/PA-IKE-GW-2.png | Bin 0 -> 19848 bytes docs/_static/images/PA-IKE-group.png | Bin 0 -> 26998 bytes docs/_static/images/PA-IPsec-tunnel.png | Bin 0 -> 33519 bytes docs/_static/images/PA-tunnel-1.png | Bin 0 -> 16308 bytes docs/_static/images/PA-tunnel-2.png | Bin 0 -> 18290 bytes docs/_static/images/PA-tunnel-3.png | Bin 0 -> 15779 bytes docs/_static/images/VyOS_Dual-Hub_DMVPN.png | Bin 0 -> 67747 bytes docs/_static/images/Wan_load_balancing1.png | Bin 0 -> 373848 bytes .../_static/images/Wan_load_balancing_exclude1.png | Bin 0 -> 382563 bytes docs/_static/images/ansible.png | Bin 0 -> 204124 bytes docs/_static/images/apu4_desk_1.jpg | Bin 0 -> 816206 bytes docs/_static/images/apu4_desk_2.jpg | Bin 0 -> 288989 bytes docs/_static/images/apu4_desk_3.jpg | Bin 0 -> 831843 bytes docs/_static/images/apu4_desk_4.jpg | Bin 0 -> 804070 bytes docs/_static/images/apu4_rack_1.jpg | Bin 0 -> 305789 bytes docs/_static/images/apu4_rack_2.jpg | Bin 0 -> 623490 bytes docs/_static/images/apu4_rack_3.jpg | Bin 0 -> 1113842 bytes docs/_static/images/apu4_rack_4.jpg | Bin 0 -> 1676612 bytes docs/_static/images/apu4_rack_5.jpg | Bin 0 -> 1584027 bytes docs/_static/images/apu4_rack_vyos_print.jpg | Bin 0 -> 569311 bytes docs/_static/images/aws.png | Bin 0 -> 150759 bytes docs/_static/images/blueprint-dmvpn.png | Bin 0 -> 29626 bytes docs/_static/images/boot-options.png | Bin 0 -> 30582 bytes docs/_static/images/cisco-vpn-ipsec.png | Bin 0 -> 38659 bytes docs/_static/images/cloud-aws-01.png | Bin 0 -> 54783 bytes docs/_static/images/cloud-aws-02.png | Bin 0 -> 88657 bytes docs/_static/images/cloud-aws-03.png | Bin 0 -> 48191 bytes docs/_static/images/cloud-aws-04.png | Bin 0 -> 131948 bytes docs/_static/images/cloud-aws-05.png | Bin 0 -> 103661 bytes docs/_static/images/cloud-aws-06.png | Bin 0 -> 111207 bytes docs/_static/images/cloud-aws-07.png | Bin 0 -> 72764 bytes docs/_static/images/cloud-aws-08.png | Bin 0 -> 20893 bytes docs/_static/images/cloud-azure-01.png | Bin 0 -> 90521 bytes docs/_static/images/cloud-azure-02.png | Bin 0 -> 56507 bytes docs/_static/images/cloud-azure-03.png | Bin 0 -> 47364 bytes docs/_static/images/cloud-azure-04.png | Bin 0 -> 87475 bytes docs/_static/images/cloud-azure-05.png | Bin 0 -> 77301 bytes docs/_static/images/cloud-azure-06.png | Bin 0 -> 57830 bytes docs/_static/images/cloud-gcp-01.png | Bin 0 -> 5526 bytes docs/_static/images/cloud-gcp-02.png | Bin 0 -> 46685 bytes docs/_static/images/cloud-gcp-03.png | Bin 0 -> 106217 bytes docs/_static/images/cloud-gcp-04.png | Bin 0 -> 19727 bytes docs/_static/images/cloud-gcp-05.png | Bin 0 -> 26049 bytes .../images/dhcp-relay-through-gre-bridge.png | Bin 0 -> 31261 bytes docs/_static/images/dual-hub-DMVPN.png | Bin 0 -> 88497 bytes docs/_static/images/eve-ng-vyos.png | Bin 0 -> 4228 bytes .../_static/images/firewall-and-vrf-blueprints.png | Bin 0 -> 84270 bytes docs/_static/images/firewall-bridge-forward.png | Bin 0 -> 26359 bytes docs/_static/images/firewall-bridge-input.png | Bin 0 -> 39158 bytes docs/_static/images/firewall-bridge-output.png | Bin 0 -> 34496 bytes .../images/firewall-flowtable-packet-flow.png | Bin 0 -> 47883 bytes docs/_static/images/firewall-fwd-packet-flow.png | Bin 0 -> 30593 bytes docs/_static/images/firewall-gral-packet-flow.png | Bin 0 -> 49632 bytes docs/_static/images/firewall-input-packet-flow.png | Bin 0 -> 43944 bytes docs/_static/images/firewall-netfilter.png | Bin 0 -> 73608 bytes docs/_static/images/firewall-traditional.png | Bin 0 -> 53437 bytes docs/_static/images/firewall-zonebased.png | Bin 0 -> 55621 bytes docs/_static/images/gns3-01.png | Bin 0 -> 28912 bytes docs/_static/images/gns3-02.png | Bin 0 -> 179730 bytes docs/_static/images/gns3-03.png | Bin 0 -> 22829 bytes docs/_static/images/gns3-04.png | Bin 0 -> 35150 bytes docs/_static/images/gns3-05.png | Bin 0 -> 31728 bytes docs/_static/images/gns3-06.png | Bin 0 -> 29168 bytes docs/_static/images/gns3-07.png | Bin 0 -> 31199 bytes docs/_static/images/gns3-08.png | Bin 0 -> 29636 bytes docs/_static/images/gns3-09.png | Bin 0 -> 21881 bytes docs/_static/images/gns3-10.png | Bin 0 -> 30788 bytes docs/_static/images/gns3-11.png | Bin 0 -> 168937 bytes docs/_static/images/gns3-12.png | Bin 0 -> 58597 bytes docs/_static/images/gns3-13.png | Bin 0 -> 56994 bytes docs/_static/images/gns3-14.png | Bin 0 -> 28821 bytes docs/_static/images/gns3-15.png | Bin 0 -> 45453 bytes docs/_static/images/gns3-16.png | Bin 0 -> 54790 bytes docs/_static/images/gns3-17.png | Bin 0 -> 169380 bytes docs/_static/images/gns3-20.png | Bin 0 -> 55168 bytes docs/_static/images/gns3-21.png | Bin 0 -> 25663 bytes docs/_static/images/gns3-215.png | Bin 0 -> 44485 bytes docs/_static/images/gns3-22.png | Bin 0 -> 54674 bytes docs/_static/images/gowin-01.png | Bin 0 -> 355723 bytes docs/_static/images/gowin-02.png | Bin 0 -> 2613833 bytes docs/_static/images/gowin-03.png | Bin 0 -> 2268530 bytes docs/_static/images/gowin-04.png | Bin 0 -> 2165023 bytes docs/_static/images/inter-vrf-routing-vrf-lite.png | Bin 0 -> 104622 bytes docs/_static/images/ipsec-vyos-pa.png | Bin 0 -> 61250 bytes docs/_static/images/json.png | Bin 0 -> 26585 bytes docs/_static/images/key.png | Bin 0 -> 165894 bytes docs/_static/images/keypairs.png | Bin 0 -> 49718 bytes docs/_static/images/lac-lns-diagram.jpg | Bin 0 -> 35665 bytes docs/_static/images/lac-lns-winclient.jpg | Bin 0 -> 90842 bytes docs/_static/images/ldapone.png | Bin 0 -> 88753 bytes docs/_static/images/ldaptwo.png | Bin 0 -> 58322 bytes docs/_static/images/mainschema.png | Bin 0 -> 78790 bytes docs/_static/images/multicast-basic.png | Bin 0 -> 43708 bytes docs/_static/images/nat_before_vpn_topology.png | Bin 0 -> 19015 bytes docs/_static/images/nmp1.png | Bin 0 -> 128546 bytes docs/_static/images/nmp2.png | Bin 0 -> 52507 bytes docs/_static/images/nmp3.png | Bin 0 -> 107595 bytes docs/_static/images/nmp4.png | Bin 0 -> 72678 bytes docs/_static/images/nmp5.png | Bin 0 -> 115299 bytes docs/_static/images/nmp6.png | Bin 0 -> 130524 bytes docs/_static/images/nmp7.png | Bin 0 -> 100135 bytes docs/_static/images/openvpn_site2site_diagram.jpg | Bin 0 -> 24179 bytes docs/_static/images/pbr_example_1.png | Bin 0 -> 39170 bytes .../images/policy-based-ipsec-and-firewall.png | Bin 0 -> 42987 bytes docs/_static/images/pppoe-ipv6-pd-diagram.jpg | Bin 0 -> 19993 bytes docs/_static/images/project.png | Bin 0 -> 18173 bytes docs/_static/images/qos1.png | Bin 0 -> 135527 bytes docs/_static/images/qos10.png | Bin 0 -> 119669 bytes docs/_static/images/qos2.png | Bin 0 -> 140834 bytes docs/_static/images/qos3.png | Bin 0 -> 16699 bytes docs/_static/images/qos4.png | Bin 0 -> 17273 bytes docs/_static/images/qos5.png | Bin 0 -> 15868 bytes docs/_static/images/qos6.png | Bin 0 -> 139244 bytes docs/_static/images/qos7.png | Bin 0 -> 17775 bytes docs/_static/images/qos8.png | Bin 0 -> 17368 bytes docs/_static/images/qos9.png | Bin 0 -> 17065 bytes docs/_static/images/reset-password-step-1.jpg | Bin 0 -> 37351 bytes docs/_static/images/reset-password-step-2.jpg | Bin 0 -> 42278 bytes docs/_static/images/reset-password-step-3.jpg | Bin 0 -> 36932 bytes docs/_static/images/reset-password-step-4.jpg | Bin 0 -> 31564 bytes docs/_static/images/reset-password-step-5.jpg | Bin 0 -> 100973 bytes docs/_static/images/service.png | Bin 0 -> 195145 bytes .../images/service_conntrack_sync-schema.png | Bin 0 -> 56954 bytes docs/_static/images/service_dhcp-relay01.png | Bin 0 -> 153617 bytes docs/_static/images/service_dhcpv6-relay01.png | Bin 0 -> 150157 bytes ...rvice_snmp_communication_principles_diagram.png | Bin 0 -> 56582 bytes docs/_static/images/sg.png | Bin 0 -> 31817 bytes docs/_static/images/sticky-connections.jpg | Bin 0 -> 22252 bytes docs/_static/images/traffic.png | Bin 0 -> 36786 bytes docs/_static/images/uefi_secureboot_01.png | Bin 0 -> 60527 bytes docs/_static/images/uefi_secureboot_02.png | Bin 0 -> 14091 bytes docs/_static/images/uefi_secureboot_03.png | Bin 0 -> 14760 bytes docs/_static/images/uefi_secureboot_04.png | Bin 0 -> 7349 bytes docs/_static/images/uefi_secureboot_05.png | Bin 0 -> 6636 bytes docs/_static/images/uefi_secureboot_06.png | Bin 0 -> 7102 bytes docs/_static/images/uefi_secureboot_07.png | Bin 0 -> 12622 bytes docs/_static/images/virt-libvirt-01.png | Bin 0 -> 33227 bytes docs/_static/images/virt-libvirt-02.png | Bin 0 -> 30981 bytes docs/_static/images/virt-libvirt-03.png | Bin 0 -> 24547 bytes docs/_static/images/virt-libvirt-04.png | Bin 0 -> 28896 bytes docs/_static/images/virt-libvirt-05.png | Bin 0 -> 38080 bytes docs/_static/images/virt-libvirt-06.png | Bin 0 -> 28784 bytes docs/_static/images/virt-libvirt-qc-01.png | Bin 0 -> 33468 bytes docs/_static/images/virt-libvirt-qc-02.png | Bin 0 -> 26749 bytes docs/_static/images/virt-libvirt-qc-03.png | Bin 0 -> 28278 bytes docs/_static/images/vpn_dmvpn_topology01.png | Bin 0 -> 94382 bytes docs/_static/images/vpn_s2s_ikev2.png | Bin 0 -> 66279 bytes docs/_static/images/vpn_s2s_ikev2_c.png | Bin 0 -> 69496 bytes docs/_static/images/vrf-example-topology-01.png | Bin 0 -> 32567 bytes docs/_static/images/vyos-downloads.png | Bin 0 -> 65202 bytes docs/_static/images/vyos-sr-isis.png | Bin 0 -> 45339 bytes docs/_static/images/vyos_1_4_nat66_simple.png | Bin 0 -> 21021 bytes .../images/vyos_1_5_nat66_dhcpv6_wdummy.png | Bin 0 -> 349078 bytes docs/_static/images/vyos_arista_bond_lacp.png | Bin 0 -> 40622 bytes docs/_static/images/vyosnew-downloads.png | Bin 0 -> 64419 bytes docs/_static/images/wireguard_qrcode.jpg | Bin 0 -> 133939 bytes .../_static/images/wireguard_site2site_diagram.jpg | Bin 0 -> 19987 bytes docs/_static/images/zone-policy-diagram.png | Bin 0 -> 113618 bytes docs/_swap.txt | 262 ---- docs/automation/md-cloud-init.md | 378 ----- docs/automation/md-command-scripting.md | 225 --- docs/automation/md-index.md | 16 - docs/automation/md-vyos-ansible.md | 101 -- docs/automation/md-vyos-api.md | 587 -------- docs/automation/md-vyos-govyos.md | 197 --- docs/automation/md-vyos-napalm.md | 152 -- docs/automation/md-vyos-netmiko.md | 76 - docs/automation/md-vyos-pyvyos.md | 149 -- docs/automation/md-vyos-salt.md | 211 --- docs/automation/terraform/md-index.md | 29 - docs/automation/terraform/md-terraformAWS.md | 548 ------- docs/automation/terraform/md-terraformAZ.md | 501 ------- docs/automation/terraform/md-terraformGoogle.md | 703 --------- docs/automation/terraform/md-terraformvSphere.md | 388 ----- docs/automation/terraform/terraformvyos.md | 44 - docs/conf.py | 29 +- .../DHCPRelay_through_GRE/_include/topology.png | Bin 0 -> 57080 bytes .../md-DHCPRelay_through_GRE.md | 89 -- .../autotest/L3VPN_EVPN/_include/topology.png | Bin 0 -> 102832 bytes .../autotest/L3VPN_EVPN/md-L3VPN_EVPN.md | 246 --- .../OpenVPN_with_LDAP/_include/topology.png | Bin 0 -> 40891 bytes .../OpenVPN_with_LDAP/md-OpenVPN_with_LDAP.md | 238 --- .../autotest/Wireguard/_include/topology.png | Bin 0 -> 158227 bytes .../autotest/Wireguard/md-Wireguard.md | 108 -- .../autotest/tunnelbroker/_include/topology.png | Bin 0 -> 34614 bytes .../autotest/tunnelbroker/md-tunnelbroker.md | 206 --- docs/configexamples/md-ansible.md | 212 --- docs/configexamples/md-azure-vpn-bgp.md | 134 -- docs/configexamples/md-azure-vpn-dual-bgp.md | 160 -- docs/configexamples/md-bgp-ipv6-unnumbered.md | 174 --- docs/configexamples/md-dmvpn-dualhub-dualcloud.md | 552 ------- docs/configexamples/md-firewall.md | 16 - docs/configexamples/md-fwall-and-bridge.md | 490 ------ docs/configexamples/md-fwall-and-vrf.md | 121 -- docs/configexamples/md-ha.md | 556 ------- docs/configexamples/md-index.md | 60 - .../md-inter-vrf-routing-vrf-lite.md | 797 ---------- docs/configexamples/md-ipsec-cisco-policy-based.md | 363 ----- docs/configexamples/md-ipsec-cisco-route-based.md | 406 ----- docs/configexamples/md-ipsec-pa-route-based.md | 412 ----- docs/configexamples/md-l3vpn-hub-and-spoke.md | 1091 -------------- docs/configexamples/md-lac-lns.md | 181 --- docs/configexamples/md-nmp.md | 76 - docs/configexamples/md-ospf-unnumbered.md | 118 -- .../md-policy-based-ipsec-and-firewall.md | 269 ---- docs/configexamples/md-pppoe-ipv6-basic.md | 114 -- docs/configexamples/md-qos.md | 201 --- docs/configexamples/md-segment-routing-isis.md | 277 ---- docs/configexamples/md-site-2-site-cisco.md | 170 --- docs/configexamples/md-wan-load-balancing.md | 183 --- docs/configexamples/md-zone-policy.md | 417 ------ docs/configuration/container/md-index.md | 479 ------ docs/configuration/firewall/md-bridge.md | 685 --------- docs/configuration/firewall/md-flowtables.md | 176 --- docs/configuration/firewall/md-global-options.md | 186 --- docs/configuration/firewall/md-groups.md | 477 ------ docs/configuration/firewall/md-index.md | 278 ---- docs/configuration/firewall/md-ipv4.md | 1517 ------------------- docs/configuration/firewall/md-ipv6.md | 1567 -------------------- docs/configuration/firewall/md-zone.md | 201 --- docs/configuration/highavailability/md-index.md | 561 ------- docs/configuration/interfaces/md-bonding.md | 764 ---------- docs/configuration/interfaces/md-bridge.md | 431 ------ docs/configuration/interfaces/md-dummy.md | 87 -- docs/configuration/interfaces/md-ethernet.md | 515 ------- docs/configuration/interfaces/md-geneve.md | 105 -- docs/configuration/interfaces/md-index.md | 26 - docs/configuration/interfaces/md-l2tpv3.md | 170 --- docs/configuration/interfaces/md-loopback.md | 67 - docs/configuration/interfaces/md-macsec.md | 319 ---- .../interfaces/md-openvpn-examples.md | 769 ---------- docs/configuration/interfaces/md-openvpn.md | 614 -------- docs/configuration/interfaces/md-pppoe.md | 419 ------ .../configuration/interfaces/md-pseudo-ethernet.md | 52 - docs/configuration/interfaces/md-sstp-client.md | 170 --- docs/configuration/interfaces/md-tunnel.md | 309 ---- .../interfaces/md-virtual-ethernet.md | 119 -- docs/configuration/interfaces/md-vti.md | 121 -- docs/configuration/interfaces/md-vxlan.md | 373 ----- docs/configuration/interfaces/md-wireguard.md | 434 ------ docs/configuration/interfaces/md-wireless.md | 923 ------------ docs/configuration/interfaces/md-wwan.md | 355 ----- docs/configuration/loadbalancing/md-haproxy.md | 510 ------- docs/configuration/loadbalancing/md-index.md | 15 - docs/configuration/loadbalancing/md-wan.md | 306 ---- docs/configuration/md-index.md | 23 - docs/configuration/nat/md-cgnat.md | 200 --- docs/configuration/nat/md-index.md | 13 - docs/configuration/nat/md-nat44.md | 788 ---------- docs/configuration/nat/md-nat64.md | 73 - docs/configuration/nat/md-nat66.md | 243 --- docs/configuration/pki/md-index.md | 583 -------- docs/configuration/policy/md-access-list.md | 70 - docs/configuration/policy/md-as-path-list.md | 29 - docs/configuration/policy/md-community-list.md | 29 - docs/configuration/policy/md-examples.md | 205 --- docs/configuration/policy/md-extcommunity-list.md | 33 - docs/configuration/policy/md-index.md | 53 - .../policy/md-large-community-list.md | 29 - docs/configuration/policy/md-local-route.md | 100 -- docs/configuration/policy/md-prefix-list.md | 152 -- docs/configuration/policy/md-route-map.md | 439 ------ docs/configuration/policy/md-route.md | 424 ------ docs/configuration/protocols/md-arp.md | 72 - docs/configuration/protocols/md-babel.md | 296 ---- docs/configuration/protocols/md-bfd.md | 205 --- docs/configuration/protocols/md-bgp.md | 1414 ------------------ docs/configuration/protocols/md-failover.md | 237 --- docs/configuration/protocols/md-igmp-proxy.md | 79 - docs/configuration/protocols/md-index.md | 25 - docs/configuration/protocols/md-isis.md | 746 ---------- docs/configuration/protocols/md-mpls.md | 285 ---- docs/configuration/protocols/md-multicast.md | 31 - docs/configuration/protocols/md-openfabric.md | 242 --- docs/configuration/protocols/md-ospf.md | 1504 ------------------- docs/configuration/protocols/md-pim.md | 282 ---- docs/configuration/protocols/md-pim6.md | 100 -- docs/configuration/protocols/md-rip.md | 294 ---- docs/configuration/protocols/md-rpki.md | 210 --- docs/configuration/protocols/md-segment-routing.md | 359 ----- docs/configuration/protocols/md-static.md | 298 ---- .../protocols/md-traffic-engineering.md | 54 - docs/configuration/service/md-broadcast-relay.md | 70 - docs/configuration/service/md-config-sync.md | 164 -- docs/configuration/service/md-conntrack-sync.md | 321 ---- docs/configuration/service/md-console-server.md | 139 -- docs/configuration/service/md-dhcp-relay.md | 205 --- docs/configuration/service/md-dhcp-server.md | 1178 --------------- docs/configuration/service/md-dns.md | 582 -------- docs/configuration/service/md-eventhandler.md | 130 -- docs/configuration/service/md-https.md | 138 -- docs/configuration/service/md-index.md | 29 - docs/configuration/service/md-ipoe-server.md | 512 ------- docs/configuration/service/md-lldp.md | 154 -- docs/configuration/service/md-mdns.md | 131 -- docs/configuration/service/md-monitoring.md | 334 ----- docs/configuration/service/md-ntp.md | 202 --- docs/configuration/service/md-pppoe-server.md | 753 ---------- docs/configuration/service/md-router-advert.md | 121 -- docs/configuration/service/md-salt-minion.md | 51 - docs/configuration/service/md-snmp.md | 258 ---- docs/configuration/service/md-ssh.md | 366 ----- docs/configuration/service/md-suricata.md | 93 -- docs/configuration/service/md-tftp-server.md | 78 - docs/configuration/service/md-webproxy.md | 459 ------ docs/configuration/system/md-acceleration.md | 158 -- docs/configuration/system/md-conntrack.md | 218 --- docs/configuration/system/md-console.md | 59 - docs/configuration/system/md-default-route.md | 40 - docs/configuration/system/md-flow-accounting.md | 209 --- docs/configuration/system/md-frr.md | 45 - docs/configuration/system/md-host-name.md | 70 - docs/configuration/system/md-index.md | 34 - docs/configuration/system/md-ip.md | 126 -- docs/configuration/system/md-ipv6.md | 193 --- docs/configuration/system/md-lcd.md | 41 - docs/configuration/system/md-login.md | 604 -------- docs/configuration/system/md-name-server.md | 65 - docs/configuration/system/md-option.md | 190 --- docs/configuration/system/md-proxy.md | 27 - docs/configuration/system/md-sflow.md | 66 - docs/configuration/system/md-sysctl.md | 16 - docs/configuration/system/md-syslog.md | 450 ------ docs/configuration/system/md-task-scheduler.md | 45 - docs/configuration/system/md-time-zone.md | 17 - docs/configuration/system/md-updates.md | 36 - docs/configuration/system/md-watchdog.md | 212 --- docs/configuration/trafficpolicy/md-index.md | 1299 ---------------- docs/configuration/vpn/ipsec/md-index.md | 11 - docs/configuration/vpn/ipsec/md-ipsec_general.md | 407 ----- .../vpn/ipsec/md-remoteaccess_ipsec.md | 186 --- docs/configuration/vpn/ipsec/md-site2site_ipsec.md | 780 ---------- .../vpn/ipsec/md-troubleshooting_ipsec.md | 313 ---- docs/configuration/vpn/md-dmvpn.md | 431 ------ docs/configuration/vpn/md-index.md | 14 - docs/configuration/vpn/md-l2tp.md | 624 -------- docs/configuration/vpn/md-openconnect.md | 330 ----- docs/configuration/vpn/md-pptp.md | 594 -------- docs/configuration/vpn/md-rsa-keys.md | 114 -- docs/configuration/vpn/md-sstp.md | 698 --------- docs/configuration/vrf/md-index.md | 646 -------- docs/contributing/md-build-vyos.md | 730 --------- docs/contributing/md-cla.md | 45 - docs/contributing/md-debugging.md | 204 --- docs/contributing/md-development.md | 549 ------- docs/contributing/md-index.md | 13 - docs/contributing/md-issues-features.md | 122 -- docs/contributing/md-testing.md | 207 --- docs/contributing/md-upstream-packages.md | 147 -- docs/installation/cloud/md-aws.md | 188 --- docs/installation/cloud/md-azure.md | 98 -- docs/installation/cloud/md-gcp.md | 61 - docs/installation/cloud/md-index.md | 10 - docs/installation/cloud/md-oracle.md | 17 - docs/installation/md-bare-metal.md | 626 -------- docs/installation/md-image.md | 113 -- docs/installation/md-index.md | 30 - docs/installation/md-install.md | 466 ------ docs/installation/md-secure-boot.md | 194 --- docs/installation/md-update.md | 105 -- docs/installation/virtual/md-docker.md | 72 - docs/installation/virtual/md-eve-ng.md | 14 - docs/installation/virtual/md-gns3.md | 191 --- docs/installation/virtual/md-index.md | 16 - docs/installation/virtual/md-libvirt.md | 186 --- docs/installation/virtual/md-proxmox.md | 80 - docs/installation/virtual/md-vmware.md | 38 - docs/introducing/md-about.md | 21 - docs/introducing/md-history.md | 171 --- docs/md-404.md | 13 - docs/md-cli.md | 868 ----------- docs/md-coverage.md | 59 - docs/md-documentation.md | 442 ------ docs/md-index.md | 113 -- docs/md-quick-start.md | 381 ----- docs/operation/md-boot-options.md | 55 - docs/operation/md-index.md | 12 - docs/operation/md-information.md | 106 -- docs/operation/md-password-recovery.md | 46 - docs/operation/md-raid.md | 236 --- docs/operation/md-upgrade-recovery.md | 70 - docs/troubleshooting/md-connectivity.md | 147 -- docs/troubleshooting/md-index.md | 17 - docs/troubleshooting/md-interfaces.md | 36 - docs/troubleshooting/md-monitoring.md | 152 -- docs/troubleshooting/md-system.md | 48 - docs/troubleshooting/md-terminal.md | 39 - docs/vpp/configuration/dataplane/md-buffers.md | 102 -- docs/vpp/configuration/dataplane/md-cpu.md | 71 - docs/vpp/configuration/dataplane/md-index.md | 36 - docs/vpp/configuration/dataplane/md-interface.md | 104 -- docs/vpp/configuration/dataplane/md-ipsec.md | 74 - docs/vpp/configuration/dataplane/md-ipv6.md | 46 - docs/vpp/configuration/dataplane/md-l2learn.md | 35 - docs/vpp/configuration/dataplane/md-lcp.md | 46 - docs/vpp/configuration/dataplane/md-logging.md | 59 - docs/vpp/configuration/dataplane/md-memory.md | 142 -- docs/vpp/configuration/dataplane/md-system.md | 212 --- docs/vpp/configuration/dataplane/md-unix.md | 57 - docs/vpp/configuration/dataplane/system.rst | 1 - docs/vpp/configuration/interfaces/md-bonding.md | 255 ---- docs/vpp/configuration/interfaces/md-bridge.md | 194 --- docs/vpp/configuration/interfaces/md-gre.md | 168 --- docs/vpp/configuration/interfaces/md-index.md | 49 - docs/vpp/configuration/interfaces/md-ipip.md | 119 -- docs/vpp/configuration/interfaces/md-loopback.md | 148 -- docs/vpp/configuration/interfaces/md-vxlan.md | 157 -- docs/vpp/configuration/interfaces/md-xconnect.md | 108 -- docs/vpp/configuration/md-acl.md | 582 -------- docs/vpp/configuration/md-index.md | 47 - docs/vpp/configuration/md-ipfix.md | 50 - docs/vpp/configuration/md-ipsec.md | 188 --- docs/vpp/configuration/md-sflow.md | 62 - docs/vpp/configuration/nat/md-cgnat.md | 249 ---- docs/vpp/configuration/nat/md-index.md | 41 - docs/vpp/configuration/nat/md-nat44.md | 755 ---------- docs/vpp/md-description.md | 87 -- docs/vpp/md-index.md | 25 - docs/vpp/md-limitations.md | 42 - docs/vpp/md-requirements.md | 131 -- docs/vpp/md-troubleshooting.md | 474 ------ 440 files changed, 13 insertions(+), 65701 deletions(-) create mode 100644 docs/_static/images/1u_vyos_back.jpg create mode 100644 docs/_static/images/1u_vyos_front.jpg create mode 100644 docs/_static/images/1u_vyos_front_10ge_open_1.jpg create mode 100644 docs/_static/images/1u_vyos_front_10ge_open_2.jpg create mode 100644 docs/_static/images/1u_vyos_front_10ge_open_3.jpg create mode 100644 docs/_static/images/1u_vyos_front_10ge_open_4.jpg create mode 100644 docs/_static/images/1u_vyos_front_open_1.jpg create mode 100644 docs/_static/images/1u_vyos_front_open_2.jpg create mode 100644 docs/_static/images/1u_vyos_front_open_3.jpg create mode 100644 docs/_static/images/480px-Acrosser_ANDJ190N1_Back.jpg create mode 100644 docs/_static/images/480px-Acrosser_ANDJ190N1_Front.jpg create mode 100644 docs/_static/images/600px-Partaker-i5.jpg create mode 100644 docs/_static/images/ESP_AH.png create mode 100644 docs/_static/images/IPSec_close_action_settings.png create mode 100644 docs/_static/images/L3VPN_hub_and_spoke.png create mode 100644 docs/_static/images/PA-ESP-group.png create mode 100644 docs/_static/images/PA-IKE-GW-1.png create mode 100644 docs/_static/images/PA-IKE-GW-2.png create mode 100644 docs/_static/images/PA-IKE-group.png create mode 100644 docs/_static/images/PA-IPsec-tunnel.png create mode 100644 docs/_static/images/PA-tunnel-1.png create mode 100644 docs/_static/images/PA-tunnel-2.png create mode 100644 docs/_static/images/PA-tunnel-3.png create mode 100644 docs/_static/images/VyOS_Dual-Hub_DMVPN.png create mode 100644 docs/_static/images/Wan_load_balancing1.png create mode 100644 docs/_static/images/Wan_load_balancing_exclude1.png create mode 100644 docs/_static/images/ansible.png create mode 100644 docs/_static/images/apu4_desk_1.jpg create mode 100644 docs/_static/images/apu4_desk_2.jpg create mode 100644 docs/_static/images/apu4_desk_3.jpg create mode 100644 docs/_static/images/apu4_desk_4.jpg create mode 100644 docs/_static/images/apu4_rack_1.jpg create mode 100644 docs/_static/images/apu4_rack_2.jpg create mode 100644 docs/_static/images/apu4_rack_3.jpg create mode 100644 docs/_static/images/apu4_rack_4.jpg create mode 100644 docs/_static/images/apu4_rack_5.jpg create mode 100644 docs/_static/images/apu4_rack_vyos_print.jpg create mode 100644 docs/_static/images/aws.png create mode 100644 docs/_static/images/blueprint-dmvpn.png create mode 100644 docs/_static/images/boot-options.png create mode 100644 docs/_static/images/cisco-vpn-ipsec.png create mode 100644 docs/_static/images/cloud-aws-01.png create mode 100644 docs/_static/images/cloud-aws-02.png create mode 100644 docs/_static/images/cloud-aws-03.png create mode 100644 docs/_static/images/cloud-aws-04.png create mode 100644 docs/_static/images/cloud-aws-05.png create mode 100644 docs/_static/images/cloud-aws-06.png create mode 100644 docs/_static/images/cloud-aws-07.png create mode 100644 docs/_static/images/cloud-aws-08.png create mode 100644 docs/_static/images/cloud-azure-01.png create mode 100644 docs/_static/images/cloud-azure-02.png create mode 100644 docs/_static/images/cloud-azure-03.png create mode 100644 docs/_static/images/cloud-azure-04.png create mode 100644 docs/_static/images/cloud-azure-05.png create mode 100644 docs/_static/images/cloud-azure-06.png create mode 100644 docs/_static/images/cloud-gcp-01.png create mode 100644 docs/_static/images/cloud-gcp-02.png create mode 100644 docs/_static/images/cloud-gcp-03.png create mode 100644 docs/_static/images/cloud-gcp-04.png create mode 100644 docs/_static/images/cloud-gcp-05.png create mode 100644 docs/_static/images/dhcp-relay-through-gre-bridge.png create mode 100644 docs/_static/images/dual-hub-DMVPN.png create mode 100644 docs/_static/images/eve-ng-vyos.png create mode 100644 docs/_static/images/firewall-and-vrf-blueprints.png create mode 100644 docs/_static/images/firewall-bridge-forward.png create mode 100644 docs/_static/images/firewall-bridge-input.png create mode 100644 docs/_static/images/firewall-bridge-output.png create mode 100644 docs/_static/images/firewall-flowtable-packet-flow.png create mode 100644 docs/_static/images/firewall-fwd-packet-flow.png create mode 100644 docs/_static/images/firewall-gral-packet-flow.png create mode 100644 docs/_static/images/firewall-input-packet-flow.png create mode 100644 docs/_static/images/firewall-netfilter.png create mode 100644 docs/_static/images/firewall-traditional.png create mode 100644 docs/_static/images/firewall-zonebased.png create mode 100644 docs/_static/images/gns3-01.png create mode 100644 docs/_static/images/gns3-02.png create mode 100644 docs/_static/images/gns3-03.png create mode 100644 docs/_static/images/gns3-04.png create mode 100644 docs/_static/images/gns3-05.png create mode 100644 docs/_static/images/gns3-06.png create mode 100644 docs/_static/images/gns3-07.png create mode 100644 docs/_static/images/gns3-08.png create mode 100644 docs/_static/images/gns3-09.png create mode 100644 docs/_static/images/gns3-10.png create mode 100644 docs/_static/images/gns3-11.png create mode 100644 docs/_static/images/gns3-12.png create mode 100644 docs/_static/images/gns3-13.png create mode 100644 docs/_static/images/gns3-14.png create mode 100644 docs/_static/images/gns3-15.png create mode 100644 docs/_static/images/gns3-16.png create mode 100644 docs/_static/images/gns3-17.png create mode 100644 docs/_static/images/gns3-20.png create mode 100644 docs/_static/images/gns3-21.png create mode 100644 docs/_static/images/gns3-215.png create mode 100644 docs/_static/images/gns3-22.png create mode 100644 docs/_static/images/gowin-01.png create mode 100644 docs/_static/images/gowin-02.png create mode 100644 docs/_static/images/gowin-03.png create mode 100644 docs/_static/images/gowin-04.png create mode 100644 docs/_static/images/inter-vrf-routing-vrf-lite.png create mode 100644 docs/_static/images/ipsec-vyos-pa.png create mode 100644 docs/_static/images/json.png create mode 100644 docs/_static/images/key.png create mode 100644 docs/_static/images/keypairs.png create mode 100644 docs/_static/images/lac-lns-diagram.jpg create mode 100644 docs/_static/images/lac-lns-winclient.jpg create mode 100644 docs/_static/images/ldapone.png create mode 100644 docs/_static/images/ldaptwo.png create mode 100644 docs/_static/images/mainschema.png create mode 100644 docs/_static/images/multicast-basic.png create mode 100644 docs/_static/images/nat_before_vpn_topology.png create mode 100644 docs/_static/images/nmp1.png create mode 100644 docs/_static/images/nmp2.png create mode 100644 docs/_static/images/nmp3.png create mode 100644 docs/_static/images/nmp4.png create mode 100644 docs/_static/images/nmp5.png create mode 100644 docs/_static/images/nmp6.png create mode 100644 docs/_static/images/nmp7.png create mode 100644 docs/_static/images/openvpn_site2site_diagram.jpg create mode 100644 docs/_static/images/pbr_example_1.png create mode 100644 docs/_static/images/policy-based-ipsec-and-firewall.png create mode 100644 docs/_static/images/pppoe-ipv6-pd-diagram.jpg create mode 100644 docs/_static/images/project.png create mode 100644 docs/_static/images/qos1.png create mode 100644 docs/_static/images/qos10.png create mode 100644 docs/_static/images/qos2.png create mode 100644 docs/_static/images/qos3.png create mode 100644 docs/_static/images/qos4.png create mode 100644 docs/_static/images/qos5.png create mode 100644 docs/_static/images/qos6.png create mode 100644 docs/_static/images/qos7.png create mode 100644 docs/_static/images/qos8.png create mode 100644 docs/_static/images/qos9.png create mode 100644 docs/_static/images/reset-password-step-1.jpg create mode 100644 docs/_static/images/reset-password-step-2.jpg create mode 100644 docs/_static/images/reset-password-step-3.jpg create mode 100644 docs/_static/images/reset-password-step-4.jpg create mode 100644 docs/_static/images/reset-password-step-5.jpg create mode 100644 docs/_static/images/service.png create mode 100644 docs/_static/images/service_conntrack_sync-schema.png create mode 100644 docs/_static/images/service_dhcp-relay01.png create mode 100644 docs/_static/images/service_dhcpv6-relay01.png create mode 100644 docs/_static/images/service_snmp_communication_principles_diagram.png create mode 100644 docs/_static/images/sg.png create mode 100644 docs/_static/images/sticky-connections.jpg create mode 100644 docs/_static/images/traffic.png create mode 100644 docs/_static/images/uefi_secureboot_01.png create mode 100644 docs/_static/images/uefi_secureboot_02.png create mode 100644 docs/_static/images/uefi_secureboot_03.png create mode 100644 docs/_static/images/uefi_secureboot_04.png create mode 100644 docs/_static/images/uefi_secureboot_05.png create mode 100644 docs/_static/images/uefi_secureboot_06.png create mode 100644 docs/_static/images/uefi_secureboot_07.png create mode 100644 docs/_static/images/virt-libvirt-01.png create mode 100644 docs/_static/images/virt-libvirt-02.png create mode 100644 docs/_static/images/virt-libvirt-03.png create mode 100644 docs/_static/images/virt-libvirt-04.png create mode 100644 docs/_static/images/virt-libvirt-05.png create mode 100644 docs/_static/images/virt-libvirt-06.png create mode 100644 docs/_static/images/virt-libvirt-qc-01.png create mode 100644 docs/_static/images/virt-libvirt-qc-02.png create mode 100644 docs/_static/images/virt-libvirt-qc-03.png create mode 100644 docs/_static/images/vpn_dmvpn_topology01.png create mode 100644 docs/_static/images/vpn_s2s_ikev2.png create mode 100644 docs/_static/images/vpn_s2s_ikev2_c.png create mode 100644 docs/_static/images/vrf-example-topology-01.png create mode 100644 docs/_static/images/vyos-downloads.png create mode 100644 docs/_static/images/vyos-sr-isis.png create mode 100644 docs/_static/images/vyos_1_4_nat66_simple.png create mode 100644 docs/_static/images/vyos_1_5_nat66_dhcpv6_wdummy.png create mode 100644 docs/_static/images/vyos_arista_bond_lacp.png create mode 100644 docs/_static/images/vyosnew-downloads.png create mode 100644 docs/_static/images/wireguard_qrcode.jpg create mode 100644 docs/_static/images/wireguard_site2site_diagram.jpg create mode 100644 docs/_static/images/zone-policy-diagram.png delete mode 100644 docs/_swap.txt delete mode 100644 docs/automation/md-cloud-init.md delete mode 100644 docs/automation/md-command-scripting.md delete mode 100644 docs/automation/md-index.md delete mode 100644 docs/automation/md-vyos-ansible.md delete mode 100644 docs/automation/md-vyos-api.md delete mode 100644 docs/automation/md-vyos-govyos.md delete mode 100644 docs/automation/md-vyos-napalm.md delete mode 100644 docs/automation/md-vyos-netmiko.md delete mode 100644 docs/automation/md-vyos-pyvyos.md delete mode 100644 docs/automation/md-vyos-salt.md delete mode 100644 docs/automation/terraform/md-index.md delete mode 100644 docs/automation/terraform/md-terraformAWS.md delete mode 100644 docs/automation/terraform/md-terraformAZ.md delete mode 100644 docs/automation/terraform/md-terraformGoogle.md delete mode 100644 docs/automation/terraform/md-terraformvSphere.md delete mode 100644 docs/automation/terraform/terraformvyos.md create mode 100644 docs/configexamples/autotest/DHCPRelay_through_GRE/_include/topology.png delete mode 100644 docs/configexamples/autotest/DHCPRelay_through_GRE/md-DHCPRelay_through_GRE.md create mode 100644 docs/configexamples/autotest/L3VPN_EVPN/_include/topology.png delete mode 100644 docs/configexamples/autotest/L3VPN_EVPN/md-L3VPN_EVPN.md create mode 100644 docs/configexamples/autotest/OpenVPN_with_LDAP/_include/topology.png delete mode 100644 docs/configexamples/autotest/OpenVPN_with_LDAP/md-OpenVPN_with_LDAP.md create mode 100644 docs/configexamples/autotest/Wireguard/_include/topology.png delete mode 100644 docs/configexamples/autotest/Wireguard/md-Wireguard.md create mode 100644 docs/configexamples/autotest/tunnelbroker/_include/topology.png delete mode 100644 docs/configexamples/autotest/tunnelbroker/md-tunnelbroker.md delete mode 100644 docs/configexamples/md-ansible.md delete mode 100644 docs/configexamples/md-azure-vpn-bgp.md delete mode 100644 docs/configexamples/md-azure-vpn-dual-bgp.md delete mode 100644 docs/configexamples/md-bgp-ipv6-unnumbered.md delete mode 100644 docs/configexamples/md-dmvpn-dualhub-dualcloud.md delete mode 100644 docs/configexamples/md-firewall.md delete mode 100644 docs/configexamples/md-fwall-and-bridge.md delete mode 100644 docs/configexamples/md-fwall-and-vrf.md delete mode 100644 docs/configexamples/md-ha.md delete mode 100644 docs/configexamples/md-index.md delete mode 100644 docs/configexamples/md-inter-vrf-routing-vrf-lite.md delete mode 100644 docs/configexamples/md-ipsec-cisco-policy-based.md delete mode 100644 docs/configexamples/md-ipsec-cisco-route-based.md delete mode 100644 docs/configexamples/md-ipsec-pa-route-based.md delete mode 100644 docs/configexamples/md-l3vpn-hub-and-spoke.md delete mode 100644 docs/configexamples/md-lac-lns.md delete mode 100644 docs/configexamples/md-nmp.md delete mode 100644 docs/configexamples/md-ospf-unnumbered.md delete mode 100644 docs/configexamples/md-policy-based-ipsec-and-firewall.md delete mode 100644 docs/configexamples/md-pppoe-ipv6-basic.md delete mode 100644 docs/configexamples/md-qos.md delete mode 100644 docs/configexamples/md-segment-routing-isis.md delete mode 100644 docs/configexamples/md-site-2-site-cisco.md delete mode 100644 docs/configexamples/md-wan-load-balancing.md delete mode 100644 docs/configexamples/md-zone-policy.md delete mode 100644 docs/configuration/container/md-index.md delete mode 100644 docs/configuration/firewall/md-bridge.md delete mode 100644 docs/configuration/firewall/md-flowtables.md delete mode 100644 docs/configuration/firewall/md-global-options.md delete mode 100644 docs/configuration/firewall/md-groups.md delete mode 100644 docs/configuration/firewall/md-index.md delete mode 100644 docs/configuration/firewall/md-ipv4.md delete mode 100644 docs/configuration/firewall/md-ipv6.md delete mode 100644 docs/configuration/firewall/md-zone.md delete mode 100644 docs/configuration/highavailability/md-index.md delete mode 100644 docs/configuration/interfaces/md-bonding.md delete mode 100644 docs/configuration/interfaces/md-bridge.md delete mode 100644 docs/configuration/interfaces/md-dummy.md delete mode 100644 docs/configuration/interfaces/md-ethernet.md delete mode 100644 docs/configuration/interfaces/md-geneve.md delete mode 100644 docs/configuration/interfaces/md-index.md delete mode 100644 docs/configuration/interfaces/md-l2tpv3.md delete mode 100644 docs/configuration/interfaces/md-loopback.md delete mode 100644 docs/configuration/interfaces/md-macsec.md delete mode 100644 docs/configuration/interfaces/md-openvpn-examples.md delete mode 100644 docs/configuration/interfaces/md-openvpn.md delete mode 100644 docs/configuration/interfaces/md-pppoe.md delete mode 100644 docs/configuration/interfaces/md-pseudo-ethernet.md delete mode 100644 docs/configuration/interfaces/md-sstp-client.md delete mode 100644 docs/configuration/interfaces/md-tunnel.md delete mode 100644 docs/configuration/interfaces/md-virtual-ethernet.md delete mode 100644 docs/configuration/interfaces/md-vti.md delete mode 100644 docs/configuration/interfaces/md-vxlan.md delete mode 100644 docs/configuration/interfaces/md-wireguard.md delete mode 100644 docs/configuration/interfaces/md-wireless.md delete mode 100644 docs/configuration/interfaces/md-wwan.md delete mode 100644 docs/configuration/loadbalancing/md-haproxy.md delete mode 100644 docs/configuration/loadbalancing/md-index.md delete mode 100644 docs/configuration/loadbalancing/md-wan.md delete mode 100644 docs/configuration/md-index.md delete mode 100644 docs/configuration/nat/md-cgnat.md delete mode 100644 docs/configuration/nat/md-index.md delete mode 100644 docs/configuration/nat/md-nat44.md delete mode 100644 docs/configuration/nat/md-nat64.md delete mode 100644 docs/configuration/nat/md-nat66.md delete mode 100644 docs/configuration/pki/md-index.md delete mode 100644 docs/configuration/policy/md-access-list.md delete mode 100644 docs/configuration/policy/md-as-path-list.md delete mode 100644 docs/configuration/policy/md-community-list.md delete mode 100644 docs/configuration/policy/md-examples.md delete mode 100644 docs/configuration/policy/md-extcommunity-list.md delete mode 100644 docs/configuration/policy/md-index.md delete mode 100644 docs/configuration/policy/md-large-community-list.md delete mode 100644 docs/configuration/policy/md-local-route.md delete mode 100644 docs/configuration/policy/md-prefix-list.md delete mode 100644 docs/configuration/policy/md-route-map.md delete mode 100644 docs/configuration/policy/md-route.md delete mode 100644 docs/configuration/protocols/md-arp.md delete mode 100644 docs/configuration/protocols/md-babel.md delete mode 100644 docs/configuration/protocols/md-bfd.md delete mode 100644 docs/configuration/protocols/md-bgp.md delete mode 100644 docs/configuration/protocols/md-failover.md delete mode 100644 docs/configuration/protocols/md-igmp-proxy.md delete mode 100644 docs/configuration/protocols/md-index.md delete mode 100644 docs/configuration/protocols/md-isis.md delete mode 100644 docs/configuration/protocols/md-mpls.md delete mode 100644 docs/configuration/protocols/md-multicast.md delete mode 100644 docs/configuration/protocols/md-openfabric.md delete mode 100644 docs/configuration/protocols/md-ospf.md delete mode 100644 docs/configuration/protocols/md-pim.md delete mode 100644 docs/configuration/protocols/md-pim6.md delete mode 100644 docs/configuration/protocols/md-rip.md delete mode 100644 docs/configuration/protocols/md-rpki.md delete mode 100644 docs/configuration/protocols/md-segment-routing.md delete mode 100644 docs/configuration/protocols/md-static.md delete mode 100644 docs/configuration/protocols/md-traffic-engineering.md delete mode 100644 docs/configuration/service/md-broadcast-relay.md delete mode 100644 docs/configuration/service/md-config-sync.md delete mode 100644 docs/configuration/service/md-conntrack-sync.md delete mode 100644 docs/configuration/service/md-console-server.md delete mode 100644 docs/configuration/service/md-dhcp-relay.md delete mode 100644 docs/configuration/service/md-dhcp-server.md delete mode 100644 docs/configuration/service/md-dns.md delete mode 100644 docs/configuration/service/md-eventhandler.md delete mode 100644 docs/configuration/service/md-https.md delete mode 100644 docs/configuration/service/md-index.md delete mode 100644 docs/configuration/service/md-ipoe-server.md delete mode 100644 docs/configuration/service/md-lldp.md delete mode 100644 docs/configuration/service/md-mdns.md delete mode 100644 docs/configuration/service/md-monitoring.md delete mode 100644 docs/configuration/service/md-ntp.md delete mode 100644 docs/configuration/service/md-pppoe-server.md delete mode 100644 docs/configuration/service/md-router-advert.md delete mode 100644 docs/configuration/service/md-salt-minion.md delete mode 100644 docs/configuration/service/md-snmp.md delete mode 100644 docs/configuration/service/md-ssh.md delete mode 100644 docs/configuration/service/md-suricata.md delete mode 100644 docs/configuration/service/md-tftp-server.md delete mode 100644 docs/configuration/service/md-webproxy.md delete mode 100644 docs/configuration/system/md-acceleration.md delete mode 100644 docs/configuration/system/md-conntrack.md delete mode 100644 docs/configuration/system/md-console.md delete mode 100644 docs/configuration/system/md-default-route.md delete mode 100644 docs/configuration/system/md-flow-accounting.md delete mode 100644 docs/configuration/system/md-frr.md delete mode 100644 docs/configuration/system/md-host-name.md delete mode 100644 docs/configuration/system/md-index.md delete mode 100644 docs/configuration/system/md-ip.md delete mode 100644 docs/configuration/system/md-ipv6.md delete mode 100644 docs/configuration/system/md-lcd.md delete mode 100644 docs/configuration/system/md-login.md delete mode 100644 docs/configuration/system/md-name-server.md delete mode 100644 docs/configuration/system/md-option.md delete mode 100644 docs/configuration/system/md-proxy.md delete mode 100644 docs/configuration/system/md-sflow.md delete mode 100644 docs/configuration/system/md-sysctl.md delete mode 100644 docs/configuration/system/md-syslog.md delete mode 100644 docs/configuration/system/md-task-scheduler.md delete mode 100644 docs/configuration/system/md-time-zone.md delete mode 100644 docs/configuration/system/md-updates.md delete mode 100644 docs/configuration/system/md-watchdog.md delete mode 100644 docs/configuration/trafficpolicy/md-index.md delete mode 100644 docs/configuration/vpn/ipsec/md-index.md delete mode 100644 docs/configuration/vpn/ipsec/md-ipsec_general.md delete mode 100644 docs/configuration/vpn/ipsec/md-remoteaccess_ipsec.md delete mode 100644 docs/configuration/vpn/ipsec/md-site2site_ipsec.md delete mode 100644 docs/configuration/vpn/ipsec/md-troubleshooting_ipsec.md delete mode 100644 docs/configuration/vpn/md-dmvpn.md delete mode 100644 docs/configuration/vpn/md-index.md delete mode 100644 docs/configuration/vpn/md-l2tp.md delete mode 100644 docs/configuration/vpn/md-openconnect.md delete mode 100644 docs/configuration/vpn/md-pptp.md delete mode 100644 docs/configuration/vpn/md-rsa-keys.md delete mode 100644 docs/configuration/vpn/md-sstp.md delete mode 100644 docs/configuration/vrf/md-index.md delete mode 100644 docs/contributing/md-build-vyos.md delete mode 100644 docs/contributing/md-cla.md delete mode 100644 docs/contributing/md-debugging.md delete mode 100644 docs/contributing/md-development.md delete mode 100644 docs/contributing/md-index.md delete mode 100644 docs/contributing/md-issues-features.md delete mode 100644 docs/contributing/md-testing.md delete mode 100644 docs/contributing/md-upstream-packages.md delete mode 100644 docs/installation/cloud/md-aws.md delete mode 100644 docs/installation/cloud/md-azure.md delete mode 100644 docs/installation/cloud/md-gcp.md delete mode 100644 docs/installation/cloud/md-index.md delete mode 100644 docs/installation/cloud/md-oracle.md delete mode 100644 docs/installation/md-bare-metal.md delete mode 100644 docs/installation/md-image.md delete mode 100644 docs/installation/md-index.md delete mode 100644 docs/installation/md-install.md delete mode 100644 docs/installation/md-secure-boot.md delete mode 100644 docs/installation/md-update.md delete mode 100644 docs/installation/virtual/md-docker.md delete mode 100644 docs/installation/virtual/md-eve-ng.md delete mode 100644 docs/installation/virtual/md-gns3.md delete mode 100644 docs/installation/virtual/md-index.md delete mode 100644 docs/installation/virtual/md-libvirt.md delete mode 100644 docs/installation/virtual/md-proxmox.md delete mode 100644 docs/installation/virtual/md-vmware.md delete mode 100644 docs/introducing/md-about.md delete mode 100644 docs/introducing/md-history.md delete mode 100644 docs/md-404.md delete mode 100644 docs/md-cli.md delete mode 100644 docs/md-coverage.md delete mode 100644 docs/md-documentation.md delete mode 100644 docs/md-index.md delete mode 100644 docs/md-quick-start.md delete mode 100644 docs/operation/md-boot-options.md delete mode 100644 docs/operation/md-index.md delete mode 100644 docs/operation/md-information.md delete mode 100644 docs/operation/md-password-recovery.md delete mode 100644 docs/operation/md-raid.md delete mode 100644 docs/operation/md-upgrade-recovery.md delete mode 100644 docs/troubleshooting/md-connectivity.md delete mode 100644 docs/troubleshooting/md-index.md delete mode 100644 docs/troubleshooting/md-interfaces.md delete mode 100644 docs/troubleshooting/md-monitoring.md delete mode 100644 docs/troubleshooting/md-system.md delete mode 100644 docs/troubleshooting/md-terminal.md delete mode 100644 docs/vpp/configuration/dataplane/md-buffers.md delete mode 100644 docs/vpp/configuration/dataplane/md-cpu.md delete mode 100644 docs/vpp/configuration/dataplane/md-index.md delete mode 100644 docs/vpp/configuration/dataplane/md-interface.md delete mode 100644 docs/vpp/configuration/dataplane/md-ipsec.md delete mode 100644 docs/vpp/configuration/dataplane/md-ipv6.md delete mode 100644 docs/vpp/configuration/dataplane/md-l2learn.md delete mode 100644 docs/vpp/configuration/dataplane/md-lcp.md delete mode 100644 docs/vpp/configuration/dataplane/md-logging.md delete mode 100644 docs/vpp/configuration/dataplane/md-memory.md delete mode 100644 docs/vpp/configuration/dataplane/md-system.md delete mode 100644 docs/vpp/configuration/dataplane/md-unix.md delete mode 100644 docs/vpp/configuration/interfaces/md-bonding.md delete mode 100644 docs/vpp/configuration/interfaces/md-bridge.md delete mode 100644 docs/vpp/configuration/interfaces/md-gre.md delete mode 100644 docs/vpp/configuration/interfaces/md-index.md delete mode 100644 docs/vpp/configuration/interfaces/md-ipip.md delete mode 100644 docs/vpp/configuration/interfaces/md-loopback.md delete mode 100644 docs/vpp/configuration/interfaces/md-vxlan.md delete mode 100644 docs/vpp/configuration/interfaces/md-xconnect.md delete mode 100644 docs/vpp/configuration/md-acl.md delete mode 100644 docs/vpp/configuration/md-index.md delete mode 100644 docs/vpp/configuration/md-ipfix.md delete mode 100644 docs/vpp/configuration/md-ipsec.md delete mode 100644 docs/vpp/configuration/md-sflow.md delete mode 100644 docs/vpp/configuration/nat/md-cgnat.md delete mode 100644 docs/vpp/configuration/nat/md-index.md delete mode 100644 docs/vpp/configuration/nat/md-nat44.md delete mode 100644 docs/vpp/md-description.md delete mode 100644 docs/vpp/md-index.md delete mode 100644 docs/vpp/md-limitations.md delete mode 100644 docs/vpp/md-requirements.md delete mode 100644 docs/vpp/md-troubleshooting.md (limited to 'docs') diff --git a/docs/Makefile b/docs/Makefile index ae12b802..cb6226af 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -12,44 +12,22 @@ AUTOHOST = 0.0.0.0 AUTOPORT = 8000 AUTOOPTS = --watch . -SWAP = python3 ../scripts/swap_sources.py - # Put it first so that "make" without argument is like "make help". help: @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) -.PHONY: help Makefile swap restore html dirhtml pdf livehtml defaultvalue - -swap: - $(SWAP) --swap - -restore: - $(SWAP) --restore - -html: swap - @trap '$(SWAP) --restore' EXIT; \ - $(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) - -dirhtml: swap - @trap '$(SWAP) --restore' EXIT; \ - $(SPHINXBUILD) -M dirhtml "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) - -pdf: swap - @trap '$(SWAP) --restore' EXIT; \ - $(SPHINXBUILD) -M latexpdf "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) - -livehtml: swap - @trap '$(SWAP) --restore' EXIT; \ - sphinx-autobuild --host $(AUTOHOST) --port $(AUTOPORT) \ - --ignore '$(BUILDDIR)/**' \ - --ignore '**/_build/**' \ - --ignore '**/md-*' \ - "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) - -defaultvalue: export VYOS_DEFAULT=True -defaultvalue: html +.PHONY: help Makefile # Catch-all target: route all unknown targets to Sphinx using the new # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). %: Makefile @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +livehtml: + sphinx-autobuild --host $(AUTOHOST) --port $(AUTOPORT) $(AUTOOPTS) \ + "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + + +defaultvalue: export VYOS_DEFAULT=True +defaultvalue: + @$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) \ No newline at end of file diff --git a/docs/_ext/vyos.py b/docs/_ext/vyos.py index 527178d1..2f4dede9 100644 --- a/docs/_ext/vyos.py +++ b/docs/_ext/vyos.py @@ -364,18 +364,8 @@ class CmdInclude(SphinxDirective): line = re.sub('{{\s?var' + str(i) + '\s?}}',value,line) new_include_lines.append(line) - if hasattr(self.state, '_renderer'): - self.state._renderer.nested_render_text(''.join(new_include_lines), self.lineno) - return [] - from docutils.statemachine import ViewList - from docutils import nodes - content = ''.join(new_include_lines) - vl = ViewList() - for i, line in enumerate(content.splitlines(keepends=False)): - vl.append(line, include_file[1], i) - node = nodes.Element() - self.state.nested_parse(vl, self.content_offset, node, match_titles=True) - return node.children + self.state._renderer.nested_render_text(''.join(new_include_lines), self.lineno) + return [] class CfgcmdlistDirective(Directive): diff --git a/docs/_static/images/1u_vyos_back.jpg b/docs/_static/images/1u_vyos_back.jpg new file mode 100644 index 00000000..cd00c11c Binary files /dev/null and b/docs/_static/images/1u_vyos_back.jpg differ diff --git a/docs/_static/images/1u_vyos_front.jpg b/docs/_static/images/1u_vyos_front.jpg new file mode 100644 index 00000000..3d135d56 Binary files /dev/null and b/docs/_static/images/1u_vyos_front.jpg differ diff --git a/docs/_static/images/1u_vyos_front_10ge_open_1.jpg b/docs/_static/images/1u_vyos_front_10ge_open_1.jpg new file mode 100644 index 00000000..edfba5a3 Binary files /dev/null and b/docs/_static/images/1u_vyos_front_10ge_open_1.jpg differ diff --git a/docs/_static/images/1u_vyos_front_10ge_open_2.jpg b/docs/_static/images/1u_vyos_front_10ge_open_2.jpg new file mode 100644 index 00000000..4f48a116 Binary files /dev/null and b/docs/_static/images/1u_vyos_front_10ge_open_2.jpg differ diff --git a/docs/_static/images/1u_vyos_front_10ge_open_3.jpg b/docs/_static/images/1u_vyos_front_10ge_open_3.jpg new file mode 100644 index 00000000..c102b903 Binary files /dev/null and b/docs/_static/images/1u_vyos_front_10ge_open_3.jpg differ diff --git a/docs/_static/images/1u_vyos_front_10ge_open_4.jpg b/docs/_static/images/1u_vyos_front_10ge_open_4.jpg new file mode 100644 index 00000000..2f270b7e Binary files /dev/null and b/docs/_static/images/1u_vyos_front_10ge_open_4.jpg differ diff --git a/docs/_static/images/1u_vyos_front_open_1.jpg b/docs/_static/images/1u_vyos_front_open_1.jpg new file mode 100644 index 00000000..d90d565e Binary files /dev/null and b/docs/_static/images/1u_vyos_front_open_1.jpg differ diff --git a/docs/_static/images/1u_vyos_front_open_2.jpg b/docs/_static/images/1u_vyos_front_open_2.jpg new file mode 100644 index 00000000..6d112463 Binary files /dev/null and b/docs/_static/images/1u_vyos_front_open_2.jpg differ diff --git a/docs/_static/images/1u_vyos_front_open_3.jpg b/docs/_static/images/1u_vyos_front_open_3.jpg new file mode 100644 index 00000000..198ba3ce Binary files /dev/null and b/docs/_static/images/1u_vyos_front_open_3.jpg differ diff --git a/docs/_static/images/480px-Acrosser_ANDJ190N1_Back.jpg b/docs/_static/images/480px-Acrosser_ANDJ190N1_Back.jpg new file mode 100644 index 00000000..6441c54a Binary files /dev/null and b/docs/_static/images/480px-Acrosser_ANDJ190N1_Back.jpg differ diff --git a/docs/_static/images/480px-Acrosser_ANDJ190N1_Front.jpg b/docs/_static/images/480px-Acrosser_ANDJ190N1_Front.jpg new file mode 100644 index 00000000..5f216aa1 Binary files /dev/null and b/docs/_static/images/480px-Acrosser_ANDJ190N1_Front.jpg differ diff --git a/docs/_static/images/600px-Partaker-i5.jpg b/docs/_static/images/600px-Partaker-i5.jpg new file mode 100644 index 00000000..68196d41 Binary files /dev/null and b/docs/_static/images/600px-Partaker-i5.jpg differ diff --git a/docs/_static/images/ESP_AH.png b/docs/_static/images/ESP_AH.png new file mode 100644 index 00000000..6075c3f4 Binary files /dev/null and b/docs/_static/images/ESP_AH.png differ diff --git a/docs/_static/images/IPSec_close_action_settings.png b/docs/_static/images/IPSec_close_action_settings.png new file mode 100644 index 00000000..531643f7 Binary files /dev/null and b/docs/_static/images/IPSec_close_action_settings.png differ diff --git a/docs/_static/images/L3VPN_hub_and_spoke.png b/docs/_static/images/L3VPN_hub_and_spoke.png new file mode 100644 index 00000000..d442cc1a Binary files /dev/null and b/docs/_static/images/L3VPN_hub_and_spoke.png differ diff --git a/docs/_static/images/PA-ESP-group.png b/docs/_static/images/PA-ESP-group.png new file mode 100644 index 00000000..c6411b66 Binary files /dev/null and b/docs/_static/images/PA-ESP-group.png differ diff --git a/docs/_static/images/PA-IKE-GW-1.png b/docs/_static/images/PA-IKE-GW-1.png new file mode 100644 index 00000000..863eeb3a Binary files /dev/null and b/docs/_static/images/PA-IKE-GW-1.png differ diff --git a/docs/_static/images/PA-IKE-GW-2.png b/docs/_static/images/PA-IKE-GW-2.png new file mode 100644 index 00000000..21a16055 Binary files /dev/null and b/docs/_static/images/PA-IKE-GW-2.png differ diff --git a/docs/_static/images/PA-IKE-group.png b/docs/_static/images/PA-IKE-group.png new file mode 100644 index 00000000..06fd535d Binary files /dev/null and b/docs/_static/images/PA-IKE-group.png differ diff --git a/docs/_static/images/PA-IPsec-tunnel.png b/docs/_static/images/PA-IPsec-tunnel.png new file mode 100644 index 00000000..2f8f4cb8 Binary files /dev/null and b/docs/_static/images/PA-IPsec-tunnel.png differ diff --git a/docs/_static/images/PA-tunnel-1.png b/docs/_static/images/PA-tunnel-1.png new file mode 100644 index 00000000..3c99c6c7 Binary files /dev/null and b/docs/_static/images/PA-tunnel-1.png differ diff --git a/docs/_static/images/PA-tunnel-2.png b/docs/_static/images/PA-tunnel-2.png new file mode 100644 index 00000000..6f073513 Binary files /dev/null and b/docs/_static/images/PA-tunnel-2.png differ diff --git a/docs/_static/images/PA-tunnel-3.png b/docs/_static/images/PA-tunnel-3.png new file mode 100644 index 00000000..ca5a94e9 Binary files /dev/null and b/docs/_static/images/PA-tunnel-3.png differ diff --git a/docs/_static/images/VyOS_Dual-Hub_DMVPN.png b/docs/_static/images/VyOS_Dual-Hub_DMVPN.png new file mode 100644 index 00000000..9c25a308 Binary files /dev/null and b/docs/_static/images/VyOS_Dual-Hub_DMVPN.png differ diff --git a/docs/_static/images/Wan_load_balancing1.png b/docs/_static/images/Wan_load_balancing1.png new file mode 100644 index 00000000..bde1edb6 Binary files /dev/null and b/docs/_static/images/Wan_load_balancing1.png differ diff --git a/docs/_static/images/Wan_load_balancing_exclude1.png b/docs/_static/images/Wan_load_balancing_exclude1.png new file mode 100644 index 00000000..1111535d Binary files /dev/null and b/docs/_static/images/Wan_load_balancing_exclude1.png differ diff --git a/docs/_static/images/ansible.png b/docs/_static/images/ansible.png new file mode 100644 index 00000000..1d80b3f4 Binary files /dev/null and b/docs/_static/images/ansible.png differ diff --git a/docs/_static/images/apu4_desk_1.jpg b/docs/_static/images/apu4_desk_1.jpg new file mode 100644 index 00000000..b7a3d08e Binary files /dev/null and b/docs/_static/images/apu4_desk_1.jpg differ diff --git a/docs/_static/images/apu4_desk_2.jpg b/docs/_static/images/apu4_desk_2.jpg new file mode 100644 index 00000000..fe356e1f Binary files /dev/null and b/docs/_static/images/apu4_desk_2.jpg differ diff --git a/docs/_static/images/apu4_desk_3.jpg b/docs/_static/images/apu4_desk_3.jpg new file mode 100644 index 00000000..af7dc406 Binary files /dev/null and b/docs/_static/images/apu4_desk_3.jpg differ diff --git a/docs/_static/images/apu4_desk_4.jpg b/docs/_static/images/apu4_desk_4.jpg new file mode 100644 index 00000000..37251af2 Binary files /dev/null and b/docs/_static/images/apu4_desk_4.jpg differ diff --git a/docs/_static/images/apu4_rack_1.jpg b/docs/_static/images/apu4_rack_1.jpg new file mode 100644 index 00000000..3793cd39 Binary files /dev/null and b/docs/_static/images/apu4_rack_1.jpg differ diff --git a/docs/_static/images/apu4_rack_2.jpg b/docs/_static/images/apu4_rack_2.jpg new file mode 100644 index 00000000..b8caf976 Binary files /dev/null and b/docs/_static/images/apu4_rack_2.jpg differ diff --git a/docs/_static/images/apu4_rack_3.jpg b/docs/_static/images/apu4_rack_3.jpg new file mode 100644 index 00000000..08ff633e Binary files /dev/null and b/docs/_static/images/apu4_rack_3.jpg differ diff --git a/docs/_static/images/apu4_rack_4.jpg b/docs/_static/images/apu4_rack_4.jpg new file mode 100644 index 00000000..a88d62fe Binary files /dev/null and b/docs/_static/images/apu4_rack_4.jpg differ diff --git a/docs/_static/images/apu4_rack_5.jpg b/docs/_static/images/apu4_rack_5.jpg new file mode 100644 index 00000000..644b8e0a Binary files /dev/null and b/docs/_static/images/apu4_rack_5.jpg differ diff --git a/docs/_static/images/apu4_rack_vyos_print.jpg b/docs/_static/images/apu4_rack_vyos_print.jpg new file mode 100644 index 00000000..a0bbaab2 Binary files /dev/null and b/docs/_static/images/apu4_rack_vyos_print.jpg differ diff --git a/docs/_static/images/aws.png b/docs/_static/images/aws.png new file mode 100644 index 00000000..c1c111bb Binary files /dev/null and b/docs/_static/images/aws.png differ diff --git a/docs/_static/images/blueprint-dmvpn.png b/docs/_static/images/blueprint-dmvpn.png new file mode 100644 index 00000000..85f189c1 Binary files /dev/null and b/docs/_static/images/blueprint-dmvpn.png differ diff --git a/docs/_static/images/boot-options.png b/docs/_static/images/boot-options.png new file mode 100644 index 00000000..b00350bc Binary files /dev/null and b/docs/_static/images/boot-options.png differ diff --git a/docs/_static/images/cisco-vpn-ipsec.png b/docs/_static/images/cisco-vpn-ipsec.png new file mode 100644 index 00000000..bc19e8bc Binary files /dev/null and b/docs/_static/images/cisco-vpn-ipsec.png differ diff --git a/docs/_static/images/cloud-aws-01.png b/docs/_static/images/cloud-aws-01.png new file mode 100644 index 00000000..cda6542f Binary files /dev/null and b/docs/_static/images/cloud-aws-01.png differ diff --git a/docs/_static/images/cloud-aws-02.png b/docs/_static/images/cloud-aws-02.png new file mode 100644 index 00000000..639d42fa Binary files /dev/null and b/docs/_static/images/cloud-aws-02.png differ diff --git a/docs/_static/images/cloud-aws-03.png b/docs/_static/images/cloud-aws-03.png new file mode 100644 index 00000000..92d3e63b Binary files /dev/null and b/docs/_static/images/cloud-aws-03.png differ diff --git a/docs/_static/images/cloud-aws-04.png b/docs/_static/images/cloud-aws-04.png new file mode 100644 index 00000000..3ae4fb2a Binary files /dev/null and b/docs/_static/images/cloud-aws-04.png differ diff --git a/docs/_static/images/cloud-aws-05.png b/docs/_static/images/cloud-aws-05.png new file mode 100644 index 00000000..fa3521a6 Binary files /dev/null and b/docs/_static/images/cloud-aws-05.png differ diff --git a/docs/_static/images/cloud-aws-06.png b/docs/_static/images/cloud-aws-06.png new file mode 100644 index 00000000..c8f88ded Binary files /dev/null and b/docs/_static/images/cloud-aws-06.png differ diff --git a/docs/_static/images/cloud-aws-07.png b/docs/_static/images/cloud-aws-07.png new file mode 100644 index 00000000..d9f934ac Binary files /dev/null and b/docs/_static/images/cloud-aws-07.png differ diff --git a/docs/_static/images/cloud-aws-08.png b/docs/_static/images/cloud-aws-08.png new file mode 100644 index 00000000..db3030a0 Binary files /dev/null and b/docs/_static/images/cloud-aws-08.png differ diff --git a/docs/_static/images/cloud-azure-01.png b/docs/_static/images/cloud-azure-01.png new file mode 100644 index 00000000..2c7b1adb Binary files /dev/null and b/docs/_static/images/cloud-azure-01.png differ diff --git a/docs/_static/images/cloud-azure-02.png b/docs/_static/images/cloud-azure-02.png new file mode 100644 index 00000000..286b8689 Binary files /dev/null and b/docs/_static/images/cloud-azure-02.png differ diff --git a/docs/_static/images/cloud-azure-03.png b/docs/_static/images/cloud-azure-03.png new file mode 100644 index 00000000..4661a1fb Binary files /dev/null and b/docs/_static/images/cloud-azure-03.png differ diff --git a/docs/_static/images/cloud-azure-04.png b/docs/_static/images/cloud-azure-04.png new file mode 100644 index 00000000..af12d337 Binary files /dev/null and b/docs/_static/images/cloud-azure-04.png differ diff --git a/docs/_static/images/cloud-azure-05.png b/docs/_static/images/cloud-azure-05.png new file mode 100644 index 00000000..c5a32d2e Binary files /dev/null and b/docs/_static/images/cloud-azure-05.png differ diff --git a/docs/_static/images/cloud-azure-06.png b/docs/_static/images/cloud-azure-06.png new file mode 100644 index 00000000..1cc7cbf1 Binary files /dev/null and b/docs/_static/images/cloud-azure-06.png differ diff --git a/docs/_static/images/cloud-gcp-01.png b/docs/_static/images/cloud-gcp-01.png new file mode 100644 index 00000000..f7681d6e Binary files /dev/null and b/docs/_static/images/cloud-gcp-01.png differ diff --git a/docs/_static/images/cloud-gcp-02.png b/docs/_static/images/cloud-gcp-02.png new file mode 100644 index 00000000..5a17efb4 Binary files /dev/null and b/docs/_static/images/cloud-gcp-02.png differ diff --git a/docs/_static/images/cloud-gcp-03.png b/docs/_static/images/cloud-gcp-03.png new file mode 100644 index 00000000..9881a5a3 Binary files /dev/null and b/docs/_static/images/cloud-gcp-03.png differ diff --git a/docs/_static/images/cloud-gcp-04.png b/docs/_static/images/cloud-gcp-04.png new file mode 100644 index 00000000..61ee2d5e Binary files /dev/null and b/docs/_static/images/cloud-gcp-04.png differ diff --git a/docs/_static/images/cloud-gcp-05.png b/docs/_static/images/cloud-gcp-05.png new file mode 100644 index 00000000..acaafc59 Binary files /dev/null and b/docs/_static/images/cloud-gcp-05.png differ diff --git a/docs/_static/images/dhcp-relay-through-gre-bridge.png b/docs/_static/images/dhcp-relay-through-gre-bridge.png new file mode 100644 index 00000000..1f3e7744 Binary files /dev/null and b/docs/_static/images/dhcp-relay-through-gre-bridge.png differ diff --git a/docs/_static/images/dual-hub-DMVPN.png b/docs/_static/images/dual-hub-DMVPN.png new file mode 100644 index 00000000..51ba9c14 Binary files /dev/null and b/docs/_static/images/dual-hub-DMVPN.png differ diff --git a/docs/_static/images/eve-ng-vyos.png b/docs/_static/images/eve-ng-vyos.png new file mode 100644 index 00000000..fdd196a7 Binary files /dev/null and b/docs/_static/images/eve-ng-vyos.png differ diff --git a/docs/_static/images/firewall-and-vrf-blueprints.png b/docs/_static/images/firewall-and-vrf-blueprints.png new file mode 100644 index 00000000..8c3bf9f2 Binary files /dev/null and b/docs/_static/images/firewall-and-vrf-blueprints.png differ diff --git a/docs/_static/images/firewall-bridge-forward.png b/docs/_static/images/firewall-bridge-forward.png new file mode 100644 index 00000000..1294349b Binary files /dev/null and b/docs/_static/images/firewall-bridge-forward.png differ diff --git a/docs/_static/images/firewall-bridge-input.png b/docs/_static/images/firewall-bridge-input.png new file mode 100644 index 00000000..20a46b2e Binary files /dev/null and b/docs/_static/images/firewall-bridge-input.png differ diff --git a/docs/_static/images/firewall-bridge-output.png b/docs/_static/images/firewall-bridge-output.png new file mode 100644 index 00000000..ab2fd3d7 Binary files /dev/null and b/docs/_static/images/firewall-bridge-output.png differ diff --git a/docs/_static/images/firewall-flowtable-packet-flow.png b/docs/_static/images/firewall-flowtable-packet-flow.png new file mode 100644 index 00000000..fca7e13a Binary files /dev/null and b/docs/_static/images/firewall-flowtable-packet-flow.png differ diff --git a/docs/_static/images/firewall-fwd-packet-flow.png b/docs/_static/images/firewall-fwd-packet-flow.png new file mode 100644 index 00000000..1ca213e8 Binary files /dev/null and b/docs/_static/images/firewall-fwd-packet-flow.png differ diff --git a/docs/_static/images/firewall-gral-packet-flow.png b/docs/_static/images/firewall-gral-packet-flow.png new file mode 100644 index 00000000..4fb5d516 Binary files /dev/null and b/docs/_static/images/firewall-gral-packet-flow.png differ diff --git a/docs/_static/images/firewall-input-packet-flow.png b/docs/_static/images/firewall-input-packet-flow.png new file mode 100644 index 00000000..20d356bd Binary files /dev/null and b/docs/_static/images/firewall-input-packet-flow.png differ diff --git a/docs/_static/images/firewall-netfilter.png b/docs/_static/images/firewall-netfilter.png new file mode 100644 index 00000000..dde3766b Binary files /dev/null and b/docs/_static/images/firewall-netfilter.png differ diff --git a/docs/_static/images/firewall-traditional.png b/docs/_static/images/firewall-traditional.png new file mode 100644 index 00000000..7eb2b49d Binary files /dev/null and b/docs/_static/images/firewall-traditional.png differ diff --git a/docs/_static/images/firewall-zonebased.png b/docs/_static/images/firewall-zonebased.png new file mode 100644 index 00000000..46b2f623 Binary files /dev/null and b/docs/_static/images/firewall-zonebased.png differ diff --git a/docs/_static/images/gns3-01.png b/docs/_static/images/gns3-01.png new file mode 100644 index 00000000..a655d6aa Binary files /dev/null and b/docs/_static/images/gns3-01.png differ diff --git a/docs/_static/images/gns3-02.png b/docs/_static/images/gns3-02.png new file mode 100644 index 00000000..3dffdd2b Binary files /dev/null and b/docs/_static/images/gns3-02.png differ diff --git a/docs/_static/images/gns3-03.png b/docs/_static/images/gns3-03.png new file mode 100644 index 00000000..fcab6c5d Binary files /dev/null and b/docs/_static/images/gns3-03.png differ diff --git a/docs/_static/images/gns3-04.png b/docs/_static/images/gns3-04.png new file mode 100644 index 00000000..afc30131 Binary files /dev/null and b/docs/_static/images/gns3-04.png differ diff --git a/docs/_static/images/gns3-05.png b/docs/_static/images/gns3-05.png new file mode 100644 index 00000000..fee0dc65 Binary files /dev/null and b/docs/_static/images/gns3-05.png differ diff --git a/docs/_static/images/gns3-06.png b/docs/_static/images/gns3-06.png new file mode 100644 index 00000000..c03cd89f Binary files /dev/null and b/docs/_static/images/gns3-06.png differ diff --git a/docs/_static/images/gns3-07.png b/docs/_static/images/gns3-07.png new file mode 100644 index 00000000..89d0a565 Binary files /dev/null and b/docs/_static/images/gns3-07.png differ diff --git a/docs/_static/images/gns3-08.png b/docs/_static/images/gns3-08.png new file mode 100644 index 00000000..aca0ff8a Binary files /dev/null and b/docs/_static/images/gns3-08.png differ diff --git a/docs/_static/images/gns3-09.png b/docs/_static/images/gns3-09.png new file mode 100644 index 00000000..7ae38c30 Binary files /dev/null and b/docs/_static/images/gns3-09.png differ diff --git a/docs/_static/images/gns3-10.png b/docs/_static/images/gns3-10.png new file mode 100644 index 00000000..1ee70d58 Binary files /dev/null and b/docs/_static/images/gns3-10.png differ diff --git a/docs/_static/images/gns3-11.png b/docs/_static/images/gns3-11.png new file mode 100644 index 00000000..7990c73a Binary files /dev/null and b/docs/_static/images/gns3-11.png differ diff --git a/docs/_static/images/gns3-12.png b/docs/_static/images/gns3-12.png new file mode 100644 index 00000000..9ad51f70 Binary files /dev/null and b/docs/_static/images/gns3-12.png differ diff --git a/docs/_static/images/gns3-13.png b/docs/_static/images/gns3-13.png new file mode 100644 index 00000000..5f9dd783 Binary files /dev/null and b/docs/_static/images/gns3-13.png differ diff --git a/docs/_static/images/gns3-14.png b/docs/_static/images/gns3-14.png new file mode 100644 index 00000000..447fcafe Binary files /dev/null and b/docs/_static/images/gns3-14.png differ diff --git a/docs/_static/images/gns3-15.png b/docs/_static/images/gns3-15.png new file mode 100644 index 00000000..956b9edb Binary files /dev/null and b/docs/_static/images/gns3-15.png differ diff --git a/docs/_static/images/gns3-16.png b/docs/_static/images/gns3-16.png new file mode 100644 index 00000000..4f75ffab Binary files /dev/null and b/docs/_static/images/gns3-16.png differ diff --git a/docs/_static/images/gns3-17.png b/docs/_static/images/gns3-17.png new file mode 100644 index 00000000..64eff002 Binary files /dev/null and b/docs/_static/images/gns3-17.png differ diff --git a/docs/_static/images/gns3-20.png b/docs/_static/images/gns3-20.png new file mode 100644 index 00000000..17d92dea Binary files /dev/null and b/docs/_static/images/gns3-20.png differ diff --git a/docs/_static/images/gns3-21.png b/docs/_static/images/gns3-21.png new file mode 100644 index 00000000..e461016a Binary files /dev/null and b/docs/_static/images/gns3-21.png differ diff --git a/docs/_static/images/gns3-215.png b/docs/_static/images/gns3-215.png new file mode 100644 index 00000000..fde268ba Binary files /dev/null and b/docs/_static/images/gns3-215.png differ diff --git a/docs/_static/images/gns3-22.png b/docs/_static/images/gns3-22.png new file mode 100644 index 00000000..6ed52c1d Binary files /dev/null and b/docs/_static/images/gns3-22.png differ diff --git a/docs/_static/images/gowin-01.png b/docs/_static/images/gowin-01.png new file mode 100644 index 00000000..403ce52a Binary files /dev/null and b/docs/_static/images/gowin-01.png differ diff --git a/docs/_static/images/gowin-02.png b/docs/_static/images/gowin-02.png new file mode 100644 index 00000000..413f2948 Binary files /dev/null and b/docs/_static/images/gowin-02.png differ diff --git a/docs/_static/images/gowin-03.png b/docs/_static/images/gowin-03.png new file mode 100644 index 00000000..fbdbb142 Binary files /dev/null and b/docs/_static/images/gowin-03.png differ diff --git a/docs/_static/images/gowin-04.png b/docs/_static/images/gowin-04.png new file mode 100644 index 00000000..c68b8731 Binary files /dev/null and b/docs/_static/images/gowin-04.png differ diff --git a/docs/_static/images/inter-vrf-routing-vrf-lite.png b/docs/_static/images/inter-vrf-routing-vrf-lite.png new file mode 100644 index 00000000..3acefee6 Binary files /dev/null and b/docs/_static/images/inter-vrf-routing-vrf-lite.png differ diff --git a/docs/_static/images/ipsec-vyos-pa.png b/docs/_static/images/ipsec-vyos-pa.png new file mode 100644 index 00000000..0929bcc7 Binary files /dev/null and b/docs/_static/images/ipsec-vyos-pa.png differ diff --git a/docs/_static/images/json.png b/docs/_static/images/json.png new file mode 100644 index 00000000..6c884e8e Binary files /dev/null and b/docs/_static/images/json.png differ diff --git a/docs/_static/images/key.png b/docs/_static/images/key.png new file mode 100644 index 00000000..7d9366f4 Binary files /dev/null and b/docs/_static/images/key.png differ diff --git a/docs/_static/images/keypairs.png b/docs/_static/images/keypairs.png new file mode 100644 index 00000000..7e772ae9 Binary files /dev/null and b/docs/_static/images/keypairs.png differ diff --git a/docs/_static/images/lac-lns-diagram.jpg b/docs/_static/images/lac-lns-diagram.jpg new file mode 100644 index 00000000..4463a3c3 Binary files /dev/null and b/docs/_static/images/lac-lns-diagram.jpg differ diff --git a/docs/_static/images/lac-lns-winclient.jpg b/docs/_static/images/lac-lns-winclient.jpg new file mode 100644 index 00000000..9fa99152 Binary files /dev/null and b/docs/_static/images/lac-lns-winclient.jpg differ diff --git a/docs/_static/images/ldapone.png b/docs/_static/images/ldapone.png new file mode 100644 index 00000000..33ecf628 Binary files /dev/null and b/docs/_static/images/ldapone.png differ diff --git a/docs/_static/images/ldaptwo.png b/docs/_static/images/ldaptwo.png new file mode 100644 index 00000000..7cb9e0cb Binary files /dev/null and b/docs/_static/images/ldaptwo.png differ diff --git a/docs/_static/images/mainschema.png b/docs/_static/images/mainschema.png new file mode 100644 index 00000000..c39e5da2 Binary files /dev/null and b/docs/_static/images/mainschema.png differ diff --git a/docs/_static/images/multicast-basic.png b/docs/_static/images/multicast-basic.png new file mode 100644 index 00000000..3d4a3de3 Binary files /dev/null and b/docs/_static/images/multicast-basic.png differ diff --git a/docs/_static/images/nat_before_vpn_topology.png b/docs/_static/images/nat_before_vpn_topology.png new file mode 100644 index 00000000..ae23c92d Binary files /dev/null and b/docs/_static/images/nat_before_vpn_topology.png differ diff --git a/docs/_static/images/nmp1.png b/docs/_static/images/nmp1.png new file mode 100644 index 00000000..0b761a76 Binary files /dev/null and b/docs/_static/images/nmp1.png differ diff --git a/docs/_static/images/nmp2.png b/docs/_static/images/nmp2.png new file mode 100644 index 00000000..3190a099 Binary files /dev/null and b/docs/_static/images/nmp2.png differ diff --git a/docs/_static/images/nmp3.png b/docs/_static/images/nmp3.png new file mode 100644 index 00000000..0585b80e Binary files /dev/null and b/docs/_static/images/nmp3.png differ diff --git a/docs/_static/images/nmp4.png b/docs/_static/images/nmp4.png new file mode 100644 index 00000000..e0aa893e Binary files /dev/null and b/docs/_static/images/nmp4.png differ diff --git a/docs/_static/images/nmp5.png b/docs/_static/images/nmp5.png new file mode 100644 index 00000000..d3149034 Binary files /dev/null and b/docs/_static/images/nmp5.png differ diff --git a/docs/_static/images/nmp6.png b/docs/_static/images/nmp6.png new file mode 100644 index 00000000..c4645e33 Binary files /dev/null and b/docs/_static/images/nmp6.png differ diff --git a/docs/_static/images/nmp7.png b/docs/_static/images/nmp7.png new file mode 100644 index 00000000..3e518e7e Binary files /dev/null and b/docs/_static/images/nmp7.png differ diff --git a/docs/_static/images/openvpn_site2site_diagram.jpg b/docs/_static/images/openvpn_site2site_diagram.jpg new file mode 100644 index 00000000..05881e7d Binary files /dev/null and b/docs/_static/images/openvpn_site2site_diagram.jpg differ diff --git a/docs/_static/images/pbr_example_1.png b/docs/_static/images/pbr_example_1.png new file mode 100644 index 00000000..3dff6db6 Binary files /dev/null and b/docs/_static/images/pbr_example_1.png differ diff --git a/docs/_static/images/policy-based-ipsec-and-firewall.png b/docs/_static/images/policy-based-ipsec-and-firewall.png new file mode 100644 index 00000000..6e9d43ac Binary files /dev/null and b/docs/_static/images/policy-based-ipsec-and-firewall.png differ diff --git a/docs/_static/images/pppoe-ipv6-pd-diagram.jpg b/docs/_static/images/pppoe-ipv6-pd-diagram.jpg new file mode 100644 index 00000000..430848c8 Binary files /dev/null and b/docs/_static/images/pppoe-ipv6-pd-diagram.jpg differ diff --git a/docs/_static/images/project.png b/docs/_static/images/project.png new file mode 100644 index 00000000..6f844c23 Binary files /dev/null and b/docs/_static/images/project.png differ diff --git a/docs/_static/images/qos1.png b/docs/_static/images/qos1.png new file mode 100644 index 00000000..9c16e6a3 Binary files /dev/null and b/docs/_static/images/qos1.png differ diff --git a/docs/_static/images/qos10.png b/docs/_static/images/qos10.png new file mode 100644 index 00000000..2f90ffe7 Binary files /dev/null and b/docs/_static/images/qos10.png differ diff --git a/docs/_static/images/qos2.png b/docs/_static/images/qos2.png new file mode 100644 index 00000000..4d351344 Binary files /dev/null and b/docs/_static/images/qos2.png differ diff --git a/docs/_static/images/qos3.png b/docs/_static/images/qos3.png new file mode 100644 index 00000000..97efaeb7 Binary files /dev/null and b/docs/_static/images/qos3.png differ diff --git a/docs/_static/images/qos4.png b/docs/_static/images/qos4.png new file mode 100644 index 00000000..b87b256e Binary files /dev/null and b/docs/_static/images/qos4.png differ diff --git a/docs/_static/images/qos5.png b/docs/_static/images/qos5.png new file mode 100644 index 00000000..4a615755 Binary files /dev/null and b/docs/_static/images/qos5.png differ diff --git a/docs/_static/images/qos6.png b/docs/_static/images/qos6.png new file mode 100644 index 00000000..907d6104 Binary files /dev/null and b/docs/_static/images/qos6.png differ diff --git a/docs/_static/images/qos7.png b/docs/_static/images/qos7.png new file mode 100644 index 00000000..03ec5cd1 Binary files /dev/null and b/docs/_static/images/qos7.png differ diff --git a/docs/_static/images/qos8.png b/docs/_static/images/qos8.png new file mode 100644 index 00000000..3566ac00 Binary files /dev/null and b/docs/_static/images/qos8.png differ diff --git a/docs/_static/images/qos9.png b/docs/_static/images/qos9.png new file mode 100644 index 00000000..67d8afd2 Binary files /dev/null and b/docs/_static/images/qos9.png differ diff --git a/docs/_static/images/reset-password-step-1.jpg b/docs/_static/images/reset-password-step-1.jpg new file mode 100644 index 00000000..3b6f7703 Binary files /dev/null and b/docs/_static/images/reset-password-step-1.jpg differ diff --git a/docs/_static/images/reset-password-step-2.jpg b/docs/_static/images/reset-password-step-2.jpg new file mode 100644 index 00000000..265bc73b Binary files /dev/null and b/docs/_static/images/reset-password-step-2.jpg differ diff --git a/docs/_static/images/reset-password-step-3.jpg b/docs/_static/images/reset-password-step-3.jpg new file mode 100644 index 00000000..98795757 Binary files /dev/null and b/docs/_static/images/reset-password-step-3.jpg differ diff --git a/docs/_static/images/reset-password-step-4.jpg b/docs/_static/images/reset-password-step-4.jpg new file mode 100644 index 00000000..6f70ea24 Binary files /dev/null and b/docs/_static/images/reset-password-step-4.jpg differ diff --git a/docs/_static/images/reset-password-step-5.jpg b/docs/_static/images/reset-password-step-5.jpg new file mode 100644 index 00000000..70c586e2 Binary files /dev/null and b/docs/_static/images/reset-password-step-5.jpg differ diff --git a/docs/_static/images/service.png b/docs/_static/images/service.png new file mode 100644 index 00000000..e2a9bbbc Binary files /dev/null and b/docs/_static/images/service.png differ diff --git a/docs/_static/images/service_conntrack_sync-schema.png b/docs/_static/images/service_conntrack_sync-schema.png new file mode 100644 index 00000000..1b5fe8fb Binary files /dev/null and b/docs/_static/images/service_conntrack_sync-schema.png differ diff --git a/docs/_static/images/service_dhcp-relay01.png b/docs/_static/images/service_dhcp-relay01.png new file mode 100644 index 00000000..cd7f30cf Binary files /dev/null and b/docs/_static/images/service_dhcp-relay01.png differ diff --git a/docs/_static/images/service_dhcpv6-relay01.png b/docs/_static/images/service_dhcpv6-relay01.png new file mode 100644 index 00000000..9a10a10f Binary files /dev/null and b/docs/_static/images/service_dhcpv6-relay01.png differ diff --git a/docs/_static/images/service_snmp_communication_principles_diagram.png b/docs/_static/images/service_snmp_communication_principles_diagram.png new file mode 100644 index 00000000..eff2ce45 Binary files /dev/null and b/docs/_static/images/service_snmp_communication_principles_diagram.png differ diff --git a/docs/_static/images/sg.png b/docs/_static/images/sg.png new file mode 100644 index 00000000..8be51e1f Binary files /dev/null and b/docs/_static/images/sg.png differ diff --git a/docs/_static/images/sticky-connections.jpg b/docs/_static/images/sticky-connections.jpg new file mode 100644 index 00000000..25fd72a9 Binary files /dev/null and b/docs/_static/images/sticky-connections.jpg differ diff --git a/docs/_static/images/traffic.png b/docs/_static/images/traffic.png new file mode 100644 index 00000000..74002b16 Binary files /dev/null and b/docs/_static/images/traffic.png differ diff --git a/docs/_static/images/uefi_secureboot_01.png b/docs/_static/images/uefi_secureboot_01.png new file mode 100644 index 00000000..02ec56b0 Binary files /dev/null and b/docs/_static/images/uefi_secureboot_01.png differ diff --git a/docs/_static/images/uefi_secureboot_02.png b/docs/_static/images/uefi_secureboot_02.png new file mode 100644 index 00000000..336d654d Binary files /dev/null and b/docs/_static/images/uefi_secureboot_02.png differ diff --git a/docs/_static/images/uefi_secureboot_03.png b/docs/_static/images/uefi_secureboot_03.png new file mode 100644 index 00000000..ff126842 Binary files /dev/null and b/docs/_static/images/uefi_secureboot_03.png differ diff --git a/docs/_static/images/uefi_secureboot_04.png b/docs/_static/images/uefi_secureboot_04.png new file mode 100644 index 00000000..90242299 Binary files /dev/null and b/docs/_static/images/uefi_secureboot_04.png differ diff --git a/docs/_static/images/uefi_secureboot_05.png b/docs/_static/images/uefi_secureboot_05.png new file mode 100644 index 00000000..b08cb946 Binary files /dev/null and b/docs/_static/images/uefi_secureboot_05.png differ diff --git a/docs/_static/images/uefi_secureboot_06.png b/docs/_static/images/uefi_secureboot_06.png new file mode 100644 index 00000000..784f0eed Binary files /dev/null and b/docs/_static/images/uefi_secureboot_06.png differ diff --git a/docs/_static/images/uefi_secureboot_07.png b/docs/_static/images/uefi_secureboot_07.png new file mode 100644 index 00000000..6ff450b4 Binary files /dev/null and b/docs/_static/images/uefi_secureboot_07.png differ diff --git a/docs/_static/images/virt-libvirt-01.png b/docs/_static/images/virt-libvirt-01.png new file mode 100644 index 00000000..06baea8e Binary files /dev/null and b/docs/_static/images/virt-libvirt-01.png differ diff --git a/docs/_static/images/virt-libvirt-02.png b/docs/_static/images/virt-libvirt-02.png new file mode 100644 index 00000000..b6c4b379 Binary files /dev/null and b/docs/_static/images/virt-libvirt-02.png differ diff --git a/docs/_static/images/virt-libvirt-03.png b/docs/_static/images/virt-libvirt-03.png new file mode 100644 index 00000000..ac3891f0 Binary files /dev/null and b/docs/_static/images/virt-libvirt-03.png differ diff --git a/docs/_static/images/virt-libvirt-04.png b/docs/_static/images/virt-libvirt-04.png new file mode 100644 index 00000000..b1218597 Binary files /dev/null and b/docs/_static/images/virt-libvirt-04.png differ diff --git a/docs/_static/images/virt-libvirt-05.png b/docs/_static/images/virt-libvirt-05.png new file mode 100644 index 00000000..5579c281 Binary files /dev/null and b/docs/_static/images/virt-libvirt-05.png differ diff --git a/docs/_static/images/virt-libvirt-06.png b/docs/_static/images/virt-libvirt-06.png new file mode 100644 index 00000000..e0983d23 Binary files /dev/null and b/docs/_static/images/virt-libvirt-06.png differ diff --git a/docs/_static/images/virt-libvirt-qc-01.png b/docs/_static/images/virt-libvirt-qc-01.png new file mode 100644 index 00000000..49867bd0 Binary files /dev/null and b/docs/_static/images/virt-libvirt-qc-01.png differ diff --git a/docs/_static/images/virt-libvirt-qc-02.png b/docs/_static/images/virt-libvirt-qc-02.png new file mode 100644 index 00000000..a71b8f64 Binary files /dev/null and b/docs/_static/images/virt-libvirt-qc-02.png differ diff --git a/docs/_static/images/virt-libvirt-qc-03.png b/docs/_static/images/virt-libvirt-qc-03.png new file mode 100644 index 00000000..4eefaa58 Binary files /dev/null and b/docs/_static/images/virt-libvirt-qc-03.png differ diff --git a/docs/_static/images/vpn_dmvpn_topology01.png b/docs/_static/images/vpn_dmvpn_topology01.png new file mode 100644 index 00000000..17433be6 Binary files /dev/null and b/docs/_static/images/vpn_dmvpn_topology01.png differ diff --git a/docs/_static/images/vpn_s2s_ikev2.png b/docs/_static/images/vpn_s2s_ikev2.png new file mode 100644 index 00000000..f8050e3a Binary files /dev/null and b/docs/_static/images/vpn_s2s_ikev2.png differ diff --git a/docs/_static/images/vpn_s2s_ikev2_c.png b/docs/_static/images/vpn_s2s_ikev2_c.png new file mode 100644 index 00000000..2d9e21b5 Binary files /dev/null and b/docs/_static/images/vpn_s2s_ikev2_c.png differ diff --git a/docs/_static/images/vrf-example-topology-01.png b/docs/_static/images/vrf-example-topology-01.png new file mode 100644 index 00000000..57357509 Binary files /dev/null and b/docs/_static/images/vrf-example-topology-01.png differ diff --git a/docs/_static/images/vyos-downloads.png b/docs/_static/images/vyos-downloads.png new file mode 100644 index 00000000..6bad2b19 Binary files /dev/null and b/docs/_static/images/vyos-downloads.png differ diff --git a/docs/_static/images/vyos-sr-isis.png b/docs/_static/images/vyos-sr-isis.png new file mode 100644 index 00000000..62430919 Binary files /dev/null and b/docs/_static/images/vyos-sr-isis.png differ diff --git a/docs/_static/images/vyos_1_4_nat66_simple.png b/docs/_static/images/vyos_1_4_nat66_simple.png new file mode 100644 index 00000000..d7c54115 Binary files /dev/null and b/docs/_static/images/vyos_1_4_nat66_simple.png differ diff --git a/docs/_static/images/vyos_1_5_nat66_dhcpv6_wdummy.png b/docs/_static/images/vyos_1_5_nat66_dhcpv6_wdummy.png new file mode 100644 index 00000000..297fdd11 Binary files /dev/null and b/docs/_static/images/vyos_1_5_nat66_dhcpv6_wdummy.png differ diff --git a/docs/_static/images/vyos_arista_bond_lacp.png b/docs/_static/images/vyos_arista_bond_lacp.png new file mode 100644 index 00000000..6c9ef8ec Binary files /dev/null and b/docs/_static/images/vyos_arista_bond_lacp.png differ diff --git a/docs/_static/images/vyosnew-downloads.png b/docs/_static/images/vyosnew-downloads.png new file mode 100644 index 00000000..294a4589 Binary files /dev/null and b/docs/_static/images/vyosnew-downloads.png differ diff --git a/docs/_static/images/wireguard_qrcode.jpg b/docs/_static/images/wireguard_qrcode.jpg new file mode 100644 index 00000000..0a9a98c0 Binary files /dev/null and b/docs/_static/images/wireguard_qrcode.jpg differ diff --git a/docs/_static/images/wireguard_site2site_diagram.jpg b/docs/_static/images/wireguard_site2site_diagram.jpg new file mode 100644 index 00000000..4a7a95e4 Binary files /dev/null and b/docs/_static/images/wireguard_site2site_diagram.jpg differ diff --git a/docs/_static/images/zone-policy-diagram.png b/docs/_static/images/zone-policy-diagram.png new file mode 100644 index 00000000..cfde4af6 Binary files /dev/null and b/docs/_static/images/zone-policy-diagram.png differ diff --git a/docs/_swap.txt b/docs/_swap.txt deleted file mode 100644 index 3ffcdaf6..00000000 --- a/docs/_swap.txt +++ /dev/null @@ -1,262 +0,0 @@ -# Incremental MyST swap list -# One page stem per line (relative to docs/, no extension) -# Pages listed here will render from MD instead of RST at build time. -# -# Default: every imported md-*.md page is listed below so MD is served -# by default. To revert a specific page back to RST, remove its line -# (or comment it out). - -404 -automation/cloud-init -automation/command-scripting -automation/index -automation/terraform/index -automation/terraform/terraformAWS -automation/terraform/terraformAZ -automation/terraform/terraformGoogle -automation/terraform/terraformvSphere -automation/vyos-ansible -automation/vyos-api -automation/vyos-govyos -automation/vyos-napalm -automation/vyos-netmiko -automation/vyos-pyvyos -automation/vyos-salt -cli -configexamples/ansible -configexamples/autotest/DHCPRelay_through_GRE/DHCPRelay_through_GRE -configexamples/autotest/L3VPN_EVPN/L3VPN_EVPN -configexamples/autotest/OpenVPN_with_LDAP/OpenVPN_with_LDAP -configexamples/autotest/Wireguard/Wireguard -configexamples/autotest/tunnelbroker/tunnelbroker -configexamples/azure-vpn-bgp -configexamples/azure-vpn-dual-bgp -configexamples/bgp-ipv6-unnumbered -configexamples/dmvpn-dualhub-dualcloud -configexamples/firewall -configexamples/fwall-and-bridge -configexamples/fwall-and-vrf -configexamples/ha -configexamples/index -configexamples/inter-vrf-routing-vrf-lite -configexamples/ipsec-cisco-policy-based -configexamples/ipsec-cisco-route-based -configexamples/ipsec-pa-route-based -configexamples/l3vpn-hub-and-spoke -configexamples/lac-lns -configexamples/nmp -configexamples/ospf-unnumbered -configexamples/policy-based-ipsec-and-firewall -configexamples/pppoe-ipv6-basic -configexamples/qos -configexamples/segment-routing-isis -configexamples/site-2-site-cisco -configexamples/wan-load-balancing -configexamples/zone-policy -configuration/container/index -configuration/firewall/bridge -configuration/firewall/flowtables -configuration/firewall/global-options -configuration/firewall/groups -configuration/firewall/index -configuration/firewall/ipv4 -configuration/firewall/ipv6 -configuration/firewall/zone -configuration/highavailability/index -configuration/index -configuration/interfaces/bonding -configuration/interfaces/bridge -configuration/interfaces/dummy -configuration/interfaces/ethernet -configuration/interfaces/geneve -configuration/interfaces/index -configuration/interfaces/l2tpv3 -configuration/interfaces/loopback -configuration/interfaces/macsec -configuration/interfaces/openvpn -configuration/interfaces/openvpn-examples -configuration/interfaces/pppoe -configuration/interfaces/pseudo-ethernet -configuration/interfaces/sstp-client -configuration/interfaces/tunnel -configuration/interfaces/virtual-ethernet -configuration/interfaces/vti -configuration/interfaces/vxlan -configuration/interfaces/wireguard -configuration/interfaces/wireless -configuration/interfaces/wwan -configuration/loadbalancing/haproxy -configuration/loadbalancing/index -configuration/loadbalancing/wan -configuration/nat/cgnat -configuration/nat/index -configuration/nat/nat44 -configuration/nat/nat64 -configuration/nat/nat66 -configuration/pki/index -configuration/policy/access-list -configuration/policy/as-path-list -configuration/policy/community-list -configuration/policy/examples -configuration/policy/extcommunity-list -configuration/policy/index -configuration/policy/large-community-list -configuration/policy/local-route -configuration/policy/prefix-list -configuration/policy/route -configuration/policy/route-map -configuration/protocols/arp -configuration/protocols/babel -configuration/protocols/bfd -configuration/protocols/bgp -configuration/protocols/failover -configuration/protocols/igmp-proxy -configuration/protocols/index -configuration/protocols/isis -configuration/protocols/mpls -configuration/protocols/multicast -configuration/protocols/openfabric -configuration/protocols/ospf -configuration/protocols/pim -configuration/protocols/pim6 -configuration/protocols/rip -configuration/protocols/rpki -configuration/protocols/segment-routing -configuration/protocols/static -configuration/protocols/traffic-engineering -configuration/service/broadcast-relay -configuration/service/config-sync -configuration/service/conntrack-sync -configuration/service/console-server -configuration/service/dhcp-relay -configuration/service/dhcp-server -configuration/service/dns -configuration/service/eventhandler -configuration/service/https -configuration/service/index -configuration/service/ipoe-server -configuration/service/lldp -configuration/service/mdns -configuration/service/monitoring -configuration/service/ntp -configuration/service/pppoe-server -configuration/service/router-advert -configuration/service/salt-minion -configuration/service/snmp -configuration/service/ssh -configuration/service/suricata -configuration/service/tftp-server -configuration/service/webproxy -configuration/system/acceleration -configuration/system/conntrack -configuration/system/console -configuration/system/default-route -configuration/system/flow-accounting -configuration/system/frr -configuration/system/host-name -configuration/system/index -configuration/system/ip -configuration/system/ipv6 -configuration/system/lcd -configuration/system/login -configuration/system/name-server -configuration/system/option -configuration/system/proxy -configuration/system/sflow -configuration/system/sysctl -configuration/system/syslog -configuration/system/task-scheduler -configuration/system/time-zone -configuration/system/updates -configuration/system/watchdog -configuration/trafficpolicy/index -configuration/vpn/dmvpn -configuration/vpn/index -configuration/vpn/ipsec/index -configuration/vpn/ipsec/ipsec_general -configuration/vpn/ipsec/remoteaccess_ipsec -configuration/vpn/ipsec/site2site_ipsec -configuration/vpn/ipsec/troubleshooting_ipsec -configuration/vpn/l2tp -configuration/vpn/openconnect -configuration/vpn/pptp -configuration/vpn/rsa-keys -configuration/vpn/sstp -configuration/vrf/index -contributing/build-vyos -contributing/cla -contributing/debugging -contributing/development -contributing/index -contributing/issues-features -contributing/testing -contributing/upstream-packages -coverage -documentation -index -installation/bare-metal -installation/cloud/aws -installation/cloud/azure -installation/cloud/gcp -installation/cloud/index -installation/cloud/oracle -installation/image -installation/index -installation/install -installation/secure-boot -installation/update -installation/virtual/docker -installation/virtual/eve-ng -installation/virtual/gns3 -installation/virtual/index -installation/virtual/libvirt -installation/virtual/proxmox -installation/virtual/vmware -introducing/about -introducing/history -operation/boot-options -operation/index -operation/information -operation/password-recovery -operation/raid -operation/upgrade-recovery -quick-start -troubleshooting/connectivity -troubleshooting/index -troubleshooting/interfaces -troubleshooting/monitoring -troubleshooting/system -troubleshooting/terminal -vpp/configuration/acl -vpp/configuration/dataplane/buffers -vpp/configuration/dataplane/cpu -vpp/configuration/dataplane/index -vpp/configuration/dataplane/interface -vpp/configuration/dataplane/ipsec -vpp/configuration/dataplane/ipv6 -vpp/configuration/dataplane/l2learn -vpp/configuration/dataplane/lcp -vpp/configuration/dataplane/logging -vpp/configuration/dataplane/memory -vpp/configuration/dataplane/system -vpp/configuration/dataplane/unix -vpp/configuration/index -vpp/configuration/interfaces/bonding -vpp/configuration/interfaces/bridge -vpp/configuration/interfaces/gre -vpp/configuration/interfaces/index -vpp/configuration/interfaces/ipip -vpp/configuration/interfaces/loopback -vpp/configuration/interfaces/vxlan -vpp/configuration/interfaces/xconnect -vpp/configuration/ipfix -vpp/configuration/ipsec -vpp/configuration/nat/cgnat -vpp/configuration/nat/index -vpp/configuration/nat/nat44 -vpp/configuration/sflow -vpp/description -vpp/index -vpp/limitations -vpp/requirements -vpp/troubleshooting diff --git a/docs/automation/md-cloud-init.md b/docs/automation/md-cloud-init.md deleted file mode 100644 index b6350b54..00000000 --- a/docs/automation/md-cloud-init.md +++ /dev/null @@ -1,378 +0,0 @@ ---- -lastproofread: '2026-04-13' ---- - -(cloud-init)= - -# VyOS cloud-init - -VyOS instances in cloud and virtualized environments are initialized using the -industry-standard `cloud-init`. Through `cloud-init`, VyOS injects SSH -keys, configures network settings, and applies custom configurations during the -initial instance boot. - -## Configuration sources - -VyOS `cloud-init` obtains configuration data from the following sources: - -- `meta-data`: Instance-specific details provided by the cloud platform or - hypervisor. In some cloud environments, this data is available via an HTTP - endpoint at `http://169.254.169.254`. -- `network configuration`: Network settings such as IP addresses, routes, and - DNS (only available on certain cloud and virtualization platforms). -- `user-data`: User-supplied CLI configuration commands. - -## User-data - -Major cloud providers support injecting `user-data` as plain text or base64 -encoding text during initial instance boot. As `user-data` has a strict size -limit of \~16384 bytes, long configuration command lists can be compressed using -`gzip`. - -The recommended method for configuring VyOS instances via `user-data` is to -use the `cloud-config` syntax described below. - -## Cloud-config modules - -By default, VyOS enables only two `cloud-config` modules: - -- `write_files`: Inserts user-provided files such as encryption keys, - certificates, or `config.boot` into the filesystem during the initial - instance boot. See [Cloud-init-write_files] for file syntax and file format - requirements. -- `vyos_userdata`: Executes user-provided CLI configuration commands during - the initial instance boot. - -The files to insert and the CLI commands to execute must be provided in a -`cloud-config` YAML file. - -## Cloud-config file format - -`cloud-config` files are written in YAML and must begin with the -`#cloud-config` line. Only `vyos_config_commands` and `write_files` are -supported as top-level keys. The use of these keys is described in the -following two sections. - -## Vyos_config_commands key - -Use the `vyos_config_commands` key to define configuration commands for -initializing your VyOS instance. Commands must follow the set-style syntax -and can include both `set` and `delete` statements. - -Syntax requirements: - -- Place one command per line. -- Enclose values in single quotes. -- Avoid single quotes within commands or values. - -Applying commands from `cloud-config` overrides both settings configured via -`meta-data` and default VyOS settings. After commands are applied, -`cloud-init` automatically performs `commit` and `save`. - -The following is an example of a `cloud-config` file: - -```yaml -#cloud-config -vyos_config_commands: - - set system host-name 'vyos-prod-ashburn' - - set service ntp server 1.pool.ntp.org - - set service ntp server 2.pool.ntp.org - - delete interfaces ethernet eth1 address 'dhcp' - - set interfaces ethernet eth1 address '192.0.2.247/24' - - set protocols static route 198.51.100.0/24 next-hop '192.0.2.1' -``` - - -### Instance defaults/fallbacks - -If no external configuration data is provided, VyOS applies the following -defaults: - -- **SSH:** port 22. -- **Credentials:** `vyos`/`vyos`. -- **Networking:** DHCP is enabled on the first Ethernet interface. - -All defaults can be overridden via `user-data` configurations. - -## Write_files key - -VyOS allows you to run custom scripts during the initial instance boot to -execute operational, configuration, and standard Linux commands. - -Use the `write_files` key to insert these scripts into the -`/opt/vyatta/etc/config/scripts/` directory. - -Depending on when your commands need to run, use one of the following paths: - -- `/opt/vyatta/etc/config/scripts/vyos-preconfig-bootup.script`: Commands - defined here are executed before the system configuration is applied. -- `/opt/vyatta/etc/config/scripts/vyos-postconfig-bootup.script`: Commands - defined here are executed after the system configuration is applied. - -In both cases, commands are executed with `root` privileges. - -:::{note} -Use the `/opt/vyatta/etc/config/` path instead of `/config/scripts/` as -referenced in the {ref}`command-scripting` section. The `/config/scripts/` -directory is not mounted when the `write_files` module runs. -::: - -The following example shows how to use `write_files` to execute an -operational command **after** the initial configuration is complete: - -```yaml -#cloud-config -write_files: - - path: /opt/vyatta/etc/config/scripts/vyos-postconfig-bootup.script - owner: root:vyattacfg - permissions: '0775' - content: | - #!/bin/vbash - source /opt/vyatta/etc/functions/script-template - filename=/tmp/bgp_status_`date +"%Y_%m_%d_%I_%M_%p"`.log - run show ip bgp summary >> $filename -``` - -You can combine standard Linux commands to fetch data and VyOS configuration -commands (like `set` and `commit`) in the same script. - -The following example sets the `hostname` based on the instance identifier -obtained from the EC2 Instance Metadata Service (IMDS). - -```yaml -#cloud-config -write_files: - - path: /opt/vyatta/etc/config/scripts/vyos-postconfig-bootup.script - owner: root:vyattacfg - permissions: '0775' - content: | - #!/bin/vbash - source /opt/vyatta/etc/functions/script-template - hostname=`curl -s http://169.254.169.254/latest/meta-data/instance-id` - configure - set system host-name $hostname - commit - exit -``` - - -## NoCloud - -Injecting configuration data is not limited to cloud platforms. The NoCloud -data source allows you to inject `user-data` and `meta-data` on -virtualization platforms such as VMware, Hyper-V, and KVM. - -The simplest way to use the NoCloud data source is to create a `seed.iso` -file and attach it to the virtual machine as a CD drive. The volume must be -formatted as a VFAT or ISO 9660 file system with the label `cidata` or -`CIDATA`. - -Create text files named `user-data` and `meta-data`. On Linux-based -systems, use the `mkisofs` utility to create the `seed.iso` file. The -following syntax adds these files to the ISO 9660 file system: - -```none -mkisofs -joliet -rock -volid "cidata" -output seed.iso meta-data user-data -``` - -Once generated, attach the `seed.iso` file to your virtual machine. The -following example shows how to attach the file as a CD drive using KVM: - -```none -$ virt-install -n vyos_r1 \ - --ram 4096 \ - --vcpus 2 \ - --cdrom seed.iso \ - --os-type linux \ - --os-variant debian10 \ - --network network=default \ - --graphics vnc \ - --hvm \ - --virt-type kvm \ - --disk path=/var/lib/libvirt/images/vyos_kvm.qcow2,bus=virtio \ - --import \ - --noautoconsole -``` - -For more information on the NoCloud data source, visit the [NoCloud] page in -the `cloud-init` documentation. - -## Troubleshooting - -If your configuration does not apply as expected, follow these troubleshooting -steps: - -1. **Validate your YAML**: Ensure your `cloud-config` file follows proper - YAML syntax. Online resources such as [YAML Lint](https://www.yamllint.com/) - provide simple validation tools. -2. **Check the logs**: `cloud-init` writes logs to `/var/log/cloud-init.log`. - Filter for VyOS-specific entries using: - -```none -sudo grep vyos /var/log/cloud-init.log -``` - - -## Cloud-init on Proxmox - -Before you begin, review the `cloud-init` [network-config-docs] to -understand how to import user and network configuration data. - -Key considerations: - -- Define VyOS configuration commands in the `user-data` file. -- Avoid including network configuration data in the `user-data` file. -- If no network configuration data is provided, the DHCP client is enabled on - the first interface. This happens at the OS level and is not reflected in the - VyOS CLI. - -The following example shows how to disable the DHCP client on `eth0` to -address this behavior. - -In this example: - -- **Proxmox IP address**: `192.168.0.253/24`. -- **Storage**: The `local` volume is mounted at `/var/lib/vz` and contains - all content types, including snippets. - -The goal is to remove the default DHCP client from the first interface and -apply a custom configuration during the initial instance boot using -`cloud-init`. - -### Generate .qcow2 image - -First, generate a VyOS `.qcow2` image with `cloud-init` support from the -[vyos-vm-images] repository: - -1. Clone the `vyos-vm-images` repository and comment out the `download-iso` - role in `qemu.yml`. -2. Download your preferred VyOS `.iso` file and save it as `/tmp/vyos.iso`. -3. Generate the `.qcow2` image (using a 10G disk size for this example): - -```sh -sudo ansible-playbook qemu.yml -e disk_size=10 \ - -e iso_local=/tmp/vyos.iso -e grub_console=serial -e vyos_version=1.5.0 \ - -e cloud_init=true -e cloud_init_ds=NoCloud -``` - -This generates your new image at `/tmp/vyos-1.5.0-cloud-init-10G-qemu.qcow2`. - -4. Copy the resulting image to the Proxmox server: - -```sh -sudo scp /tmp/vyos-1.5.0-cloud-init-10G-qemu.qcow2 root@192.168.0.253:/tmp/ -``` - - -### Prepare cloud-init files - -Create the following files on your Proxmox server to proceed with this setup: - -- `user-data`: Contains VyOS configuration commands. -- `network-config`: Disables the DHCP client on the first interface. -- `meta-data`: An empty file (required by `cloud-init`). - -All files must be placed in the `/tmp/` directory. - -Follow these steps to create the required files: - -1. Navigate to the `/tmp/` directory: - - ```sh - cd /tmp/ - ``` - -2. Create the `user-data` file. Begin the file with `#cloud-config` and - include VyOS configuration commands. - - ```none - #cloud-config - vyos_config_commands: - - set system host-name 'vyos-BRAS' - - set service ntp server '1.pool.ntp.org' - - set service ntp server '2.pool.ntp.org' - - delete interfaces ethernet eth0 address 'dhcp' - - set interfaces ethernet eth0 address '198.51.100.2/30' - - set interfaces ethernet eth0 description 'WAN - ISP01' - - set interfaces ethernet eth1 address '192.168.25.1/24' - - set interfaces ethernet eth1 description 'Coming through VLAN 25' - - set interfaces ethernet eth2 address '192.168.26.1/24' - - set interfaces ethernet eth2 description 'Coming through VLAN 26' - - set protocols static route 0.0.0.0/0 next-hop '198.51.100.1' - ``` - -3. Create the `network-config` file. Include the following: - - ```none - version: 2 - ethernets: - eth0: - dhcp4: false - dhcp6: false - ``` - -4. Create the required empty `meta-data` file. - -### Create seed.iso - -Once you have created the necessary files, generate the `seed.iso` image and -mount it as a CD drive to the new VM. - -```sh -mkisofs -joliet -rock -volid "cidata" -output seed.iso meta-data \ -user-data network-config -``` - -:::{note} -Be careful while copying and pasting the above commands. Double quotes may need -to be corrected. -::: - -### Create the VM - -Note that the following settings apply to this particular example and may -require adjustment for other setups: - -- **VM ID**: `555`. -- **VM and .iso file storage**: The local volume (`directory` type, - mounted at `/var/lib/vz`). -- **VM resources**: Can be modified as needed. - -The `seed.iso` file was previously created in the `/tmp/` directory. Move -it to `/var/lib/vz/template/iso`: - -```sh -mv /tmp/seed.iso /var/lib/vz/template/iso/ -``` - -On the Proxmox server: - -```none -## Create VM, import disk and define boot order -qm create 555 --name vyos-1.5.0-cloudinit --memory 1024 --net0 virtio,bridge=vmbr0 -qm importdisk 555 vyos-1.5.0-cloud-init-10G-qemu.qcow2 local -qm set 555 --virtio0 local:555/vm-555-disk-0.raw -qm set 555 --boot order=virtio0 - -## Import seed.iso for cloud init -qm set 555 --ide2 media=cdrom,file=local:iso/seed.iso - -## Since this server has 1 nic, lets add network intefaces (vlan 25 and 26) -qm set 555 --net1 virtio,bridge=vmbr0,firewall=1,tag=25 -qm set 555 --net2 virtio,bridge=vmbr0,firewall=1,tag=26 -``` - - -### Power on and verify the VM - -Power on the VM using the CLI or GUI. After it boots, verify the configuration. - -### References - -- Cloud-init [network-config-docs]. -- Proxmox [Cloud-init-Support]. -[cloud-init-support]: -[cloud-init-write_files]: https://cloudinit.readthedocs.io/en/latest/topics/examples.html#writing-out-arbitrary-files -[network-config-docs]: https://cloudinit.readthedocs.io/en/latest/topics/network-config.html -[nocloud]: https://cloudinit.readthedocs.io/en/latest/reference/datasources/nocloud.html -[vyos-vm-images]: https://github.com/vyos/vyos-vm-images diff --git a/docs/automation/md-command-scripting.md b/docs/automation/md-command-scripting.md deleted file mode 100644 index 7e736152..00000000 --- a/docs/automation/md-command-scripting.md +++ /dev/null @@ -1,225 +0,0 @@ ---- -lastproofread: '2026-03-16' ---- - -(command-scripting)= - -# Command scripting - -VyOS supports executing configuration and operational commands non-interactively -from shell scripts. - -To include VyOS-specific functions and aliases, source the -`/opt/vyatta/etc/functions/script-template` file at the beginning of your -script. - -```none -#!/bin/vbash -source /opt/vyatta/etc/functions/script-template -exit -``` - - -## Script execute permissions - -Simply placing script files in `/config/scripts/` does not mean the system -can execute them. - -To make your scripts executable, grant them **execute permissions**. Use the -following command: - -```none -chmod +x /config/scripts/script-name.sh -``` - - -## Run configuration commands - -In scripts, present configuration commands as in a standard configuration -session. - -For example, to disable a BGP peer during a VRRP transition to the backup -state, use the following syntax: - -```none -#!/bin/vbash -source /opt/vyatta/etc/functions/script-template -configure -set protocols bgp system-as 65536 -set protocols bgp neighbor 192.168.2.1 shutdown -commit -exit -``` - - -## Run operational commands - -In scripts, **always** prefix operational commands with `run`. - -```none -#!/bin/vbash -source /opt/vyatta/etc/functions/script-template -run show interfaces -exit -``` - - -## Run commands remotely - -You can execute multiple **operational commands** on a remote VyOS system by -passing a script block over SSH. - -```none -ssh 192.0.2.1 'vbash -s' < -[salt]: https://docs.saltproject.io/en/latest/contents.html diff --git a/docs/automation/terraform/md-index.md b/docs/automation/terraform/md-index.md deleted file mode 100644 index dc787db1..00000000 --- a/docs/automation/terraform/md-index.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -lastproofread: '2026-03-23' ---- - -# VyOS Terraform - -VyOS supports development infrastructure via Terraform and provisioning -via Ansible. -Terraform allows you to automate the deployment of instances on a number of -cloud and virtual platforms. This section shows how to deploy VyOS on -multiple platforms: AWS, Microsoft Azure, Google Cloud Platform (GCP), -and VMware vSphere. -For more information, see the -official documentation for [Terraform] and [Ansible]. - -```{toctree} -:caption: Guides -:maxdepth: 1 - -terraformvyos -terraformAWS -terraformAZ -terraformGoogle -terraformvSphere -``` - -[ansible]: https://docs.ansible.com -[install]: https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli -[terraform]: https://developer.hashicorp.com/terraform/intro diff --git a/docs/automation/terraform/md-terraformAWS.md b/docs/automation/terraform/md-terraformAWS.md deleted file mode 100644 index 488e7926..00000000 --- a/docs/automation/terraform/md-terraformAWS.md +++ /dev/null @@ -1,548 +0,0 @@ ---- -lastproofread: '2026-03-16' ---- - -(terraformaws)= - -# Deploy VyOS on AWS with Terraform and Ansible - -You can use Terraform to quickly deploy VyOS-based infrastructure -on AWS and remove infrastructure when it's no longer needed. -Additionally, you can use Ansible for provisioning. - -```{eval-rst} -.. image:: /_static/images/aws.webp - :width: 50% - :align: center - :alt: Network Topology Diagram -``` - -On this page you'll learn how to: -- Create the necessary files for Terraform and Ansible. -- Use Terraform to create a single instance on AWS and use Ansible for - provisioning. - -## Prepare to deploy VyOS with Terraform on AWS - -To create a single instance and install your configuration using -Terraform, Ansible, and AWS, follow these steps: - -### AWS - -1. Create an account with AWS and get your `access_key` and `secret_key`. -2. Create a key [pair] and download your `.pem` key. - -```{eval-rst} -.. image:: /_static/images/keypairs.webp - :width: 50% - :align: center - :alt: Network Topology Diagram -``` - -3. Create a security [group] for the new VyOS instance and open all traffic. - -```{eval-rst} -.. image:: /_static/images/sg.webp - :width: 50% - :align: center - :alt: Network Topology Diagram -``` - -```{eval-rst} -.. image:: /_static/images/traffic.webp - :width: 50% - :align: center - :alt: Network Topology Diagram -``` - - -### Terraform - -```{eval-rst} -1. Create an UNIX or Windows instance. - -2. Download and install - `Terraform `__. - -3. Create a folder, for example ``/root/awsterraform``: - - .. code-block:: none - - mkdir /root/awsterraform - -.. stop_vyoslinter - -4. Copy all files into your Terraform project - (``vyos.tf``, ``var.tf``, ``terraform.tfvars``, ``version.tf``). - See `Structure of files in Terraform for AWS <#structure-of-files-in-terraform-for-aws>`__ for more details. - -.. start_vyoslinter - -5. Run the following commands: - -.. code-block:: none - - cd / - terraform init -``` - -### Ansible - -```{eval-rst} -1. Create a UNIX instance whenever you need. - -2. Download and install Ansible - -3. Create a folder, for example ``/root/aws/``. - -.. stop_vyoslinter - -4. Copy all files into your Ansible project - (``ansible.cfg``, ``instance.yml``, - ``mykey.pem``, and ``all``). - See `Structure of files in Ansible for AWS <#structure-of-files-in-ansible-for-aws>`__ for more details. - You can obtain ``mykey.pem`` by creating a key `pair `__ in AWS and - downloading your ``.pem`` key. -``` - -### Deploy with Terraform - -Run the following commands on your Terraform instance: - -```none -cd / -terraform plan -terraform apply -yes -``` - -## Create an AWS instance and check its configuration - -```none -root@localhost:~/awsterraform# terraform apply - -Terraform used the selected providers to generate the following execution plan. -Resource actions are indicated with the following symbols: - + create - -Terraform will perform the following actions: - - # aws_instance.myVyOSec2 will be created - + resource "aws_instance" "myVyOSec2" { - + ami = "ami-************62c2d" - + arn = (known after apply) - + associate_public_ip_address = (known after apply) - + availability_zone = (known after apply) - + cpu_core_count = (known after apply) - + cpu_threads_per_core = (known after apply) - + disable_api_stop = (known after apply) - + disable_api_termination = (known after apply) - + ebs_optimized = (known after apply) - + get_password_data = false - + host_id = (known after apply) - + host_resource_group_arn = (known after apply) - + iam_instance_profile = (known after apply) - + id = (known after apply) - + instance_initiated_shutdown_behavior = (known after apply) - + instance_lifecycle = (known after apply) - + instance_state = (known after apply) - + instance_type = "t2.micro" - + ipv6_address_count = (known after apply) - + ipv6_addresses = (known after apply) - + key_name = "awsterraform" - + monitoring = (known after apply) - + outpost_arn = (known after apply) - + password_data = (known after apply) - + placement_group = (known after apply) - + placement_partition_number = (known after apply) - + primary_network_interface_id = (known after apply) - + private_dns = (known after apply) - + private_ip = (known after apply) - + public_dns = (known after apply) - + public_ip = (known after apply) - + secondary_private_ips = (known after apply) - + security_groups = [ - + "awsterraformsg", - ] - + source_dest_check = true - + spot_instance_request_id = (known after apply) - + subnet_id = (known after apply) - + tags = { - + "name" = "VyOS System" - } - + tags_all = { - + "name" = "VyOS System" - } - + tenancy = (known after apply) - + user_data = (known after apply) - + user_data_base64 = (known after apply) - + user_data_replace_on_change = false - + vpc_security_group_ids = (known after apply) - } - - # local_file.ip will be created - + resource "local_file" "ip" { - + content = (known after apply) - + content_base64sha256 = (known after apply) - + content_base64sha512 = (known after apply) - + content_md5 = (known after apply) - + content_sha1 = (known after apply) - + content_sha256 = (known after apply) - + content_sha512 = (known after apply) - + directory_permission = "0777" - + file_permission = "0777" - + filename = "ip.txt" - + id = (known after apply) - } - - # null_resource.SSHconnection1 will be created - + resource "null_resource" "SSHconnection1" { - + id = (known after apply) - } - - # null_resource.SSHconnection2 will be created - + resource "null_resource" "SSHconnection2" { - + id = (known after apply) - } - -Plan: 4 to add, 0 to change, 0 to destroy. - -Changes to Outputs: - + my_IP = (known after apply) - -Do you want to perform these actions? - Terraform will perform the actions described above. - Only 'yes' will be accepted to approve. - - Enter a value: yes - -aws_instance.myVyOSec2: Creating... -aws_instance.myVyOSec2: Still creating... [10s elapsed] -aws_instance.myVyOSec2: Still creating... [20s elapsed] -aws_instance.myVyOSec2: Still creating... [30s elapsed] -aws_instance.myVyOSec2: Still creating... [40s elapsed] -aws_instance.myVyOSec2: Creation complete after 44s [id=i-09edfca15aac2fe0a] -null_resource.SSHconnection1: Creating... -null_resource.SSHconnection2: Creating... -null_resource.SSHconnection1: Provisioning with 'file'... -null_resource.SSHconnection2: Provisioning with 'remote-exec'... -null_resource.SSHconnection2 (remote-exec): Connecting to remote host via SSH... -null_resource.SSHconnection2 (remote-exec): Host: 10.217.80.104 -null_resource.SSHconnection2 (remote-exec): User: root -null_resource.SSHconnection2 (remote-exec): Password: true -null_resource.SSHconnection2 (remote-exec): Private key: false -null_resource.SSHconnection2 (remote-exec): Certificate: false -null_resource.SSHconnection2 (remote-exec): SSH Agent: false -null_resource.SSHconnection2 (remote-exec): Checking Host Key: false -null_resource.SSHconnection2 (remote-exec): Target Platform: unix -local_file.ip: Creating... -local_file.ip: Creation complete after 0s [id=e8e91f2e24579cd28b92e2d152c0c24c3bf4b52c] -null_resource.SSHconnection2 (remote-exec): Connected! -null_resource.SSHconnection1: Creation complete after 0s [id=7070868940858935600] - -null_resource.SSHconnection2 (remote-exec): PLAY [integration of terraform and ansible] ************************************ - -null_resource.SSHconnection2 (remote-exec): TASK [Wait 300 seconds, but only start checking after 60 seconds] ************** -null_resource.SSHconnection2: Still creating... [10s elapsed] -null_resource.SSHconnection2: Still creating... [20s elapsed] -null_resource.SSHconnection2: Still creating... [30s elapsed] -null_resource.SSHconnection2: Still creating... [40s elapsed] -null_resource.SSHconnection2: Still creating... [50s elapsed] -null_resource.SSHconnection2: Still creating... [1m0s elapsed] -null_resource.SSHconnection2 (remote-exec): ok: [54.xxx.xxx.xxx] - -null_resource.SSHconnection2 (remote-exec): TASK [Configure general settings for the vyos hosts group] ********************* -null_resource.SSHconnection2: Still creating... [1m10s elapsed] -null_resource.SSHconnection2 (remote-exec): changed: [54.xxx.xxx.xxx] - -null_resource.SSHconnection2 (remote-exec): PLAY RECAP ********************************************************************* -null_resource.SSHconnection2 (remote-exec): 54.xxx.xxx.xxx : ok=2 changed=1 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 - -null_resource.SSHconnection2: Creation complete after 1m16s [id=4902256962410024771] - -Apply complete! Resources: 4 added, 0 changed, 0 destroyed. - -Outputs: - -my_IP = "54.xxx.xxx.xxx" -``` - -After running all the commands, your VyOS instance is deployed on -AWS with your specified configuration. -To delete the instance, type the following command: - -```none -terraform destroy -``` - -## Troubleshooting - -1. If Ansible doesn't connect via SSH to your AWS instance, verify that - your SSH key is in the path `/root/aws/`. You might need to - increase the timeout in `instance.yml` from 300 seconds to 500 - seconds or more, depending on your location. Make sure that the - security group allows access to the instance. -2. If Terraform doesn't connect via SSH to your Ansible instance, - verify the correct login and password in the `VyOS.tf` file. - -```{eval-rst} - .. code-block:: none - - connection { - type = "ssh" - user = "root" # open root access using login and password on your Ansible - password = var.password # check password in the file terraform.tfvars isn't empty - host = var.host # check the correct IP address of your Ansible host - } -``` - -Make sure Ansible can ping from Terraform. - -## Structure of files in Terraform for AWS - -```none -. -├── vyos.tf # The main script -├── var.tf # The file of all variables in "vyos.tf" -├── versions.tf # File for the changing version of Terraform. -└── terraform.tfvars # The value of all variables (passwords, login, ip adresses and so on) -``` - -## File contents of Terraform for AWS - -`vyos.tf` - -```none -############################################################################## -# Build a VyOS VM from the Marketplace. -# Find the necessary AMI image_ in AWS. -# -# The vyos.tf script uses default values (you can change them as -# needed) -# AWS Region = "us-east-1" -# AMI = "standard AMI of VyOS from AWS Marketplace" -# Size of VM = "t2.micro" -# AWS Region = "us-east-1" -# After deploying the AWS instance and getting an IP address, the IP address is copied into the file -#"ip.txt" and copied to the Ansible node for provisioning. -############################################################################## - -provider "aws" { - access_key = var.access - secret_key = var.secret - region = var.region -} - -variable "region" { - default = "us-east-1" - description = "AWS Region" -} - -variable "ami" { - default = "ami-**************3b3" # ami image please enter your details - description = "Amazon Machine Image ID for VyOS" -} - -variable "type" { - default = "t2.micro" - description = "Size of VM" -} - -# my resource for VyOS - -resource "aws_instance" "myVyOSec2" { - ami = var.ami - key_name = "awsterraform" # Please enter your details from 1.2 of Preparation steps for deploying VyOS on AWS - security_groups = ["awsterraformsg"] # Please enter your details from 1.3 of Preparation steps for deploying VyOS on AWS - instance_type = var.type - tags = { - name = "VyOS System" - } -} - -############################################################################## -# Specific variable (to getting type "terraform plan"): -# aws_instance.myVyOSec2.public_ip - the information about public IP address -# of our instance, needs for provisioning and SSH connection from Ansible -############################################################################## - -output "my_IP"{ -value = aws_instance.myVyOSec2.public_ip -} - -############################################################################## -# The IP address of the AWS instance is copied to the ip.txt file -# on the local Terraform system. The ip.txt file contains the public -# IP address in the format: xxx.xxx.xxx.xxx -############################################################################## - -resource "local_file" "ip" { - content = aws_instance.myVyOSec2.public_ip - filename = "ip.txt" -} - -#connecting to the Ansible control node using SSH connection - -############################################################################## -# The "SSHconnection1" and "SSHconnection2" steps retrieve ip.txt -# from the Terraform node and run the Ansible playbook remotely. -############################################################################## - -resource "null_resource" "SSHconnection1" { -depends_on = [aws_instance.myVyOSec2] -connection { - type = "ssh" - user = "root" - password = var.password - host = var.host -} - -# Copy the ip.txt file to the Ansible control node from the local -# system - provisioner "file" { - source = "ip.txt" - destination = "/root/aws/ip.txt" # The folder of your Ansible project - } -} - -resource "null_resource" "SSHconnection2" { -depends_on = [aws_instance.myVyOSec2] -connection { - type = "ssh" - user = "root" - password = var.password - host = var.host -} -# Run Ansible playbook on remote Linux OS -provisioner "remote-exec" { - inline = [ - "cd /root/aws/", - "ansible-playbook instance.yml" # more detailed in "File contents of Ansible for AWS" -] -} -} -``` - -`var.tf` - -```none -variable "password" { - description = "pass for Ansible" - type = string - sensitive = true -} -variable "host"{ - description = "The IP of my Ansible" - type = string -} -variable "access" { - description = "my access_key for AWS" - type = string - sensitive = true -} -variable "secret" { - description = "my secret_key for AWS" - type = string - sensitive = true -} -``` - -`versions.tf` - -```none - terraform { - required_providers { - aws = { - source = "hashicorp/aws" - version = "~> 5.0" - } - } -} -``` - -`terraform.tfvars` - -```none -password = "" # password for Ansible SSH -host = "" # IP of my Ansible -access = "" # access_key for AWS -secret = "" # secret_key for AWS -``` - -## Structure of files in Ansible for AWS - -```none -. -├── group_vars - └── all -├── ansible.cfg -├── mykey.pem -└── instance.yml -``` - -## File contents of Ansible for AWS - -`ansible.cfg` - -```none -[defaults] -inventory = /root/aws/ip.txt -host_key_checking= False -private_key_file = /root/aws/awsterraform.pem # check the name -remote_user=vyos -``` - -`mykey.pem` - -```none -Copy your key.pem from AWS -``` - -`instance.yml` - -```none -############################################################################## -# About tasks: -# "Wait 300 seconds, but only start checking after 60 seconds" - -# attempts SSH connection every 60 seconds until 300 seconds -# "Configure general settings for the VyOS hosts group" - -# provisions the AWS VyOS node -# Add all necessary VyOS commands under the "lines:" block -############################################################################## - -- name: integration of terraform and ansible - hosts: all - gather_facts: 'no' - - tasks: - - - name: "Wait 300 seconds, but only start checking after 60 seconds" - wait_for_connection: - delay: 60 - timeout: 300 - - - name: "Configure general settings for the VyOS hosts group" - vyos_config: - lines: - - set system name-server xxx.xxx.xxx.xxx - save: - true -``` - -`group_vars/all` - -```none -ansible_connection: ansible.netcommon.network_cli -ansible_network_os: vyos.vyos.vyos -ansible_user: vyos -``` - - -## Source files on GitHub - -All files related to deploying VyOS on AWS with Terraform and Ansible -can be found in the [vyos-automation] repository. - -[group]: https://docs.aws.amazon.com/cli/latest/userguide/cli-services-ec2-sg.html -[pair]: https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/create-key-pairs.html -[vyos-automation]: diff --git a/docs/automation/terraform/md-terraformAZ.md b/docs/automation/terraform/md-terraformAZ.md deleted file mode 100644 index b1b8fac0..00000000 --- a/docs/automation/terraform/md-terraformAZ.md +++ /dev/null @@ -1,501 +0,0 @@ ---- -lastproofread: '2026-03-19' ---- - -(terraformaz)= - -# Deploy VyOS on Microsoft Azure with Terraform and Ansible - -You can use Terraform to quickly deploy VyOS-based infrastructure -on Microsoft Azure (hereafter referred to as *Azure*) and remove -infrastructure when it's no longer needed. -Additionally, you can use Ansible for provisioning. - -On this page you'll learn how to: - -- Create the necessary files for Terraform and Ansible. -- Use Terraform to create a single instance on Azure and use Ansible for - provisioning. - -## Prepare to deploy VyOS with Terraform on Azure - -To create a single instance and install your configuration using -Terraform, Ansible, and Azure, follow these steps: - -### Azure - -- Create an [Azure account](https://azure.microsoft.com/). - -### Terraform - -```{eval-rst} -1. Create an UNIX or Windows instance. - -2. Download and install - `Terraform `__. - -3. Create the folder for example ``/root/azvyos/``. - -.. code-block:: none - - mkdir /root/azvyos - -.. stop_vyoslinter - -4. Copy all files into your Terraform project "/root/azvyos" - (``vyos.tf``, ``var.tf``, ``terraform.tfvars``). For more details, see - `Structure of files in Terraform for Azure <#structure-of-files-in-terraform-for-azure>`_. - -.. start_vyoslinter - -5. Log in to Azure using the command: - - .. code-block:: none - - az login - -6. Run the following commands to initialize Terraform: - - .. code-block:: none - - cd / - terraform init -``` - - -### Ansible - -1. Create an UNIX instance either locally or in the cloud. - -2. Download and install Ansible - -3. Create a folder, for example `/root/az/`. - -4. Copy all files into your Ansible project `/root/az/` (`ansible.cfg`, - `instance.yml`, `all`). For more details, see - [Structure of files in Ansible for Azure](#structure-of-files-in-ansible-for-azure) - -### Deploy with Terraform - -Run the following commands on your Terraform instance: - -```none -cd / -terraform plan -terraform apply -yes -``` - -After executing all the commands, your VyOS instance is deployed to -Azure with your configuration. -If you need to delete the instance, run the following command: - -```none -terraform destroy -``` - - -## Structure of files in Terraform for Azure - -```none -. -├── vyos.tf # The main script -├── var.tf # File for the Terraform version. -└── terraform.tfvars # Values for all variables (passwords, - # login, IP addresses, etc.) -``` - - -## File contents of Terraform for Azure - -`vyos.tf` - -```none -############################################################################## -# HashiCorp Guide to Using Terraform on Azure -# This Terraform configuration will create the following: -# Resource group with a virtual network and subnet -# A VyOS server without SSH key (only login+password) -############################################################################## - -# Choose a provider - -provider "azurerm" { - features {} -} - -# Create a resource group. In Azure, every resource belongs to a -# resource group. - -resource "azurerm_resource_group" "azure_vyos" { - name = "${var.resource_group}" - location = "${var.location}" -} - -# The next resource is a Virtual Network. - -resource "azurerm_virtual_network" "vnet" { - name = "${var.virtual_network_name}" - location = "${var.location}" - address_space = ["${var.address_space}"] - resource_group_name = "${var.resource_group}" -} - -# Build a subnet to run your VMs. - -resource "azurerm_subnet" "subnet" { - name = "${var.prefix}subnet" - virtual_network_name = "${azurerm_virtual_network.vnet.name}" - resource_group_name = "${var.resource_group}" - address_prefixes = ["${var.subnet_prefix}"] -} - -############################################################################## -# Build a VyOS VM from the Marketplace. -# To find the necessary image, use the command: -# -# az vm image list --offer vyos --all -# -# Now that you have a network, you can deploy a VyOS server. -# An Azure Virtual Machine has several components. In this example, -# you build a security group, a network interface, a public IP -# address, a storage account, and finally the VM itself. Terraform -# handles all the dependencies automatically, and each resource is -# named with user-defined variables. -############################################################################## - - -# Security group to allow inbound access on port 22 (SSH) - -resource "azurerm_network_security_group" "vyos-sg" { - name = "${var.prefix}-sg" - location = "${var.location}" - resource_group_name = "${var.resource_group}" - - security_rule { - name = "SSH" - priority = 100 - direction = "Inbound" - access = "Allow" - protocol = "Tcp" - source_port_range = "*" - destination_port_range = "22" - source_address_prefix = "${var.source_network}" - destination_address_prefix = "*" - } -} - -# A network interface. - -resource "azurerm_network_interface" "vyos-nic" { - name = "${var.prefix}vyos-nic" - location = "${var.location}" - resource_group_name = "${var.resource_group}" - - ip_configuration { - name = "${var.prefix}ipconfig" - subnet_id = "${azurerm_subnet.subnet.id}" - private_ip_address_allocation = "Dynamic" - public_ip_address_id = "${azurerm_public_ip.vyos-pip.id}" - } -} - -# Add a public IP address. - -resource "azurerm_public_ip" "vyos-pip" { - name = "${var.prefix}-ip" - location = "${var.location}" - resource_group_name = "${var.resource_group}" - allocation_method = "Dynamic" -} - -# Build a virtual machine. This is a standard VyOS instance from -# Marketplace. - -resource "azurerm_virtual_machine" "vyos" { - name = "${var.hostname}-vyos" - location = "${var.location}" - resource_group_name = "${var.resource_group}" - vm_size = "${var.vm_size}" - - network_interface_ids = ["${azurerm_network_interface.vyos-nic.id}"] - delete_os_disk_on_termination = "true" - -# To find information about the plan, use the command: -# az vm image list --offer vyos --all - - plan { - publisher = "sentriumsl" - name = "vyos-1-3" - product = "vyos-1-2-lts-on-azure" - } - - storage_image_reference { - publisher = "${var.image_publisher}" - offer = "${var.image_offer}" - sku = "${var.image_sku}" - version = "${var.image_version}" - } - - storage_os_disk { - name = "${var.hostname}-osdisk" - managed_disk_type = "Standard_LRS" - caching = "ReadWrite" - create_option = "FromImage" - } - - os_profile { - computer_name = "${var.hostname}" - admin_username = "${var.admin_username}" - admin_password = "${var.admin_password}" - } - - os_profile_linux_config { - disable_password_authentication = false - } -} - -data "azurerm_public_ip" "example" { - depends_on = ["azurerm_virtual_machine.vyos"] - name = "vyos-ip" - resource_group_name = "${var.resource_group}" -} -output "public_ip_address" { - value = data.azurerm_public_ip.example.ip_address -} - -# IP of AZ instance copied to a file ip.txt in the local system. - -resource "local_file" "ip" { - content = data.azurerm_public_ip.example.ip_address - filename = "ip.txt" -} - -# Connect to the Ansible control node via SSH - -resource "null_resource" "nullremote1" { -depends_on = ["azurerm_virtual_machine.vyos"] -connection { - type = "ssh" - user = "root" - password = var.password - host = var.host -} - -# Copy the ip.txt file to the Ansible control node from the local -# system - - provisioner "file" { - source = "ip.txt" - destination = "/root/az/ip.txt" - } -} - -resource "null_resource" "nullremote2" { -depends_on = ["azurerm_virtual_machine.vyos"] -connection { - type = "ssh" - user = "root" - password = var.password - host = var.host -} - -# Run the Ansible playbook on the remote Linux OS - -provisioner "remote-exec" { - - inline = [ - "cd /root/az/", - "ansible-playbook instance.yml" -] -} -} -``` - -`var.tf` - -```none -############################################################################## -# Variables File -# -# Default values for all variables used in Terraform code. -############################################################################## - -variable "resource_group" { - description = "The name of your Azure Resource Group." - default = "my_resource_group" -} - -variable "prefix" { - description = "This prefix will be included in the name of some resources." - default = "vyos" -} - -variable "hostname" { - description = "Virtual machine hostname. Used for local hostname, DNS, and storage-related names." - default = "vyos_terraform" -} - -variable "location" { - description = "The region where the virtual network is created." - default = "centralus" -} - -variable "virtual_network_name" { - description = "The name for your virtual network." - default = "vnet" -} - -variable "address_space" { - description = "The address space that is used by the virtual network. You can supply more than one address space. Changing this forces a new resource to be created." - default = "10.0.0.0/16" -} - -variable "subnet_prefix" { - description = "The address prefix to use for the subnet." - default = "10.0.10.0/24" -} - -variable "storage_account_tier" { - description = "Defines the storage tier. Valid options are Standard and Premium." - default = "Standard" -} - -variable "storage_replication_type" { - description = "Defines the replication type to use for this storage account. Valid options include LRS, GRS etc." - default = "LRS" -} - -# The most cost-effective size - -variable "vm_size" { - description = "Specifies the size of the virtual machine." - default = "Standard_B1s" -} - -variable "image_publisher" { - description = "Name of the publisher of the image (az vm image list)" - default = "sentriumsl" -} - -variable "image_offer" { - description = "Name of the offer (az vm image list)" - default = "vyos-1-2-lts-on-azure" -} - -variable "image_sku" { - description = "Image SKU to apply (az vm image list)" - default = "vyos-1-3" -} - -variable "image_version" { - description = "Version of the image to apply (az vm image list)" - default = "1.3.3" -} - -variable "admin_username" { - description = "Administrator user name" - default = "vyos" -} - -variable "admin_password" { - description = "Administrator password" - type = string - sensitive = true -} - -variable "source_network" { - description = "Allow access from this network prefix. Defaults to '*'." - default = "*" -} - -variable "password" { - description = "pass for Ansible" - type = string - sensitive = true -} -variable "host"{ - description = "IP of my Ansible" -} -``` - -`terraform.tfvars` - -```none -password = "" # password for Ansible SSH -host = "" # IP of my Ansible -``` - - -## Structure of files in Ansible for Azure - -```none -. -├── group_vars - └── all -├── ansible.cfg -└── instance.yml -``` - - -## File contents of Ansible for Azure - -`ansible.cfg` - -```none -[defaults] -inventory = /root/az/ip.txt -host_key_checking= False -remote_user=vyos -``` - -`instance.yml` - -```none -############################################################################## -# About tasks: -# "Wait 300 seconds, but only start checking after 60 seconds" - Tries -# to make SSH connection every 60 seconds until 300 seconds. -# "Configure general settings for the VyOS hosts group" - Provision -# the Azure VyOS node. -# Add all necessary commands for VyOS under the block "lines:" -############################################################################## - - -- name: integration of terraform and ansible - hosts: all - gather_facts: 'no' - - tasks: - - - name: "Wait 300 seconds, but only start checking after 60 seconds" - wait_for_connection: - delay: 60 - timeout: 300 - - - name: "Configure general settings for the VyOS hosts group" - vyos_config: - lines: - - set system name-server xxx.xxx.xxx.xxx - save: - true -``` - -`group_vars/all` - -```none -ansible_connection: ansible.netcommon.network_cli -ansible_network_os: vyos.vyos.vyos - -# user and password gets from terraform variables "admin_username" and "admin_password" in the file /root/azvyos/var.tf -ansible_user: vyos -ansible_ssh_pass: "{{ vault_vyos_ssh_pass }}" -``` - - -## Source files on GitHub - -All files related to deploying VyOS on Azure with Terraform and Ansible -can be found in the [vyos-automation] repository. - -[vyos-automation]: diff --git a/docs/automation/terraform/md-terraformGoogle.md b/docs/automation/terraform/md-terraformGoogle.md deleted file mode 100644 index f9c002a7..00000000 --- a/docs/automation/terraform/md-terraformGoogle.md +++ /dev/null @@ -1,703 +0,0 @@ ---- -lastproofread: '2026-03-23' ---- - -(terraformgoogle)= - -# Deploy VyOS on Google Cloud with Terraform and Ansible - -Using Terraform, you can quickly deploy VyOS-based infrastructure on -Google Cloud Platform (GCP) and remove the -infrastructure when it's no longer needed. -Additionally, you can use Ansible for provisioning. - -On this page you'll learn how to: - -- Create the necessary files for Terraform and Ansible. -- Use Terraform to create a single instance on GCP and use Ansible for - provisioning. - -## Prepare to deploy VyOS with Terraform on GCP - -To create a single instance and install your configuration using -Terraform, Ansible, and GCP, follow these steps: - -### GCP - -1. Create an account with GCP and a new project. - -```{image} /_static/images/project.webp -:align: center -:alt: Network Topology Diagram -:width: 50% -``` - -2. Create a service account and download your key (a JSON file). - -```{image} /_static/images/service.webp -:align: center -:alt: Network Topology Diagram -:width: 50% -``` - -```{image} /_static/images/key.webp -:align: center -:alt: Network Topology Diagram -:width: 50% -``` - -The .JSON file downloads automatically after you create it and looks -like the following: - -```{image} /_static/images/json.webp -:align: center -:alt: Network Topology Diagram -:width: 50% -``` - -### Terraform - -1. Create an UNIX or Windows instance. - -2. Download and install - [Terraform](https://developer.hashicorp.com/terraform/install). - -3. Create the folder. For example, `/root/google`. - -```none -mkdir /root/google -``` - -4. Copy all files into your Terraform project `/root/google` - (`vyos.tf`, `var.tf`, `terraform.tfvars`, `mykey.json`). - For more details, - see [Structure of files Terraform for Google Cloud](#structure-of-files-in-terraform-for-google-cloud) - - - -5. Run the following commands: - -```none -cd / -terraform init -``` - -### Ansible - -1. Create an UNIX instance either locally or in the cloud. - -2. Download and install Ansible - -3. Create the folder for example /root/google/ - -4. Copy all files into your Ansible project `/root/google/` - (`ansible.cfg`, `instance.yml`, `mykey.json`, and `all`). For more - details, see [Structure of files in Ansible for Google Cloud](#structure-of-files-in-ansible-for-google-cloud) - -You obtain `mykey.json` when you create a service account in GCP -and download the key (a JSON file). - -### Deploy with Terraform - -Run the following commands on your Terraform instance: - -```none -cd / -terraform plan -terraform apply -yes -``` - -## Create a GCP instance and check its configuration - -```none -# terraform apply - -Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following symbols: - + create - -Terraform will perform the following actions: - - # google_compute_firewall.tcp_22[0] will be created - + resource "google_compute_firewall" "tcp_22" { - + creation_timestamp = (known after apply) - + destination_ranges = (known after apply) - + direction = (known after apply) - + enable_logging = (known after apply) - + id = (known after apply) - + name = "vyos-tcp-22" - + network = "default" - + priority = 1000 - + project = "vyosproject" - + self_link = (known after apply) - + source_ranges = [ - + "0.0.0.0/0", - ] - + target_tags = [ - + "vyos-deployment", - ] - - + allow { - + ports = [ - + "22", - ] - + protocol = "tcp" - } - } - - # google_compute_firewall.udp_500_4500[0] will be created - + resource "google_compute_firewall" "udp_500_4500" { - + creation_timestamp = (known after apply) - + destination_ranges = (known after apply) - + direction = (known after apply) - + enable_logging = (known after apply) - + id = (known after apply) - + name = "vyos-udp-500-4500" - + network = "default" - + priority = 1000 - + project = "vyosproject" - + self_link = (known after apply) - + source_ranges = [ - + "0.0.0.0/0", - ] - + target_tags = [ - + "vyos-deployment", - ] - - + allow { - + ports = [ - + "500", - + "4500", - ] - + protocol = "udp" - } - } - - # google_compute_instance.default will be created - + resource "google_compute_instance" "default" { - + can_ip_forward = true - + cpu_platform = (known after apply) - + current_status = (known after apply) - + deletion_protection = false - + effective_labels = (known after apply) - + guest_accelerator = (known after apply) - + id = (known after apply) - + instance_id = (known after apply) - + label_fingerprint = (known after apply) - + machine_type = "n2-highcpu-4" - + metadata = { - + "enable-oslogin" = "FALSE" - + "serial-port-enable" = "TRUE" - + "user-data" = "" - } - + metadata_fingerprint = (known after apply) - + min_cpu_platform = (known after apply) - + name = "vyos" - + project = "vyosproject" - + self_link = (known after apply) - + tags_fingerprint = (known after apply) - + terraform_labels = (known after apply) - + zone = "us-west1-a" - - + boot_disk { - + auto_delete = true - + device_name = (known after apply) - + disk_encryption_key_sha256 = (known after apply) - + kms_key_self_link = (known after apply) - + mode = "READ_WRITE" - + source = (known after apply) - - + initialize_params { - + image = "projects/sentrium-public/global/images/vyos-1-3-5-20231222143039" - + labels = (known after apply) - + provisioned_iops = (known after apply) - + provisioned_throughput = (known after apply) - + size = (known after apply) - + type = (known after apply) - } - } - - + network_interface { - + internal_ipv6_prefix_length = (known after apply) - + ipv6_access_type = (known after apply) - + ipv6_address = (known after apply) - + name = (known after apply) - + network = "default" - + network_ip = (known after apply) - + nic_type = "GVNIC" - + stack_type = (known after apply) - + subnetwork = "default" - + subnetwork_project = (known after apply) - - + access_config { - + nat_ip = (known after apply) - + network_tier = (known after apply) - } - } - } - - # local_file.ip will be created - + resource "local_file" "ip" { - + content = (known after apply) - + content_base64sha256 = (known after apply) - + content_base64sha512 = (known after apply) - + content_md5 = (known after apply) - + content_sha1 = (known after apply) - + content_sha256 = (known after apply) - + content_sha512 = (known after apply) - + directory_permission = "0777" - + file_permission = "0777" - + filename = "ip.txt" - + id = (known after apply) - } - - # null_resource.SSHconnection1 will be created - + resource "null_resource" "SSHconnection1" { - + id = (known after apply) - } - - # null_resource.SSHconnection2 will be created - + resource "null_resource" "SSHconnection2" { - + id = (known after apply) - } - -Plan: 6 to add, 0 to change, 0 to destroy. - -Changes to Outputs: - + public_ip_address = (known after apply) -╷ -│ Warning: Quoted references are deprecated -│ -│ on vyos.tf line 126, in resource "null_resource" "SSHconnection1": -│ 126: depends_on = ["google_compute_instance.default"] -│ -│ In this context, references are expected literally rather than in quotes. Terraform 0.11 and earlier required quotes, but quoted references are now deprecated and will be removed in a -│ future version of Terraform. Remove the quotes surrounding this reference to silence this warning. -│ -│ (and one more similar warning elsewhere) -╵ - -Do you want to perform these actions? - Terraform will perform the actions described above. - Only 'yes' will be accepted to approve. - - Enter a value: yes - -google_compute_firewall.udp_500_4500[0]: Creating... -google_compute_firewall.tcp_22[0]: Creating... -google_compute_instance.default: Creating... -google_compute_firewall.udp_500_4500[0]: Still creating... [10s elapsed] -google_compute_firewall.tcp_22[0]: Still creating... [10s elapsed] -google_compute_instance.default: Still creating... [10s elapsed] -google_compute_firewall.tcp_22[0]: Creation complete after 16s [id=projects/vyosproject/global/firewalls/vyos-tcp-22] -google_compute_firewall.udp_500_4500[0]: Creation complete after 16s [id=projects/vyosproject/global/firewalls/vyos-udp-500-4500] -google_compute_instance.default: Creation complete after 20s [id=projects/vyosproject/zones/us-west1-a/instances/vyos] -null_resource.SSHconnection1: Creating... -null_resource.SSHconnection2: Creating... -null_resource.SSHconnection1: Provisioning with 'file'... -null_resource.SSHconnection2: Provisioning with 'remote-exec'... -null_resource.SSHconnection2 (remote-exec): Connecting to remote host via SSH... -null_resource.SSHconnection2 (remote-exec): Host: 10.***.***.104 -null_resource.SSHconnection2 (remote-exec): User: root -null_resource.SSHconnection2 (remote-exec): Password: true -null_resource.SSHconnection2 (remote-exec): Private key: false -null_resource.SSHconnection2 (remote-exec): Certificate: false -null_resource.SSHconnection2 (remote-exec): SSH Agent: false -null_resource.SSHconnection2 (remote-exec): Checking Host Key: false -null_resource.SSHconnection2 (remote-exec): Target Platform: unix -local_file.ip: Creating... -local_file.ip: Creation complete after 0s [id=7d568c3b994a018c942a3cdb952ccbf3c729d0ca] -null_resource.SSHconnection2 (remote-exec): Connected! -null_resource.SSHconnection1: Creation complete after 4s [id=5175298735911137161] - -null_resource.SSHconnection2 (remote-exec): PLAY [integration of terraform and ansible] ************************************ - -null_resource.SSHconnection2 (remote-exec): TASK [Wait 300 seconds, but only start checking after 60 seconds] ************** -null_resource.SSHconnection2: Still creating... [10s elapsed] -null_resource.SSHconnection2: Still creating... [20s elapsed] -null_resource.SSHconnection2: Still creating... [30s elapsed] -null_resource.SSHconnection2: Still creating... [40s elapsed] -null_resource.SSHconnection2: Still creating... [50s elapsed] -null_resource.SSHconnection2: Still creating... [1m0s elapsed] -null_resource.SSHconnection2: Still creating... [1m10s elapsed] -null_resource.SSHconnection2 (remote-exec): ok: [104.***.***.158] - -null_resource.SSHconnection2 (remote-exec): TASK [Configure general settings for the vyos hosts group] ********************* -null_resource.SSHconnection2: Still creating... [1m20s elapsed] -null_resource.SSHconnection2 (remote-exec): changed: [104.***.***.158] - -null_resource.SSHconnection2 (remote-exec): PLAY RECAP ********************************************************************* -null_resource.SSHconnection2 (remote-exec): 104.***.***.158 : ok=2 changed=1 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 - -null_resource.SSHconnection2: Creation complete after 1m22s [id=3355727070503709742] - -Apply complete! Resources: 6 added, 0 changed, 0 destroyed. - -Outputs: - -public_ip_address = "104.***.***.158" -``` - -After running all the commands, your VyOS instance is deployed on -GCP with your specified configuration. -To delete the instance, type the following command: - -```none -terraform destroy -``` - -## Troubleshooting - -- Increase the timeout value in `instance.yml` from 300 seconds to - 500 seconds or more (depends on your location). Ensure that the - security group allows access to the instance. -- If Terraform doesn't connect via SSH to your Ansible instance: - Check the correct login and password in the `VyOS.tf` file. - -```none -connection { - type = "ssh" - user = "root" # open root access using login and password on your Ansible - password = var.password # check password in the file terraform.tfvars isn't empty - host = var.host # check the correct IP address of your Ansible host -} -``` - -Verify that Ansible can ping from Terraform. - -## Structure of files in Terraform for Google Cloud - -```none -. -├── vyos.tf # The main script -├── ***.JSON # The credential file from GCP -├── var.tf # The file of all variables in "vyos.tf" -└── terraform.tfvars # The value of all variables (passwords, login, IP addresses and so on) -``` - -## File contents of Terraform for Google Cloud - -`vyos.tf` - -```none -############################################################################## -# Build a VyOS VM from the Marketplace -# -# After deploying the GCP instance and getting an IP address, the IP address is copied into the file -#"ip.txt" and copied to the Ansible node for provisioning. -############################################################################## - -terraform { - required_providers { - google = { - source = "hashicorp/google" - } - } -} - -provider "google" { - project = var.project_id - request_timeout = "60s" - credentials = file(var.gcp_auth_file) -} - -locals { - network_interfaces = [for i, n in var.networks : { - network = n, - subnetwork = length(var.sub_networks) > i ? element(var.sub_networks, i) : null - external_ip = length(var.external_ips) > i ? element(var.external_ips, i) : "NONE" - } - ] -} - -resource "google_compute_instance" "default" { - name = var.goog_cm_deployment_name - machine_type = var.machine_type - zone = var.zone - - metadata = { - enable-oslogin = "FALSE" - serial-port-enable = "TRUE" - user-data = var.vyos_user_data - } - boot_disk { - initialize_params { - image = var.image - } - } - - can_ip_forward = true - - dynamic "network_interface" { - for_each = local.network_interfaces - content { - network = network_interface.value.network - subnetwork = network_interface.value.subnetwork - nic_type = "GVNIC" - dynamic "access_config" { - for_each = network_interface.value.external_ip == "NONE" ? [] : [1] - content { - nat_ip = network_interface.value.external_ip == "EPHEMERAL" ? null : network_interface.value.external_ip - } - } - } - } -} - -resource "google_compute_firewall" "tcp_22" { - count = var.enable_tcp_22 ? 1 : 0 - - name = "${var.goog_cm_deployment_name}-tcp-22" - network = element(var.networks, 0) - - allow { - ports = ["22"] - protocol = "tcp" - } - - source_ranges = ["0.0.0.0/0"] - - target_tags = ["${var.goog_cm_deployment_name}-deployment"] -} - -resource "google_compute_firewall" "udp_500_4500" { - count = var.enable_udp_500_4500 ? 1 : 0 - - name = "${var.goog_cm_deployment_name}-udp-500-4500" - network = element(var.networks, 0) - - allow { - ports = ["500", "4500"] - protocol = "udp" - } - - source_ranges = ["0.0.0.0/0"] - - target_tags = ["${var.goog_cm_deployment_name}-deployment"] -} - -output "public_ip_address" { - value = google_compute_instance.default.network_interface[0].access_config[0].nat_ip -} - -############################################################################## -# -# IP of google instance copied to a file ip.txt in local system Terraform -# ip.txt looks like: -# cat ./ip.txt -# ххх.ххх.ххх.ххх -############################################################################## - -resource "local_file" "ip" { - content = google_compute_instance.default.network_interface[0].access_config[0].nat_ip - filename = "ip.txt" -} - -#connecting to the Ansible control node using SSH connection - -############################################################################## -# Steps "SSHconnection1" and "SSHconnection2" need to get file ip.txt from the terraform node and start remotely the playbook of Ansible. -############################################################################## - -resource "null_resource" "SSHconnection1" { -depends_on = ["google_compute_instance.default"] -connection { - type = "ssh" - user = "root" - password = var.password - host = var.host -} - -#copying the ip.txt file to the Ansible control node from local system - - provisioner "file" { - source = "ip.txt" - destination = "/root/google/ip.txt" # The folder of your Ansible project - } -} - -resource "null_resource" "SSHconnection2" { -depends_on = ["google_compute_instance.default"] -connection { - type = "ssh" - user = "root" - password = var.password - host = var.host -} - -#command to run Ansible playbook on remote Linux OS - -provisioner "remote-exec" { - inline = [ - "cd /root/google/", - "ansible-playbook instance.yml" # more detailed in "File contents of Ansible for Google Cloud" -] -} -} -``` - -`var.tf` - -```none -variable "image" { - type = string - default = "projects/sentrium-public/global/images/vyos-1-3-5-20231222143039" -} - -variable "project_id" { - type = string -} - -variable "zone" { - type = string -} - -############################################################################## -# You can choose a lower cost machine type than n2-highcpu-4 -############################################################################## - -variable "machine_type" { - type = string - default = "n2-highcpu-4" -} - -variable "networks" { - description = "The network name to attach the VM instance." - type = list(string) - default = ["default"] -} - -variable "sub_networks" { - description = "The sub network name to attach the VM instance." - type = list(string) - default = ["default"] -} - -variable "external_ips" { - description = "The external IPs assigned to the VM for public access." - type = list(string) - default = ["EPHEMERAL"] -} - -variable "enable_tcp_22" { - description = "Allow SSH traffic from the Internet" - type = bool - default = true -} - -variable "enable_udp_500_4500" { - description = "Allow IKE/IPSec traffic from the Internet" - type = bool - default = true -} - -variable "vyos_user_data" { - type = string - default = "" -} - -// Marketplace requires this variable name to be declared -variable "goog_cm_deployment_name" { - description = "VyOS Universal Router Deployment" - type = string - default = "vyos" -} - -# GCP authentication file -variable "gcp_auth_file" { - type = string - description = "GCP authentication file" -} - -variable "password" { - description = "pass for Ansible" - type = string - sensitive = true -} -variable "host"{ - description = "The IP of my Ansible" - type = string -} -``` - -`terraform.tfvars` - -```none -############################################################################## -# Must be filled in -############################################################################## - -zone = "us-west1-a" -gcp_auth_file = "/root/***/***.json" # path of your .json file -project_id = "" # the google project -password = "" # password for Ansible SSH -host = "" # IP of my Ansible -``` - -## Structure of files in Ansible for Google Cloud - -```none -. -├── group_vars - └── all -├── ansible.cfg -└── instance.yml -``` - -## File contents of Ansible for Google Cloud - -`ansible.cfg` - -```none -[defaults] -inventory = /root/google/ip.txt -host_key_checking= False -remote_user=vyos -``` - -`instance.yml` - -```none -############################################################################## -# About tasks: -# "Wait 300 seconds, but only start checking after 60 seconds" - try to make ssh connection every 60 seconds until 300 seconds -# "Configure general settings for the VyOS hosts group" - make provisioning into Google Cloud VyOS node -# Add all necessary VyOS commands under the "lines:" block -############################################################################## - - -- name: integration of terraform and ansible - hosts: all - gather_facts: 'no' - - tasks: - - - name: "Wait 300 seconds, but only start checking after 60 seconds" - wait_for_connection: - delay: 60 - timeout: 300 - - - name: "Configure general settings for the VyOS hosts group" - vyos_config: - lines: - - set system name-server xxx.xxx.xxx.xxx - save: - true -``` - -`group_vars/all` - -```none -ansible_connection: ansible.netcommon.network_cli -ansible_network_os: vyos.vyos.vyos -ansible_user: vyos -ansible_ssh_pass: vyos -``` - - -## Source files on GitHub - -All files related to deploying VyOS on Google Cloud Platform with -Terraform and Ansible can be found in the [vyos-automation] repository. - -[vyos-automation]: diff --git a/docs/automation/terraform/md-terraformvSphere.md b/docs/automation/terraform/md-terraformvSphere.md deleted file mode 100644 index abcef5fa..00000000 --- a/docs/automation/terraform/md-terraformvSphere.md +++ /dev/null @@ -1,388 +0,0 @@ ---- -lastproofread: '2026-03-23' ---- - -(terraformvSphere)= - -# Deploy VyOS on VMware vSphere with Terraform and Ansible - -You can use Terraform to quickly deploy VyOS-based infrastructure -on VMware vSphere (hereafter referred to as *vSphere*) and remove -infrastructure when it's no longer needed. -Additionally, you can use Ansible for provisioning. - -On this page you'll learn how to: - -- Create the necessary files for Terraform and Ansible. -- Use Terraform to create a single instance on vSphere and use Ansible for - provisioning. - -## Prepare to deploy VyOS with Terraform on vSphere - -To create a single instance and install your configuration using -Terraform, Ansible, and vSphere, follow these steps: - -### vSphere - -- Add all necessary data to the `terraform.tfvars` - [file]() - and create resources. - -### Terraform - -- Create an UNIX or Windows instance. -- Download and install - [Terraform](https://developer.hashicorp.com/terraform/install). -- Create the folder for example `/root/vsphereterraform`. - -```none -mkdir /root/vsphereterraform -``` - -- Copy all files into your Terraform project `/root/vsphereterraform` - (`vyos.tf`, `var.tf`, `terraform.tfvars`, `version.tf`). - For more details, - see [Structure of files in Terraform for vSphere](#structure-of-files-in-terraform-for-vsphere) -- Run the following commands: - -```none -cd / -terraform init -``` - - -### Ansible - -- Create an UNIX instance either locally or in the cloud. -- Download and install Ansible. -- Create the folder. For example, `/root/vsphereterraform/`. -- Copy all files into your Ansible project `/root/vsphereterraform/` - (`ansible.cfg`, `instance.yml`, `all`). For more details, see - [Structure of files in Ansible for vSphere](#structure-of-files-in-ansible-for-vsphere) - -### Deploy with Terraform - -Run the following commands on your Terraform instance: - -```none -cd / -terraform plan -terraform apply -yes -``` - -After executing these commands, your VyOS instance is deployed to -vSphere with your configuration. -If you need to delete the instance, run the following command: - -```none -terraform destroy -``` - -## Structure of files in Terraform for vSphere - -```none -. -├── vyos.tf # The main script. -├── versions.tf # File for Terraform version. -├── var.tf # File for Terraform version. -└── terraform.tfvars # Values for all variables (passwords, - # login, IP addresses, etc.). -``` - -## File contents of Terraform for vSphere - -`vyos.tf` - -```none -provider "vsphere" { - user = var.vsphere_user - password = var.vsphere_password - vsphere_server = var.vsphere_server - allow_unverified_ssl = true -} - -data "vsphere_datacenter" "datacenter" { - name = var.datacenter -} - -data "vsphere_datastore" "datastore" { - name = var.datastore - datacenter_id = data.vsphere_datacenter.datacenter.id -} - -data "vsphere_compute_cluster" "cluster" { - name = var.cluster - datacenter_id = data.vsphere_datacenter.datacenter.id -} - -data "vsphere_resource_pool" "default" { - name = format("%s%s", data.vsphere_compute_cluster.cluster.name, "/Resources/terraform") # set as you need - datacenter_id = data.vsphere_datacenter.datacenter.id -} - -data "vsphere_host" "host" { - name = var.host - datacenter_id = data.vsphere_datacenter.datacenter.id -} - -data "vsphere_network" "network" { - name = var.network_name - datacenter_id = data.vsphere_datacenter.datacenter.id -} - -# Deployment of VM from Remote OVF -resource "vsphere_virtual_machine" "vmFromRemoteOvf" { - name = var.remotename - datacenter_id = data.vsphere_datacenter.datacenter.id - datastore_id = data.vsphere_datastore.datastore.id - host_system_id = data.vsphere_host.host.id - resource_pool_id = data.vsphere_resource_pool.default.id - network_interface { - network_id = data.vsphere_network.network.id - } - wait_for_guest_net_timeout = 2 - wait_for_guest_ip_timeout = 2 - - ovf_deploy { - allow_unverified_ssl_cert = true - remote_ovf_url = var.url_ova - disk_provisioning = "thin" - ip_protocol = "IPv4" - ip_allocation_policy = "dhcpPolicy" - ovf_network_map = { - "Network 1" = data.vsphere_network.network.id - "Network 2" = data.vsphere_network.network.id - } - } - vapp { - properties = { - "password" = "12345678", - "local-hostname" = "terraform_vyos" - } - } -} - -output "ip" { - description = "default ip address of the deployed VM" - value = vsphere_virtual_machine.vmFromRemoteOvf.default_ip_address -} - -# IP of vSphere instance copied to a file ip.txt in local system - -resource "local_file" "ip" { - content = vsphere_virtual_machine.vmFromRemoteOvf.default_ip_address - filename = "ip.txt" -} - -#Connecting to the Ansible control node using SSH connection - -resource "null_resource" "nullremote1" { -depends_on = ["vsphere_virtual_machine.vmFromRemoteOvf"] -connection { - type = "ssh" - user = "root" - password = var.ansiblepassword - host = var.ansiblehost - -} - -# Copying the ip.txt file to the Ansible control node from local system - - provisioner "file" { - source = "ip.txt" - destination = "/root/vsphere/ip.txt" - } -} - -resource "null_resource" "nullremote2" { -depends_on = ["vsphere_virtual_machine.vmFromRemoteOvf"] -connection { - type = "ssh" - user = "root" - password = var.ansiblepassword - host = var.ansiblehost -} - -# Command to run ansible playbook on remote Linux OS - -provisioner "remote-exec" { - - inline = [ - "cd /root/vsphere/", - "ansible-playbook instance.yml" -] -} -} -``` - -`versions.tf` - -```none -# Copyright (c) HashiCorp, Inc. -# SPDX-License-Identifier: MPL-2.0 - -terraform { - required_providers { - vsphere = { - source = "hashicorp/vsphere" - version = "2.4.0" - } - } -} -``` - -`var.tf` - -```none -# Copyright (c) HashiCorp, Inc. -# SPDX-License-Identifier: MPL-2.0 - -variable "vsphere_server" { - description = "vSphere server" - type = string -} - -variable "vsphere_user" { - description = "vSphere username" - type = string -} - -variable "vsphere_password" { - description = "vSphere password" - type = string - sensitive = true -} - -variable "datacenter" { - description = "vSphere data center" - type = string -} - -variable "cluster" { - description = "vSphere cluster" - type = string -} - -variable "datastore" { - description = "vSphere datastore" - type = string -} - -variable "network_name" { - description = "vSphere network name" - type = string -} - -variable "host" { - description = "Name of your host" - type = string -} - -variable "remotename" { - description = "The name of your VM" - type = string -} - -variable "url_ova" { - description = "The URL to the .OVA file or cloud storage" - type = string -} - -variable "ansiblepassword" { - description = "Ansible password" - type = string -} - -variable "ansiblehost" { - description = "Ansible host name or IP" - type = string -} -``` - -`terraform.tfvars` - -```none -vsphere_user = "" -vsphere_password = "" -vsphere_server = "" -datacenter = "" -datastore = "" -cluster = "" -network_name = "" -host = "" -url_ova = "" -ansiblepassword = "" -ansiblehost = "" -remotename = "" -``` - -## Structure of files in Ansible for vSphere - -```none -. -├── group_vars - └── all -├── ansible.cfg -└── instance.yml -``` - -## File contents of Ansible for vSphere - -`ansible.cfg` - -```none -[defaults] -inventory = /root/vsphere/ip.txt -host_key_checking= False -remote_user=vyos -``` - -`instance.yml` - -```none -############################################################################## -# About tasks: -# "Wait 300 seconds, but only start checking after 60 seconds" - try to make ssh connection every 60 seconds until 300 seconds -# "Configure general settings for the VyOS hosts group" - make provisioning into vSphere VyOS node -# You have to add all necessary commands of VyOS under the block "lines:" -############################################################################## - - -- name: integration of terraform and ansible - hosts: all - gather_facts: 'no' - - tasks: - - - name: "Wait 300 seconds, but only start checking after 60 seconds" - wait_for_connection: - delay: 60 - timeout: 300 - - name: "Configure general settings for the VyOS hosts group" - vyos_config: - lines: - - set system name-server 192.0.2.1 - save: - true -``` - -`group_vars/all` - -```none -ansible_connection: ansible.netcommon.network_cli -ansible_network_os: vyos.vyos.vyos - -# user and password gets from terraform variables "admin_username" and "admin_password" -ansible_user: vyos -# get from vyos.tf "vapp" -ansible_ssh_pass: 12345678 -``` - - -## Source files on GitHub - -All files related to deploying VyOS on vSphere with Terraform and Ansible -can be found in the [vyos-automation] repository. - -[vyos-automation]: diff --git a/docs/automation/terraform/terraformvyos.md b/docs/automation/terraform/terraformvyos.md deleted file mode 100644 index bfe1b6d1..00000000 --- a/docs/automation/terraform/terraformvyos.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -lastproofread: '2024-03-03' ---- - -(terraformvyos)= - -# Terraform for VyOS - -VyOS supports development infrastructure via Terraform and -provisioning via Ansible. Terraform allows you to automate the -process of deploying instances on many cloud and virtual -platforms. In this article, we will look at using Terraform to -deploy VyOS on platforms - AWS, Azure, and vSphere. For more -details about Terraform please have a look at [link]. - -You will need to [install] Terraform before proceeding. - -Structure of files in the standard Terraform project: - -```none -. -├── main.tf # The main script -├── version.tf # File for the changing version of Terraform. -├── variables.tf # The file of all variables in "main.tf" -└── terraform.tfvars # The value of all variables (passwords, login, IP addresses and so on) -``` - -General commands that we will use for running Terraform scripts - -```none -cd / # go to the Terraform project -terraform init # install all add-ons and providers (AWS, Azure, and so on) -terraform plan # show what is changing -terraform apply # run script -yes # apply running -``` - -% stop_vyoslinter - -% start_vyoslinter - -[install]: https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli -[link]: https://developer.hashicorp.com/terraform/intro - diff --git a/docs/conf.py b/docs/conf.py index 083baa61..1c1014e0 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -13,7 +13,6 @@ # documentation root, use os.path.abspath to make it absolute, like shown here. # import os -import shutil import sys sys.path.append(os.path.abspath("./_ext")) @@ -67,9 +66,6 @@ autosectionlabel_prefix_document = True # source_suffix = ['.rst', '.md'] source_suffix = ['.rst', '.md'] -myst_enable_extensions = ["colon_fence", "deflist", "fieldlist", "substitution"] -myst_fence_as_directive = ["cfgcmd", "opcmd", "cmdincludemd"] - # The master toctree document. master_doc = 'index' @@ -89,17 +85,7 @@ gettext_uuid = False # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. # This pattern also affects html_static_path and html_extra_path . -exclude_patterns = [ - u'_build', 'Thumbs.db', '.DS_Store', '_include/vyos-1x', - 'md-*.md', '**/md-*.md', -] - -import pathlib -_build = pathlib.Path(__file__).parent / '_build' -if (_build / '_swap_state.json').exists() and (_build / '_swap_exclude.txt').exists(): - exclude_patterns.extend( - s for s in (line.strip() for line in (_build / '_swap_exclude.txt').read_text().splitlines()) if s - ) +exclude_patterns = [u'_build', 'Thumbs.db', '.DS_Store', '_include/vyos-1x'] # The name of the Pygments (syntax highlighting) style to use. pygments_style = 'sphinx' @@ -231,18 +217,5 @@ def _prefer_webp(app): app.builder.supported_image_types = ['image/webp'] + types -def _copy_md_sources(app, exception): - """Copy .md source files verbatim into the HTML output tree.""" - if exception is not None: - return - src = pathlib.Path(app.srcdir) - out = pathlib.Path(app.outdir) - for path in src.rglob("*.md"): - dest = out / path.relative_to(src) - dest.parent.mkdir(parents=True, exist_ok=True) - shutil.copy2(path, dest) - - def setup(app): app.connect('builder-inited', _prefer_webp) - app.connect('build-finished', _copy_md_sources) diff --git a/docs/configexamples/autotest/DHCPRelay_through_GRE/_include/topology.png b/docs/configexamples/autotest/DHCPRelay_through_GRE/_include/topology.png new file mode 100644 index 00000000..952b664b Binary files /dev/null and b/docs/configexamples/autotest/DHCPRelay_through_GRE/_include/topology.png differ diff --git a/docs/configexamples/autotest/DHCPRelay_through_GRE/md-DHCPRelay_through_GRE.md b/docs/configexamples/autotest/DHCPRelay_through_GRE/md-DHCPRelay_through_GRE.md deleted file mode 100644 index 1633b349..00000000 --- a/docs/configexamples/autotest/DHCPRelay_through_GRE/md-DHCPRelay_through_GRE.md +++ /dev/null @@ -1,89 +0,0 @@ -# DHCP Relay through GRE-Bridge - -```{eval-rst} -| Testdate: 2023-05-11 -| Version: 1.4-rolling-202305100734 -``` - -This simple structure shows how to configure a DHCP Relay over a GRE Bridge -interface. - -## Topology - -The topology has 3 VyOS routers and one client. Between the DHCP Server and -the DHCP Relay is a GRE tunnel. The `transport` VyOS represent a large -Network. - -```{image} _include/topology.webp -:alt: Ansible Example topology image -``` - - -## Configuration - -First, we configure the transport network and the Tunnel interface. - -Transport: - -```{literalinclude} _include/transport.conf -:language: none -``` - -DHCP-Server - -```{literalinclude} _include/dhcp-server.conf -:language: none -:lines: 1-8 -``` - -DHCP-Relay - -```{literalinclude} _include/dhcp-relay.conf -:language: none -:lines: 1-8 -``` - -After this, we need the DHCP-Server and Relay configuration. -To get a testable result, we just have one IP in the DHCP range. -Expand it as you need it. - -DHCP-Server - -```{literalinclude} _include/dhcp-server.conf -:language: none -:lines: 9-13 -``` - -DHCP-Relay - -```{literalinclude} _include/dhcp-relay.conf -:language: none -:lines: 9-10 -``` - - -## Test the result - -Ping the Client from the DHCP Server. - -```none -vyos@dhcp-server:~$ ping 192.168.0.30 count 4 -PING 192.168.0.30 (192.168.0.30) 56(84) bytes of data. -64 bytes from 192.168.0.30: icmp_seq=1 ttl=63 time=1.02 ms -64 bytes from 192.168.0.30: icmp_seq=2 ttl=63 time=1.06 ms -64 bytes from 192.168.0.30: icmp_seq=3 ttl=63 time=1.21 ms -64 bytes from 192.168.0.30: icmp_seq=4 ttl=63 time=1.16 ms - ---- 192.168.0.30 ping statistics --- -4 packets transmitted, 4 received, 0% packet loss, time 3004ms -rtt min/avg/max/mdev = 1.016/1.112/1.214/0.077 ms -``` - -And show all DHCP Leases - -```none -vyos@dhcp-server:~$ show dhcp server leases -IP Address MAC address State Lease start Lease expiration Remaining Pool Hostname ------------- ----------------- ------- ------------------- ------------------- ----------- ---------- ---------- -192.168.0.30 00:50:79:66:68:05 active 2023/05/11 13:08:50 2023/05/12 13:08:50 23:59:16 DHCPTun100 VPCS -``` diff --git a/docs/configexamples/autotest/L3VPN_EVPN/_include/topology.png b/docs/configexamples/autotest/L3VPN_EVPN/_include/topology.png new file mode 100644 index 00000000..18ecaabb Binary files /dev/null and b/docs/configexamples/autotest/L3VPN_EVPN/_include/topology.png differ diff --git a/docs/configexamples/autotest/L3VPN_EVPN/md-L3VPN_EVPN.md b/docs/configexamples/autotest/L3VPN_EVPN/md-L3VPN_EVPN.md deleted file mode 100644 index b74452e1..00000000 --- a/docs/configexamples/autotest/L3VPN_EVPN/md-L3VPN_EVPN.md +++ /dev/null @@ -1,246 +0,0 @@ -# L3VPN EVPN with VyOS - -```{eval-rst} -| Testdate: 2023-05-11 -| Version: 1.4-rolling-202305100734 -``` - -I spun up a new lab in EVE-NG, which represents this as the -"Foo Bar - Service Provider Inc." that has 3 points of presence (PoP) in random -datacenters/sites named PE1, PE2, and PE3. Each PoP aggregates at least two -customers. - -I named the customers blue, red and green which is common practice in -VRF (Virtual Routing and Forwarding) documentation scenarios. - -- PE1 is located in an industrial area that holds multiple office buildings. - All customers have a site in this area. -- PE2 is located in a smaller area where by coincidence two customers - (blue and red) share an office building. -- PE3 is located in a smaller area where by coincidence two customers - (blue and green) are located. - -## Management VRF - -A brief excursion into VRFs: This has been one of the longest-standing feature -requests of VyOS (dating back to 2016) which can be described as -"a VLAN for layer 2 is what a VRF is for layer 3". -With VRFs, a router/system can hold multiple, isolated routing tables on the -same system. If you wonder what's the difference between multiple tables that -people used for policy-based routing since forever, it's that a VRF also -isolates connected routes rather than just static and dynamically learned -routes, so it allows NICs in different VRFs to use conflicting network -ranges without issues. - -VyOS 1.3 added initial support for VRFs (including IPv4/IPv6 static routing) -and VyOS 1.4 now enables full dynamic routing protocol support for -OSPF, IS-IS, and BGP for individual VRFs. - -The lab I built is using a VRF (called **mgmt**) to provide out-of-band -SSH access to the PE (Provider Edge) routers. - -```{literalinclude} _include/PE1.conf -:language: none -:lines: 1-6 -``` - - -## Topology - -We use the following network topology in this example: - -```{image} _include/topology.webp -:alt: L3VPN EVPN with VyOS topology image -``` - - -## Core network - -I chose to run OSPF as the IGP (Interior Gateway Protocol). -All required BGP sessions are established via a dummy interfaces -(similar to the loopback, but in Linux you can have only one loopback, -while there can be many dummy interfaces) on the PE routers. In case of a link -failure, traffic is diverted in the other direction in this triangle setup and -BGP sessions will not go down. One could even enable -BFD (Bidirectional Forwarding Detection) on the links for a faster -failover and resilience in the network. - -Regular VyOS users will notice that the BGP syntax has changed in VyOS 1.4 from -even the prior post about this subject. This is due to T1711, where it was -finally decided to get rid of the redundant BGP ASN (Autonomous System Number) -specification on the CLI and move it to a single leaf node -(set protocols bgp local-as). - -It's important to note that all your existing configurations will be migrated -automatically on image upgrade. Nothing to do on your side. - -PE1 - -```{literalinclude} _include/PE1.conf -:language: none -:lines: 8-38 -``` - -PE2 - -```{literalinclude} _include/PE2.conf -:language: none -:lines: 8-38 -``` - -PE3 - -```{literalinclude} _include/PE3.conf -:language: none -:lines: 8-38 -``` - - -## Tenant networks (VRFs) - -Once all routers can be safely remotely managed and the core network is -operational, we can now setup the tenant networks. - -Every tenant is assigned an individual VRF that would support overlapping -address ranges for customers blue, red and green. In our example, -we do not use overlapping ranges to make it easier when showing debug commands. - -Thus you can easily match it to one of the devices/networks below. - -Every router that provides access to a customer network needs to have the -customer network (VRF + VNI) configured. To make our own lives easier, -we utilize the same VRF table id (local routing table number) and -VNI (Virtual Network Identifier) per tenant on all our routers. - -- blue uses local routing table id and VNI 2000 -- red uses local routing table id and VNI 3000 -- green uses local routing table id and VNI 4000 - -PE1 - -```{literalinclude} _include/PE1.conf -:language: none -:lines: 40-96 -``` - -PE2 - -```{literalinclude} _include/PE2.conf -:language: none -:lines: 40-89 -``` - -PE3 - -```{literalinclude} _include/PE3.conf -:language: none -:lines: 40-89 -``` - - -## Testing and debugging - -You managed to come this far, now we want to see the network and routing -tables in action. - -Show routes for all VRFs - -```none -vyos@PE1:~$ show ip route vrf all -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 - -VRF blue: -C>* 10.1.1.0/24 is directly connected, br2000, 00:01:13 -B>* 10.1.2.0/24 [200/0] via 172.29.255.2, br2000 onlink, weight 1, 00:00:49 -B>* 10.1.3.0/24 [200/0] via 172.29.255.3, br2000 onlink, weight 1, 00:00:49 - -VRF default: -O 172.29.0.2/31 [110/1] is directly connected, eth1, weight 1, 00:01:09 -C>* 172.29.0.2/31 is directly connected, eth1, 00:01:12 -O>* 172.29.0.4/31 [110/2] via 172.29.0.3, eth1, weight 1, 00:00:46 - * via 172.29.0.7, eth3, weight 1, 00:00:46 -O 172.29.0.6/31 [110/1] is directly connected, eth3, weight 1, 00:01:09 -C>* 172.29.0.6/31 is directly connected, eth3, 00:01:12 -C>* 172.29.255.1/32 is directly connected, dum0, 00:01:14 -O>* 172.29.255.2/32 [110/20] via 172.29.0.3, eth1, weight 1, 00:00:50 -O>* 172.29.255.3/32 [110/20] via 172.29.0.7, eth3, weight 1, 00:00:45 - -VRF green: -C>* 10.3.1.0/24 is directly connected, br4000, 00:01:13 -B>* 10.3.3.0/24 [200/0] via 172.29.255.3, br4000 onlink, weight 1, 00:00:49 - -VRF mgmt: -S>* 0.0.0.0/0 [210/0] via 10.100.0.1, eth0, weight 1, 00:01:45 -C>* 10.100.0.0/24 is directly connected, eth0, 00:01:45 - -VRF red: -C>* 10.2.1.0/24 is directly connected, br3000, 00:01:13 -B>* 10.2.2.0/24 [200/0] via 172.29.255.2, br3000 onlink, weight 1, 00:00:49 -``` - -Information about Ethernet Virtual Private Networks - -```none -vyos@PE1:~$ show bgp l2vpn evpn -BGP table version is 1, local router ID is 172.29.255.1 -Status codes: s suppressed, d damped, h history, * valid, > best, i - internal -Origin codes: i - IGP, e - EGP, ? - incomplete -EVPN type-1 prefix: [1]:[EthTag]:[ESI]:[IPlen]:[VTEP-IP]:[Frag-id] -EVPN type-2 prefix: [2]:[EthTag]:[MAClen]:[MAC]:[IPlen]:[IP] -EVPN type-3 prefix: [3]:[EthTag]:[IPlen]:[OrigIP] -EVPN type-4 prefix: [4]:[ESI]:[IPlen]:[OrigIP] -EVPN type-5 prefix: [5]:[EthTag]:[IPlen]:[IP] - - Network Next Hop Metric LocPrf Weight Path -Route Distinguisher: 10.1.1.1:5 -*> [5]:[0]:[24]:[10.1.1.0] - 172.29.255.1 0 32768 ? - ET:8 RT:100:2000 Rmac:4e:bb:3c:ba:bd:a6 -Route Distinguisher: 10.1.2.1:4 -*>i[5]:[0]:[24]:[10.1.2.0] - 172.29.255.2 0 100 0 ? - RT:100:2000 ET:8 Rmac:26:07:da:eb:fc:ea -Route Distinguisher: 10.1.3.1:4 -*>i[5]:[0]:[24]:[10.1.3.0] - 172.29.255.3 0 100 0 ? - RT:100:2000 ET:8 Rmac:26:98:28:24:6e:54 -Route Distinguisher: 10.2.1.1:6 -*> [5]:[0]:[24]:[10.2.1.0] - 172.29.255.1 0 32768 ? - ET:8 RT:100:3000 Rmac:50:00:00:01:00:05 -Route Distinguisher: 10.2.2.1:5 -*>i[5]:[0]:[24]:[10.2.2.0] - 172.29.255.2 0 100 0 ? - RT:100:3000 ET:8 Rmac:50:00:00:02:00:05 -Route Distinguisher: 10.3.1.1:7 -*> [5]:[0]:[24]:[10.3.1.0] - 172.29.255.1 0 32768 ? - ET:8 RT:100:4000 Rmac:50:00:00:01:00:06 -Route Distinguisher: 10.3.3.1:6 -*>i[5]:[0]:[24]:[10.3.3.0] - 172.29.255.3 0 100 0 ? - RT:100:4000 ET:8 Rmac:06:32:9d:22:55:8a - -Displayed 7 out of 7 total prefixes -``` - -If we need to retrieve information about a specific host/network inside -the EVPN network we need to run - -```none -vyos@PE2:~$ show bgp l2vpn evpn 10.3.1.10 -BGP routing table entry for 10.3.1.1:7:[5]:[0]:[24]:[10.3.1.0] -Paths: (1 available, best #1) - Not advertised to any peer - Route [5]:[0]:[24]:[10.3.1.0] VNI 4000 - Local - 172.29.255.1 (metric 20) from 172.29.255.1 (172.29.255.1) - Origin incomplete, metric 0, localpref 100, valid, internal, best (First path received) - Extended Community: RT:100:4000 ET:8 Rmac:50:00:00:01:00:06 - Last update: Thu May 11 13:31:13 2023 -``` diff --git a/docs/configexamples/autotest/OpenVPN_with_LDAP/_include/topology.png b/docs/configexamples/autotest/OpenVPN_with_LDAP/_include/topology.png new file mode 100644 index 00000000..382e44f6 Binary files /dev/null and b/docs/configexamples/autotest/OpenVPN_with_LDAP/_include/topology.png differ diff --git a/docs/configexamples/autotest/OpenVPN_with_LDAP/md-OpenVPN_with_LDAP.md b/docs/configexamples/autotest/OpenVPN_with_LDAP/md-OpenVPN_with_LDAP.md deleted file mode 100644 index bd1ccfc4..00000000 --- a/docs/configexamples/autotest/OpenVPN_with_LDAP/md-OpenVPN_with_LDAP.md +++ /dev/null @@ -1,238 +0,0 @@ -(examples-openvpn-with-ldap)= - -# OpenVPN with LDAP - -```{eval-rst} -| Testdate: 2023-05-11 -| Version: 1.4-rolling-202305100734 -``` - -This LAB shows how to use OpenVPN with a Active Directory authentication method. - -Topology consists of: -: - Windows Server 2019 with a running Active Directory - - VyOS as a OpenVPN Server - - VyOS as Client - -```{image} _include/topology.webp -:alt: OpenVPN with LDAP topology image -``` - - -## Active Directory on Windows server - -The lab assumes a full running Active Directory on the Windows Server. -Here are some PowerShell commands to quickly add a Test Active Directory. - -```powershell -# install the Active Directory Server role -Install-WindowsFeature AD-Domain-Services -IncludeManagementTools - -# install the Active Directory Server role -Install-ADDSForest -DomainName "vyos.local" -DomainNetBiosName "VYOS" -InstallDns:$true -NoRebootCompletion:$true - -# create test user01 and binduser -New-ADUser binduser -AccountPassword(Read-Host -AsSecureString "Input Password") -Enabled $true -New-ADUser user01 -AccountPassword(Read-Host -AsSecureString "Input Password") -Enabled $true -``` - - -## Configure VyOS as OpenVPN Server - -In this example OpenVPN will be setup with a client certificate and username / password authentication. - -First a CA, a signed server and client ceftificate and a Diffie-Hellman parameter musst be generated and installed. -Please look {ref}`here ` for more information. - -```{eval-rst} -| Add the LDAP plugin configuration file `/config/auth/ldap-auth.config` -``` - -```{eval-rst} -| Check all possible settings `here `_. -``` - -```{literalinclude} _include/ldap-auth.config -:language: none -``` - -Now generate all required certificates on the ovpn-server: - -First the CA - -```none -vyos@ovpn-server# run generate pki ca install OVPN-CA -``` - -after this create a signed server and a client certificate - -```none -vyos@ovpn-server# run generate pki certificate sign OVPN-CA install SRV -vyos@ovpn-server# run generate pki certificate sign OVPN-CA install CLIENT -``` - -and last the DH Key - -```none -vyos@ovpn-server# run generate pki dh install DH -``` - -after all these steps the config look like this: - -```none -set pki ca OVPN-CA certificate 'MIIFnTCCA4WgAwIBAgIUIPFIXvCxYdavCnSPFNjr6lUtlsswDQYJKoZIhvcNAQELBQAwVzELMAkGA1UEBhMCR0IxEzARBgNVBAgMClNvbWUtU3RhdGUxEjAQBgNVBAcMCVNvbWUtQ2l0eTENMAsGA1UECgwEVnlPUzEQMA4GA1UEAwwHdnlvcy5pbzAeFw0yMzA1MTExMjM4MjJaFw0zMzA1MDgxMjM4MjJaMFcxCzAJBgNVBAYTAkdCMRMwEQYDVQQIDApTb21lLVN0YXRlMRIwEAYDVQQHDAlTb21lLUNpdHkxDTALBgNVBAoMBFZ5T1MxEDAOBgNVBAMMB3Z5b3MuaW8wggIiMA0GCSqGSIb3DQEBAQUAA4ICDwAwggIKAoICAQDg45vAzS6xNqU+Pa7wk1Imt1/az1C22Sbp3wPJLfgOmy0K3TA5qVsx/c/8gatsatMkCsekGnK5BPzCDd5eCCLo//B25HFO6fBYRNvHvVyCUx7QEXw4FHFNG88zCIizx114AGtVwZfGGG9xCc53xjLPUpH6iqTXme41cCFFQlqXwZ7fuySieSdoV8SAsJTTOsGCEUEcDEnNPn6tX3KWTzNuyFPECy8WCmNgWNyG2nmH+U7WRTX0ehZ5dZyU5au7TxpRN4a+JtE0gNqcWJ+nh1A543q2pcRoQpPAzHFclgj8wG/EyauQMY/LC4tLc6moPaNlTwA9HJv8s6xUqpzNptDoUHKOqKuw2JRFnno5SCQ788KkKNgVWBy2o3BGoewfHFhAdR61CXeLpmuneuhi96GcM031gW8ptXbd4DkCF7H6KRtqeIvwiyG79ttC8kZf01Sn1fM5fTjGxaE38dAk/RchtHRC6rtFavHJjB2cUcCkhhQofUE6IR2dYJZ1cw0Wy5CI3bXHf43BpvDGmuxIlNGirTq8wf5RCWzDJJgmkQpYhUYe8x4faF4gTo00uH4ZvAYjQu3JNZGkb50p4kM9Mu5rQAiZJUeMAz/QD+EIV9xXgOk14+BbnHKWbZ7Ou5emewFuE/bjl79oNJklpXdc4soRkCPCTEGK3zDBdmUtCYk1DwIDAQABo2EwXzAPBgNVHRMBAf8EBTADAQH/MA4GA1UdDwEB/wQEAwIBhjAdBgNVHSUEFjAUBggrBgEFBQcDAgYIKwYBBQUHAwEwHQYDVR0OBBYEFP5NDac/yC+mQmaTpZDUv9GZMGMBMA0GCSqGSIb3DQEBCwUAA4ICAQDEqpF2ibwYFxsF1XDIPS5/Gs0sZTZBuByNm5d2+jTyO7d5alZUdbvobbwhxZOhWasmFNyPLr4TYmZm5zF+efFsiOxjyRuEoVU+Fe8rZmpRIF/+6+nYX5r9vMI4QxGjeeyP20OHJ85Kvz182CTsITrM15Vw/kVVjAVzFI5Gm/QolalAoFQza9rAL4kDqaUszjHjPbysvDpGF+NLPjiYDHXcty/BC48bnuzAeEM60SGZ7EXvf8l0X8YsO7z39w6780A/3rbZvFhCYMKp/+p5xBRDjnX91dM6DJw73RwYQ1KHbHk9wWUwnL1giL71jzp/y4Oj6SSK2PQv+OnO80J6Zg06WIQx9xYcxr108Xh9FotUrlG7GYPI3Udf95t6SjuydDhULAVD0lMBxlDe9DHW1k1q1pOXaHZg926tY66xx/lda6dcuwJjA2Dx5JI6L0u9ureQmQAtxvnoTCtf+hR1iX/IkskZCKs34SjNiCnBuw/DNfdOpfaABm7y+tWiXBwnu5l/K8poXcQYQByyZj6YMmpgsbVPr5KNsLWOgRA81M6IPof8qxvnFrkazhiQWh1YHSjnaHtA3z5/BdgwHVICuFyrIOlbkKyJOjKcKBsDdMwIV0tsnpnyli2xEPZKu1tAQFAavXrK/RGYYhOZ3e0aRSV8hlP8i/mf7p0I45cJiBCqPg==' -set pki ca OVPN-CA private key '' -set pki certificate SRV certificate 'MIIFtTCCA52gAwIBAgIUeZnSAMPohIvKL/1Fy/pW2cV73HkwDQYJKoZIhvcNAQELBQAwVzELMAkGA1UEBhMCR0IxEzARBgNVBAgMClNvbWUtU3RhdGUxEjAQBgNVBAcMCVNvbWUtQ2l0eTENMAsGA1UECgwEVnlPUzEQMA4GA1UEAwwHdnlvcy5pbzAeFw0yMzA1MTExMjM4MzFaFw0zMzA1MDgxMjM4MzFaMFsxCzAJBgNVBAYTAkdCMRMwEQYDVQQIDApTb21lLVN0YXRlMRIwEAYDVQQHDAlTb21lLUNpdHkxDTALBgNVBAoMBFZ5T1MxFDASBgNVBAMMC292cG4tc2VydmVyMIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEApDWzTcB5LFM/tacaRHvpchBKLigJ5FlqNNfJ2vnP87KfCmTA5tkWF7MtuY990tHZtl1vQ3Pim4d6XBOngiQmaw7tZeWAIrv1L2/VBjORUrLrQhkkg9nSpcYFxoyUQzukTY75PcwhYLkS6ZO/vPPSBuh97f3XR645Aauf7ZIk2NsUidP2uGZz/Sr5VC7ovH2l3zz1kIHPCinfvpPEVb5oTt7qEffk4vnKjy9RY+H1hZowvcAp1zfLaOt/dXaK6vfNutbmwDHbYAlIals0EcjtTr+63ymxmupn7RBjgWtK7MgocGZnt6HKJ4J6teP3WgiSd+I9pdFG4wHZOSVL3axf3rBx7q09DMn/Snvfbly+SlhXw9Ebk368J6j6rhNUkxo/M9fbfgxS0JnNjHInRNAvRQW5CgQfT9KyUdxR63BeSnngk2XYX+bDinb0ig+VDpZcr6PgOBR8aNFsCPbXRwDy0bmuFnFYMzs/7ZmFQhzE6rQykHvVvAsyv7FYrlW0E02H4+Xe6bEVpE1fLcH8OCGY2cfuTfq1Ax6R4r+tdHYW1kzFLjwdh3uqTLF11zcbkAwd78E/ItrfEadvgxrYR9gfhX79AkK0VHmZ/hzrLFeGznnVcqoTKgq21dfMfQG2P13QvqS7tCE5swM9N09ASVrifyVDuoL6jaW96wgeqR6eHMECAwEAAaN1MHMwDAYDVR0TAQH/BAIwADAOBgNVHQ8BAf8EBAMCB4AwEwYDVR0lBAwwCgYIKwYBBQUHAwEwHQYDVR0OBBYEFE1U3Zamfuv6ocYiF9q7H//U8h+AMB8GA1UdIwQYMBaAFP5NDac/yC+mQmaTpZDUv9GZMGMBMA0GCSqGSIb3DQEBCwUAA4ICAQBZwHvGj/jziNFwXS2W1Q11I12YANmVhISP39AA7DNhXR+E1hXFs+U52ehurZoLTi5YTjd8PD0KcE58mw8CLsFQB/+pni9EwJuAhpMb6XsmYEp0PeOH7C/q5eOc4TB/NBsvEa5IdTmUoewmjubKeJ8OHdRBMI77Me53lSC6iskc9DGyixSLqQogQW4aiTposFJOW/YugBy7kiuygmFNJv4luDbyRBb9131zH0qSSishLT4Bp5lXQNYWI4AU0JeyQcYaSHWCr0h6H9GN3QOf/emc3/2Tee40FcEMsszJBRnQ3IISzU5xVLlfU02SJMpjvFT2MGfHAs7obrNbwiFeoLZ6fQeGLe53aOQ5M9XeW5bdIeR2ZrLoO1hW33x5jYI8nLnU0FnqpMMY14r7LZE/mjwfdrTsGChFzsLasB0Tj++mGMOXw3DSusppub17AE2bO2uO6J9XMlbkOC8EmDCF1Hetija4D3aunhtu6jRBOcR8DHVBqNae2YgUk1ALqGrNUGFH4bEioTjDDx2GieOtp9rUwJMlkAyUEe0k/wzcBLjZaO8KBCtrmTdr1wMXizPT+XcjAlzRNXvHiZFq0NG5Rnim+LH9tp90EHzO7EeVXV+LegnIKQqboIrY3KOw5Qx8ska+t1WrWHpyzpwsA0WjA6sDTyWthgNYSxb1ikNGO8STCA==' -set pki certificate SRV private key '' -set pki certificate CLIENT certificate 'MIIFsDCCA5igAwIBAgIUSzQgwzGsfJFecGxCwLXVsGCLMkAwDQYJKoZIhvcNAQELBQAwVzELMAkGA1UEBhMCR0IxEzARBgNVBAgMClNvbWUtU3RhdGUxEjAQBgNVBAcMCVNvbWUtQ2l0eTENMAsGA1UECgwEVnlPUzEQMA4GA1UEAwwHdnlvcy5pbzAeFw0yMzA1MTExMjM4MzlaFw0zMzA1MDgxMjM4MzlaMFYxCzAJBgNVBAYTAkdCMRMwEQYDVQQIDApTb21lLVN0YXRlMRIwEAYDVQQHDAlTb21lLUNpdHkxDTALBgNVBAoMBFZ5T1MxDzANBgNVBAMMBmNsaWVudDCCAiIwDQYJKoZIhvcNAQEBBQADggIPADCCAgoCggIBANHNJOSwcDbRqziL1gXYnHIq7P7vEUFvS8d/XLYJ1xIpcYTRXTut2CTGRar7fZZicu7x0yoK4TzrHvGVf1o4NC4NSGV5RX6kwRdrfWBmvpIkjSLGtCREFyhb+PHDpnsIS7cfN9udC0vocqVlx/xM/sfcP6Vja/uFp+9TQcneJIxYw34zkF+TtOVbE3pP5VxU7ZAj8F5/q1ONhTMdzG4Ol4/0nBqZfdYA3LVDeSSNIJNF5jlaKXXFHz1EJRemTYDx+f5bfCVcK2Qs8fU9jCFBlATjMu9O5rgk6nMLRwEnJZuZ1gj2tWQvz4e9yo5yUqf1PUhOrn3c81MRliUNHKr+CkxgQJal6P3Ar3q4iftJih3K+/j4o194mQ/Dt/Et+/Qn/DUFk2FB0rTMcQwJLTEAzxtTdmBJeJpipIPDR0u7UMZLNh/raQ8s3FsbY4uYORt2f5YQlCVHbth4dRa9xa+oRbm7eomNACIbWfkLh5Bzud1+qIfdBMZKaZbnf0HEeuH0J5LBJeova8EPxWbYMJPrRHzu5gowkIKl+uIxcy8IiNTA9YEoJVonCjmlr8NEtYShrIVbicdMNSI3pOQR60MFhkHwBjSU2l/z+4wwLxtzq/c2xKw9yrOZ46ZVLwGDFq8rPwp7/P9r6mDKsbn6jIvGOeH71dMZvoc4lCaClw+hKIzLAgMBAAGjdTBzMAwGA1UdEwEB/wQCMAAwDgYDVR0PAQH/BAQDAgeAMBMGA1UdJQQMMAoGCCsGAQUFBwMCMB0GA1UdDgQWBBS6j30FmL6kZW7rDH8QjRMoWoA/njAfBgNVHSMEGDAWgBT+TQ2nP8gvpkJmk6WQ1L/RmTBjATANBgkqhkiG9w0BAQsFAAOCAgEANW2Y4bgaB9oexEjj6rkGvePtQmXRkF/adVQREY9iZDGTe72ePybVzrfMkZHjse3o7JvXWRIVVztWSzEpv5noIOX7lAioGG3wsFTHotTFR0zrYJHXHBcV2Neq4Kx2Ta/TZwD8QnZHAAxEQ1pYb4fxwN/A60VElAZoz9zYsbrJyVrfuHDL9queQxPFzqis+7W1BiVIcv4rn0DMQ560jTGh4t4rImOSu5gUsUrQaih85XDdOBPxViSNwfVdZJIgbvamudpfEaKsIun/uCjcxpNnzIp0rhyYmDeqVat4GnTV7Sy48e/Uvcq71ZWbBYJF4+yW4pylIU2Sh/Uy2sAz4C2M71FlFB7qsmcnPRsFFHf+r1NyD1lkVI9k2371fTG/Kub9V0rOz4pvKz4Em5b4MUPdDbZOqJ8hQ+atGE3ovFJIovA3NFb0OtnyC4l+kG7dfjqFudOnmDa+Qsya+2YOxBZBIRfuhlXhb6Y6Smsk9R6x0jBmcQTPS5ZmvKaTxQCFc53xMdQNAswjiI2L9rw4BcqQfVmf/vpoN+VusD/XEv2V0Ixm10YybA7BI/tixh9vwj3fdQXVLy3jSYjVBd5WOFPizbQZeD10ElvlLqZZyWrP/Wre7Nmi/gEOnhBXXmo034fFF/vXf0JRpQsd2oDs24+4XwZYb8mbM31j7Nx8YvhR+64=' -set pki certificate CLIENT private key '' -set pki dh DH parameters 'MIIBCAKCAQEAzPOQWrWaIX2qt4sbV6bRbUnFx4jmeE+WXC8GIvulnC4pIr1nt2Gc/7uNfEPjDZ4X6csD3X6zAWxtSuWeNuml9Yuy+tS8gI7d0FlbQRAFO/9GIlRuVdMcbCtEhg8ja7Y0g3fQjOSQJ9mqFo7sRoXyYQALD+MDEJOxhnV7neCrgDi1pqnN4xZLoR9DLARp0ad30VIvnv0ay55wxFWAKh2iwNRwyeXIEOtUDBkfcLGSNNfK0kQsos/J8Q+7YXmk4cN9tiVX4xR92edVO4z/vhMkjsGKLSDm/E6EMusX+N0UhQ3dv7qDgeSS8vDsqBm8XJonumNZLvFbYt2ARGRZYL6DUwIBAg==' -``` - -Once all the required certificates and keys are installed, the remaining -OpenVPN Server configuration can be carried out. - -```{literalinclude} _include/ovpn-server.conf -:language: none -``` - - -## Client configuration - -One advantage of having the client certificate stored is the ability to create the client configuration. - -```none -vyos@ovpn-server:~$ generate openvpn client-config interface vtun10 ca OVPN-CA certificate CLIENT -``` - -save the output to a file and import it in nearly all openvpn clients. - -```none -client -nobind -remote 198.51.100.254 1194 -remote-cert-tls server -proto udp -dev tun -dev-type tun -persist-key -persist-tun -verb 3 - -# Encryption options - -keysize 256 -comp-lzo no - - ------BEGIN CERTIFICATE----- -MIIFnTCCA4WgAwIBAgIUIPFIXvCxYdavCnSPFNjr6lUtlsswDQYJKoZIhvcNAQEL -BQAwVzELMAkGA1UEBhMCR0IxEzARBgNVBAgMClNvbWUtU3RhdGUxEjAQBgNVBAcM -CVNvbWUtQ2l0eTENMAsGA1UECgwEVnlPUzEQMA4GA1UEAwwHdnlvcy5pbzAeFw0y -MzA1MTExMjM4MjJaFw0zMzA1MDgxMjM4MjJaMFcxCzAJBgNVBAYTAkdCMRMwEQYD -VQQIDApTb21lLVN0YXRlMRIwEAYDVQQHDAlTb21lLUNpdHkxDTALBgNVBAoMBFZ5 -T1MxEDAOBgNVBAMMB3Z5b3MuaW8wggIiMA0GCSqGSIb3DQEBAQUAA4ICDwAwggIK -AoICAQDg45vAzS6xNqU+Pa7wk1Imt1/az1C22Sbp3wPJLfgOmy0K3TA5qVsx/c/8 -gatsatMkCsekGnK5BPzCDd5eCCLo//B25HFO6fBYRNvHvVyCUx7QEXw4FHFNG88z -CIizx114AGtVwZfGGG9xCc53xjLPUpH6iqTXme41cCFFQlqXwZ7fuySieSdoV8SA -sJTTOsGCEUEcDEnNPn6tX3KWTzNuyFPECy8WCmNgWNyG2nmH+U7WRTX0ehZ5dZyU -5au7TxpRN4a+JtE0gNqcWJ+nh1A543q2pcRoQpPAzHFclgj8wG/EyauQMY/LC4tL -c6moPaNlTwA9HJv8s6xUqpzNptDoUHKOqKuw2JRFnno5SCQ788KkKNgVWBy2o3BG -oewfHFhAdR61CXeLpmuneuhi96GcM031gW8ptXbd4DkCF7H6KRtqeIvwiyG79ttC -8kZf01Sn1fM5fTjGxaE38dAk/RchtHRC6rtFavHJjB2cUcCkhhQofUE6IR2dYJZ1 -cw0Wy5CI3bXHf43BpvDGmuxIlNGirTq8wf5RCWzDJJgmkQpYhUYe8x4faF4gTo00 -uH4ZvAYjQu3JNZGkb50p4kM9Mu5rQAiZJUeMAz/QD+EIV9xXgOk14+BbnHKWbZ7O -u5emewFuE/bjl79oNJklpXdc4soRkCPCTEGK3zDBdmUtCYk1DwIDAQABo2EwXzAP -BgNVHRMBAf8EBTADAQH/MA4GA1UdDwEB/wQEAwIBhjAdBgNVHSUEFjAUBggrBgEF -BQcDAgYIKwYBBQUHAwEwHQYDVR0OBBYEFP5NDac/yC+mQmaTpZDUv9GZMGMBMA0G -CSqGSIb3DQEBCwUAA4ICAQDEqpF2ibwYFxsF1XDIPS5/Gs0sZTZBuByNm5d2+jTy -O7d5alZUdbvobbwhxZOhWasmFNyPLr4TYmZm5zF+efFsiOxjyRuEoVU+Fe8rZmpR -IF/+6+nYX5r9vMI4QxGjeeyP20OHJ85Kvz182CTsITrM15Vw/kVVjAVzFI5Gm/Qo -lalAoFQza9rAL4kDqaUszjHjPbysvDpGF+NLPjiYDHXcty/BC48bnuzAeEM60SGZ -7EXvf8l0X8YsO7z39w6780A/3rbZvFhCYMKp/+p5xBRDjnX91dM6DJw73RwYQ1KH -bHk9wWUwnL1giL71jzp/y4Oj6SSK2PQv+OnO80J6Zg06WIQx9xYcxr108Xh9FotU -rlG7GYPI3Udf95t6SjuydDhULAVD0lMBxlDe9DHW1k1q1pOXaHZg926tY66xx/ld -a6dcuwJjA2Dx5JI6L0u9ureQmQAtxvnoTCtf+hR1iX/IkskZCKs34SjNiCnBuw/D -NfdOpfaABm7y+tWiXBwnu5l/K8poXcQYQByyZj6YMmpgsbVPr5KNsLWOgRA81M6I -Pof8qxvnFrkazhiQWh1YHSjnaHtA3z5/BdgwHVICuFyrIOlbkKyJOjKcKBsDdMwI -V0tsnpnyli2xEPZKu1tAQFAavXrK/RGYYhOZ3e0aRSV8hlP8i/mf7p0I45cJiBCq -Pg== ------END CERTIFICATE----- - - - - ------BEGIN CERTIFICATE----- -MIIFsDCCA5igAwIBAgIUSzQgwzGsfJFecGxCwLXVsGCLMkAwDQYJKoZIhvcNAQEL -BQAwVzELMAkGA1UEBhMCR0IxEzARBgNVBAgMClNvbWUtU3RhdGUxEjAQBgNVBAcM -CVNvbWUtQ2l0eTENMAsGA1UECgwEVnlPUzEQMA4GA1UEAwwHdnlvcy5pbzAeFw0y -MzA1MTExMjM4MzlaFw0zMzA1MDgxMjM4MzlaMFYxCzAJBgNVBAYTAkdCMRMwEQYD -VQQIDApTb21lLVN0YXRlMRIwEAYDVQQHDAlTb21lLUNpdHkxDTALBgNVBAoMBFZ5 -T1MxDzANBgNVBAMMBmNsaWVudDCCAiIwDQYJKoZIhvcNAQEBBQADggIPADCCAgoC -ggIBANHNJOSwcDbRqziL1gXYnHIq7P7vEUFvS8d/XLYJ1xIpcYTRXTut2CTGRar7 -fZZicu7x0yoK4TzrHvGVf1o4NC4NSGV5RX6kwRdrfWBmvpIkjSLGtCREFyhb+PHD -pnsIS7cfN9udC0vocqVlx/xM/sfcP6Vja/uFp+9TQcneJIxYw34zkF+TtOVbE3pP -5VxU7ZAj8F5/q1ONhTMdzG4Ol4/0nBqZfdYA3LVDeSSNIJNF5jlaKXXFHz1EJRem -TYDx+f5bfCVcK2Qs8fU9jCFBlATjMu9O5rgk6nMLRwEnJZuZ1gj2tWQvz4e9yo5y -Uqf1PUhOrn3c81MRliUNHKr+CkxgQJal6P3Ar3q4iftJih3K+/j4o194mQ/Dt/Et -+/Qn/DUFk2FB0rTMcQwJLTEAzxtTdmBJeJpipIPDR0u7UMZLNh/raQ8s3FsbY4uY -ORt2f5YQlCVHbth4dRa9xa+oRbm7eomNACIbWfkLh5Bzud1+qIfdBMZKaZbnf0HE -euH0J5LBJeova8EPxWbYMJPrRHzu5gowkIKl+uIxcy8IiNTA9YEoJVonCjmlr8NE -tYShrIVbicdMNSI3pOQR60MFhkHwBjSU2l/z+4wwLxtzq/c2xKw9yrOZ46ZVLwGD -Fq8rPwp7/P9r6mDKsbn6jIvGOeH71dMZvoc4lCaClw+hKIzLAgMBAAGjdTBzMAwG -A1UdEwEB/wQCMAAwDgYDVR0PAQH/BAQDAgeAMBMGA1UdJQQMMAoGCCsGAQUFBwMC -MB0GA1UdDgQWBBS6j30FmL6kZW7rDH8QjRMoWoA/njAfBgNVHSMEGDAWgBT+TQ2n -P8gvpkJmk6WQ1L/RmTBjATANBgkqhkiG9w0BAQsFAAOCAgEANW2Y4bgaB9oexEjj -6rkGvePtQmXRkF/adVQREY9iZDGTe72ePybVzrfMkZHjse3o7JvXWRIVVztWSzEp -v5noIOX7lAioGG3wsFTHotTFR0zrYJHXHBcV2Neq4Kx2Ta/TZwD8QnZHAAxEQ1pY -b4fxwN/A60VElAZoz9zYsbrJyVrfuHDL9queQxPFzqis+7W1BiVIcv4rn0DMQ560 -jTGh4t4rImOSu5gUsUrQaih85XDdOBPxViSNwfVdZJIgbvamudpfEaKsIun/uCjc -xpNnzIp0rhyYmDeqVat4GnTV7Sy48e/Uvcq71ZWbBYJF4+yW4pylIU2Sh/Uy2sAz -4C2M71FlFB7qsmcnPRsFFHf+r1NyD1lkVI9k2371fTG/Kub9V0rOz4pvKz4Em5b4 -MUPdDbZOqJ8hQ+atGE3ovFJIovA3NFb0OtnyC4l+kG7dfjqFudOnmDa+Qsya+2YO -xBZBIRfuhlXhb6Y6Smsk9R6x0jBmcQTPS5ZmvKaTxQCFc53xMdQNAswjiI2L9rw4 -BcqQfVmf/vpoN+VusD/XEv2V0Ixm10YybA7BI/tixh9vwj3fdQXVLy3jSYjVBd5W -OFPizbQZeD10ElvlLqZZyWrP/Wre7Nmi/gEOnhBXXmo034fFF/vXf0JRpQsd2oDs -24+4XwZYb8mbM31j7Nx8YvhR+64= ------END CERTIFICATE----- - - - - ------BEGIN PRIVATE KEY----- -...REDACTED... ------END PRIVATE KEY----- - - -``` - - -### Configure VyOS as client - -```none -set interfaces openvpn vtun10 authentication username 'user01' -set interfaces openvpn vtun10 authentication password '$ecret' -set interfaces openvpn vtun10 encryption cipher '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 '198.51.100.254' -set interfaces openvpn vtun10 remote-port '1194' -set interfaces openvpn vtun10 tls ca-certificate 'OVPN-CA' -set interfaces openvpn vtun10 tls certificate 'CLIENT' -``` - - -## Monitoring - -If the client is connected successfully you can check the status - -```none -vyos@ovpn-server:~$ show openvpn server -OpenVPN status on vtun10 - -Client CN Remote Host Tunnel IP Local Host TX bytes RX bytes Connected Since ------------ ------------------ ----------- ------------------- ---------- ---------- ------------------- -client 198.51.100.1:55150 10.23.1.6 198.51.100.254:1194 4.7 KB 4.7 KB 2023-05-11 12:47:11 -``` diff --git a/docs/configexamples/autotest/Wireguard/_include/topology.png b/docs/configexamples/autotest/Wireguard/_include/topology.png new file mode 100644 index 00000000..43c0018e Binary files /dev/null and b/docs/configexamples/autotest/Wireguard/_include/topology.png differ diff --git a/docs/configexamples/autotest/Wireguard/md-Wireguard.md b/docs/configexamples/autotest/Wireguard/md-Wireguard.md deleted file mode 100644 index 7bbf4c55..00000000 --- a/docs/configexamples/autotest/Wireguard/md-Wireguard.md +++ /dev/null @@ -1,108 +0,0 @@ -# Wireguard - -```{eval-rst} -| Testdate: 2024-01-13 -| Version: 1.5-rolling-202401121239 -``` - -This simple structure show how to connect two offices. One remote branch and the -central office. - -## Topology - -The topology have a central and a branch VyOS router and one client, to -test, in each site. - -```{image} _include/topology.webp -:alt: Ansible Example topology image -``` - - -## Configuration - -Set the local subnet on eth2 and the public ip address eth1 on each site. - -Central - -```{literalinclude} _include/central.conf -:language: none -:lines: 1-2 -``` - -Branch - -```{literalinclude} _include/branch.conf -:language: none -:lines: 1-2 -``` - -Next thing to do, is to create a wireguard keypair on each side. -After this, the public key can be displayed, to save for later. - -```none -vyos@central:~$ generate pki wireguard -Private key: wHQS+ib3eMIp2DxRiAeXfFVaSCMMP1YHBaKfSR1xfV8= -Public key: RCMy6BAER0uEcPvspUb3K38MHyHJpK5kiV5IOX943HI= -``` - -After you have each public key. The wireguard interfaces can be setup. - -Central - -```{literalinclude} _include/central.conf -:language: none -:lines: 4-12 -``` - -Branch - -```{literalinclude} _include/branch.conf -:language: none -:lines: 4-12 -``` - -To reach the network, a route must be set on each VyOS host. -In this structure, a static interface route will fit the requirements. - -Central - -```{literalinclude} _include/central.conf -:language: none -:lines: 14 -``` - -Branch - -```{literalinclude} _include/branch.conf -:language: none -:lines: 14 -``` - - -## Testing and debugging - -After all is done and commit, let's take a look if the Wireguard interface is -up and running. - -```none -vyos@central:~$ show interfaces wireguard -Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down -Interface IP Address S/L Description ---------- ---------- --- ----------- -wg01 192.168.0.1/24 u/u VPN-to-Branch -``` - -And ping the Branch PC from your central router to check the response. - -```none -vyos@central:~$ ping 10.0.2.100 count 4 -PING 10.0.2.100 (10.0.2.100) 56(84) bytes of data. -64 bytes from 10.0.2.100: icmp_seq=1 ttl=63 time=0.894 ms -64 bytes from 10.0.2.100: icmp_seq=2 ttl=63 time=0.869 ms -64 bytes from 10.0.2.100: icmp_seq=3 ttl=63 time=0.966 ms -64 bytes from 10.0.2.100: icmp_seq=4 ttl=63 time=0.998 ms - ---- 10.0.2.100 ping statistics --- -4 packets transmitted, 4 received, 0% packet loss, time 3004ms -rtt min/avg/max/mdev = 0.869/0.931/0.998/0.052 ms -``` diff --git a/docs/configexamples/autotest/tunnelbroker/_include/topology.png b/docs/configexamples/autotest/tunnelbroker/_include/topology.png new file mode 100644 index 00000000..e70d55bc Binary files /dev/null and b/docs/configexamples/autotest/tunnelbroker/_include/topology.png differ diff --git a/docs/configexamples/autotest/tunnelbroker/md-tunnelbroker.md b/docs/configexamples/autotest/tunnelbroker/md-tunnelbroker.md deleted file mode 100644 index 6c59a491..00000000 --- a/docs/configexamples/autotest/tunnelbroker/md-tunnelbroker.md +++ /dev/null @@ -1,206 +0,0 @@ -(examples-tunnelbroker-ipv6)= - -# Tunnelbroker.net (IPv6) - -```{eval-rst} -| Testdate: 2024-01-13 -| Version: 1.5-rolling-202401121239 -``` - -This guide walks through the setup of for an -IPv6 Tunnel. - -## Prerequisites - -- A public, routable IPv4 address. This does not necessarily need to be static, - but you will need to update the tunnel endpoint when/if your IP address - changes, which can be done with a script and a scheduled task. -- Account at -- Requested a "Regular Tunnel". You want to choose a location that is closest - to your physical location for the best response time. - -### Topology - -The example topology has 2 VyOS routers. One as the WAN router and one as a -client, to test a single LAN setup - -```{image} _include/topology.webp -:alt: Tunnelbroker topology image -``` - - -### Configuration - -First, we configure the `vyos-wan` interface to get a DHCP address. - -```{literalinclude} _include/vyos-wan.conf -:language: none -``` - -Now we are able to setup the tunnel interface. - -```{literalinclude} _include/vyos-wan_tun0.conf -:language: none -:lines: 1-5 -``` - -:::{note} -The `source-address` is the Tunnelbroker client IPv4 -address or if there is NAT the current WAN interface address. - -If `source-address` is dynamic, the tunnel will cease working once -the address changes. To avoid having to manually update -`source-address` each time the dynamic IP changes, an address of -'0.0.0.0' can be specified. -::: - -Setup the IPv6 default route to the tunnel interface - -```{literalinclude} _include/vyos-wan_tun0.conf -:language: none -:lines: 7 -``` - -Now you should be able to ping a public IPv6 Address - -```none -vyos@vyos-wan:~$ ping 2001:470:20::2 count 4 -PING 2001:470:20::2(2001:470:20::2) 56 data bytes -64 bytes from 2001:470:20::2: icmp_seq=1 ttl=64 time=33.8 ms -64 bytes from 2001:470:20::2: icmp_seq=2 ttl=64 time=43.9 ms -64 bytes from 2001:470:20::2: icmp_seq=3 ttl=64 time=43.4 ms -64 bytes from 2001:470:20::2: icmp_seq=4 ttl=64 time=42.5 ms - ---- 2001:470:20::2 ping statistics --- -4 packets transmitted, 4 received, 0% packet loss, time 2999ms -rtt min/avg/max/mdev = 33.802/40.920/43.924/4.139 ms -``` - -Assuming the pings are successful, you need to add some DNS servers. -Some options: - -```{literalinclude} _include/vyos-wan_tun0.conf -:language: none -:lines: 13 -``` - -You should now be able to ping something by IPv6 DNS name: - -```none -vyos@vyos-wan:~$ ping tunnelbroker.net count 4 -PING tunnelbroker.net(tunnelbroker.net (2001:470:0:63::2)) 56 data bytes -64 bytes from tunnelbroker.net (2001:470:0:63::2): icmp_seq=1 ttl=48 time=285 ms -64 bytes from tunnelbroker.net (2001:470:0:63::2): icmp_seq=2 ttl=48 time=186 ms -64 bytes from tunnelbroker.net (2001:470:0:63::2): icmp_seq=3 ttl=48 time=178 ms -64 bytes from tunnelbroker.net (2001:470:0:63::2): icmp_seq=4 ttl=48 time=177 ms - ---- tunnelbroker.net ping statistics --- -4 packets transmitted, 4 received, 0% packet loss, time 3002ms -rtt min/avg/max/mdev = 176.707/206.638/285.128/45.457 ms -``` - - -### LAN Configuration - -At this point, your VyOS install should have full IPv6, but now your LAN devices -need access. - -With Tunnelbroker.net, you have two options: - -- Routed /64. This is the default assignment. In IPv6-land, it's good for a - single "LAN", and is somewhat equivalent to a /24. -- Routed /48. This is something you can request by clicking the "Assign /48" - link in the Tunnelbroker.net tunnel config. It allows you to have up to 65k - -Unlike IPv4, IPv6 is really not designed to be broken up smaller than /64. So -if you ever want to have multiple LANs, VLANs, DMZ, etc, you'll want to ignore -the assigned /64, and request the /48 and use that. - -## Single LAN Setup - -Single LAN setup where eth2 is your LAN interface. Use the Tunnelbroker -Routed /64 prefix: - -```{literalinclude} _include/vyos-wan_tun0.conf -:language: none -:lines: 9-11 -``` - -Please note, 'autonomous-flag' and 'on-link-flag' are enabled by default, -'valid-lifetime' and 'preferred-lifetime' are set to default values of -30 days and 4 hours respectively. - -And the `client` to receive an IPv6 address with stateless autoconfig. - -```{literalinclude} _include/client.conf -:language: none -``` - -This accomplishes a few things: -- Sets your LAN interface's IP address -- Enables router advertisements. This is an IPv6 alternative for DHCP (though - DHCPv6 can still be used). With RAs, Your devices will automatically find the - information they need for routing and DNS. - -Now the Client is able to ping a public IPv6 address - -```none -vyos@client:~$ ping 2001:470:20::2 count 4 -PING 2001:470:20::2(2001:470:20::2) 56 data bytes -64 bytes from 2001:470:20::2: icmp_seq=1 ttl=63 time=32.1 ms -64 bytes from 2001:470:20::2: icmp_seq=2 ttl=63 time=41.8 ms -64 bytes from 2001:470:20::2: icmp_seq=3 ttl=63 time=41.7 ms -64 bytes from 2001:470:20::2: icmp_seq=4 ttl=63 time=47.1 ms - ---- 2001:470:20::2 ping statistics --- -4 packets transmitted, 4 received, 0% packet loss, time 3005ms -rtt min/avg/max/mdev = 32.128/40.688/47.107/5.403 ms -``` - - -## Multiple LAN/DMZ Setup - -That's how you can expand the example above. -Use the `Routed /48` information. This allows you to assign a -different /64 to every interface, LAN, or even device. Or you could break your -network into smaller chunks like /56 or /60. - -The format of these addresses: -- `2001:470:xxxx::/48`: The whole subnet. xxxx should come from Tunnelbroker. -- `2001:470:xxxx:1::/64`: A subnet suitable for a LAN -- `2001:470:xxxx:2::/64`: Another subnet -- `2001:470:xxxx:ffff::/64`: The last usable /64 subnet. - -In the above examples, 1,2,ffff are all chosen by you. You can use 1-ffff -(1-65535). - -So, when your LAN is eth1, your DMZ is eth2, your cameras are on eth3, etc: - -```none -set interfaces ethernet eth1 address '2001:470:xxxx:1::1/64' -set service router-advert interface eth1 name-server '2001:470:20::2' -set service router-advert interface eth1 prefix 2001:470:xxxx:1::/64 - -set interfaces ethernet eth2 address '2001:470:xxxx:2::1/64' -set service router-advert interface eth2 name-server '2001:470:20::2' -set service router-advert interface eth2 prefix 2001:470:xxxx:2::/64 - -set interfaces ethernet eth3 address '2001:470:xxxx:3::1/64' -set service router-advert interface eth3 name-server '2001:470:20::2' -set service router-advert interface eth3 prefix 2001:470:xxxx:3::/64 -``` - -Please note, 'autonomous-flag' and 'on-link-flag' are enabled by default, -'valid-lifetime' and 'preferred-lifetime' are set to default values of -30 days and 4 hours respectively. - -## Firewall - -Finally, don't forget the -{ref}`Firewall `. The usage is -identical, except instead of `set firewall ipv4 name NAME`, you would -use `set firewall ipv6 name NAME`. - -Similarly, to attach the firewall, you would use -`set firewall ipv6 name NAME rule N inbound-interface name eth0` or -`set firewall zone LOCAL from WAN firewall ipv6-name`. diff --git a/docs/configexamples/md-ansible.md b/docs/configexamples/md-ansible.md deleted file mode 100644 index 8bbd9306..00000000 --- a/docs/configexamples/md-ansible.md +++ /dev/null @@ -1,212 +0,0 @@ ---- -lastproofread: '2024-04-09' ---- - -(examples-ansible)= - -# Ansible example - -## Setting up Ansible on a server running the Debian operating system. - -In this example, we will set up a simple use of Ansible to configure -multiple VyOS routers. -We have four pre-configured routers with this configuration: - -Using the general schema for example: - -```{image} /_static/images/ansible.webp -:align: center -:alt: Network Topology Diagram -:width: 80% -``` - -We have four pre-configured routers with this configuration: - -```none -set interfaces ethernet eth0 address dhcp -set service ssh -commit -save -``` - -- vyos7 - 192.0.2.105 -- vyos8 - 192.0.2.106 -- vyos9 - 192.0.2.107 -- vyos10 - 192.0.2.108 - -## Install Ansible: - -```none -# apt-get install ansible -Do you want to continue? [Y/n] y -``` - - -## Install Paramiko: - -```none -#apt-get install -y python3-paramiko -``` - - -## Check the version: - -```none -# ansible --version -ansible 2.10.8 -config file = None -configured module search path = ['/root/.ansible/plugins/modules', '/usr/share/ansible/plugins/modules'] -ansible python module location = /usr/lib/python3/dist-packages/ansible -executable location = /usr/bin/ansible -python version = 3.9.2 (default, Feb 28 2021, 17:03:44) [GCC 10.2.1 20210110] -``` - - -## Basic configuration of ansible.cfg: - -```none -# nano /root/ansible.cfg -[defaults] -host_key_checking = no -``` - - -## Add all the VyOS hosts: - -```none -# nano /root/hosts -[vyos_hosts] -vyos7 ansible_ssh_host=192.0.2.105 -vyos8 ansible_ssh_host=192.0.2.106 -vyos9 ansible_ssh_host=192.0.2.107 -vyos10 ansible_ssh_host=192.0.2.108 -``` - - -## Add general variables: - -```none -# mkdir /root/group_vars/ -# nano /root/group_vars/vyos_hosts -ansible_python_interpreter: /usr/bin/python3 -ansible_network_os: vyos -ansible_connection: network_cli -ansible_user: vyos -ansible_ssh_pass: vyos -``` - - -## Add a simple playbook with the tasks for each router: - -```none -# nano /root/main.yml - ---- -- hosts: vyos_hosts - gather_facts: 'no' - tasks: - - name: Configure general settings for the vyos hosts group - vyos_config: - lines: - - set system name-server 192.0.2.1 - - set interfaces ethernet eth0 description '#WAN#' - - set interfaces ethernet eth1 description '#LAN#' - - set interfaces ethernet eth2 disable - - set interfaces ethernet eth3 disable - - set system host-name {{ inventory_hostname }} - save: true -``` - - -## Start the playbook: - -```none -ansible-playbook -i hosts main.yml -PLAY [vyos_hosts] ************************************************************** - -TASK [Configure general settings for the vyos hosts group] ********************* -ok: [vyos9] -ok: [vyos10] -ok: [vyos7] -ok: [vyos8] - -PLAY RECAP ********************************************************************* -vyos10 : ok=2 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 -vyos7 : ok=2 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 -vyos8 : ok=2 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 -vyos9 : ok=2 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 -``` - - -## Check the result on the vyos10 router: - -```none -vyos@vyos10:~$ show interfaces -Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down -Interface IP Address S/L Description ---------- ---------- --- ----------- -eth0 192.0.2.108/24 u/u WAN -eth1 - u/u LAN -eth2 - A/D -eth3 - A/D -lo 127.0.0.1/8 u/u - ::1/128 - -vyos@vyos10:~$ sh configuration commands | grep 192.0.2.1 -set system name-server '192.0.2.1' -``` - - -## The simple way without configuration of the hostname (one task for all routers): - -```none -# nano /root/hosts_v2 -[vyos_hosts_group] -vyos7 ansible_ssh_host=192.0.2.105 -vyos8 ansible_ssh_host=192.0.2.106 -vyos9 ansible_ssh_host=192.0.2.107 -vyos10 ansible_ssh_host=192.0.2.108 -[vyos_hosts_group:vars] -ansible_python_interpreter=/usr/bin/python3 -ansible_user=vyos -ansible_ssh_pass=vyos -ansible_network_os=vyos -ansible_connection=network_cli - -# nano /root/main_v2.yml ---- -- hosts: vyos_hosts_group - connection: network_cli - gather_facts: 'no' - tasks: - - name: Configure remote vyos_hosts_group - vyos_config: - lines: - - set system name-server 192.0.2.1 - - set interfaces ethernet eth0 description WAN - - set interfaces ethernet eth1 description LAN - - set interfaces ethernet eth2 disable - - set interfaces ethernet eth3 disable - save: true -``` - -```none -# ansible-playbook -i hosts_v2 main_v2.yml - -PLAY [vyos_hosts_group] ******************************************************** - -TASK [Configure remote vyos_hosts_group] *************************************** -ok: [vyos8] -ok: [vyos7] -ok: [vyos9] -ok: [vyos10] - -PLAY RECAP ********************************************************************* -vyos10 : ok=1 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 -vyos7 : ok=1 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 -vyos8 : ok=1 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 -vyos9 : ok=1 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 -``` - -In the next chapter of the example, we'll use Ansible with jinja2 -templates and variables. diff --git a/docs/configexamples/md-azure-vpn-bgp.md b/docs/configexamples/md-azure-vpn-bgp.md deleted file mode 100644 index 83d77e53..00000000 --- a/docs/configexamples/md-azure-vpn-bgp.md +++ /dev/null @@ -1,134 +0,0 @@ ---- -lastproofread: '2021-06-28' ---- - -(examples-azure-vpn-bgp)= - -# Route-Based Site-to-Site VPN to Azure (BGP over IKEv2/IPsec) - -This guide shows an example of a route-based IKEv2 site-to-site VPN to -Azure using VTI and BGP for dynamic routing updates. - -For redundant / active-active configurations see -{ref}`examples-azure-vpn-dual-bgp` - -## Prerequisites - -- A pair of Azure VNet Gateways deployed in active-passive - configuration with BGP enabled. -- A local network gateway deployed in Azure representing - the Vyos device, matching the below Vyos settings except for - address space, which only requires the Vyos private IP, in - this example 10.10.0.5/32 -- A connection resource deployed in Azure linking the - Azure VNet gateway and the local network gateway representing - the Vyos device. - -## Example - -```{eval-rst} -+---------------------------------------+---------------------+ -| WAN Interface | eth0 | -+---------------------------------------+---------------------+ -| On-premises address space | 10.10.0.0/16 | -+---------------------------------------+---------------------+ -| Azure address space | 10.0.0.0/16 | -+---------------------------------------+---------------------+ -| Vyos public IP | 198.51.100.3 | -+---------------------------------------+---------------------+ -| Vyos private IP | 10.10.0.5 | -+---------------------------------------+---------------------+ -| Azure VNet Gateway public IP | 203.0.113.2 | -+---------------------------------------+---------------------+ -| Azure VNet Gateway BGP IP | 10.0.0.4 | -+---------------------------------------+---------------------+ -| Pre-shared key | ch00s3-4-s3cur3-psk | -+---------------------------------------+---------------------+ -| Vyos ASN | 64499 | -+---------------------------------------+---------------------+ -| Azure ASN | 65540 | -+---------------------------------------+---------------------+ -``` - -## Vyos configuration - -- Configure the IKE and ESP settings to match a subset - of those supported by Azure: - -```none -set vpn ipsec esp-group AZURE lifetime '3600' -set vpn ipsec esp-group AZURE mode 'tunnel' -set vpn ipsec esp-group AZURE pfs 'dh-group2' -set vpn ipsec esp-group AZURE proposal 1 encryption 'aes256' -set vpn ipsec esp-group AZURE proposal 1 hash 'sha1' - -set vpn ipsec ike-group AZURE dead-peer-detection action 'restart' -set vpn ipsec ike-group AZURE dead-peer-detection interval '15' -set vpn ipsec ike-group AZURE dead-peer-detection timeout '30' -set vpn ipsec ike-group AZURE ikev2-reauth -set vpn ipsec ike-group AZURE key-exchange 'ikev2' -set vpn ipsec ike-group AZURE lifetime '28800' -set vpn ipsec ike-group AZURE proposal 1 dh-group '2' -set vpn ipsec ike-group AZURE proposal 1 encryption 'aes256' -set vpn ipsec ike-group AZURE proposal 1 hash 'sha1' -``` - -- Enable IPsec on eth0 - -```none -set vpn ipsec interface 'eth0' -``` - -- Configure a VTI with a dummy IP address - -```none -set interfaces vti vti1 address '10.10.1.5/32' -set interfaces vti vti1 description 'Azure Tunnel' -``` - -- Clamp the VTI's MSS to 1350 to avoid PMTU blackholes. - -```none -set interfaces vti vti1 ip adjust-mss 1350 -``` - -- Configure the VPN tunnel - -```none -set vpn ipsec authentication psk azure id '198.51.100.3' -set vpn ipsec authentication psk azure id '203.0.113.2' -set vpn ipsec authentication psk azure secret 'ch00s3-4-s3cur3-psk' -set vpn ipsec site-to-site peer 203.0.113.2 authentication local-id '198.51.100.3' -set vpn ipsec site-to-site peer 203.0.113.2 authentication mode 'pre-shared-secret' -set vpn ipsec site-to-site peer 203.0.113.2 authentication remote-id '203.0.113.2' -set vpn ipsec site-to-site peer 203.0.113.2 connection-type 'initiate' -set vpn ipsec site-to-site peer 203.0.113.2 description 'AZURE PRIMARY TUNNEL' -set vpn ipsec site-to-site peer 203.0.113.2 ike-group 'AZURE' -set vpn ipsec site-to-site peer 203.0.113.2 ikev2-reauth 'inherit' -set vpn ipsec site-to-site peer 203.0.113.2 local-address '10.10.0.5' -set vpn ipsec site-to-site peer 203.0.113.2 remote-address '203.0.113.2' -set vpn ipsec site-to-site peer 203.0.113.2 vti bind 'vti1' -set vpn ipsec site-to-site peer 203.0.113.2 vti esp-group 'AZURE' -``` - -- **Important**: Add an interface route to reach Azure's BGP listener - -```none -set protocols static route 10.0.0.4/32 interface vti1 -``` - -- Configure your BGP settings - -```none -set protocols bgp system-as 64499 -set protocols bgp neighbor 10.0.0.4 remote-as '65540' -set protocols bgp neighbor 10.0.0.4 address-family ipv4-unicast soft-reconfiguration 'inbound' -set protocols bgp neighbor 10.0.0.4 timers holdtime '30' -set protocols bgp neighbor 10.0.0.4 timers keepalive '10' -``` - -- **Important**: Disable connected check - -```none -set protocols bgp neighbor 10.0.0.4 disable-connected-check -``` diff --git a/docs/configexamples/md-azure-vpn-dual-bgp.md b/docs/configexamples/md-azure-vpn-dual-bgp.md deleted file mode 100644 index 967debd4..00000000 --- a/docs/configexamples/md-azure-vpn-dual-bgp.md +++ /dev/null @@ -1,160 +0,0 @@ ---- -lastproofread: '2021-06-28' ---- - -(examples-azure-vpn-dual-bgp)= - -# Route-Based Redundant Site-to-Site VPN to Azure (BGP over IKEv2/IPsec) - -This guide shows an example of a redundant (active-active) route-based IKEv2 -site-to-site VPN to Azure using VTI -and BGP for dynamic routing updates. - -## Prerequisites - -- A pair of Azure VNet Gateways deployed in active-active - configuration with BGP enabled. -- A local network gateway deployed in Azure representing - the Vyos device, matching the below Vyos settings except for - address space, which only requires the Vyos private IP, in - this example 10.10.0.5/32 -- A connection resource deployed in Azure linking the - Azure VNet gateway and the local network gateway representing - the Vyos device. - -## Example - -```{eval-rst} -+---------------------------------------+---------------------+ -| WAN Interface | eth0 | -+---------------------------------------+---------------------+ -| On-premises address space | 10.10.0.0/16 | -+---------------------------------------+---------------------+ -| Azure address space | 10.0.0.0/16 | -+---------------------------------------+---------------------+ -| Vyos public IP | 198.51.100.3 | -+---------------------------------------+---------------------+ -| Vyos private IP | 10.10.0.5 | -+---------------------------------------+---------------------+ -| Azure VNet Gateway 1 public IP | 203.0.113.2 | -+---------------------------------------+---------------------+ -| Azure VNet Gateway 2 public IP | 203.0.113.3 | -+---------------------------------------+---------------------+ -| Azure VNet Gateway BGP IP | 10.0.0.4,10.0.0.5 | -+---------------------------------------+---------------------+ -| Pre-shared key | ch00s3-4-s3cur3-psk | -+---------------------------------------+---------------------+ -| Vyos ASN | 64499 | -+---------------------------------------+---------------------+ -| Azure ASN | 65540 | -+---------------------------------------+---------------------+ -``` - -## Vyos configuration - -- Configure the IKE and ESP settings to match a subset - of those supported by Azure: - -```none -set vpn ipsec esp-group AZURE lifetime '3600' -set vpn ipsec esp-group AZURE mode 'tunnel' -set vpn ipsec esp-group AZURE pfs 'dh-group2' -set vpn ipsec esp-group AZURE proposal 1 encryption 'aes256' -set vpn ipsec esp-group AZURE proposal 1 hash 'sha1' - -set vpn ipsec ike-group AZURE dead-peer-detection action 'restart' -set vpn ipsec ike-group AZURE dead-peer-detection interval '15' -set vpn ipsec ike-group AZURE dead-peer-detection timeout '30' -set vpn ipsec ike-group AZURE ikev2-reauth -set vpn ipsec ike-group AZURE key-exchange 'ikev2' -set vpn ipsec ike-group AZURE lifetime '28800' -set vpn ipsec ike-group AZURE proposal 1 dh-group '2' -set vpn ipsec ike-group AZURE proposal 1 encryption 'aes256' -set vpn ipsec ike-group AZURE proposal 1 hash 'sha1' -``` - -- Enable IPsec on eth0 - -```none -set vpn ipsec interface 'eth0' -``` - -- Configure two VTIs with a dummy IP address each - -```none -set interfaces vti vti1 address '10.10.1.5/32' -set interfaces vti vti1 description 'Azure Primary Tunnel' - -set interfaces vti vti2 address '10.10.1.6/32' -set interfaces vti vti2 description 'Azure Secondary Tunnel' -``` - -- Clamp the VTI's MSS to 1350 to avoid PMTU blackholes. - -```none -set interfaces vti vti1 ip adjust-mss 1350 -set interfaces vti vti2 ip adjust-mss 1350 -``` - -- Configure the VPN tunnels - -```none -set vpn ipsec authentication psk azure id '198.51.100.3' -set vpn ipsec authentication psk azure id '203.0.113.2' -set vpn ipsec authentication psk azure id '203.0.113.3' -set vpn ipsec authentication psk azure secret 'ch00s3-4-s3cur3-psk' - -set vpn ipsec site-to-site peer azure-primary authentication local-id '198.51.100.3' -set vpn ipsec site-to-site peer azure-primary authentication mode 'pre-shared-secret' -set vpn ipsec site-to-site peer azure-primary authentication remote-id '203.0.113.2' -set vpn ipsec site-to-site peer azure-primary connection-type 'initiate' -set vpn ipsec site-to-site peer azure-primary description 'AZURE PRIMARY TUNNEL' -set vpn ipsec site-to-site peer azure-primary ike-group 'AZURE' -set vpn ipsec site-to-site peer azure-primary ikev2-reauth 'inherit' -set vpn ipsec site-to-site peer azure-primary local-address '10.10.0.5' -set vpn ipsec site-to-site peer azure-primary remote-address '203.0.113.2' -set vpn ipsec site-to-site peer azure-primary vti bind 'vti1' -set vpn ipsec site-to-site peer azure-primary vti esp-group 'AZURE' - -set vpn ipsec site-to-site peer azure-secondary authentication local-id '198.51.100.3' -set vpn ipsec site-to-site peer azure-secondary authentication mode 'pre-shared-secret' -set vpn ipsec site-to-site peer azure-secondary authentication remote-id '203.0.113.3' -set vpn ipsec site-to-site peer azure-secondary connection-type 'initiate' -set vpn ipsec site-to-site peer azure-secondary description 'AZURE secondary TUNNEL' -set vpn ipsec site-to-site peer azure-secondary ike-group 'AZURE' -set vpn ipsec site-to-site peer azure-secondary ikev2-reauth 'inherit' -set vpn ipsec site-to-site peer azure-secondary local-address '10.10.0.5' -set vpn ipsec site-to-site peer azure-secondary remote-address '203.0.113.3' -set vpn ipsec site-to-site peer azure-secondary vti bind 'vti2' -set vpn ipsec site-to-site peer azure-secondary vti esp-group 'AZURE' -``` - -- **Important**: Add an interface route to reach both Azure's BGP listeners - -```none -set protocols static route 10.0.0.4/32 interface vti1 -set protocols static route 10.0.0.5/32 interface vti2 -``` - -- Configure your BGP settings - -```none -set protocols bgp system-as 64499 -set protocols bgp neighbor 10.0.0.4 remote-as '65540' -set protocols bgp neighbor 10.0.0.4 address-family ipv4-unicast soft-reconfiguration 'inbound' -set protocols bgp neighbor 10.0.0.4 timers holdtime '30' -set protocols bgp neighbor 10.0.0.4 timers keepalive '10' - -set protocols bgp neighbor 10.0.0.5 remote-as '65540' -set protocols bgp neighbor 10.0.0.5 address-family ipv4-unicast soft-reconfiguration 'inbound' -set protocols bgp neighbor 10.0.0.5 timers holdtime '30' -set protocols bgp neighbor 10.0.0.5 timers keepalive '10' -``` - -- **Important**: Disable connected check, otherwise the routes learned - from Azure will not be imported into the routing table. - -```none -set protocols bgp neighbor 10.0.0.4 disable-connected-check -set protocols bgp neighbor 10.0.0.5 disable-connected-check -``` diff --git a/docs/configexamples/md-bgp-ipv6-unnumbered.md b/docs/configexamples/md-bgp-ipv6-unnumbered.md deleted file mode 100644 index 4fa29834..00000000 --- a/docs/configexamples/md-bgp-ipv6-unnumbered.md +++ /dev/null @@ -1,174 +0,0 @@ ---- -lastproofread: '2021-06-28' ---- - -(examples-bgp-ipv6-unnumbered)= - -# BGP IPv6 unnumbered with extended nexthop - -General information can be found in the {ref}`routing-bgp` chapter. - -## Configuration - -- Router A: - -```none -set protocols bgp system-as 64496 -set protocols bgp address-family ipv4-unicast redistribute connected -set protocols bgp address-family ipv6-unicast redistribute connected -set protocols bgp neighbor eth1 interface v6only -set protocols bgp neighbor eth1 interface v6only peer-group 'fabric' -set protocols bgp neighbor eth2 interface v6only -set protocols bgp neighbor eth2 interface v6only peer-group 'fabric' -set protocols bgp parameters bestpath as-path multipath-relax -set protocols bgp parameters bestpath compare-routerid -set protocols bgp parameters default no-ipv4-unicast -set protocols bgp parameters router-id '192.168.0.1' -set protocols bgp peer-group fabric address-family ipv4-unicast -set protocols bgp peer-group fabric address-family ipv6-unicast -set protocols bgp peer-group fabric capability extended-nexthop -set protocols bgp peer-group fabric remote-as 'external' -``` - -- Router B: - -```none -set protocols bgp system-as 64499 -set protocols bgp address-family ipv4-unicast redistribute connected -set protocols bgp address-family ipv6-unicast redistribute connected -set protocols bgp neighbor eth1 interface v6only -set protocols bgp neighbor eth1 interface v6only peer-group 'fabric' -set protocols bgp neighbor eth2 interface v6only -set protocols bgp neighbor eth2 interface v6only peer-group 'fabric' -set protocols bgp parameters bestpath as-path multipath-relax -set protocols bgp parameters bestpath compare-routerid -set protocols bgp parameters default no-ipv4-unicast -set protocols bgp parameters router-id '192.168.0.2' -set protocols bgp peer-group fabric address-family ipv4-unicast -set protocols bgp peer-group fabric address-family ipv6-unicast -set protocols bgp peer-group fabric capability extended-nexthop -set protocols bgp peer-group fabric remote-as 'external' -``` - - -## Results - -- Router A: - -```none -vyos@vyos:~$ show interfaces -Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down -Interface IP Address S/L Description ---------- ---------- --- ----------- -eth0 198.51.100.34/24 u/u -eth1 - u/u -eth2 - u/u -lo 127.0.0.1/8 u/u - 192.168.0.1/32 - ::1/128 -``` - -```none -vyos@vyos:~$ show ip route -Codes: K - kernel route, C - connected, S - static, R - RIP, - O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, - T - Table, v - VNC, V - VNC-Direct, A - Babel, D - SHARP, - F - PBR, f - OpenFabric, - > - selected route, * - FIB route - -S>* 0.0.0.0/0 [210/0] via 198.51.100.34, eth0, 03:21:53 -C>* 198.51.100.0/24 is directly connected, eth0, 03:21:53 -C>* 192.168.0.1/32 is directly connected, lo, 03:21:56 -B>* 192.168.0.2/32 [20/0] via fe80::a00:27ff:fe3b:7ed2, eth2, 00:05:07 - * via fe80::a00:27ff:fe7b:4000, eth1, 00:05:07 -``` - -```none -vyos@vyos:~$ ping 192.168.0.2 -PING 192.168.0.2 (192.168.0.2) 56(84) bytes of data. -64 bytes from 192.168.0.2: icmp_seq=1 ttl=64 time=0.575 ms -64 bytes from 192.168.0.2: icmp_seq=2 ttl=64 time=0.628 ms -64 bytes from 192.168.0.2: icmp_seq=3 ttl=64 time=0.581 ms -64 bytes from 192.168.0.2: icmp_seq=4 ttl=64 time=0.682 ms -64 bytes from 192.168.0.2: icmp_seq=5 ttl=64 time=0.597 ms - ---- 192.168.0.2 ping statistics --- -5 packets transmitted, 5 received, 0% packet loss, time 4086ms -rtt min/avg/max/mdev = 0.575/0.612/0.682/0.047 ms -``` - -```none -vyos@vyos:~$ show ip bgp summary - -IPv4 Unicast Summary: -BGP router identifier 192.168.0.1, local AS number 64496 vrf-id 0 -BGP table version 4 -RIB entries 5, using 800 bytes of memory -Peers 2, using 41 KiB of memory -Peer groups 1, using 64 bytes of memory - -Neighbor V AS MsgRcvd MsgSent TblVer InQ OutQ Up/Down State/PfxRcd -eth1 4 64499 13 13 0 0 0 00:05:33 2 -eth2 4 64499 13 14 0 0 0 00:05:29 2 - -Total number of neighbors 2 -``` - -- Router B: - -```none -vyos@vyos:~$ show interfaces -Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down -Interface IP Address S/L Description ---------- ---------- --- ----------- -eth0 198.51.100.33/24 u/u -eth1 - u/u -eth2 - u/u -lo 127.0.0.1/8 u/u - 192.168.0.2/32 - ::1/128 -``` - -```none -vyos@vyos:~$ show ip route -Codes: K - kernel route, C - connected, S - static, R - RIP, - O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, - T - Table, v - VNC, V - VNC-Direct, A - Babel, D - SHARP, - F - PBR, f - OpenFabric, - > - selected route, * - FIB route - -S>* 0.0.0.0/0 [210/0] via 198.51.100.33, eth0, 00:44:08 -C>* 198.51.100.0/24 is directly connected, eth0, 00:44:09 -B>* 192.168.0.1/32 [20/0] via fe80::a00:27ff:fe2d:205d, eth1, 00:06:18 - * via fe80::a00:27ff:fe93:e142, eth2, 00:06:18 -C>* 192.168.0.2/32 is directly connected, lo, 00:44:11 -``` - -```none -vyos@vyos:~$ ping 192.168.0.1 -PING 192.168.0.1 (192.168.0.1) 56(84) bytes of data. -64 bytes from 192.168.0.1: icmp_seq=1 ttl=64 time=0.427 ms -64 bytes from 192.168.0.1: icmp_seq=2 ttl=64 time=0.471 ms -64 bytes from 192.168.0.1: icmp_seq=3 ttl=64 time=0.782 ms -64 bytes from 192.168.0.1: icmp_seq=4 ttl=64 time=0.715 ms - ---- 192.168.0.1 ping statistics --- -4 packets transmitted, 4 received, 0% packet loss, time 3051ms -rtt min/avg/max/mdev = 0.427/0.598/0.782/0.155 ms -``` - -```none -vyos@vyos:~$ show ip bgp summary -IPv4 Unicast Summary: -BGP router identifier 192.168.0.2, local AS number 64499 vrf-id 0 -BGP table version 4 -RIB entries 5, using 800 bytes of memory -Peers 2, using 41 KiB of memory -Peer groups 1, using 64 bytes of memory - -Neighbor V AS MsgRcvd MsgSent TblVer InQ OutQ Up/Down State/PfxRcd -eth1 4 64496 14 14 0 0 0 00:06:40 2 -eth2 4 64496 14 14 0 0 0 00:06:37 2 - -Total number of neighbors 2 -``` diff --git a/docs/configexamples/md-dmvpn-dualhub-dualcloud.md b/docs/configexamples/md-dmvpn-dualhub-dualcloud.md deleted file mode 100644 index 20c1a064..00000000 --- a/docs/configexamples/md-dmvpn-dualhub-dualcloud.md +++ /dev/null @@ -1,552 +0,0 @@ ---- -lastproofread: '2024-02-21' ---- - -(examples-dmvpn-dualhub-dualcloud)= - -# DMVPN Dual HUB Dual Cloud - -This document is to describe a basic setup to build DMVPN network with two Hubs and two clouds using DMVPN Phase3. -OSPF is used as routing protocol inside DMVPN. - -In this example we use VyOS 1.5 as HUBs and Spokes (HUB-1, HUB-2, SPOKE-2, SPOKE-3) and Cisco IOSv 15.5(3)M (SPOKE-1) -as a Spoke. - -## Network Topology - -```{image} /_static/images/dual-hub-DMVPN.webp -:align: center -:alt: DMVPN Network Topology -:width: 80% -``` - - -## Configurations - -### Underlay configuration - -Networks 192.168.X.0/24 are used as LANs for every spoke. - -HUB-1 - -```none -set interfaces ethernet eth0 address '10.0.0.2/30' -set protocols static route 0.0.0.0/0 next-hop 10.0.0.1 -``` - -HUB-2 - -```none -set interfaces ethernet eth0 address '10.0.1.2/30' -set protocols static route 0.0.0.0/0 next-hop 10.0.1.1 -``` - -Spoke-1 - -```none -interface GigabitEthernet0/0 - ip address 10.0.11.2 255.255.255.252 - duplex auto - speed auto - media-type rj45 -! -interface GigabitEthernet0/1 - ip address 192.168.11.1 255.255.255.0 - ip ospf 1 area 0 - duplex auto - speed auto - media-type rj45 -! -ip route 0.0.0.0 0.0.0.0 10.0.11.1 -``` - -Spoke-2 - -```none -set interfaces ethernet eth0 address '10.0.12.2/30' -set interfaces ethernet eth1 address '192.168.12.1/24' -set protocols static route 0.0.0.0/0 next-hop 10.0.12.1 -``` - -Spoke-3 - -```none -set interfaces ethernet eth0 address '10.0.13.2/30' -set interfaces ethernet eth1 address '192.168.13.1/24' -set protocols static route 0.0.0.0/0 next-hop 10.0.13.1 -``` - - -### NHRP configuration - -The next step is to configure the NHRP protocol. In a Dual cloud network, every HUB has to be configured with one GRE -multipoint tunnel interface and every spoke has to be configured with two tunnel interfaces, one tunnel to each hub. -In this example tunnel networks are 10.100.100.0/24 for the first cloud and 10.100.101.0/24 for the second cloud. -But VyOS uses FRR for NHRP, that is why the tunnel address mask must be /32. - -HUB-1 - -```none -set interfaces tunnel tun100 address '10.100.100.1/32' -set interfaces tunnel tun100 enable-multicast -set interfaces tunnel tun100 encapsulation 'gre' -set interfaces tunnel tun100 ip adjust-mss '1360' -set interfaces tunnel tun100 mtu '1436' -set interfaces tunnel tun100 parameters ip key '42' -set interfaces tunnel tun100 source-interface 'eth0' -set protocols nhrp tunnel tun100 authentication 'vyos' -set protocols nhrp tunnel tun100 holdtime '300' -set protocols nhrp tunnel tun100 multicast 'dynamic' -set protocols nhrp tunnel tun100 network-id '1' -set protocols nhrp tunnel tun100 redirect -set protocols nhrp tunnel tun100 registration-no-unique -``` - -HUB-2 - -```none -set interfaces tunnel tun101 address '10.100.101.1/32' -set interfaces tunnel tun101 enable-multicast -set interfaces tunnel tun101 encapsulation 'gre' -set interfaces tunnel tun101 ip adjust-mss '1360' -set interfaces tunnel tun101 mtu '1436' -set interfaces tunnel tun101 parameters ip key '43' -set interfaces tunnel tun101 source-interface 'eth0' -set protocols nhrp tunnel tun101 authentication 'vyos' -set protocols nhrp tunnel tun101 holdtime '300' -set protocols nhrp tunnel tun101 multicast 'dynamic' -set protocols nhrp tunnel tun101 network-id '2' -set protocols nhrp tunnel tun101 redirect -set protocols nhrp tunnel tun101 registration-no-unique -``` - -Spoke-1 - -```none -interface Tunnel100 - ip address 10.100.100.11 255.255.255.0 - no ip redirects - ip mtu 1436 - ip nhrp authentication vyos - ip nhrp map multicast 10.0.0.2 - ip nhrp network-id 1 - ip nhrp holdtime 300 - ip nhrp nhs 10.100.100.1 nbma 10.0.0.2 - ip nhrp shortcut - ip tcp adjust-mss 1360 - tunnel source GigabitEthernet0/0 - tunnel mode gre multipoint - tunnel key 42 -! -interface Tunnel101 - ip address 10.100.101.11 255.255.255.0 - no ip redirects - ip mtu 1436 - ip nhrp authentication vyos - ip nhrp map multicast 10.0.1.2 - ip nhrp network-id 2 - ip nhrp holdtime 300 - ip nhrp nhs 10.100.101.1 nbma 10.0.1.2 - ip nhrp shortcut - ip tcp adjust-mss 1360 - tunnel source GigabitEthernet0/0 - tunnel mode gre multipoint - tunnel key 43 -``` - -Spoke-2 - -```none -set interfaces tunnel tun100 address '10.100.100.12/32' -set interfaces tunnel tun100 enable-multicast -set interfaces tunnel tun100 encapsulation 'gre' -set interfaces tunnel tun100 ip adjust-mss '1360' -set interfaces tunnel tun100 mtu '1436' -set interfaces tunnel tun100 parameters ip key '42' -set interfaces tunnel tun100 source-interface 'eth0' -set interfaces tunnel tun101 address '10.100.101.12/32' -set interfaces tunnel tun101 enable-multicast -set interfaces tunnel tun101 encapsulation 'gre' -set interfaces tunnel tun101 ip adjust-mss '1360' -set interfaces tunnel tun101 mtu '1436' -set interfaces tunnel tun101 parameters ip key '43' -set interfaces tunnel tun101 source-interface 'eth0' -set protocols nhrp tunnel tun100 authentication 'vyos' -set protocols nhrp tunnel tun100 holdtime '300' -set protocols nhrp tunnel tun100 multicast '10.0.0.2' -set protocols nhrp tunnel tun100 network-id '1' -set protocols nhrp tunnel tun100 nhs tunnel-ip dynamic nbma '10.0.0.2' -set protocols nhrp tunnel tun100 registration-no-unique -set protocols nhrp tunnel tun100 shortcut -set protocols nhrp tunnel tun101 authentication 'vyos' -set protocols nhrp tunnel tun101 holdtime '300' -set protocols nhrp tunnel tun101 multicast '10.0.1.2' -set protocols nhrp tunnel tun101 network-id '2' -set protocols nhrp tunnel tun101 nhs tunnel-ip dynamic nbma '10.0.1.2' -set protocols nhrp tunnel tun101 registration-no-unique -set protocols nhrp tunnel tun101 shortcut -``` - -Spoke-3 - -```none -set protocols nhrp tunnel tun100 authentication 'vyos' -set protocols nhrp tunnel tun100 holdtime '300' -set protocols nhrp tunnel tun100 multicast '10.0.0.2' -set protocols nhrp tunnel tun100 network-id '1' -set protocols nhrp tunnel tun100 nhs tunnel-ip dynamic nbma '10.0.0.2' -set protocols nhrp tunnel tun100 registration-no-unique -set protocols nhrp tunnel tun100 shortcut -set protocols nhrp tunnel tun101 authentication 'vyos' -set protocols nhrp tunnel tun101 holdtime '300' -set protocols nhrp tunnel tun101 multicast '10.0.1.2' -set protocols nhrp tunnel tun101 network-id '2' -set protocols nhrp tunnel tun101 nhs tunnel-ip dynamic nbma '10.0.1.2' -set protocols nhrp tunnel tun101 registration-no-unique -set protocols nhrp tunnel tun101 shortcut -``` - - -### Overlay configuration - -The last step is to configure the routing protocol. In this scenario, OSPF was chosen as the dynamic routing protocol. -But you can use iBGP or eBGP. To form fast convergence it is possible to use BFD protocol. - -HUB-1 - -```none -set protocols ospf interface tun100 area '0' -set protocols ospf interface tun100 network 'point-to-multipoint' -set protocols ospf interface tun100 passive disable -set protocols ospf passive-interface 'default' -``` - -HUB-2 - -```none -set protocols ospf interface tun101 area '0' -set protocols ospf interface tun101 network 'point-to-multipoint' -set protocols ospf interface tun101 passive disable -set protocols ospf passive-interface 'default' -``` - -Spoke-1 - -```none -interface Tunnel100 - ip ospf network point-to-multipoint - ip ospf dead-interval 40 - ip ospf hello-interval 10 - ip ospf 1 area 0 -! -interface Tunnel101 - ip ospf network point-to-multipoint - ip ospf dead-interval 40 - ip ospf hello-interval 10 - ip ospf 1 area 0 -! -router ospf 1 - passive-interface default - no passive-interface Tunnel100 - no passive-interface Tunnel101 -``` - -Spoke-2 - -```none -set protocols ospf interface eth1 area '0' -set protocols ospf interface tun100 area '0' -set protocols ospf interface tun100 network 'point-to-multipoint' -set protocols ospf interface tun100 passive disable -set protocols ospf interface tun101 area '0' -set protocols ospf interface tun101 network 'point-to-multipoint' -set protocols ospf interface tun101 passive disable -set protocols ospf passive-interface 'default' -``` - -Spoke-3 - -```none -set protocols ospf interface eth1 area '0' -set protocols ospf interface tun100 area '0' -set protocols ospf interface tun100 network 'point-to-multipoint' -set protocols ospf interface tun100 passive disable -set protocols ospf interface tun101 area '0' -set protocols ospf interface tun101 network 'point-to-multipoint' -set protocols ospf interface tun101 passive disable -set protocols ospf passive-interface 'default' -``` - - -### Security configuration - -Tunnels can be encrypted by IPSEC for security. - -HUB-1 - -```{eval-rst} - .. code-block:: none - - set vpn ipsec esp-group ESP-HUB lifetime '1800' - set vpn ipsec esp-group ESP-HUB mode 'transport' - set vpn ipsec esp-group ESP-HUB pfs 'disable' - set vpn ipsec esp-group ESP-HUB proposal 1 encryption 'aes256' - set vpn ipsec esp-group ESP-HUB proposal 1 hash 'sha1' - set vpn ipsec ike-group IKE-HUB key-exchange 'ikev1' - set vpn ipsec ike-group IKE-HUB lifetime '3600' - set vpn ipsec ike-group IKE-HUB proposal 1 dh-group '2' - set vpn ipsec ike-group IKE-HUB proposal 1 encryption 'aes256' - set vpn ipsec ike-group IKE-HUB proposal 1 hash 'sha1' - set vpn ipsec interface 'eth0' - set vpn ipsec profile NHRPVPN authentication mode 'pre-shared-secret' - set vpn ipsec profile NHRPVPN authentication pre-shared-secret 'secret' - set vpn ipsec profile NHRPVPN bind tunnel 'tun100' - set vpn ipsec profile NHRPVPN esp-group 'ESP-HUB' - set vpn ipsec profile NHRPVPN ike-group 'IKE-HUB' -``` - -HUB-2 - -```{eval-rst} - .. code-block:: none - - set vpn ipsec esp-group ESP-HUB lifetime '1800' - set vpn ipsec esp-group ESP-HUB mode 'transport' - set vpn ipsec esp-group ESP-HUB pfs 'disable' - set vpn ipsec esp-group ESP-HUB proposal 1 encryption 'aes256' - set vpn ipsec esp-group ESP-HUB proposal 1 hash 'sha1' - set vpn ipsec ike-group IKE-HUB key-exchange 'ikev1' - set vpn ipsec ike-group IKE-HUB lifetime '3600' - set vpn ipsec ike-group IKE-HUB proposal 1 dh-group '2' - set vpn ipsec ike-group IKE-HUB proposal 1 encryption 'aes256' - set vpn ipsec ike-group IKE-HUB proposal 1 hash 'sha1' - set vpn ipsec interface 'eth0' - set vpn ipsec profile NHRPVPN authentication mode 'pre-shared-secret' - set vpn ipsec profile NHRPVPN authentication pre-shared-secret 'secret' - set vpn ipsec profile NHRPVPN bind tunnel 'tun101' - set vpn ipsec profile NHRPVPN esp-group 'ESP-HUB' - set vpn ipsec profile NHRPVPN ike-group 'IKE-HUB' -``` - -VyOS Spokes have the same configuration - -```{eval-rst} - .. code-block:: none - - set vpn ipsec esp-group ESP-HUB lifetime '1800' - set vpn ipsec esp-group ESP-HUB mode 'transport' - set vpn ipsec esp-group ESP-HUB pfs 'disable' - set vpn ipsec esp-group ESP-HUB proposal 1 encryption 'aes256' - set vpn ipsec esp-group ESP-HUB proposal 1 hash 'sha1' - set vpn ipsec ike-group IKE-HUB key-exchange 'ikev1' - set vpn ipsec ike-group IKE-HUB lifetime '3600' - set vpn ipsec ike-group IKE-HUB proposal 1 dh-group '2' - set vpn ipsec ike-group IKE-HUB proposal 1 encryption 'aes256' - set vpn ipsec ike-group IKE-HUB proposal 1 hash 'sha1' - set vpn ipsec interface 'eth0' - set vpn ipsec profile NHRPVPN authentication mode 'pre-shared-secret' - set vpn ipsec profile NHRPVPN authentication pre-shared-secret 'secret' - set vpn ipsec profile NHRPVPN bind tunnel 'tun100' - set vpn ipsec profile NHRPVPN bind tunnel 'tun101' - set vpn ipsec profile NHRPVPN esp-group 'ESP-HUB' - set vpn ipsec profile NHRPVPN ike-group 'IKE-HUB' -``` - -SPOKE-1 - -```{eval-rst} - .. code-block:: none - - crypto isakmp policy 1 - encr aes 256 - authentication pre-share - group 2 - lifetime 3600 - crypto isakmp key secret address 0.0.0.0 - ! - ! - crypto ipsec transform-set ESP_TRANSFORMSET esp-aes 256 esp-sha-hmac - mode transport - ! - ! - crypto ipsec profile gre_protection - set security-association lifetime seconds 1800 - set transform-set ESP_TRANSFORMSET - ! - interface Tunnel100 - tunnel protection ipsec profile gre_protection shared - ! - interface Tunnel101 - tunnel protection ipsec profile gre_protection shared -``` - - -## Monitoring - -All spokes created IPSec tunnels to Hubs, are registered on Hubs using NHRP protocol and formed adjacency in OSPF. - -```none -vyos@HUB-1:~$ show vpn ipsec sa -Connection State Uptime Bytes In/Out Packets In/Out Remote address Remote ID Proposal --------------------------- ------- -------- -------------- ---------------- ---------------- ----------- ------------------------ -dmvpn-NHRPVPN-tun100-child up 6m1s 4K/5K 51/56 10.0.13.2 10.0.13.2 AES_CBC_256/HMAC_SHA1_96 -dmvpn-NHRPVPN-tun100-child up 6m36s 4K/6K 56/65 10.0.12.2 10.0.12.2 AES_CBC_256/HMAC_SHA1_96 -dmvpn-NHRPVPN-tun100-child up 8m49s 6K/6K 73/77 10.0.11.2 10.0.11.2 AES_CBC_256/HMAC_SHA1_96 - -vyos@HUB-1:~$ show ip nhrp cache -Iface Type Protocol NBMA Claimed NBMA Flags Identity -tun100 dynamic 10.100.100.12 10.0.12.2 10.0.12.2 T 10.0.12.2 -tun100 dynamic 10.100.100.13 10.0.13.2 10.0.13.2 T 10.0.13.2 -tun100 dynamic 10.100.100.11 10.0.11.2 10.0.11.2 T 10.0.11.2 -tun100 local 10.100.100.1 10.0.0.2 10.0.0.2 - - -vyos@HUB-1:~$ show ip ospf neighbor - -Neighbor ID Pri State Up Time Dead Time Address Interface RXmtL RqstL DBsmL -192.168.11.1 1 Full/DROther 17m01s 36.201s 10.100.100.11 tun100:10.100.100.1 0 0 0 -192.168.12.1 1 Full/DROther 9m42s 37.443s 10.100.100.12 tun100:10.100.100.1 0 0 0 -192.168.13.1 1 Full/DROther 9m15s 35.053s 10.100.100.13 tun100:10.100.100.1 0 0 0 -``` - -First, we see that LANs are accessible through hubs using OSPF routes. - -```none -SPOKE-1#show ip route -Codes: L - local, C - connected, S - static, R - RIP, M - mobile, B - BGP - D - EIGRP, EX - EIGRP external, O - OSPF, IA - OSPF inter area - N1 - OSPF NSSA external type 1, N2 - OSPF NSSA external type 2 - E1 - OSPF external type 1, E2 - OSPF external type 2 - i - IS-IS, su - IS-IS summary, L1 - IS-IS level-1, L2 - IS-IS level-2 - ia - IS-IS inter area, * - candidate default, U - per-user static route - o - ODR, P - periodic downloaded static route, H - NHRP, l - LISP - a - application route - + - replicated route, % - next hop override, p - overrides from PfR - -Gateway of last resort is 10.0.11.1 to network 0.0.0.0 -..... - 192.168.11.0/24 is variably subnetted, 2 subnets, 2 masks -C 192.168.11.0/24 is directly connected, GigabitEthernet0/1 -L 192.168.11.1/32 is directly connected, GigabitEthernet0/1 -O 192.168.12.0/24 [110/1002] via 10.100.101.1, 00:14:36, Tunnel101 - [110/1002] via 10.100.100.1, 00:16:13, Tunnel100 -O 192.168.13.0/24 [110/1002] via 10.100.101.1, 00:14:36, Tunnel101 - [110/1002] via 10.100.100.1, 00:15:45, Tunnel100 - - -vyos@SPOKE-2:~$ show ip route -Codes: K - kernel route, C - connected, L - local, 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, t - Table-Direct, - > - selected route, * - FIB route, q - queued, r - rejected, b - backup - t - trapped, o - offload failure - -...... -O>* 192.168.11.0/24 [110/3] via 10.100.100.1, tun100 onlink, weight 1, 00:12:36 - * via 10.100.101.1, tun101 onlink, weight 1, 00:12:36 -O 192.168.12.0/24 [110/1] is directly connected, eth1, weight 1, 01:24:40 -C>* 192.168.12.0/24 is directly connected, eth1, weight 1, 01:24:43 -L>* 192.168.12.1/32 is directly connected, eth1, weight 1, 01:24:43 -O>* 192.168.13.0/24 [110/3] via 10.100.100.1, tun100 onlink, weight 1, 00:12:36 - * via 10.100.101.1, tun101 onlink, weight 1, 00:12:36 -``` - -After initiating traffic between SPOKES sites, Phase 3 of DMVPN will work. -For instance, traceroute was generated from PC-SPOKE-2 to PC-SPOKE-1 - -```none -PC-SPOKE-2 : 192.168.12.2 255.255.255.0 gateway 192.168.12.1 - -PC-SPOKE-2> trace 192.168.11.2 -trace to 192.168.11.2, 8 hops max, press Ctrl+C to stop - 1 192.168.12.1 0.558 ms 0.378 ms 0.561 ms - 2 10.100.101.1 1.768 ms 1.158 ms 1.744 ms - 3 10.100.101.11 7.196 ms 4.971 ms 4.793 ms - 4 *192.168.11.2 7.747 ms (ICMP type:3, code:3, Destination port unreachable) - -PC-SPOKE-2> trace 192.168.11.2 -trace to 192.168.11.2, 8 hops max, press Ctrl+C to stop - 1 192.168.12.1 0.562 ms 0.396 ms 0.364 ms - 2 10.100.100.11 4.401 ms 4.399 ms 4.174 ms - 3 *192.168.11.2 3.241 ms (ICMP type:3, code:3, Destination port unreachable) -``` - -First trace goes via HUB but the second goes directly from SPOKE-1 to SPOKE-2. -Now routing tables are changed. LAN networks 192.168.12.0/24 and 192.168.11.0/24 available directly via SPOKES. - -```none -vyos@SPOKE-2:~$ show ip route -Codes: K - kernel route, C - connected, L - local, 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, t - Table-Direct, - > - selected route, * - FIB route, q - queued, r - rejected, b - backup - t - trapped, o - offload failure - -N>* 192.168.11.0/24 [10/0] via 10.100.100.11, tun100 onlink, weight 1, 00:00:14 -O 192.168.11.0/24 [110/3] via 10.100.100.1, tun100 onlink, weight 1, 00:00:54 - via 10.100.101.1, tun101 onlink, weight 1, 00:00:54 - - -SPOKE-1# show ip route next-hop-override -Codes: L - local, C - connected, S - static, R - RIP, M - mobile, B - BGP - D - EIGRP, EX - EIGRP external, O - OSPF, IA - OSPF inter area - N1 - OSPF NSSA external type 1, N2 - OSPF NSSA external type 2 - E1 - OSPF external type 1, E2 - OSPF external type 2 - i - IS-IS, su - IS-IS summary, L1 - IS-IS level-1, L2 - IS-IS level-2 - ia - IS-IS inter area, * - candidate default, U - per-user static route - o - ODR, P - periodic downloaded static route, H - NHRP, l - LISP - a - application route - + - replicated route, % - next hop override, p - overrides from PfR - -Gateway of last resort is 10.0.11.1 to network 0.0.0.0 - -O % 192.168.12.0/24 [110/1002] via 10.100.101.1, 00:24:09, Tunnel101 - [110/1002] via 10.100.100.1, 00:25:46, Tunnel100 - [NHO][110/1] via 10.100.100.12, 00:00:03, Tunnel100 -``` - -NHRP shows shortcuts on Spokes - -```none -vyos@SPOKE-2:~$ show ip nhrp shortcut -Type Prefix Via Identity -dynamic 192.168.11.0/24 10.100.100.11 10.0.11.2 - -SPOKE-1# show ip nhrp shortcut -10.100.100.12/32 via 10.100.100.12 - Tunnel100 created 00:09:59, expire 00:02:21 - Type: dynamic, Flags: router nhop rib nho - NBMA address: 10.0.12.2 -192.168.12.0/24 via 10.100.100.12 - Tunnel100 created 00:02:38, expire 00:02:21 - Type: dynamic, Flags: router rib nho - NBMA address: 10.0.12.2 -``` - -A new Spoke to Spoke IPSec tunnel is created - -```none -SPOKE-1#show crypto isakmp sa -IPv4 Crypto ISAKMP SA -dst src state conn-id status -10.0.0.2 10.0.11.2 QM_IDLE 1002 ACTIVE -10.0.12.2 10.0.11.2 QM_IDLE 1004 ACTIVE -10.0.1.2 10.0.11.2 QM_IDLE 1003 ACTIVE - -vyos@SPOKE-2:~$ show vpn ipsec sa -Connection State Uptime Bytes In/Out Packets In/Out Remote address Remote ID Proposal --------------------------- ------- -------- -------------- ---------------- ---------------- ----------- ------------------------ -dmvpn-NHRPVPN-tun100-child up 7m26s 4K/4K 57/53 10.0.0.2 10.0.0.2 AES_CBC_256/HMAC_SHA1_96 -dmvpn-NHRPVPN-tun100-child up 11m48s 316B/1K 3/15 10.0.11.2 10.0.11.2 AES_CBC_256/HMAC_SHA1_96 -dmvpn-NHRPVPN-tun101-child up 5m58s 5K/4K 62/51 10.0.1.2 10.0.1.2 AES_CBC_256/HMAC_SHA1_96 -``` - - -## Summary - -If one of the Hubs loses connectivity to the Internet, the other Hub will be available and take the main role. -This is a simple example where only one internet connection is used. But in the real world, there can be two -connections to the Internet. In this case, there is a recommendation to build each tunnel via each Internet connection, -choose the main cloud, and manipulate traffic via a routing protocol. It allows the creation failover on link-level -connections too. diff --git a/docs/configexamples/md-firewall.md b/docs/configexamples/md-firewall.md deleted file mode 100644 index 5d170511..00000000 --- a/docs/configexamples/md-firewall.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -lastproofread: '2024-09-11' ---- - -# Firewall Examples - -This section contains examples of firewall configurations for various -deployments. - -```{toctree} -:maxdepth: 2 - -fwall-and-vrf -fwall-and-bridge -zone-policy -``` diff --git a/docs/configexamples/md-fwall-and-bridge.md b/docs/configexamples/md-fwall-and-bridge.md deleted file mode 100644 index d6602592..00000000 --- a/docs/configexamples/md-fwall-and-bridge.md +++ /dev/null @@ -1,490 +0,0 @@ ---- -lastproofread: '2024-09-11' ---- - -# Bridge and firewall example - -## Scenario and requirements - -This example shows how to configure a VyOS router with bridge interfaces and -firewall rules. - -Three non VLAN-aware bridges are going to be configured, and each one has its -own requirements. - -- Bridge br0: - : - Isolated layer 2 bridge. - - Accept only IPv6 communication within the bridge. -- Bridge br1: - : - Drop all DHCP discover packets. - - Accept all ARP packets. - - Within the bridge, accept only new IPv4 connections from host 10.1.1.102 - - Drop all other IPv4 connections. - - Drop all IPv6 connections. - - Accept access to router itself. - - Allow connections to internet - - Drop connections to other LANs. -- Bridge br2: - : - Accept all DHCP discover packets. - - Accept only DHCP offers from valid server and|or trusted bridge port. - - Accept all ARP packets. - - Accept all IPv4 connections. - - Drop all IPv6 connections. - - Deny access to the router. - - Allow connections to internet. - - Allow connections to bridge br1. - -## Configuration - -### Bridges and interfaces configuration - -First, we need to configure the interfaces and bridges: - -```none -# Brige br0 -set interfaces bridge br0 description 'Isolated L2 bridge' -set interfaces bridge br0 member interface eth1 -set interfaces bridge br0 member interface eth2 -set interfaces ethernet eth1 description 'br0' -set interfaces ethernet eth2 description 'br0' - -# Bridge br1: -set interfaces bridge br1 address '10.1.1.1/24' -set interfaces bridge br1 description 'L3 bridge br1' -set interfaces bridge br1 member interface eth3 -set interfaces bridge br1 member interface eth4 -set interfaces ethernet eth3 description 'br1' -set interfaces ethernet eth4 description 'br1' - -# Bridge br2: -set interfaces bridge br2 address '10.2.2.1/24' -set interfaces bridge br2 description 'L3 bridge br2' -set interfaces bridge br2 member interface eth5 -set interfaces bridge br2 member interface eth6 -set interfaces bridge br2 member interface eth7 -set interfaces ethernet eth5 description 'br2 - Host' -set interfaces ethernet eth6 description 'br2 - Trusted DHCP Server' -set interfaces ethernet eth7 description 'br2' -``` - - -### Bridge firewall configuration - -In this section, we are going to configure the firewall rules that will be used -in bridge firewall, and will control the traffic within each bridge. - -We are going to use custom firewall rulesets, one for each bridge that will -be used in `prerouting`, and one for each bridge that will be used in the -`forward` chain. - -Also, we are going to use firewall interface groups in order to simplify the -firewall configuration. - -So first, let's create the required firewall interface groups: - -```none -# Bridge br0 interface-group: -set firewall group interface-group br0-ifaces interface 'br0' -set firewall group interface-group br0-ifaces interface 'eth1' -set firewall group interface-group br0-ifaces interface 'eth2' - -# Bridge br1 interface-group: -set firewall group interface-group br1-ifaces interface 'br1' -set firewall group interface-group br1-ifaces interface 'eth3' -set firewall group interface-group br1-ifaces interface 'eth4' - -# Bridge br2 interface-group: -set firewall group interface-group br2-ifaces interface 'br2' -set firewall group interface-group br2-ifaces interface 'eth5' -set firewall group interface-group br2-ifaces interface 'eth6' -set firewall group interface-group br2-ifaces interface 'eth7' -``` - -As said before, we are going to create custom firewall rulesets for each -bridge, that will be used in the `prerouting` chain, in order to drop as much -unwanted traffic as early as possible. So, custom rulesets used in -`prerouting` chain are going to be `br0-pre`, `br1-pre`, and `br2-pre`: - -```none -# Prerouting - Catch all traffic for br0 -set firewall bridge prerouting filter rule 10 action 'jump' -set firewall bridge prerouting filter rule 10 description 'br0 traffic' -set firewall bridge prerouting filter rule 10 inbound-interface group 'br0-ifaces' -set firewall bridge prerouting filter rule 10 jump-target 'br0-pre' - -# Prerouting - Catch all traffic for br1 -set firewall bridge prerouting filter rule 20 action 'jump' -set firewall bridge prerouting filter rule 20 description 'br1 traffic' -set firewall bridge prerouting filter rule 20 inbound-interface group 'br1-ifaces' -set firewall bridge prerouting filter rule 20 jump-target 'br1-pre' - -# Prerouting - Catch all traffic for br2 -set firewall bridge prerouting filter rule 30 action 'jump' -set firewall bridge prerouting filter rule 30 description 'br2 traffic' -set firewall bridge prerouting filter rule 30 inbound-interface group 'br2-ifaces' -set firewall bridge prerouting filter rule 30 jump-target 'br2-pre' -``` - -And then create the custom rulesets: - -```none -### br0 - br0-pre - # Requirements: accept only IPv6 communication within the bridge -set firewall bridge name br0-pre rule 10 description 'Accept IPv6 traffic' -set firewall bridge name br0-pre rule 10 action 'accept' -set firewall bridge name br0-pre rule 10 ethernet-type 'ipv6' - # And drop everything else -set firewall bridge name br0-pre default-action 'drop' - -### br1 - br1-pre - # Requirements: drop all DHCP discover packets -set firewall bridge name br1-pre rule 10 description 'Drop DHCP discover' -set firewall bridge name br1-pre rule 10 action 'drop' -set firewall bridge name br1-pre rule 10 protocol 'udp' -set firewall bridge name br1-pre rule 10 source port '68' -set firewall bridge name br1-pre rule 10 destination port '67' -set firewall bridge name br1-pre rule 10 destination mac-address 'ff:ff:ff:ff:ff:ff' -set firewall bridge name br1-pre rule 10 log - # Requirement: drop all IPv6 connections -set firewall bridge name br1-pre rule 20 description 'Drop IPv6 traffic' -set firewall bridge name br1-pre rule 20 action 'drop' -set firewall bridge name br1-pre rule 20 ethernet-type 'ipv6' - # Accept everything else so it can be parsed later -set firewall bridge name br1-pre default-action 'accept' - -### br2 - br2-pre - # Requirements: drop all IPv6 connections -set firewall bridge name br2-pre rule 10 description 'Drop IPv6 traffic' -set firewall bridge name br2-pre rule 10 action 'drop' -set firewall bridge name br2-pre rule 10 ethernet-type 'ipv6' - # Accept everything else so it can be parsed later -set firewall bridge name br2-pre default-action 'accept' -``` - -Now, in the `forward` chain, we are going to define state policies, and -custom rulesets for each bridge that would be used in the `forward` chain. -These rulesets are `br0-fwd`, `br1-fwd`, and `br2-fwd`: - -```none -# Forward - State policies if not defined globally -set firewall bridge forward filter rule 5 action 'accept' -set firewall bridge forward filter rule 5 state 'established' -set firewall bridge forward filter rule 5 state 'related' -set firewall bridge forward filter rule 10 action 'drop' -set firewall bridge forward filter rule 10 state 'invalid' - -# Forward - Catch all traffic for br0 -set firewall bridge forward filter rule 110 description 'br0 traffic' -set firewall bridge forward filter rule 110 action 'jump' -set firewall bridge forward filter rule 110 inbound-interface group 'br0-ifaces' -set firewall bridge forward filter rule 110 jump-target 'br0-fwd' - -# Forward - Catch all traffic for br1 -set firewall bridge forward filter rule 120 description 'br1 traffic' -set firewall bridge forward filter rule 120 action 'jump' -set firewall bridge forward filter rule 120 inbound-interface group 'br1-ifaces' -set firewall bridge forward filter rule 120 jump-target 'br1-fwd' - -# Forward - Catch all traffic for br2 -set firewall bridge forward filter rule 130 description 'br2 traffic' -set firewall bridge forward filter rule 130 action 'jump' -set firewall bridge forward filter rule 130 inbound-interface group 'br2-ifaces' -set firewall bridge forward filter rule 130 jump-target 'br2-fwd' - -# Forward - Default action drop: -set firewall bridge forward filter default-action 'drop' -``` - -And the content of the custom rulesets: - -```none -### br0 - br0-fwd - # Accept everything that wasn't dropped in prerouting -set firewall bridge name br0-fwd default-action 'accept' - -### br1 - br1-fwd - # Requirement: Accept all ARP packets -set firewall bridge name br1-fwd rule 10 description 'Accept ARP' -set firewall bridge name br1-fwd rule 10 action 'accept' -set firewall bridge name br1-fwd rule 10 ethernet-type 'arp' - # Requirement: Accept only new IPv4 connections from host 10.1.1.102 -set firewall bridge name br1-fwd rule 20 description 'Accept ipv4 from host' -set firewall bridge name br1-fwd rule 20 action 'accept' -set firewall bridge name br1-fwd rule 20 source address '10.1.1.102' -set firewall bridge name br1-fwd rule 20 state 'new' - # Drop everything else within the bridge: -set firewall bridge name br1-fwd default-action 'drop' - -### br2 - br2-fwd - # Requirement: Accept all DHCP discover packets -set firewall bridge name br2-fwd rule 10 description 'Accept DHCP discover' -set firewall bridge name br2-fwd rule 10 action 'accept' -set firewall bridge name br2-fwd rule 10 protocol 'udp' -set firewall bridge name br2-fwd rule 10 source port '68' -set firewall bridge name br2-fwd rule 10 destination port '67' -set firewall bridge name br2-fwd rule 10 destination mac-address 'ff:ff:ff:ff:ff:ff' - # Requirement: Accept only DHCP offers from valid server on port eth6 -set firewall bridge name br2-fwd rule 20 description 'Accept DHCP offers from trusted interface' -set firewall bridge name br2-fwd rule 20 action 'accept' -set firewall bridge name br2-fwd rule 20 protocol 'udp' -set firewall bridge name br2-fwd rule 20 source port '67' -set firewall bridge name br2-fwd rule 20 destination port '68' -set firewall bridge name br2-fwd rule 20 inbound-interface name 'eth6' -set firewall bridge name br2-fwd rule 22 description 'Drop all other DHCP offers' -set firewall bridge name br2-fwd rule 22 action 'drop' -set firewall bridge name br2-fwd rule 22 protocol 'udp' -set firewall bridge name br2-fwd rule 22 source port '67' -set firewall bridge name br2-fwd rule 22 destination port '68' -set firewall bridge name br2-fwd rule 22 log - - # Accept all ARP packets -set firewall bridge name br2-fwd rule 30 description 'Accept ARP' -set firewall bridge name br2-fwd rule 30 action 'accept' -set firewall bridge name br2-fwd rule 30 ethernet-type 'arp' - # Accept all IPv4 connections -set firewall bridge name br2-fwd rule 40 description 'Accept ipv4' -set firewall bridge name br2-fwd rule 40 action 'accept' -set firewall bridge name br2-fwd rule 40 ethernet-type 'ipv4' - # Drop everything else -set firewall bridge name br2-fwd default-action 'drop' -``` - - -### IP firewall configuration - -Since some of the requirements listed above exceed the capabilities of the -bridge firewall, we need to use the IP firewall to implement them. -For bridge br1 and br2, we need to control the traffic that is going to the -router itself, to other local networks, and to the Internet. - -As a reminder, here's a link to the {doc}`firewall documentation -`, where you can find more information about -the packet flow for traffic that comes from bridge layer and should be analized -by the IP firewall. - -Access to the router itself is controlled by the base chain `input`, and -rules to accomplish all the requirements are: - -```none -# First of all, if not using global state policies, we need to define them: -set firewall ipv4 input filter rule 10 state 'established' -set firewall ipv4 input filter rule 10 state 'related' -set firewall ipv4 input filter rule 10 action 'accept' -set firewall ipv4 input filter rule 20 state 'invalid' -set firewall ipv4 input filter rule 20 action 'drop' - -# Input - br1 - Accept access to router itself -set firewall ipv4 input filter rule 110 description "Accept access from br1" -set firewall ipv4 input filter rule 110 action 'accept' -set firewall ipv4 input filter rule 110 inbound-interface group 'br1-ifaces' - -# Input - br2 - Deny access to the router -set firewall ipv4 input filter rule 120 description "Deny access from br2" -set firewall ipv4 input filter rule 120 action 'drop' -set firewall ipv4 input filter rule 120 inbound-interface group 'br2-ifaces' -``` - -And for traffic that is going to other local networks, and to he Internet, we -need to use the base chain `forward`. As in the bridge firewall, we are -going to use custom rulesets for each bridge, that would be used in the -`forward` chain. Those rulesets are `ip-br1-fwd` and `ip-br2-fwd`: - -```none -# First of all, if not using global state policies, we need to define them: -set firewall ipv4 forward filter rule 5 action 'accept' -set firewall ipv4 forward filter rule 5 state 'established' -set firewall ipv4 forward filter rule 5 state 'related' -set firewall ipv4 forward filter rule 10 action 'drop' -set firewall ipv4 forward filter rule 10 state 'invalid' - -# Forward - Catch all traffic for br1 -set firewall ipv4 forward filter rule 110 description 'br1 traffic' -set firewall ipv4 forward filter rule 110 action 'jump' -set firewall ipv4 forward filter rule 110 inbound-interface group 'br1-ifaces' -set firewall ipv4 forward filter rule 110 jump-target 'ip-br1-fwd' - -# Forward - Catch all traffic for br2 -set firewall ipv4 forward filter rule 120 description 'br2 traffic' -set firewall ipv4 forward filter rule 120 action 'jump' -set firewall ipv4 forward filter rule 120 inbound-interface group 'br2-ifaces' -set firewall ipv4 forward filter rule 120 jump-target 'ip-br2-fwd' - -# Forward - Default action drop: -set firewall ipv4 forward filter default-action 'drop' -``` - -And the content of the custom rulesets: - -```none -### br1 - ip-br1-fwd - # Requirement: Allow connections to internet -set firewall ipv4 name ip-br1-fwd rule 10 description 'br1 - allow internet access' -set firewall ipv4 name ip-br1-fwd rule 10 action 'accept' -set firewall ipv4 name ip-br1-fwd rule 10 outbound-interface name 'eth0' - # Requirement: Drop all other connections -set firewall ipv4 name ip-br1-fwd default-action 'drop' - -### br2 - ip-br2-fwd - # Requirement: Allow connections to internet -set firewall ipv4 name ip-br2-fwd rule 10 description 'br2 - allow internet access' -set firewall ipv4 name ip-br2-fwd rule 10 action 'accept' -set firewall ipv4 name ip-br2-fwd rule 10 outbound-interface name 'eth0' - # Requirement: Allow connections to br1 -set firewall ipv4 name ip-br2-fwd rule 20 description 'br2 - allow access to br1' -set firewall ipv4 name ip-br2-fwd rule 20 action 'accept' -set firewall ipv4 name ip-br2-fwd rule 20 outbound-interface group 'br1-ifaces' - # Requirement: Drop all other connections -set firewall ipv4 name ip-br2-fwd default-action 'drop' -``` - - -## Validation - -While testing the configuration, we can check logs in order to ensure that -we are accepting and/or blocking the correct traffic. - -For example, while a host tries to get an IP address from a DHCP server in -br1 all DHCP discover are dropped, and in br2, we can see that DHCP offers from -untrusted servers are dropped: - -```none -vyos@bridge:~$ show log firewall bridge -Sep 17 14:22:35 kernel: [bri-NAM-br2-fwd-22-D]IN=eth7 OUT=eth5 MAC=50:00:00:09:00:00:50:00:00:04:00:00:08:00 SRC=10.2.2.199 DST=10.2.2.92 LEN=322 TOS=0x10 PREC=0x00 TTL=128 ID=0 DF PROTO=UDP SPT=67 DPT=68 LEN=302 -Sep 17 14:28:18 kernel: [bri-NAM-br1-pre-10-D]IN=eth3 OUT= MAC=ff:ff:ff:ff:ff:ff:00:50:79:66:68:0c:08:00 SRC=0.0.0.0 DST=255.255.255.255 LEN=392 TOS=0x10 PREC=0x00 TTL=16 ID=0 PROTO=UDP SPT=68 DPT=67 LEN=372 -Sep 17 14:28:19 kernel: [bri-NAM-br1-pre-10-D]IN=eth3 OUT= MAC=ff:ff:ff:ff:ff:ff:00:50:79:66:68:0c:08:00 SRC=0.0.0.0 DST=255.255.255.255 LEN=392 TOS=0x10 PREC=0x00 TTL=16 ID=0 PROTO=UDP SPT=68 DPT=67 LEN=372 -``` - -And with operational mode commands, we can check rules matchers, actions, and -counters. - -Bridge firewall ruleset: - -```none -vyos@bri:~$ show firewall bridge -Rulesets bridge Information - ---------------------------------- -bridge Firewall "forward filter" - -Rule Action Protocol Packets Bytes Conditions -------- -------- ---------- --------- ------- ----------------------------------------- -5 accept all 19 1916 ct state { established, related } accept -10 drop all 0 0 ct state invalid -110 jump all 2 208 iifname @I_br0-ifaces jump NAME_br0-fwd -120 jump all 10 670 iifname @I_br1-ifaces jump NAME_br1-fwd -130 jump all 12 3086 iifname @I_br2-ifaces jump NAME_br2-fwd -default drop all 0 0 - ---------------------------------- -bridge Firewall "name br0-fwd" - -Rule Action Protocol Packets Bytes -------- -------- ---------- --------- ------- -default accept all 2 208 - ---------------------------------- -bridge Firewall "name br0-pre" - -Rule Action Protocol Packets Bytes Conditions -------- -------- ---------- --------- ------- ---------------------- -10 accept all 18 1872 ether type ip6 accept -default drop all 9 1476 - ---------------------------------- -bridge Firewall "name br1-fwd" - -Rule Action Protocol Packets Bytes Conditions -------- -------- ---------- --------- ------- ---------------------------------------- -10 accept all 5 250 ether type arp accept -20 accept all 3 252 ct state new ip saddr 10.1.1.102 accept -default drop all 2 168 - ---------------------------------- -bridge Firewall "name br1-pre" - -Rule Action Protocol Packets Bytes Conditions -------- -------- ---------- --------- ------- ---------------------------------------------------------------------------------------- -10 drop udp 3 1176 ether daddr ff:ff:ff:ff:ff:ff udp sport 68 udp dport 67 prefix "[bri-NAM-br1-pre-10-D]" -20 drop all 0 0 ether type ip6 -default accept all 58 4430 - ---------------------------------- -bridge Firewall "name br2-fwd" - -Rule Action Protocol Packets Bytes Conditions -------- -------- ---------- --------- ------- --------------------------------------------------------------- -10 accept udp 4 1312 ether daddr ff:ff:ff:ff:ff:ff udp sport 68 udp dport 67 accept -20 accept udp 2 656 udp sport 67 udp dport 68 iifname "eth6" accept -22 drop udp 1 322 udp sport 67 udp dport 68 prefix "[bri-NAM-br2-fwd-22-D]" -30 accept all 2 92 ether type arp accept -40 accept all 3 704 ether type ip accept -default drop all 0 0 - ---------------------------------- -bridge Firewall "name br2-pre" - -Rule Action Protocol Packets Bytes Conditions -------- -------- ---------- --------- ------- -------------- -10 drop all 7 728 ether type ip6 -default accept all 77 7548 - ---------------------------------- -bridge Firewall "prerouting filter" - -Rule Action Protocol Packets Bytes Conditions -------- -------- ---------- --------- ------- ---------------------------------------- -10 jump all 27 3348 iifname @I_br0-ifaces jump NAME_br0-pre -20 jump all 61 5606 iifname @I_br1-ifaces jump NAME_br1-pre -30 jump all 84 8276 iifname @I_br2-ifaces jump NAME_br2-pre -default drop all 0 0 - -vyos@bridge:~$ -``` - -IPv4 firewall ruleset: - -```none -vyos@bridge:~$ show firewall ipv4 -Rulesets ipv4 Information - ---------------------------------- -ipv4 Firewall "forward filter" - -Rule Action Protocol Packets Bytes Conditions -------- -------- ---------- --------- ------- ------------------------------------------- -5 accept all 76 6384 ct state { established, related } accept -10 drop all 0 0 ct state invalid -110 jump all 13 1092 iifname @I_br1-ifaces jump NAME_ip-br1-fwd -120 jump all 3 252 iifname @I_br2-ifaces jump NAME_ip-br2-fwd -default drop all 0 0 - ---------------------------------- -ipv4 Firewall "input filter" - -Rule Action Protocol Packets Bytes Conditions -------- -------- ---------- --------- ------- ----------------------------------------- -10 accept all 0 0 ct state { established, related } accept -20 drop all 0 0 ct state invalid -110 accept all 10 720 iifname @I_br1-ifaces accept -120 drop all 26 2672 iifname @I_br2-ifaces -default accept all 3037 991621 - ---------------------------------- -ipv4 Firewall "name ip-br1-fwd" - -Rule Action Protocol Packets Bytes Conditions -------- -------- ---------- --------- ------- ---------------------- -10 accept all 5 420 oifname "eth0" accept -default drop all 8 672 - ---------------------------------- -ipv4 Firewall "name ip-br2-fwd" - -Rule Action Protocol Packets Bytes Conditions -------- -------- ---------- --------- ------- ----------------------------- -10 accept all 1 84 oifname "eth0" accept -20 accept all 2 168 oifname @I_br1-ifaces accept -default drop all 0 0 - -vyos@bridge:~$ -``` diff --git a/docs/configexamples/md-fwall-and-vrf.md b/docs/configexamples/md-fwall-and-vrf.md deleted file mode 100644 index da9949db..00000000 --- a/docs/configexamples/md-fwall-and-vrf.md +++ /dev/null @@ -1,121 +0,0 @@ -# VRF and firewall example - -## Scenario and requirements - -This example shows how to configure a VyOS router with VRFs and firewall rules. - -Diagram used in this example: - -```{image} /_static/images/firewall-and-vrf-blueprints.webp -:align: center -:alt: Network Topology Diagram -:width: 80% -``` - -As exposed in the diagram, there are four VRFs. These VRFs are `MGMT`, -`WAN`, `LAN` and `PROD`, and their requirements are: - -```{eval-rst} -* VRF MGMT: - * Allow connections to LAN and PROD. - * Deny connections to internet(WAN). - * Allow connections to the router. -* VRF LAN: - * Allow connections to PROD. - * Allow connections to internet(WAN). -* VRF PROD: - * Only accepts connections. -* VRF WAN: - * Allow connection to PROD. -``` - -## Configuration - -First, we need to configure the interfaces and VRFs: - -```none -set interfaces ethernet eth1 address '10.100.100.1/24' -set interfaces ethernet eth1 vrf 'MGMT' -set interfaces ethernet eth2 vif 150 address '10.150.150.1/24' -set interfaces ethernet eth2 vif 150 vrf 'LAN' -set interfaces ethernet eth2 vif 160 address '10.160.160.1/24' -set interfaces ethernet eth2 vif 160 vrf 'LAN' -set interfaces ethernet eth2 vif 3500 address '172.16.20.1/24' -set interfaces ethernet eth2 vif 3500 vrf 'PROD' -set interfaces loopback lo -set interfaces pppoe pppoe0 authentication password 'p4ssw0rd' -set interfaces pppoe pppoe0 authentication username 'vyos' -set interfaces pppoe pppoe0 source-interface 'eth0' -set interfaces pppoe pppoe0 vrf 'WAN' -set vrf bind-to-all -set vrf name LAN protocols static route 0.0.0.0/0 interface pppoe0 vrf 'WAN' -set vrf name LAN protocols static route 10.100.100.0/24 interface eth1 vrf 'MGMT' -set vrf name LAN protocols static route 172.16.20.0/24 interface eth2.3500 vrf 'PROD' -set vrf name LAN table '103' -set vrf name MGMT protocols static route 10.150.150.0/24 interface eth2.150 vrf 'LAN' -set vrf name MGMT protocols static route 10.160.160.0/24 interface eth2.160 vrf 'LAN' -set vrf name MGMT protocols static route 172.16.20.0/24 interface eth2.3500 vrf 'PROD' -set vrf name MGMT table '102' -set vrf name PROD protocols static route 0.0.0.0/0 interface pppoe0 vrf 'WAN' -set vrf name PROD protocols static route 10.100.100.0/24 interface eth1 vrf 'MGMT' -set vrf name PROD protocols static route 10.150.150.0/24 interface eth2.150 vrf 'LAN' -set vrf name PROD protocols static route 10.160.160.0/24 interface eth2.160 vrf 'LAN' -set vrf name PROD table '104' -set vrf name WAN protocols static route 10.150.150.0/24 interface eth2.150 vrf 'LAN' -set vrf name WAN protocols static route 10.160.160.0/24 interface eth2.160 vrf 'LAN' -set vrf name WAN protocols static route 172.16.20.0/24 interface eth2.3500 vrf 'PROD' -set vrf name WAN table '101' -``` - -And before firewall rules are shown, we need to pay attention how to configure -and match interfaces and VRFs. In case where an interface is assigned to a -non-default VRF, if we want to use inbound-interface or outbound-interface in -firewall rules, we need to: - -- For **inbound-interface**: use the interface name with the VRF name, like - `MGMT` or `LAN`. -- For **outbound-interface**: use the interface name, like `eth0`, `vtun0`, - `eth2*` or similar. - -Next, we need to configure the firewall rules. First we will define all rules -for transit traffic between VRFs. - -```none -set firewall ipv4 forward filter default-action 'drop' -set firewall ipv4 forward filter default-log -set firewall ipv4 forward filter rule 10 action 'accept' -set firewall ipv4 forward filter rule 10 description 'MGMT - Allow to LAN and PROD' -set firewall ipv4 forward filter rule 10 inbound-interface name 'MGMT' -set firewall ipv4 forward filter rule 10 outbound-interface name 'eth2*' -set firewall ipv4 forward filter rule 99 action 'drop' -set firewall ipv4 forward filter rule 99 description 'MGMT - Drop all going to mgmt' -set firewall ipv4 forward filter rule 99 outbound-interface name 'eth1' -set firewall ipv4 forward filter rule 120 action 'accept' -set firewall ipv4 forward filter rule 120 description 'LAN - Allow to PROD' -set firewall ipv4 forward filter rule 120 inbound-interface name 'LAN' -set firewall ipv4 forward filter rule 120 outbound-interface name 'eth2.3500' -set firewall ipv4 forward filter rule 130 action 'accept' -set firewall ipv4 forward filter rule 130 description 'LAN - Allow internet' -set firewall ipv4 forward filter rule 130 inbound-interface name 'LAN' -set firewall ipv4 forward filter rule 130 outbound-interface name 'pppoe0' -``` - -Also, we are adding global state policies, in order to allow established and -related traffic, in order not to drop valid responses: - -```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' -``` - -And finally, we need to allow input connections to the router itself only from -vrf MGMT: - -```none -set firewall ipv4 input filter default-action 'drop' -set firewall ipv4 input filter default-log -set firewall ipv4 input filter rule 10 action 'accept' -set firewall ipv4 input filter rule 10 description 'MGMT - Allow input' -set firewall ipv4 input filter rule 10 inbound-interface name 'MGMT' -``` diff --git a/docs/configexamples/md-ha.md b/docs/configexamples/md-ha.md deleted file mode 100644 index c3fd4f84..00000000 --- a/docs/configexamples/md-ha.md +++ /dev/null @@ -1,556 +0,0 @@ ---- -lastproofread: '2021-06-28' ---- - -(example-high-availability)= - -# High Availability Walkthrough - -This document walks you through a complete HA setup of two VyOS machines. This -design is based on a VM as the primary router and a physical machine as a -backup, using VRRP, BGP, OSPF, and conntrack sharing. - -This document aims to walk you through setting everything up, so -at a point where you can reboot any machine and not lose more than a few -seconds worth of connectivity. - -## Design - -This is based on a real-life production design. One of the complex issues -is ensuring you have redundant data INTO your network. We do this with a pair -of Cisco Nexus switches and using Virtual PortChannels that are spanned across -them. As a bonus, this also allows for complete switch failure without -an outage. How you achieve this yourself is left as an exercise to the reader. -But our setup is documented here. - -### Walkthrough suggestion - -The `commit` command is implied after every section. If you make an error, -`commit` will warn you and you can fix it before getting too far into things. -Please ensure you commit early and commit often. - -If you are following through this document, it is strongly suggested you -complete the entire document, ONLY doing the virtual router1 steps, and then -come back and walk through it AGAIN on the backup hardware router. - -This ensures you don't go too fast or miss a step. However, it will make your -life easier to configure the fixed IP address and default route now on the -hardware router. - -### Example Network - -In this document, we have been allocated 203.0.113.0/24 by our upstream -provider, which we are publishing on VLAN100. - -They want us to establish a BGP session to their routers on 192.0.2.11 and -192.0.2.12 from our routers 192.0.2.21 and 192.0.2.22. They are AS 65550 and -we are AS 65551. - -Our routers are going to have a floating IP address of 203.0.113.1, and use -.2 and .3 as their fixed IPs. - -We are going to use 10.200.201.0/24 for an 'internal' network on VLAN201. - -When traffic is originated from the 10.200.201.0/24 network, it will be -masqueraded to 203.0.113.1 - -For connection between sites, we are running a WireGuard link to two REMOTE -routers and using OSPF over those links to distribute routes. That remote -site is expected to send traffic from anything in 10.201.0.0/16 - -### VLANs - -These are the vlans we will be using: - -- 50: Upstream, using the 192.0.2.0/24 network allocated by them. -- 100: 'Public' network, using our 203.0.113.0/24 network. -- 201: 'Internal' network, using 10.200.201.0/24 - -### Hardware - -- switch1 (Nexus 10gb Switch) -- switch2 (Nexus 10gb Switch) -- compute1 (VMware ESXi 6.5) -- compute2 (VMware ESXi 6.5) -- compute3 (VMware ESXi 6.5) -- router2 (Random 1RU machine with 4 NICs) - -Note that router1 is a VM that runs on one of the compute nodes. - -### Network Cabling - -- From Datacenter - This connects into port 1 on both switches, and is tagged - as VLAN 50 -- Cisco VPC Crossconnect - Ports 39 and 40 bonded between each switch -- Hardware Router - Port 8 of each switch -- compute1 - Port 9 of each switch -- compute2 - Port 10 of each switch -- compute3 - Port 11 of each switch - -This is ignoring the extra Out-of-band management networking, which should be -on totally different switches, and a different feed into the rack, and is out -of scope of this. - -:::{note} -Our implementation uses VMware's Distributed Port Groups, which allows -VMware to use LACP. This is a part of the ENTERPRISE licence, and is not -available on a free licence. If you are implementing this and do not have -access to DPGs, you should not use VMware, and use some other virtualization -platform instead. -::: - -## Basic Setup (via console) - -Create your router1 VM. So it can withstand a VM Host failing or a -network link failing. Using VMware, this is achieved by enabling vSphere DRS, -vSphere Availability, and creating a Distributed Port Group that uses LACP. - -Many other Hypervisors do this, and I'm hoping that this document will be -expanded to document how to do this for others. - -Create an 'All VLANs' network group, that passes all trunked traffic through -to the VM. Attach this network group to router1 as eth0. - -:::{note} -VMware: You must DISABLE SECURITY on this Port group. Make sure that -`Promiscuous Mode`, `MAC address changes` and `Forged transmits` are -enabled. All of these will be done as part of failover. -::: - -### Bonding on Hardware Router - -Create a LACP bond on the hardware router. We are assuming that eth0 and eth1 -are connected to port 8 on both switches, and that those ports are configured -as a Port-Channel. - -```none -set interfaces bonding bond0 description 'Switch Port-Channel' -set interfaces bonding bond0 hash-policy 'layer2' -set interfaces bonding bond0 member interface 'eth0' -set interfaces bonding bond0 member interface 'eth1' -set interfaces bonding bond0 mode '802.3ad' -``` - - -### Assign external IP addresses - -VLAN 100 and 201 will have floating IP addresses, but VLAN50 does not, as this -is talking directly to upstream. Create our IP address on vlan50. - -For the hardware router, replace `eth0` with `bond0`. As (almost) every -command is identical, this will not be specified unless different things need -to be performed on different hosts. - -```none -set interfaces ethernet eth0 vif 50 address '192.0.2.21/24' -``` - -In this case, the hardware router has a different IP, so it would be - -```none -set interfaces ethernet bond0 vif 50 address '192.0.2.22/24' -``` - - -### Add (temporary) default route - -It is assumed that the routers provided by upstream are capable of acting as a -default router, add that as a static route. - -```none -set protocols static route 0.0.0.0/0 next-hop 192.0.2.11 -commit -save -``` - - -### Enable SSH - -Enable SSH so you can now SSH into the routers, rather than using the console. - -```none -set service ssh -commit -save -``` - -At this point, you should be able to SSH into both of them, and will no longer -need access to the console (unless you break something!) - -## VRRP Configuration - -We are setting up VRRP so that it does NOT fail back when a machine returns into -service, and it prioritizes router1 over router2. - -### Internal Network - -This has a floating IP address of 10.200.201.1/24, using virtual router ID 201. -The difference between them is the interface name, hello-source-address, and -peer-address. - -**router1** - -```none -set interfaces ethernet eth0 vif 201 address 10.200.201.2/24 -set high-availability vrrp group int hello-source-address '10.200.201.2' -set high-availability vrrp group int interface 'eth0.201' -set high-availability vrrp group int peer-address '10.200.201.3' -set high-availability vrrp group int no-preempt -set high-availability vrrp group int priority '200' -set high-availability vrrp group int address '10.200.201.1/24' -set high-availability vrrp group int vrid '201' -``` - -**router2** - -```none -set interfaces ethernet bond0 vif 201 address 10.200.201.3/24 -set high-availability vrrp group int hello-source-address '10.200.201.3' -set high-availability vrrp group int interface 'bond0.201' -set high-availability vrrp group int peer-address '10.200.201.2' -set high-availability vrrp group int no-preempt -set high-availability vrrp group int priority '100' -set high-availability vrrp group int address '10.200.201.1/24' -set high-availability vrrp group int vrid '201' -``` - - -### Public Network - -This has a floating IP address of 203.0.113.1/24, using virtual router ID 113. -The virtual router ID is just a random number between 1 and 254, and can be set -to whatever you want. Best practices suggest you try to keep them unique -enterprise-wide. - -**router1** - -```none -set interfaces ethernet eth0 vif 100 address 203.0.113.2/24 -set high-availability vrrp group public hello-source-address '203.0.113.2' -set high-availability vrrp group public interface 'eth0.100' -set high-availability vrrp group public peer-address '203.0.113.3' -set high-availability vrrp group public no-preempt -set high-availability vrrp group public priority '200' -set high-availability vrrp group public address '203.0.113.1/24' -set high-availability vrrp group public vrid '113' -``` - -**router2** - -```none -set interfaces ethernet bond0 vif 100 address 203.0.113.3/24 -set high-availability vrrp group public hello-source-address '203.0.113.3' -set high-availability vrrp group public interface 'bond0.100' -set high-availability vrrp group public peer-address '203.0.113.2' -set high-availability vrrp group public no-preempt -set high-availability vrrp group public priority '100' -set high-availability vrrp group public address '203.0.113.1/24' -set high-availability vrrp group public vrid '113' -``` - - -### Create VRRP sync-group - -The sync group is used to replicate connection tracking. It needs to be assigned -to a random VRRP group, and we are creating a sync group called `sync` using -the vrrp group `int`. - -```none -set high-availability vrrp sync-group sync member 'int' -``` - - -### Testing - -At this point, you should be able to see both IP addresses when you run -`show interfaces`, and `show vrrp` should show both interfaces in MASTER -state (and SLAVE state on router2). - -```none -vyos@router1:~$ show vrrp -Name Interface VRID State Last Transition --------- ----------- ------ ------- ----------------- -int eth0.201 201 MASTER 100s -public eth0.100 113 MASTER 200s -vyos@router1:~$ -``` - -You should be able to ping to and from all the IPs you have allocated. - -## NAT and conntrack-sync - -Masquerade Traffic originating from 10.200.201.0/24 that is heading out the -public interface. - -:::{note} -We explicitly exclude the primary upstream network so that BGP or -OSPF traffic doesn't accidentally get NAT'ed. -::: - -```none -set nat source rule 10 destination address '!192.0.2.0/24' -set nat source rule 10 outbound-interface name 'eth0.50' -set nat source rule 10 source address '10.200.201.0/24' -set nat source rule 10 translation address '203.0.113.1' -``` - - -### Configure conntrack-sync and enable helpers - -Conntrack helper modules are enabled by default, but they tend to cause more -problems than they're worth in complex networks. You can disable all of them -at one go. - -```none -delete system conntrack modules -``` - -Now enable replication between nodes. Replace eth0.201 with bond0.201 on the -hardware router. - -```none -set service conntrack-sync accept-protocol 'tcp,udp,icmp' -set service conntrack-sync event-listen-queue-size '8' -set service conntrack-sync failover-mechanism vrrp sync-group 'sync' -set service conntrack-sync interface eth0.201 -set service conntrack-sync mcast-group '224.0.0.50' -set service conntrack-sync sync-queue-size '8' -``` - -(ha-contracktesting)= - -### Testing - -The simplest way to test is to look at the connection tracking stats on the -standby hardware router with the command `show conntrack-sync statistics`. -The numbers should be very close to the numbers on the primary router. - -When you have both routers up, you should be able to establish a connection -from a NAT'ed machine out to the internet, reboot the active machine, and that -connection should be preserved, and will not drop out. - -## OSPF Over WireGuard - -Wireguard doesn't have the concept of an up or down link, due to its design. -This complicates AND simplifies using it for network transport, as for reliable -state detection you need to use SOMETHING to detect when the link is down. - -If you use a routing protocol itself, you solve two problems at once. This is -only a basic example, and is provided as a starting point. - -### Configure Wireguard - -There is plenty of instructions and documentation on setting up Wireguard. The -only important thing you need to remember is to only use one WireGuard -interface per OSPF connection. - -We use small /30's from 10.254.60/24 for the point-to-point links. - -**router1** - -Replace the 203.0.113.3 with whatever the other router's IP address is. - -```none -set interfaces wireguard wg01 address '10.254.60.1/30' -set interfaces wireguard wg01 description 'router1-to-offsite1' -set interfaces wireguard wg01 peer OFFSITE1 allowed-ips '0.0.0.0/0' -set interfaces wireguard wg01 peer OFFSITE1 endpoint '203.0.113.3:50001' -set interfaces wireguard wg01 peer OFFSITE1 persistent-keepalive '15' -set interfaces wireguard wg01 peer OFFSITE1 pubkey 'GEFMOWzAyau42/HwdwfXnrfHdIISQF8YHj35rOgSZ0o=' -set interfaces wireguard wg01 port '50001' -set protocols ospf interface wg01 authentication md5 key-id 1 md5-key 'i360KoCwUGZvPq7e' -set protocols ospf interface wg01 cost '11' -set protocols ospf interface wg01 dead-interval '5' -set protocols ospf interface wg01 hello-interval '1' -set protocols ospf interface wg01 network 'point-to-point' -set protocols ospf interface wg01 priority '1' -set protocols ospf interface wg01 retransmit-interval '5' -set protocols ospf interface wg01 transmit-delay '1' -``` - -**offsite1** - -This is connecting back to the STATIC IP of router1, not the floating. - -```none -set interfaces wireguard wg01 address '10.254.60.2/30' -set interfaces wireguard wg01 description 'offsite1-to-router1' -set interfaces wireguard wg01 peer ROUTER1 allowed-ips '0.0.0.0/0' -set interfaces wireguard wg01 peer ROUTER1 endpoint '192.0.2.21:50001' -set interfaces wireguard wg01 peer ROUTER1 persistent-keepalive '15' -set interfaces wireguard wg01 peer ROUTER1 pubkey 'CKwMV3ZaLntMule2Kd3G7UyVBR7zE8/qoZgLb82EE2Q=' -set interfaces wireguard wg01 port '50001' -set protocols ospf interface wg01 authentication md5 key-id 1 md5-key 'i360KoCwUGZvPq7e' -set protocols ospf interface wg01 cost '11' -set protocols ospf interface wg01 dead-interval '5' -set protocols ospf interface wg01 hello-interval '1' -set protocols ospf interface wg01 network 'point-to-point' -set protocols ospf interface wg01 priority '1' -set protocols ospf interface wg01 retransmit-interval '5' -set protocols ospf interface wg01 transmit-delay '1' -``` - - -### Test WireGuard - -Make sure you can ping 10.254.60.1 and .2 from both routers. - -### Create Export Filter - -We only want to export the networks we know. Always do a whitelist on your route -filters, both importing and exporting. A good rule of thumb is -**'If you are not the default router for a network, don't advertise -it'**. This means we explicitly do not want to advertise the 192.0.2.0/24 -network (but do want to advertise 10.200.201.0 and 203.0.113.0, which we ARE -the default route for). This filter is applied to `redistribute connected`. -If we WERE to advertise it, the remote machines would see 192.0.2.21 available -via their default route, establish the connection, and then OSPF would say -'192.0.2.0/24 is available via this tunnel', at which point the tunnel would -break, OSPF would drop the routes, and then 192.0.2.0/24 would be reachable via -default again. This is called 'flapping'. - -```none -set policy access-list 150 description 'Outbound OSPF Redistribution' -set policy access-list 150 rule 10 action 'permit' -set policy access-list 150 rule 10 destination any -set policy access-list 150 rule 10 source inverse-mask '0.0.0.255' -set policy access-list 150 rule 10 source network '10.200.201.0' -set policy access-list 150 rule 20 action 'permit' -set policy access-list 150 rule 20 destination any -set policy access-list 150 rule 20 source inverse-mask '0.0.0.255' -set policy access-list 150 rule 20 source network '203.0.113.0' -set policy access-list 150 rule 100 action 'deny' -set policy access-list 150 rule 100 destination any -set policy access-list 150 rule 100 source any -``` - - -### Create Import Filter - -We only want to import networks we know. Our OSPF peer should only be -advertising networks in the 10.201.0.0/16 range. Note that this is an INVERSE -MATCH. You deny in access-list 100 to accept the route. - -```none -set policy access-list 100 description 'Inbound OSPF Routes from Peers' -set policy access-list 100 rule 10 action 'deny' -set policy access-list 100 rule 10 destination any -set policy access-list 100 rule 10 source inverse-mask '0.0.255.255' -set policy access-list 100 rule 10 source network '10.201.0.0' -set policy access-list 100 rule 100 action 'permit' -set policy access-list 100 rule 100 destination any -set policy access-list 100 rule 100 source any -set policy route-map PUBOSPF rule 100 action 'deny' -set policy route-map PUBOSPF rule 100 match ip address access-list '100' -set policy route-map PUBOSPF rule 500 action 'permit' -``` - - -### Enable OSPF - -Every router **must** have a unique router-id. -The 'reference-bandwidth' is used because when OSPF was originally designed, -the idea of a link faster than 1gbit was unheard of, and it does not scale -correctly. - -```none -set protocols ospf area 0.0.0.0 authentication 'md5' -set protocols ospf area 0.0.0.0 network '10.254.60.0/24' -set protocols ospf auto-cost reference-bandwidth '10000' -set protocols ospf log-adjacency-changes -set protocols ospf parameters abr-type 'cisco' -set protocols ospf parameters router-id '10.254.60.2' -set system ip protocol ospf route-map PUBOSPF -``` - - -### Test OSPF - -When you have enabled OSPF on both routers, you should be able to see each -other with the command `show ip ospf neighbour`. The state must be 'Full' -or '2-Way'. If it is not, then there is a network connectivity issue between the -hosts. This is often caused by NAT or MTU issues. You should not see any new -routes (unless this is the second pass) in the output of `show ip route` - -## Advertise connected routes - -As a reminder, only advertise routes that you are the default router for. This -is why we are NOT announcing the 192.0.2.0/24 network, because if that was -announced into OSPF, the other routers would try to connect to that network -over a tunnel that connects to that network! - -```none -set protocols ospf access-list 150 export 'connected' -set protocols ospf redistribute connected -``` - -You should now be able to see the advertised network on the other host. - -### Duplicate configuration - -At this point, you now need to create the X link between all four routers. -Use a different /30 for each link. - -### Priorities - -Set the cost on the secondary links to be 200. This means that they will not -be used unless the primary links are down. - -```none -set protocols ospf interface wg01 cost '10' -set protocols ospf interface wg01 cost '200' -``` - -This will be visible in 'show ip route'. - -## BGP - -BGP is an extremely complex network protocol. An example is provided here. - -:::{note} -Router id's must be unique. -::: - -**router1** - -The `redistribute ospf` command is there purely as an example of how this can -be expanded. In this walkthrough, it will be filtered by BGPOUT rule 10000, as -it is not 203.0.113.0/24. - -```none -set policy prefix-list BGPOUT description 'BGP Export List' -set policy prefix-list BGPOUT rule 10 action 'deny' -set policy prefix-list BGPOUT rule 10 description 'Do not advertise short masks' -set policy prefix-list BGPOUT rule 10 ge '25' -set policy prefix-list BGPOUT rule 10 prefix '0.0.0.0/0' -set policy prefix-list BGPOUT rule 100 action 'permit' -set policy prefix-list BGPOUT rule 100 description 'Our network' -set policy prefix-list BGPOUT rule 100 prefix '203.0.113.0/24' -set policy prefix-list BGPOUT rule 10000 action 'deny' -set policy prefix-list BGPOUT rule 10000 prefix '0.0.0.0/0' - -set policy route-map BGPOUT description 'BGP Export Filter' -set policy route-map BGPOUT rule 10 action 'permit' -set policy route-map BGPOUT rule 10 match ip address prefix-list 'BGPOUT' -set policy route-map BGPOUT rule 10000 action 'deny' -set policy route-map BGPPREPENDOUT description 'BGP Export Filter' -set policy route-map BGPPREPENDOUT rule 10 action 'permit' -set policy route-map BGPPREPENDOUT rule 10 set as-path prepend '65551 65551 65551' -set policy route-map BGPPREPENDOUT rule 10 match ip address prefix-list 'BGPOUT' -set policy route-map BGPPREPENDOUT rule 10000 action 'deny' - -set protocols bgp system-as 65551 -set protocols bgp address-family ipv4-unicast network 192.0.2.0/24 -set protocols bgp address-family ipv4-unicast redistribute connected metric '50' -set protocols bgp address-family ipv4-unicast redistribute ospf metric '50' -set protocols bgp neighbor 192.0.2.11 address-family ipv4-unicast route-map export 'BGPOUT' -set protocols bgp neighbor 192.0.2.11 address-family ipv4-unicast soft-reconfiguration inbound -set protocols bgp neighbor 192.0.2.11 remote-as '65550' -set protocols bgp neighbor 192.0.2.11 update-source '192.0.2.21' -set protocols bgp parameters router-id '192.0.2.21' -``` - -**router2** - -This is identical, but you use the BGPPREPENDOUT route-map to advertise the -route with a longer path. diff --git a/docs/configexamples/md-index.md b/docs/configexamples/md-index.md deleted file mode 100644 index e5a81305..00000000 --- a/docs/configexamples/md-index.md +++ /dev/null @@ -1,60 +0,0 @@ -(examples)= - -# Configuration Blueprints - -This chapter contains various configuration examples: - -```{toctree} -:maxdepth: 2 - -firewall -bgp-ipv6-unnumbered -ospf-unnumbered -azure-vpn-bgp -azure-vpn-dual-bgp -ha -wan-load-balancing -pppoe-ipv6-basic -l3vpn-hub-and-spoke -lac-lns -inter-vrf-routing-vrf-lite -dmvpn-dualhub-dualcloud -qos -segment-routing-isis -nmp -ansible -ipsec-cisco-policy-based -ipsec-cisco-route-based -ipsec-pa-route-based -policy-based-ipsec-and-firewall -site-2-site-cisco -``` - - -## Configuration Blueprints (autotest) - -The next pages contain fully automated configuration examples. - -Each lab will build and test from an external script. -The page content is generated, so changes will not take effect. - -A host `vyos-oobm` will be used as an SSH proxy. This host is just -necessary for the lab tests. - -The process will do the following steps: -1. create the lab on a eve-ng server -2. configure each host in the lab -3. do some defined tests -4. optional do an upgrade to a higher version and do step 3 again. -5. generate the documentation and include files -6. shutdown and destroy the lab, if there is no error - -```{toctree} -:maxdepth: 1 - -autotest/DHCPRelay_through_GRE/DHCPRelay_through_GRE -autotest/tunnelbroker/tunnelbroker -autotest/L3VPN_EVPN/L3VPN_EVPN -autotest/Wireguard/Wireguard -autotest/OpenVPN_with_LDAP/OpenVPN_with_LDAP -``` diff --git a/docs/configexamples/md-inter-vrf-routing-vrf-lite.md b/docs/configexamples/md-inter-vrf-routing-vrf-lite.md deleted file mode 100644 index 349a6f14..00000000 --- a/docs/configexamples/md-inter-vrf-routing-vrf-lite.md +++ /dev/null @@ -1,797 +0,0 @@ -# Inter-VRF Routing over VRF Lite - -**Virtual Routing and Forwarding** is a technology that allow multiple instance -of a routing table to exist within a single device. One of the key aspect of -**VRFs** is that do not share the same routes or interfaces, therefore packets -are forwarded between interfaces that belong to the same VRF only. - -Any information related to a VRF is not exchanged between devices -or in the -same device- by default, this is a technique called **VRF-Lite**. - -Keep networks isolated is -in general- a good principle, but there are cases -where you might need that some network can access other in a different VRF. - -The scope of this document is to cover such cases in a dynamic way without the -use of MPLS-LDP. - -General information about L3VPNs can be found in the {ref}`configuration/vrf/index:L3VPN VRFs` chapter. - -## Overview - -Let’s say we have a requirement to have multiple networks. - -- LAN 1 -- LAN 2 -- Management -- Internet - -Both LANs have to be able to route between each other, both will have managed -devices through a dedicated management network and both will need Internet -access yet the LAN2 will need access to some set of outside networks, not all. -The management network will need access to both LANs but cannot have access -to/from the outside. - -This scenario could be a nightmare applying regular routing and might need -filtering in multiple interfaces. - -A simple solution could be using different routing tables, or VRFs -for all the networks so we can keep the routing restrictions. -But for us to route between the different VRFs we would need a cable or a -logical connection between each other: - -- One cable/logical connection between LAN1 and LAN2 -- One cable/logical connection between LAN1 and Internet -- One cable/logical connection between LAN2 and Internet -- One cable/logical connection between LAN1 and Management -- One cable/logical connection between LAN2 and Management - -As we can see this is unpractical. - -To address this scenario we will use to our advantage an extension of the BGP -routing protocol that will help us in the “Export” between VRFs without the -need for MPLS. - -MP-BGP or MultiProtocol BGP introduces two main concepts to solve this -limitation: -\- Route Distinguisher (RD): Is used to distinguish between different VRFs -–called VPNs- inside the BGP Process. The RD is appended to each IPv4 Network -that is advertised into BGP for that VPN making it a unique VPNv4 route. -\- Route Target (RT): This is an extended BGP community append to the VPNv4 route -in the Import/Export process. When a route passes from the VRF routing table -into the BGP process it will add the configured export extended community(ies) -for that VPN. When that route needs to go from BGP into the VRF routing table -will only pass if that given VPN import policy matches any of the appended -community(ies) into that prefix. - -## Topology - -```{image} /_static/images/inter-vrf-routing-vrf-lite.webp -:align: center -:alt: Network Topology Diagram -:width: 70% -``` - - -### IP Schema - -```{eval-rst} -+----------+------------+----------------+------------------+ -| Device-A | Device-B | IPv4 Network | IPv6 Network | -+----------+------------+----------------+------------------+ -| Core | LAN1 | 10.1.1.0/30 | 2001:db8::/127 | -+----------+------------+----------------+------------------+ -| Core | LAN2 | 172.16.2.0/30 | 2001:db8::2/127 | -+----------+------------+----------------+------------------+ -| Core | Management | 192.168.3.0/30 | 2001:db8::4/127 | -+----------+------------+----------------+------------------+ -| Core | ISP | 10.2.2.0/30 | 2001:db8::6/127 | -+----------+------------+----------------+------------------+ -``` - -### RD & RT Schema - -```{eval-rst} -+------------+-----------+-----------+ -| VRF | RD | RT | -+------------+-----------+-----------+ -| LAN1 | 64496:1 | 64496:1 | -+------------+-----------+-----------+ -| LAN2 | 64496:2 | 64496:2 | -+------------+-----------+-----------+ -| Management | 64496:50 | 64496:50 | -+------------+-----------+-----------+ -| Internet | 64496:100 | 64496:100 | -+------------+-----------+-----------+ -``` - -## Configurations - -:::{note} -We use a static route configuration in between the Core and each -LAN and Management router, and BGP between the Core router and the ISP router -but any dynamic routing protocol can be used. -::: - -### Remote Networks - -The following template configuration can be used in each remote router based -in our topology. - -```none -# Interface Configuration -set interface eth eth address - -# Static default route back to Core -set procotols static route 0.0.0.0/0 next-hop -``` - - -### Core Router - -#### Step 1: VRF and Configurations to remote networks - -- Configuration - -Set the VRF name and Table ID, set interface address and bind it to the VRF. -Last add the static route to the remote network. - -```none -# VRF name and table ID (MANDATORY) -set vrf name table - -# Interface Configuration -set interface eth eth address - -# Assign interface to VRF -set interface eth eth vrf - -# Static route to remote Network -set vrf name protocols static route next-hop -``` - -- Verification - -Checking the routing table of the VRF should reveal both static and connected -entries active. A PING test between the Core and remote router is a way to -validate connectivity within the VRF. - -```none -# show ip route vrf -# show ipv6 route vrf - -vyos@Core:~$ show ip route vrf LAN1 -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 - -VRF LAN1: -S>* 10.0.0.0/24 [1/0] via 10.1.1.2, eth0, weight 1, 00:05:41 -C>* 10.1.1.0/30 is directly connected, eth0, 00:05:44 - -vyos@Core:~$ show ipv6 route vrf LAN1 -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 - -VRF LAN1: -C>* 2001:db8::/127 is directly connected, eth0, 00:18:43 -S>* 2001:db8:0:1::/64 [1/0] via 2001:db8::1, eth0, weight 1, 00:16:03 -C>* fe80::/64 is directly connected, eth0, 00:18:43 - -# ping vrf - -vyos@Core:~$ ping 10.1.1.2 vrf LAN1 -PING 10.1.1.2 (10.1.1.2) 56(84) bytes of data. -64 bytes from 10.1.1.2: icmp_seq=1 ttl=64 time=1.52 ms -64 bytes from 10.1.1.2: icmp_seq=2 ttl=64 time=0.830 ms -^C ---- 10.1.1.2 ping statistics --- -2 packets transmitted, 2 received, 0% packet loss, time 1002ms -rtt min/avg/max/mdev = 0.830/1.174/1.518/0.344 ms -vyos@Core:~$ ping 10.0.0.1 vrf LAN1 -PING 10.0.0.1 (10.0.0.1) 56(84) bytes of data. -64 bytes from 10.0.0.1: icmp_seq=1 ttl=64 time=0.785 ms -64 bytes from 10.0.0.1: icmp_seq=2 ttl=64 time=0.948 ms -^C ---- 10.0.0.1 ping statistics --- -2 packets transmitted, 2 received, 0% packet loss, time 1002ms -rtt min/avg/max/mdev = 0.785/0.866/0.948/0.081 ms - -vyos@Core:~$ ping 2001:db8:0:1::1 vrf LAN1 -PING 2001:db8:0:1::1(2001:db8:0:1::1) 56 data bytes -64 bytes from 2001:db8:0:1::1: icmp_seq=1 ttl=64 time=3.04 ms -64 bytes from 2001:db8:0:1::1: icmp_seq=2 ttl=64 time=1.04 ms -64 bytes from 2001:db8:0:1::1: icmp_seq=3 ttl=64 time=0.925 ms -^C ---- 2001:db8:0:1::1 ping statistics --- -3 packets transmitted, 3 received, 0% packet loss, time 2004ms -rtt min/avg/max/mdev = 0.925/1.665/3.035/0.969 ms -``` - - -#### Step 2: BGP Configuration for VRF-Lite - -- Configuration - -Setting BGP global local-as as well inside the VRF. Redistribute static -routes to inject configured networks into the BGP process but still inside -the VRF. - -```none -# set BGP global local-as -set protocols bgp system-as - -# set BGP VRF local-as and redistribution -set vrf name protocols bgp address-family redistribute static -``` - -- Verification - -Check the BGP VRF table and verify if the static routes are injected showing -the correct next-hop information. - -```none -# show ip bgp vrf -# show bgp vrf ipv6 - -vyos@Core:~$ show ip bgp vrf LAN1 -BGP table version is 3, local router ID is 10.1.1.1, vrf id 8 -Default local pref 100, local AS 64496 -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 -*> 10.0.0.0/24 10.1.1.2 0 32768 ? - -vyos@Core# run show bgp vrf LAN1 ipv6 -BGP table version is 13, local router ID is 10.1.1.1, vrf id 8 -Default local pref 100, local AS 64496 -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 -*> 2001:db8:0:1::/64 - 2001:db8::1 0 32768 ? -``` - - -#### Step 3: VPN Configuration - -- Configuration - -Within the VRF we set the Route-Distinguisher (RD) and Route-Targets (RT), -then we enable the export/import VPN. - -```none -# set Route-distinguisher -set vrf name protocols bgp address-family rd vpn export '' - -# set route-target for import/export -# Note: RT are a list that can be more than one community between apostrophe -# and separated by blank space. Ex: ' ' -set vrf name protocols bgp address-family route-target vpn export '' -set vrf name protocols bgp address-family route-target vpn import '' - -# Enable VPN export/import under this VRF -set vrf name protocols bgp address-family export vpn -set vrf name protocols bgp address-family import vpn -``` - -A key point to understand is that if we need two VRFs to communicate between -each other EXPORT rt from VRF1 has to be in the IMPORT rt list from VRF2. But -this is only in ONE direction, to complete the communication the EXPORT rt from -VRF2 has to be in the IMPORT rt list from VRF1. - -There are some cases where this is not needed -for example, in some -DDoS appliance- but most inter-vrf routing designs use the above configurations. - -- Verification - -After configured all the VRFs involved in this topology we take a deeper look -at both BGP and Routing table for the VRF LAN1 - -```none -# show ip bgp vrf -# show bgp vrf ipv6 - -vyos@Core# run show ip bgp vrf LAN1 -BGP table version is 53, local router ID is 10.1.1.1, vrf id 8 -Default local pref 100, local AS 64496 -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 -*> 0.0.0.0/0 10.2.2.2@7< 0 64497 i -*> 10.0.0.0/24 10.1.1.2 0 32768 ? -*> 10.2.2.0/30 10.2.2.2@7< 0 0 64497 ? -*> 192.0.2.0/24 10.2.2.2@7< 0 0 64497 ? -*> 192.168.0.0/24 192.168.3.2@11< 0 32768 ? -*> 198.51.100.0/24 10.2.2.2@7< 0 0 64497 ? -*> 203.0.113.0/24 10.2.2.2@7< 0 0 64497 ? - -vyos@Core# run show bgp vrf LAN1 ipv6 -BGP table version is 13, local router ID is 10.1.1.1, vrf id 8 -Default local pref 100, local AS 64496 -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 -*> ::/0 fe80::5200:ff:fe02:3@7< - 0 64497 i -*> 2001:db8::6/127 fe80::5200:ff:fe02:3@7< - 0 0 64497 ? -*> 2001:db8:0:1::/64 - 2001:db8::1 0 32768 ? -*> 2001:db8:0:3::/64 - 2001:db8::5@11< 0 32768 ? -*> 2001:db8:1::/48 fe80::5200:ff:fe02:3@7< - 0 0 64497 ? -*> 2001:db8:2::/48 fe80::5200:ff:fe02:3@7< - 0 0 64497 ? -*> 2001:db8:3::/48 fe80::5200:ff:fe02:3@7< - 0 0 64497 ? - -# show ip route vrf -# show ipv6 route vrf - -vyos@Core:~$ show ip route vrf LAN1 -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 - -VRF LAN1: -B>* 0.0.0.0/0 [20/0] via 10.2.2.2, eth3 (vrf Internet), weight 1, 00:00:38 -S>* 10.0.0.0/24 [1/0] via 10.1.1.2, eth0, weight 1, 00:29:57 -C>* 10.1.1.0/30 is directly connected, eth0, 00:29:59 -B 10.2.2.0/30 [20/0] via 10.2.2.2 (vrf Internet) inactive, weight 1, 00:00:38 -B>* 172.16.0.0/24 [20/0] via 172.16.2.2, eth1 (vrf LAN2), weight 1, 00:00:38 -B>* 192.0.2.0/24 [20/0] via 10.2.2.2, eth3 (vrf Internet), weight 1, 00:00:38 -B>* 198.51.100.0/24 [20/0] via 10.2.2.2, eth3 (vrf Internet), weight 1, 00:00:38 -B>* 203.0.113.0/24 [20/0] via 10.2.2.2, eth3 (vrf Internet), weight 1, 00:00:38 - -vyos@Core# run show ipv6 route vrf LAN1 -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 - -VRF LAN1: -B>* ::/0 [20/0] via fe80::5200:ff:fe02:3, eth3 (vrf Internet), weight 1, 00:07:50 -C>* 2001:db8::/127 is directly connected, eth0, 05:33:43 -B>* 2001:db8::6/127 [20/0] via fe80::5200:ff:fe02:3, eth3 (vrf Internet), weight 1, 00:07:50 -S>* 2001:db8:0:1::/64 [1/0] via 2001:db8::1, eth0, weight 1, 05:31:03 -B>* 2001:db8:0:3::/64 [20/0] via 2001:db8::5, eth2 (vrf Management), weight 1, 00:07:50 -B>* 2001:db8:1::/48 [20/0] via fe80::5200:ff:fe02:3, eth3 (vrf Internet), weight 1, 00:07:50 -B>* 2001:db8:2::/48 [20/0] via fe80::5200:ff:fe02:3, eth3 (vrf Internet), weight 1, 00:07:50 -B>* 2001:db8:3::/48 [20/0] via fe80::5200:ff:fe02:3, eth3 (vrf Internet), weight 1, 00:07:50 -C>* fe80::/64 is directly connected, eth0, 05:33:43 -``` - -As we can see in the BGP table any imported route has been injected with a "@" -followed by the VPN id; In the routing table of the VRF, if the route was -installed, we can see -between round brackets- the exported VRF table. - -#### Step 4: End to End verification - -Now we perform some end-to-end testing -- From Management to LAN1/LAN2 - -```none -vyos@Management:~$ ping 10.0.0.1 source-address 192.168.0.1 -PING 10.0.0.1 (10.0.0.1) from 192.168.0.1 : 56(84) bytes of data. -64 bytes from 10.0.0.1: icmp_seq=1 ttl=63 time=1.93 ms -64 bytes from 10.0.0.1: icmp_seq=2 ttl=63 time=2.12 ms -64 bytes from 10.0.0.1: icmp_seq=3 ttl=63 time=2.12 ms -^C ---- 10.0.0.1 ping statistics --- -3 packets transmitted, 3 received, 0% packet loss, time 2005ms -rtt min/avg/max/mdev = 1.931/2.056/2.123/0.088 ms -vyos@Management:~$ ping 172.16.0.1 source-address 192.168.0.1 -PING 172.16.0.1 (172.16.0.1) from 192.168.0.1 : 56(84) bytes of data. -64 bytes from 172.16.0.1: icmp_seq=1 ttl=63 time=1.62 ms -64 bytes from 172.16.0.1: icmp_seq=2 ttl=63 time=1.75 ms -^C ---- 172.16.0.1 ping statistics --- -2 packets transmitted, 2 received, 0% packet loss, time 1001ms -rtt min/avg/max/mdev = 1.621/1.686/1.752/0.065 ms -vyos@Management:~$ ping 2001:db8:0:1::1 source-address 2001:db8:0:3::1 -PING 2001:db8:0:1::1(2001:db8:0:1::1) from 2001:db8:0:3::1 : 56 data bytes -64 bytes from 2001:db8:0:1::1: icmp_seq=1 ttl=63 time=2.44 ms -64 bytes from 2001:db8:0:1::1: icmp_seq=2 ttl=63 time=2.40 ms -64 bytes from 2001:db8:0:1::1: icmp_seq=3 ttl=63 time=2.41 ms -^C ---- 2001:db8:0:1::1 ping statistics --- -3 packets transmitted, 3 received, 0% packet loss, time 2003ms -rtt min/avg/max/mdev = 2.399/2.418/2.442/0.017 ms -vyos@Management:~$ ping 2001:db8:0:2::1 source-address 2001:db8:0:3::1 -PING 2001:db8:0:2::1(2001:db8:0:2::1) from 2001:db8:0:3::1 : 56 data bytes -64 bytes from 2001:db8:0:2::1: icmp_seq=1 ttl=63 time=1.66 ms -64 bytes from 2001:db8:0:2::1: icmp_seq=2 ttl=63 time=1.99 ms -64 bytes from 2001:db8:0:2::1: icmp_seq=3 ttl=63 time=1.88 ms -64 bytes from 2001:db8:0:2::1: icmp_seq=4 ttl=63 time=2.32 ms -^C ---- 2001:db8:0:2::1 ping statistics --- -4 packets transmitted, 4 received, 0% packet loss, time 3005ms -rtt min/avg/max/mdev = 1.660/1.960/2.315/0.236 ms -``` - -- From Management to Outside (fails as intended) - -```none -vyos@Management:~$ show ip route -Codes: K - kernel route, C - connected, S - static, R - RIP, - O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, - T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, - f - OpenFabric, - > - selected route, * - FIB route, q - queued, r - rejected, b - backup - t - trapped, o - offload failure - -S>* 0.0.0.0/0 [1/0] via 192.168.3.1, eth2, weight 1, 00:01:58 -C>* 192.168.0.0/24 is directly connected, dum0, 00:02:05 -C>* 192.168.3.0/30 is directly connected, eth2, 00:02:03 -vyos@Management:~$ ping 192.0.2.1 -PING 192.0.2.1 (192.0.2.1) 56(84) bytes of data. -From 192.168.3.1 icmp_seq=1 Destination Net Unreachable -From 192.168.3.1 icmp_seq=2 Destination Net Unreachable -^C ---- 192.0.2.1 ping statistics --- -2 packets transmitted, 0 received, +2 errors, 100% packet loss, time 1002ms - -vyos@Management:~$ ping 195.51.100.1 -PING 195.51.100.1 (195.51.100.1) 56(84) bytes of data. -From 192.168.3.1 icmp_seq=1 Destination Net Unreachable -From 192.168.3.1 icmp_seq=2 Destination Net Unreachable -From 192.168.3.1 icmp_seq=3 Destination Net Unreachable -^C ---- 195.51.100.1 ping statistics --- -3 packets transmitted, 0 received, +3 errors, 100% packet loss, time 2003ms - -vyos@Management:~$ ping 2001:db8:1::1 -PING 2001:db8:1::1(2001:db8:1::1) 56 data bytes -From 2001:db8::4 icmp_seq=1 Destination unreachable: No route -From 2001:db8::4 icmp_seq=2 Destination unreachable: No route -^C ---- 2001:db8:1::1 ping statistics --- -2 packets transmitted, 0 received, +2 errors, 100% packet loss, time 1002ms - -vyos@Management:~$ ping 2001:db8:2::1 -PING 2001:db8:2::1(2001:db8:2::1) 56 data bytes -From 2001:db8::4 icmp_seq=1 Destination unreachable: No route -From 2001:db8::4 icmp_seq=2 Destination unreachable: No route -^C ---- 2001:db8:2::1 ping statistics --- -2 packets transmitted, 0 received, +2 errors, 100% packet loss, time 1002ms -``` - -- LAN1 to Outside - -```none -vyos@LAN1:~$ ping 192.0.2.1 source-address 10.0.0.1 -PING 192.0.2.1 (192.0.2.1) from 10.0.0.1 : 56(84) bytes of data. -64 bytes from 192.0.2.1: icmp_seq=1 ttl=63 time=1.47 ms -64 bytes from 192.0.2.1: icmp_seq=2 ttl=63 time=1.41 ms -64 bytes from 192.0.2.1: icmp_seq=3 ttl=63 time=1.80 ms -^C ---- 192.0.2.1 ping statistics --- -3 packets transmitted, 3 received, 0% packet loss, time 2004ms -rtt min/avg/max/mdev = 1.414/1.563/1.803/0.171 ms -vyos@LAN1:~$ ping 198.51.100.1 source-address 10.0.0.1 -PING 198.51.100.1 (198.51.100.1) from 10.0.0.1 : 56(84) bytes of data. -64 bytes from 198.51.100.1: icmp_seq=1 ttl=63 time=1.71 ms -64 bytes from 198.51.100.1: icmp_seq=2 ttl=63 time=1.83 ms -^C ---- 198.51.100.1 ping statistics --- -2 packets transmitted, 2 received, 0% packet loss, time 1002ms -rtt min/avg/max/mdev = 1.705/1.766/1.828/0.061 ms -vyos@LAN1:~$ ping 203.0.113.1 source-address 10.0.0.1 -PING 203.0.113.1 (203.0.113.1) from 10.0.0.1 : 56(84) bytes of data. -64 bytes from 203.0.113.1: icmp_seq=1 ttl=63 time=1.25 ms -64 bytes from 203.0.113.1: icmp_seq=2 ttl=63 time=1.88 ms -^C ---- 203.0.113.1 ping statistics --- -2 packets transmitted, 2 received, 0% packet loss, time 1003ms -rtt min/avg/max/mdev = 1.249/1.566/1.884/0.317 ms -vyos@LAN1:~$ ping 2001:db8:1::1 source-address 2001:db8:0:1::1 -PING 2001:db8:1::1(2001:db8:1::1) from 2001:db8:0:1::1 : 56 data bytes -64 bytes from 2001:db8:1::1: icmp_seq=1 ttl=63 time=2.35 ms -64 bytes from 2001:db8:1::1: icmp_seq=2 ttl=63 time=2.29 ms -64 bytes from 2001:db8:1::1: icmp_seq=3 ttl=63 time=2.22 ms -^C ---- 2001:db8:1::1 ping statistics --- -3 packets transmitted, 3 received, 0% packet loss, time 2004ms -rtt min/avg/max/mdev = 2.215/2.285/2.352/0.055 ms -vyos@LAN1:~$ ping 2001:db8:2::1 source-address 2001:db8:0:1::1 -PING 2001:db8:2::1(2001:db8:2::1) from 2001:db8:0:1::1 : 56 data bytes -64 bytes from 2001:db8:2::1: icmp_seq=1 ttl=63 time=1.37 ms -64 bytes from 2001:db8:2::1: icmp_seq=2 ttl=63 time=2.68 ms -64 bytes from 2001:db8:2::1: icmp_seq=3 ttl=63 time=2.00 ms -^C ---- 2001:db8:2::1 ping statistics --- -3 packets transmitted, 3 received, 0% packet loss, time 2003ms -rtt min/avg/max/mdev = 1.367/2.015/2.679/0.535 ms -``` - -:::{note} -we are using "source-address" option cause we are not redistributing -connected interfaces into BGP on the Core router hence there is no comeback -route and ping will fail. -::: - -- LAN1 to LAN2 - -```none -vyos@LAN1:~$ ping 172.16.0.1 source-address 10.0.0.1 -PING 172.16.0.1 (172.16.0.1) from 10.0.0.1 : 56(84) bytes of data. -64 bytes from 172.16.0.1: icmp_seq=1 ttl=63 time=3.00 ms -64 bytes from 172.16.0.1: icmp_seq=2 ttl=63 time=2.20 ms -^C ---- 172.16.0.1 ping statistics --- -2 packets transmitted, 2 received, 0% packet loss, time 1002ms -rtt min/avg/max/mdev = 2.199/2.600/3.001/0.401 ms -vyos@LAN1:~$ ping 2001:db8:0:2::1 source 2001:db8:0:1::1 -PING 2001:db8:0:2::1(2001:db8:0:2::1) from 2001:db8:0:1::1 : 56 data bytes -64 bytes from 2001:db8:0:2::1: icmp_seq=1 ttl=63 time=4.82 ms -64 bytes from 2001:db8:0:2::1: icmp_seq=2 ttl=63 time=1.95 ms -64 bytes from 2001:db8:0:2::1: icmp_seq=3 ttl=63 time=1.98 ms -^C ---- 2001:db8:0:2::1 ping statistics --- -3 packets transmitted, 3 received, 0% packet loss, time 2003ms -rtt min/avg/max/mdev = 1.949/2.915/4.815/1.343 ms -``` - - -## Conclusions - -Inter-VRF routing is a well-known solution to address complex routing scenarios -that enable -in a dynamic way- to leak routes between VRFs. Is recommended to -take special consideration while designing route-targets and its application as -it can minimize future interventions while creating a new VRF will automatically -take the desired effect in its propagation. - -## Appendix-A - -### Full configuration from all devices - -- Core - -```none -set interfaces ethernet eth0 address '10.1.1.1/30' -set interfaces ethernet eth0 address '2001:db8::/127' -set interfaces ethernet eth0 vrf 'LAN1' -set interfaces ethernet eth1 address '172.16.2.1/30' -set interfaces ethernet eth1 address '2001:db8::2/127' -set interfaces ethernet eth1 vrf 'LAN2' -set interfaces ethernet eth2 address '192.168.3.1/30' -set interfaces ethernet eth2 address '2001:db8::4/127' -set interfaces ethernet eth2 vrf 'Management' -set interfaces ethernet eth3 address '10.2.2.1/30' -set interfaces ethernet eth3 address '2001:db8::6/127' -set interfaces ethernet eth3 vrf 'Internet' -set protocols bgp address-family ipv4-unicast -set protocols bgp system-as '64496' -set vrf name Internet protocols bgp address-family ipv4-unicast export vpn -set vrf name Internet protocols bgp address-family ipv4-unicast import vpn -set vrf name Internet protocols bgp address-family ipv4-unicast rd vpn export '64496:100' -set vrf name Internet protocols bgp address-family ipv4-unicast route-target vpn export '64496:100' -set vrf name Internet protocols bgp address-family ipv4-unicast route-target vpn import '64496:1 64496:2' -set vrf name Internet protocols bgp address-family ipv6-unicast export vpn -set vrf name Internet protocols bgp address-family ipv6-unicast import vpn -set vrf name Internet protocols bgp address-family ipv6-unicast rd vpn export '64496:100' -set vrf name Internet protocols bgp address-family ipv6-unicast route-target vpn export '64496:100' -set vrf name Internet protocols bgp address-family ipv6-unicast route-target vpn import '64496:1 64496:2' -set vrf name Internet protocols bgp neighbor 10.2.2.2 address-family ipv4-unicast -set vrf name Internet protocols bgp neighbor 10.2.2.2 remote-as '64497' -set vrf name Internet protocols bgp neighbor 2001:db8::7 address-family ipv6-unicast -set vrf name Internet protocols bgp neighbor 2001:db8::7 remote-as '64497' -set vrf name Internet table '104' -set vrf name LAN1 protocols bgp address-family ipv4-unicast export vpn -set vrf name LAN1 protocols bgp address-family ipv4-unicast import vpn -set vrf name LAN1 protocols bgp address-family ipv4-unicast rd vpn export '64496:1' -set vrf name LAN1 protocols bgp address-family ipv4-unicast redistribute static -set vrf name LAN1 protocols bgp address-family ipv4-unicast route-target vpn export '64496:1' -set vrf name LAN1 protocols bgp address-family ipv4-unicast route-target vpn import '64496:100 64496:50 64496:2' -set vrf name LAN1 protocols bgp address-family ipv6-unicast export vpn -set vrf name LAN1 protocols bgp address-family ipv6-unicast import vpn -set vrf name LAN1 protocols bgp address-family ipv6-unicast rd vpn export '64496:1' -set vrf name LAN1 protocols bgp address-family ipv6-unicast redistribute static -set vrf name LAN1 protocols bgp address-family ipv6-unicast route-target vpn export '64496:1' -set vrf name LAN1 protocols bgp address-family ipv6-unicast route-target vpn import '64496:100 64496:50 64496:2' -set vrf name LAN1 protocols static route 10.0.0.0/24 next-hop 10.1.1.2 -set vrf name LAN1 protocols static route6 2001:db8:0:1::/64 next-hop 2001:db8::1 -set vrf name LAN1 table '101' -set vrf name LAN2 protocols bgp address-family ipv4-unicast export vpn -set vrf name LAN2 protocols bgp address-family ipv4-unicast import vpn -set vrf name LAN2 protocols bgp address-family ipv4-unicast rd vpn export '64496:2' -set vrf name LAN2 protocols bgp address-family ipv4-unicast redistribute static -set vrf name LAN2 protocols bgp address-family ipv4-unicast route-target vpn export '64496:2' -set vrf name LAN2 protocols bgp address-family ipv4-unicast route-target vpn import '64496:100 64496:50 64496:1' -set vrf name LAN2 protocols bgp address-family ipv6-unicast export vpn -set vrf name LAN2 protocols bgp address-family ipv6-unicast import vpn -set vrf name LAN2 protocols bgp address-family ipv6-unicast rd vpn export '64496:2' -set vrf name LAN2 protocols bgp address-family ipv6-unicast redistribute static -set vrf name LAN2 protocols bgp address-family ipv6-unicast route-target vpn export '64496:2' -set vrf name LAN2 protocols bgp address-family ipv6-unicast route-target vpn import '64496:100 64496:50 64496:1' -set vrf name LAN2 protocols static route 172.16.0.0/24 next-hop 172.16.2.2 -set vrf name LAN2 protocols static route6 2001:db8:0:2::/64 next-hop 2001:db8::3 -set vrf name LAN2 table '102' -set vrf name Management protocols bgp address-family ipv4-unicast export vpn -set vrf name Management protocols bgp address-family ipv4-unicast import vpn -set vrf name Management protocols bgp address-family ipv4-unicast rd vpn export '64496:50' -set vrf name Management protocols bgp address-family ipv4-unicast redistribute static -set vrf name Management protocols bgp address-family ipv4-unicast route-target vpn export '64496:50' -set vrf name Management protocols bgp address-family ipv4-unicast route-target vpn import '64496:1 64496:2' -set vrf name Management protocols bgp address-family ipv6-unicast export vpn -set vrf name Management protocols bgp address-family ipv6-unicast import vpn -set vrf name Management protocols bgp address-family ipv6-unicast rd vpn export '64496:50' -set vrf name Management protocols bgp address-family ipv6-unicast redistribute static -set vrf name Management protocols bgp address-family ipv6-unicast route-target vpn export '64496:50' -set vrf name Management protocols bgp address-family ipv6-unicast route-target vpn import '64496:1 64496:2' -set vrf name Management protocols static route 192.168.0.0/24 next-hop 192.168.3.2 -set vrf name Management protocols static route6 2001:db8:0:3::/64 next-hop 2001:db8::5 -set vrf name Management table '103' -``` - -- LAN1 - -```none -set interfaces dummy dum0 address '10.0.0.1/24' -set interfaces dummy dum0 address '2001:db8:0:1::1/64' -set interfaces ethernet eth0 address '10.1.1.2/30' -set interfaces ethernet eth0 address '2001:db8::1/127' -set protocols static route 0.0.0.0/0 next-hop 10.1.1.1 -set protocols static route6 ::/0 next-hop 2001:db8::1 -``` - -- LAN2 - -```none -set interfaces dummy dum0 address '172.16.0.1/24' -set interfaces dummy dum0 address '2001:db8:0:2::1/64' -set interfaces ethernet eth0 hw-id '50:00:00:03:00:00' -set interfaces ethernet eth1 address '172.16.2.2/30' -set interfaces ethernet eth1 address '2001:db8::3/127' -set protocols static route 0.0.0.0/0 next-hop 172.16.2.1 -set protocols static route6 ::/0 next-hop 2001:db8::2 -``` - -- Management - -```none -set interfaces dummy dum0 address '192.168.0.1/24' -set interfaces dummy dum0 address '2001:db8:0:3::1/64' -set interfaces ethernet eth2 address '192.168.3.2/30' -set interfaces ethernet eth2 address '2001:db8::5/127' -set protocols static route 0.0.0.0/0 next-hop 192.168.3.1 -set protocols static route6 ::/0 next-hop 2001:db8::4 -``` - -- ISP - -```none -set interfaces dummy dum0 address '192.0.2.1/24' -set interfaces dummy dum0 address '2001:db8:1::1/48' -set interfaces dummy dum1 address '198.51.100.1/24' -set interfaces dummy dum1 address '2001:db8:2::1/48' -set interfaces dummy dum2 address '203.0.113.1/24' -set interfaces dummy dum2 address '2001:db8:3::1/48' -set interfaces ethernet eth3 address '10.2.2.2/30' -set interfaces ethernet eth3 address '2001:db8::7/127' -set protocols bgp address-family ipv4-unicast redistribute connected -set protocols bgp address-family ipv6-unicast redistribute connected -set protocols bgp system-as '64497' -set protocols bgp neighbor 10.2.2.1 address-family ipv4-unicast default-originate -set protocols bgp neighbor 10.2.2.1 remote-as '64496' -set protocols bgp neighbor 2001:db8::6 address-family ipv6-unicast default-originate -set protocols bgp neighbor 2001:db8::6 remote-as '64496' -set protocols static route 0.0.0.0/0 next-hop 10.2.2.1 -set protocols static route6 ::/0 next-hop 2001:db8::6 -``` - - -## Appendix-B - -### Route-Filtering - -When importing routes using MP-BGP it is possible to filter a subset of them -before are injected in the BGP table. One of the most common case is to use a -route-map with an prefix-list. -- Configuration - -We create a prefix-list first and add all the routes we need to. - -```none -# set both ipv4 and ipv6 policies - -set policy prefix-list LAN2-Internet rule 1 action 'permit' -set policy prefix-list LAN2-Internet rule 1 le '24' -set policy prefix-list LAN2-Internet rule 1 prefix '198.51.0.0/16' -set policy prefix-list LAN2-Internet rule 2 action 'permit' -set policy prefix-list LAN2-Internet rule 2 prefix '192.0.2.0/24' -set policy prefix-list LAN2-Internet rule 3 action 'permit' -set policy prefix-list LAN2-Internet rule 3 prefix '192.168.0.0/24' -set policy prefix-list LAN2-Internet rule 4 action 'permit' -set policy prefix-list LAN2-Internet rule 4 prefix '10.0.0.0/24' - -set policy prefix-list6 LAN2-Internet-v6 rule 1 action 'permit' -set policy prefix-list6 LAN2-Internet-v6 rule 1 prefix '2001:db8:1::/48' -set policy prefix-list6 LAN2-Internet-v6 rule 2 action 'permit' -set policy prefix-list6 LAN2-Internet-v6 rule 2 prefix '2001:db8:2::/48' -set policy prefix-list6 LAN2-Internet-v6 rule 3 action 'permit' -set policy prefix-list6 LAN2-Internet-v6 rule 3 prefix '2001:db8:0:3::/64' -set policy prefix-list6 LAN2-Internet-v6 rule 4 action 'permit' -set policy prefix-list6 LAN2-Internet-v6 rule 4 prefix '2001:db8:0:1::/64' -``` - -Then add a route-map and reference to above prefix. Consider that the actions -taken inside the prefix will MATCH the routes that will be affected by the -actions inside the rules of the route-map. - -```none -set policy route-map LAN2-Internet rule 1 action 'permit' -set policy route-map LAN2-Internet rule 1 match ip address prefix-list 'LAN2-Internet' - -set policy route-map LAN2-Internet-v6 rule 1 action 'permit' -set policy route-map LAN2-Internet-v6 rule 1 match ipv6 address prefix-list 'LAN2-Internet-v6' -``` - -We are using a "white list" approach by allowing only what is necessary. In case -that need to implement a "black list" approach then you will need to change the -action in the route-map for a deny BUT you need to add a rule that permits the -rest due to the implicit deny in the route-map. - -Then we need to attach the policy to the BGP process. This needs to be under -the import statement in the vrf we need to filter. - -```none -set vrf name LAN2 protocols bgp address-family ipv4-unicast route-map vpn import 'LAN2-Internet' -set vrf name LAN2 protocols bgp address-family ipv6-unicast route-map vpn import 'LAN2-Internet-v6' -``` - -- Verification - -```none -# show ip route vrf LAN2 - -B>* 10.0.0.0/24 [20/0] via 10.1.1.2, eth0 (vrf LAN1), weight 1, 00:45:28 -S>* 172.16.0.0/24 [1/0] via 172.16.2.2, eth1, weight 1, 00:45:32 -C>* 172.16.2.0/30 is directly connected, eth1, 00:45:39 -B>* 192.0.2.0/24 [20/0] via 10.2.2.2, eth3 (vrf Internet), weight 1, 00:45:24 -B>* 192.168.0.0/24 [20/0] via 192.168.3.2, eth2 (vrf Managment), weight 1, 00:45:27 -B>* 198.51.100.0/24 [20/0] via 10.2.2.2, eth3 (vrf Internet), weight 1, 00:45:24 - -# show ipv6 route vrf LAN2 - -C>* 2001:db8::2/127 is directly connected, eth1, 00:46:26 -B>* 2001:db8:0:1::/64 [20/0] via 2001:db8::1, eth0 (vrf LAN1), weight 1, 00:46:17 -S>* 2001:db8:0:2::/64 [1/0] via 2001:db8::3, eth1, weight 1, 00:46:21 -B>* 2001:db8:0:3::/64 [20/0] via 2001:db8::5, eth2 (vrf Managment), weight 1, 00:46:16 -B>* 2001:db8:1::/48 [20/0] via fe80::5200:ff:fe02:3, eth3 (vrf Internet), weight 1, 00:46:13 -B>* 2001:db8:2::/48 [20/0] via fe80::5200:ff:fe02:3, eth3 (vrf Internet), weight 1, 00:46:13 -C>* fe80::/64 is directly connected, eth1, 00:46:27 -``` - -As we can see even if both VRF LAN1 and LAN2 has the same import RTs we are able -to select which routes are effectively imported and installed. diff --git a/docs/configexamples/md-ipsec-cisco-policy-based.md b/docs/configexamples/md-ipsec-cisco-policy-based.md deleted file mode 100644 index 7a31601d..00000000 --- a/docs/configexamples/md-ipsec-cisco-policy-based.md +++ /dev/null @@ -1,363 +0,0 @@ ---- -lastproofread: '2025-06-26' ---- - -(examples-ipsec-cisco-policy-based)= - -# Policy-based Site-to-Site VPN IPsec between VyOS and Cisco - -This document is to describe a basic setup using policy-based -site-to-site VPN IPsec. In this example we use VyOS 1.5 and -Cisco IOS. Cisco initiates IPsec connection only if interesting -traffic present. For stable work we recommend configuring an -initiator role on VyOS side. - -## Network Topology - -```{image} /_static/images/cisco-vpn-ipsec.webp -:align: center -:alt: Network Topology Diagram -``` - - -## Prerequirements - -**VyOS:** - -```{eval-rst} -+---------+----------------+ -| WAN IP | 10.0.1.2/30 | -+---------+----------------+ -| LAN1 IP | 192.168.0.1/24 | -+---------+----------------+ -| LAN2 IP | 192.168.1.1/24 | -+---------+----------------+ -``` - -**Cisco:** - -```{eval-rst} -+---------+-----------------+ -| WAN IP | 10.0.2.2/30 | -+---------+-----------------+ -| LAN1 IP | 192.168.10.1/24 | -+---------+-----------------+ -| LAN2 IP | 192.168.11.1/24 | -+---------+-----------------+ -``` - -**IKE parameters:** - -```{eval-rst} -+-------------------+---------+ -| Encryption | AES-256 | -+-------------------+---------+ -| HASH | SHA-1 | -+-------------------+---------+ -| Diff-Helman Group | 14 | -+-------------------+---------+ -| Life-Time | 28800 | -+-------------------+---------+ -| IKE Version | 2 | -+-------------------+---------+ -``` - -**IPsec parameters:** - -```{eval-rst} -+------------+---------+ -| Encryption | AES-256 | -+------------+---------+ -| HASH | SHA-256 | -+------------+---------+ -| Life-Time | 3600 | -+------------+---------+ -| PFS | disable | -+------------+---------+ -``` - -```{eval-rst} -**Traffic Selectors** - 192.168.0.0/24 <==> 192.168.10.0/24 - - 192.168.1.0/24 <==> 192.168.11.0/24 -``` - -**Hosts configuration** - -```{eval-rst} -+--------+--------------+ -| PC1 IP | 192.168.0.2 | -+--------+--------------+ -| PC2 IP | 192.168.1.2 | -+--------+--------------+ -| PC3 IP | 192.168.10.2 | -+--------+--------------+ -| PC4 IP | 192.168.11.2 | -+--------+--------------+ -``` - -## Configuration - -:::{note} -Pfs is disabled in Cisco by default. -::: - -### VyOS - -```none -set interfaces ethernet eth0 address '10.0.1.2/30' -set interfaces ethernet eth1 address '192.168.0.1/24' -set interfaces ethernet eth2 address '192.168.1.1/24' -set protocols static route 0.0.0.0/0 next-hop 10.0.1.1 -set vpn ipsec authentication psk AUTH-PSK id '10.0.1.2' -set vpn ipsec authentication psk AUTH-PSK id '10.0.2.2' -set vpn ipsec authentication psk AUTH-PSK secret 'dGVzdA==' -set vpn ipsec authentication psk AUTH-PSK secret-type 'base64' -set vpn ipsec esp-group ESP-GROUP lifetime '3600' -set vpn ipsec esp-group ESP-GROUP pfs 'disable' -set vpn ipsec esp-group ESP-GROUP proposal 10 encryption 'aes256' -set vpn ipsec esp-group ESP-GROUP proposal 10 hash 'sha256' -set vpn ipsec ike-group IKE-GROUP close-action 'start' -set vpn ipsec ike-group IKE-GROUP dead-peer-detection action 'restart' -set vpn ipsec ike-group IKE-GROUP dead-peer-detection interval '10' -set vpn ipsec ike-group IKE-GROUP key-exchange 'ikev2' -set vpn ipsec ike-group IKE-GROUP lifetime '28800' -set vpn ipsec ike-group IKE-GROUP proposal 10 dh-group '14' -set vpn ipsec ike-group IKE-GROUP proposal 10 encryption 'aes256' -set vpn ipsec ike-group IKE-GROUP proposal 10 hash 'sha1' -set vpn ipsec site-to-site peer CISCO authentication local-id '10.0.1.2' -set vpn ipsec site-to-site peer CISCO authentication mode 'pre-shared-secret' -set vpn ipsec site-to-site peer CISCO authentication remote-id '10.0.2.2' -set vpn ipsec site-to-site peer CISCO connection-type 'initiate' -set vpn ipsec site-to-site peer CISCO default-esp-group 'ESP-GROUP' -set vpn ipsec site-to-site peer CISCO ike-group 'IKE-GROUP' -set vpn ipsec site-to-site peer CISCO local-address '10.0.1.2' -set vpn ipsec site-to-site peer CISCO remote-address '10.0.2.2' -set vpn ipsec site-to-site peer CISCO tunnel 1 local prefix '192.168.0.0/24' -set vpn ipsec site-to-site peer CISCO tunnel 1 remote prefix '192.168.10.0/24' -set vpn ipsec site-to-site peer CISCO tunnel 2 local prefix '192.168.1.0/24' -set vpn ipsec site-to-site peer CISCO tunnel 2 remote prefix '192.168.11.0/24' -``` - - -### Cisco - -```none -crypto ikev2 proposal aes-cbc-256-proposal - encryption aes-cbc-256 - integrity sha1 - group 14 -! -crypto ikev2 policy policy1 - match address local 10.0.2.2 - proposal aes-cbc-256-proposal -! -crypto ikev2 keyring keys - peer VyOS - address 10.0.1.2 - pre-shared-key local test - pre-shared-key remote test -! -crypto ikev2 profile IKEv2-profile - match identity remote address 10.0.1.2 255.255.255.255 - authentication remote pre-share - authentication local pre-share - keyring local keys - lifetime 28800 -! -crypto ipsec transform-set TS esp-aes 256 esp-sha256-hmac - mode tunnel -! -crypto map IPSEC-map 10 ipsec-isakmp - set peer 10.0.1.2 - set security-association lifetime seconds 3600 - set transform-set TS - set ikev2-profile IKEv2-profile - match address cryptoacl -! -interface GigabitEthernet0/0 - ip address 10.0.2.2 255.255.255.252 - crypto map IPSEC-map -! -interface GigabitEthernet0/1 - ip address 192.168.10.1 255.255.255.0 -! -interface GigabitEthernet0/2 - ip address 192.168.11.1 255.255.255.0 -! -ip route 0.0.0.0 0.0.0.0 10.0.2.1 -! -ip access-list extended cryptoacl - permit ip 192.168.10.0 0.0.0.255 192.168.0.0 0.0.0.255 - permit ip 192.168.11.0 0.0.0.255 192.168.1.0 0.0.0.255 -``` - - -## Monitoring - -### Monitoring on VyOS side - -IKE SAs: - -```none -vyos@vyos:~$ show vpn ike sa -Peer ID / IP Local ID / IP ------------- ------------- -10.0.2.2 10.0.2.2 10.0.1.2 10.0.1.2 - - State IKEVer Encrypt Hash D-H Group NAT-T A-Time L-Time - ----- ------ ------- ---- --------- ----- ------ ------ - up IKEv2 AES_CBC_256 HMAC_SHA1_96 MODP_2048 no 304 26528 -``` - -IPsec SAs: - -```none -vyos@vyos:~$ show vpn ipsec sa -Connection State Uptime Bytes In/Out Packets In/Out Remote address Remote ID Proposal --------------- ------- -------- -------------- ---------------- ---------------- ----------- ----------------------------- -CISCO-tunnel-1 up 6m6s 0B/0B 0/0 10.0.2.2 10.0.2.2 AES_CBC_256/HMAC_SHA2_256_128 -CISCO-tunnel-2 up 6m6s 0B/0B 0/0 10.0.2.2 10.0.2.2 AES_CBC_256/HMAC_SHA2_256_128 -``` - - -### Monitoring on Cisco side - -IKE SAs: - -```none -Cisco#show crypto ikev2 sa - IPv4 Crypto IKEv2 SA - -Tunnel-id Local Remote fvrf/ivrf Status -1 10.0.2.2/4500 10.0.1.2/4500 none/none READY - Encr: AES-CBC, keysize: 256, PRF: SHA1, Hash: SHA96, DH Grp:14, Auth sign: PSK, Auth verify: PSK - Life/Active Time: 28800/471 sec - - IPv6 Crypto IKEv2 SA -``` - -IPsec SAs: - -```none - Cisco#show crypto ipsec sa - -interface: GigabitEthernet0/0 - Crypto map tag: IPSEC-map, local addr 10.0.2.2 - - protected vrf: (none) - local ident (addr/mask/prot/port): (192.168.11.0/255.255.255.0/0/0) - remote ident (addr/mask/prot/port): (192.168.1.0/255.255.255.0/0/0) - current_peer 10.0.1.2 port 4500 - PERMIT, flags={origin_is_acl,} - #pkts encaps: 0, #pkts encrypt: 0, #pkts digest: 0 - #pkts decaps: 0, #pkts decrypt: 0, #pkts verify: 0 - #pkts compressed: 0, #pkts decompressed: 0 - #pkts not compressed: 0, #pkts compr. failed: 0 - #pkts not decompressed: 0, #pkts decompress failed: 0 - #send errors 0, #recv errors 0 - - local crypto endpt.: 10.0.2.2, remote crypto endpt.: 10.0.1.2 - plaintext mtu 1438, path mtu 1500, ip mtu 1500, ip mtu idb GigabitEthernet0/0 - current outbound spi: 0xC81F83DA(3357508570) - PFS (Y/N): N, DH group: none - - inbound esp sas: - spi: 0x8C63C51E(2355348766) - transform: esp-256-aes esp-sha256-hmac , - in use settings ={Tunnel, } - conn id: 23, flow_id: SW:23, sibling_flags 80000040, crypto map: IPSEC-map - sa timing: remaining key lifetime (k/sec): (4231729/3585) - IV size: 16 bytes - replay detection support: Y - Status: ACTIVE(ACTIVE) - - inbound ah sas: - - inbound pcp sas: - - outbound esp sas: - spi: 0xC81F83DA(3357508570) - transform: esp-256-aes esp-sha256-hmac , - in use settings ={Tunnel, } - conn id: 24, flow_id: SW:24, sibling_flags 80000040, crypto map: IPSEC-map - sa timing: remaining key lifetime (k/sec): (4231729/3585) - IV size: 16 bytes - replay detection support: Y - Status: ACTIVE(ACTIVE) - - outbound ah sas: - - outbound pcp sas: - - protected vrf: (none) - local ident (addr/mask/prot/port): (192.168.10.0/255.255.255.0/0/0) - remote ident (addr/mask/prot/port): (192.168.0.0/255.255.255.0/0/0) - current_peer 10.0.1.2 port 4500 - PERMIT, flags={origin_is_acl,} - #pkts encaps: 0, #pkts encrypt: 0, #pkts digest: 0 - #pkts decaps: 0, #pkts decrypt: 0, #pkts verify: 0 - #pkts compressed: 0, #pkts decompressed: 0 - #pkts not compressed: 0, #pkts compr. failed: 0 - #pkts not decompressed: 0, #pkts decompress failed: 0 - #send errors 0, #recv errors 0 - - local crypto endpt.: 10.0.2.2, remote crypto endpt.: 10.0.1.2 - plaintext mtu 1438, path mtu 1500, ip mtu 1500, ip mtu idb GigabitEthernet0/0 - current outbound spi: 0xC40C7A20(3289152032) - PFS (Y/N): N, DH group: none - - inbound esp sas: - spi: 0x2948B6CB(692631243) - transform: esp-256-aes esp-sha256-hmac , - in use settings ={Tunnel, } - conn id: 21, flow_id: SW:21, sibling_flags 80000040, crypto map: IPSEC-map - sa timing: remaining key lifetime (k/sec): (4194891/3581) - IV size: 16 bytes - replay detection support: Y - Status: ACTIVE(ACTIVE) - - inbound ah sas: - - inbound pcp sas: - - outbound esp sas: - spi: 0xC40C7A20(3289152032) - transform: esp-256-aes esp-sha256-hmac , - in use settings ={Tunnel, } - conn id: 22, flow_id: SW:22, sibling_flags 80000040, crypto map: IPSEC-map - sa timing: remaining key lifetime (k/sec): (4194891/3581) - IV size: 16 bytes - replay detection support: Y - Status: ACTIVE(ACTIVE) - - outbound ah sas: - - outbound pcp sas: -``` - - -### Checking Connectivity - -ICMP packets from PC1 to PC3. - -```none -PC1> ping 192.168.10.2 - -84 bytes from 192.168.10.2 icmp_seq=1 ttl=62 time=8.479 ms -84 bytes from 192.168.10.2 icmp_seq=2 ttl=62 time=3.344 ms -84 bytes from 192.168.10.2 icmp_seq=3 ttl=62 time=3.139 ms -84 bytes from 192.168.10.2 icmp_seq=4 ttl=62 time=3.176 ms -84 bytes from 192.168.10.2 icmp_seq=5 ttl=62 time=3.978 ms -``` - -ICMP packets from PC2 to PC4. - -```none -PC2> ping 192.168.11.2 - -84 bytes from 192.168.11.2 icmp_seq=1 ttl=62 time=9.687 ms -84 bytes from 192.168.11.2 icmp_seq=2 ttl=62 time=3.286 ms -84 bytes from 192.168.11.2 icmp_seq=3 ttl=62 time=2.972 ms -``` diff --git a/docs/configexamples/md-ipsec-cisco-route-based.md b/docs/configexamples/md-ipsec-cisco-route-based.md deleted file mode 100644 index 40a3985b..00000000 --- a/docs/configexamples/md-ipsec-cisco-route-based.md +++ /dev/null @@ -1,406 +0,0 @@ ---- -lastproofread: '2025-06-26' ---- - -(examples-ipsec-cisco-route-based)= - -# Route-based Site-to-Site VPN IPsec between VyOS and Cisco - -This document is to describe a basic setup using route-based -site-to-site VPN IPsec. In this example we use VyOS 1.5 and -Cisco IOS. Cisco initiates IPsec connection only if interesting -traffic present. For stable work we recommend configuring an -initiator role on VyOS side. OSPF is selected as routing protocol -inside the tunnel. - -## Network Topology - -```{eval-rst} -.. image:: /_static/images/cisco-vpn-ipsec.webp - :align: center - :alt: Network Topology Diagram -``` - - -## Prerequirements - -**VyOS:** - -```{eval-rst} -+---------+----------------+ -| WAN IP | 10.0.1.2/30 | -+---------+----------------+ -| LAN1 IP | 192.168.0.1/24 | -+---------+----------------+ -| LAN2 IP | 192.168.1.1/24 | -+---------+----------------+ -``` - -**Cisco:** - -```{eval-rst} -+---------+-----------------+ -| WAN IP | 10.0.2.2/30 | -+---------+-----------------+ -| LAN1 IP | 192.168.10.1/24 | -+---------+-----------------+ -| LAN2 IP | 192.168.11.1/24 | -+---------+-----------------+ -``` - -**IKE parameters:** - -```{eval-rst} -+-------------------+---------+ -| Encryption | AES-128 | -+-------------------+---------+ -| HASH | SHA-1 | -+-------------------+---------+ -| Diff-Helman Group | 14 | -+-------------------+---------+ -| Life-Time | 28800 | -+-------------------+---------+ -| IKE Version | 1 | -+-------------------+---------+ -``` - -**IPsec parameters:** - -```{eval-rst} -+------------+---------+ -| Encryption | AES-256 | -+------------+---------+ -| HASH | SHA-256 | -+------------+---------+ -| Life-Time | 3600 | -+------------+---------+ -| PFS | disable | -+------------+---------+ -``` - -**Hosts configuration** - -```{eval-rst} -+--------+--------------+ -| PC1 IP | 192.168.0.2 | -+--------+--------------+ -| PC2 IP | 192.168.1.2 | -+--------+--------------+ -| PC3 IP | 192.168.10.2 | -+--------+--------------+ -| PC4 IP | 192.168.11.2 | -+--------+--------------+ -``` - -## Configuration - -:::{note} -Pfs is disabled in Cisco by default. -::: - -### VyOS - -```none -set interfaces ethernet eth0 address '10.0.1.2/30' -set interfaces ethernet eth1 address '192.168.0.1/24' -set interfaces ethernet eth2 address '192.168.1.1/24' -set interfaces vti vti1 address '10.100.100.1/30' -set interfaces vti vti1 mtu '1438' -set protocols ospf area 0 network '10.100.100.0/30' -set protocols ospf area 0 network '192.168.0.0/24' -set protocols ospf area 0 network '192.168.1.0/24' -set protocols ospf interface eth1 passive -set protocols ospf interface eth2 passive -set protocols ospf interface vti1 network 'point-to-point' -set protocols ospf parameters router-id '2.2.2.2' -set protocols static route 0.0.0.0/0 next-hop 10.0.1.1 -set vpn ipsec authentication psk AUTH-PSK id '10.0.1.2' -set vpn ipsec authentication psk AUTH-PSK id '10.0.2.2' -set vpn ipsec authentication psk AUTH-PSK secret 'dGVzdA==' -set vpn ipsec authentication psk AUTH-PSK secret-type 'base64' -set vpn ipsec esp-group ESP-GROUP lifetime '3600' -set vpn ipsec esp-group ESP-GROUP pfs 'disable' -set vpn ipsec esp-group ESP-GROUP proposal 10 encryption 'aes256' -set vpn ipsec esp-group ESP-GROUP proposal 10 hash 'sha256' -set vpn ipsec ike-group IKE-GROUP close-action 'start' -set vpn ipsec ike-group IKE-GROUP dead-peer-detection action 'restart' -set vpn ipsec ike-group IKE-GROUP dead-peer-detection interval '10' -set vpn ipsec ike-group IKE-GROUP dead-peer-detection timeout '30' -set vpn ipsec ike-group IKE-GROUP key-exchange 'ikev1' -set vpn ipsec ike-group IKE-GROUP lifetime '28800' -set vpn ipsec ike-group IKE-GROUP proposal 10 dh-group '14' -set vpn ipsec ike-group IKE-GROUP proposal 10 encryption 'aes128' -set vpn ipsec ike-group IKE-GROUP proposal 10 hash 'sha1' -set vpn ipsec options disable-route-autoinstall -set vpn ipsec site-to-site peer CISCO authentication local-id '10.0.1.2' -set vpn ipsec site-to-site peer CISCO authentication mode 'pre-shared-secret' -set vpn ipsec site-to-site peer CISCO authentication remote-id '10.0.2.2' -set vpn ipsec site-to-site peer CISCO connection-type 'initiate' -set vpn ipsec site-to-site peer CISCO default-esp-group 'ESP-GROUP' -set vpn ipsec site-to-site peer CISCO ike-group 'IKE-GROUP' -set vpn ipsec site-to-site peer CISCO local-address '10.0.1.2' -set vpn ipsec site-to-site peer CISCO remote-address '10.0.2.2' -set vpn ipsec site-to-site peer CISCO vti bind 'vti1' -``` - - -### Cisco - -```none -crypto isakmp policy 10 - encr aes - authentication pre-share - group 14 - lifetime 28800 -crypto isakmp key test address 10.0.1.2 -! -! -crypto ipsec transform-set TS esp-aes 256 esp-sha256-hmac - mode transport -! -crypto ipsec profile IPsec-profile - set transform-set TS -! -! -! -! -! -! -! -interface Loopback0 - ip address 1.1.1.1 255.255.255.255 -! -interface Tunnel10 - ip address 10.100.100.2 255.255.255.252 - ip ospf network point-to-point - tunnel source GigabitEthernet0/0 - tunnel mode ipsec ipv4 - tunnel destination 10.0.1.2 - tunnel protection ipsec profile IPsec-profile -! -interface GigabitEthernet0/0 - ip address 10.0.2.2 255.255.255.252 - duplex auto - speed auto - media-type rj45 -! -interface GigabitEthernet0/1 - ip address 192.168.10.1 255.255.255.0 - duplex auto - speed auto - media-type rj45 -! -interface GigabitEthernet0/2 - ip address 192.168.11.1 255.255.255.0 - duplex auto - speed auto - media-type rj45 -! -router ospf 1 - router-id 1.1.1.1 - passive-interface GigabitEthernet0/1 - passive-interface GigabitEthernet0/2 - network 10.100.100.0 0.0.0.3 area 0 - network 192.168.10.0 0.0.0.255 area 0 - network 192.168.11.0 0.0.0.255 area 0 -! -ip route 0.0.0.0 0.0.0.0 10.0.2.1 -``` - - -## Monitoring - -### Monitoring on VyOS side - -IKE SAs: - -```none -vyos@vyos:~$ show vpn ike sa -Peer ID / IP Local ID / IP ------------- ------------- -10.0.2.2 10.0.2.2 10.0.1.2 10.0.1.2 - - State IKEVer Encrypt Hash D-H Group NAT-T A-Time L-Time - ----- ------ ------- ---- --------- ----- ------ ------ - up IKEv1 AES_CBC_128 HMAC_SHA1_96 MODP_2048 no 8175 18439 -``` - -IPsec SAs: - -```none -vyos@vyos:~$ show vpn ipsec sa -Connection State Uptime Bytes In/Out Packets In/Out Remote address Remote ID Proposal ------------- ------- -------- -------------- ---------------- ---------------- ----------- ----------------------------- -CISCO-vti up 34m59s 17K/14K 224/213 10.0.2.2 10.0.2.2 AES_CBC_256/HMAC_SHA2_256_128 -``` - -OSPF Neighbor Status: - -```none -vyos@vyos:~$ show ip ospf neighbor - -Neighbor ID Pri State Up Time Dead Time Address Interface RXmtL RqstL DBsmL -1.1.1.1 1 Full/- 1h29m37s 39.317s 10.100.100.2 vti1:10.100.100.1 0 0 0 -``` - -Routing Table: - -```none -vyos@vyos:~$ show ip route -Codes: K - kernel route, C - connected, L - local, 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, t - Table-Direct, - > - selected route, * - FIB route, q - queued, r - rejected, b - backup - t - trapped, o - offload failure -S>* 0.0.0.0/0 [1/0] via 10.0.1.1, eth0, weight 1, 00:07:54 -C>* 10.0.1.0/30 is directly connected, eth0, weight 1, 00:07:59 -L>* 10.0.1.2/32 is directly connected, eth0, weight 1, 00:07:59 -O 10.100.100.0/30 [110/1] is directly connected, vti1, weight 1, 00:07:50 -C>* 10.100.100.0/30 is directly connected, vti1, weight 1, 00:07:50 -L>* 10.100.100.1/32 is directly connected, vti1, weight 1, 00:07:50 -O 192.168.0.0/24 [110/1] is directly connected, eth1, weight 1, 00:07:54 -C>* 192.168.0.0/24 is directly connected, eth1, weight 1, 00:07:59 -L>* 192.168.0.1/32 is directly connected, eth1, weight 1, 00:07:59 -O 192.168.1.0/24 [110/1] is directly connected, eth2, weight 1, 00:07:54 -C>* 192.168.1.0/24 is directly connected, eth2, weight 1, 00:07:59 -L>* 192.168.1.1/32 is directly connected, eth2, weight 1, 00:07:59 -O>* 192.168.10.0/24 [110/2] via 10.100.100.2, vti1, weight 1, 00:07:34 -O>* 192.168.11.0/24 [110/2] via 10.100.100.2, vti1, weight 1, 00:07:34 -``` - - -### Monitoring on Cisco side - -IKE SAs: - -```none -Cisco#show crypto isakmp sa -IPv4 Crypto ISAKMP SA -dst src state conn-id status -10.0.1.2 10.0.2.2 QM_IDLE 1002 ACTIVE - -IPv6 Crypto ISAKMP SA -``` - -IPsec SAs: - -```none -Cisco#show crypto ipsec sa - -interface: Tunnel10 - Crypto map tag: Tunnel10-head-0, local addr 10.0.2.2 - - protected vrf: (none) - local ident (addr/mask/prot/port): (0.0.0.0/0.0.0.0/0/0) - remote ident (addr/mask/prot/port): (0.0.0.0/0.0.0.0/0/0) - current_peer 10.0.1.2 port 500 - PERMIT, flags={origin_is_acl,} - #pkts encaps: 1295, #pkts encrypt: 1295, #pkts digest: 1295 - #pkts decaps: 1238, #pkts decrypt: 1238, #pkts verify: 1238 - #pkts compressed: 0, #pkts decompressed: 0 - #pkts not compressed: 0, #pkts compr. failed: 0 - #pkts not decompressed: 0, #pkts decompress failed: 0 - #send errors 0, #recv errors 0 - - local crypto endpt.: 10.0.2.2, remote crypto endpt.: 10.0.1.2 - plaintext mtu 1438, path mtu 1500, ip mtu 1500, ip mtu idb GigabitEthernet0/0 - current outbound spi: 0xC3E9B307(3286872839) - PFS (Y/N): N, DH group: none - - inbound esp sas: - spi: 0x2740C328(658555688) - transform: esp-256-aes esp-sha256-hmac , - in use settings ={Tunnel, } - conn id: 7, flow_id: SW:7, sibling_flags 80000040, crypto map: Tunnel10-head-0 - sa timing: remaining key lifetime (k/sec): (4173824/1401) - IV size: 16 bytes - replay detection support: Y - Status: ACTIVE(ACTIVE) - - inbound ah sas: - - inbound pcp sas: - - outbound esp sas: - spi: 0xC3E9B307(3286872839) - transform: esp-256-aes esp-sha256-hmac , - in use settings ={Tunnel, } - conn id: 8, flow_id: SW:8, sibling_flags 80000040, crypto map: Tunnel10-head-0 - sa timing: remaining key lifetime (k/sec): (4173819/1401) - IV size: 16 bytes - replay detection support: Y - Status: ACTIVE(ACTIVE) - - outbound ah sas: - - outbound pcp sas: -``` - -OSPF Neighbor Status: - -```none -Cisco# show ip ospf neighbor - -Neighbor ID Pri State Dead Time Address Interface -2.2.2.2 0 FULL/ - 00:00:35 10.100.100.1 Tunnel10 -``` - -Routing Table: - -```none -Cisco#show ip route -Codes: L - local, C - connected, S - static, R - RIP, M - mobile, B - BGP - D - EIGRP, EX - EIGRP external, O - OSPF, IA - OSPF inter area - N1 - OSPF NSSA external type 1, N2 - OSPF NSSA external type 2 - E1 - OSPF external type 1, E2 - OSPF external type 2 - i - IS-IS, su - IS-IS summary, L1 - IS-IS level-1, L2 - IS-IS level-2 - ia - IS-IS inter area, * - candidate default, U - per-user static route - o - ODR, P - periodic downloaded static route, H - NHRP, l - LISP - a - application route - + - replicated route, % - next hop override, p - overrides from PfR - -Gateway of last resort is 10.0.2.1 to network 0.0.0.0 - -S* 0.0.0.0/0 [1/0] via 10.0.2.1 - 1.0.0.0/32 is subnetted, 1 subnets -C 1.1.1.1 is directly connected, Loopback0 - 10.0.0.0/8 is variably subnetted, 4 subnets, 2 masks -C 10.0.2.0/30 is directly connected, GigabitEthernet0/0 -L 10.0.2.2/32 is directly connected, GigabitEthernet0/0 -C 10.100.100.0/30 is directly connected, Tunnel10 -L 10.100.100.2/32 is directly connected, Tunnel10 -O 192.168.0.0/24 [110/1001] via 10.100.100.1, 00:09:36, Tunnel10 -O 192.168.1.0/24 [110/1001] via 10.100.100.1, 00:09:36, Tunnel10 - 192.168.10.0/24 is variably subnetted, 2 subnets, 2 masks -C 192.168.10.0/24 is directly connected, GigabitEthernet0/1 -L 192.168.10.1/32 is directly connected, GigabitEthernet0/1 - 192.168.11.0/24 is variably subnetted, 2 subnets, 2 masks -C 192.168.11.0/24 is directly connected, GigabitEthernet0/2 -L 192.168.11.1/32 is directly connected, GigabitEthernet0/2 -``` - - -### Checking Connectivity - -ICMP packets from PC1 to PC3. - -```none -PC1> ping 192.168.10.2 - -84 bytes from 192.168.10.2 icmp_seq=1 ttl=62 time=8.479 ms -84 bytes from 192.168.10.2 icmp_seq=2 ttl=62 time=3.344 ms -84 bytes from 192.168.10.2 icmp_seq=3 ttl=62 time=3.139 ms -84 bytes from 192.168.10.2 icmp_seq=4 ttl=62 time=3.176 ms -84 bytes from 192.168.10.2 icmp_seq=5 ttl=62 time=3.978 ms -``` - -ICMP packets from PC2 to PC4. - -```none -PC2> ping 192.168.11.2 - -84 bytes from 192.168.11.2 icmp_seq=1 ttl=62 time=9.687 ms -84 bytes from 192.168.11.2 icmp_seq=2 ttl=62 time=3.286 ms -84 bytes from 192.168.11.2 icmp_seq=3 ttl=62 time=2.972 ms -``` diff --git a/docs/configexamples/md-ipsec-pa-route-based.md b/docs/configexamples/md-ipsec-pa-route-based.md deleted file mode 100644 index c4a9e06c..00000000 --- a/docs/configexamples/md-ipsec-pa-route-based.md +++ /dev/null @@ -1,412 +0,0 @@ ---- -lastproofread: '2025-06-26' ---- - -(examples-ipsec-pa-route-based)= - -# Route-based Site-to-Site VPN IPsec between VyOS and Palo Alto - -This document is to describe a basic setup using route-based -site-to-site VPN IPsec. In this example we use VyOS 1.5 and -PA 11.0.0. OSPF is selected as routing protocol inside the -tunnel. - -Since this example focuses on IPsec configuration it does not -include firewall configuration. - -## Network Topology - -```{image} /_static/images/ipsec-vyos-pa.webp -:align: center -:alt: Network Topology Diagram -``` - - -## Prerequirements - -**VyOS:** - -```{eval-rst} -+---------+----------------+ -| WAN IP | 10.0.1.2/30 | -+---------+----------------+ -| LAN1 IP | 192.168.0.1/24 | -+---------+----------------+ -| LAN2 IP | 192.168.1.1/24 | -+---------+----------------+ -``` - -**Palo Alto:** - -```{eval-rst} -+---------+-----------------+ -| WAN IP | 10.0.2.2/30 | -+---------+-----------------+ -| LAN1 IP | 192.168.10.1/24 | -+---------+-----------------+ -| LAN2 IP | 192.168.11.1/24 | -+---------+-----------------+ -``` - -**IKE parameters:** - -```{eval-rst} -+-------------------+---------+ -| Encryption | AES-128 | -+-------------------+---------+ -| HASH | SHA-1 | -+-------------------+---------+ -| Diff-Helman Group | 14 | -+-------------------+---------+ -| Life-Time | 28800 | -+-------------------+---------+ -| IKE Version | 1 | -+-------------------+---------+ -``` - -**IPsec parameters:** - -```{eval-rst} -+------------+---------+ -| Encryption | AES-256 | -+------------+---------+ -| HASH | SHA-256 | -+------------+---------+ -| Life-Time | 3600 | -+------------+---------+ -| PFS | disable | -+------------+---------+ -``` - -**Hosts configuration** - -```{eval-rst} -+--------+--------------+ -| PC1 IP | 192.168.0.2 | -+--------+--------------+ -| PC2 IP | 192.168.1.2 | -+--------+--------------+ -| PC3 IP | 192.168.10.2 | -+--------+--------------+ -| PC4 IP | 192.168.11.2 | -+--------+--------------+ -``` - -## Configuration - -### VyOS - -```none -set interfaces ethernet eth0 address '10.0.1.2/30' -set interfaces ethernet eth1 address '192.168.0.1/24' -set interfaces ethernet eth2 address '192.168.1.1/24' -set interfaces vti vti1 address '10.100.100.1/30' -set interfaces vti vti1 mtu '1438' -set protocols ospf area 0 network '10.100.100.0/30' -set protocols ospf area 0 network '192.168.0.0/24' -set protocols ospf area 0 network '192.168.1.0/24' -set protocols ospf interface eth1 passive -set protocols ospf interface eth2 passive -set protocols ospf interface vti1 network 'point-to-point' -set protocols ospf parameters router-id '2.2.2.2' -set protocols static route 0.0.0.0/0 next-hop 10.0.1.1 -set vpn ipsec authentication psk AUTH-PSK id '10.0.1.2' -set vpn ipsec authentication psk AUTH-PSK id '10.0.2.2' -set vpn ipsec authentication psk AUTH-PSK secret 'dGVzdA==' -set vpn ipsec authentication psk AUTH-PSK secret-type 'base64' -set vpn ipsec esp-group ESP-GROUP lifetime '3600' -set vpn ipsec esp-group ESP-GROUP pfs 'disable' -set vpn ipsec esp-group ESP-GROUP proposal 10 encryption 'aes256' -set vpn ipsec esp-group ESP-GROUP proposal 10 hash 'sha256' -set vpn ipsec ike-group IKE-GROUP close-action 'start' -set vpn ipsec ike-group IKE-GROUP dead-peer-detection action 'restart' -set vpn ipsec ike-group IKE-GROUP dead-peer-detection interval '10' -set vpn ipsec ike-group IKE-GROUP dead-peer-detection timeout '30' -set vpn ipsec ike-group IKE-GROUP key-exchange 'ikev1' -set vpn ipsec ike-group IKE-GROUP lifetime '28800' -set vpn ipsec ike-group IKE-GROUP proposal 10 dh-group '14' -set vpn ipsec ike-group IKE-GROUP proposal 10 encryption 'aes128' -set vpn ipsec ike-group IKE-GROUP proposal 10 hash 'sha1' -set vpn ipsec options disable-route-autoinstall -set vpn ipsec site-to-site peer PA authentication local-id '10.0.1.2' -set vpn ipsec site-to-site peer PA authentication mode 'pre-shared-secret' -set vpn ipsec site-to-site peer PA authentication remote-id '10.0.2.2' -set vpn ipsec site-to-site peer PA connection-type 'initiate' -set vpn ipsec site-to-site peer PA default-esp-group 'ESP-GROUP' -set vpn ipsec site-to-site peer PA ike-group 'IKE-GROUP' -set vpn ipsec site-to-site peer PA local-address '10.0.1.2' -set vpn ipsec site-to-site peer PA remote-address '10.0.2.2' -set vpn ipsec site-to-site peer PA vti bind 'vti1' -``` - - -### Palo Alto - -```{eval-rst} -GUI Configuration: - Network -> Network Profiles -> IKE Crypto - - .. image:: /_static/images/PA-IKE-group.webp - :align: center - - Network -> Network Profiles -> IKE Gateways - - .. image:: /_static/images/PA-IKE-GW-1.webp - :align: center - - .. image:: /_static/images/PA-IKE-GW-2.webp - :align: center - - Network -> Network Profiles -> IPSec Crypto - - .. image:: /_static/images/PA-ESP-group.webp - :align: center - - Network -> Interfaces - - .. image:: /_static/images/PA-tunnel-1.webp - :align: center - - .. image:: /_static/images/PA-tunnel-2.webp - :align: center - - .. image:: /_static/images/PA-tunnel-3.webp - :align: center - - Network -> IPSec Tunnels - - .. image:: /_static/images/PA-IPsec-tunnel.webp - :align: center -``` -CLI configuration with OSPF: -```none -set network interface ethernet ethernet1/1 layer3 ip 10.0.2.2/30 -set network interface ethernet ethernet1/1 layer3 interface-management-profile Allow -set network interface ethernet ethernet1/2 layer3 ip 192.168.10.1/24 -set network interface ethernet ethernet1/1 layer3 interface-management-profile Allow -set network interface ethernet ethernet1/3 layer3 ip 192.168.11.1/24 -set network interface ethernet ethernet1/1 layer3 interface-management-profile Allow -set network interface tunnel units tunnel.1 ip 10.100.100.2/30 -set network interface tunnel units tunnel.1 interface-management-profile Allow -set network interface tunnel units tunnel.1 mtu 1438 -set network profiles interface-management-profile Allow ping yes -set network ike crypto-profiles ike-crypto-profiles IKE-GROUP hash sha1 -set network ike crypto-profiles ike-crypto-profiles IKE-GROUP dh-group group14 -set network ike crypto-profiles ike-crypto-profiles IKE-GROUP encryption aes-128-cbc -set network ike crypto-profiles ike-crypto-profiles IKE-GROUP lifetime seconds 28800 -set network ike crypto-profiles ipsec-crypto-profiles ESP-GROUP esp authentication sha256 -set network ike crypto-profiles ipsec-crypto-profiles ESP-GROUP esp encryption aes-256-cbc -set network ike crypto-profiles ipsec-crypto-profiles ESP-GROUP lifetime seconds 3600 -set network ike crypto-profiles ipsec-crypto-profiles ESP-GROUP dh-group no-pfs -set network ike gateway VyOS authentication pre-shared-key key test -set network ike gateway VyOS protocol ikev1 dpd enable yes -set network ike gateway VyOS protocol ikev1 exchange-mode main -set network ike gateway VyOS protocol ikev1 ike-crypto-profile IKE-GROUP -set network ike gateway VyOS protocol ikev2 dpd enable yes -set network ike gateway VyOS protocol version ikev1 -set network ike gateway VyOS protocol-common nat-traversal enable yes -set network ike gateway VyOS protocol-common fragmentation enable no -set network ike gateway VyOS protocol-common passive-mode yes -set network ike gateway VyOS local-address interface ethernet1/1 -set network ike gateway VyOS peer-address ip 10.0.1.2 -set network ike gateway VyOS local-id id 10.0.2.2 -set network ike gateway VyOS local-id type ipaddr -set network ike gateway VyOS peer-id id 10.0.1.2 -set network ike gateway VyOS peer-id type ipaddr -set network tunnel ipsec VyOS-tunnel auto-key ike-gateway VyOS -set network tunnel ipsec VyOS-tunnel auto-key ipsec-crypto-profile ESP-GROUP -set network tunnel ipsec VyOS-tunnel tunnel-monitor enable no -set network tunnel ipsec VyOS-tunnel tunnel-interface tunnel.1 -set network tunnel ipsec VyOS-tunnel anti-replay no -set network virtual-router default protocol ospf enable yes -set network virtual-router default protocol ospf area 0.0.0.0 type normal -set network virtual-router default protocol ospf area 0.0.0.0 interface tunnel.1 enable yes -set network virtual-router default protocol ospf area 0.0.0.0 interface tunnel.1 passive no -set network virtual-router default protocol ospf area 0.0.0.0 interface tunnel.1 link-type p2p -set network virtual-router default protocol ospf area 0.0.0.0 interface ethernet1/2 enable yes -set network virtual-router default protocol ospf area 0.0.0.0 interface ethernet1/2 passive yes -set network virtual-router default protocol ospf area 0.0.0.0 interface ethernet1/2 link-type broadcast -set network virtual-router default protocol ospf area 0.0.0.0 interface ethernet1/3 enable yes -set network virtual-router default protocol ospf area 0.0.0.0 interface ethernet1/3 passive yes -set network virtual-router default protocol ospf area 0.0.0.0 interface ethernet1/3 link-type broadcast -set network virtual-router default protocol ospf router-id 1.1.1.1 -set network virtual-router default interface [ ethernet1/1 ethernet1/2 ethernet1/3 tunnel.1 ] -``` - -## Monitoring -### Monitoring on VyOS side - -IKE SAs: - -```none -vyos@vyos:~$ show vpn ike sa -Peer ID / IP Local ID / IP ------------- ------------- -10.0.2.2 10.0.2.2 10.0.1.2 10.0.1.2 - - State IKEVer Encrypt Hash D-H Group NAT-T A-Time L-Time - ----- ------ ------- ---- --------- ----- ------ ------ - up IKEv1 AES_CBC_128 HMAC_SHA1_96 MODP_2048 no 1372 25802 -``` - -IPsec SAs: - -```none -vyos@vyos:~$ show vpn ipsec sa -Connection State Uptime Bytes In/Out Packets In/Out Remote address Remote ID Proposal ------------- ------- -------- -------------- ---------------- ---------------- ----------- ----------------------------- -PA-vti up 23m27s 9K/10K 149/151 10.0.2.2 10.0.2.2 AES_CBC_256/HMAC_SHA2_256_128 -``` - -OSPF Neighbor Status: - -```none -vyos@vyos:~$ show ip ospf neighbor - -Neighbor ID Pri State Up Time Dead Time Address Interface RXmtL RqstL DBsmL -1.1.1.1 1 Full/- 23m56s 37.948s 10.100.100.2 vti1:10.100.100.1 0 0 0 -``` - -Routing Table: - -```none -vyos@vyos:~$ show ip route -Codes: K - kernel route, C - connected, L - local, 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, t - Table-Direct, - > - selected route, * - FIB route, q - queued, r - rejected, b - backup - t - trapped, o - offload failure - -S>* 0.0.0.0/0 [1/0] via 10.0.1.1, eth0, weight 1, 00:27:30 -C>* 10.0.1.0/30 is directly connected, eth0, weight 1, 00:27:34 -L>* 10.0.1.2/32 is directly connected, eth0, weight 1, 00:27:34 -O 10.100.100.0/30 [110/1] is directly connected, vti1, weight 1, 00:24:34 -C>* 10.100.100.0/30 is directly connected, vti1, weight 1, 00:24:34 -L>* 10.100.100.1/32 is directly connected, vti1, weight 1, 00:24:34 -O 192.168.0.0/24 [110/1] is directly connected, eth1, weight 1, 00:27:29 -C>* 192.168.0.0/24 is directly connected, eth1, weight 1, 00:27:34 -L>* 192.168.0.1/32 is directly connected, eth1, weight 1, 00:27:34 -O 192.168.1.0/24 [110/1] is directly connected, eth2, weight 1, 00:27:29 -C>* 192.168.1.0/24 is directly connected, eth2, weight 1, 00:27:34 -L>* 192.168.1.1/32 is directly connected, eth2, weight 1, 00:27:34 -O>* 192.168.10.0/24 [110/11] via 10.100.100.2, vti1, weight 1, 00:24:19 -O>* 192.168.11.0/24 [110/11] via 10.100.100.2, vti1, weight 1, 00:24:19 -``` - -### Monitoring on Palo Alto side - -IKE SAs: - -```none -admin@PA-VM> show vpn ike-sa - -IKEv1 phase-1 SAs -GwID/client IP Peer-Address Gateway Name Role Mode Algorithm Established Expiration V ST Xt Phase2 --------------- ------------ ------------ ---- ---- --------- ----------- ---------- - -- -- ------ -1 10.0.1.2 VyOS Resp Main PSK/DH14/A128/SHA1 Jul.31 01:35:00 Jul.31 09:35:00 v1 13 1 1 - -Show IKEv1 IKE SA: Total 1 gateways found. 1 ike sa found. - - -IKEv1 phase-2 SAs -Gateway Name TnID Tunnel GwID/IP Role Algorithm SPI(in) SPI(out) MsgID ST Xt ------------- ---- ------ ------- ---- --------- ------- -------- ----- -- -- -VyOS 1 VyOS-tunnel 1 Resp ESP/ /tunl/SHA2 8827A3D9 C204F4FA BD202829 9 1 - -Show IKEv1 phase2 SA: Total 1 gateways found. 1 ike sa found. - - -There is no IKEv2 SA found. -``` - -IPsec SAs: - -```none -admin@PA-VM> show vpn ipsec-sa - -GwID/client IP TnID Peer-Address Tunnel(Gateway) Algorithm SPI(in) SPI(out) life(Sec/KB) remain-time(Sec) --------------- ---- ------------ --------------- --------- ------- -------- ------------ ---------------- -1 1 10.0.1.2 VyOS-tunnel(VyOS) ESP/A256/SHA256 8827A3D9 C204F4FA 3600/Unlimited 2733 - -Show IPSec SA: Total 1 tunnels found. 1 ipsec sa found. -``` - -OSPF Neighbor Status: - -```none -admin@PA-VM> show routing protocol ospf neighbor - - Options: 0x80:reserved, O:Opaq-LSA capability, DC:demand circuits, EA:Ext-Attr LSA capability, - N/P:NSSA option, MC:multicase, E:AS external LSA capability, T:TOS capability - ========== - virtual router: default - neighbor address: 10.100.100.1 - local address binding: 0.0.0.0 - type: dynamic - status: full - neighbor router ID: 2.2.2.2 - area id: 0.0.0.0 - neighbor priority: 1 - lifetime remain: 32 - messages pending: 0 - LSA request pending: 0 - options: 0x02: E - hello suppressed: no - restart helper status: not helping - restart helper time remaining: 0 - restart helper exit reason: none -``` - -Routing Table: - -```none -admin@PA-VM> show routing route - -flags: A:active, ?:loose, C:connect, H:host, S:static, ~:internal, R:rip, O:ospf, B:bgp, - Oi:ospf intra-area, Oo:ospf inter-area, O1:ospf ext-type-1, O2:ospf ext-type-2, E:ecmp, M:multicast - - -VIRTUAL ROUTER: default (id 1) - ========== -destination nexthop metric flags age interface next-AS -0.0.0.0/0 10.0.2.1 10 A S ethernet1/1 -10.0.2.0/30 10.0.2.2 0 A C ethernet1/1 -10.0.2.2/32 0.0.0.0 0 A H -10.100.100.0/30 0.0.0.0 10 Oi 1273 tunnel.1 -10.100.100.0/30 10.100.100.2 0 A C tunnel.1 -10.100.100.2/32 0.0.0.0 0 A H -192.168.0.0/24 10.100.100.1 11 A Oi 1253 tunnel.1 -192.168.1.0/24 10.100.100.1 11 A Oi 1253 tunnel.1 -192.168.10.0/24 0.0.0.0 10 Oi 1273 ethernet1/2 -192.168.10.0/24 192.168.10.1 0 A C ethernet1/2 -192.168.10.1/32 0.0.0.0 0 A H -192.168.11.0/24 0.0.0.0 10 Oi 1273 ethernet1/3 -192.168.11.0/24 192.168.11.1 0 A C ethernet1/3 -192.168.11.1/32 0.0.0.0 0 A H -total routes shown: 14 -``` - -### Checking Connectivity - -ICMP packets from PC1 to PC3. - -```none -PC1> ping 192.168.10.2 - -84 bytes from 192.168.10.2 icmp_seq=1 ttl=62 time=8.479 ms -84 bytes from 192.168.10.2 icmp_seq=2 ttl=62 time=3.344 ms -84 bytes from 192.168.10.2 icmp_seq=3 ttl=62 time=3.139 ms -84 bytes from 192.168.10.2 icmp_seq=4 ttl=62 time=3.176 ms -84 bytes from 192.168.10.2 icmp_seq=5 ttl=62 time=3.978 ms -``` - -ICMP packets from PC2 to PC4. - -```none -PC2> ping 192.168.11.2 - -84 bytes from 192.168.11.2 icmp_seq=1 ttl=62 time=9.687 ms -84 bytes from 192.168.11.2 icmp_seq=2 ttl=62 time=3.286 ms -84 bytes from 192.168.11.2 icmp_seq=3 ttl=62 time=2.972 ms -``` diff --git a/docs/configexamples/md-l3vpn-hub-and-spoke.md b/docs/configexamples/md-l3vpn-hub-and-spoke.md deleted file mode 100644 index 3c719926..00000000 --- a/docs/configexamples/md-l3vpn-hub-and-spoke.md +++ /dev/null @@ -1,1091 +0,0 @@ -# L3VPN for Hub-and-Spoke connectivity with VyOS - -IP/MPLS technology is widely used by various service providers and large -enterprises in order to achieve better network scalability, manageability -and flexibility. It also provides the possibility to deliver different -services for the customers in a seamless manner. -Layer 3 VPN (L3VPN) is a type of VPN mode that is built and delivered -through OSI layer 3 networking technologies. Often the border gateway -protocol (BGP) is used to send and receive VPN-related data that is -responsible for the control plane. L3VPN utilizes virtual routing and -forwarding (VRF) techniques to receive and deliver user data as well as -separate data planes of the end-users. It is built using a combination of -IP- and MPLS-based information. Generally, L3VPNs are used to send data -on back-end VPN infrastructures, such as for VPN connections between data -centres, HQs and branches. - -An L3VPN consists of multiple access links, multiple VPN routing and -forwarding (VRF) tables, and multiple MPLS paths or multiple P2MP LSPs. -An L3VPN can be configured to connect two or more customer sites. -In hub-and-spoke MPLS L3VPN environments, the spoke routers need to have -unique Route Distinguishers (RDs). In order to use the hub site as a -transit point for connectivity in such an environment, the spoke sites -export their routes to the hub. Spokes can talk to hubs, but never have -direct paths to other spokes. All traffic between spokes is controlled -and delivered over the hub site. - -To deploy a Layer3 VPN with MPLS on VyOS, we should meet a couple -requirements in order to properly implement the solution. -We'll use the following nodes in our LAB environment: - -- 2 x Route reflectors (VyOS-RRx) -- 4 x Provider routers (VyOS-Px) -- 3 x Provider Edge (VyOs-PEx) -- 3 x Customer Edge (VyOS-CEx) - -The following software was used in the creation of this document: - -- Operating system: VyOS -- Version: 1.4-rolling-202110310317 -- Image name: vyos-1.4-rolling-202110310317-amd64.iso - -**NOTE:** VyOS Router (tested with VyOS 1.4-rolling-202110310317) -– The configurations below are specifically for VyOS 1.4.x. - -General information can be found in the -{ref}`configuration/vrf/index:L3VPN VRFs` chapter. - -## Topology - -```{image} /_static/images/L3VPN_hub_and_spoke.webp -:align: center -:alt: Network Topology Diagram -:width: 80% -``` - - -## How does it work? - -As we know the main assumption of L3VPN “Hub and Spoke” is, that the -traffic between spokes have to pass via hub, in our scenario VyOS-PE2 -is the Hub PE -and the VyOS-CE1-HUB is the central customer office device that is responsible -for controlling access between all spokes and announcing its network prefixes -(10.0.0.100/32). VyOS-PE2 has the main VRF (its name is BLUE_HUB), its -own Route-Distinguisher(RD) and route-target import/export lists. -Multiprotocol-BGP(MP-BGP) delivers L3VPN related control-plane information to -the nodes across network where PEs Spokes import the route-target 60535:1030 -(this is export route-target of vrf BLUE_HUB) and export its own route-target -60535:1011(this is vrf BLUE_SPOKE export route-target). Therefore, the -Customer edge nodes can only learn the network prefixes of the HUB site -[10.0.0.100/32]. For this example VyOS-CE1 has network prefixes -[10.0.0.80/32] / VyOS-CE2 has network prefixes [10.0.0.90/32]. -Route-Reflector devices VyOS-RR1 and VyOS-RR2 are used to simplify network -routes exchange and minimize iBGP peerings between devices. - -L3VPN configuration parameters table: - -```{eval-rst} -+----------+-------+------------+-----------------+-------------+-------------+ -| Node | Role | VRF | RD | RT import | RT export | -+----------+-------+------------+-----------------+-------------+-------------+ -| VyOS-PE2 | Hub | BLUE_HUB | 10.80.80.1:1011 | 65035:1011 | 65035:1030 | -| | | | | 65035:1030 | | -+----------+-------+------------+-----------------+-------------+-------------+ -| VyOS-PE1 | Spoke | BLUE_SPOKE | 10.50.50.1:1011 | 65035:1030 | 65035:1011 | -+----------+-------+------------+-----------------+-------------+-------------+ -| VyOS-PE3 | Spoke | BLUE_SPOKE | 10.60.60.1:1011 | 65035:1030 | 65035:1011 | -+----------+-------+------------+-----------------+-------------+-------------+ -``` - -## Configuration - -### Step-1: Configuring IGP and enabling MPLS LDP - -At the first step we need to configure the IP/MPLS backbone network using OSPF -as IGP protocol and LDP as label-switching protocol for the base connectivity -between **P** (rovider), **P** (rovider) **E** (dge) and **R** (oute) **R** -(eflector) nodes: -- VyOS-P1: - -```none -# interfaces -set interfaces dummy dum10 address '10.0.0.3/32' -set interfaces ethernet eth0 address '172.16.30.1/24' -set interfaces ethernet eth1 address '172.16.40.1/24' -set interfaces ethernet eth2 address '172.16.90.1/24' -set interfaces ethernet eth3 address '172.16.10.1/24' -set interfaces ethernet eth5 address '172.16.100.1/24' - -# protocols ospf+ldp -set protocols mpls interface 'eth1' -set protocols mpls interface 'eth2' -set protocols mpls interface 'eth3' -set protocols mpls interface 'eth5' -set protocols mpls interface 'eth0' -set protocols mpls ldp discovery transport-ipv4-address '10.0.0.3' -set protocols mpls ldp interface 'eth0' -set protocols mpls ldp interface 'eth1' -set protocols mpls ldp interface 'eth2' -set protocols mpls ldp interface 'eth3' -set protocols mpls ldp interface 'eth5' -set protocols mpls ldp router-id '10.0.0.3' -set protocols ospf area 0 network '0.0.0.0/0' -set protocols ospf parameters abr-type 'cisco' -set protocols ospf parameters router-id '10.0.0.3' -``` - -- VyOS-P2: - -```none -# interfaces -set interfaces dummy dum10 address '10.0.0.4/32' -set interfaces ethernet eth0 address '172.16.30.2/24' -set interfaces ethernet eth1 address '172.16.20.1/24' -set interfaces ethernet eth2 address '172.16.120.1/24' -set interfaces ethernet eth3 address '172.16.60.1/24' - -# protocols ospf+ldp -set protocols mpls interface 'eth1' -set protocols mpls interface 'eth2' -set protocols mpls interface 'eth3' -set protocols mpls interface 'eth0' -set protocols mpls ldp discovery transport-ipv4-address '10.0.0.4' -set protocols mpls ldp interface 'eth0' -set protocols mpls ldp interface 'eth1' -set protocols mpls ldp interface 'eth2' -set protocols mpls ldp interface 'eth3' -set protocols mpls ldp router-id '10.0.0.4' -set protocols ospf area 0 network '0.0.0.0/0' -set protocols ospf parameters abr-type 'cisco' -set protocols ospf parameters router-id '10.0.0.4' -``` - -- VyOS-P3: - -```none -# interfaces -set interfaces dummy dum10 address '10.0.0.5/32' -set interfaces ethernet eth0 address '172.16.110.1/24' -set interfaces ethernet eth1 address '172.16.40.2/24' -set interfaces ethernet eth2 address '172.16.50.1/24' -set interfaces ethernet eth3 address '172.16.70.1/24' - -# protocols ospf + ldp -set protocols mpls interface 'eth1' -set protocols mpls interface 'eth2' -set protocols mpls interface 'eth3' -set protocols mpls interface 'eth0' -set protocols mpls ldp discovery transport-ipv4-address '10.0.0.5' -set protocols mpls ldp interface 'eth0' -set protocols mpls ldp interface 'eth1' -set protocols mpls ldp interface 'eth2' -set protocols mpls ldp interface 'eth3' -set protocols mpls ldp router-id '10.0.0.5' -set protocols ospf area 0 network '0.0.0.0/0' -set protocols ospf parameters abr-type 'cisco' -set protocols ospf parameters router-id '10.0.0.5' -``` - -- VyOS-P4: - -```none -# interfaces -set interfaces dummy dum10 address '10.0.0.6/32' -set interfaces ethernet eth0 address '172.16.80.2/24' -set interfaces ethernet eth1 address '172.16.130.1/24' -set interfaces ethernet eth2 address '172.16.50.2/24' -set interfaces ethernet eth3 address '172.16.60.2/24' -set interfaces ethernet eth5 address '172.16.140.1/24' - - -# protocols ospf + ldp -set protocols mpls interface 'eth1' -set protocols mpls interface 'eth2' -set protocols mpls interface 'eth3' -set protocols mpls interface 'eth0' -set protocols mpls interface 'eth5' -set protocols mpls ldp discovery transport-ipv4-address '10.0.0.6' -set protocols mpls ldp interface 'eth0' -set protocols mpls ldp interface 'eth1' -set protocols mpls ldp interface 'eth2' -set protocols mpls ldp interface 'eth3' -set protocols mpls ldp interface 'eth5' -set protocols mpls ldp router-id '10.0.0.6' -set protocols ospf area 0 network '0.0.0.0/0' -set protocols ospf parameters abr-type 'cisco' -set protocols ospf parameters router-id '10.0.0.6' -``` - -- VyOS-PE1: - -```none -# interfaces -set interfaces dummy dum10 address '10.0.0.7/32' -set interfaces ethernet eth0 address '172.16.90.2/24' - -# protocols ospf + ldp -set protocols mpls interface 'eth0' -set protocols mpls ldp discovery transport-ipv4-address '10.0.0.7' -set protocols mpls ldp interface 'eth0' -set protocols mpls ldp router-id '10.0.0.7' -set protocols ospf area 0 network '0.0.0.0/0' -set protocols ospf parameters abr-type 'cisco' -set protocols ospf parameters router-id '10.0.0.7' -``` - -- VyOS-PE2: - -```none -# interfaces -set interfaces dummy dum10 address '10.0.0.8/32' -set interfaces ethernet eth0 address '172.16.110.2/24' -set interfaces ethernet eth1 address '172.16.100.2/24' -set interfaces ethernet eth2 address '172.16.80.1/24' - -# protocols ospf + ldp -set protocols mpls interface 'eth0' -set protocols mpls interface 'eth1' -set protocols mpls ldp discovery transport-ipv4-address '10.0.0.8' -set protocols mpls ldp interface 'eth0' -set protocols mpls ldp interface 'eth1' -set protocols mpls ldp router-id '10.0.0.8' -set protocols ospf area 0 network '0.0.0.0/0' -set protocols ospf parameters abr-type 'cisco' -set protocols ospf parameters router-id '10.0.0.8' -``` - -- VyOS-PE3: - -```none -# interfaces -set interfaces dummy dum10 address '10.0.0.10/32' -set interfaces ethernet eth0 address '172.16.140.2/24' - -# protocols ospf + ldp -set protocols mpls interface 'eth0' -set protocols mpls ldp discovery transport-ipv4-address '10.0.0.10' -set protocols mpls ldp interface 'eth0' -set protocols mpls ldp router-id '10.0.0.10' -set protocols ospf area 0 network '0.0.0.0/0' -set protocols ospf parameters abr-type 'cisco' -set protocols ospf parameters router-id '10.0.0.10' -``` - -- VyOS-RR1: - -```none -# interfaces -set interfaces ethernet eth1 address '172.16.20.2/24' -set interfaces ethernet eth2 address '172.16.10.2/24' -set interfaces dummy dum10 address '10.0.0.1/32' - -# protocols ospf + ldp -set protocols mpls interface 'eth1' -set protocols mpls interface 'eth2' -set protocols mpls ldp discovery transport-ipv4-address '10.0.0.1' -set protocols mpls ldp interface 'eth1' -set protocols mpls ldp interface 'eth2' -set protocols mpls ldp router-id '10.0.0.1' -set protocols ospf area 0 network '0.0.0.0/0' -set protocols ospf parameters abr-type 'cisco' -set protocols ospf parameters router-id '10.0.0.1' -``` - -- VyOS-RR2: - -```none -# interfaces -set interfaces ethernet eth0 address '172.16.80.1/24' -set interfaces ethernet eth1 address '172.16.70.2/24' -set interfaces dummy dum10 address '10.0.0.2/32' - -# protocols ospf + ldp -set protocols mpls interface 'eth0' -set protocols mpls interface 'eth1' -set protocols mpls ldp discovery transport-ipv4-address '10.0.0.2' -set protocols mpls ldp interface 'eth1' -set protocols mpls ldp interface 'eth0' -set protocols mpls ldp router-id '10.0.0.2' -set protocols ospf area 0 network '0.0.0.0/0' -set protocols ospf parameters abr-type 'cisco' -set protocols ospf parameters router-id '10.0.0.2' -``` - - -### Step-2: Configuring iBGP for L3VPN control-plane - -At this step we are going to enable iBGP protocol on MPLS nodes and -Route Reflectors (two routers for redundancy) that will deliver IPv4 -VPN (L3VPN) routes between them: -- VyOS-RR1: - -```none -set protocols bgp system-as '65001' -set protocols bgp neighbor 10.0.0.7 address-family ipv4-vpn route-reflector-client -set protocols bgp neighbor 10.0.0.7 peer-group 'RR_VPNv4' -set protocols bgp neighbor 10.0.0.8 address-family ipv4-vpn route-reflector-client -set protocols bgp neighbor 10.0.0.8 peer-group 'RR_VPNv4' -set protocols bgp neighbor 10.0.0.10 address-family ipv4-vpn route-reflector-client -set protocols bgp neighbor 10.0.0.10 peer-group 'RR_VPNv4' -set protocols bgp parameters cluster-id '10.0.0.1' -set protocols bgp parameters log-neighbor-changes -set protocols bgp parameters router-id '10.0.0.1' -set protocols bgp peer-group RR_VPNv4 remote-as '65001' -set protocols bgp peer-group RR_VPNv4 update-source 'dum10' -``` - -- VyOS-RR2: - -```none -set protocols bgp system-as '65001' -set protocols bgp neighbor 10.0.0.7 address-family ipv4-vpn route-reflector-client -set protocols bgp neighbor 10.0.0.7 peer-group 'RR_VPNv4' -set protocols bgp neighbor 10.0.0.8 address-family ipv4-vpn route-reflector-client -set protocols bgp neighbor 10.0.0.8 peer-group 'RR_VPNv4' -set protocols bgp neighbor 10.0.0.10 address-family ipv4-vpn route-reflector-client -set protocols bgp neighbor 10.0.0.10 peer-group 'RR_VPNv4' -set protocols bgp parameters cluster-id '10.0.0.1' -set protocols bgp parameters log-neighbor-changes -set protocols bgp parameters router-id '10.0.0.2' -set protocols bgp peer-group RR_VPNv4 remote-as '65001' -set protocols bgp peer-group RR_VPNv4 update-source 'dum10' -``` - -- VyOS-PE1: - -```none -set protocols bgp system-as '65001' -set protocols bgp neighbor 10.0.0.1 address-family ipv4-vpn nexthop-self -set protocols bgp neighbor 10.0.0.1 peer-group 'RR_VPNv4' -set protocols bgp neighbor 10.0.0.2 address-family ipv4-vpn nexthop-self -set protocols bgp neighbor 10.0.0.2 peer-group 'RR_VPNv4' -set protocols bgp parameters log-neighbor-changes -set protocols bgp parameters router-id '10.0.0.7' -set protocols bgp peer-group RR_VPNv4 remote-as '65001' -set protocols bgp peer-group RR_VPNv4 update-source 'dum10' -``` - -- VyOS-PE2: - -```none -set protocols bgp system-as '65001' -set protocols bgp neighbor 10.0.0.1 address-family ipv4-vpn nexthop-self -set protocols bgp neighbor 10.0.0.1 peer-group 'RR_VPNv4' -set protocols bgp neighbor 10.0.0.2 address-family ipv4-vpn nexthop-self -set protocols bgp neighbor 10.0.0.2 peer-group 'RR_VPNv4' -set protocols bgp parameters log-neighbor-changes -set protocols bgp parameters router-id '10.0.0.8' -set protocols bgp peer-group RR_VPNv4 remote-as '65001' -set protocols bgp peer-group RR_VPNv4 update-source 'dum10' -``` - -- VyOS-PE3: - -```none -set protocols bgp system-as '65001' -set protocols bgp neighbor 10.0.0.1 address-family ipv4-vpn nexthop-self -set protocols bgp neighbor 10.0.0.1 peer-group 'RR_VPNv4' -set protocols bgp neighbor 10.0.0.2 address-family ipv4-vpn nexthop-self -set protocols bgp neighbor 10.0.0.2 peer-group 'RR_VPNv4' -set protocols bgp parameters log-neighbor-changes -set protocols bgp parameters router-id '10.0.0.10' -set protocols bgp peer-group RR_VPNv4 remote-as '65001' -set protocols bgp peer-group RR_VPNv4 update-source 'dum10' -``` - - -### Step-3: Configuring L3VPN VRFs on PE nodes - -This section provides configuration steps for setting up VRFs on our -PE nodes including CE facing interfaces, BGP, rd and route-target -import/export based on the pre-defined parameters. -- VyOS-PE1: - -```none -# VRF settings -set vrf name BLUE_SPOKE table '200' -set vrf name BLUE_SPOKE protocols bgp address-family ipv4-unicast export vpn -set vrf name BLUE_SPOKE protocols bgp address-family ipv4-unicast import vpn -set vrf name BLUE_SPOKE protocols bgp address-family ipv4-unicast label vpn export 'auto' -set vrf name BLUE_SPOKE protocols bgp address-family ipv4-unicast network 10.50.50.0/24 -set vrf name BLUE_SPOKE protocols bgp address-family ipv4-unicast rd vpn export '10.50.50.1:1011' -set vrf name BLUE_SPOKE protocols bgp address-family ipv4-unicast redistribute connected -set vrf name BLUE_SPOKE protocols bgp address-family ipv4-unicast route-target vpn export '65035:1011' -set vrf name BLUE_SPOKE protocols bgp address-family ipv4-unicast route-target vpn import '65035:1030' -set vrf name BLUE_SPOKE protocols bgp neighbor 10.50.50.2 address-family ipv4-unicast as-override -set vrf name BLUE_SPOKE protocols bgp neighbor 10.50.50.2 remote-as '65035' - -# interfaces -set interfaces ethernet eth3 address '10.50.50.1/24' -set interfaces ethernet eth3 vrf 'BLUE_SPOKE' -``` - -- VyOS-PE2: - -```none -# VRF settings -set vrf name BLUE_HUB table '400' -set vrf name BLUE_HUB protocols bgp address-family ipv4-unicast export vpn -set vrf name BLUE_HUB protocols bgp address-family ipv4-unicast import vpn -set vrf name BLUE_HUB protocols bgp address-family ipv4-unicast label vpn export 'auto' -set vrf name BLUE_HUB protocols bgp address-family ipv4-unicast network 10.80.80.0/24 -set vrf name BLUE_HUB protocols bgp address-family ipv4-unicast rd vpn export '10.80.80.1:1011' -set vrf name BLUE_HUB protocols bgp address-family ipv4-unicast redistribute connected -set vrf name BLUE_HUB protocols bgp address-family ipv4-unicast route-target vpn export '65035:1030' -set vrf name BLUE_HUB protocols bgp address-family ipv4-unicast route-target vpn import '65035:1011 65050:2011 65035:1030' -set vrf name BLUE_HUB protocols bgp neighbor 10.80.80.2 address-family ipv4-unicast as-override -set vrf name BLUE_HUB protocols bgp neighbor 10.80.80.2 remote-as '65035' - -# interfaces -set interfaces ethernet eth3 address '10.80.80.1/24' -set interfaces ethernet eth3 vrf 'BLUE_HUB' -``` - -- VyOS-PE3: - -```none -# VRF settings -set vrf name BLUE_SPOKE table '200' -set vrf name BLUE_SPOKE protocols bgp address-family ipv4-unicast export vpn -set vrf name BLUE_SPOKE protocols bgp address-family ipv4-unicast import vpn -set vrf name BLUE_SPOKE protocols bgp address-family ipv4-unicast label vpn export 'auto' -set vrf name BLUE_SPOKE protocols bgp address-family ipv4-unicast network 10.60.60.0/24 -set vrf name BLUE_SPOKE protocols bgp address-family ipv4-unicast rd vpn export '10.60.60.1:1011' -set vrf name BLUE_SPOKE protocols bgp address-family ipv4-unicast redistribute connected -set vrf name BLUE_SPOKE protocols bgp address-family ipv4-unicast route-target vpn export '65035:1011' -set vrf name BLUE_SPOKE protocols bgp address-family ipv4-unicast route-target vpn import '65035:1030' -set vrf name BLUE_SPOKE protocols bgp neighbor 10.60.60.2 address-family ipv4-unicast as-override -set vrf name BLUE_SPOKE protocols bgp neighbor 10.60.60.2 remote-as '65035' - -# interfaces -set interfaces ethernet eth3 address '10.60.60.1/24' -set interfaces ethernet eth3 vrf 'BLUE_SPOKE' -``` - - -### Step-4: Configuring CE nodes - -Dynamic routing used between CE and PE nodes and eBGP peering -established for the route exchanging between them. All routes -received by PEs are then exported to L3VPN and delivered from -Spoke sites to Hub and vise-versa based on previously -configured L3VPN parameters. -- VyOS-CE1-SPOKE: - -```none -# interfaces -set interfaces dummy dum20 address '10.0.0.80/32' -set interfaces ethernet eth0 address '10.50.50.2/24' - -# BGP for peering with PE -set protocols bgp system-as 65035 -set protocols bgp address-family ipv4-unicast network 10.0.0.80/32 -set protocols bgp neighbor 10.50.50.1 ebgp-multihop '2' -set protocols bgp neighbor 10.50.50.1 remote-as '65001' -set protocols bgp neighbor 10.50.50.1 update-source 'eth0' -set protocols bgp parameters log-neighbor-changes -set protocols bgp parameters router-id '10.50.50.2' -``` - -- VyOS-CE1-HUB: - -```none -# interfaces -set interfaces dummy dum20 address '10.0.0.100/32' -set interfaces ethernet eth0 address '10.80.80.2/24' - -# BGP for peering with PE -set protocols bgp system-as 65035 -set protocols bgp address-family ipv4-unicast network 10.0.0.100/32 -set protocols bgp address-family ipv4-unicast redistribute connected -set protocols bgp neighbor 10.80.80.1 ebgp-multihop '2' -set protocols bgp neighbor 10.80.80.1 remote-as '65001' -set protocols bgp neighbor 10.80.80.1 update-source 'eth0' -set protocols bgp parameters log-neighbor-changes -set protocols bgp parameters router-id '10.80.80.2' -``` - -- VyOS-CE2-SPOKE: - -```none -# interfaces -set interfaces dummy dum20 address '10.0.0.90/32' -set interfaces ethernet eth0 address '10.60.60.2/24' - -# BGP for peering with PE -set protocols bgp system-as 65035 -set protocols bgp address-family ipv4-unicast network 10.0.0.90/32 -set protocols bgp neighbor 10.60.60.1 ebgp-multihop '2' -set protocols bgp neighbor 10.60.60.1 remote-as '65001' -set protocols bgp neighbor 10.60.60.1 update-source 'eth0' -set protocols bgp parameters log-neighbor-changes -set protocols bgp parameters router-id '10.60.60.2' -``` - - -### Step-5: Verification - -This section describes verification commands for MPLS/BGP/LDP -protocols and L3VPN related routes as well as diagnosis and -reachability checks between CE nodes. - -Let’s check IPv4 routing and MPLS information on provider nodes -(same procedure for all P nodes): -- “show ip ospf neighbor” for checking ospf relationship - -```none -vyos@VyOS-P1:~$ show ip ospf neighbor - -Neighbor ID Pri State Dead Time Address Interface RXmtL RqstL DBsmL -10.0.0.4 1 Full/Backup 34.718s 172.16.30.2 eth0:172.16.30.1 0 0 0 -10.0.0.5 1 Full/Backup 35.132s 172.16.40.2 eth1:172.16.40.1 0 0 0 -10.0.0.7 1 Full/Backup 34.764s 172.16.90.2 eth2:172.16.90.1 0 0 0 -10.0.0.1 1 Full/Backup 35.642s 172.16.10.2 eth3:172.16.10.1 0 0 0 -10.0.0.8 1 Full/Backup 35.484s 172.16.100.2 eth5:172.16.100.1 0 0 0 -``` - -- “show mpls ldp neighbor “ for checking ldp neighbors - -```none -vyos@VyOS-P1:~$ show mpls ldp neighbor -AF ID State Remote Address Uptime -ipv4 10.0.0.1 OPERATIONAL 10.0.0.1 07w5d06h -ipv4 10.0.0.4 OPERATIONAL 10.0.0.4 09w3d00h -ipv4 10.0.0.5 OPERATIONAL 10.0.0.5 09w2d23h -ipv4 10.0.0.7 OPERATIONAL 10.0.0.7 03w0d01h -ipv4 10.0.0.8 OPERATIONAL 10.0.0.8 01w3d02h -``` - -- “show mpls ldp binding” for checking mpls label assignment - -```none -vyos@VyOS-P1:~$ show mpls ldp discovery -AF Destination Nexthop Local Label Remote Label In Use -ipv4 10.0.0.1/32 10.0.0.1 23 imp-null yes -ipv4 10.0.0.1/32 10.0.0.4 23 20 no -ipv4 10.0.0.1/32 10.0.0.5 23 17 no -ipv4 10.0.0.1/32 10.0.0.7 23 16 no -ipv4 10.0.0.1/32 10.0.0.8 23 16 no -ipv4 10.0.0.2/32 10.0.0.1 20 16 no -ipv4 10.0.0.2/32 10.0.0.4 20 22 no -ipv4 10.0.0.2/32 10.0.0.5 20 24 yes -ipv4 10.0.0.2/32 10.0.0.7 20 17 no -ipv4 10.0.0.2/32 10.0.0.8 20 17 no -ipv4 10.0.0.3/32 10.0.0.1 imp-null 17 no -ipv4 10.0.0.3/32 10.0.0.4 imp-null 16 no -ipv4 10.0.0.3/32 10.0.0.5 imp-null 18 no -ipv4 10.0.0.3/32 10.0.0.7 imp-null 18 no -ipv4 10.0.0.3/32 10.0.0.8 imp-null 18 no -ipv4 10.0.0.4/32 10.0.0.1 16 18 no -ipv4 10.0.0.4/32 10.0.0.4 16 imp-null yes -ipv4 10.0.0.4/32 10.0.0.5 16 19 no -ipv4 10.0.0.4/32 10.0.0.7 16 19 no -ipv4 10.0.0.4/32 10.0.0.8 16 19 no -ipv4 10.0.0.5/32 10.0.0.1 21 19 no -ipv4 10.0.0.5/32 10.0.0.4 21 17 no -ipv4 10.0.0.5/32 10.0.0.5 21 imp-null yes -ipv4 10.0.0.5/32 10.0.0.7 21 20 no -ipv4 10.0.0.5/32 10.0.0.8 21 20 no -ipv4 10.0.0.6/32 10.0.0.1 17 20 no -ipv4 10.0.0.6/32 10.0.0.4 17 23 yes -ipv4 10.0.0.6/32 10.0.0.5 17 21 yes -ipv4 10.0.0.6/32 10.0.0.7 17 21 no -ipv4 10.0.0.6/32 10.0.0.8 17 21 no -ipv4 10.0.0.7/32 10.0.0.1 22 21 no -ipv4 10.0.0.7/32 10.0.0.4 22 18 no -ipv4 10.0.0.7/32 10.0.0.5 22 20 no -ipv4 10.0.0.7/32 10.0.0.7 22 imp-null yes -ipv4 10.0.0.7/32 10.0.0.8 22 22 no -ipv4 10.0.0.8/32 10.0.0.1 24 22 no -ipv4 10.0.0.8/32 10.0.0.4 24 19 no -ipv4 10.0.0.8/32 10.0.0.5 24 16 no -ipv4 10.0.0.8/32 10.0.0.7 24 22 no -ipv4 10.0.0.8/32 10.0.0.8 24 imp-null yes -ipv4 10.0.0.9/32 10.0.0.1 18 23 no -ipv4 10.0.0.9/32 10.0.0.4 18 21 yes -ipv4 10.0.0.9/32 10.0.0.5 18 22 no -ipv4 10.0.0.9/32 10.0.0.7 18 23 no -ipv4 10.0.0.9/32 10.0.0.8 18 23 no -ipv4 10.0.0.10/32 10.0.0.1 19 24 no -ipv4 10.0.0.10/32 10.0.0.4 19 24 yes -ipv4 10.0.0.10/32 10.0.0.5 19 23 yes -ipv4 10.0.0.10/32 10.0.0.7 19 24 no -ipv4 10.0.0.10/32 10.0.0.8 19 24 no -``` - -Now we’re checking iBGP status and routes from route-reflector -nodes to other devices: -- “show bgp ipv4 vpn summary” for checking BGP VPNv4 neighbors: - -```none -vyos@VyOS-RR1:~$ show bgp ipv4 vpn summary -BGP router identifier 10.0.0.1, local AS number 65001 vrf-id 0 -BGP table version 0 -RIB entries 9, using 1728 bytes of memory -Peers 4, using 85 KiB of memory -Peer groups 1, using 64 bytes of memory - -Neighbor V AS MsgRcvd MsgSent TblVer InQ OutQ Up/Down State/PfxRcd PfxSnt -10.0.0.7 4 65001 7719 7733 0 0 0 5d07h56m 2 10 -10.0.0.8 4 65001 7715 7724 0 0 0 5d08h28m 4 10 -10.0.0.9 4 65001 7713 7724 0 0 0 5d08h28m 2 10 -10.0.0.10 4 65001 7713 7724 0 0 0 5d08h28m 2 10 - -Total number of neighbors 4 -``` - -- “show bgp ipv4 vpn” for checking all VPNv4 prefixes information: - -```none -vyos@VyOS-RR1:~$ show bgp ipv4 vpn -BGP table version is 2, local router ID is 10.0.0.1, vrf id 0 -Default local pref 100, local AS 65001 -Status codes: s suppressed, d damped, h history, * valid, > best, = multipath, - i internal, r RIB-failure, S Stale, R Removed -Nexthop codes: @NNN nexthop's vrf id, < announce-nh-self -Origin codes: i - IGP, e - EGP, ? - incomplete - - Network Next Hop Metric LocPrf Weight Path -Route Distinguisher: 10.50.50.1:1011 -*>i10.50.50.0/24 10.0.0.7 0 100 0 i - UN=10.0.0.7 EC{65035:1011} label=80 type=bgp, subtype=0 -*>i80.80.80.80/32 10.0.0.7 0 100 0 65035 i - UN=10.0.0.7 EC{65035:1011} label=80 type=bgp, subtype=0 -Route Distinguisher: 10.60.60.1:1011 -*>i10.60.60.0/24 10.0.0.10 0 100 0 i - UN=10.0.0.10 EC{65035:1011} label=80 type=bgp, subtype=0 -*>i90.90.90.90/32 10.0.0.10 0 100 0 65035 i - UN=10.0.0.10 EC{65035:1011} label=80 type=bgp, subtype=0 -Route Distinguisher: 10.80.80.1:1011 -*>i10.80.80.0/24 10.0.0.8 0 100 0 i - UN=10.0.0.8 EC{65035:1030} label=80 type=bgp, subtype=0 -*>i100.100.100.100/32 - 10.0.0.8 0 100 0 65035 i - UN=10.0.0.8 EC{65035:1030} label=80 type=bgp, subtype=0 -Route Distinguisher: 172.16.80.1:2011 -*>i10.110.110.0/24 10.0.0.8 0 100 0 65050 i - UN=10.0.0.8 EC{65050:2011} label=81 type=bgp, subtype=0 -*>i172.16.80.0/24 10.0.0.8 0 100 0 i - UN=10.0.0.8 EC{65050:2011} label=81 type=bgp, subtype=0 -Route Distinguisher: 172.16.100.1:2011 -*>i10.210.210.0/24 10.0.0.9 0 100 0 65050 i - UN=10.0.0.9 EC{65050:2011} label=80 type=bgp, subtype=0 -*>i172.16.100.0/24 10.0.0.9 0 100 0 i - UN=10.0.0.9 EC{65050:2011} label=80 type=bgp, subtype=0 -``` - -- “show bgp ipv4 vpn x.x.x.x/x” for checking best path selected - for specific VPNv4 destination - -```none -vyos@VyOS-RR1:~$ show bgp ipv4 vpn 10.0.0.100/32 -BGP routing table entry for 10.80.80.1:1011:10.0.0.100/32 -not allocated -Paths: (1 available, best #1) - Advertised to non peer-group peers: - 10.0.0.7 10.0.0.8 10.0.0.9 10.0.0.10 - 65035, (Received from a RR-client) - 10.0.0.8 from 10.0.0.8 (10.0.0.8) - Origin incomplete, metric 0, localpref 100, valid, internal, best (First path received) - Extended Community: RT:65035:1030 - Remote label: 80 - Last update: Tue Oct 19 13:45:32 202 -``` - -Also we can verify how PE devices receives VPNv4 networks from the RRs -and installing them to the specific customer VRFs: -- “show bgp ipv4 vpn summary” for checking iBGP neighbors against - route-reflector devices: - -```none -vyos@VyOS-PE1:~$ show bgp ipv4 vpn summary -BGP router identifier 10.0.0.7, local AS number 65001 vrf-id 0 -BGP table version 0 -RIB entries 9, using 1728 bytes of memory -Peers 2, using 43 KiB of memory -Peer groups 1, using 64 bytes of memory - -Neighbor V AS MsgRcvd MsgSent TblVer InQ OutQ Up/Down State/PfxRcd PfxSnt -10.0.0.1 4 65001 8812 8794 0 0 0 01:18:42 8 2 -10.0.0.2 4 65001 8800 8792 0 0 0 6d02h27m 8 2 -``` - -- “show bgp vrf all” for checking all the prefix learning on BGP - : within VRFs: - -```none -vyos@VyOS-PE1:~$ show bgp vrf all - -Instance default: -No BGP prefixes displayed, 0 exist - -Instance BLUE_SPOKE: -BGP table version is 8, local router ID is 10.50.50.1, vrf id 6 -Default local pref 100, local AS 65001 -Status codes: s suppressed, d damped, h history, * valid, > best, = multipath, - i internal, r RIB-failure, S Stale, R Removed -Nexthop codes: @NNN nexthop's vrf id, < announce-nh-self -Origin codes: i - IGP, e - EGP, ? - incomplete - - Network Next Hop Metric LocPrf Weight Path -* 10.50.50.0/24 0.0.0.0 0 32768 ? -*> 0.0.0.0 0 32768 i -*> 10.80.80.0/24 10.0.0.8@0< 0 100 0 i -* 10.0.0.8@0< 0 100 0 i -*> 10.0.0.80/32 10.50.50.2 0 0 65035 i -*> 10.0.0.100/32 - 10.0.0.8@0< 0 100 0 65035 ? -* 10.0.0.8@0< 0 100 0 65035 ? -``` - -- “show bgp vrf BLUE_SPOKE summary” for checking EBGP neighbor - : information between PE and CE: - -```none -vyos@VyOS-PE1:~$ show bgp vrf BLUE_SPOKE summary - -IPv4 Unicast Summary: -BGP router identifier 10.50.50.1, local AS number 65001 vrf-id 6 -BGP table version 8 -RIB entries 7, using 1344 bytes of memory -Peers 1, using 21 KiB of memory - -Neighbor V AS MsgRcvd MsgSent TblVer InQ OutQ Up/Down State/PfxRcd PfxSnt -10.50.50.2 4 65035 9019 9023 0 0 0 6d06h12m 1 4 - -Total number of neighbors 1 -``` - -- “show ip route vrf BLUE_SPOKE” for viewing the RIB in our Spoke PE. - : Using this command we are also able to check the transport and - customer label (inner/outer) for Hub network prefix (10.0.0.100/32): - -```none -vyos@VyOS-PE1:~$ show ip route vrf BLUE_SPOKE - -Codes: K - kernel route, C - connected, S - static, R - RIP, - O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, - T - Table, v - VNC, V - VNC-Direct, A - Babel, D - SHARP, - F - PBR, f - OpenFabric, - > - selected route, * - FIB route, q - queued, r - rejected, b - backup - -VRF BLUE_SPOKE: -K>* 0.0.0.0/0 [255/8192] unreachable (ICMP unreachable), 03w0d23h -C>* 10.50.50.0/24 is directly connected, eth3, 03w0d23h -B> 10.80.80.0/24 [200/0] via 10.0.0.8 (vrf default) (recursive), label 80, weight 1, 04:22:00 - * via 172.16.90.1, eth0 (vrf default), label 24/80, weight 1, 04:22:00 -B>* 10.0.0.80/32 [20/0] via 10.50.50.2, eth3, weight 1, 6d05h30m -B> 10.0.0.100/32 [200/0] via 10.0.0.8 (vrf default) (recursive), label 80, weight 1, 04:22:00 - * via 172.16.90.1, eth0 (vrf default), label 24/80, weight 1, 04:22:00 -``` - -- “show bgp ipv4 vpn x.x.x.x/32” for checking the best-path to the - : specific VPNv4 destination including extended community and - remotelabel information. This procedure is the same on all Spoke nodes: - -```none -vyos@VyOS-PE1:~$ show bgp ipv4 vpn 10.0.0.100/32 -BGP routing table entry for 10.80.80.1:1011:10.0.0.100/32 -not allocated -Paths: (2 available, best #1) - Not advertised to any peer - 65035 - 10.0.0.8 from 10.0.0.1 (10.0.0.8) - Origin incomplete, metric 0, localpref 100, valid, internal, best (Neighbor IP) - Extended Community: RT:65035:1030 - Originator: 10.0.0.8, Cluster list: 10.0.0.1 - Remote label: 80 - Last update: Tue Oct 19 13:45:26 2021 - 65035 - 10.0.0.8 from 10.0.0.2 (10.0.0.8) - Origin incomplete, metric 0, localpref 100, valid, internal - Extended Community: RT:65035:1030 - Originator: 10.0.0.8, Cluster list: 10.0.0.1 - Remote label: 80 - Last update: Wed Oct 13 12:39:34 202 -``` - -Now, let’s check routing information on out Hub PE: -- “show bgp ipv4 vpn summary” for checking iBGP neighbors again - : VyOS-RR1/RR2 - -```none -vyos@VyOS-PE2:~$ show bgp ipv4 vpn summary -BGP router identifier 10.0.0.8, local AS number 65001 vrf-id 0 -BGP table version 0 -RIB entries 9, using 1728 bytes of memory -Peers 2, using 43 KiB of memory -Peer groups 1, using 64 bytes of memory - -Neighbor V AS MsgRcvd MsgSent TblVer InQ OutQ Up/Down State/PfxRcd PfxSnt -10.0.0.1 4 65001 15982 15949 0 0 0 05:41:28 6 4 -10.0.0.2 4 65001 9060 9054 0 0 0 6d06h47m 6 4 - -Total number of neighbors -``` - -- “show bgp vrf all” for checking all the prefixes learning on BGP - -```none -vyos@VyOS-PE2:~$ show bgp vrf all - -Instance default: -No BGP prefixes displayed, 0 exist - -Instance BLUE_HUB: -BGP table version is 50, local router ID is 10.80.80.1, vrf id 8 -Default local pref 100, local AS 65001 -Status codes: s suppressed, d damped, h history, * valid, > best, = multipath, - i internal, r RIB-failure, S Stale, R Removed -Nexthop codes: @NNN nexthop's vrf id, < announce-nh-self -Origin codes: i - IGP, e - EGP, ? - incomplete - - Network Next Hop Metric LocPrf Weight Path -*> 10.50.50.0/24 10.0.0.7@0< 0 100 0 i -* 10.0.0.7@0< 0 100 0 i -*> 10.60.60.0/24 10.0.0.10@0< 0 100 0 i -* 10.0.0.10@0< 0 100 0 i -* 10.80.80.0/24 10.80.80.2 0 0 65035 ? -* 0.0.0.0 0 32768 i -*> 0.0.0.0 0 32768 ? -*> 10.110.110.0/24 172.16.80.2@9< 0 0 65050 i -*> 10.210.210.0/24 10.0.0.9@0< 0 100 0 65050 i -* 10.0.0.9@0< 0 100 0 65050 i -*> 10.0.0.80/32 10.0.0.7@0< 0 100 0 65035 i -* 10.0.0.7@0< 0 100 0 65035 i -*> 10.0.0.90/32 10.0.0.10@0< 0 100 0 65035 i -* 10.0.0.10@0< 0 100 0 65035 i -*> 10.0.0.100/32 - 10.80.80.2 0 0 65035 ? -*> 172.16.80.0/24 0.0.0.0@9< 0 32768 ? - 0.0.0.0@9< 0 32768 i -*> 172.16.100.0/24 10.0.0.9@0< 0 100 0 i -* 10.0.0.9@0< 0 100 0 i -``` - -- “show bgp vrf BLUE_HUB summary” for checking EBGP neighbor - : CE Hub device - -```none -vyos@VyOS-PE2:~$ show bgp vrf BLUE_HUB summary - -IPv4 Unicast Summary: -BGP router identifier 10.80.80.1, local AS number 65001 vrf-id 8 -BGP table version 50 -RIB entries 19, using 3648 bytes of memory -Peers 1, using 21 KiB of memory - -Neighbor V AS MsgRcvd MsgSent TblVer InQ OutQ Up/Down State/PfxRcd PfxSnt -10.80.80.2 4 65035 15954 15972 0 0 0 01w4d01h 2 10 -``` - -- “show ip route vrf BLUE_HUB” to view the RIB in our Hub PE. - : With this command we are able to check the transport and - customer label (inner/outer) for network spokes prefixes - 10.0.0.80/32 - 10.0.0.90/32 - -```none -vyos@VyOS-PE2:~$ show ip route vrf BLUE_HUB - -Codes: K - kernel route, C - connected, S - static, R - RIP, - O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, - T - Table, v - VNC, V - VNC-Direct, A - Babel, D - SHARP, - F - PBR, f - OpenFabric, - > - selected route, * - FIB route, q - queued, r - rejected, b - backup - -VRF BLUE_HUB: -K>* 0.0.0.0/0 [255/8192] unreachable (ICMP unreachable), 01w4d01h -B> 10.50.50.0/24 [200/0] via 10.0.0.7 (vrf default) (recursive), label 144, weight 1, 05:53:15 - * via 172.16.100.1, eth1 (vrf default), label 22/144, weight 1, 05:53:15 -B> 10.60.60.0/24 [200/0] via 10.0.0.10 (vrf default) (recursive), label 144, weight 1, 05:53:15 - * via 172.16.110.1, eth0 (vrf default), label 23/144, weight 1, 05:53:15 -C>* 10.80.80.0/24 is directly connected, eth3, 01w4d01h -B>* 10.110.110.0/24 [200/0] via 172.16.80.2, eth2 (vrf GREEN), weight 1, 01w4d01h -B> 10.210.210.0/24 [200/0] via 10.0.0.9 (vrf default) (recursive), label 144, weight 1, 05:53:15 - * via 172.16.100.1, eth1 (vrf default), label 18/144, weight 1, 05:53:15 - * via 172.16.110.1, eth0 (vrf default), label 22/144, weight 1, 05:53:15 -B> 10.0.0.80/32 [200/0] via 10.0.0.7 (vrf default) (recursive), label 144, weight 1, 05:53:15 - * via 172.16.100.1, eth1 (vrf default), label 22/144, weight 1, 05:53:15 -B> 10.0.0.90/32 [200/0] via 10.0.0.10 (vrf default) (recursive), label 144, weight 1, 05:53:15 - * via 172.16.110.1, eth0 (vrf default), label 23/144, weight 1, 05:53:15 -B>* 10.0.0.100/32 [20/0] via 10.80.80.2, eth3, weight 1, 01w4d01h -B>* 172.16.80.0/24 [200/0] is directly connected, eth2 (vrf GREEN), weight 1, 01w4d01h -B> 172.16.100.0/24 [200/0] via 10.0.0.9 (vrf default) (recursive), label 144, weight 1, 05:53:15 - * via 172.16.100.1, eth1 (vrf default), label 18/144, weight 1, 05:53:15 - * via 172.16.110.1, eth0 (vrf default), label 22/144, weight 1, 05:53:15 -``` - -- “show bgp ipv4 vpn x.x.x.x/32” for checking best-path, - : extended community and remote label of specific destination - -```none -vyos@VyOS-PE2:~$ show bgp ipv4 vpn 10.0.0.80/32 -BGP routing table entry for 10.50.50.1:1011:10.0.0.80/32 -not allocated -Paths: (2 available, best #1) - Not advertised to any peer - 65035 - 10.0.0.7 from 10.0.0.1 (10.0.0.7) - Origin IGP, metric 0, localpref 100, valid, internal, best (Neighbor IP) - Extended Community: RT:65035:1011 - Originator: 10.0.0.7, Cluster list: 10.0.0.1 - Remote label: 144 - Last update: Tue Oct 19 13:45:30 2021 - 65035 - 10.0.0.7 from 10.0.0.2 (10.0.0.7) - Origin IGP, metric 0, localpref 100, valid, internal - Extended Community: RT:65035:1011 - Originator: 10.0.0.7, Cluster list: 10.0.0.1 - Remote label: 144 - Last update: Wed Oct 13 12:39:37 2021 - -vyos@VyOS-PE2:~$ show bgp ipv4 vpn 10.0.0.90/32 -BGP routing table entry for 10.60.60.1:1011:10.0.0.90/32 -not allocated -Paths: (2 available, best #1) - Not advertised to any peer - 65035 - 10.0.0.10 from 10.0.0.1 (10.0.0.10) - Origin IGP, metric 0, localpref 100, valid, internal, best (Neighbor IP) - Extended Community: RT:65035:1011 - Originator: 10.0.0.10, Cluster list: 10.0.0.1 - Remote label: 144 - Last update: Tue Oct 19 13:45:30 2021 - 65035 - 10.0.0.10 from 10.0.0.2 (10.0.0.10) - Origin IGP, metric 0, localpref 100, valid, internal - Extended Community: RT:65035:1011 - Originator: 10.0.0.10, Cluster list: 10.0.0.1 - Remote label: 144 - Last update: Wed Oct 13 12:45:44 2021 -``` - -Finally, let’s check the reachability between CEs: -- VyOS-CE1-SPOKE -----> VyOS-CE-HUB - -```none -# check rib -vyos@VyOS-CE1-SPOKE:~$ show ip route -Codes: K - kernel route, C - connected, S - static, R - RIP, - O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, - T - Table, v - VNC, V - VNC-Direct, A - Babel, D - SHARP, - F - PBR, f - OpenFabric, - > - selected route, * - FIB route, q - queued, r - rejected, b - backup - -B 10.50.50.0/24 [20/0] via 10.50.50.1 inactive, weight 1, 6d07h53m -C>* 10.50.50.0/24 is directly connected, eth0, 09w0d00h -B>* 10.80.80.0/24 [20/0] via 10.50.50.1, eth0, weight 1, 6d07h53m -C>* 10.0.0.80/32 is directly connected, dum20, 09w0d00h -B>* 10.0.0.100/32 [20/0] via 10.50.50.1, eth0, weight 1, 6d07h53m - -# check icmp -vyos@VyOS-CE1-SPOKE:~$ ping 10.0.0.100 interface 10.0.0.80 -PING 10.0.0.100 (10.0.0.100) from 10.0.0.80 : 56(84) bytes of data. -64 bytes from 10.0.0.100: icmp_seq=1 ttl=62 time=6.52 ms -64 bytes from 10.0.0.100: icmp_seq=2 ttl=62 time=4.13 ms -64 bytes from 10.0.0.100: icmp_seq=3 ttl=62 time=4.04 ms -64 bytes from 10.0.0.100: icmp_seq=4 ttl=62 time=4.03 ms -^C ---- 10.0.0.100 ping statistics --- -4 packets transmitted, 4 received, 0% packet loss, time 8ms -rtt min/avg/max/mdev = 4.030/4.680/6.518/1.064 ms - -# check network path -vyos@VyOS-CE1-SPOKE:~$ traceroute 10.0.0.100 -traceroute to 10.0.0.100 (10.0.0.100), 30 hops max, 60 byte packets - 1 10.50.50.1 (10.50.50.1) 1.041 ms 1.252 ms 1.835 ms - 2 * * * - 3 10.0.0.100 (10.0.0.100) 9.225 ms 9.159 ms 9.121 m -``` - -- VyOS-CE-HUB -------> VyOS-CE1-SPOKE -- VyOS-CE-HUB -------> VyOS-CE2-SPOKE - -```none -# check rib -vyos@VyOS-CE-HUB:~$ show ip route -Codes: K - kernel route, C - connected, S - static, R - RIP, - O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, - T - Table, v - VNC, V - VNC-Direct, A - Babel, D - SHARP, - F - PBR, f - OpenFabric, - > - selected route, * - FIB route, q - queued, r - rejected, b - backup - -B>* 10.50.50.0/24 [20/0] via 10.80.80.1, eth0, weight 1, 6d08h04m -B>* 10.60.60.0/24 [20/0] via 10.80.80.1, eth0, weight 1, 6d08h35m -C>* 10.80.80.0/24 is directly connected, eth0, 01w6d07h -B>* 10.110.110.0/24 [20/0] via 10.80.80.1, eth0, weight 1, 01w4d02h -B>* 10.210.210.0/24 [20/0] via 10.80.80.1, eth0, weight 1, 6d08h35m -B>* 10.0.0.80/32 [20/0] via 10.80.80.1, eth0, weight 1, 6d08h04m -B>* 10.0.0.90/32 [20/0] via 10.80.80.1, eth0, weight 1, 6d08h35m -C>* 10.0.0.100/32 is directly connected, dum20, 01w6d07h -B>* 172.16.80.0/24 [20/0] via 10.80.80.1, eth0, weight 1, 01w4d02h -B>* 172.16.100.0/24 [20/0] via 10.80.80.1, eth0, weight 1, 6d08h35m - -# check icmp -vyos@VyOS-CE-HUB:~$ ping 10.0.0.80 interface 10.0.0.100 c 4 -PING 10.0.0.80 (10.0.0.80) from 10.0.0.100 : 56(84) bytes of data. -64 bytes from 10.0.0.80: icmp_seq=1 ttl=62 time=3.31 ms -64 bytes from 10.0.0.80: icmp_seq=2 ttl=62 time=4.23 ms -64 bytes from 10.0.0.80: icmp_seq=3 ttl=62 time=3.89 ms -64 bytes from 10.0.0.80: icmp_seq=4 ttl=62 time=3.22 ms - ---- 10.0.0.80 ping statistics --- -4 packets transmitted, 4 received, 0% packet loss, time 9ms -rtt min/avg/max/mdev = 3.218/3.661/4.226/0.421 ms - -vyos@VyOS-CE-HUB:~$ ping 10.0.0.90 interface 10.0.0.100 c 4 -PING 10.0.0.90 (10.0.0.90) from 10.0.0.100 : 56(84) bytes of data. -64 bytes from 10.0.0.90: icmp_seq=1 ttl=62 time=7.46 ms -64 bytes from 10.0.0.90: icmp_seq=2 ttl=62 time=4.43 ms -64 bytes from 10.0.0.90: icmp_seq=3 ttl=62 time=4.60 ms -^C ---- 10.0.0.90 ping statistics --- -3 packets transmitted, 3 received, 0% packet loss, time 6ms -rtt min/avg/max/mdev = 4.430/5.498/7.463/1.391 ms - -# check network path -vyos@VyOS-CE-HUB:~$ traceroute 10.0.0.80 -traceroute to 10.0.0.80 (10.0.0.80), 30 hops max, 60 byte packets - 1 10.80.80.1 (10.80.80.1) 1.563 ms 1.341 ms 1.075 ms - 2 * * * - 3 10.0.0.80 (10.0.0.80) 8.125 ms 8.019 ms 7.781 ms - -vyos@VyOS-CE-HUB:~$ traceroute 10.0.0.90 -traceroute to 10.0.0.90 (10.0.0.90), 30 hops max, 60 byte packets - 1 10.80.80.1 (10.80.80.1) 1.305 ms 1.137 ms 1.097 ms - 2 * * * - 3 * * * - 4 10.0.0.90 (10.0.0.90) 9.358 ms 9.325 ms 9.292 ms -``` - -- VyOS-CE2-SPOKE -------> VyOS-CE-HUB - -```none -# check rib -vyos@rt-ce2-SPOKE:~$ show ip route -Codes: K - kernel route, C - connected, S - static, R - RIP, - O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, - T - Table, v - VNC, V - VNC-Direct, A - Babel, D - SHARP, - F - PBR, f - OpenFabric, - > - selected route, * - FIB route, q - queued, r - rejected, b - backup - -B 10.60.60.0/24 [20/0] via 10.60.60.1 inactive, weight 1, 02w6d00h -C>* 10.60.60.0/24 is directly connected, eth0, 02w6d00h -B>* 10.80.80.0/24 [20/0] via 10.60.60.1, eth0, weight 1, 6d08h46m -C>* 10.0.0.90/32 is directly connected, dum20, 02w6d00h -B>* 10.0.0.100/32 [20/0] via 10.60.60.1, eth0, weight 1, 6d08h46m - -# check icmp -vyos@rt-ce2-SPOKE:~$ ping 10.0.0.100 interface 10.0.0.90 c 4 -PING 10.0.0.100 (10.0.0.100) from 10.0.0.90 : 56(84) bytes of data. -64 bytes from 10.0.0.100: icmp_seq=1 ttl=62 time=4.97 ms -64 bytes from 10.0.0.100: icmp_seq=2 ttl=62 time=4.45 ms -64 bytes from 10.0.0.100: icmp_seq=3 ttl=62 time=4.20 ms -64 bytes from 10.0.0.100: icmp_seq=4 ttl=62 time=4.29 ms - ---- 10.0.0.100 ping statistics --- -4 packets transmitted, 4 received, 0% packet loss, time 9ms -rtt min/avg/max/mdev = 4.201/4.476/4.971/0.309 ms - -# check network path -vyos@rt-ce2-SPOKE:~$ traceroute 10.0.0.100 -traceroute to 10.0.0.100 (10.0.0.100), 30 hops max, 60 byte packets - 1 10.60.60.1 (10.60.60.1) 1.343 ms 1.190 ms 1.152 ms - 2 * * * - 3 * * * - 4 10.0.0.100 (10.0.0.100) 7.504 ms 7.480 ms 7.488 ms -``` - -**Note:** At the moment, trace mpls doesn’t show labels/paths. So we’ll -see `* * *` for the transit routers of the mpls backbone. diff --git a/docs/configexamples/md-lac-lns.md b/docs/configexamples/md-lac-lns.md deleted file mode 100644 index 51a96f8b..00000000 --- a/docs/configexamples/md-lac-lns.md +++ /dev/null @@ -1,181 +0,0 @@ ---- -lastproofread: '2024-02-21' ---- - -(examples-lac-lns)= - -# PPPoE over L2TP - -This document is to describe a basic setup using PPPoE over L2TP. -LAC and LNS are components of the broadband topology. -LAC - L2TP access concentrator -LNS - L2TP Network Server -LAC and LNS forms L2TP tunnel. LAC receives packets from PPPoE clients and -forward them to LNS. LNS is the termination point that comes from PPP packets -from the remote client. - -In this example we use VyOS 1.5 as LNS and Cisco IOS as LAC. -All users with domain **vyos.io** will be tunneled to LNS via L2TP. - -## Network Topology - -```{image} /_static/images/lac-lns-diagram.webp -:align: center -:alt: Network Topology Diagram -:width: 60% -``` - - -## Configurations - -### LAC - -```none -aaa new-model -! -aaa authentication ppp default local -! -vpdn enable -vpdn aaa attribute nas-ip-address vpdn-nas -! -vpdn-group LAC - request-dialin - protocol l2tp - domain vyos.io - initiate-to ip 192.168.139.100 - source-ip 192.168.139.101 - local name LAC - l2tp tunnel password 0 test123 -! -bba-group pppoe MAIN-BBA - virtual-template 1 -! -interface GigabitEthernet0/0 - description To LNS - ip address 192.168.139.101 255.255.255.0 - duplex auto - speed auto - media-type rj45 -! -interface GigabitEthernet0/1 - description To PPPoE clients - no ip address - duplex auto - speed auto - media-type rj45 - pppoe enable group MAIN-BBA -! -interface Virtual-Template1 - description pppoe MAIN-BBA - no ip address - no peer default ip address - ppp mtu adaptive - ppp authentication chap -! -``` - - -### LNS - -% stop_vyoslinter - -```none -set interfaces ethernet eth0 address '192.168.139.100/24' -set nat source rule 100 outbound-interface name 'eth0' -set nat source rule 100 source address '10.0.0.0/24' -set nat source rule 100 translation address 'masquerade' -set protocols static route 0.0.0.0/0 next-hop 192.168.139.2 -set vpn l2tp remote-access authentication mode 'radius' -set vpn l2tp remote-access authentication radius server 192.168.139.110 key 'radiustest' -set vpn l2tp remote-access client-ip-pool TEST-POOL range '10.0.0.2-10.0.0.100' -set vpn l2tp remote-access default-pool 'TEST-POOL' -set vpn l2tp remote-access gateway-address '10.0.0.1' -set vpn l2tp remote-access lns host-name 'LAC' -set vpn l2tp remote-access lns shared-secret 'test123' -set vpn l2tp remote-access name-server '8.8.8.8' -set vpn l2tp remote-access ppp-options disable-ccp -``` - -% start_vyoslinter - -:::{note} -This setup requires the Compression Control Protocol (CCP) -being disabled, the command `set vpn l2tp remote-access ppp-options disable-ccp` -accomplishes that. -::: - -### Client - -In this lab we use Windows PPPoE client. - -```{image} /_static/images/lac-lns-winclient.webp -:align: center -:alt: Window PPPoE Client Configuration -:width: 100% -``` - - -### Monitoring - -Monitoring on LNS side - -```none -vyos@vyos:~$ show l2tp-server sessions - ifname | username | ip | ip6 | ip6-dp | calling-sid | rate-limit | state | uptime | rx-bytes | tx-bytes ---------+--------------+----------+-----+--------+-----------------+------------+--------+----------+-----------+---------- - l2tp0 | test@vyos.io | 10.0.0.2 | | | 192.168.139.101 | | active | 00:00:35 | 188.4 KiB | 9.3 MiB -``` - -Monitoring on LAC side - -```none -Router#show pppoe session - 1 session in FORWARDED (FWDED) State - 1 session total -Uniq ID PPPoE RemMAC Port VT VA State - SID LocMAC VA-st Type - 1 1 000c.290b.20a6 Gi0/1 1 N/A FWDED - 0c58.88ac.0001 - -Router#show l2tp -L2TP Tunnel and Session Information Total tunnels 1 sessions 1 - -LocTunID RemTunID Remote Name State Remote Address Sessn L2TP Class/ - Count VPDN Group -23238 2640 LAC est 192.168.139.100 1 LAC - -LocID RemID TunID Username, Intf/ State Last Chg Uniq ID - Vcid, Circuit -25641 25822 23238 test@vyos.io, Gi0/1 est 00:05:36 1 -``` - -Monitoring on RADIUS Server side - -```none -root@Radius:~# cat /var/log/freeradius/radacct/192.168.139.100/detail-20240221 -Wed Feb 21 13:37:17 2024 - User-Name = "test@vyos.io" - NAS-Port = 0 - NAS-Port-Id = "l2tp0" - NAS-Port-Type = Virtual - Service-Type = Framed-User - Framed-Protocol = PPP - Calling-Station-Id = "192.168.139.101" - Called-Station-Id = "192.168.139.100" - Acct-Status-Type = Start - Acct-Authentic = RADIUS - Acct-Session-Id = "45c731e169d9a4f1" - Acct-Session-Time = 0 - Acct-Input-Octets = 0 - Acct-Output-Octets = 0 - Acct-Input-Packets = 0 - Acct-Output-Packets = 0 - Acct-Input-Gigawords = 0 - Acct-Output-Gigawords = 0 - Framed-IP-Address = 10.0.0.2 - NAS-IP-Address = 192.168.139.100 - Event-Timestamp = "Feb 21 2024 13:37:17 UTC" - Tmp-String-9 = "ai:" - Acct-Unique-Session-Id = "ea6a1089816f19c0d0f1819bc61c3318" - Timestamp = 1708522637 -``` diff --git a/docs/configexamples/md-nmp.md b/docs/configexamples/md-nmp.md deleted file mode 100644 index 63231a09..00000000 --- a/docs/configexamples/md-nmp.md +++ /dev/null @@ -1,76 +0,0 @@ ---- -lastproofread: '2023-03-26' ---- - -(examples-nmp)= - -# NMP example - -Consider how to quickly set up NMP and VyOS for monitoring. -NMP is multi-vendor network monitoring from 'SolarWinds' built to -scale and expand with the needs of your network. - -## Configuration 'VyOS' - -First prepare our VyOS router for connection to NMP. We have to set -up the SNMP protocol and connectivity between the router and NMP. - -% stop_vyoslinter - -```none -set interfaces ethernet eth0 address 'dhcp' -set system name-server '8.8.8.8' -set service snmp community router authorization 'test' -set service snmp community router network '0.0.0.0/0' -``` - -% start_vyoslinter - - -## Configuration 'NMP' - -Next, you should just follow the pictures: - -```{image} /_static/images/nmp1.webp -:align: center -:alt: Network Topology Diagram -:width: 80% -``` - -```{image} /_static/images/nmp2.webp -:align: center -:alt: Network Topology Diagram -:width: 80% -``` - -```{image} /_static/images/nmp3.webp -:align: center -:alt: Network Topology Diagram -:width: 80% -``` - -```{image} /_static/images/nmp4.webp -:align: center -:alt: Network Topology Diagram -:width: 80% -``` - -```{image} /_static/images/nmp5.webp -:align: center -:alt: Network Topology Diagram -:width: 80% -``` - -```{image} /_static/images/nmp6.webp -:align: center -:alt: Network Topology Diagram -:width: 80% -``` - -```{image} /_static/images/nmp7.webp -:align: center -:alt: Network Topology Diagram -:width: 80% -``` - -In the end, you'll get a powerful instrument for monitoring the VyOS systems. diff --git a/docs/configexamples/md-ospf-unnumbered.md b/docs/configexamples/md-ospf-unnumbered.md deleted file mode 100644 index 9174d1b4..00000000 --- a/docs/configexamples/md-ospf-unnumbered.md +++ /dev/null @@ -1,118 +0,0 @@ ---- -lastproofread: '2021-06-29' ---- - -(examples-ospf-unnumbered)= - -# OSPF unnumbered with ECMP - -General information can be found in the {ref}`routing-ospf` chapter. - -## Configuration - -- Router A: - -```none -set interfaces ethernet eth0 address '10.0.0.1/24' -set interfaces ethernet eth1 address '192.168.0.1/32' -set interfaces ethernet eth1 ip ospf authentication md5 key-id 1 md5-key 'yourpassword' -set interfaces ethernet eth1 ip ospf network 'point-to-point' -set interfaces ethernet eth2 address '192.168.0.1/32' -set interfaces ethernet eth2 ip ospf authentication md5 key-id 1 md5-key 'yourpassword' -set interfaces ethernet eth2 ip ospf network 'point-to-point' -set interfaces loopback lo address '192.168.0.1/32' -set protocols ospf area 0.0.0.0 authentication 'md5' -set protocols ospf area 0.0.0.0 network '192.168.0.1/32' -set protocols ospf parameters router-id '192.168.0.1' -set protocols ospf redistribute connected -``` - -- Router B: - -```none -set interfaces ethernet eth0 address '10.0.0.2/24' -set interfaces ethernet eth1 address '192.168.0.2/32' -set interfaces ethernet eth1 ip ospf authentication md5 key-id 1 md5-key 'yourpassword' -set interfaces ethernet eth1 ip ospf network 'point-to-point' -set interfaces ethernet eth2 address '192.168.0.2/32' -set interfaces ethernet eth2 ip ospf authentication md5 key-id 1 md5-key 'yourpassword' -set interfaces ethernet eth2 ip ospf network 'point-to-point' -set interfaces loopback lo address '192.168.0.2/32' -set protocols ospf area 0.0.0.0 authentication 'md5' -set protocols ospf area 0.0.0.0 network '192.168.0.2/32' -set protocols ospf parameters router-id '192.168.0.2' -set protocols ospf redistribute connected -``` - - -## Results - -- Router A: - -```none -vyos@vyos:~$ show interfaces -Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down -Interface IP Address S/L Description ---------- ---------- --- ----------- -eth0 10.0.0.1/24 u/u -eth1 192.168.0.1/32 u/u -eth2 192.168.0.1/32 u/u -lo 127.0.0.1/8 u/u - 192.168.0.1/32 - ::1/128 -``` - -```none -vyos@vyos:~$ show ip route -Codes: K - kernel route, C - connected, S - static, R - RIP, - O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, - T - Table, v - VNC, V - VNC-Direct, A - Babel, D - SHARP, - F - PBR, f - OpenFabric, - > - selected route, * - FIB route, q - queued route, r - rejected route - -S>* 0.0.0.0/0 [210/0] via 10.0.0.254, eth0, 00:57:34 -O 10.0.0.0/24 [110/20] via 192.168.0.2, eth1 onlink, 00:13:21 - via 192.168.0.2, eth2 onlink, 00:13:21 -C>* 10.0.0.0/24 is directly connected, eth0, 00:57:35 -O 192.168.0.1/32 [110/0] is directly connected, lo, 00:48:53 -C * 192.168.0.1/32 is directly connected, eth2, 00:56:31 -C * 192.168.0.1/32 is directly connected, eth1, 00:56:31 -C>* 192.168.0.1/32 is directly connected, lo, 00:57:36 -O>* 192.168.0.2/32 [110/1] via 192.168.0.2, eth1 onlink, 00:29:03 - * via 192.168.0.2, eth2 onlink, 00:29:03 -``` - -- Router B: - -```none -vyos@vyos:~$ show interfaces -Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down -Interface IP Address S/L Description ---------- ---------- --- ----------- -eth0 10.0.0.2/24 u/u -eth1 192.168.0.2/32 u/u -eth2 192.168.0.2/32 u/u -lo 127.0.0.1/8 u/u - 192.168.0.2/32 - ::1/128 -``` - -```none -vyos@vyos:~$ show ip route -Codes: K - kernel route, C - connected, S - static, R - RIP, - O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, - T - Table, v - VNC, V - VNC-Direct, A - Babel, D - SHARP, - F - PBR, f - OpenFabric, - > - selected route, * - FIB route, q - queued route, r - rejected route - -S>* 0.0.0.0/0 [210/0] via 10.0.0.254, eth0, 00:57:34 -O 10.0.0.0/24 [110/20] via 192.168.0.1, eth1 onlink, 00:13:21 - via 192.168.0.1, eth2 onlink, 00:13:21 -C>* 10.0.0.0/24 is directly connected, eth0, 00:57:35 -O 192.168.0.2/32 [110/0] is directly connected, lo, 00:48:53 -C * 192.168.0.2/32 is directly connected, eth2, 00:56:31 -C * 192.168.0.2/32 is directly connected, eth1, 00:56:31 -C>* 192.168.0.2/32 is directly connected, lo, 00:57:36 -O>* 192.168.0.1/32 [110/1] via 192.168.0.1, eth1 onlink, 00:29:03 - * via 192.168.0.1, eth2 onlink, 00:29:03 -``` diff --git a/docs/configexamples/md-policy-based-ipsec-and-firewall.md b/docs/configexamples/md-policy-based-ipsec-and-firewall.md deleted file mode 100644 index 86bc9318..00000000 --- a/docs/configexamples/md-policy-based-ipsec-and-firewall.md +++ /dev/null @@ -1,269 +0,0 @@ -(examples-policy-based-ipsec-and-firewall)= - -# Policy-Based Site-to-Site VPN and Firewall Configuration - -This guide shows an example policy-based IKEv2 site-to-site VPN between two -VyOS routers, and firewall configuration. - -For simplicity, configuration and tests are done only using IPv4, and firewall -configuration is done only on one router. - -## Network Topology and requirements - -This configuration example and the requirements consists of: - -- Two VyOS routers with public IP address. - -- 2 private subnets on each site. - -- Local subnets should be able to reach internet using source NAT. - -- Communication between private subnets should be done through IPSec tunnel - without NAT. - -- Configuration of basic firewall in one site, in order to: - - > - Protect the router on 'WAN' interface, allowing only IPSec connections - > and SSH access from trusted IPs. - > - Allow access to the router only from trusted networks. - > - Allow DNS requests only only for local networks. - > - Allow ICMP on all interfaces. - > - Allow all new connections from local subnets. - > - Allow connections from LANs to LANs through the tunnel. - -```{image} /_static/images/policy-based-ipsec-and-firewall.webp -``` - - -## Configuration - -Interface and routing configuration: - -```none -# LEFT router: -set interfaces ethernet eth0 address '198.51.100.14/30' -set interfaces ethernet eth1 vif 111 address '10.1.11.1/24' -set interfaces ethernet eth2 vif 112 address '10.1.12.1/24' -set protocols static route 0.0.0.0/0 next-hop 198.51.100.13 - -# RIGHT router: -set interfaces ethernet eth0 address '192.0.2.130/30' -set interfaces ethernet eth1 vif 221 address '10.2.21.1/24' -set interfaces ethernet eth2 vif 222 address '10.2.22.1/24' -``` - -IPSec configuration: - -```none -# LEFT router: -set vpn ipsec authentication psk RIGHT id '198.51.100.14' -set vpn ipsec authentication psk RIGHT id '192.0.2.130' -set vpn ipsec authentication psk RIGHT secret 'p4ssw0rd' -set vpn ipsec esp-group ESP-GROUP mode 'tunnel' -set vpn ipsec esp-group ESP-GROUP proposal 1 encryption 'aes256' -set vpn ipsec esp-group ESP-GROUP proposal 1 hash 'sha256' -set vpn ipsec ike-group IKE-GROUP key-exchange 'ikev2' -set vpn ipsec ike-group IKE-GROUP proposal 1 dh-group '14' -set vpn ipsec ike-group IKE-GROUP proposal 1 encryption 'aes256' -set vpn ipsec ike-group IKE-GROUP proposal 1 hash 'sha256' -set vpn ipsec interface 'eth0' -set vpn ipsec site-to-site peer RIGHT authentication mode 'pre-shared-secret' -set vpn ipsec site-to-site peer RIGHT connection-type 'initiate' -set vpn ipsec site-to-site peer RIGHT default-esp-group 'ESP-GROUP' -set vpn ipsec site-to-site peer RIGHT ike-group 'IKE-GROUP' -set vpn ipsec site-to-site peer RIGHT local-address '198.51.100.14' -set vpn ipsec site-to-site peer RIGHT remote-address '192.0.2.130' -set vpn ipsec site-to-site peer RIGHT tunnel 0 local prefix '10.1.11.0/24' -set vpn ipsec site-to-site peer RIGHT tunnel 0 remote prefix '10.2.21.0/24' -set vpn ipsec site-to-site peer RIGHT tunnel 1 local prefix '10.1.11.0/24' -set vpn ipsec site-to-site peer RIGHT tunnel 1 remote prefix '10.2.22.0/24' -set vpn ipsec site-to-site peer RIGHT tunnel 2 local prefix '10.1.12.0/24' -set vpn ipsec site-to-site peer RIGHT tunnel 2 remote prefix '10.2.21.0/24' -set vpn ipsec site-to-site peer RIGHT tunnel 3 local prefix '10.1.12.0/24' -set vpn ipsec site-to-site peer RIGHT tunnel 3 remote prefix '10.2.22.0/24' - -# RIGHT router: -set vpn ipsec authentication psk LEFT id '192.0.2.130' -set vpn ipsec authentication psk LEFT id '198.51.100.14' -set vpn ipsec authentication psk LEFT secret 'p4ssw0rd' -set vpn ipsec esp-group ESP-GROUP mode 'tunnel' -set vpn ipsec esp-group ESP-GROUP proposal 1 encryption 'aes256' -set vpn ipsec esp-group ESP-GROUP proposal 1 hash 'sha256' -set vpn ipsec ike-group IKE-GROUP key-exchange 'ikev2' -set vpn ipsec ike-group IKE-GROUP proposal 1 dh-group '14' -set vpn ipsec ike-group IKE-GROUP proposal 1 encryption 'aes256' -set vpn ipsec ike-group IKE-GROUP proposal 1 hash 'sha256' -set vpn ipsec interface 'eth0' -set vpn ipsec site-to-site peer LEFT authentication mode 'pre-shared-secret' -set vpn ipsec site-to-site peer LEFT connection-type 'none' -set vpn ipsec site-to-site peer LEFT default-esp-group 'ESP-GROUP' -set vpn ipsec site-to-site peer LEFT ike-group 'IKE-GROUP' -set vpn ipsec site-to-site peer LEFT local-address '192.0.2.130' -set vpn ipsec site-to-site peer LEFT remote-address '198.51.100.14' -set vpn ipsec site-to-site peer LEFT tunnel 0 local prefix '10.2.21.0/24' -set vpn ipsec site-to-site peer LEFT tunnel 0 remote prefix '10.1.11.0/24' -set vpn ipsec site-to-site peer LEFT tunnel 1 local prefix '10.2.22.0/24' -set vpn ipsec site-to-site peer LEFT tunnel 1 remote prefix '10.1.11.0/24' -set vpn ipsec site-to-site peer LEFT tunnel 2 local prefix '10.2.21.0/24' -set vpn ipsec site-to-site peer LEFT tunnel 2 remote prefix '10.1.12.0/24' -set vpn ipsec site-to-site peer LEFT tunnel 3 local prefix '10.2.22.0/24' -set vpn ipsec site-to-site peer LEFT tunnel 3 remote prefix '10.1.12.0/24' -``` - -Firewall Configuration: - -```none -# Firewall Groups: -set firewall group network-group LOCAL-NETS network '10.1.11.0/24' -set firewall group network-group LOCAL-NETS network '10.1.12.0/24' -set firewall group network-group REMOTE-NETS network '10.2.21.0/24' -set firewall group network-group REMOTE-NETS network '10.2.22.0/24' -set firewall group network-group TRUSTED network '198.51.100.125/32' -set firewall group network-group TRUSTED network '203.0.113.0/24' -set firewall group network-group TRUSTED network '10.1.11.0/24' -set firewall group network-group TRUSTED network '192.168.70.0/24' - -# Forward traffic: default drop and only allow what is needed -set firewall ipv4 forward filter default-action 'drop' - -# Forward traffic: global state policies -set firewall ipv4 forward filter rule 1 action 'accept' -set firewall ipv4 forward filter rule 1 state established 'enable' -set firewall ipv4 forward filter rule 1 state related 'enable' -set firewall ipv4 forward filter rule 2 action 'drop' -set firewall ipv4 forward filter rule 2 state invalid 'enable' - -# Forward traffic: Accept all connections from local networks -set firewall ipv4 forward filter rule 10 action 'accept' -set firewall ipv4 forward filter rule 10 source group network-group 'LOCAL-NETS' - -# Forward traffic: accept connections from remote LANs to local LANs -set firewall ipv4 forward filter rule 20 action 'accept' -set firewall ipv4 forward filter rule 20 destination group network-group 'LOCAL-NETS' -set firewall ipv4 forward filter rule 20 source group network-group 'REMOTE-NETS' - -# Input traffic: default drop and only allow what is needed -set firewall ipv4 input filter default-action 'drop' - -# Input traffic: global state policies -set firewall ipv4 input filter rule 1 action 'accept' -set firewall ipv4 input filter rule 1 state established 'enable' -set firewall ipv4 input filter rule 1 state related 'enable' -set firewall ipv4 input filter rule 2 action 'drop' -set firewall ipv4 input filter rule 2 state invalid 'enable' - -# Input traffic: add rules needed for ipsec connection -set firewall ipv4 input filter rule 10 action 'accept' -set firewall ipv4 input filter rule 10 destination port '500,4500' -set firewall ipv4 input filter rule 10 inbound-interface name 'eth0' -set firewall ipv4 input filter rule 10 protocol 'udp' -set firewall ipv4 input filter rule 15 action 'accept' -set firewall ipv4 input filter rule 15 inbound-interface name 'eth0' -set firewall ipv4 input filter rule 15 protocol 'esp' - -# Input traffic: accept ssh connection from trusted ips -set firewall ipv4 input filter rule 20 action 'accept' -set firewall ipv4 input filter rule 20 destination port '22' -set firewall ipv4 input filter rule 20 protocol 'tcp' -set firewall ipv4 input filter rule 20 source group network-group 'TRUSTED' - -# Input traffic: accept dns requests only from local networks. -set firewall ipv4 input filter rule 25 action 'accept' -set firewall ipv4 input filter rule 25 destination port '53' -set firewall ipv4 input filter rule 25 protocol 'udp' -set firewall ipv4 input filter rule 25 source group network-group 'LOCAL-NETS' - -# Input traffic: allow icmp -set firewall ipv4 input filter rule 30 action 'accept' -set firewall ipv4 input filter rule 30 protocol 'icmp' -``` - -And NAT Configuration: - -```none -set nat source rule 10 destination group network-group 'REMOTE-NETS' -set nat source rule 10 exclude -set nat source rule 10 outbound-interface name 'eth0' -set nat source rule 10 source group network-group 'LOCAL-NETS' -set nat source rule 20 outbound-interface name 'eth0' -set nat source rule 20 source group network-group 'LOCAL-NETS' -set nat source rule 20 translation address 'masquerade' -``` - -## Checking through op-mode commands - -After some testing, we can check IPSec status, and counter on every tunnel: - -```none -vyos@LEFT:~$ show vpn ipsec sa -Connection State Uptime Bytes In/Out Packets In/Out Remote address Remote ID Proposal --------------- ------- -------- -------------- ---------------- ---------------- ----------- --------------------------------------- -RIGHT-tunnel-0 up 36m24s 840B/840B 10/10 192.0.2.130 192.0.2.130 AES_CBC_256/HMAC_SHA2_256_128/MODP_2048 -RIGHT-tunnel-1 up 36m33s 588B/588B 7/7 192.0.2.130 192.0.2.130 AES_CBC_256/HMAC_SHA2_256_128/MODP_2048 -RIGHT-tunnel-2 up 35m50s 1K/1K 15/15 192.0.2.130 192.0.2.130 AES_CBC_256/HMAC_SHA2_256_128/MODP_2048 -RIGHT-tunnel-3 up 36m54s 2K/2K 32/32 192.0.2.130 192.0.2.130 AES_CBC_256/HMAC_SHA2_256_128/MODP_2048 -vyos@LEFT:~$ -``` - -Also, we can check firewall counters: - -```none -vyos@LEFT:~$ show firewall -Rulesets Information - ---------------------------------- -IPv4 Firewall "forward filter" - -Rule Action Protocol Packets Bytes Conditions -------- -------- ---------- --------- ------- ------------------------------------------------------ -1 accept all 681 96545 ct state { established, related } accept -2 drop all 0 0 ct state invalid -10 accept all 360 27205 ip saddr @N_LOCAL-NETS accept -20 accept all 8 648 ip daddr @N_LOCAL-NETS ip saddr @N_REMOTE-NETS accept -default drop all - ---------------------------------- -IPv4 Firewall "input filter" - -Rule Action Protocol Packets Bytes Conditions -------- -------- ---------- --------- ------- ---------------------------------------------- -1 accept all 901 123709 ct state { established, related } accept -2 drop all 0 0 ct state invalid -10 accept udp 0 0 udp dport { 500, 4500 } iifname "eth0" accept -15 accept esp 0 0 meta l4proto esp iifname "eth0" accept -20 accept tcp 1 60 tcp dport 22 ip saddr @N_TRUSTED accept -25 accept udp 0 0 udp dport 53 ip saddr @N_LOCAL-NETS accept -30 accept icmp 0 0 meta l4proto icmp accept -default drop all - -vyos@LEFT:~$ -vyos@LEFT:~$ show firewall statistics -Rulesets Statistics - ---------------------------------- -IPv4 Firewall "forward filter" - -Rule Packets Bytes Action Source Destination Inbound-Interface Outbound-interface -------- --------- ------- -------- ----------- ------------- ------------------- -------------------- -1 681 96545 accept any any any any -2 0 0 drop any any any any -10 360 27205 accept LOCAL-NETS any any any -20 8 648 accept REMOTE-NETS LOCAL-NETS any any -default N/A N/A drop any any any any - ---------------------------------- -IPv4 Firewall "input filter" - -Rule Packets Bytes Action Source Destination Inbound-Interface Outbound-interface -------- --------- ------- -------- ---------- ------------- ------------------- -------------------- -1 905 124213 accept any any any any -2 0 0 drop any any any any -10 0 0 accept any any eth0 any -15 0 0 accept any any eth0 any -20 1 60 accept TRUSTED any any any -25 0 0 accept LOCAL-NETS any any any -30 0 0 accept any any any any -default N/A N/A drop any any any any - -vyos@LEFT:~$ -``` diff --git a/docs/configexamples/md-pppoe-ipv6-basic.md b/docs/configexamples/md-pppoe-ipv6-basic.md deleted file mode 100644 index 76984f4b..00000000 --- a/docs/configexamples/md-pppoe-ipv6-basic.md +++ /dev/null @@ -1,114 +0,0 @@ ---- -lastproofread: '2021-06-29' ---- - -(examples-pppoe-ipv6-basic)= - -# PPPoE IPv6 Basic Setup for Home Network - -This document is to describe a basic setup using PPPoE with DHCPv6-PD + -SLAAC to construct a typical home network. The user can follow the steps -described here to quickly setup a working network and use this as a starting -point to further configure or fine-tune other settings. - -To achieve this, your ISP is required to support DHCPv6-PD. If you're not sure, -please contact your ISP for more information. - -## Network Topology - -```{image} /_static/images/pppoe-ipv6-pd-diagram.webp -:align: center -:alt: Network Topology Diagram -:width: 60% -``` - - -## Configurations - -### PPPoE Setup - -```none -set interfaces pppoe pppoe0 authentication password -set interfaces pppoe pppoe0 authentication username -set interfaces pppoe pppoe0 service-name -set interfaces pppoe pppoe0 source-interface 'eth0' -``` - -- Fill `password` and `user` with the credential provided by your ISP. -- `service-name` can be an arbitrary string. - -### DHCPv6-PD Setup - -During address configuration, in addition to assigning an address to the WAN -interface, ISP also provides a prefix to allow the router to configure addresses -of LAN interface and other nodes connecting to LAN, which is called prefix -delegation (PD). - -```none -set interfaces pppoe pppoe0 ipv6 address autoconf -set interfaces pppoe pppoe0 dhcpv6-options pd 0 interface eth1 address '100' -``` - -- Here we use the prefix to configure the address of eth1 (LAN) to form - `::64`, where `64` is hexadecimal of address 100. - - - -- For home network users, most of time ISP only provides /64 prefix, hence - there is no need to set SLA ID and prefix length. See {ref}`pppoe-interface` - for more information. - -### Router Advertisement - -We need to enable router advertisement for LAN network so that PC can receive -the prefix and use SLAAC to configure the address automatically. - -```none -set service router-advert interface eth1 link-mtu '1492' -set service router-advert interface eth1 name-server -set service router-advert interface eth1 prefix ::/64 valid-lifetime '172800' -``` - -- Set MTU in advertisement to 1492 because of PPPoE header overhead. -- Set DNS server address in the advertisement so that clients can obtain it by - using RDNSS option. Most operating systems (Windows, Linux, Mac) should - already support it. -- Here we set the prefix to `::/64` to indicate advertising any /64 prefix - the LAN interface is assigned. -- Since some ISPs disconnects continuous connection for every 2~3 days, we set - `valid-lifetime` to 2 days to allow PC for phasing out old address. - -### Basic Firewall - -To have basic protection while keeping IPv6 network functional, we need to: -- Allow all established and related traffic for router and LAN -- Allow all icmpv6 packets for router and LAN -- Allow DHCPv6 packets for router - -```none -set firewall ipv6 name WAN_IN default-action 'drop' -set firewall ipv6 name WAN_IN rule 10 action 'accept' -set firewall ipv6 name WAN_IN rule 10 state established 'enable' -set firewall ipv6 name WAN_IN rule 10 state related 'enable' -set firewall ipv6 name WAN_IN rule 20 action 'accept' -set firewall ipv6 name WAN_IN rule 20 protocol 'icmpv6' -set firewall ipv6 name WAN_LOCAL default-action 'drop' -set firewall ipv6 name WAN_LOCAL rule 10 action 'accept' -set firewall ipv6 name WAN_LOCAL rule 10 state established 'enable' -set firewall ipv6 name WAN_LOCAL rule 10 state related 'enable' -set firewall ipv6 name WAN_LOCAL rule 20 action 'accept' -set firewall ipv6 name WAN_LOCAL rule 20 protocol 'icmpv6' -set firewall ipv6 name WAN_LOCAL rule 30 action 'accept' -set firewall ipv6 name WAN_LOCAL rule 30 destination port '546' -set firewall ipv6 name WAN_LOCAL rule 30 protocol 'udp' -set firewall ipv6 name WAN_LOCAL rule 30 source port '547' -set firewall ipv6 forward filter rule 10 action jump -set firewall ipv6 forward filter rule 10 jump-target 'WAN_IN' -set firewall ipv6 forward filter rule 10 inbound-interface name 'pppoe0' -set firewall ipv6 input filter rule 10 action jump -set firewall ipv6 input filter rule 10 jump-target 'WAN_LOCAL' -set firewall ipv6 input filter rule 10 inbound-interface name 'pppoe0' -``` - -Note to allow the router to receive DHCPv6 response from ISP. We need to allow -packets with source port 547 (server) and destination port 546 (client). diff --git a/docs/configexamples/md-qos.md b/docs/configexamples/md-qos.md deleted file mode 100644 index e8335584..00000000 --- a/docs/configexamples/md-qos.md +++ /dev/null @@ -1,201 +0,0 @@ ---- -lastproofread: '2023-02-18' ---- - -(examples-qos)= - -# QoS example - -## Configuration 'dcsp' and shaper using QoS - -In this case, we'll try to make a simple lab using QoS and the -general ability of the VyOS system. -We recommend you to go through the main article about -[QoS](https://docs.vyos.io/en/latest/configuration/trafficpolicy/index.html) -first. - -Using the general schema for example: - -```{image} /_static/images/qos1.webp -:align: center -:alt: Network Topology Diagram -:width: 80% -``` - -We have four hosts on the local network 172.17.1.0/24. All hosts are -labeled CS0 by default. We need to replace labels on all hosts except -vpc8. -We will replace the labels on the nearest router “VyOS3” using the IP -addresses of the sources. - -- 172.17.1.2 CS0 -> CS4 -- 172.17.1.3 CS0 -> CS5 -- 172.17.1.4 CS0 -> CS6 -- 172.17.1.40 CS0 by default - -Next, we will replace only all CS4 labels on the “VyOS2” router. - -- CS4 -> CS5 - -In the end, we will configure the traffic shaper using QoS mechanisms -on the “VYOS2” router. - -## Configuration: - -Set IP addresses on all VPCs and a default gateway 172.17.1.1. We'll -use in this case only static routes. -On the VyOS3 router, we need to change the 'dscp' labels for the -VPCs. To do this, we use this configuration. - -```none -set interfaces ethernet eth0 address '10.1.1.100/24' -set interfaces ethernet eth1 address '172.17.1.1/24' -set protocols static route 0.0.0.0/0 next-hop 10.1.1.1 -set qos policy shaper vyos3 class 10 match ADDRESS10 ip source address '172.17.1.2/32' -set qos policy shaper vyos3 class 10 set-dscp 'CS4' -set qos policy shaper vyos3 class 20 match ADDRESS20 ip source address '172.17.1.3/32' -set qos policy shaper vyos3 class 20 set-dscp 'CS5' -set qos policy shaper vyos3 class 30 match ADDRESS30 ip source address '172.17.1.4/32' -set qos policy shaper vyos3 class 30 set-dscp 'CS6' -set qos policy shaper vyos3 default bandwidth '10%' -set qos policy shaper vyos3 default ceiling '100%' -set qos policy shaper vyos3 default priority '7' -set qos policy shaper vyos3 default queue-type 'fair-queue' -set qos interface eth0 egress 'vyos3' -``` - -Main rules: - -- ADDRESS10 change CS0 -> CS4 source 172.17.1.2/32 -- ADDRESS20 change CS0 -> CS5 source 172.17.1.3/32 -- ADDRESS30 change CS0 -> CS6 source 172.17.1.4/32 - -Check the result - -```{image} /_static/images/qos2.webp -:align: center -:alt: Network Topology Diagram -:width: 80% -``` - -Before the interface eth0 on router VyOS3 - -```{image} /_static/images/qos3.webp -:align: center -:alt: Network Topology Diagram -:width: 80% -``` - -After the interface eth0 on router VyOS3 - -```{image} /_static/images/qos4.webp -:align: center -:alt: Network Topology Diagram -:width: 80% -``` - -On the router, VyOS4 set all traffic as CS4. We have to configure the -default class and class for changing all labels from CS0 to CS4 - -```none -set interfaces ethernet eth0 address '10.2.1.100/24' -set protocols static route 0.0.0.0/0 next-hop 10.2.1.1 -set qos policy shaper vyos4 class 10 bandwidth '100%' -set qos policy shaper vyos4 class 10 burst '15k' -set qos policy shaper vyos4 class 10 match ALL ether protocol 'all' -set qos policy shaper vyos4 class 10 queue-type 'fair-queue' -set qos policy shaper vyos4 class 10 set-dscp 'CS4' -set qos policy shaper vyos4 default bandwidth '10%' -set qos policy shaper vyos4 default burst '15k' -set qos policy shaper vyos4 default ceiling '100%' -set qos policy shaper vyos4 default priority '7' -set qos policy shaper vyos4 default queue-type 'fair-queue' - set qos interface eth0 egress 'vyos4' -``` - -Next on the router VyOS2 we will change labels on all incoming -traffic only from CS4-> CS6 - -```{image} /_static/images/qos5.webp -:align: center -:alt: Network Topology Diagram -:width: 80% -``` - -```none -set interfaces ethernet eth0 address '10.1.1.1/24' -set interfaces ethernet eth1 address '10.2.1.1/24' -set interfaces ethernet eth2 address '10.9.9.1/24' -set protocols static route 172.17.1.0/24 next-hop 10.1.1.100 -set qos policy shaper vyos2 class 10 bandwidth '100%' -set qos policy shaper vyos2 class 10 burst '15k' -set qos policy shaper vyos2 class 10 match VYOS2 ip dscp 'CS4' -set qos policy shaper vyos2 class 10 queue-type 'fair-queue' -set qos policy shaper vyos2 class 10 set-dscp 'CS5' -set qos policy shaper vyos2 default bandwidth '100%' -set qos policy shaper vyos2 default burst '15k' -set qos policy shaper vyos2 default ceiling '100%' -set qos policy shaper vyos2 default priority '7' -set qos policy shaper vyos2 default queue-type 'fair-queue' - set qos interface eth2 egress 'vyos2' -``` - -```{image} /_static/images/qos6.webp -:align: center -:alt: Network Topology Diagram -:width: 80% -``` - -- 172.17.1.2/24 CS0 - -```{image} /_static/images/qos7.webp -:align: center -:alt: Network Topology Diagram -:width: 80% -``` - -- 172.17.1.2/24 CS0 - > CS4 - -```{image} /_static/images/qos8.webp -:align: center -:alt: Network Topology Diagram -:width: 80% -``` - -- 172.17.1.2/24 CS4 - > CS5 - -```{image} /_static/images/qos9.webp -:align: center -:alt: Network Topology Diagram -:width: 80% -``` - -In the end, on the router “VyOS2” we will set outgoing bandwidth -limits between the “VyOS3” and “VyOS1” routers. Let's set a limit for -IP 10.1.1.100 = 5 Mbps(Tx). We will check the result of the work -with the help of the “iPerf” utility. - -Set up bandwidth limits on the eth2 interface of the router “VyOS2”. - -```none -vyos@vyos2# show qos policy shaper vyos2 class 20 -bandwidth 5mbit -description "for VyOS3 eth0" -match VyOS3 { - ip { - source { - address 10.1.1.100/32 - } - } -} -``` - -Check the result. - -```{image} /_static/images/qos10.webp -:align: center -:alt: Network Topology Diagram -:width: 80% -``` - -As we see shaper is working and the traffic will not work over 5 Mbit/s. diff --git a/docs/configexamples/md-segment-routing-isis.md b/docs/configexamples/md-segment-routing-isis.md deleted file mode 100644 index 41ba2389..00000000 --- a/docs/configexamples/md-segment-routing-isis.md +++ /dev/null @@ -1,277 +0,0 @@ ---- -lastproofread: '2023-04-10' ---- - -(examples-segment-routing-isis)= - -# Segment-routing IS-IS example - -When utilizing VyOS in an environment with Cisco IOS-XR gear you can use this -blue print as an initial setup to get MPLS ISIS-SR working between those two -devices.The lab was build using {abbr}`EVE-NG (Emulated Virtual -Environment NG)`. - -:::{figure} /_static/images/vyos-sr-isis.webp -:alt: ISIS-SR network - -ISIS-SR example network -::: - -The below configuration is used as example where we keep focus on -VyOS-P1/VyOS-P2/XRv-P3 which we share the settings. - -## Configuration - -- VyOS-P1: - -```none -set interfaces dummy dum0 address '192.0.2.1/32' -set interfaces ethernet eth1 address '192.0.2.5/30' -set interfaces ethernet eth1 mtu '8000' -set interfaces ethernet eth3 address '192.0.2.21/30' -set interfaces ethernet eth3 mtu '8000' -set protocols isis interface dum0 passive -set protocols isis interface eth1 network point-to-point -set protocols isis interface eth3 network point-to-point -set protocols isis level 'level-2' -set protocols isis log-adjacency-changes -set protocols isis metric-style 'wide' -set protocols isis net '49.0000.0000.0000.0001.00' -set protocols isis segment-routing maximum-label-depth '8' -set protocols isis segment-routing prefix 192.0.2.1/32 index value '1' -set protocols mpls interface 'eth1' -set protocols mpls interface 'eth3' -set system host-name 'P1-VyOS' -``` - -- XRv-P3: - -```none -hostname P3-VyOS -interface Loopback0 - ipv4 address 192.0.2.3 255.255.255.255 -! -interface GigabitEthernet0/0/0/1 - mtu 8014 - ipv4 address 192.0.2.6 255.255.255.252 -! -interface GigabitEthernet0/0/0/2 - mtu 8014 - ipv4 address 192.0.2.18 255.255.255.252 -! -router isis VyOS - is-type level-2-only - net 49.0000.0000.0000.0003.00 - log adjacency changes - address-family ipv4 unicast - metric-style wide - segment-routing mpls - ! - interface Loopback0 - passive - address-family ipv4 unicast - prefix-sid index 3 - ! - ! - interface GigabitEthernet0/0/0/1 - point-to-point - address-family ipv4 unicast - ! - ! - interface GigabitEthernet0/0/0/2 - point-to-point - address-family ipv4 unicast - ! - ! -! -``` - -- VyOS-P2: - -```none -set interfaces dummy dum0 address '192.0.2.2/32' -set interfaces ethernet eth2 address '192.0.2.17/30' -set interfaces ethernet eth2 mtu '8000' -set interfaces ethernet eth3 address '192.0.2.26/30' -set interfaces ethernet eth3 mtu '8000' -set protocols isis interface dum0 passive -set protocols isis interface eth2 network point-to-point -set protocols isis interface eth3 network point-to-point -set protocols isis level 'level-2' -set protocols isis log-adjacency-changes -set protocols isis metric-style 'wide' -set protocols isis net '49.0000.0000.0000.0002.00' -set protocols isis segment-routing maximum-label-depth '8' -set protocols isis segment-routing prefix 192.0.2.2/32 index value '2' -set protocols mpls interface 'eth2' -set protocols mpls interface 'eth3' -set system host-name 'P2-VyOS' -``` - -This gives us MPLS segment routing enabled and labels forwarding : - -```none -vyos@P1-VyOS:~$ show mpls table -Inbound Label Type Nexthop Outbound Label ------------------------------------------------------------------ -15000 SR (IS-IS) 192.0.2.6 implicit-null -15001 SR (IS-IS) 192.0.2.22 implicit-null -15002 SR (IS-IS) fe80::5200:ff:fe04:3 implicit-null -16002 SR (IS-IS) 192.0.2.6 16002 -16003 SR (IS-IS) 192.0.2.6 implicit-null -16011 SR (IS-IS) 192.0.2.22 implicit-null - -vyos@P2-VyOS:~$ show mpls table -Inbound Label Type Nexthop Outbound Label -------------------------------------------------------- -15000 SR (IS-IS) 192.0.2.18 implicit-null -16001 SR (IS-IS) 192.0.2.18 16001 -16003 SR (IS-IS) 192.0.2.18 implicit-null -16011 SR (IS-IS) 192.0.2.18 16011 - -RP/0/0/CPU0:P3-VyOS#show mpls forwarding -Tue Mar 28 17:47:18.928 UTC -Local Outgoing Prefix Outgoing Next Hop Bytes -Label Label or ID Interface Switched ------- ----------- ------------------ ------------ --------------- ------------ -16001 Pop SR Pfx (idx 1) Gi0/0/0/1 192.0.2.5 0 -16002 Pop SR Pfx (idx 2) Gi0/0/0/2 192.0.2.17 0 -16011 16011 SR Pfx (idx 11) Gi0/0/0/1 192.0.2.5 0 -24000 Pop SR Adj (idx 1) Gi0/0/0/1 192.0.2.5 0 -24001 Pop SR Adj (idx 3) Gi0/0/0/1 192.0.2.5 0 -24002 Pop SR Adj (idx 1) Gi0/0/0/2 192.0.2.17 0 -24003 Pop SR Adj (idx 3) Gi0/0/0/2 192.0.2.17 0 -``` - -VyOS is able to check MSD per devices: - -```none -vyos@P1-VyOS:~$ show isis segment-routing node -Area VyOS: -IS-IS L1 SR-Nodes: - -IS-IS L2 SR-Nodes: - -System ID SRGB SRLB Algorithm MSD ---------------------------------------------------------------- -0000.0000.0001 16000 - 23999 15000 - 15999 SPF 8 -0000.0000.0002 16000 - 23999 15000 - 15999 SPF 8 -0000.0000.0003 16000 - 23999 0 - 4294967295 SPF 10 -0000.0000.0011 16000 - 23999 15000 - 15999 SPF 8 - -vyos@P2-VyOS:~$ show isis segment-routing node -Area VyOS: - IS-IS L1 SR-Nodes: - - IS-IS L2 SR-Nodes: - - System ID SRGB SRLB Algorithm MSD - --------------------------------------------------------------- - 0000.0000.0001 16000 - 23999 15000 - 15999 SPF 8 - 0000.0000.0002 16000 - 23999 15000 - 15999 SPF 8 - 0000.0000.0003 16000 - 23999 0 - 4294967295 SPF 10 - 0000.0000.0011 16000 - 23999 15000 - 15999 SPF 8 -``` - -Here is the routing tables showing the MPLS segment routing label operations: - -```none -vyos@P1-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.2/32 [115/30] via 192.0.2.6, eth1, label 16002, weight 1, 1d03h18m -I>* 192.0.2.3/32 [115/10] via 192.0.2.6, eth1, label implicit-null, weight 1, 1d03h18m -I 192.0.2.4/30 [115/20] via 192.0.2.6, eth1 inactive, weight 1, 1d03h18m -I>* 192.0.2.11/32 [115/20] via 192.0.2.22, eth3, label implicit-null, weight 1, 1d02h47m -I>* 192.0.2.16/30 [115/20] via 192.0.2.6, eth1, weight 1, 1d03h18m -I 192.0.2.20/30 [115/20] via 192.0.2.22, eth3 inactive, weight 1, 1d02h48m -I>* 192.0.2.24/30 [115/30] via 192.0.2.6, eth1, weight 1, 1d03h18m - - -vyos@P2-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.1/32 [115/30] via 192.0.2.18, eth2, label 16001, weight 1, 1d03h17m -I>* 192.0.2.3/32 [115/10] via 192.0.2.18, eth2, label implicit-null, weight 1, 1d03h17m -I>* 192.0.2.4/30 [115/20] via 192.0.2.18, eth2, weight 1, 1d03h17m -I>* 192.0.2.11/32 [115/40] via 192.0.2.18, eth2, label 16011, weight 1, 1d02h47m -I 192.0.2.16/30 [115/20] via 192.0.2.18, eth2 inactive, weight 1, 1d03h17m -I>* 192.0.2.20/30 [115/30] via 192.0.2.18, eth2, weight 1, 1d03h17m - -RP/0/0/CPU0:P3-VyOS#show route isis -Tue Mar 28 18:19:16.417 UTC - -i L2 192.0.2.1/32 [115/20] via 192.0.2.5, 1d03h, GigabitEthernet0/0/0/1 -i L2 192.0.2.2/32 [115/20] via 192.0.2.17, 1d03h, GigabitEthernet0/0/0/2 -i L2 192.0.2.11/32 [115/30] via 192.0.2.5, 1d02h, GigabitEthernet0/0/0/1 -i L2 192.0.2.20/30 [115/20] via 192.0.2.5, 1d03h, GigabitEthernet0/0/0/1 -i L2 192.0.2.24/30 [115/20] via 192.0.2.17, 1d03h, GigabitEthernet0/0/0/2 -``` - -Information about prefix-sid and label-operation from VyOS - -```none -vyos@P1-VyOS:~$ show isis route prefix-sid -Area VyOS: -IS-IS L2 IPv4 routing table: - - Prefix Metric Interface Nexthop SID Label Op. - ---------------------------------------------------------------------- - 192.0.2.1/32 0 - - - - - 192.0.2.2/32 30 eth1 192.0.2.6 2 Swap(16002, 16002) - 192.0.2.3/32 10 eth1 192.0.2.6 3 Pop(16003) - 192.0.2.4/30 20 eth1 192.0.2.6 - - - 192.0.2.16/30 20 eth1 192.0.2.6 - - - 192.0.2.20/30 0 - - - - - 192.0.2.24/30 30 eth1 192.0.2.6 - - - - vyos@P2-VyOS:~$ show isis route prefix-sid - Area VyOS: - IS-IS L2 IPv4 routing table: - - Prefix Metric Interface Nexthop SID Label Op. - ----------------------------------------------------------------------- - 192.0.2.1/32 30 eth2 192.0.2.18 1 Swap(16001, 16001) - 192.0.2.2/32 0 - - - - - 192.0.2.3/32 10 eth2 192.0.2.18 3 Pop(16003) - 192.0.2.4/30 20 eth2 192.0.2.18 - - - 192.0.2.16/30 20 eth2 192.0.2.18 - - - 192.0.2.20/30 30 eth2 192.0.2.18 - - - 192.0.2.24/30 0 - - - - -``` - -Ping between VyOS-P1 / VyOS-P2 to confirm reachability: - -```none -vyos@P1-VyOS:~$ ping 192.0.2.2 source-address 192.0.2.1 -PING 192.0.2.2 (192.0.2.2) from 192.0.2.1 : 56(84) bytes of data. -64 bytes from 192.0.2.2: icmp_seq=1 ttl=63 time=3.47 ms -64 bytes from 192.0.2.2: icmp_seq=2 ttl=63 time=2.06 ms -64 bytes from 192.0.2.2: icmp_seq=3 ttl=63 time=3.90 ms -64 bytes from 192.0.2.2: icmp_seq=4 ttl=63 time=3.87 ms -^C ---- 192.0.2.2 ping statistics --- -4 packets transmitted, 4 received, 0% packet loss, time 3004ms -rtt min/avg/max/mdev = 2.064/3.326/3.903/0.748 ms - -vyos@P2-VyOS:~$ ping 192.0.2.1 source-address 192.0.2.2 -PING 192.0.2.1 (192.0.2.1) from 192.0.2.2 : 56(84) bytes of data. -64 bytes from 192.0.2.1: icmp_seq=1 ttl=63 time=2.91 ms -64 bytes from 192.0.2.1: icmp_seq=2 ttl=63 time=3.23 ms -64 bytes from 192.0.2.1: icmp_seq=3 ttl=63 time=2.91 ms -64 bytes from 192.0.2.1: icmp_seq=4 ttl=63 time=2.85 ms -^C ---- 192.0.2.1 ping statistics --- -4 packets transmitted, 4 received, 0% packet loss, time 3005ms -rtt min/avg/max/mdev = 2.846/2.972/3.231/0.151 ms -``` diff --git a/docs/configexamples/md-site-2-site-cisco.md b/docs/configexamples/md-site-2-site-cisco.md deleted file mode 100644 index d8ca2c18..00000000 --- a/docs/configexamples/md-site-2-site-cisco.md +++ /dev/null @@ -1,170 +0,0 @@ -(examples-site-2-site-cisco)= - -# Site-to-Site IPSec VPN to Cisco using FlexVPN - -This guide shows a sample configuration for FlexVPN site-to-site Internet -Protocol Security (IPsec)/Generic Routing Encapsulation (GRE) tunnel. - -FlexVPN is a newer "solution" for deployment of VPNs and it utilizes IKEv2 as -the key exchange protocol. The result is a flexible and scalable VPN solution -that can be easily adapted to fit various network needs. It can also support a -variety of encryption methods, including AES and 3DES. - -The lab was built using EVE-NG. - -## Configuration - -### VyOS - -- GRE: - -```none -set interfaces tunnel tun1 encapsulation 'gre' -set interfaces tunnel tun1 ip adjust-mss '1336' -set interfaces tunnel tun1 mtu '1376' -set interfaces tunnel tun1 remote '10.1.1.6' -set interfaces tunnel tun1 source-address '198.51.100.1' -``` - -- IPsec: - -```none -set vpn ipsec authentication psk vyos_cisco_l id 'vyos.net' -set vpn ipsec authentication psk vyos_cisco_l id 'cisco.hub.net' -set vpn ipsec authentication psk vyos_cisco_l secret 'secret' -set vpn ipsec esp-group e1 lifetime '3600' -set vpn ipsec esp-group e1 mode 'tunnel' -set vpn ipsec esp-group e1 pfs 'disable' -set vpn ipsec esp-group e1 proposal 1 encryption 'aes128' -set vpn ipsec esp-group e1 proposal 1 hash 'sha256' -set vpn ipsec ike-group i1 key-exchange 'ikev2' -set vpn ipsec ike-group i1 lifetime '28800' -set vpn ipsec ike-group i1 proposal 1 dh-group '5' -set vpn ipsec ike-group i1 proposal 1 encryption 'aes256' -set vpn ipsec ike-group i1 proposal 1 hash 'sha256' -set vpn ipsec interface 'eth2' -set vpn ipsec options disable-route-autoinstall -set vpn ipsec options flexvpn -set vpn ipsec options interface 'tun1' -set vpn ipsec options virtual-ip -set vpn ipsec site-to-site peer cisco_hub authentication local-id 'vyos.net' -set vpn ipsec site-to-site peer cisco_hub authentication mode 'pre-shared-secret' -set vpn ipsec site-to-site peer cisco_hub authentication remote-id 'cisco.hub.net' -set vpn ipsec site-to-site peer cisco_hub connection-type 'initiate' -set vpn ipsec site-to-site peer cisco_hub default-esp-group 'e1' -set vpn ipsec site-to-site peer cisco_hub ike-group 'i1' -set vpn ipsec site-to-site peer cisco_hub local-address '198.51.100.1' -set vpn ipsec site-to-site peer cisco_hub remote-address '10.1.1.6' -set vpn ipsec site-to-site peer cisco_hub tunnel 1 local prefix '198.51.100.1/32' -set vpn ipsec site-to-site peer cisco_hub tunnel 1 protocol 'gre' -set vpn ipsec site-to-site peer cisco_hub tunnel 1 remote prefix '10.1.1.6/32' -set vpn ipsec site-to-site peer cisco_hub virtual-address '0.0.0.0' -``` - - -### Cisco - -```none -aaa new-model -! -! -aaa authorization network default local -! -crypto ikev2 name-mangler GET_DOMAIN - fqdn all - email all -! -! -crypto ikev2 authorization policy vyos - pool mypool - aaa attribute list mylist - route set interface - route accept any tag 100 distance 5 -! -crypto ikev2 keyring mykeys - peer peer1 - identity fqdn vyos.net - pre-shared-key local secret - pre-shared-key remote secret -crypto ikev2 profile my_profile - match identity remote fqdn vyos.net - identity local fqdn cisco.hub.net - authentication remote pre-share - authentication local pre-share - keyring local mykeys - dpd 10 3 periodic - aaa authorization group psk list local name-mangler GET_DOMAIN - aaa authorization user psk cached - virtual-template 1 -! -! -! -crypto ipsec transform-set TSET esp-aes esp-sha256-hmac - mode tunnel -! -! -crypto ipsec profile my-ipsec-profile - set transform-set TSET - set ikev2-profile my_profile -! -interface Virtual-Template1 type tunnel - no ip address - ip mtu 1376 - ip nhrp network-id 1 - ip nhrp shortcut virtual-template 1 - ip tcp adjust-mss 1336 - tunnel path-mtu-discovery - tunnel protection ipsec profile my-ipsec-profile - ! - ip local pool my_pool 172.16.122.1 172.16.122.254 -``` - -Since the tunnel is a point-to-point GRE tunnel, it behaves like any other -point-to-point interface (for example: serial, dialer), and it is possible to -run any Interior Gateway Protocol (IGP)/Exterior Gateway Protocol (EGP) over -the link in order to exchange routing information - -## Verification - -```none -vyos@vyos$ show interfaces -Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down -Interface IP Address S/L Description ---------- ---------- --- ----------- -eth0 - u/u -eth1 - u/u -eth2 198.51.100.1/24 u/u -eth3 172.16.1.2/24 u/u -lo 127.0.0.1/8 u/u - ::1/128 -tun1 172.16.122.2/32 u/u - -vyos@vyos:~$ show vpn ipsec sa -Connection State Uptime Bytes In/Out Packets In/Out Remote address Remote ID Proposal ------------------- ------- -------- -------------- ---------------- ---------------- --------------------- ----------------------------- -cisco_hub-tunnel-1 up 44m17s 35K/31K 382/367 10.1.1.6 cisco.hub.net AES_CBC_128/HMAC_SHA2_256_128 - - -Hub#sh crypto ikev2 sa detailed - IPv4 Crypto IKEv2 SA - -Tunnel-id Local Remote fvrf/ivrf Status -5 10.1.1.6/4500 198.51.100.1/4500 none/none READY - Encr: AES-CBC, keysize: 256, PRF: SHA256, Hash: SHA256, DH Grp:5, Auth sign: PSK, Auth verify: PSK - Life/Active Time: 86400/2694 sec - CE id: 0, Session-id: 2 - Status Description: Negotiation done - Local spi: C94EE2DC92A60C47 Remote spi: 9AF0EF151BECF14C - Local id: cisco.hub.net - Remote id: vyos.net - Local req msg id: 269 Remote req msg id: 0 - Local next msg id: 269 Remote next msg id: 0 - Local req queued: 269 Remote req queued: 0 - Local window: 5 Remote window: 1 - DPD configured for 10 seconds, retry 3 - Fragmentation not configured. - Extended Authentication not configured. - NAT-T is not detected - Cisco Trust Security SGT is disabled - Assigned host addr: 172.16.122.2 -``` diff --git a/docs/configexamples/md-wan-load-balancing.md b/docs/configexamples/md-wan-load-balancing.md deleted file mode 100644 index b9357523..00000000 --- a/docs/configexamples/md-wan-load-balancing.md +++ /dev/null @@ -1,183 +0,0 @@ ---- -lastproofread: '2021-06-29' ---- - -(wan-load-balancing)= - - -# WAN Load Balancer examples - -% stop_vyoslinter - -## Example 1: Distributing load evenly - -The setup used in this example is shown in the following diagram: - -```{image} /_static/images/Wan_load_balancing1.webp -:align: center -:alt: Network Topology Diagram -:width: 80% -``` - - -### Overview - -> - All traffic coming in through eth2 is balanced between eth0 and eth1 -> on the router. -> - Pings will be sent to four targets for health testing (33.44.55.66, -> 44.55.66.77, 55.66.77.88 and 66.77.88.99). -> - All outgoing packets are assigned the source address of the assigned -> interface (SNAT). -> - eth0 is set to be removed from the load balancer's interface pool -> after 5 ping failures, eth1 will be removed after 4 ping failures. - -### Create static routes to ping targets - -Create static routes through the two ISPs towards the ping targets and -commit the changes: - -```none -set protocols static route 33.44.55.66/32 next-hop 11.22.33.1 -set protocols static route 44.55.66.77/32 next-hop 11.22.33.1 -set protocols static route 55.66.77.88/32 next-hop 22.33.44.1 -set protocols static route 66.77.88.99/32 next-hop 22.33.44.1 -``` - - -### Configure the load balancer - -Configure the WAN load balancer with the parameters described above: - -```none -set load-balancing wan interface-health eth0 failure-count 5 -set load-balancing wan interface-health eth0 nexthop 11.22.33.1 -set load-balancing wan interface-health eth0 test 10 type ping -set load-balancing wan interface-health eth0 test 10 target 33.44.55.66 -set load-balancing wan interface-health eth0 test 20 type ping -set load-balancing wan interface-health eth0 test 20 target 44.55.66.77 -set load-balancing wan interface-health eth1 failure-count 4 -set load-balancing wan interface-health eth1 nexthop 22.33.44.1 -set load-balancing wan interface-health eth1 test 10 type ping -set load-balancing wan interface-health eth1 test 10 target 55.66.77.88 -set load-balancing wan interface-health eth1 test 20 type ping -set load-balancing wan interface-health eth1 test 20 target 66.77.88.99 -set load-balancing wan rule 10 inbound-interface eth2 -set load-balancing wan rule 10 interface eth0 -set load-balancing wan rule 10 interface eth1 -``` - - -## Example 2: Failover based on interface weights - -This example uses the failover mode. -(wan-example2-overview)= - -### Overview - -In this example, eth0 is the primary interface and eth1 is the secondary -interface. To provide simple failover functionality. If eth0 fails, eth1 -takes over. - -### Create interface weight based configuration - -The configuration steps are the same as in the previous example, except -rule 10. So we keep the configuration, remove rule 10 and add a new rule -for the failover mode: - -```none -delete load-balancing wan rule 10 -set load-balancing wan rule 10 failover -set load-balancing wan rule 10 inbound-interface eth2 -set load-balancing wan rule 10 interface eth0 weight 10 -set load-balancing wan rule 10 interface eth1 weight 1 -``` - - -## Example 3: Failover based on rule order - -The previous example used the failover command to send traffic through -eth1 if eth0 fails. In this example, failover functionality is provided -by rule order. -(wan-example3-overview)= - -### Overview - -Two rules will be created, the first rule directs traffic coming in -from eth2 to eth0 and the second rule directs the traffic to eth1. If -eth0 fails the first rule is bypassed and the second rule matches, -directing traffic to eth1. - -### Create rule order based configuration - -We keep the configuration from the previous example, delete rule 10 -and create the two new rules as described: - -```none -delete load-balancing wan rule 10 -set load-balancing wan rule 10 inbound-interface eth2 -set load-balancing wan rule 10 interface eth0 -set load-balancing wan rule 20 inbound-interface eth2 -set load-balancing wan rule 20 interface eth1 -``` - - -## Example 4: Failover based on rule order - priority traffic - -A rule order for prioritizing traffic is useful in scenarios where the -secondary link has a lower speed and should only carry high priority -traffic. It is assumed for this example that eth1 is connected to a -slower connection than eth0 and should prioritize VoIP traffic. -(wan-example4-overview)= - -### Overview - -A rule order for prioritizing traffic is useful in scenarios where the -secondary link has a lower speed and should only carry high priority -traffic. It is assumed for this example that eth1 is connected to a -slower connection than eth0 and should prioritize VoIP traffic. - -### Create rule order based configuration with low speed secondary link - -We keep the configuration from the previous example, delete rule 20 and -create a new rule as described: - -```none -delete load-balancing wan rule 20 -set load-balancing wan rule 20 inbound-interface eth2 -set load-balancing wan rule 20 interface eth1 -set load-balancing wan rule 20 destination port sip -set load-balancing wan rule 20 protocol tcp -set protocols static route 0.0.0.0/0 next-hop 11.22.33.1 -``` - - -## Example 5: Exclude traffic from load balancing - -In this example two LAN interfaces exist in different subnets instead -of one like in the previous examples: - -```{image} /_static/images/Wan_load_balancing_exclude1.webp -:align: center -:alt: Network Topology Diagram -:width: 80% -``` - - -### Adding a rule for the second interface - -Based on the previous example, another rule for traffic from the second -interface eth3 can be added to the load balancer. However, traffic meant -to flow between the LAN subnets will be sent to eth0 and eth1 as well. -To prevent this, another rule is required. This rule excludes traffic -between the local subnets from the load balancer. It also excludes -locally-sources packets (required for web caching with load balancing). -eth+ is used as an alias that refers to all ethernet interfaces: - -```none -set load-balancing wan rule 5 exclude -set load-balancing wan rule 5 inbound-interface eth+ -set load-balancing wan rule 5 destination address 10.0.0.0/8 -``` - -% start_vyoslinter - diff --git a/docs/configexamples/md-zone-policy.md b/docs/configexamples/md-zone-policy.md deleted file mode 100644 index 2cd773a9..00000000 --- a/docs/configexamples/md-zone-policy.md +++ /dev/null @@ -1,417 +0,0 @@ ---- -lastproofread: '2024-06-14' ---- - -(examples-zone-policy)= - -# Zone-Policy example - -:::{note} -In {vytask}`T2199` the syntax of the zone configuration was changed. -The zone configuration moved from `zone-policy zone ` to `firewall -zone `. -::: - -## Native IPv4 and IPv6 - -We have three networks. - -```none -WAN - 172.16.10.0/24, 2001:0DB8:0:9999::0/64 -LAN - 192.168.100.0/24, 2001:0DB8:0:AAAA::0/64 -DMZ - 192.168.200.0/24, 2001:0DB8:0:BBBB::0/64 -``` - -**This specific example is for a router on a stick, but is very easily -adapted for however many NICs you have**: - -- Internet - 192.168.200.100 - TCP/80 -- Internet - 192.168.200.100 - TCP/443 -- Internet - 192.168.200.100 - TCP/25 -- Internet - 192.168.200.100 - TCP/53 -- VyOS acts as DHCP, DNS forwarder, NAT, router and firewall. -- 192.168.200.200/2001:0DB8:0:BBBB::200 is an internal/external DNS, web - and mail (SMTP/IMAP) server. -- 192.168.100.10/2001:0DB8:0:AAAA::10 is the administrator's console. It - can SSH to VyOS. -- LAN and DMZ hosts have basic outbound access: Web, FTP, SSH. -- LAN can access DMZ resources. -- DMZ cannot access LAN resources. -- Inbound WAN connect to DMZ host. - -```{image} /_static/images/zone-policy-diagram.webp -:align: center -:alt: Network Topology Diagram -:width: 80% -``` - -The VyOS interface is assigned the .1/:1 address of their respective -networks. WAN is on VLAN 10, LAN on VLAN 20, and DMZ on VLAN 30. - -It will look something like this: - -```none -interfaces { - ethernet eth0 { - duplex auto - hw-id 00:53:ed:6e:2a:92 - smp_affinity auto - speed auto - vif 10 { - address 172.16.10.1/24 - address 2001:db8:0:9999::1/64 - } - vif 20 { - address 192.168.100.1/24 - address 2001:db8:0:AAAA::1/64 - } - vif 30 { - address 192.168.200.1/24 - address 2001:db8:0:BBBB::1/64 - } - } - loopback lo { - } -} -``` - - -## Zones Basics - -Each interface is assigned to a zone. The interface can be physical or -virtual such as tunnels (VPN, PPTP, GRE, etc) and are treated exactly -the same. - -Traffic flows from zone A to zone B. That flow is what I refer to as a -zone-pair-direction. eg. A->B and B->A are two zone-pair-destinations. - -Ruleset are created per zone-pair-direction. - -I name rule sets to indicate which zone-pair-direction they represent. -eg. ZoneA-ZoneB or ZoneB-ZoneA. LAN-DMZ, DMZ-LAN. - -In VyOS, you have to have unique Ruleset names. In the event of overlap, -I add a "-6" to the end of v6 rulesets. eg. LAN-DMZ, LAN-DMZ-6. This -allows for each auto-completion and uniqueness. - -In this example we have 4 zones. LAN, WAN, DMZ, Local. The local zone is -the firewall itself. - -If your computer is on the LAN and you need to SSH into your VyOS box, -you would need a rule to allow it in the LAN-Local ruleset. If you want -to access a webpage from your VyOS box, you need a rule to allow it in -the Local-LAN ruleset. - -In rules, it is good to keep them named consistently. As the number of -rules you have grows, the more consistency you have, the easier your -life will be. - -```none -Rule 1 - State Established, Related -Rule 2 - State Invalid -Rule 100 - ICMP -Rule 200 - Web -Rule 300 - FTP -Rule 400 - NTP -Rule 500 - SMTP -Rule 600 - DNS -Rule 700 - DHCP -Rule 800 - SSH -Rule 900 - IMAPS -``` - -The first two rules are to deal with the idiosyncrasies of VyOS and -iptables. - -Zones and Rulesets both have a default action statement. When using -Zone-Policies, the default action is set by the zone-policy statement -and is represented by rule 10000. - -It is good practice to log both accepted and denied traffic. It can save -you significant headaches when trying to troubleshoot a connectivity -issue. - -To add logging to the default rule, do: - -```none -set firewall name default-log -``` - -By default, iptables does not allow traffic for established sessions to -return, so you must explicitly allow this. I do this by adding two rules -to every ruleset. 1 allows established and related state packets through -and rule 2 drops and logs invalid state packets. We place the -established/related rule at the top because the vast majority of traffic -on a network is established and the invalid rule to prevent invalid -state packets from mistakenly being matched against other rules. Having -the most matched rule listed first reduces CPU load in high volume -environments. Note: I have filed a bug to have this added as a default -action as well. - -''It is important to note, that you do not want to add logging to the -established state rule as you will be logging both the inbound and -outbound packets for each session instead of just the initiation of the -session. Your logs will be massive in a very short period of time.'' - -In VyOS you must have the interfaces created before you can apply it to -the zone and the rulesets must be created prior to applying it to a -zone-policy. - -I create/configure the interfaces first. Build out the rulesets for each -zone-pair-direction which includes at least the three state rules. Then -I setup the zone-policies. - -Zones do not allow for a default action of accept; either drop or -reject. It is important to remember this because if you apply an -interface to a zone and commit, any active connections will be dropped. -Specifically, if you are SSH’d into VyOS and add local or the interface -you are connecting through to a zone and do not have rulesets in place -to allow SSH and established sessions, you will not be able to connect. - -The following are the rules that were created for this example (may not -be complete), both in IPv4 and IPv6. If there is no IP specified, then -the source/destination address is not explicit. - -```none -WAN - DMZ:192.168.200.200 - tcp/80 -WAN - DMZ:192.168.200.200 - tcp/443 -WAN - DMZ:192.168.200.200 - tcp/25 -WAN - DMZ:192.168.200.200 - tcp/53 -WAN - DMZ:2001:0DB8:0:BBBB::200 - tcp/80 -WAN - DMZ:2001:0DB8:0:BBBB::200 - tcp/443 -WAN - DMZ:2001:0DB8:0:BBBB::200 - tcp/25 -WAN - DMZ:2001:0DB8:0:BBBB::200 - tcp/53 - -DMZ - Local - tcp/53 -DMZ - Local - tcp/123 -DMZ - Local - tcp/67,68 - -LAN - Local - tcp/53 -LAN - Local - tcp/123 -LAN - Local - tcp/67,68 -LAN:192.168.100.10 - Local - tcp/22 -LAN:2001:0DB8:0:AAAA::10 - Local - tcp/22 - -LAN - WAN - tcp/80 -LAN - WAN - tcp/443 -LAN - WAN - tcp/22 -LAN - WAN - tcp/20,21 - -DMZ - WAN - tcp/80 -DMZ - WAN - tcp/443 -DMZ - WAN - tcp/22 -DMZ - WAN - tcp/20,21 -DMZ - WAN - tcp/53 -DMZ - WAN - udp/53 - -Local - WAN - tcp/80 -Local - WAN - tcp/443 -Local - WAN - tcp/20,21 - -Local - DMZ - tcp/25 -Local - DMZ - tcp/67,68 -Local - DMZ - tcp/53 -Local - DMZ - udp/53 - -Local - LAN - tcp/67,68 - -LAN - DMZ - tcp/80 -LAN - DMZ - tcp/443 -LAN - DMZ - tcp/993 -LAN:2001:0DB8:0:AAAA::10 - DMZ:2001:0DB8:0:BBBB::200 - tcp/22 -LAN:192.168.100.10 - DMZ:192.168.200.200 - tcp/22 -``` - -Since we have 4 zones, we need to setup the following rulesets. - -```none -Lan-wan -Lan-local -Lan-dmz -Wan-lan -Wan-local -Wan-dmz -Local-lan -Local-wan -Local-dmz -Dmz-lan -Dmz-wan -Dmz-local -``` - -Even if the two zones will never communicate, it is a good idea to -create the zone-pair-direction rulesets and set default-log. This -will allow you to log attempts to access the networks. Without it, you -will never see the connection attempts. - -This is an example of the three base rules. - -```none -name wan-lan { - default-action drop - default-log - rule 1 { - action accept - state { - established enable - related enable - } - } - rule 2 { - action drop - log enable - state { - invalid enable - } - } -} -``` - -Here is an example of an IPv6 DMZ-WAN ruleset. - -```none -ipv6-name dmz-wan-6 { - default-action drop - default-log - rule 1 { - action accept - state { - established enable - related enable - } - } - rule 2 { - action drop - log enable - state { - invalid enable - } - } - rule 100 { - action accept - log enable - protocol ipv6-icmp - } - rule 200 { - action accept - destination { - port 80,443 - } - log enable - protocol tcp - } - rule 300 { - action accept - destination { - port 20,21 - } - log enable - protocol tcp - } - rule 500 { - action accept - destination { - port 25 - } - log enable - protocol tcp - source { - address 2001:db8:0:BBBB::200 - } - } - rule 600 { - action accept - destination { - port 53 - } - log enable - protocol tcp_udp - source { - address 2001:db8:0:BBBB::200 - } - } - rule 800 { - action accept - destination { - port 22 - } - log enable - protocol tcp - } -} -``` - -Once you have all of your rulesets built, then you need to create your -zone-policy. - -Start by setting the interface and default action for each zone. - -```none -set firewall zone dmz default-action drop -set firewall zone dmz interface eth0.30 -``` - -In this case, we are setting the v6 ruleset that represents traffic -sourced from the LAN, destined for the DMZ. Because the zone-policy -firewall syntax is a little awkward, I keep it straight by thinking of -it backwards. - -```none -set firewall zone dmz from lan firewall ipv6-name lan-dmz-6 -``` - -DMZ-LAN policy is LAN-DMZ. You can get a rhythm to it when you build out -a bunch at one time. - -In the end, you will end up with something like this config. I took out -everything but the Firewall, Interfaces, and zone-policy sections. It is -long enough as is. - -## IPv6 Tunnel - -If you are using a IPv6 tunnel from HE.net or someone else, the basis is -the same except you have two WAN interfaces. One for v4 and one for v6. - -You would have 5 zones instead of just 4 and you would configure your v6 -ruleset between your tunnel interface and your LAN/DMZ zones instead of -to the WAN. - -LAN, WAN, DMZ, local and TUN (tunnel) - -v6 pairs would be: - -```none -lan-tun -lan-local -lan-dmz -tun-lan -tun-local -tun-dmz -local-lan -local-tun -local-dmz -dmz-lan -dmz-tun -dmz-local -``` - -Notice, none go to WAN since WAN wouldn't have a v6 address on it. - -You would have to add a couple of rules on your wan-local ruleset to -allow protocol 41 in. - -Something like: - -```none -rule 400 { - action accept - destination { - address 172.16.10.1 - } - log enable - protocol 41 - source { - address ip.of.tunnel.broker - } -} -``` diff --git a/docs/configuration/container/md-index.md b/docs/configuration/container/md-index.md deleted file mode 100644 index db46db38..00000000 --- a/docs/configuration/container/md-index.md +++ /dev/null @@ -1,479 +0,0 @@ ---- -lastproofread: '2024-07-03' ---- - -# Container - -The VyOS container implementation is based on [Podman](https://podman.io/) as -a daemonless container engine. - -## Configuration - -```{cfgcmd} set container name \ image - -Sets the image name in the hub registry - -:::{code-block} none -set container name mysql-server image mysql:8.0 -::: - -If a registry is not specified, Docker.io will be used as the container -registry unless an alternative registry is specified using -`set container registry ` or the registry is included -in the image name - -:::{code-block} none -set container name mysql-server image quay.io/mysql:8.0 -::: -``` - - -```{cfgcmd} set container name \ entrypoint \ - -Override the default entrypoint from the image for a container. -``` - - -```{cfgcmd} set container name \ command \ - -Override the default command from the image for a container. -``` - - -```{cfgcmd} set container name \ arguments \ - -Set the command arguments for a container. -``` - - -```{cfgcmd} set container name \ host-name \ - -Set the host name for a container. -``` - - -```{cfgcmd} set container name \ allow-host-pid - -The container and the host share the same process namespace. -This means that processes running on the host are visible inside the -container, and processes inside the container are visible on the host. - -The command translates to "--pid host" when the container is created. -``` - - -```{cfgcmd} set container name \ allow-host-networks - -Allow host networking in a container. The network stack of the container is -not isolated from the host and will use the host IP. - -The command translates to "--net host" when the container is created. - -:::{note} -**allow-host-networks** cannot be used with **network** -::: -``` - - -```{cfgcmd} set container name \ network \ - -Attaches user-defined network to a container. -Only one network must be specified and must already exist. -``` - - -```{cfgcmd} set container name \ network \ address \ - -Optionally set a specific static IPv4 or IPv6 address for the container. -This address must be within the named network prefix. - -:::{note} -The first IP in the container network is reserved by the -engine and cannot be used -::: -``` - - -```{cfgcmd} set container name \ name-server \ - -Optionally set a custom name server. -If a container network is used with DNS enabled, -this setting will not have any effect. -``` - - -```{cfgcmd} set container name \ description \ - -Set a container description -``` - - -```{cfgcmd} set container name \ environment \ value \ - -Add custom environment variables. -Multiple environment variables are allowed. -The following commands translate to "-e key=value" when the container -is created. - -:::{code-block} none -set container name mysql-server environment MYSQL_DATABASE value 'zabbix' -set container name mysql-server environment MYSQL_USER value 'zabbix' -set container name mysql-server environment MYSQL_PASSWORD value 'zabbix_pwd' -set container name mysql-server environment MYSQL_ROOT_PASSWORD value 'root_pwd' -::: -``` - - -```{cfgcmd} set container name \ port \ source \ - -``` -```{cfgcmd} set container name \ port \ destination \ -``` - -```{cfgcmd} set container name \ port \ protocol \ - -Publish a port for the container. - -:::{code-block} none -set container name zabbix-web-nginx-mysql port http source 80 -set container name zabbix-web-nginx-mysql port http destination 8080 -set container name zabbix-web-nginx-mysql port http protocol tcp -::: -``` -:::{note} -Port publishing cannot be used with **network**. For this purpose, a workaround -using destination NAT and static IP assignment for the container is available. -::: -```{cfgcmd} set container name \ volume \ source \ -``` - -```{cfgcmd} set container name \ volume \ destination \ - -Mount a volume into the container - -:::{code-block} none -set container name coredns volume 'corefile' source /config/coredns/Corefile -set container name coredns volume 'corefile' destination /etc/Corefile -::: -``` - -```{cfgcmd} set container name \ volume \ mode \ - -Volume is either mounted as rw (read-write - default) or ro (read-only) -``` - -```{cfgcmd} set container name \ tmpfs \ destination \ - -Mount a tmpfs *(ramdisk)* filesystem to the given path within the container. -``` - -```{cfgcmd} set container name \ tmpfs \ size \ - -Size in MB for tmpfs filesystem, maximum size is 64GB or 50% of the -systems total available memory. -``` - -```{cfgcmd} set container name \ uid \ -``` - -```{cfgcmd} set container name \ gid \ - -Set the User ID or Group ID of the container -``` - -```{cfgcmd} set container name \ restart [no | on-failure | always] - -Set the restart behavior of the container. - -- **no**: Do not restart containers on exit -- **on-failure**: Restart containers when they exit with a non-zero -exit code, retrying indefinitely (default) -- **always**: Restart containers when they exit, regardless of status, -retrying indefinitely -``` - -```{cfgcmd} set container name \ cpu-quota \ - -This specifies the number of CPU resources the container can use. - -Default is 0 for unlimited. -For example, 1.25 limits the container to use up to 1.25 cores -worth of CPU time. -This can be a decimal number with up to three decimal places. - -The command translates to "--cpus=\" when the container is created. -``` - -```{cfgcmd} set container name \ memory \ - -Constrain the memory available to the container. - -Default is 512 MB. Use 0 MB for unlimited memory. -``` - -```{cfgcmd} set container name \ device \ source \ -``` - -```{cfgcmd} set container name \ device \ destination \ - -Add a host device to the container. -``` - -```{cfgcmd} set container name \ capability \ - -Set container capabilities or permissions. - -- **net-admin**: Network operations (interface, firewall, routing tables) -- **net-bind-service**: Bind a socket to privileged ports -(port numbers less than 1024) -- **net-raw**: Permission to create raw network sockets -- **setpcap**: Capability sets (from bounded or inherited set) -- **sys-admin**: Administration operations (quotactl, mount, sethostname, -setdomainame) -- **sys-time**: Permission to set system clock -``` - -```{cfgcmd} set container name \ sysctl parameter \ value \ - -Set container sysctl values. - -The subset of possible parameters are: - -- Kernel Parameters: kernel.msgmax, kernel.msgmnb, kernel.msgmni, kernel.sem, -kernel.shmall, kernel.shmmax, kernel.shmmni, kernel.shm_rmid_forced -- Parameters beginning with fs.mqueue.* -- Parameters beginning with net.* (only if user-defined network is used) -``` - -```{cfgcmd} set container name \ label \ value \ - -Add metadata label for this container. -``` - -```{cfgcmd} set container name \ disable - -Disable a container. -``` - -### Container Health checks - - -By default, no health checks are run, even when defined by the image. - -```{cfgcmd} set container name \ health-check - -Default health check is run for the container if defined by the image. -``` - -```{cfgcmd} set container name \ health-check command \ - -Override the default health check command from the image for a container. -``` - -```{cfgcmd} set container name \ health-check interval \ - -Override the default health-check interval. For example: `60` -``` - -```{cfgcmd} set container name \ health-check timeout \ - -Override the default health-check timeout. For example: `10` -``` - -```{cfgcmd} set container name \ health-check retries \ - -Number of health check retries before container is considered unhealthy. For example: `1` -``` - -### Container Networks - -```{cfgcmd} set container network \ - -Creates a named container network -``` - -```{cfgcmd} set container network \ description - -A brief description what this network is all about. -``` - -```{cfgcmd} set container network \ prefix \ - -Define IPv4 and/or IPv6 prefix for a given network name. -Both IPv4 and IPv6 can be used in parallel. -``` - -```{cfgcmd} set container network \ mtu \ - -Configure {abbr}`MTU (Maximum Transmission Unit)` for a given network. It -is the size (in bytes) of the largest ethernet frame sent on this link. -``` - -```{cfgcmd} set container network \ no-name-server - -Disable Domain Name System (DNS) plugin for this network. -``` - -```{cfgcmd} set container network \ vrf \ - -Bind container network to a given VRF instance. -``` - -### Container Registry - -```{cfgcmd} set container registry \ - -Adds registry to list of unqualified-search-registries. By default, for any -image that does not include the registry in the image name, VyOS will use -docker.io and quay.io as the container registry. -``` - -```{cfgcmd} set container registry \ disable - -Disable a given container registry -``` - -```{cfgcmd} set container registry \ authentication username -``` - -```{cfgcmd} set container registry \ authentication password - -Some container registries require credentials to be used. - -Credentials can be defined here and will only be used when adding a -container image to the system. -``` - -```{cfgcmd} set container registry \ insecure - -Allow registry access over unencrypted HTTP or TLS connections with -untrusted certificates. -``` - -```{cfgcmd} set container registry \ mirror address \ -``` - -```{cfgcmd} set container registry \ mirror host-name \ -``` - -```{cfgcmd} set container registry \ mirror port \ -``` - -```{cfgcmd} set container registry \ mirror path \ - -Registry mirror, use ``(host-name|address)[:port][/path]``. - -If you have mirror http://192.168.1.1:8080 for docker.io, you can use ``docker.io/some/repo`` or run ``podman pull docker.io/some/repo`` - -:::{code-block} none -set container registry docker.io mirror address 192.168.1.1 -set container registry docker.io mirror port 8080 -set container registry docker.io insecure -::: -If http://192.168.1.1:8080 is your own registry, you can use ``192.168.1.1:8080/some/repo`` or run ``podman pull 192.168.1.1:8080/some/repo`` - -:::{code-block} none -set container registry 192.168.1.1:8080 insecure -::: -``` - -### Log Configuration - -```{cfgcmd} set container name \ log-driver [k8s-file | journald | none] - -Set the default log driver for containers. - -- **k8s-file**: Log to a plain text file in Kubernetes-style format. -- **journald**: Log to the system journal -- **none**: Disable logging for the container - -Current default is journald. - -``` - -## Operation Commands - -```{opcmd} add container image \ - -Pull a new image for container -``` -```{opcmd} show container - -Show the list of all active containers. -``` -```{opcmd} show container image - -Show the local container images. -``` -```{opcmd} show container log \ - -Show logs from a given container -``` -```{opcmd} show container network - -Show a list available container networks -``` -```{opcmd} restart container \ - -Restart a given container -``` -```{opcmd} update container image \ - -Update container image -``` -```{opcmd} delete container image \ [force] - -Delete a particular container image based on it's image ID. -You can also delete all container images at once. - -You can not delete a container image if it has more then one tag -assigned, this is why there is a `force` option to pass down to -the container image to also remove those images. -``` - -## Example Configuration - -For the sake of demonstration, [example #1 in the official documentation](https://www.zabbix.com/documentation/current/manual/installation/containers) -to the declarative VyOS CLI syntax. - -```none -set container network zabbix prefix 172.20.0.0/16 -set container network zabbix description 'Network for Zabbix component containers' - -set container name mysql-server image mysql:8.0 -set container name mysql-server network zabbix - -set container name mysql-server environment 'MYSQL_DATABASE' value 'zabbix' -set container name mysql-server environment 'MYSQL_USER' value 'zabbix' -set container name mysql-server environment 'MYSQL_PASSWORD' value 'zabbix_pwd' -set container name mysql-server environment 'MYSQL_ROOT_PASSWORD' value 'root_pwd' - -set container name zabbix-java-gateway image zabbix/zabbix-java-gateway:alpine-5.2-latest -set container name zabbix-java-gateway network zabbix - -set container name zabbix-server-mysql image zabbix/zabbix-server-mysql:alpine-5.2-latest -set container name zabbix-server-mysql network zabbix - -set container name zabbix-server-mysql environment 'DB_SERVER_HOST' value 'mysql-server' -set container name zabbix-server-mysql environment 'MYSQL_DATABASE' value 'zabbix' -set container name zabbix-server-mysql environment 'MYSQL_USER' value 'zabbix' -set container name zabbix-server-mysql environment 'MYSQL_PASSWORD' value 'zabbix_pwd' -set container name zabbix-server-mysql environment 'MYSQL_ROOT_PASSWORD' value 'root_pwd' -set container name zabbix-server-mysql environment 'ZBX_JAVAGATEWAY' value 'zabbix-java-gateway' - -set container name zabbix-server-mysql port zabbix source 10051 -set container name zabbix-server-mysql port zabbix destination 10051 - -set container name zabbix-web-nginx-mysql image zabbix/zabbix-web-nginx-mysql:alpine-5.2-latest -set container name zabbix-web-nginx-mysql network zabbix - -set container name zabbix-web-nginx-mysql environment 'MYSQL_DATABASE' value 'zabbix' -set container name zabbix-web-nginx-mysql environment 'ZBX_SERVER_HOST' value 'zabbix-server-mysql' -set container name zabbix-web-nginx-mysql environment 'DB_SERVER_HOST' value 'mysql-server' -set container name zabbix-web-nginx-mysql environment 'MYSQL_USER' value 'zabbix' -set container name zabbix-web-nginx-mysql environment 'MYSQL_PASSWORD' value 'zabbix_pwd' -set container name zabbix-web-nginx-mysql environment 'MYSQL_ROOT_PASSWORD' value 'root_pwd' - -set container name zabbix-web-nginx-mysql port http source 80 -set container name zabbix-web-nginx-mysql port http destination 8080 -``` diff --git a/docs/configuration/firewall/md-bridge.md b/docs/configuration/firewall/md-bridge.md deleted file mode 100644 index f0e94f9e..00000000 --- a/docs/configuration/firewall/md-bridge.md +++ /dev/null @@ -1,685 +0,0 @@ ---- -lastproofread: '2026-03-28' ---- - -(firewall-configuration)= - -# Bridge Firewall Configuration - -## Overview - -Learn more about bridge firewall configuration -and related op-mode commands. - -The following commands are covered in this section: - -```{cfgcmd} set firewall bridge \ -``` - -From the main structure defined in -{doc}`Firewall Overview` -in this section you can find detailed information only for the next part -of the general structure: - -```none -- set firewall - * bridge - - forward - + filter - - input - + filter - - output - + filter - - prerouting - + filter - - name - + custom_name -``` - -Traffic that is received by the router on an interface that is a member of a -bridge is processed on the **Bridge Layer**. Before the bridge decision is -made, all packets are analyzed at **Prerouting**. First filters can be applied -here, and also rules for ignoring connection tracking system can be configured. -The relevant configuration that acts in **prerouting** is: - - -- `set firewall bridge prerouting filter ...`. - - -For traffic that needs to be switched internally by the bridge, the base -chain is **forward**, and its base command for filtering is `set firewall -bridge forward filter ...`, which happens in stage 4, highlighted with red -color. - - -:::{figure} /_static/images/firewall-bridge-forward.webp -::: - - -For traffic destined to the router itself or that needs to be routed -(assuming a layer3 bridge is configured), the base chain is **input**, and the -base command is `set firewall bridge input filter ...` and the path is: - - -:::{figure} /_static/images/firewall-bridge-input.webp -::: - - -If it's not dropped, then the packet is sent to **IP Layer**, and will be -processed by the **IP Layer** firewall: IPv4 or IPv6 ruleset. Check once again -the {doc}`general packet flow diagram` if -needed. - - -For traffic that originates from the bridge itself, the base chain is -**output**, and the base command is `set firewall bridge output filter -...`, and the path is: - - -:::{figure} /_static/images/firewall-bridge-output.webp -::: - - -Custom bridge firewall chains can be created with the command `set firewall -bridge name ...`. To use such a custom chain, a rule with action jump -and the appropriate target must be defined in a base chain. - - -## Bridge Rules - - -For firewall filtering, firewall rules need to be created. Each rule is -numbered, has an action to apply if the rule is matched, and the ability -to specify multiple matching criteria. Data packets go through the rules -from 1 - 999999, so order is crucial. At the first match the action of the -rule will be executed. - - -### Actions - - -If a rule is defined, an action must also be defined for it. This tells the -firewall what to do if all matching criteria in the rule are met. - - -In firewall bridge rules, the action can be: - - -- `accept`: accept the packet. -- `continue`: continue parsing next rule. -- `drop`: drop the packet. -- `jump`: jump to another custom chain. -- `return`: Return from the current chain and continue at the next rule - of the last chain. -- `queue`: Enqueue packet to userspace. -- `notrack`: ignore connection tracking system. This action is only - available in prerouting chain. - -```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> action [accept | continue | drop | jump | queue | return] -``` - -```{cfgcmd} set firewall bridge input filter rule \<1-999999\> action [accept | continue | drop | jump | queue | return] -``` - -```{cfgcmd} set firewall bridge output filter rule \<1-999999\> action [accept | continue | drop | jump | queue | return] -``` - -```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> action [accept | continue | drop | jump | notrack | queue | return] -``` - -```{cfgcmd} set firewall bridge name \ rule \<1-999999\> action [accept | continue | drop | jump | queue | return] - -This required setting defines the action of the current rule. If action is -set to jump, then jump-target is also needed. -``` - -```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> jump-target \ -``` - -```{cfgcmd} set firewall bridge input filter rule \<1-999999\> jump-target \ -``` - -```{cfgcmd} set firewall bridge output filter rule \<1-999999\> jump-target \ -``` - -```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> jump-target \ -``` - -```{cfgcmd} set firewall bridge name \ rule \<1-999999\> jump-target \ -``` - -If action is set to ``queue``, use next command to specify the queue -target. Range is also supported: - -```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> queue \<0-65535\> -``` - -```{cfgcmd} set firewall bridge input filter rule \<1-999999\> queue \<0-65535\> -``` - -```{cfgcmd} set firewall bridge output filter rule \<1-999999\> queue \<0-65535\> -``` - -```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> queue \<0-65535\> -``` - -```{cfgcmd} set firewall bridge name \ rule \<1-999999\> queue \<0-65535\> - -Also, if action is set to ``queue``, use next command to specify the queue -options. Possible options are ``bypass`` and ``fanout``: -``` - -```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> queue-options bypass -``` - -```{cfgcmd} set firewall bridge input filter rule \<1-999999\> queue-options bypass -``` - -```{cfgcmd} set firewall bridge output filter rule \<1-999999\> queue-options bypass -``` - -```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> queue-options bypass -``` - -```{cfgcmd} set firewall bridge name \ rule \<1-999999\> queue-options bypass -``` - -```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> queue-options fanout -``` - -```{cfgcmd} set firewall bridge input filter rule \<1-999999\> queue-options fanout -``` - -```{cfgcmd} set firewall bridge output filter rule \<1-999999\> queue-options fanout -``` - -```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> queue-options fanout -``` - -```{cfgcmd} set firewall bridge name \ rule \<1-999999\> queue-options fanout -``` - -Also, **default-action** is an action that takes place whenever a packet does -not match any rule in its chain. For base chains, possible options for -**default-action** are **accept** or **drop**. - -```{cfgcmd} set firewall bridge forward filter default-action [accept | drop] -``` - -```{cfgcmd} set firewall bridge input filter default-action [accept | drop] -``` - -```{cfgcmd} set firewall bridge output filter default-action [accept | drop] -``` - -```{cfgcmd} set firewall bridge prerouting filter default-action [accept | drop] -``` - -```{cfgcmd} set firewall bridge name \ default-action [accept | continue | drop | jump | reject | return] - -This sets the default action of the rule-set if a packet does not match -any of the rules in that chain. If default-action is set to ``jump``, then -``default-jump-target`` is also needed. Note that for base chains, default -action can only be set to ``accept`` or ``drop``, while on custom chains -more actions are available. -``` - -```{cfgcmd} set firewall bridge name \ default-jump-target \ - -To be used only when ``default-action`` is set to ``jump``. Use this -command to specify jump target for default rule. -``` -:::{note} -**Important note about default-actions:** -If the default action for any base chain is not defined, then the default -action is set to **accept** for that chain. For custom chains, if the -default action is not defined, then the default-action is set to **drop**. -::: - - -### Firewall Logs - - -You can enable logging for every firewall rule. If enabled, other log options -can be configured. - -```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> log -``` - -```{cfgcmd} set firewall bridge input filter rule \<1-999999\> log -``` - -```{cfgcmd} set firewall bridge output filter rule \<1-999999\> log -``` - -```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> log -``` - -```{cfgcmd} set firewall bridge name \ rule \<1-999999\> log - -Enable logging for the matched packet. If this configuration command is not -present, then the log is not enabled. -``` - -```{cfgcmd} set firewall bridge forward filter default-log -``` - -```{cfgcmd} set firewall bridge input filter default-log -``` - -```{cfgcmd} set firewall bridge output filter default-log -``` - -```{cfgcmd} set firewall bridge prerouting filter default-log -``` - -```{cfgcmd} set firewall bridge name \ default-log - -Use this command to enable the logging of the default action on -the specified chain. -``` - -```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> log-options level [emerg | alert | crit | err | warn | notice | info | debug] -``` - -```{cfgcmd} set firewall bridge input filter rule \<1-999999\> log-options level [emerg | alert | crit | err | warn | notice | info | debug] -``` - -```{cfgcmd} set firewall bridge output filter rule \<1-999999\> log-options level [emerg | alert | crit | err | warn | notice | info | debug] -``` - -```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> log-options level [emerg | alert | crit | err | warn | notice | info | debug] -``` - -```{cfgcmd} set firewall bridge name \ rule \<1-999999\> log-options level [emerg | alert | crit | err | warn | notice | info | debug] - -Define log-level. Only applicable if rule log is enabled. -``` - -```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> log-options group \<0-65535\> -``` - -```{cfgcmd} set firewall bridge input filter rule \<1-999999\> log-options group \<0-65535\> -``` - -```{cfgcmd} set firewall bridge output filter rule \<1-999999\> log-options group \<0-65535\> -``` - -```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> log-options group \<0-65535\> -``` - -```{cfgcmd} set firewall bridge name \ rule \<1-999999\> log-options group \<0-65535\> - -Define the log group to send messages to. Only applicable if rule log is -enabled. -``` - -```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> log-options snapshot-length \<0-9000\> -``` - -```{cfgcmd} set firewall bridge input filter rule \<1-999999\> log-options snapshot-length \<0-9000\> -``` - -```{cfgcmd} set firewall bridge output filter rule \<1-999999\> log-options snapshot-length \<0-9000\> -``` - -```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> log-options snapshot-length \<0-9000\> -``` - -```{cfgcmd} set firewall bridge name \ rule \<1-999999\> log-options snapshot-length \<0-9000\> - -Define length of packet payload to include in netlink message. Only -applicable if rule log is enabled and the log group is defined. -``` - -```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> log-options queue-threshold \<0-65535\> -``` - -```{cfgcmd} set firewall bridge input filter rule \<1-999999\> log-options queue-threshold \<0-65535\> -``` - -```{cfgcmd} set firewall bridge output filter rule \<1-999999\> log-options queue-threshold \<0-65535\> -``` - -```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> log-options queue-threshold \<0-65535\> -``` - -```{cfgcmd} set firewall bridge name \ rule \<1-999999\> log-options queue-threshold \<0-65535\> - -Define the number of packets to queue inside the kernel before sending them -to userspace. Only applicable if rule log is enabled and the log group is -defined. -``` - -### Firewall Description - - -You can define a description for reference for every custom chain. - -```{cfgcmd} set firewall bridge name \ description \ - -Provide a rule-set description to a custom firewall chain. -``` - -```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> description \ -``` - -```{cfgcmd} set firewall bridge input filter rule \<1-999999\> description \ -``` - -```{cfgcmd} set firewall bridge output filter rule \<1-999999\> description \ -``` - -```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> description \ -``` - -```{cfgcmd} set firewall bridge name \ rule \<1-999999\> description \ - -Provide a description for each rule. -``` - -### Rule Status - - -By default, when you define a rule, it is enabled. In some cases, it is -useful to disable the rule instead of removing it. - -```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> disable -``` - -```{cfgcmd} set firewall bridge input filter rule \<1-999999\> disable -``` - -```{cfgcmd} set firewall bridge output filter rule \<1-999999\> disable -``` - -```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> disable -``` - -```{cfgcmd} set firewall bridge name \ rule \<1-999999\> disable - -Command for disabling a rule but keep it in the configuration. -``` - -### Matching criteria - - -There are many matching criteria against which a packet can be tested. Refer -to {doc}`IPv4` and -{doc}`IPv6` matching criteria for more details. - - -Since bridges operate at layer 2, both matchers for IPv4 and IPv6 are -supported in bridge firewall configuration. Same applies to firewall groups. - - -Same specific matching criteria that can be used in bridge firewall are -described in this section: - -```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> ethernet-type [802.1q | 802.1ad | arp | ipv4 | ipv6] -``` - -```{cfgcmd} set firewall bridge input filter rule \<1-999999\> ethernet-type [802.1q | 802.1ad | arp | ipv4 | ipv6] -``` - -```{cfgcmd} set firewall bridge output filter rule \<1-999999\> ethernet-type [802.1q | 802.1ad | arp | ipv4 | ipv6] -``` - -```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> ethernet-type [802.1q | 802.1ad | arp | ipv4 | ipv6] -``` - -```{cfgcmd} set firewall bridge name \ rule \<1-999999\> ethernet-type [802.1q | 802.1ad | arp | ipv4 | ipv6] - -Match based on the Ethernet type of the packet. -``` - -```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> vlan ethernet-type [802.1q | 802.1ad | arp | ipv4 | ipv6] -``` - -```{cfgcmd} set firewall bridge input filter rule \<1-999999\> vlan ethernet-type [802.1q | 802.1ad | arp | ipv4 | ipv6] -``` - -```{cfgcmd} set firewall bridge output filter rule \<1-999999\> vlan ethernet-type [802.1q | 802.1ad | arp | ipv4 | ipv6] -``` - -```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> vlan ethernet-type [802.1q | 802.1ad | arp | ipv4 | ipv6] -``` - -```{cfgcmd} set firewall bridge name \ rule \<1-999999\> vlan ethernet-type [802.1q | 802.1ad | arp | ipv4 | ipv6] - -Match based on the Ethernet type of the packet when it is VLAN tagged. -``` - -```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> vlan id \<0-4096\> -``` - -```{cfgcmd} set firewall bridge input filter rule \<1-999999\> vlan id \<0-4096\> -``` - -```{cfgcmd} set firewall bridge output filter rule \<1-999999\> vlan id \<0-4096\> -``` - -```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> vlan id \<0-4096\> -``` - -```{cfgcmd} set firewall bridge name \ rule \<1-999999\> vlan id \<0-4096\> - -Match based on VLAN identifier. Range is also supported. -``` - -```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> vlan priority \<0-7\> -``` - -```{cfgcmd} set firewall bridge input filter rule \<1-999999\> vlan priority \<0-7\> -``` - -```{cfgcmd} set firewall bridge output filter rule \<1-999999\> vlan priority \<0-7\> -``` - -```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> vlan priority \<0-7\> -``` - -```{cfgcmd} set firewall bridge name \ rule \<1-999999\> vlan priority \<0-7\> - -Match based on VLAN priority (Priority Code Point - PCP). Range is also -supported. -``` - -### Packet Modifications - - -Starting from **VyOS-1.5-rolling-202410060007**, the firewall can modify -packets before they are sent out. This feature provides more flexibility in -packet handling. - -```{cfgcmd} set firewall bridge [prerouting | forward | output] filter rule \<1-999999\> set dscp \<0-63\> - -Set a specific value of Differentiated Services Codepoint (DSCP). -``` - -```{cfgcmd} set firewall bridge [prerouting | forward | output] filter rule \<1-999999\> set mark \<1-2147483647\> - -Set a specific packet mark value. -``` - -```{cfgcmd} set firewall bridge [prerouting | forward | output] filter rule \<1-999999\> set tcp-mss \<500-1460\> - -Set the TCP-MSS (TCP maximum segment size) for the connection. -``` - -```{cfgcmd} set firewall bridge [prerouting | forward | output] filter rule \<1-999999\> set ttl \<0-255\> - -Set the TTL (Time to Live) value. -``` - -```{cfgcmd} set firewall bridge [prerouting | forward | output] filter rule \<1-999999\> set hop-limit \<0-255\> - -Set hop limit value. -``` - -```{cfgcmd} set firewall bridge [forward | output] filter rule \<1-999999\> set connection-mark \<0-2147483647\> - -Set connection mark value. -``` - -### Use IP firewall - -By default, for switched traffic, only the rules defined under `set firewall -bridge` are applied. There are two global-options that can be configured in -order to force deeper analysis of the packet on the IP layer. These options -are: - -```{cfgcmd} set firewall global-options apply-to-bridged-traffic ipv4 - -This command enables the IPv4 firewall for bridged traffic. If this option -is used, packets are also parsed by rules defined in ``set firewall ipv4 -...`` -``` - -```{cfgcmd} set firewall global-options apply-to-bridged-traffic ipv6 - -This command enables the IPv6 firewall for bridged traffic. If this option -is used, packets are also parsed by rules defined in ``set firewall ipv6 -...`` -``` - -## Operation-mode Firewall -### Rule-set overview - -In this section you can find all useful firewall op-mode commands. -General commands for firewall configuration, counter and statistics: - -```{opcmd} show firewall -``` - -```{opcmd} show firewall summary -``` - -```{opcmd} show firewall statistics -``` - -And, to print only bridge firewall information: - -```{opcmd} show firewall bridge -``` - -```{opcmd} show firewall bridge forward filter -``` - -```{opcmd} show firewall bridge forward filter rule \ -``` - -```{opcmd} show firewall bridge name \ -``` - -```{opcmd} show firewall bridge name \ rule \ -``` - -### Show Firewall log - -```{opcmd} show log firewall -``` - -```{opcmd} show log firewall bridge -``` - -```{opcmd} show log firewall bridge forward -``` - -```{opcmd} show log firewall bridge forward filter -``` - -```{opcmd} show log firewall bridge name \ -``` - -```{opcmd} show log firewall bridge forward filter rule \ -``` - -```{opcmd} show log firewall bridge name \ rule \ - -Show the logs of all firewall; show all bridge firewall logs; show all logs -for forward hook; show all logs for forward hook and priority filter; show -all logs for particular custom chain; show logs for specific Rule-Set. -``` - -### Example - -Configuration example: - -```none -set firewall bridge forward filter default-action 'drop' -set firewall bridge forward filter default-log -set firewall bridge forward filter rule 10 action 'continue' -set firewall bridge forward filter rule 10 inbound-interface name 'eth2' -set firewall bridge forward filter rule 10 vlan id '22' -set firewall bridge forward filter rule 20 action 'drop' -set firewall bridge forward filter rule 20 inbound-interface group 'TRUNK-RIGHT' -set firewall bridge forward filter rule 20 vlan id '60' -set firewall bridge forward filter rule 30 action 'jump' -set firewall bridge forward filter rule 30 jump-target 'TEST' -set firewall bridge forward filter rule 30 outbound-interface name '!eth1' -set firewall bridge forward filter rule 35 action 'accept' -set firewall bridge forward filter rule 35 vlan id '11' -set firewall bridge forward filter rule 40 action 'continue' -set firewall bridge forward filter rule 40 destination mac-address '66:55:44:33:22:11' -set firewall bridge forward filter rule 40 source mac-address '11:22:33:44:55:66' -set firewall bridge name TEST default-action 'accept' -set firewall bridge name TEST default-log -set firewall bridge name TEST rule 10 action 'continue' -set firewall bridge name TEST rule 10 log -set firewall bridge name TEST rule 10 vlan priority '0' -``` - -And op-mode commands: - -```none -vyos@BRI:~$ show firewall bridge -Rulesets bridge Information - ---------------------------------- -bridge Firewall "forward filter" - -Rule Action Protocol Packets Bytes Conditions -------- -------- ---------- --------- ------- --------------------------------------------------------------------- -10 continue all 0 0 iifname "eth2" vlan id 22 continue -20 drop all 0 0 iifname @I_TRUNK-RIGHT vlan id 60 -30 jump all 2130 170688 oifname != "eth1" jump NAME_TEST -35 accept all 2080 168616 vlan id 11 accept -40 continue all 0 0 ether daddr 66:55:44:33:22:11 ether saddr 11:22:33:44:55:66 continue -default drop all 0 0 - ---------------------------------- -bridge Firewall "name TEST" - -Rule Action Protocol Packets Bytes Conditions -------- -------- ---------- --------- ------- -------------------------------------------------- -10 continue all 2130 170688 vlan pcp 0 prefix "[bri-NAM-TEST-10-C]" continue -default accept all 2130 170688 - -vyos@BRI:~$ -vyos@BRI:~$ show firewall bridge name TEST -Ruleset Information - ---------------------------------- -bridge Firewall "name TEST" - -Rule Action Protocol Packets Bytes Conditions -------- -------- ---------- --------- ------- -------------------------------------------------- -10 continue all 2130 170688 vlan pcp 0 prefix "[bri-NAM-TEST-10-C]" continue -default accept all 2130 170688 - -vyos@BRI:~$ -``` - -Inspect logs: - -```none -vyos@BRI:~$ show log firewall bridge -Dec 05 14:37:47 kernel: [bri-NAM-TEST-10-C]IN=eth1 OUT=eth2 ARP HTYPE=1 PTYPE=0x0800 OPCODE=1 MACSRC=50:00:00:04:00:00 IPSRC=10.11.11.101 MACDST=00:00:00:00:00:00 IPDST=10.11.11.102 -Dec 05 14:37:48 kernel: [bri-NAM-TEST-10-C]IN=eth1 OUT=eth2 ARP HTYPE=1 PTYPE=0x0800 OPCODE=1 MACSRC=50:00:00:04:00:00 IPSRC=10.11.11.101 MACDST=00:00:00:00:00:00 IPDST=10.11.11.102 -Dec 05 14:37:49 kernel: [bri-NAM-TEST-10-C]IN=eth1 OUT=eth2 ARP HTYPE=1 PTYPE=0x0800 OPCODE=1 MACSRC=50:00:00:04:00:00 IPSRC=10.11.11.101 MACDST=00:00:00:00:00:00 IPDST=10.11.11.102 -... -vyos@BRI:~$ show log firewall bridge forward filter -Dec 05 14:42:22 kernel: [bri-FWD-filter-default-D]IN=eth2 OUT=eth1 MAC=33:33:00:00:00:16:50:00:00:06:00:00:86:dd SRC=0000:0000:0000:0000:0000:0000:0000:0000 DST=ff02:0000:0000:0000:0000:0000:0000:0016 LEN=96 TC=0 HOPLIMIT=1 FLOWLBL=0 PROTO=ICMPv6 TYPE=143 CODE=0 -Dec 05 14:42:22 kernel: [bri-FWD-filter-default-D]IN=eth2 OUT=eth1 MAC=33:33:00:00:00:16:50:00:00:06:00:00:86:dd SRC=0000:0000:0000:0000:0000:0000:0000:0000 DST=ff02:0000:0000:0000:0000:0000:0000:0016 LEN=96 TC=0 HOPLIMIT=1 FLOWLBL=0 PROTO=ICMPv6 TYPE=143 CODE=0 -``` diff --git a/docs/configuration/firewall/md-flowtables.md b/docs/configuration/firewall/md-flowtables.md deleted file mode 100644 index 24d0675e..00000000 --- a/docs/configuration/firewall/md-flowtables.md +++ /dev/null @@ -1,176 +0,0 @@ ---- -lastproofread: '2026-03-30' ---- - -(firewall-flowtables-configuration)= - -# Flowtables Firewall Configuration - -```{include} /_include/need_improvement.txt -``` - - -## Overview - -This section provides information on firewall configuration for flowtables. - -```{cfgcmd} set firewall flowtable ... -``` - -To learn about the general traffic flow in VyOS firewalls, -see {doc}`Firewall `. - -```none -- set firewall - * flowtable - - custom_flow_table - + ... -``` - -Flowtables let you define a fastpath through the flowtable datapath. -Flowtables support layer 3 (IPv4 and IPv6) and layer 4 (TCP and UDP) -protocols. - -:::{figure} /_static/images/firewall-flowtable-packet-flow.webp -::: - -After the first packet successfully traverses the IP forwarding path (black -circles path), you can offload subsequent packets to the flowtable through your -ruleset. You specify when to add a flow to the flowtable during forward -filtering (red circle number 6). - -When a packet finds a matching entry in the flowtable (flowtable hit), the -system transmits it to the output netdevice. This means packets bypass the -classic IP forwarding path and use the **Fast Path** (orange circles path). -As a result, you do not see these packets from any Netfilter hooks after -ingress. If no matching entry exists in the flowtable (flowtable miss), the -packet traverses the classic IP forwarding path. - -:::{note} -**Flowtable Reference:** - -::: - -## Flowtable Configuration - -To use flowtables, you need to configure the following: -> - Create a flowtable that includes the interfaces -> that are going to be used by the flowtable. -> - Create a firewall rule. Set the action to -> `offload` and use your desired flowtable for `offload-target`. - -Creating a flow table: - -```{cfgcmd} set firewall flowtable \ interface \ - -Specify interfaces to use in the flowtable. -``` - -```{cfgcmd} set firewall flowtable \ description \ -``` - -Provide a description for the flow table. - -```{cfgcmd} set firewall flowtable \ offload \ - -Specify the offload type the flowtable uses: ``hardware`` or -``software``. The default is ``software`` offload. -``` -:::{note} -**Hardware offload**: Make sure your network interface controller -(NIC) supports hardware offloading and that you have the necessary drivers -> installed before enabling this option. -::: - -Creating rules for using flow tables: - -```{cfgcmd} set firewall [ipv4 | ipv6] forward filter rule \<1-999999\> action offload - -Create a firewall rule in the forward chain with the action set to -``offload``. -``` - -```{cfgcmd} set firewall [ipv4 | ipv6] forward filter rule \<1-999999\> offload-target \ - -Create a firewall rule in the forward chain and specify which flowtable -to use. Only applicable if the action is ``offload``. -``` - -## Configuration Example - -Consider the following in this setup: -> - This example uses two interfaces in the flowtables: `eth0` and `eth1`. -> - The example provides a minimal firewall ruleset with filtering rules -> and rules for using flowtable offload capabilities. - -The first packet is evaluated by the firewall path, so a -desired connection should be explicitly accepted. -The same should occur for traffic in reverse order. -In most cases, state policies are -used to accept a connection in the reverse path. - -In the following example only traffic coming from interface `eth0`, -TCP protocol, and destination port 1122 is accepted. -All other traffic to the router is dropped. - -### Commands - -```none -set firewall flowtable FT01 interface 'eth0' -set firewall flowtable FT01 interface 'eth1' -set firewall ipv4 forward filter default-action 'drop' -set firewall ipv4 forward filter rule 10 action 'offload' -set firewall ipv4 forward filter rule 10 offload-target 'FT01' -set firewall ipv4 forward filter rule 10 state 'established' -set firewall ipv4 forward filter rule 10 state 'related' -set firewall ipv4 forward filter rule 20 action 'accept' -set firewall ipv4 forward filter rule 20 state 'established' -set firewall ipv4 forward filter rule 20 state 'related' -set firewall ipv4 forward filter rule 110 action 'accept' -set firewall ipv4 forward filter rule 110 destination address '192.0.2.100' -set firewall ipv4 forward filter rule 110 destination port '1122' -set firewall ipv4 forward filter rule 110 inbound-interface name 'eth0' -set firewall ipv4 forward filter rule 110 protocol 'tcp' -``` - -### Explanation - -Here's what happens for a desired connection: -> 1. A packet arrives on `eth0` with destination address `192.0.2.100`, TCP -> protocol, and destination port 1122. Assume this address is reachable -> through interface `eth1`. -> 2. For this first packet, the connection state is **new**. Neither rule 10 -> nor rule 20 applies. -> 3. Rule 110 matches, so the connection is accepted. -> 4. When the server 192.0.2.100 replies, the connection state becomes -> **established**, and rule 20 accepts the reply. -> 5. The router receives the second packet for this connection. Because the -> connection state is **established**, rule 10 matches and adds a new -> entry in the flowtable FT01 for this connection. -> 6. Subsequent packets skip the traditional path and use the **Fast Path** -> for offloading. - -### Checks - -Check the conntrack table to verify that the system accepted and properly -offloaded connections. - -```none -vyos@FlowTables:~$ show firewall ipv4 forward filter -Ruleset Information - ---------------------------------- -ipv4 Firewall "forward filter" - -Rule Action Protocol Packets Bytes Conditions -------- -------- ---------- --------- ------- ---------------------------------------------------------------- -10 offload all 8 468 ct state { established, related } flow add @VYOS_FLOWTABLE_FT01 -20 accept all 8 468 ct state { established, related } accept -110 accept tcp 2 120 ip daddr 192.0.2.100 tcp dport 1122 iifname "eth0" accept -default drop all 7 420 - -vyos@FlowTables:~$ sudo conntrack -L | grep tcp -conntrack v1.4.6 (conntrack-tools): 5 flow entries have been shown. -tcp 6 src=198.51.100.100 dst=192.0.2.100 sport=41676 dport=1122 src=192.0.2.100 dst=198.51.100.100 sport=1122 dport=41676 [OFFLOAD] mark=0 use=2 -vyos@FlowTables:~$ -``` diff --git a/docs/configuration/firewall/md-global-options.md b/docs/configuration/firewall/md-global-options.md deleted file mode 100644 index 0f6d91ac..00000000 --- a/docs/configuration/firewall/md-global-options.md +++ /dev/null @@ -1,186 +0,0 @@ ---- -lastproofread: '2026-03-30' ---- - -(firewall-global-options-configuration)= - -# Global Options Firewall Configuration - -## Overview - -Some firewall settings are global and affect the entire system. This section -provides information about these global options that you can configure using -the VyOS CLI. - -Configuration commands covered in this section: - -```{cfgcmd} set firewall global-options ... -``` - -## Configuration - -```{cfgcmd} set firewall global-options all-ping [enable | disable] - -By default, when VyOS receives an ICMP echo request packet destined for -itself, it answers with an ICMP echo reply, unless your firewall prevents -it. - -You can set firewall rules to accept, drop, or reject ICMP in, out, or -local traffic. You can also use the **firewall global-options all-ping** -command. This command affects only LOCAL traffic (packets destined for your -VyOS system), not IN or OUT traffic. - -:::{note} -**firewall global-options all-ping** affects only LOCAL traffic -and always behaves in the most restrictive way -::: -:::{code-block} none -set firewall global-options all-ping enable -::: -When you set this command, VyOS answers every ICMP echo request addressed -to itself, but that response occurs only if no other rule drops or rejects -local echo requests. In case of conflict, VyOS does not answer ICMP echo -requests. - -:::{code-block} none -set firewall global-options all-ping disable -::: -When you set this command, VyOS answers no ICMP echo requests addressed to -itself, regardless of where they come from or what specific rules accept -them. -``` - -```{cfgcmd} set firewall global-options apply-to-bridged-traffic [ipv4 | ipv6] - -Apply IPv4 or IPv6 firewall rules to bridged traffic. -``` - -```{cfgcmd} set firewall global-options broadcast-ping [enable | disable] - -Enable or disable the response to ICMP broadcast messages. The system -alters the following parameter: -* ``net.ipv4.icmp_echo_ignore_broadcasts`` -``` - -```{cfgcmd} set firewall global-options ip-src-route [enable | disable] -``` - -```{cfgcmd} set firewall global-options ipv6-src-route [enable | disable] - -Set whether VyOS accepts packets with a source route option. -The following sysctl parameters will be changed: -* ``net.ipv4.conf.all.accept_source_route`` -* ``net.ipv6.conf.all.accept_source_route`` -``` - -```{cfgcmd} set firewall global-options receive-redirects [enable | disable] -``` - -```{cfgcmd} set firewall global-options ipv6-receive-redirects [enable | disable] - -Allow VyOS to accept ICMPv4 and ICMPv6 redirect messages. -The following sysctl parameters will be changed: -* ``net.ipv4.conf.all.accept_redirects`` -* ``net.ipv6.conf.all.accept_redirects`` -``` - -```{cfgcmd} set firewall global-options send-redirects [enable | disable] - -Allow VyOS to send ICMPv4 redirect messages. -The following sysctl parameter will be changed: -* ``net.ipv4.conf.all.send_redirects`` -``` - -```{cfgcmd} set firewall global-options log-martians [enable | disable] - -Allow VyOS to log martian IPv4 packets. -The following sysctl parameter will be changed: -* ``net.ipv4.conf.all.log_martians`` -``` - -```{cfgcmd} set firewall global-options source-validation [strict | loose | disable] - -Set the IPv4 source validation mode. -The following sysctl parameter will be changed: -* ``net.ipv4.conf.all.rp_filter`` -``` - -```{cfgcmd} set firewall global-options syn-cookies [enable | disable] - -Allow VyOS to use IPv4 TCP SYN Cookies. -The following sysctl parameter will be changed: -* ``net.ipv4.tcp_syncookies`` -``` - -```{cfgcmd} set firewall global-options twa-hazards-protection [enable | disable] - -Enable or disable VyOS {rfc}`1337` conformance. -The following sysctl parameter will be changed: -* ``net.ipv4.tcp_rfc1337`` -``` - -```{cfgcmd} set firewall global-options state-policy established action [accept | drop | reject] -``` - -```{cfgcmd} set firewall global-options state-policy established log -``` - -```{cfgcmd} set firewall global-options state-policy established log-level [emerg | alert | crit | err | warn | notice | info | debug] - -Set the global setting for an established connection. -``` - -```{cfgcmd} set firewall global-options state-policy invalid action [accept | drop | reject] -``` - -```{cfgcmd} set firewall global-options state-policy invalid log -``` - -```{cfgcmd} set firewall global-options state-policy invalid log-level [emerg | alert | crit | err | warn | notice | info | debug] - -Set the global setting for invalid packets. -``` - -```{cfgcmd} set firewall global-options state-policy related action [accept | drop | reject] -``` - -```{cfgcmd} set firewall global-options state-policy related log -``` - -```{cfgcmd} set firewall global-options state-policy related log-level [emerg | alert | crit | err | warn | notice | info | debug] - -Set the global setting for related connections. -``` - -VyOS supports setting timeouts for connections by connection type. You can -set timeout values for generic connections, ICMP connections, UDP -connections, or TCP connections in various states. - -```{eval-rst} -.. cfgcmd:: set firewall global-options timeout icmp <1-21474836> - :defaultvalue: -.. cfgcmd:: set firewall global-options timeout other <1-21474836> - :defaultvalue: -.. cfgcmd:: set firewall global-options timeout tcp close <1-21474836> - :defaultvalue: -.. cfgcmd:: set firewall global-options timeout tcp close-wait <1-21474836> - :defaultvalue: -.. cfgcmd:: set firewall global-options timeout tcp established <1-21474836> - :defaultvalue: -.. cfgcmd:: set firewall global-options timeout tcp fin-wait <1-21474836> - :defaultvalue: -.. cfgcmd:: set firewall global-options timeout tcp last-ack <1-21474836> - :defaultvalue: -.. cfgcmd:: set firewall global-options timeout tcp syn-recv <1-21474836> - :defaultvalue: -.. cfgcmd:: set firewall global-options timeout tcp syn-sent <1-21474836> - :defaultvalue: -.. cfgcmd:: set firewall global-options timeout tcp time-wait <1-21474836> - :defaultvalue: -.. cfgcmd:: set firewall global-options timeout udp other <1-21474836> - :defaultvalue: -.. cfgcmd:: set firewall global-options timeout udp stream <1-21474836> - :defaultvalue: - - Set the timeout in seconds for a protocol or state. -``` \ No newline at end of file diff --git a/docs/configuration/firewall/md-groups.md b/docs/configuration/firewall/md-groups.md deleted file mode 100644 index 817f610e..00000000 --- a/docs/configuration/firewall/md-groups.md +++ /dev/null @@ -1,477 +0,0 @@ ---- -lastproofread: '2026-03-30' ---- - -(firewall-groups-configuration)= - -# Firewall groups - -## Configuration - -Firewall groups represent collections of IP addresses, networks, ports, -MAC addresses, domains, or interfaces. You can reference a group in firewall, -NAT, and policy route rules as either a source or destination matcher, and/or -as inbound or outbound in the case of interface groups. - -### Address Groups - -An **address group** contains a single IP address or IP address range. - -```{cfgcmd} set firewall group address-group \ address [address | address range] - -``` -```{cfgcmd} set firewall group ipv6-address-group \ address \ - -Define an IPv4 or IPv6 address group. - -:::{code-block} none -set firewall group address-group ADR-INSIDE-v4 address 192.168.0.1 -set firewall group address-group ADR-INSIDE-v4 address 10.0.0.1-10.0.0.8 -set firewall group ipv6-address-group ADR-INSIDE-v6 address 2001:db8::1 -::: -``` - -```{cfgcmd} set firewall group address-group \ description \ -``` - -```{cfgcmd} set firewall group ipv6-address-group \ description \ - -Provide an IPv4 or IPv6 address group description. -``` - -### Remote Groups - -A **remote-group** uses a URL that hosts a newline-delimited list of IPv4 -and/or IPv6 addresses, CIDRs, and ranges. VyOS pulls this list periodically -according to the frequency you define in the firewall **resolver-interval** -and loads matching entries into the group for use in rules. The list is cached -in persistent storage, so rules continue to function if updates fail. - -```{cfgcmd} set firewall group remote-group \ url \ - -Specify a remote list of IPv4 and/or IPv6 addresses, ranges, and CIDRs -to fetch. -``` - -```{cfgcmd} set firewall group remote-group \ description \ - -Set a description for a remote group. -``` - -The remote list format is flexible. VyOS attempts to parse the first word of -each line as an entry and skips lines it cannot match. Lines that begin with -an alphanumeric character but do not match valid IPv4 or IPv6 addresses, -ranges, or CIDRs are logged to the system log. The following examples show -acceptable formats that VyOS parses correctly: - -```none -127.0.0.1 -127.0.0.0/24 -127.0.0.1-127.0.0.254 -2001:db8::1 -2001:db8:cafe::/48 -2001:db8:cafe::1-2001:db8:cafe::ffff -``` - -### Network Groups - -**Network groups** accept IP networks in CIDR notation. You can add specific -IP addresses as a 32-bit prefix. If you need to add a mix of addresses and -networks, use a network group. - -```{cfgcmd} set firewall group network-group \ network \ -``` - -```{cfgcmd} set firewall group ipv6-network-group \ network \ - -Define an IPv4 or IPv6 network group. - -:::{code-block} none -set firewall group network-group NET-INSIDE-v4 network 192.168.0.0/24 -set firewall group network-group NET-INSIDE-v4 network 192.168.1.0/24 -set firewall group ipv6-network-group NET-INSIDE-v6 network 2001:db8::/64 -::: -``` - -```{cfgcmd} set firewall group network-group \ description \ -``` - -```{cfgcmd} set firewall group ipv6-network-group \ description \ - -Provide an IPv4 or IPv6 network group description. -``` - -### Interface Groups - -An **interface group** represents a collection of interfaces. - -```{cfgcmd} set firewall group interface-group \ interface \ - -Define an interface group. -Wildcard ``*`` is supported. For example: ``eth3*``. -Prepend the character ``!`` to invert the criteria. For example: ``!eth2``. -``` - -```none -set firewall group interface-group LAN interface bond1001 -set firewall group interface-group LAN interface eth3* -``` - -```{cfgcmd} set firewall group interface-group \ description \ - -Provide an interface group description. -``` - -### Port Groups - -A **port group** represents only port numbers, not the protocol. You can -reference port groups for either TCP or UDP. Create TCP and UDP groups -separately to avoid accidentally filtering unnecessary ports. Specify port -ranges by using `-`. - -```{cfgcmd} set firewall group port-group \ port [portname | portnumber | startport-endport] - -Define a port group. A port name can be any name defined in -/etc/services. For example, ``http``. - -:::{code-block} none -set firewall group port-group PORT-TCP-SERVER1 port http -set firewall group port-group PORT-TCP-SERVER1 port 443 -set firewall group port-group PORT-TCP-SERVER1 port 5000-5010 -::: -``` - -```{cfgcmd} set firewall group port-group \ description \ - -Provide a port group description. -``` - -### MAC Groups - -A **mac group** represents a collection of mac addresses. - -```{cfgcmd} set firewall group mac-group \ mac-address \ - -Define a mac group. -``` - -```none -set firewall group mac-group MAC-G01 mac-address 88:a4:c2:15:b6:4f -set firewall group mac-group MAC-G01 mac-address 4c:d5:77:c0:19:81 -``` - -```{cfgcmd} set firewall group mac-group \ description \ - -Provide a MAC group description. -``` - -### Domain Groups - -A **domain group** represents a collection of domains. - -```{cfgcmd} set firewall group domain-group \ address \ - -Define a domain group. -``` - -```none -set firewall group domain-group DOM address example.com -``` - -```{cfgcmd} set firewall group domain-group \ description \ - -Provide a domain group description. -``` - -### Dynamic Groups - -Firewall dynamic groups differ from other groups because you can use them as -source/destination in firewall rules, and members are not defined statically -in VyOS configuration. Instead, firewall rules dynamically add members to -these groups. - -#### Defining Dynamic Address Groups - -Dynamic address groups support both IPv4 and IPv6 families. Use these -commands to define dynamic IPv4 and IPv6 address groups: - -```{cfgcmd} set firewall group dynamic-group address-group \ -``` - -```{cfgcmd} set firewall group dynamic-group ipv6-address-group \ -``` - -Add description to firewall groups: - -```{cfgcmd} set firewall group dynamic-group address-group \ description \ -``` - -```{cfgcmd} set firewall group dynamic-group ipv6-address-group \ description \ -``` - -#### Adding elements to Dynamic Firewall Groups - -After you define dynamic firewall groups, use them in firewall rules to -dynamically add elements to them. - -Commands used for this task are: -- Add destination IP address of the connection to a dynamic address group: - -```{cfgcmd} set firewall ipv4 [forward | input | output] filter rule \<1-999999\> add-address-to-group destination-address address-group \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> add-address-to-group destination-address address-group \ -``` - -```{cfgcmd} set firewall ipv6 [forward | input | output] filter rule \<1-999999\> add-address-to-group destination-address address-group \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> add-address-to-group destination-address address-group \ -``` - -- Add source IP address of the connection to a dynamic address group: - -```{cfgcmd} set firewall ipv4 [forward | input | output] filter rule \<1-999999\> add-address-to-group source-address address-group \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> add-address-to-group source-address address-group \ -``` - -```{cfgcmd} set firewall ipv6 [forward | input | output] filter rule \<1-999999\> add-address-to-group source-address address-group \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> add-address-to-group source-address address-group \ -``` - -You can define specific timeouts per rule. When a rule matches, the source or -destination address is added to the group, and the element remains in the group -until the timeout expires. If you do not define a timeout, the element remains -in the group until the next reboot or until you commit firewall configuration -changes. - -```{cfgcmd} set firewall ipv4 [forward | input | output] filter rule \<1-999999\> add-address-to-group [destination-address | source-address] timeout \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> add-address-to-group [destination-address | source-address] timeout \ -``` - -```{cfgcmd} set firewall ipv6 [forward | input | output] filter rule \<1-999999\> add-address-to-group [destination-address | source-address] timeout \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> add-address-to-group [destination-address | source-address] timeout \ -``` - -Timeout can be defined using seconds, minutes, hours or days: - -```none -set firewall ipv6 name FOO rule 10 add-address-to-group source-address timeout -Possible completions: -s Timeout value in seconds -m Timeout value in minutes -h Timeout value in hours -d Timeout value in days -``` - -#### Using Dynamic Firewall Groups - -Like other firewall groups, you can use dynamic firewall groups in firewall -rules as matching options. For example: - -```none -set firewall ipv4 input filter rule 10 source group dynamic-address-group FOO -set firewall ipv4 input filter rule 10 destination group dynamic-address-group BAR -``` - -## Examples - -### General example - -After you create firewall groups, you can reference them in firewall, NAT, -NAT66, and/or policy-route rules. The following example creates multiple -groups: - -```{eval-rst} - .. code-block:: none - - set firewall group address-group SERVERS address 198.51.100.101 - set firewall group address-group SERVERS address 198.51.100.102 - set firewall group network-group TRUSTEDv4 network 192.0.2.0/30 - set firewall group network-group TRUSTEDv4 network 203.0.113.128/25 - set firewall group ipv6-network-group TRUSTEDv6 network 2001:db8::/64 - set firewall group interface-group LAN interface eth2.2001 - set firewall group interface-group LAN interface bon0 - set firewall group port-group PORT-SERVERS port http - set firewall group port-group PORT-SERVERS port 443 - set firewall group port-group PORT-SERVERS port 5000-5010 -``` - -And next, some configuration example where groups are used: - -```{eval-rst} - .. code-block:: none - - set firewall ipv4 output filter rule 10 action accept - set firewall ipv4 output filter rule 10 outbound-interface group !LAN - set firewall ipv4 forward filter rule 20 action accept - set firewall ipv4 forward filter rule 20 source group network-group TRUSTEDv4 - set firewall ipv6 input filter rule 10 action accept - set firewall ipv6 input filter rule 10 source group network-group TRUSTEDv6 - set nat destination rule 101 inbound-interface group LAN - set nat destination rule 101 destination group address-group SERVERS - set nat destination rule 101 protocol tcp - set nat destination rule 101 destination group port-group PORT-SERVERS - set nat destination rule 101 translation address 203.0.113.250 - set policy route PBR rule 201 destination group port-group PORT-SERVERS - set policy route PBR rule 201 protocol tcp - set policy route PBR rule 201 set table 15 -``` - -### Port knocking example - -You can use dynamic firewall groups with port knocking to secure access to -the router or any other device. The following example shows a 4-step port -knocking configuration: - -```{eval-rst} - .. code-block:: none - - set firewall global-options state-policy established action 'accept' - set firewall global-options state-policy invalid action 'drop' - set firewall global-options state-policy related action 'accept' - set firewall group dynamic-group address-group ALLOWED - set firewall group dynamic-group address-group PN_01 - set firewall group dynamic-group address-group PN_02 - set firewall ipv4 input filter default-action 'drop' - set firewall ipv4 input filter rule 5 action 'accept' - set firewall ipv4 input filter rule 5 protocol 'icmp' - set firewall ipv4 input filter rule 10 action 'drop' - set firewall ipv4 input filter rule 10 add-address-to-group source-address address-group 'PN_01' - set firewall ipv4 input filter rule 10 add-address-to-group source-address timeout '2m' - set firewall ipv4 input filter rule 10 description 'Port_nock 01' - set firewall ipv4 input filter rule 10 destination port '9990' - set firewall ipv4 input filter rule 10 protocol 'tcp' - set firewall ipv4 input filter rule 20 action 'drop' - set firewall ipv4 input filter rule 20 add-address-to-group source-address address-group 'PN_02' - set firewall ipv4 input filter rule 20 add-address-to-group source-address timeout '3m' - set firewall ipv4 input filter rule 20 description 'Port_nock 02' - set firewall ipv4 input filter rule 20 destination port '9991' - set firewall ipv4 input filter rule 20 protocol 'tcp' - set firewall ipv4 input filter rule 20 source group dynamic-address-group 'PN_01' - set firewall ipv4 input filter rule 30 action 'drop' - set firewall ipv4 input filter rule 30 add-address-to-group source-address address-group 'ALLOWED' - set firewall ipv4 input filter rule 30 add-address-to-group source-address timeout '2h' - set firewall ipv4 input filter rule 30 description 'Port_nock 03' - set firewall ipv4 input filter rule 30 destination port '9992' - set firewall ipv4 input filter rule 30 protocol 'tcp' - set firewall ipv4 input filter rule 30 source group dynamic-address-group 'PN_02' - set firewall ipv4 input filter rule 99 action 'accept' - set firewall ipv4 input filter rule 99 description 'Port_nock 04 - Allow ssh' - set firewall ipv4 input filter rule 99 destination port '22' - set firewall ipv4 input filter rule 99 protocol 'tcp' - set firewall ipv4 input filter rule 99 source group dynamic-address-group 'ALLOWED' -``` - -Before testing, we can check the members of firewall groups: - -```none -vyos@vyos# run show firewall group -Firewall Groups - -Name Type References Members Timeout Expires -------- ---------------------- -------------------- ------------- --------- --------- -ALLOWED address_group(dynamic) ipv4-input-filter-30 N/D N/D N/D -PN_01 address_group(dynamic) ipv4-input-filter-10 N/D N/D N/D -PN_02 address_group(dynamic) ipv4-input-filter-20 N/D N/D N/D -[edit] -vyos@vyos# -``` - -With this configuration, to gain SSH access to the router, the user must: - -1. Create a new TCP connection to destination port 9990. A new entry is added - to dynamic firewall group `PN_01`. - - ```none - vyos@vyos# run show firewall group - Firewall Groups - - Name Type References Members Timeout Expires - ------- ---------------------- -------------------- ------------- --------- --------- - ALLOWED address_group(dynamic) ipv4-input-filter-30 N/D N/D N/D - PN_01 address_group(dynamic) ipv4-input-filter-10 192.168.89.31 120 119 - PN_02 address_group(dynamic) ipv4-input-filter-20 N/D N/D N/D - [edit] - vyos@vyos# - ``` - -2. Create a new TCP connection to destination port 9991. A new entry is added - to dynamic firewall group `PN_02`. - - ```none - vyos@vyos# run show firewall group - Firewall Groups - - Name Type References Members Timeout Expires - ------- ---------------------- -------------------- ------------- --------- --------- - ALLOWED address_group(dynamic) ipv4-input-filter-30 N/D N/D N/D - PN_01 address_group(dynamic) ipv4-input-filter-10 192.168.89.31 120 106 - PN_02 address_group(dynamic) ipv4-input-filter-20 192.168.89.31 180 179 - [edit] - vyos@vyos# - ``` - -3. Create a new TCP connection to destination port 9992. A new entry is added - to dynamic firewall group `ALLOWED`. - - ```none - vyos@vyos# run show firewall group - Firewall Groups - - Name Type References Members Timeout Expires - ------- ---------------------- -------------------- ------------- --------- --------- - ALLOWED address_group(dynamic) ipv4-input-filter-30 192.168.89.31 7200 7199 - PN_01 address_group(dynamic) ipv4-input-filter-10 192.168.89.31 120 89 - PN_02 address_group(dynamic) ipv4-input-filter-20 192.168.89.31 180 170 - [edit] - vyos@vyos# - ``` - -4. Now you can connect via SSH to the router (assuming SSH is - configured). - -## Operation-mode - -```{opcmd} show firewall group -``` - -```{opcmd} show firewall group \ - -Display an overview of defined groups, including the firewall group name, -type, references (where the group is used), members, timeout, and -expiration (the last two only apply to dynamic firewall groups). -``` - -Here is an example of such command: - -```none -vyos@vyos:~$ show firewall group -Firewall Groups - -Name Type References Members Timeout Expires ------------- ---------------------- ---------------------- ---------------- --------- --------- -SERVERS address_group nat-destination-101 198.51.100.101 - 198.51.100.102 -ALLOWED address_group(dynamic) ipv4-input-filter-30 192.168.77.39 7200 7174 -PN_01 address_group(dynamic) ipv4-input-filter-10 192.168.0.245 120 112 - 192.168.77.39 120 85 -PN_02 address_group(dynamic) ipv4-input-filter-20 192.168.77.39 180 151 -LAN interface_group ipv4-output-filter-10 bon0 - nat-destination-101 eth2.2001 -TRUSTEDv6 ipv6_network_group ipv6-input-filter-10 2001:db8::/64 -TRUSTEDv4 network_group ipv4-forward-filter-20 192.0.2.0/30 - 203.0.113.128/25 -PORT-SERVERS port_group route-PBR-201 443 - route-PBR-201 5000-5010 - nat-destination-101 http -vyos@vyos:~$ -``` diff --git a/docs/configuration/firewall/md-index.md b/docs/configuration/firewall/md-index.md deleted file mode 100644 index 9108a800..00000000 --- a/docs/configuration/firewall/md-index.md +++ /dev/null @@ -1,278 +0,0 @@ ---- -lastproofread: '2026-03-30' ---- - -# Firewall - -:::{warning} -Due to a boot-time race condition, all interfaces initialize -before the firewall. This temporarily leaves the system open to all traffic -and poses a security risk. -::: - -VyOS uses Netfilter. The Netfilter -project developed `iptables` and its successor `nftables` for the Linux -kernel to process packet data flows directly. This extends the concept of -zone-based security to let you manipulate data at multiple stages after the -network interface and driver accept it, and before sending it to its -destination (for example, a web server or another device). - -The following is a simplified traffic flow diagram based on Netfilter -packet flow. -This diagram provides an overview of how packets are processed and the -possible paths traffic can take. - -:::{figure} /_static/images/firewall-gral-packet-flow.webp -::: - -The main points regarding packet flow and terminology in VyOS firewall -are: - -- **Bridge Port?**: Choose the appropriate path based on whether the - interface where the packet was received is part of a bridge. - -If the interface where the packet was received is not part of a bridge, the -packet is processed at the **IP Layer**: - -```{eval-rst} - * **Prerouting**: The router processes all packets in this stage, - regardless of the destination. You can perform several actions in - this stage, and these actions are also defined in different parts of the - VyOS configuration. Order is important. The relevant configuration that - applies in this stage includes: - - * **Firewall prerouting**: Rules you define under ``set firewall - [ipv4 | ipv6] prerouting raw...``. The system processes all rules in - this section before the connection tracking subsystem. - - * **Conntrack Ignore**: Rules you define under ``set system conntrack - ignore [ipv4 | ipv6] ...``. You can configure this section with - ``firewall [ipv4 | ipv6] prerouting ...``. For compatibility reasons, - this feature is supported, but will be deprecated in the future. - - * **Policy Route**: Rules you define under ``set policy [route | - route6] ...``. - - * **Destination NAT**: Rules you define under ``set [nat | nat66] - destination...``. - - * **Destination is the router?**: Choose the appropriate path based on the - destination IP address. Transit traffic continues to **forward**, while - traffic destined for the router continues to **input**. - - * **Input**: The stage where you filter and control traffic destined for - the router itself. This is where you enforce all rules for securing the - router. This includes IPv4 and IPv6 filtering rules, defined in: - - * ``set firewall ipv4 input filter ...``. - - * ``set firewall ipv6 input filter ...``. - - * **Forward**: The stage where you filter and control transit traffic. - This includes IPv4 and IPv6 filtering rules, defined in: - - * ``set firewall ipv4 forward filter ...``. - - * ``set firewall ipv6 forward filter ...``. - - * **Output**: The stage where you filter and control traffic that the - router originates. Note that this traffic comes from either a new - connection that an internal process on the VyOS router (such as NTP) - originates or a response to traffic the router receives externally through - **input** (for example, a response to an SSH login attempt). This includes - IPv4 and IPv6 rules, and two different sections apply: - - * **Output Prerouting**: ``set firewall [ipv4 | ipv6] output - raw ...``. As described in **Prerouting**, the system processes - rules in this section before the connection tracking subsystem. - - * **Output Filter**: ``set firewall [ipv4 | ipv6] output filter ...``. - - * **Postrouting**: As in **Prerouting**, you can perform several actions - defined in different parts of VyOS configuration in this stage. This - includes: - - * **Source NAT**: Rules you define under ``set [nat | nat66] - source...``. -``` - -If the interface where the packet was received is part of a bridge, the -packet is processed at the **Bridge Layer**: - -```{eval-rst} - * **Prerouting (Bridge)**: The bridge processes all packets it receives in - this stage, regardless of the destination. First, you can apply filters - here, or you can configure rules that ignore the connection tracking - system. The relevant configuration that applies: - - * ``set firewall bridge prerouting filter ...``. - - * **Forward (Bridge)**: The stage where you filter and control traffic - that passes through the bridge: - - * ``set firewall bridge forward filter ...``. - - * **Input (Bridge)**: The stage where you filter and control traffic - destined for the bridge itself: - - * ``set firewall bridge input filter ...``. - - * **Output (Bridge)**: The stage where you filter and control traffic that - the bridge originates: - - * ``set firewall bridge output filter ...``. -``` - -The following is the overall structure of the VyOS firewall CLI: - -```none -- set firewall - * bridge - - forward - + filter - - input - + filter - - output - + filter - - prerouting - + filter - - name - + custom_name - * flowtable - - custom_flow_table - + ... - * global-options - + all-ping - + broadcast-ping - + ... - * group - - address-group - - ipv6-address-group - - network-group - - ipv6-network-group - - interface-group - - mac-group - - port-group - - domain-group - * ipv4 - - forward - + filter - - input - + filter - - output - + filter - + raw - - prerouting - + raw - - name - + custom_name - * ipv6 - - forward - + filter - - input - + filter - - output - + filter - + raw - - prerouting - + raw - - ipv6-name - + custom_name - * zone - - custom_zone_name - + ... -``` - -Here is a list of VyOS firewall CLI subcommands and their -corresponding pages in the documentation: - -```{cfgcmd} set firewall bridge ... - -Configure bridge firewall rules for traffic at the bridge layer. -See the Bridge Firewall Configuration page for detailed information. -``` - -```{cfgcmd} set firewall flowtable ... - -Configure firewall flowtables for stateful connection tracking and rules. -See the Flowtables Firewall Configuration page for detailed information. -``` - -```{cfgcmd} set firewall global-options ... - -Configure global firewall options such as ``all-ping``, ``broadcast-ping``, -``syn-cookies``, and other system-wide firewall settings. -See the Global Firewall Options page for detailed information. -``` - -```{cfgcmd} set firewall group ... - -Organize firewall rules by creating reusable address, network, interface, -MAC, port, and domain groups. Use groups in multiple rules to simplify -configuration and maintenance. -See the Firewall Groups page for detailed information. -``` - -```{cfgcmd} set firewall ipv4 ... - -Configure IPv4-specific firewall rules. -See the IPv4 Firewall Configuration page for detailed information. -``` - -```{cfgcmd} set firewall ipv6 ... - -Configure IPv6-specific firewall rules. -See the IPv6 Firewall Configuration page for detailed information. -``` - -```{cfgcmd} set firewall zone ... - -Configure zone-based firewall policies for controlling traffic between -different network zones. -See the Zone-Based Firewall Configuration page for detailed information. -``` - -For more information on firewall configuration, see the following pages: - -```{toctree} -:includehidden: true -:maxdepth: 1 - -global-options -groups -bridge -ipv4 -ipv6 -flowtables -``` - -:::{note} -For more information on Netfilter hooks and Linux networking packet flows, -see the [Netfilter-Hooks]() -documentation. -::: - -## Zone-Based firewall - -```{toctree} -:includehidden: true -:maxdepth: 1 - -zone -``` - -With zone-based firewalls, a new concept applies. In addition to the standard -in and out traffic flows, a local flow enables traffic originating from and -destined to the router itself. This means you must configure additional rules to -secure the firewall from the network, in addition to the existing inbound and -outbound rules. - -To configure VyOS with zone-based firewall, see -{doc}`Zone-Based Firewall Configuration `. - -As the following example image shows, you must configure rules to allow or block -traffic to or from the services running on the device that have open -connections on that interface. - -:::{figure} /_static/images/firewall-zonebased.webp -::: diff --git a/docs/configuration/firewall/md-ipv4.md b/docs/configuration/firewall/md-ipv4.md deleted file mode 100644 index 2107065d..00000000 --- a/docs/configuration/firewall/md-ipv4.md +++ /dev/null @@ -1,1517 +0,0 @@ ---- -lastproofread: '2026-03-30' ---- - -(firewall-ipv4-configuration)= - -# IPv4 Firewall Configuration - -## Overview - -This section provides information on IPv4 firewall configuration and -appropriate operation-mode commands. This section covers the following -configuration commands: - -```{cfgcmd} set firewall ipv4 ... -``` - -To learn about the general traffic flow in VyOS firewalls, see {doc}`Firewall `. - -```none -- set firewall - * ipv4 - - forward - + filter - - input - + filter - - output - + filter - + raw - - prerouting - + raw - - name - + custom_name -``` - -First, the router receives all traffic and processes it in the **prerouting** -stage. - -This stage includes: - -- **Firewall Prerouting**: commands found under `set firewall ipv4 - prerouting raw ...` -- {doc}`Conntrack Ignore`: `set system - conntrack ignore ipv4...` -- {doc}`Policy Route`: commands found under - `set policy route ...` -- {doc}`Destination NAT`: commands found under - `set nat destination ...` - -For transit traffic, which is received by the router and forwarded, the base -chain is **forward**. The following is a simplified packet flow diagram for -transit traffic: - -:::{figure} /_static/images/firewall-fwd-packet-flow.webp -::: - -The base firewall chain for configuring filtering rules for transit traffic is -`set firewall ipv4 forward filter ...`, which occurs in stage 5, highlighted -in red. - -For traffic to the router itself, the base chain is **input**. For traffic -the router originates, the base chain is **output**. A simplified packet flow -diagram is shown next, which shows the path for traffic destined to the router -itself and traffic the router generates (starting from circle number 6): - -:::{figure} /_static/images/firewall-input-packet-flow.webp -::: - -The base chain for traffic towards the router is -`set firewall ipv4 input filter ...` - -The base chain for traffic the router generates is `set firewall ipv4 -output ...`, where two sub-chains are available: **filter** and **raw**: - -- **Output Prerouting**: `set firewall ipv4 output raw ...`. As described - in **Prerouting**, the system processes rules in this section before the - connection tracking subsystem. -- **Output Filter**: `set firewall ipv4 output filter ...`. The system - processes rules in this section after the connection tracking subsystem. - -:::{note} -**Important note about default-actions:** -If you do not define a default action for a base chain, the system sets -the default action to **accept** for that chain. For custom chains, if you -do not define a default action, the system sets the default-action to -**drop**. -::: - -You can create custom firewall chains using the following commands: -`set firewall ipv4 name ...`. To use a custom chain, you must define -a rule with the **action jump** and the appropriate **target** in a base -chain. - -## Firewall - IPv4 Rules - -Each firewall rule has a -number, an action to apply if the rule matches, and the ability to specify -multiple matching criteria. Packets traverse rules numbered 1-999999, so order -is crucial. The system executes the rule action at the first match. - -### Actions - -If you define a rule, you must define an action for it. The action tells the -firewall what to do if all the criteria you define for that rule are met. - -The action can be: - -- `accept`: Accept the packet. -- `continue`: Continue parsing the next rule. -- `drop`: Drop the packet. -- `reject`: Reject the packet. -- `jump`: Jump to another custom chain. -- `return`: Return from the current chain and continue at the next rule - of the last chain. -- `queue`: Enqueue packet to userspace. -- `synproxy`: Synproxy the packet. - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> action [accept | continue | drop | jump | queue | reject | return | synproxy] -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> action [accept | continue | drop | jump | queue | reject | return | synproxy] -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> action [accept | continue | drop | jump | queue | reject | return] -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> action [accept | continue | drop | jump | queue | reject | return] - -This required setting defines the action of the current rule. If you set -the action to jump, you must also specify a jump-target. -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> jump-target \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> jump-target \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> jump-target \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> jump-target \ - -Use this command only when the action is set to ``jump``. Specify the -jump target. -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> queue \<0-65535\> -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> queue \<0-65535\> -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> queue \<0-65535\> -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> queue \<0-65535\> - -Use this command only when the action is set to ``queue``. Specify the -queue target to use. Queue range is also supported. -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> queue-options bypass -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> queue-options bypass -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> queue-options bypass -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> queue-options bypass - -Use this command only when the action is set to ``queue``. Allow the packet -to pass through the firewall when no userspace software is connected to the -queue. -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> queue-options fanout -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> queue-options fanout -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> queue-options fanout -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> queue-options fanout - -Use this command only when the action is set to ``queue``. Distribute -packets between several queues. -``` - -Also, **default-action** is an action that applies when a packet does not -match any rule in its chain. For base chains, possible options for -**default-action** are **accept** or **drop**. - -```{cfgcmd} set firewall ipv4 forward filter default-action [accept | drop] -``` - -```{cfgcmd} set firewall ipv4 input filter default-action [accept | drop] -``` - -```{cfgcmd} set firewall ipv4 output filter default-action [accept | drop] -``` - -```{cfgcmd} set firewall ipv4 name \ default-action [accept | drop | jump | queue | reject | return] - -This command sets the default action of the rule-set if a packet does not -match the criteria of any rule. If you set the default-action to ``jump``, -you must also specify ``default-jump-target``. Note that for base chains, -you can set the default action only to ``accept`` or ``drop``, while on -custom chains, more actions are available. -``` - -```{cfgcmd} set firewall ipv4 name \ default-jump-target \ - -Use this command only when you set ``default-action`` to ``jump``. Specify -the jump target for the default rule. -``` -:::{note} -**Important note about default-actions:** -If you do not define a default action for a base chain, the system sets -the default action to **accept** for that chain. For custom chains, if you -do not define a default action, the system sets the default-action to -**drop**. -::: - -### Firewall Logs - -You can enable logging for every single firewall rule. If you enable logging, -you can define other log options. - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> log -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> log -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> log -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> log - -Enable logging for the matched packet. If this command is not present, then -logging is not enabled. -``` - -```{cfgcmd} set firewall ipv4 forward filter default-log -``` - -```{cfgcmd} set firewall ipv4 input filter default-log -``` - -```{cfgcmd} set firewall ipv4 output filter default-log -``` - -```{cfgcmd} set firewall ipv4 name \ default-log - -Use this command to enable logging of the default action on the specified -chain. -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> log-options level [emerg | alert | crit | err | warn | notice | info | debug] -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> log-options level [emerg | alert | crit | err | warn | notice | info | debug] -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> log-options level [emerg | alert | crit | err | warn | notice | info | debug] -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> log-options level [emerg | alert | crit | err | warn | notice | info | debug] - -Define the log level. Only applicable if you enable rule logging. -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> log-options group \<0-65535\> -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> log-options group \<0-65535\> -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> log-options group \<0-65535\> -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> log-options group \<0-65535\> - -Define the log group to send messages to. Only applicable if you enable rule -logging. -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> log-options snapshot-length \<0-9000\> -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> log-options snapshot-length \<0-9000\> -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> log-options snapshot-length \<0-9000\> -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> log-options snapshot-length \<0-9000\> - -Define the length of packet payload to include in a netlink message. Only -applicable if you enable rule logging and define the log group. -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> log-options queue-threshold \<0-65535\> -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> log-options queue-threshold \<0-65535\> -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> log-options queue-threshold \<0-65535\> -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> log-options queue-threshold \<0-65535\> - -Define the number of packets to queue inside the kernel before sending them -to userspace. Only applicable if you enable rule logging and define the log -group. -``` - -### Firewall Description - -You can add a description for reference for every single rule and for every -defined custom chain. - -```{cfgcmd} set firewall ipv4 name \ description \ - -Provide a rule-set description for a custom firewall chain. -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> description \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> description \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> description \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> description \ - -Provide a description for each rule. -``` - -### Rule Status - -When you define a rule, it is enabled by default. In some cases, it is useful -to disable the rule rather than removing it. - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> disable -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> disable -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> disable -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> disable - -Command for disabling a rule but keeping it in the configuration. -``` - -### Matching criteria - -There are a lot of matching criteria against which the packet can be tested. - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> connection-status nat [destination | source] -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> connection-status nat [destination | source] -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> connection-status nat [destination | source] -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> connection-status nat [destination | source] - -Match based on nat connection status. -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> connection-mark \<1-2147483647\> -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> connection-mark \<1-2147483647\> -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> connection-mark \<1-2147483647\> -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> connection-mark \<1-2147483647\> - -Match based on connection mark. -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> conntrack-helper \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> conntrack-helper \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> conntrack-helper \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> conntrack-helper \ - -Match based on connection tracking protocol helper module to secure use of -that helper module. See below for possible completions \. - -:::{code-block} none -Possible completions: -ftp Related traffic from FTP helper -h323 Related traffic from H.323 helper -pptp Related traffic from PPTP helper -nfs Related traffic from NFS helper -sip Related traffic from SIP helper -tftp Related traffic from TFTP helper -sqlnet Related traffic from SQLNet helper -::: -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> source address [address | addressrange | CIDR] -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> source address [address | addressrange | CIDR] -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> source address [address | addressrange | CIDR] -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> source address [address | addressrange | CIDR] -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> destination address [address | addressrange | CIDR] -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> destination address [address | addressrange | CIDR] -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> destination address [address | addressrange | CIDR] -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> destination address [address | addressrange | CIDR] - -Match criteria based on source and/or destination address. This is similar -to the network groups part, but here you are able to negate the matching -addresses. - -:::{code-block} none -set firewall ipv4 name FOO rule 50 source address 192.0.2.10-192.0.2.11 -# with a '!' the rule match everything except the specified subnet -set firewall ipv4 name FOO rule 51 source address !203.0.113.0/24 -::: -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> source address-mask [address] -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> source address-mask [address] -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> source address-mask [address] -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> source address-mask [address] -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> destination address-mask [address] -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> destination address-mask [address] -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> destination address-mask [address] -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> destination address-mask [address] - -An arbitrary netmask can be applied to mask addresses to only match against -a specific portion. - -This functions for both individual addresses and address groups. - -:::{code-block} none -# Match any IPv4 address with `11` as the 2nd octet and `13` as the forth octet -set firewall ipv4 name FOO rule 100 destination address 0.11.0.13 -set firewall ipv4 name FOO rule 100 destination address-mask 0.255.0.255 -::: -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> source fqdn \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> source fqdn \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> source fqdn \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> source fqdn \ -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> destination fqdn \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> destination fqdn \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> destination fqdn \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> destination fqdn \ - -Specify a Fully Qualified Domain Name as source/destination to match. Ensure -that the router is able to resolve this dns query. -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> source geoip country-code \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> source geoip country-code \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> source geoip country-code \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> source geoip country-code \ -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> destination geoip country-code \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> destination geoip country-code \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> destination geoip country-code \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> destination geoip country-code \ -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> source geoip inverse-match -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> source geoip inverse-match -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> source geoip inverse-match -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> source geoip inverse-match -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> destination geoip inverse-match -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> destination geoip inverse-match -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> destination geoip inverse-match -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> destination geoip inverse-match - -Match IP addresses based on its geolocation. More info: geoip matching. -Use inverse-match to match anything except the given country-codes. -``` - -Data is provided by DB-IP.com under CC-BY-4.0 license. Attribution required, -permits redistribution so we can include a database in images(~3MB -compressed). Includes cron script (manually callable by op-mode update -geoip) to keep database and rules updated. - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> source mac-address \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> source mac-address \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> source mac-address \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> source mac-address \ - -You can only specify a source mac-address to match. - -:::{code-block} none -set firewall ipv4 input filter rule 100 source mac-address 00:53:00:11:22:33 -set firewall ipv4 input filter rule 101 source mac-address !00:53:00:aa:12:34 -::: -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> source port [1-65535 | portname | start-end] -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> source port [1-65535 | portname | start-end] -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> source port [1-65535 | portname | start-end] -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> source port [1-65535 | portname | start-end] -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> destination port [1-65535 | portname | start-end] -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> destination port [1-65535 | portname | start-end] -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> destination port [1-65535 | portname | start-end] -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> destination port [1-65535 | portname | start-end] - -A port can be set by number or name as defined in ``/etc/services``. - -:::{code-block} none -set firewall ipv4 forward filter rule 10 source port '22' -set firewall ipv4 forward filter rule 11 source port '!http' -set firewall ipv4 forward filter rule 12 source port 'https' -::: -Multiple source ports can be specified as a comma-separated list. -The whole list can also be "negated" using ``!``. For example: -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> source group address-group \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> source group address-group \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> source group address-group \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> source group address-group \ -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> destination group address-group \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> destination group address-group \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> destination group address-group \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> destination group address-group \ - -Use a specific address-group. Prepending the character ``!`` to invert the -criteria to match is also supported. -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> source group dynamic-address-group \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> source group dynamic-address-group \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> source group dynamic-address-group \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> source group dynamic-address-group \ -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> destination group dynamic-address-group \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> destination group dynamic-address-group \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> destination group dynamic-address-group \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> destination group dynamic-address-group \ - -Use a specific dynamic-address-group. Prepending the character ``!`` to -invert the criteria to match is also supported. -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> source group network-group \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> source group network-group \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> source group network-group \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> source group network-group \ -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> destination group network-group \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> destination group network-group \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> destination group network-group \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> destination group network-group \ - -Use a specific network-group. Prepending the character ``!`` to invert the -criteria to match is also supported. -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> source group port-group \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> source group port-group \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> source group port-group \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> source group port-group \ -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> destination group port-group \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> destination group port-group \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> destination group port-group \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> destination group port-group \ - -Use a specific port-group. Prepending the character ``!`` to invert the -criteria to match is also supported. -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> source group domain-group \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> source group domain-group \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> source group domain-group \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> source group domain-group \ -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> destination group domain-group \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> destination group domain-group \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> destination group domain-group \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> destination group domain-group \ - -Use a specific domain-group. Prepending the character ``!`` to invert the -criteria to match is also supported. -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> source group mac-group \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> source group mac-group \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> source group mac-group \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> source group mac-group \ -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> destination group mac-group \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> destination group mac-group \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> destination group mac-group \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> destination group mac-group \ - -Use a specific mac-group. Prepending the character ``!`` to invert the -criteria to match is also supported. -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> dscp [0-63 | start-end] -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> dscp [0-63 | start-end] -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> dscp [0-63 | start-end] -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> dscp [0-63 | start-end] -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> dscp-exclude [0-63 | start-end] -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> dscp-exclude [0-63 | start-end] -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> dscp-exclude [0-63 | start-end] -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> dscp-exclude [0-63 | start-end] - -Match based on dscp value. -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> fragment [match-frag | match-non-frag] -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> fragment [match-frag | match-non-frag] -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> fragment [match-frag | match-non-frag] -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> fragment [match-frag | match-non-frag] - -Match based on fragmentation. -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> icmp [code | type] \<0-255\> -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> icmp [code | type] \<0-255\> -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> icmp [code | type] \<0-255\> -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> icmp [code | type] \<0-255\> - -Match based on icmp code and type. -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> icmp type-name \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> icmp type-name \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> icmp type-name \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> icmp type-name \ - -Match based on icmp type-name. Use tab for information -about what **type-name** criteria are supported. -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> inbound-interface name \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> inbound-interface name \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> inbound-interface name \ - -Match based on inbound interface. Wildcard ``*`` is supported. For example: -``eth2*``. Prepend the character ``!`` to invert the criteria. For example: -``!eth2`` -``` -:::{note} -If an interface is attached to a non-default vrf, when using -**inbound-interface**, the vrf name must be used. For example `set firewall -ipv4 forward filter rule 10 inbound-interface name MGMT` -::: -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> inbound-interface group \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> inbound-interface group \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> inbound-interface group \ - -Match based on the inbound interface group. Prepend the character ``!`` to -invert the criteria. For example, ``!IFACE_GROUP`` -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> outbound-interface name \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> outbound-interface name \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> outbound-interface name \ - -Match based on outbound interface. Wildcard ``*`` is supported. For example: -``eth2*``. Prepend the character ``!`` to invert the criteria. For example: -``!eth2`` -``` -:::{note} -If an interface is attached to a non-default vrf, when using -**outbound-interface**, the real interface name must be used. For example -`set firewall ipv4 forward filter rule 10 outbound-interface name eth0` -::: -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> outbound-interface group \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> outbound-interface group \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> outbound-interface group \ - -Match based on outbound interface group. Prepend the character ``!`` to -invert the criteria. For example: ``!IFACE_GROUP`` -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> ipsec [match-ipsec-in | match-ipsec-out | match-none-in | match-none-out] -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> ipsec [match-ipsec-in | match-none-in] -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> ipsec [match-ipsec-out | match-none-out] -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> ipsec [match-ipsec-in | match-ipsec-out | match-none-in | match-none-out] - -Match based on ipsec. -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> limit burst \<0-4294967295\> -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> limit burst \<0-4294967295\> -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> limit burst \<0-4294967295\> -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> limit burst \<0-4294967295\> - -Match based on the maximum number of packets to allow in excess of rate. -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> limit rate \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> limit rate \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> limit rate \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> limit rate \ - -Specify the maximum average rate as **integer/unit**. For example: -**5/minutes** -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> packet-length \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> packet-length \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> packet-length \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> packet-length \ -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> packet-length-exclude \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> packet-length-exclude \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> packet-length-exclude \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> packet-length-exclude \ - -Match based on packet length. Specify multiple values from 1 to 65535 and -ranges. -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> packet-type [broadcast | host | multicast | other] -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> packet-type [broadcast | host | multicast | other] -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> packet-type [broadcast | host | multicast | other] -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> packet-type [broadcast | host | multicast | other] - -Match based on the packet type. -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> protocol [\ | \<0-255\> | all | tcp_udp] -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> protocol [\ | \<0-255\> | all | tcp_udp] -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> protocol [\ | \<0-255\> | all | tcp_udp] -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> protocol [\ | \<0-255\> | all | tcp_udp] - -Match based on protocol number or name as defined in ``/etc/protocols``. -Special names are ``all`` for all protocols and ``tcp_udp`` for TCP and UDP -based packets. The ``!`` character negates the selected protocol. - -:::{code-block} none -set firewall ipv4 forward filter rule 10 protocol tcp_udp -set firewall ipv4 forward filter rule 11 protocol !tcp_udp -::: -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> recent count \<1-255\> -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> recent count \<1-255\> -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> recent count \<1-255\> -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> recent count \<1-255\> -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> recent time [second | minute | hour] -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> recent time [second | minute | hour] -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> recent time [second | minute | hour] -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> recent time [second | minute | hour] - -Match based on recently seen sources. -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> tcp flags [not] \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> tcp flags [not] \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> tcp flags [not] \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> tcp flags [not] \ - -Specify TCP flags. Allowed values are ``ack``, ``cwr``, ``ecn``, ``fin``, -``psh``, ``rst``, ``syn``, and ``urg``. Specify multiple values, and use -``not`` for inverted selection, as shown in the example. - -:::{code-block} none -set firewall ipv4 input filter rule 10 tcp flags 'ack' -set firewall ipv4 input filter rule 12 tcp flags 'syn' -set firewall ipv4 input filter rule 13 tcp flags not 'fin' -::: -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> state [established | invalid | new | related] -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> state [established | invalid | new | related] -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> state [established | invalid | new | related] -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> state [established | invalid | new | related] - -Match against the state of a packet. -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> time startdate \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> time startdate \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> time startdate \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> time startdate \ -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> time starttime \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> time starttime \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> time starttime \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> time starttime \ -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> time stopdate \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> time stopdate \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> time stopdate \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> time stopdate \ -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> time stoptime \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> time stoptime \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> time stoptime \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> time stoptime \ -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> time weekdays \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> time weekdays \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> time weekdays \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> time weekdays \ - -Time to match the defined rule. -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> ttl \ \<0-255\> -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> ttl \ \<0-255\> -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> ttl \ \<0-255\> -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> ttl \ \<0-255\> - -Match the time to live parameter, where 'eq' means 'equal', 'gt' means -'greater than', and 'lt' means 'less than'. -``` - -### Packet Modifications - -Starting from **VyOS-1.5-rolling-202410060007**, the firewall can modify -packets before sending them out. This feature provides more flexibility in -packet handling. - -```{cfgcmd} set firewall ipv4 prerouting raw rule \<1-999999\> set dscp \<0-63\> -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> set dscp \<0-63\> -``` - -```{cfgcmd} set firewall ipv4 output [filter | raw] rule \<1-999999\> set dscp \<0-63\> - -Set a specific value of Differentiated Services Codepoint (DSCP). -``` - -```{cfgcmd} set firewall ipv4 prerouting raw rule \<1-999999\> set mark \<1-2147483647\> -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> set mark \<1-2147483647\> -``` - -```{cfgcmd} set firewall ipv4 output [filter | raw] rule \<1-999999\> set mark \<1-2147483647\> - -Set a specific packet mark value. -``` - -```{cfgcmd} set firewall ipv4 prerouting raw rule \<1-999999\> set tcp-mss \<500-1460\> -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> set tcp-mss \<500-1460\> -``` - -```{cfgcmd} set firewall ipv4 output [filter | raw] rule \<1-999999\> set tcp-mss \<500-1460\> - -Set the TCP-MSS (TCP maximum segment size) for the connection. -``` - -```{cfgcmd} set firewall ipv4 prerouting raw rule \<1-999999\> set ttl \<0-255\> -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> set ttl \<0-255\> -``` - -```{cfgcmd} set firewall ipv4 output [filter | raw] rule \<1-999999\> set ttl \<0-255\> - -Set the TTL (Time to Live) value. -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> set connection-mark \<0-2147483647\> -``` - -```{cfgcmd} set firewall ipv4 output [filter | raw] rule \<1-999999\> set connection-mark \<0-2147483647\> - -Set connection mark value. -``` - -## Synproxy - -Synproxy connections - -```{cfgcmd} set firewall ipv4 [input | forward] filter rule \<1-999999\> action synproxy -``` - -```{cfgcmd} set firewall ipv4 [input | forward] filter rule \<1-999999\> protocol tcp -``` - -```{cfgcmd} set firewall ipv4 [input | forward] filter rule \<1-999999\> synproxy tcp mss \<501-65535\> - - Set the TCP-MSS (maximum segment size) for the connection -``` - -```{cfgcmd} set firewall ipv4 [input | forward] filter rule \<1-999999\> synproxy tcp window-scale \<1-14\> - - Set the window scale factor for TCP window scaling -``` - -### Example synproxy - -Requirements to enable synproxy: - -- Traffic must be symmetric. -- Synproxy relies on syncookies and TCP timestamps, ensure these are enabled. -- Disable conntrack loose track option. - -```none -set system sysctl parameter net.ipv4.tcp_timestamps value '1' - -set system conntrack tcp loose disable - -set system conntrack ignore ipv4 rule 10 destination port '8080' - -set system conntrack ignore ipv4 rule 10 protocol 'tcp' - -set system conntrack ignore ipv4 rule 10 tcp flags syn - -set firewall global-options syn-cookies 'enable' - -set firewall ipv4 input filter rule 10 action 'synproxy' - -set firewall ipv4 input filter rule 10 destination port '8080' - -set firewall ipv4 input filter rule 10 inbound-interface name 'eth1' - -set firewall ipv4 input filter rule 10 protocol 'tcp' - -set firewall ipv4 input filter rule 10 synproxy tcp mss '1460' - -set firewall ipv4 input filter rule 10 synproxy tcp window-scale '7' - -set firewall ipv4 input filter rule 1000 action 'drop' - -set firewall ipv4 input filter rule 1000 state invalid - -``` - -## Operation-mode Firewall - -### Rule-set overview - -```{opcmd} show firewall - -This will show you a basic firewall overview, for all rule-sets, not -only for IPv4. - -:::{code-block} none -vyos@vyos:~$ show firewall -Rulesets Information - ---------------------------------- -ipv4 Firewall "forward filter" - -Rule Action Protocol Packets Bytes Conditions -------- -------- ---------- --------- ------- ----------------------------- -20 accept all 0 0 ip saddr @N_TRUSTEDv4 accept -21 jump all 0 0 jump NAME_AUX -default accept all 0 0 - ---------------------------------- -ipv4 Firewall "input filter" - -Rule Action Protocol Packets Bytes Conditions -------- -------- ---------- --------- ------- ------------------------- -10 accept all 156 14377 iifname != @I_LAN accept -default accept all 0 0 - ---------------------------------- -ipv4 Firewall "name AUX" - -Rule Action Protocol Packets Bytes Conditions ------- -------- ---------- --------- ------- -------------------------------------------- -10 accept icmp 0 0 meta l4proto icmp accept -20 accept udp 0 0 meta l4proto udp ip saddr @A_SERVERS accept -30 drop all 0 0 ip saddr != @A_SERVERS iifname "eth2" - ---------------------------------- -ipv4 Firewall "output filter" - -Rule Action Protocol Packets Bytes Conditions -------- -------- ---------- --------- ------- ---------------------------------------- -10 reject all 0 0 oifname @I_LAN -20 accept icmp 2 168 meta l4proto icmp oifname "eth0" accept -default accept all 72 9258 - ---------------------------------- -ipv6 Firewall "input filter" - -Rule Action Protocol Packets Bytes Conditions -------- -------- ---------- --------- ------- ------------------------------- -10 accept all 0 0 ip6 saddr @N6_TRUSTEDv6 accept -default accept all 2 112 - -vyos@vyos:~$ -::: -``` - -```{opcmd} show firewall summary - -This shows you a summary of rule-sets and groups. - -:::{code-block} none -vyos@vyos:~$ show firewall summary -Ruleset Summary - -IPv6 Ruleset: - -Ruleset Hook Ruleset Priority Description --------------- -------------------- ------------------------- -forward filter -input filter -ipv6_name IPV6-VyOS_MANAGEMENT -ipv6_name IPV6-WAN_IN PUBLIC_INTERNET - -IPv4 Ruleset: - -Ruleset Hook Ruleset Priority Description --------------- ------------------ ------------------------- -forward filter -input filter -name VyOS_MANAGEMENT -name WAN_IN PUBLIC_INTERNET - -Firewall Groups - -Name Type References Members ------------------------ ------------------ ----------------------- ---------------- -PBX address_group WAN_IN-100 198.51.100.77 -SERVERS address_group WAN_IN-110 192.0.2.10 -WAN_IN-111 192.0.2.11 -WAN_IN-112 192.0.2.12 -WAN_IN-120 -WAN_IN-121 -WAN_IN-122 -SUPPORT address_group VyOS_MANAGEMENT-20 192.168.1.2 -WAN_IN-20 -PHONE_VPN_SERVERS address_group WAN_IN-160 10.6.32.2 -PINGABLE_ADRESSES address_group WAN_IN-170 192.168.5.2 -WAN_IN-171 -PBX ipv6_address_group IPV6-WAN_IN-100 2001:db8::1 -SERVERS ipv6_address_group IPV6-WAN_IN-110 2001:db8::2 -IPV6-WAN_IN-111 2001:db8::3 -IPV6-WAN_IN-112 2001:db8::4 -IPV6-WAN_IN-120 -IPV6-WAN_IN-121 -IPV6-WAN_IN-122 -SUPPORT ipv6_address_group IPV6-VyOS_MANAGEMENT-20 2001:db8::5 -IPV6-WAN_IN-20 -::: -``` - -```{opcmd} show firewall ipv4 [forward | input | output] filter -``` - -```{opcmd} show firewall ipv4 name \ - -This command will give an overview of a single rule-set. - -:::{code-block} none -vyos@vyos:~$ show firewall ipv4 input filter -Ruleset Information ---------------------------------- -IPv4 Firewall "input filter" -Rule Action Protocol Packets Bytes Conditions -------- -------- ---------- --------- ------- ----------------------------------------- -5 jump all 0 0 iifname "eth2" jump NAME_VyOS_MANAGEMENT -default accept all -::: -``` - -```{opcmd} show firewall ipv4 [forward | input | output] filter rule \<1-999999\> -``` - -```{opcmd} show firewall ipv4 name \ rule \<1-999999\> - -This command gives an overview of a rule in a single rule-set, plus -information for default action. -``` -```none -vyos@vyos:~$show firewall ipv4 output filter rule 20 -Rule Information - ---------------------------------- -ipv4 Firewall "output filter" - -Rule Action Protocol Packets Bytes Conditions -------- -------- ---------- --------- ------- ---------------------------------------- -20 accept icmp 2 168 meta l4proto icmp oifname "eth0" accept -default accept all 286 47614 - -vyos@vyos:~$ -``` - -```{opcmd} show firewall statistics - -This will show you statistics of all rule-sets since the last boot. -``` - -### Show Firewall log - -```{opcmd} show log firewall - -``` -```{opcmd} show log firewall ipv4 -``` - -```{opcmd} show log firewall ipv4 [forward | input | output | name] -``` - -```{opcmd} show log firewall ipv4 [forward | input | output] filter -``` - -```{opcmd} show log firewall ipv4 name \ -``` - -```{opcmd} show log firewall ipv4 [forward | input | output] filter rule \ -``` - -```{opcmd} show log firewall ipv4 name \ rule \ - -Show the logs of all firewall; show all IPv4 firewall logs; show all logs -for particular hook; show all logs for particular hook and priority; -show all logs for particular custom chain; show logs for specific rule-set. -``` - -### Example Partial Config - -```none -firewall { - group { - network-group BAD-NETWORKS { - network 198.51.100.0/24 - network 203.0.113.0/24 - } - network-group GOOD-NETWORKS { - network 192.0.2.0/24 - } - port-group BAD-PORTS { - port 65535 - } - } - ipv4 { - forward { - filter { - default-action accept - rule 5 { - action accept - source { - group { - network-group GOOD-NETWORKS - } - } - } - rule 10 { - action drop - description "Bad Networks" - protocol all - source { - group { - network-group BAD-NETWORKS - } - } - } - } - } - } -} -``` - -### Update geoip database - -```{opcmd} update geoip - -Command to update GeoIP database and firewall sets. -``` \ No newline at end of file diff --git a/docs/configuration/firewall/md-ipv6.md b/docs/configuration/firewall/md-ipv6.md deleted file mode 100644 index 770cb146..00000000 --- a/docs/configuration/firewall/md-ipv6.md +++ /dev/null @@ -1,1567 +0,0 @@ ---- -lastproofread: '2026-04-01' ---- - -(firewall-ipv6-configuration)= - -# IPv6 Firewall Configuration - -## Overview - -This section covers useful information about IPv6 firewall configuration and -appropriate operation-mode commands. - -This section describes the following configuration commands: - -```{cfgcmd} set firewall ipv6 ... -``` - -To learn about the general traffic flow in VyOS firewalls, see {doc}`Firewall `. - -```none -- set firewall - * ipv6 - - forward - + filter - - input - + filter - - output - + filter - + raw - - prerouting - + raw - - name - + custom_name -``` - -The router first receives all traffic and processes it in the **prerouting** -section. - - -This stage includes: - - -- **Firewall Prerouting**: commands found under `set firewall ipv6 - prerouting raw ...` -- {doc}`Conntrack Ignore`: `set system - conntrack ignore ipv6...` -- {doc}`Policy Route`: commands found under - `set policy route6 ...` -- {doc}`Destination NAT`: commands found under - `set nat66 destination ...` - - -For transit traffic that the router receives and forwards, the base chain is -**forward**. The following diagram shows a simplified packet flow for transit -traffic: - - -:::{figure} /_static/images/firewall-fwd-packet-flow.webp -::: - - -Use `set firewall ipv6 forward filter ...` to configure filtering rules for -transit traffic. This command corresponds to stage 5 and is highlighted in red -in the diagram. - - -For traffic destined to the router, use the **input** chain. For traffic the -router generates, use the **output** chain. The following diagram shows the -packet flow for traffic destined to the router and traffic generated by the -router (starting from circle number 6): - - -:::{figure} /_static/images/firewall-input-packet-flow.webp -::: - - -Use `set firewall ipv6 input filter ...` to configure traffic destined to -the router. - - -Use `set firewall ipv6 output ...` to configure traffic the router generates. -Two sub-chains are available: **filter** and **raw**: - - -- **Output Prerouting**: `set firewall ipv6 output raw ...`. - As described in **Prerouting**, the firewall processes rules in this - section before the connection tracking subsystem. -- **Output Filter**: `set firewall ipv6 output filter ...`. The firewall - processes rules in this section after the connection tracking subsystem. - - -:::{note} -**Important note about default-actions:** -If you do not define a default action for a base chain, the system sets -the default action to **accept** for that chain. For custom chains, if you -do not define a default action, the system sets the default-action to -**drop** -::: - - -Create custom firewall chains using the commands -`set firewall ipv6 name ...`. To use the custom chain, define a -rule with **action jump** and the appropriate **target** in a base chain. - - -## Firewall - IPv6 Rules - - -Create firewall rules for firewall filtering. Each rule is numbered and has -an action to apply when the rule is matched. You can specify multiple matching -criteria. Packets go through rules from 1 - 999999, so order is crucial. The -firewall executes the action of the first matching rule. - - -### Actions - - -If you define a rule, you must define an action for it. The action tells the -firewall what to do when all criteria for that rule are met. - - -The action can be : - - -- `accept`: accept the packet. -- `continue`: continue parsing next rule. -- `drop`: drop the packet. -- `reject`: reject the packet. -- `jump`: jump to another custom chain. -- `return`: Return from the current chain and continue at the next rule - of the last chain. -- `queue`: Enqueue packet to userspace. -- `synproxy`: synproxy the packet. - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> action [accept | continue | drop | jump | queue | reject | return | synproxy] -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> action [accept | continue | drop | jump | queue | reject | return | synproxy] -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> action [accept | continue | drop | jump | queue | reject | return] -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> action [accept | continue | drop | jump | queue | reject | return] - -This required setting defines the action of the current rule. If you set -the action to jump, you must also define a jump-target. -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> jump-target \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> jump-target \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> jump-target \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> jump-target \ - -Use this command only when action is set to ``jump``. Specify the jump -target. -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> queue \<0-65535\> -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> queue \<0-65535\> -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> queue \<0-65535\> -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> queue \<0-65535\> - -Use this command only when action is set to ``queue``. Specify the queue -target. Queue ranges are also supported. -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> queue-options bypass -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> queue-options bypass -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> queue-options bypass -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> queue-options bypass - -Use this command only when action is set to ``queue``. This command allows -the packet to go through the firewall when no userspace software is connected -to the queue. -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> queue-options fanout -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> queue-options fanout -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> queue-options fanout -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> queue-options fanout - -Use this command only when action is set to ``queue``. This command -distributes packets among multiple queues. -``` - -Also, **default-action** is an action that takes place whenever a packet does -not match any rule in its chain. For base chains, possible options for -**default-action** are **accept** or **drop**. - -```{cfgcmd} set firewall ipv6 forward filter default-action [accept | drop] -``` - -```{cfgcmd} set firewall ipv6 input filter default-action [accept | drop] -``` - -```{cfgcmd} set firewall ipv6 output filter default-action [accept | drop] -``` - -```{cfgcmd} set firewall ipv6 name \ default-action [accept | drop | jump | queue | reject | return] - -Set the default action of the rule-set if a packet does not match any rule -criteria. If you set default-action to ``jump``, you must also define -``default-jump-target``. For base chains, you can only set the default -action to ``accept`` or ``drop``. For custom chains, more actions are -available. -``` - -```{cfgcmd} set firewall ipv6 name \ default-jump-target \ - -To be used only when ``default-action`` is set to ``jump``. Use this -command to specify the jump target for the default rule. -``` -:::{note} -**Important note about default-actions:** -If you do not define the default action for a base chain, the system sets -the default action to **accept** for that chain. For custom chains, if you -do not define a default action, the system sets the default-action to -**drop**. -::: - - -### Firewall Logs - - -You can enable logging for each firewall rule. When enabled, you can also -define other log options. - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> log -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> log -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> log -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> log - -Enable logging for matched packets. If this configuration command is not -present, logging is disabled. -``` - -```{cfgcmd} set firewall ipv6 forward filter default-log -``` - -```{cfgcmd} set firewall ipv6 input filter default-log -``` - -```{cfgcmd} set firewall ipv6 output filter default-log -``` - -```{cfgcmd} set firewall ipv6 name \ default-log - -Use this command to enable the logging of the default action on -the specified chain. -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> log-options level [emerg | alert | crit | err | warn | notice | info | debug] -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> log-options level [emerg | alert | crit | err | warn | notice | info | debug] -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> log-options level [emerg | alert | crit | err | warn | notice | info | debug] -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> log-options level [emerg | alert | crit | err | warn | notice | info | debug] - -Define log-level. Only applicable if rule log is enabled. -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> log-options group \<0-65535\> -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> log-options group \<0-65535\> -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> log-options group \<0-65535\> -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> log-options group \<0-65535\> - -Define the log group to send messages to. Only applicable if rule log is -enabled. -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> log-options snapshot-length \<0-9000\> -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> log-options snapshot-length \<0-9000\> -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> log-options snapshot-length \<0-9000\> -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> log-options snapshot-length \<0-9000\> - -Define the length of packet payload to include in a netlink message. Only -applicable when rule logging is enabled and log group is defined. -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> log-options queue-threshold \<0-65535\> -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> log-options queue-threshold \<0-65535\> -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> log-options queue-threshold \<0-65535\> -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> log-options queue-threshold \<0-65535\> - -Define the number of packets to queue inside the kernel before sending them -to userspace. Only applicable when rule logging is enabled and log group is -defined. -``` - -### Firewall Description - - -For reference, you can define descriptions on every rule and custom chain. - -```{cfgcmd} set firewall ipv6 name \ description \ - -Provide a rule-set description to a custom firewall chain. -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> description \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> description \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> description \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> description \ - -Provide a description for each rule. -``` - -### Rule Status - - -New rules are enabled by default. In some cases, you may want to disable a -rule rather than remove it. - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> disable -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> disable -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> disable -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> disable - -Command for disabling a rule but keep it in the configuration. -``` - -### Matching criteria - - -There are a lot of matching criteria against which the packet can be tested. - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> connection-status nat [destination | source] -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> connection-status nat [destination | source] -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> connection-status nat [destination | source] -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> connection-status nat [destination | source] - -Match packets based on NAT connection status. -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> connection-mark \<1-2147483647\> -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> connection-mark \<1-2147483647\> -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> connection-mark \<1-2147483647\> -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> connection-mark \<1-2147483647\> - -Match packets based on connection mark. -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> source address [address | addressrange | CIDR] -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> source address [address | addressrange | CIDR] -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> source address [address | addressrange | CIDR] -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> source address [address | addressrange | CIDR] -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> destination address [address | addressrange | CIDR] -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> destination address [address | addressrange | CIDR] -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> destination address [address | addressrange | CIDR] -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> destination address [address | addressrange | CIDR] - -Match based on source or destination address. This is similar to network -groups, but you can negate the matching addresses here. - -:::{code-block} none -set firewall ipv6 name FOO rule 100 source address 2001:db8::202 -::: -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> source address-mask [address] -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> source address-mask [address] -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> source address-mask [address] -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> source address-mask [address] -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> destination address-mask [address] -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> destination address-mask [address] -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> destination address-mask [address] -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> destination address-mask [address] - -Apply an arbitrary netmask to mask addresses and match only a specific -portion. This is useful for IPv6 because rules remain valid when the IPv6 -prefix changes if the host portion of the system's IPv6 address is static. -Examples include SLAAC and tokenised IPv6 addresses - -This function works for both individual addresses and address groups. - - -:::{code-block} none -# Match any IPv6 address with the suffix ::0000:0000:0000:beef -set firewall ipv6 forward filter rule 100 destination address ::beef -set firewall ipv6 forward filter rule 100 destination address-mask ::ffff:ffff:ffff:ffff -# Address groups -set firewall group ipv6-address-group WEBSERVERS address ::1000 -set firewall group ipv6-address-group WEBSERVERS address ::2000 -set firewall ipv6 forward filter rule 200 source group address-group WEBSERVERS -set firewall ipv6 forward filter rule 200 source address-mask ::ffff:ffff:ffff:ffff -::: -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> source fqdn \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> source fqdn \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> source fqdn \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> source fqdn \ -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> destination fqdn \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> destination fqdn \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> destination fqdn \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> destination fqdn \ - -Specify a Fully Qualified Domain Name as source or destination to match. -Ensure that the router can resolve the DNS query. -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> source geoip country-code \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> source geoip country-code \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> source geoip country-code \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> source geoip country-code \ -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> destination geoip country-code \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> destination geoip country-code \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> destination geoip country-code \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> destination geoip country-code \ -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> source geoip inverse-match -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> source geoip inverse-match -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> source geoip inverse-match -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> source geoip inverse-match -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> destination geoip inverse-match -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> destination geoip inverse-match -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> destination geoip inverse-match -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> destination geoip inverse-match - -Match IP addresses based on their geolocation. For more information, see -GeoIP matching. -Use inverse-match to match anything except the specified country codes. -``` - -DB-IP.com provides data under CC-BY-4.0 license. Attribution is required and -redistribution is permitted, allowing VyOS to include a database in images -(approximately 3 MB compressed). The package includes a cron script that you -can manually call through op-mode update geoip to keep the database and rules -updated. - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> source mac-address \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> source mac-address \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> source mac-address \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> source mac-address \ - -You can specify only a source MAC address to match. - -:::{code-block} none -set firewall ipv6 input filter rule 100 source mac-address 00:53:00:11:22:33 -set firewall ipv6 input filter rule 101 source mac-address !00:53:00:aa:12:34 -::: -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> source port [1-65535 | portname | start-end] -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> source port [1-65535 | portname | start-end] -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> source port [1-65535 | portname | start-end] -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> source port [1-65535 | portname | start-end] -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> destination port [1-65535 | portname | start-end] -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> destination port [1-65535 | portname | start-end] -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> destination port [1-65535 | portname | start-end] -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> destination port [1-65535 | portname | start-end] - -Specify a port by number or by name as defined in ``/etc/services``. - -:::{code-block} none -set firewall ipv6 forward filter rule 10 source port '22' -set firewall ipv6 forward filter rule 11 source port '!http' -set firewall ipv6 forward filter rule 12 source port 'https' -::: -Multiple source ports can be specified as a comma-separated list. -The whole list can also be "negated" using ``!``. For example: - -:::{code-block} none -set firewall ipv6 forward filter rule 10 source port '!22,https,3333-3338' -::: -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> source group address-group \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> source group address-group \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> source group address-group \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> source group address-group \ -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> destination group address-group \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> destination group address-group \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> destination group address-group \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> destination group address-group \ - -Specify an address group. You can prepend the character ``!`` to invert the -matching criteria. -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> source group dynamic-address-group \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> source group dynamic-address-group \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> source group dynamic-address-group \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> source group dynamic-address-group \ -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> destination group dynamic-address-group \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> destination group dynamic-address-group \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> destination group dynamic-address-group \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> destination group dynamic-address-group \ - -Specify a dynamic address group. You can prepend the character ``!`` to -invert the matching criteria. -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> source group network-group \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> source group network-group \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> source group network-group \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> source group network-group \ -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> destination group network-group \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> destination group network-group \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> destination group network-group \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> destination group network-group \ - -Specify a network group. You can prepend the character ``!`` to invert the -matching criteria. -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> source group port-group \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> source group port-group \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> source group port-group \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> source group port-group \ -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> destination group port-group \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> destination group port-group \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> destination group port-group \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> destination group port-group \ - -Specify a port group. You can prepend the character ``!`` to invert the -matching criteria. -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> source group domain-group \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> source group domain-group \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> source group domain-group \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> source group domain-group \ -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> destination group domain-group \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> destination group domain-group \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> destination group domain-group \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> destination group domain-group \ - -Specify a domain group. You can prepend the character ``!`` to invert the -matching criteria. -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> source group mac-group \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> source group mac-group \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> source group mac-group \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> source group mac-group \ -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> destination group mac-group \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> destination group mac-group \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> destination group mac-group \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> destination group mac-group \ - -Specify a MAC group. You can prepend the character ``!`` to invert the -matching criteria. -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> dscp [0-63 | start-end] -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> dscp [0-63 | start-end] -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> dscp [0-63 | start-end] -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> dscp [0-63 | start-end] -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> dscp-exclude [0-63 | start-end] -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> dscp-exclude [0-63 | start-end] -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> dscp-exclude [0-63 | start-end] -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> dscp-exclude [0-63 | start-end] - -Match based on dscp value. -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> fragment [match-frag | match-non-frag] -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> fragment [match-frag | match-non-frag] -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> fragment [match-frag | match-non-frag] -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> fragment [match-frag | match-non-frag] - -Match packets based on fragmentation. -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> icmpv6 [code | type] \<0-255\> -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> icmpv6 [code | type] \<0-255\> -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> icmpv6 [code | type] \<0-255\> -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> icmpv6 [code | type] \<0-255\> - -Match packets based on ICMP or ICMPv6 code and type. -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> icmpv6 type-name \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> icmpv6 type-name \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> icmpv6 type-name \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> icmpv6 type-name \ - -Match based on ICMPv6 type-name. Press **Tab** for information about -supported **type-name** criteria. -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> inbound-interface name \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> inbound-interface name \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> inbound-interface name \ - -Match based on inbound interface. You can use the wildcard ``*``. For -example: ``eth2*``. You can prepend the character ``!`` to invert the -matching criteria. For example ``!eth2`` -``` -:::{note} -If an interface is attached to a non-default VRF, when using -**inbound-interface**, use the VRF name. For example: -`set firewall ipv6 forward filter rule 10 inbound-interface name MGMT` -::: -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> inbound-interface group \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> inbound-interface group \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> inbound-interface group \ - -Match based on the inbound interface group. You can prepend the character -``!`` to invert the matching criteria. For example ``!IFACE_GROUP`` -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> outbound-interface name \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> outbound-interface name \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> outbound-interface name \ - -Match based on outbound interface. You can use the wildcard ``*``. For -example: ``eth2*``. You can prepend the character ``!`` to invert the -matching criteria. For example ``!eth2`` -``` -:::{note} -If an interface is attached to a non-default VRF, when using -**outbound-interface**, use the physical interface name. For example: -`set firewall ipv6 forward filter rule 10 outbound-interface name eth0` -::: -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> outbound-interface group \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> outbound-interface group \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> outbound-interface group \ - -Match based on outbound interface group. You can prepend the character ``!`` -to invert the matching criteria. For example ``!IFACE_GROUP`` -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> ipsec [match-ipsec-in | match-ipsec-out | match-none-in | match-none-out] -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> ipsec [match-ipsec-in | match-none-in] -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> ipsec [match-ipsec-out | match-none-out] -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> ipsec [match-ipsec-in | match-ipsec-out | match-none-in | match-none-out] - -Match packets based on IPsec. -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> limit burst \<0-4294967295\> -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> limit burst \<0-4294967295\> -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> limit burst \<0-4294967295\> -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> limit burst \<0-4294967295\> - -Match based on the maximum number of packets allowed to exceed the rate -limit. -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> limit rate \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> limit rate \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> limit rate \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> limit rate \ - -Match based on the maximum average rate, specified as ``integer/unit``. -For example, specify ``5/minutes``. -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> packet-length \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> packet-length \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> packet-length \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> packet-length \ -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> packet-length-exclude \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> packet-length-exclude \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> packet-length-exclude \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> packet-length-exclude \ - -Match based on packet length. You can specify multiple values from 1 to -65535 and ranges. -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> packet-type [broadcast | host | multicast | other] -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> packet-type [broadcast | host | multicast | other] -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> packet-type [broadcast | host | multicast | other] -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> packet-type [broadcast | host | multicast | other] - -Match based on packet type. -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> protocol [\ | \<0-255\> | all | tcp_udp] -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> protocol [\ | \<0-255\> | all | tcp_udp] -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> protocol [\ | \<0-255\> | all | tcp_udp] -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> protocol [\ | \<0-255\> | all | tcp_udp] - -Match based on protocol number or name as defined in ``/etc/protocols``. -Specify ``all`` for all protocols and ``tcp_udp`` for TCP and UDP packets. -Prepend ``!`` to negate the protocol selection. - -:::{code-block} none -set firewall ipv6 input filter rule 10 protocol tcp -::: -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> recent count \<1-255\> -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> recent count \<1-255\> -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> recent count \<1-255\> -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> recent count \<1-255\> -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> recent time [second | minute | hour] -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> recent time [second | minute | hour] -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> recent time [second | minute | hour] -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> recent time [second | minute | hour] - -Match packets based on recently seen sources. -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> tcp flags [not] \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> tcp flags [not] \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> tcp flags [not] \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> tcp flags [not] \ - -Allowed values for TCP flags: ``ack``, ``cwr``, ``ecn``, ``fin``, ``psh``, -``rst``, ``syn``, and ``urg``. You can specify multiple values. To invert -the selection, use ``not``, as shown in the following example. - -:::{code-block} none -set firewall ipv6 input filter rule 10 tcp flags 'ack' -set firewall ipv6 input filter rule 12 tcp flags 'syn' -set firewall ipv6 input filter rule 13 tcp flags not 'fin' -::: -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> state [established | invalid | new | related] -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> state [established | invalid | new | related] -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> state [established | invalid | new | related] -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> state [established | invalid | new | related] - -Match based on packet state. -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> time startdate \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> time startdate \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> time startdate \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> time startdate \ -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> time starttime \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> time starttime \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> time starttime \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> time starttime \ -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> time stopdate \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> time stopdate \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> time stopdate \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> time stopdate \ -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> time stoptime \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> time stoptime \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> time stoptime \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> time stoptime \ -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> time weekdays \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> time weekdays \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> time weekdays \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> time weekdays \ - -Match packets based on time criteria. -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> hop-limit \ \<0-255\> -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> hop-limit \ \<0-255\> -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> hop-limit \ \<0-255\> -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> hop-limit \ \<0-255\> - -Match the hop-limit parameter. Use ``eq`` for equal, ``gt`` for greater than, -and ``lt`` for less than. -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> recent count \<1-255\> -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> recent count \<1-255\> -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> recent count \<1-255\> -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> recent count \<1-255\> -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> recent time \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> recent time \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> recent time \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> recent time \ - -Match when the specified number of connections occur within the specified -time period. Use these criteria to block brute-force attempts. -``` - -### Packet Modifications - - -The firewall can modify packets before sending them. -This feature provides more flexibility for packet handling. - -```{cfgcmd} set firewall ipv6 prerouting raw rule \<1-999999\> set dscp \<0-63\> -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> set dscp \<0-63\> -``` - -```{cfgcmd} set firewall ipv6 output [filter | raw] rule \<1-999999\> set dscp \<0-63\> - -Set a specific value of Differentiated Services Codepoint (DSCP). -``` - -```{cfgcmd} set firewall ipv6 prerouting raw rule \<1-999999\> set mark \<1-2147483647\> -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> set mark \<1-2147483647\> -``` - -```{cfgcmd} set firewall ipv6 output [filter | raw] rule \<1-999999\> set mark \<1-2147483647\> - -Set a specific packet mark value. -``` - -```{cfgcmd} set firewall ipv6 prerouting raw rule \<1-999999\> set tcp-mss \<500-1460\> -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> set tcp-mss \<500-1460\> -``` - -```{cfgcmd} set firewall ipv6 output [filter | raw] rule \<1-999999\> set tcp-mss \<500-1460\> - -Set the TCP-MSS (TCP maximum segment size) for the connection. -``` - -```{cfgcmd} set firewall ipv6 prerouting raw rule \<1-999999\> set hop-limit \<0-255\> -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> set hop-limit \<0-255\> -``` - -```{cfgcmd} set firewall ipv6 output [filter | raw] rule \<1-999999\> set hop-limit \<0-255\> - -Set hop limit value. -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> set connection-mark \<0-2147483647\> -``` - -```{cfgcmd} set firewall ipv6 output [filter | raw] rule \<1-999999\> set connection-mark \<0-2147483647\> - -Set connection mark value. -``` - -## Synproxy - - -Synproxy connections - -```{cfgcmd} set firewall ipv6 [input | forward] filter rule \<1-999999\> action synproxy -``` - -```{cfgcmd} set firewall ipv6 [input | forward] filter rule \<1-999999\> protocol tcp -``` - -```{cfgcmd} set firewall ipv6 [input | forward] filter rule \<1-999999\> synproxy tcp mss \<501-65535\> - - Set the TCP MSS (maximum segment size) for the connection. -``` - -```{cfgcmd} set firewall ipv6 [input | forward] filter rule \<1-999999\> synproxy tcp window-scale \<1-14\> - - Set the window scale factor for TCP window scaling. -``` - -### Example synproxy - - -Requirements to enable synproxy: - - -- Traffic must be symmetric -- Synproxy relies on syncookies and TCP timestamps, ensure these are enabled -- Disable conntrack loose track option - -```none -set system sysctl parameter net.ipv4.tcp_timestamps value '1' - - -set system conntrack tcp loose disable - -set system conntrack ignore ipv6 rule 10 destination port '8080' - -set system conntrack ignore ipv6 rule 10 protocol 'tcp' - -set system conntrack ignore ipv6 rule 10 tcp flags syn - - -set firewall global-options syn-cookies 'enable' - -set firewall ipv6 input filter rule 10 action 'synproxy' - -set firewall ipv6 input filter rule 10 destination port '8080' - -set firewall ipv6 input filter rule 10 inbound-interface name 'eth1' - -set firewall ipv6 input filter rule 10 protocol 'tcp' - -set firewall ipv6 input filter rule 10 synproxy tcp mss '1460' - -set firewall ipv6 input filter rule 10 synproxy tcp window-scale '7' - -set firewall ipv6 input filter rule 1000 action 'drop' - -set firewall ipv6 input filter rule 1000 state invalid - -``` - -## Operation-mode Firewall - - -### Rule-set overview - -```{opcmd} show firewall - -Show a basic firewall overview for all rule-sets, not only for IPv6: - -:::{code-block} none -vyos@vyos:~$ show firewall -Rulesets Information - ---------------------------------- -IPv4 Firewall "forward filter" - -Rule Action Protocol Packets Bytes Conditions -------- -------- ---------- --------- ------- ----------------------------------------- -5 jump all 0 0 iifname "eth1" jump NAME_VyOS_MANAGEMENT -10 jump all 0 0 oifname "eth1" jump NAME_WAN_IN -15 jump all 0 0 iifname "eth3" jump NAME_WAN_IN -default accept all - ---------------------------------- -IPv4 Firewall "name VyOS_MANAGEMENT" - -Rule Action Protocol Packets Bytes Conditions -------- -------- ---------- --------- ------- -------------------------------- -5 accept all 0 0 ct state established accept -10 drop all 0 0 ct state invalid -20 accept all 0 0 ip saddr @A_GOOD_GUYS accept -30 accept all 0 0 ip saddr @N_ENTIRE_RANGE accept -40 accept all 0 0 ip saddr @A_VyOS_SERVERS accept -50 accept icmp 0 0 meta l4proto icmp accept -default drop all 0 0 - ---------------------------------- -IPv6 Firewall "forward filter" - -Rule Action Protocol -------- -------- ---------- -5 jump all -10 jump all -15 jump all -default accept all - ---------------------------------- -IPv6 Firewall "input filter" - -Rule Action Protocol -------- -------- ---------- -5 jump all -default accept all - ---------------------------------- -IPv6 Firewall "ipv6_name IPV6-VyOS_MANAGEMENT" - -Rule Action Protocol -------- -------- ---------- -5 accept all -10 drop all -20 accept all -30 accept all -40 accept all -50 accept ipv6-icmp -default drop all -::: -``` - -```{opcmd} show firewall summary - -This will show you a summary of rule-sets and groups - -:::{code-block} none -vyos@vyos:~$ show firewall summary -Ruleset Summary - -IPv6 Ruleset: - -Ruleset Hook Ruleset Priority Description --------------- -------------------- ------------------------- -forward filter -input filter -ipv6_name IPV6-VyOS_MANAGEMENT -ipv6_name IPV6-WAN_IN PUBLIC_INTERNET - -IPv4 Ruleset: - -Ruleset Hook Ruleset Priority Description --------------- ------------------ ------------------------- -forward filter -input filter -name VyOS_MANAGEMENT -name WAN_IN PUBLIC_INTERNET - -Firewall Groups - -Name Type References Members ------------------------ ------------------ ----------------------- ---------------- -PBX address_group WAN_IN-100 198.51.100.77 -SERVERS address_group WAN_IN-110 192.0.2.10 -WAN_IN-111 192.0.2.11 -WAN_IN-112 192.0.2.12 -WAN_IN-120 -WAN_IN-121 -WAN_IN-122 -SUPPORT address_group VyOS_MANAGEMENT-20 192.168.1.2 -WAN_IN-20 -PHONE_VPN_SERVERS address_group WAN_IN-160 10.6.32.2 -PINGABLE_ADRESSES address_group WAN_IN-170 192.168.5.2 -WAN_IN-171 -PBX ipv6_address_group IPV6-WAN_IN-100 2001:db8::1 -SERVERS ipv6_address_group IPV6-WAN_IN-110 2001:db8::2 -IPV6-WAN_IN-111 2001:db8::3 -IPV6-WAN_IN-112 2001:db8::4 -IPV6-WAN_IN-120 -IPV6-WAN_IN-121 -IPV6-WAN_IN-122 -SUPPORT ipv6_address_group IPV6-VyOS_MANAGEMENT-20 2001:db8::5 -IPV6-WAN_IN-20 -::: -``` - -```{opcmd} show firewall ipv6 [forward | input | output] filter -``` - -```{opcmd} show firewall ipv6 ipv6-name \ - -This command will give an overview of a single rule-set. - -:::{code-block} none -vyos@vyos:~$ show firewall ipv6 input filter -Ruleset Information - ---------------------------------- -ipv6 Firewall "input filter" - -Rule Action Protocol Packets Bytes Conditions -------- -------- ---------- --------- ------- ------------------------------------------------------------------------------ -10 jump all 13 1456 iifname "eth1" jump NAME6_INP-ETH1 -20 accept ipv6-icmp 10 1112 meta l4proto ipv6-icmp iifname "eth0" prefix "[ipv6-INP-filter-20-A]" accept -default accept all 14 1584 - -vyos@vyos:~$ -::: -``` - -```{opcmd} show firewall ipv6 [forward | input | output] filter rule \<1-999999\> -``` - -```{opcmd} show firewall ipv6 name \ rule \<1-999999\> -``` - -```{opcmd} show firewall ipv6 ipv6-name \ rule \<1-999999\> - -This command will give an overview of a rule in a single rule-set -``` - -```{opcmd} show firewall group \ - -Show an overview of defined groups, including the type, members, and where -the group is used. - -:::{code-block} none -vyos@vyos:~$ show firewall group LAN -Firewall Groups - -Name Type References Members ------------- ------------------ ----------------------- ---------------- -LAN ipv6_network_group IPV6-VyOS_MANAGEMENT-30 2001:db8::0/64 -IPV6-WAN_IN-30 -LAN network_group VyOS_MANAGEMENT-30 192.168.200.0/24 -WAN_IN-30 -::: -``` - -```{opcmd} show firewall statistics - -Show statistics of all rule-sets since the last boot. -``` - -### Show Firewall log - -```{opcmd} show log firewall -``` - -```{opcmd} show log firewall ipv6 -``` - -```{opcmd} show log firewall ipv6 [forward | input | output | name] -``` - -```{opcmd} show log firewall ipv6 [forward | input | output] filter -``` - -```{opcmd} show log firewall ipv6 name \ -``` - -```{opcmd} show log firewall ipv6 [forward | input | output] filter rule \ -``` - -```{opcmd} show log firewall ipv6 name \ rule \ - -Show firewall logs for all firewalls, all IPv6 firewalls, specific hooks, -specific priorities, specific custom chains, or specific rule-sets. -``` - -### Example Partial Config - -```none -firewall { - ipv6 { - input { - filter { - rule 10 { - action jump - inbound-interface { - name eth1 - } - jump-target INP-ETH1 - } - rule 20 { - action accept - inbound-interface { - name eth0 - } - log - protocol ipv6-icmp - } - } - } - name INP-ETH1 { - default-action drop - default-log - rule 10 { - action accept - protocol tcp_udp - } - } - } -} -``` - -### Update geoip database - -```{opcmd} update geoip - -Command used to update GeoIP database and firewall sets. -``` \ No newline at end of file diff --git a/docs/configuration/firewall/md-zone.md b/docs/configuration/firewall/md-zone.md deleted file mode 100644 index bbb93993..00000000 --- a/docs/configuration/firewall/md-zone.md +++ /dev/null @@ -1,201 +0,0 @@ ---- -lastproofread: '2026-03-30' ---- - -(firewall-zone)= - -# Zone-Based Firewall - -## Overview - -:::{note} -All VyOS versions built after 2023-10-22 (VyOS 1.4 and 1.5) support -this feature. -::: - -This section provides information on firewall configuration for the -zone-based firewall. This section covers the following configuration -commands: - -```{cfgcmd} set firewall zone ... -``` - -To learn about the general traffic flow in VyOS firewalls, -see {doc}`Firewall `. - -```none -- set firewall - * zone - - custom_zone_name - + ... -``` - -In zone-based policy, you assign interfaces to zones and apply inspection -policy to traffic moving between zones. The firewall acts on traffic -according to rules. A zone is a group of interfaces that have similar -functions or features. It establishes the security borders of a network. -A zone defines a boundary where the system subjects traffic to policy -restrictions as it crosses to another region of a network. - -Key Points: -- A zone must be configured before you assign an interface to it, and you - can assign an interface to only a single zone. -- All traffic to and from an interface within a zone flows freely. -- Existing policies affect all traffic between zones. -- Traffic cannot flow between a zone member interface and any interface that - is not a zone member. -- You must define 2 separate firewalls to define traffic: one for each - direction. - -:::{note} -In {vytask}`T2199` the syntax of the zone configuration was changed. -The zone configuration moved from ``zone-policy zone `` to -``firewall zone ``. -::: - -## Configuration - -As an alternative to applying policy to an interface directly, you can -create a zone-based firewall to simplify configuration when multiple -interfaces belong to the same security zone. Instead of applying rule-sets -to interfaces, you apply them to source-destination zone pairs. - -You can find a basic introduction to zone-based firewalls in the -[VyOS Knowledge Base](https://support.vyos.io/en/kb/articles/a-primer-to-zone-based-firewall), -and an example at {ref}`examples-zone-policy`. - -The following steps are required to create a zone-based firewall: -1. Define both the source and destination zones -2. Define the rule-set -3. Apply the rule-set to the zones - -### Define a Zone - -To define a zone, set up either one with interfaces or as the local zone. - -```{cfgcmd} set firewall zone \ interface \ - -Assign interfaces as a member of a zone. - -:::{note} -* An interface can only be a member of one zone. -* You can have multiple interfaces in a zone. Traffic between -interfaces in the same zone follows the intra-zone-filtering -policy (allowed by default). -::: -``` - -```{cfgcmd} set firewall zone \ local-zone - -Define the zone as the local zone for traffic that originates from or is -destined to the router itself. - -:::{note} -* A local zone cannot have any member interfaces -* You cannot have multiple local zones -::: -``` - -```{cfgcmd} set firewall zone \ default-action [drop | reject] - -Modify the zone default-action, which applies to traffic destined to this -zone that does not match any of the source zone rulesets applied. -``` - -```{cfgcmd} set firewall zone \ default-log - -Enable logging of packets that match this zone's default-action (disabled -by default). -``` - -```{cfgcmd} set firewall zone \ description - -Add a meaningful description. -``` - -### Defining a Rule-Set - -Zone-based firewall rule-sets define traffic from a *Source Zone* to a -*Destination Zone*. - -You create rule-sets as a custom firewall chain using the commands below -(refer to the firewall IPv4/IPv6 sections for the full syntax): -- For {ref}`IPv4`: - `set firewall ipv4 name ...` -- For {ref}`IPv6`: - `set firewall ipv6 name ...` - -It is helpful to name the rule-sets in the format -`--` to make them easily -identifiable. - -### Applying a Rule-Set to a Zone - -After you define a rule-set, apply it to the source and destination zones. -The configuration syntax anchors to the destination zone, with each of the -source zone rule-sets listed against the destination. - -```{cfgcmd} set firewall zone \ from \ firewall name \ -``` - -```{cfgcmd} set firewall zone \ from \ firewall ipv6-name \ -``` - -You should create two rule-sets for each source-destination zone -pair. - -```none -set firewall zone DMZ from LAN firewall name LAN-DMZ-v4 -set firewall zone LAN from DMZ firewall name DMZ-LAN-v4 -``` - -### Applying a Default Rule-Set to a Zone - -When a destination zone shares a common rule-set for multiple source zones, -or when you require a complex set of default policies, you can apply an -optional default rule-set. The default rule-set applies to all zones that do -not have a rule-set configured as defined in -{ref}`IPv4` - -```{cfgcmd} set firewall zone \ default-firewall name \ -``` - -```{cfgcmd} set firewall zone \ default-firewall ipv6-name \ -``` - -## Operation-mode - -```{opcmd} show firewall zone-policy - -Display a basic summary of the zone configuration. - -:::{code-block} none -vyos@vyos:~$ show firewall zone-policy -Zone Interfaces From Zone Firewall IPv4 Firewall IPv6 ------- ------------ ----------- --------------- --------------- -LAN eth1 WAN WAN-LAN-v4 -eth2 -LOCAL LOCAL LAN LAN-LOCAL-v4 -WAN WAN-LOCAL-v4 WAN-LOCAL-v6 -WAN eth3 LAN LAN-WAN-v4 -eth0 LOCAL LOCAL-WAN-v4 -::: -``` - -```{opcmd} show firewall zone-policy zone \ - -Display a basic summary of a particular zone. - -:::{code-block} none -vyos@vyos:~$ show firewall zone-policy zone WAN -Zone Interfaces From Zone Firewall IPv4 Firewall IPv6 ------- ------------ ----------- --------------- --------------- -WAN eth3 LAN LAN-WAN-v4 -eth0 LOCAL LOCAL-WAN-v4 -vyos@vyos:~$ show firewall zone-policy zone LOCAL -Zone Interfaces From Zone Firewall IPv4 Firewall IPv6 ------- ------------ ----------- --------------- --------------- -LOCAL LOCAL LAN LAN-LOCAL-v4 -WAN WAN-LOCAL-v4 WAN-LOCAL-v6 -::: -``` \ No newline at end of file diff --git a/docs/configuration/highavailability/md-index.md b/docs/configuration/highavailability/md-index.md deleted file mode 100644 index e26f5791..00000000 --- a/docs/configuration/highavailability/md-index.md +++ /dev/null @@ -1,561 +0,0 @@ ---- -lastproofread: '2021-06-30' ---- - -(high-availability)= - -# High availability - -VRRP (Virtual Router Redundancy Protocol) provides active/backup redundancy for -routers. Every VRRP router has a physical IP/IPv6 address, and a virtual -address. On startup, routers elect the master, and the router with the highest -priority becomes the master and assigns the virtual address to its interface. -All routers with lower priorities become backup routers. The master then starts -sending keepalive packets to notify other routers that it's available. If the -master fails and stops sending keepalive packets, the router with the next -highest priority becomes the new master and takes over the virtual address. - -VRRP keepalive packets use multicast, and VRRP setups are limited to a single -datalink layer segment. You can setup multiple VRRP groups -(also called virtual routers). Virtual routers are identified by a -VRID (Virtual Router IDentifier). If you setup multiple groups on the same -interface, their VRIDs must be unique if they use the same address family, -but it's possible (even if not recommended for readability reasons) to use -duplicate VRIDs on different interfaces. - -## Basic setup - -VRRP groups are created with the -`set high-availability vrrp group $GROUP_NAME` commands. The required -parameters are interface, vrid, and address. - -minimal config - -```none -set high-availability vrrp group Foo vrid 10 -set high-availability vrrp group Foo interface eth0 -set high-availability vrrp group Foo address 192.0.2.1/24 -``` - -You can verify your VRRP group status with the operational mode -`run show vrrp` command: - -```none -vyos@vyos# run show vrrp -Name Interface VRID State Last Transition ----------- ----------- ------ ------- ----------------- -Foo eth1 10 MASTER 2s -``` - -## IPv6 support - -The `address` parameter can be either an IPv4 or IPv6 address, but you can -not mix IPv4 and IPv6 in the same group, and will need to create groups with -different VRIDs specially for IPv4 and IPv6. -If you want to use IPv4 + IPv6 address you can use option `excluded-address` - -## Address - -The `address` can be configured either on the VRRP interface or on not VRRP -interface. - -```none -set high-availability vrrp group Foo address 192.0.2.1/24 -set high-availability vrrp group Foo address 203.0.113.22/24 interface eth2 -set high-availability vrrp group Foo address 198.51.100.33/24 interface eth3 -``` - -## Disabling a VRRP group - -You can disable a VRRP group with `disable` option: - -```none -set high-availability vrrp group Foo disable -``` - -A disabled group will be removed from the VRRP process and your router will not -participate in VRRP for that VRID. It will disappear from operational mode -commands output, rather than enter the backup state. - -## Exclude address - -Exclude IP addresses from `VRRP packets`. This option `excluded-address` is -used when you want to set IPv4 + IPv6 addresses on the same virtual interface -or when used more than 20 IP addresses. - -```none -set high-availability vrrp group Foo excluded-address '203.0.113.254/24' -set high-availability vrrp group Foo excluded-address '2001:db8:aa::1/64' -set high-availability vrrp group Foo excluded-address '2001:db8:22::1/64' -``` - -## Setting VRRP group priority - -VRRP priority can be set with `priority` option: - -```none -set high-availability vrrp group Foo priority 200 -``` - -The priority must be an integer number from 1 to 255. Higher priority value -increases router's precedence in the master elections. - -## Sync groups - -A sync group allows VRRP groups to transition together. - -```none -edit high-availability vrrp -set sync-group MAIN member VLAN9 -set sync-group MAIN member VLAN20 -``` - -In the following example, when VLAN9 transitions, VLAN20 will also transition: - -```none -vrrp { - group VLAN9 { - interface eth0.9 - address 10.9.1.1/24 - priority 200 - vrid 9 - } - group VLAN20 { - interface eth0.20 - priority 200 - address 10.20.20.1/24 - vrid 20 - } - sync-group MAIN { - member VLAN20 - member VLAN9 - } -} -``` - -:::{warning} -All items in a sync group should be similarly configured. -If one VRRP group is set to a different preemption delay or priority, -it would result in an endless transition loop. -::: - -## Preemption - -VRRP can use two modes: preemptive and non-preemptive. In the preemptive mode, -if a router with a higher priority fails and then comes back, routers with lower -priority will give up their master status. In non-preemptive mode, the newly -elected master will keep the master status and the virtual address indefinitely. - -By default VRRP uses preemption. You can disable it with the "no-preempt" -option: - -```none -set high-availability vrrp group Foo no-preempt -``` - -You can also configure the time interval for preemption with the "preempt-delay" -option. For example, to set the higher priority router to take over in 180 -seconds, use: - -```none -set high-availability vrrp group Foo preempt-delay 180 -``` - -## Track - -Track option to track non VRRP interface states. VRRP changes status to -`FAULT` if one of the track interfaces in state `down`. - -```none -set high-availability vrrp group Foo track interface eth0 -set high-availability vrrp group Foo track interface eth1 -``` - -Ignore VRRP main interface faults - -```none -set high-availability vrrp group Foo track exclude-vrrp-interface -``` - -## Unicast VRRP - -By default VRRP uses multicast packets. If your network does not support -multicast for whatever reason, you can make VRRP use unicast communication -instead. - -```none -set high-availability vrrp group Foo peer-address 192.0.2.10 -set high-availability vrrp group Foo hello-source-address 192.0.2.15 -``` - -## rfc3768-compatibility - -RFC 3768 defines a virtual MAC address to each VRRP virtual router. -This virtual router MAC address will be used as the source in all periodic VRRP -messages sent by the active node. When the rfc3768-compatibility option is set, -a new VRRP interface is created, to which the MAC address and the virtual IP -address is automatically assigned. - -```none -set high-availability vrrp group Foo rfc3768-compatibility -``` - -Verification - -```none -$show interfaces ethernet eth0v10 -eth0v10@eth0: mtu 1500 qdisc noqueue -state UP group default qlen 1000 -link/ether 00:00:5e:00:01:0a brd ff:ff:ff:ff:ff:ff -inet 172.25.0.247/16 scope global eth0v10 -valid_lft forever preferred_lft forever -``` - -:::{warning} -RFC 3768 creates a virtual interface. If you want to apply -the destination NAT rule to the traffic sent to the virtual MAC, set -the created virtual interface as `inbound-interface`. -::: - -## Global options - -On most scenarios, there's no need to change specific parameters, and using -default configuration is enough. But there are cases were extra configuration -is needed. - -```{eval-rst} -.. cfgcmd:: set high-availability vrrp global-parameters startup_delay <1-600> - - This option specifies a delay in seconds before vrrp instances start up - after keepalived starts. -``` - -## Gratuitous ARP - -These configuration is not mandatory and in most cases there's no -need to configure it. But if necessary, Gratuitous ARP can be configured in -`global-parameters` and/or in `group` section. - -```{eval-rst} -.. cfgcmd:: set high-availability vrrp global-parameters garp interval - <0.000-1000> -``` - -```{eval-rst} -.. cfgcmd:: set high-availability vrrp group garp interval <0.000-1000> - - Set delay between gratuitous ARP messages sent on an interface. - - 0 if not defined. -``` - -% stop_vyoslinter - -```{eval-rst} -.. cfgcmd:: set high-availability vrrp global-parameters garp master-delay <1-255> -``` - -% start_vyoslinter - -```{eval-rst} -.. cfgcmd:: set high-availability vrrp group garp master-delay <1-255> - - Set delay for second set of gratuitous ARPs after transition to MASTER. - - 5 if not defined. -``` - -```{eval-rst} -.. cfgcmd:: set high-availability vrrp global-parameters garp master-refresh - <1-600> -``` - -```{eval-rst} -.. cfgcmd:: set high-availability vrrp group garp master-refresh - <1-600> - - Set minimum time interval for refreshing gratuitous ARPs while MASTER. - - 0 if not defined, which means no refreshing. -``` - -```{eval-rst} -.. cfgcmd:: set high-availability vrrp global-parameters garp - master-refresh-repeat <1-600> -``` - -```{eval-rst} -.. cfgcmd:: set high-availability vrrp group garp - master-refresh-repeat <1-600> - - Set number of gratuitous ARP messages to send at a time while MASTER. - - 1 if not defined. -``` - -```{eval-rst} -.. cfgcmd:: set high-availability vrrp global-parameters garp master-repeat - <1-600> -``` - -```{eval-rst} -.. cfgcmd:: set high-availability vrrp group garp master-repeat - <1-600> - - Set number of gratuitous ARP messages to send at a time after transition to - MASTER. - - 5 if not defined. -``` - -## Version - -```{eval-rst} -.. cfgcmd:: set high-availability vrrp global-parameters version 2|3 - - Set the default VRRP version to use. This defaults to 2, but IPv6 instances - will always use version 3. -``` - -## Scripting - -VRRP functionality can be extended with scripts. VyOS supports two kinds of -scripts: health check scripts and transition scripts. Health check scripts -execute custom checks in addition to the master router reachability. Transition -scripts are executed when VRRP state changes from master to backup or fault and -vice versa and can be used to enable or disable certain services, for example. - -:::{note} -Simply placing script files in `/config/scripts/` does not mean the -system can execute them. To make custom scripts executable, grant them -**execute permissions**. Use the following command: - -```none -chmod +x /config/scripts/script-name.sh -``` -::: - -:::{warning} -It is not recommended to change VRRP configuration -inside health-check and transition scripts. -::: - -### Health check scripts - -There is the ability to run an arbitrary script at regular intervals -according to health-check parameters. If a script returns 0, it -indicates success. If a script returns anything else, it will indicate -that the VRRP instance should enter the FAULT state. - -This setup will make the VRRP process execute the -`/config/scripts/vrrp-check.sh script` every 60 seconds, and transition the -group to the fault state if it fails (i.e. exits with non-zero status) three -times: - -% stop_vyoslinter - -```none -set high-availability vrrp group Foo health-check script /config/scripts/vrrp-check.sh -set high-availability vrrp group Foo health-check interval 60 -set high-availability vrrp group Foo health-check failure-count 3 -``` - -% start_vyoslinter - -An optional `timeout` can be set to define the maximum number of seconds the -script is allowed to run. This is useful for scripts that may hang or take -longer than expected — setting the timeout higher than the interval allows -longer-running scripts to complete before being considered failed. - -% stop_vyoslinter - -```none -set high-availability vrrp group Foo health-check script /config/scripts/vrrp-check.sh -set high-availability vrrp group Foo health-check interval 20 -set high-availability vrrp group Foo health-check failure-count 3 -set high-availability vrrp group Foo health-check timeout 40 -``` - -% start_vyoslinter - -When the vrrp group is a member of the sync group will use only -the sync group health check script. -This example shows how to configure it for the sync group: - -% stop_vyoslinter - -```none -set high-availability vrrp sync-group Bar health-check script /config/scripts/vrrp-check.sh -set high-availability vrrp sync-group Bar health-check interval 60 -set high-availability vrrp sync-group Bar health-check failure-count 3 -``` - -% start_vyoslinter - -### Transition scripts - -Transition scripts can help you implement various fixups, such as starting and -stopping services, or even modifying the VyOS config on VRRP transition. -This setup will make the VRRP process execute the -`/config/scripts/vrrp-fail.sh` with argument `Foo` when VRRP fails, -and the `/config/scripts/vrrp-master.sh` when the router becomes the master: - -% stop_vyoslinter - -```none -set high-availability vrrp group Foo transition-script backup "/config/scripts/vrrp-fail.sh Foo" -set high-availability vrrp group Foo transition-script fault "/config/scripts/vrrp-fail.sh Foo" -set high-availability vrrp group Foo transition-script master "/config/scripts/vrrp-master.sh Foo" -``` - -% start_vyoslinter - -To know more about scripting, check the {ref}`command-scripting` section. - -## Virtual-server - -```{eval-rst} -.. include:: /_include/need_improvement.txt -``` - -Virtual Server allows to Load-balance traffic destination virtual-address:port -between several real servers. - -### Algorithm - -Load-balancing schedule algorithm: - -- round-robin -- weighted-round-robin -- least-connection -- weighted-least-connection -- source-hashing -- destination-hashing -- locality-based-least-connection - -```none -set high-availability virtual-server 203.0.113.1 algorithm 'least-connection' -``` - -### Forward method - -- NAT -- direct -- tunnel - -```none -set high-availability virtual-server 203.0.113.1 forward-method 'nat' -``` - -### Health-check - -Custom health-check script allows checking real-server availability - -% stop_vyoslinter - -```none -set high-availability virtual-server 203.0.113.1 real-server 192.0.2.11 health-check script -``` - -% start_vyoslinter - -### Fwmark - -Firewall mark. It possible to loadbalancing traffic based on `fwmark` value - -```none -set high-availability virtual-server 203.0.113.1 fwmark '111' -``` - -### Real server - -Real server IP address and port - -% stop_vyoslinter - -```none -set high-availability virtual-server 203.0.113.1 real-server 192.0.2.11 port '80' -``` - -% start_vyoslinter - -### Example - -Virtual-server can be configured with VRRP virtual address or without VRRP. - -In the next example all traffic destined to `203.0.113.1` and port `8280` -protocol TCP is balanced between 2 real servers `192.0.2.11` and -`192.0.2.12` to port `80` - -Real server is auto-excluded if port check with this server fail. - -% stop_vyoslinter - -```none -set interfaces ethernet eth0 address '203.0.113.11/24' -set interfaces ethernet eth1 address '192.0.2.1/24' -set high-availability vrrp group FOO interface 'eth0' -set high-availability vrrp group FOO no-preempt -set high-availability vrrp group FOO priority '150' -set high-availability vrrp group FOO address '203.0.113.1/24' -set high-availability vrrp group FOO vrid '10' - -set high-availability virtual-server 203.0.113.1 algorithm 'source-hashing' -set high-availability virtual-server 203.0.113.1 delay-loop '10' -set high-availability virtual-server 203.0.113.1 forward-method 'nat' -set high-availability virtual-server 203.0.113.1 persistence-timeout '180' -set high-availability virtual-server 203.0.113.1 port '8280' -set high-availability virtual-server 203.0.113.1 protocol 'tcp' -set high-availability virtual-server 203.0.113.1 real-server 192.0.2.11 port '80' -set high-availability virtual-server 203.0.113.1 real-server 192.0.2.12 port '80' -``` - -% start_vyoslinter - -A firewall mark `fwmark` allows using multiple ports for high-availability -virtual-server. -It uses fwmark value. - -In this example all traffic destined to ports "80, 2222, 8888" protocol TCP -marks to fwmark "111" and balanced between 2 real servers. -Port "0" is required if multiple ports are used. - -% stop_vyoslinter - -```none -set interfaces ethernet eth0 address 'dhcp' -set interfaces ethernet eth0 description 'WAN' -set interfaces ethernet eth1 address '192.0.2.1/24' -set interfaces ethernet eth1 description 'LAN' - -set policy route PR interface 'eth0' -set policy route PR rule 10 destination port '80,2222,8888' -set policy route PR rule 10 protocol 'tcp' -set policy route PR rule 10 set mark '111' - -set high-availability virtual-server vyos fwmark '111' -set high-availability virtual-server vyos protocol 'tcp' -set high-availability virtual-server vyos real-server 192.0.2.11 health-check script '/config/scripts/check-real-server-first.sh' -set high-availability virtual-server vyos real-server 192.0.2.11 port '0' -set high-availability virtual-server vyos real-server 192.0.2.12 health-check script '/config/scripts/check-real-server-second.sh' -set high-availability virtual-server vyos real-server 192.0.2.12 port '0' - -set nat source rule 100 outbound-interface name 'eth0' -set nat source rule 100 source address '192.0.2.0/24' -set nat source rule 100 translation address 'masquerade' -``` - -% start_vyoslinter - -Op-mode check virtual-server status - -```none -vyos@r14:~$ run show virtual-server -IP Virtual Server version 1.2.1 (size=4096) -Prot LocalAddress:Port Scheduler Flags - -> RemoteAddress:Port Forward Weight ActiveConn InActConn -FWM 111 lc persistent 300 - -> 192.0.2.11:0 Masq 1 0 0 - -> 192.0.2.12:0 Masq 1 1 0 -``` - diff --git a/docs/configuration/interfaces/md-bonding.md b/docs/configuration/interfaces/md-bonding.md deleted file mode 100644 index 7a07a27c..00000000 --- a/docs/configuration/interfaces/md-bonding.md +++ /dev/null @@ -1,764 +0,0 @@ ---- -lastproofread: '2025-12-09' ---- - -(bond-interface)= - -# Bond / link aggregation - -A **bonding interface** aggregates multiple network interfaces into a single -logical interface (referred to as a bond, {abbr}`LAG (Link Aggregation Group)`, -EtherChannel, or port-channel). - -The behavior of a bonding interface depends on the selected mode. Modes provide -either fault tolerance or a combination of load balancing and fault tolerance. -Additionally, the bonding interface can be configured for link integrity -monitoring. - -## Configuration - -### Common interface configuration - -```{cmdincludemd} /_include/interface-common-with-dhcp.txt -:var0: bonding -:var1: bond0 -``` - -### Member interfaces - -```{cfgcmd} set interfaces bonding \ member interface \ - -**Add an interface to the bonding group.** - -**Example:** - -To configure eth0 and eth1 as members of the bonding interface bond0, execute -the following commands: -``` - -```none -set interfaces bonding bond0 member interface eth0 -set interfaces bonding bond0 member interface eth1 -``` - -### Bond modes - -````{cfgcmd} set interfaces bonding \ mode \<802.3ad | active-backup | broadcast | round-robin | transmit-load-balance | adaptive-load-balance | xor-hash\> - -```{eval-rst} -**Configure the bonding mode on the interface. The default mode is** -``802.3ad``. - -The available modes are: - -* ``802.3ad`` - -.. list-table:: - :widths: 20 80 - - * - **Description:** - - IEEE 802.3ad Dynamic Link Aggregation. Groups only member - interfaces with the same speed (e.g., 1 Gbps) and duplex - settings. Member interfaces with different speed and duplex - settings are not included in the active bond. - - Provides load balancing and fault tolerance. Uses the - :abbr:`LACP (Link Aggregation Control Protocol)` to - negotiate the bond with the switch. - * - **Traffic distribution:** - - Traffic is distributed according to the **transmit hash - policy** (default: XOR). - - The bonding driver applies an XOR operation to specific - packet header fields, generating a hash value that maps to - a particular member interface. This ensures the same network - flow is consistently transmitted over the same member - interface. - - The transmit hash policy is configured via the ``hash-policy`` option. - * - **Failover:** - - If a member interface fails, the hash is recalculated to distribute - traffic among the remaining active member interfaces. - -.. note:: Not all transmit hash policies comply with 802.3ad, particularly - section 43.2.4. Using a non-compliant policy may result in out-of-order - packet delivery. - -* ``active-backup`` - -.. list-table:: - :widths: 20 80 - - * - **Description:** - - Provides fault tolerance. Only one member interface is active - at a time. Other member interfaces remain in a standby mode. - * - **Traffic distribution:** - - All traffic (incoming and outgoing) is routed via one active - member interface. - * - **Failover:** - - If the designated member interface fails, all traffic is - routed to another member interface. The bonding driver sends - a Gratuitous ARP to update the peer's MAC address table, - linking the bond's MAC address to another physical port. - -* ``broadcast`` - -.. list-table:: - :widths: 20 80 - - * - **Description:** - - Provides maximum fault tolerance by duplicating traffic. - * - **Traffic distribution:** - - Every packet is duplicated and transmitted on **all** member - interfaces. - * - **Failover:** - - Traffic flow is not interrupted as long as at least one - member interface remains active. - -* ``round-robin`` - -.. list-table:: - :widths: 20 80 - - * - **Description:** - - Provides load balancing and fault tolerance. - * - **Traffic distribution:** - - Packets are transmitted in sequential order across the member - interfaces (e.g., packet 1 > interface A, packet 2 > - interface B, etc.). - * - **Failover:** - - If a member interface fails, the sequence skips the failed - interface and continues with the remaining active members. - -* ``transmit-load-balance`` - -.. list-table:: - :widths: 20 80 - - * - **Description:** - - Provides adaptive transmit load balancing and fault tolerance. - * - **Traffic distribution:** - - **Outgoing:** Distributed across all active member interfaces - based on the current load. - - **Incoming:** Received by a designated member interface - (active receiver). - * - **Failover:** - - If the active receiver fails, another member interface takes - over as the new active receiver. - -* ``adaptive-load-balance`` - -.. list-table:: - :widths: 20 80 - - * - **Description:** - - Provides adaptive transmit load balancing identical to - ``transmit-load-balance``, receive load balancing for IPv4 - traffic, and fault tolerance for both incoming and outgoing - traffic. - * - **Traffic distribution:** - - **Outgoing:** Identical to ``transmit-load-balance``. - - **Incoming:** Distributed based on ARP manipulation. For - both local and remote connections, the bonding driver - intercepts ARP traffic and changes the source MAC address - to the MAC address of the least loaded member interface. - - All traffic from that peer is then routed to the chosen - member interface. - * - **Failover:** - - If a member interface's state changes (fails, recovers, is - added, or excluded), the traffic is redistributed among all - active member interfaces. - -* ``xor-hash``: Provides load balancing and fault tolerance - based on a hash formula. Distributes traffic and handles - failover identically to ``802.3ad``, but operates without - the :abbr:`LACP (Link Aggregation Control Protocol)`. -``` - -```` - -```{cfgcmd} set interfaces bonding \ min-links \<0-16\> - -**Configure how many member interfaces must be active (in the -link-up state) to mark the bonding interface UP (carrier -asserted).** - -This command applies only when the bonding interface is configured -in 802.3ad mode and functions like the Cisco EtherChannel min-links -feature. It ensures that a bonding interface is marked UP (carrier -asserted) only when a specified number of member interfaces are -active (in the link-up state). This helps guarantee a minimum level -of bandwidth for higher-level services (such as clustering) relying -on the bonding interface. - -The default value is 0. This marks the bonding interface UP -(carrier asserted) whenever an active LACP aggregator exists, -regardless of the number of member interfaces in that aggregator. - -:::{note} -In 802.3ad mode, a bond cannot be active without at least one active -member interface. Therefore, setting min-links to 0 or 1 has the same result: -the bonding interface is marked UP (carrier asserted). -::: -``` - -```{cfgcmd} set interfaces bonding \ lacp-rate \ - -**Configure the rate at which the bonding interface requests its link -partner to send** {abbr}`LACPDUs (Link Aggregation Control Protocol Data -Units)` **in 802.3ad mode.** - -This command applies only when the bonding interface is configured in -802.3ad mode. - -The following options are available: - -* **slow (default):** Requests the link partner to transmit LACPDUs every 30 seconds. - -* **fast:** Requests the link partner to transmit LACPDUs every 1 second. -``` -```{cfgcmd} set interfaces bonding \ system-mac \ - -**Configure a specific MAC address for the bonding interface.** - -This sets the 802.3ad system MAC address, which is used for {abbr}`LACPDU (Link -Aggregation Control Protocol Data Unit)` exchanges with the link partner. -You can assign a fixed MAC address or generate a random one for these -{abbr}`LACPDU (Link Aggregation Control Protocol Data Unit)` exchanges. -``` -```{cfgcmd} set interfaces bonding \ hash-policy \ - -**Configure which transmit hash policy to use for distributing traffic across -member interfaces.** - -The following policies are available: - -* ``layer2`` - -**Description:** Routes all traffic destined for a specific network peer through -the same member interface. The policy is 802.3ad-compliant. - -**Hash inputs:** Source MAC address, destination MAC address, and Ethernet packet -type ID. - -**Formula:** - -:::{code-block} none -hash = source MAC address XOR destination MAC address XOR packet type ID -member interface number = hash modulo member interface count -::: - -* ``layer2+3`` - -**Description:** Similar to ``layer2``, routes all traffic destined for a specific -network peer through the same member interface and is IEEE 802.3ad-compliant. Uses -both Layer 2 and Layer 3 information to provide a more balanced traffic distribution. - -**Hash inputs:** -* Source MAC address, destination MAC address, and Ethernet packet type ID. -* Source IP address, destination IP address. IPv6 addresses are first hashed - using ``IPv6_addr_hash``. - -**Formula:** - -:::{code-block} none -hash = source MAC address XOR destination MAC address XOR packet type ID -hash = hash XOR source IP address XOR destination IP address -hash = hash XOR (hash RSHIFT 16) -hash = hash XOR (hash RSHIFT 8) -member interface number = hash modulo member interface count -::: - -For non-IP traffic, the formula is the same as for ``layer2``. - -* ``layer3+4`` - -**Description:** Routes different connections (flows) destined for a specific -network peer through multiple member interfaces, but ensures each individual -flow is routed through only one member interface. - -:::{note} -This policy is not fully 802.3ad-compliant. When a single TCP or UDP flow -contains both fragmented and unfragmented packets, the algorithm may distribute -them across different member interfaces. This may result in out-of-order packet -delivery, violating the 802.3ad standard. -::: - -**Hash inputs:** -* Source port, destination port (if available). -* Source IP address, destination IP address. IPv6 addresses are first hashed - using ``IPv6_addr_hash``. - -**Formula:** - -:::{code-block} none -hash = source port, destination port (as in the header) -hash = hash XOR source IP address XOR destination IP address -hash = hash XOR (hash RSHIFT 16) -hash = hash XOR (hash RSHIFT 8) -member interface number = hash modulo member interface count -::: - -For fragmented TCP or UDP packets and all other IPv4 and IPv6 traffic, the -source and destination port information is omitted. - -For non-IP traffic, the formula is the same as for ``layer2``. -``` - - -```{cfgcmd} set interfaces bonding \ primary \ - -**Configure the primary member interface in the bond.** - -The primary member interface remains active as long as it is operational; -alternative member interfaces are used only if it fails. - -Use this configuration when a specific member interface is preferred, -such as one with higher throughput. - -This command applies only to ``active-backup``, ``transmit-load-balance``, and -``adaptive-load-balance`` modes. -``` - - -```{cfgcmd} set interfaces bonding \ arp-monitor interval \ - -**Configure the ARP monitoring interval, in seconds, for the bonding interface.** - -ARP monitoring periodically assesses the health of each member interface by -checking whether it has recently sent or received traffic (this criterion -varies depending on the bonding mode and the member interface’s state). ARP -probes are sent to the IP addresses specified with the arp-monitor target option. - -When ARP monitoring is used with EtherChannel-compatible modes (such as -``round-robin`` or ``xor-hash``), the switch should be configured to distribute -traffic across all member interfaces. If the switch distributes traffic using -an XOR-based policy, all ARP replies will be received on one member interface, -causing other member interfaces to be incorrectly marked as failed. - -Setting this value to 0 disables ARP monitoring. - -The default value is 0. -``` - - -```{cfgcmd} set interfaces bonding \ arp-monitor target \ - -**Configure the IP addresses for ARP monitoring requests.** - -The bonding driver sends ARP requests to these IP addresses to check the -state of member interfaces. - -To enable ARP monitoring, configure at least one IP address (up to 16 per -bonding interface). - -By default, no IP addresses are configured. -``` - -### {abbr}`VLAN (Virtual Local Area Network)` - -```{cmdincludemd} /_include/interface-vlan-8021q.txt -:var0: bonding -:var1: bond0 -``` - -### SPAN port mirroring - -```{cmdincludemd} ../../_include/interface-mirror.txt -:var0: bonding -:var1: bond1 -:var2: eth3 -``` - -#### EVPN multihoming - - -EVPN multihoming (EVPN-MH) is a standards-based solution (RFC 7432, RFC 8365) -that enables Customer Edge (CE) devices, such as servers, to connect to two -or more Provider Edge (PE) devices for redundancy and load balancing. - - -EVPN-MH is often used as a modern, standards-based alternative to -{abbr}`MLAG (Multi-Chassis Link Aggregation)` and {abbr}`VTEPs (Virtual -Tunnel Endpoints)`. - - -**Ethernet Segment (ES) and Ethernet Segment Identifier (ESI)** - - -Physical links that connect a CE device to PE devices are bundled using link -aggregation. This logical bundle is called an Ethernet Segment (ES) and is -uniquely identified by an Ethernet Segment Identifier (ESI) within the -EVPN domain. - - -To enable EVPN-MH, configure the same ESI on the bonding interfaces of all -PE devices connected to a single CE device. - - -An ESI is configured by specifying either a system MAC address and a local -discriminator, or an Ethernet Segment Identifier Name (ESINAME). - - -The following two commands generate a 10-byte Type-3 ESI by combining the -system MAC and local discriminator: - -```{cfgcmd} set interfaces bonding \ evpn es-id \<1-16777215|10-byte ID\> - -``` -```{cfgcmd} set interfaces bonding \ evpn es-sys-mac \ - -Alternatively, assign an ESINAME directly as a 10-byte Type-0 ESI using the -following format: 00:AA:BB:CC:DD:EE:FF:GG:HH:II. - -**BGP-EVPN route usage** - -EVPN-MH uses BGP-EVPN route types 1 and 2 for ES discovery and MAC-IP -synchronization: - -* **Type 1 (EAD-per-ES and EAD-per-EVI)** routes advertise the locally -attached ESs and discover remote ESs in the network. -* **Type 2 (MAC-IP advertisement)** routes are advertised with a -destination ESI, enabling MAC-IP synchronization between ES peers. -``` - -```{cfgcmd} set interfaces bonding \ evpn es-df-pref \<1-65535\> - -**Configure the** {abbr}`DF (Designated Forwarder)` **preference (1-65535) for -the interface. A higher value indicates a higher preference to become the** -{abbr}`DF (Designated Forwarder)`. **The** {abbr}`DF (Designated Forwarder)` -**preference is configured per-ES.** - -The DF election process determines which interface in a specific ES forwards -{abbr}`BUM (Broadcast, Unknown Unicast, and Multicast)` traffic from the EVPN -overlay to the connected CE device. EVPN Type-4 (Ethernet Segment) routes are -used to elect the DF, implementing the preference-based election method defined -in RFC 9785. - -Interfaces not elected as the DF drop any BUM traffic from the EVPN overlay -using non-DF filters. Similarly, traffic received from ES peers via the EVPN -overlay is blocked from forwarding to the CE device to maintain split-horizon -filtering with local bias. -``` - -```{cmdincludemd} /_include/interface-evpn-uplink.txt -:var0: bonding -:var1: bond0 -``` - -## Example - - -The following configuration example applies to all listed third-party vendors. -It creates a bonding interface with two member interfaces, defines VLANs 10 -and 100 on the bonding interface, and assigns an IPv4 address to each VLAN -subinterface. - -```none -# Create the bonding interface bond0 with 802.3ad LACP -set interfaces bonding bond0 hash-policy 'layer2' -set interfaces bonding bond0 mode '802.3ad' - -# Add the required VLANs and IPv4 addresses on them -set interfaces bonding bond0 vif 10 address 192.168.0.1/24 -set interfaces bonding bond0 vif 100 address 10.10.10.1/24 - -# Add the member interfaces to the bonding interface -set interfaces bonding bond0 member interface eth1 -set interfaces bonding bond0 member interface eth2 -``` -:::{note} -If you are running this configuration in a virtual environment like -EVE-NG, ensure the e1000 driver is chosen for your VyOS NIC. The default -drivers, such as ``virtio-net-pci`` or ``vmxnet3``, are incompatible with -this configuration. Specifically, ICMP messages will not be processed -correctly. - -To check your NIC driver, use the following command: -``show interfaces ethernet eth0 physical | grep -i driver`` -::: - - -### Cisco Catalyst configuration - - -Configure a Cisco Catalyst switch to integrate with a two-member VyOS bonding -interface. - - -Assign member interfaces to PortChannel: - -```none -interface GigabitEthernet1/0/23 - description VyOS eth1 - channel-group 1 mode active -! -interface GigabitEthernet1/0/24 - description VyOS eth2 - channel-group 1 mode active -! -``` - -A new interface, `Port-channel1`, becomes available; all configuration, -such as allowed VLAN interfaces and STP, is applied here. - -```none -interface Port-channel1 - description LACP Channel for VyOS - switchport trunk encapsulation dot1q - switchport trunk allowed vlan 10,100 - switchport mode trunk - spanning-tree portfast trunk -! -``` - -### Juniper EX Switch configuration - - -Configure a Juniper EX Series switch to integrate with a two-member VyOS bonding -interface. - -```none -# Create aggregated ethernet device with 802.3ad LACP and port speeds of 10gbit/s -set interfaces ae0 aggregated-ether-options link-speed 10g -set interfaces ae0 aggregated-ether-options lacp active - -# Create layer 2 on the aggregated ethernet device with trunking for our VLANs -set interfaces ae0 unit 0 family ethernet-switching port-mode trunk - -# Add the required vlans to the device -set interfaces ae0 unit 0 family ethernet-switching vlan members 10 -set interfaces ae0 unit 0 family ethernet-switching vlan members 100 - -# Add the two interfaces to the aggregated ethernet device, in this setup both -# ports are on the same switch (switch 0, module 1, port 0 and 1) -set interfaces xe-0/1/0 ether-options 802.3ad ae0 -set interfaces xe-0/1/1 ether-options 802.3ad ae0 - -# But this can also be done with multiple switches in a stack, a virtual -# chassis on Juniper (switch 0 and switch 1, module 1, port 0 on both switches) -set interfaces xe-0/1/0 ether-options 802.3ad ae0 -set interfaces xe-1/1/0 ether-options 802.3ad ae0 -``` - -### Aruba/HP configuration - - -Configure an Aruba/HP 2510G switch to integrate with a two-member VyOS bonding -interface. - -```none -# Create trunk with 2 member interfaces (interface 1 and 2) and LACP -trunk 1-2 Trk1 LACP - -# Add the required VLANs to the trunk -vlan 10 tagged Trk1 -vlan 100 tagged Trk1 -``` - -### Arista EOS configuration - - -When deploying VyOS in environments with Arista switches, use the following -blueprint as an initial setup to configure an operational LACP port-channel -between the two devices. - - -Let's assume the following topology: - - -```{eval-rst} -.. figure:: /_static/images/vyos_arista_bond_lacp.webp - :alt: VyOS Arista EOS setup -``` - - -**R1** - -```none -interfaces { - bonding bond10 { - hash-policy layer3+4 - member { - interface eth1 - interface eth2 - } - mode 802.3ad - vif 100 { - address 192.0.2.1/30 - address 2001:db8::1/64 - } - } -``` -**R2** - - - -```none -interfaces { - bonding bond10 { - hash-policy layer3+4 - member { - interface eth1 - interface eth2 - } - mode 802.3ad - vif 100 { - address 192.0.2.2/30 - address 2001:db8::2/64 - } - } -``` -**SW1** - -```none -! -vlan 100 - name FOO -! -interface Port-Channel10 - switchport trunk allowed vlan 100 - switchport mode trunk - spanning-tree portfast -! -interface Port-Channel20 - switchport mode trunk - no spanning-tree portfast auto - spanning-tree portfast network -! -interface Ethernet1 - channel-group 10 mode active -! -interface Ethernet2 - channel-group 10 mode active -! -interface Ethernet3 - channel-group 20 mode active -! -interface Ethernet4 - channel-group 20 mode active -! -``` -**SW2** - - - -```none -! -vlan 100 - name FOO -! -interface Port-Channel10 - switchport trunk allowed vlan 100 - switchport mode trunk - spanning-tree portfast -! -interface Port-Channel20 - switchport mode trunk - no spanning-tree portfast auto - spanning-tree portfast network -! -interface Ethernet1 - channel-group 10 mode active -! -interface Ethernet2 - channel-group 10 mode active -! -interface Ethernet3 - channel-group 20 mode active -! -interface Ethernet4 - channel-group 20 mode active -! -``` -:::{note} -When testing this environment in EVE-NG, ensure the e1000 driver -is chosen for your VyOS network interfaces. If the default virtio driver -is used, VyOS will not transmit LACP PDUs, preventing the port-channel -from ever becoming active. -::: - - -(operation)= - -## Operation - -```{opcmd} show interfaces bonding - -Show brief interface information. - - -:::{code-block} none -vyos@vyos:~$ show interfaces bonding -Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down -Interface IP Address S/L Description ---------- ---------- --- ----------- -bond0 - u/u my-sw1 int 23 and 24 -bond0.10 192.168.0.1/24 u/u office-net -bond0.100 10.10.10.1/24 u/u management-net -::: -``` -```{opcmd} show interfaces bonding \ - -Show detailed interface information. - -:::{code-block} none -vyos@vyos:~$ show interfaces bonding bond5 -bond5: mtu 1500 qdisc noqueue state DOWN group default qlen 1000 - link/ether 00:50:56:bf:ef:aa brd ff:ff:ff:ff:ff:ff - inet6 fe80::e862:26ff:fe72:2dac/64 scope link tentative - valid_lft forever preferred_lft forever - - RX: bytes packets errors dropped overrun mcast - 0 0 0 0 0 0 - TX: bytes packets errors dropped carrier collisions - 0 0 0 0 0 0 -::: -``` -```{opcmd} show interfaces bonding \ detail - -Show detailed information about the underlying physical links on the given -bonding interface. - -:::{code-block} none -vyos@vyos:~$ show interfaces bonding bond5 detail -Ethernet Channel Bonding Driver: v3.7.1 (April 27, 2011) -Bonding Mode: IEEE 802.3ad Dynamic link aggregation -Transmit Hash Policy: layer2 (0) -MII Status: down -MII Polling Interval (ms): 100 -Up Delay (ms): 0 -Down Delay (ms): 0 -802.3ad info -LACP rate: slow -Min links: 0 -Aggregator selection policy (ad_select): stable -Slave Interface: eth1 -MII Status: down -Speed: Unknown -Duplex: Unknown -Link Failure Count: 0 -Permanent HW addr: 00:50:56:bf:ef:aa -Slave queue ID: 0 -Aggregator ID: 1 -Actor Churn State: churned -Partner Churn State: churned -Actor Churned Count: 1 -Partner Churned Count: 1 -Slave Interface: eth2 -MII Status: down -Speed: Unknown -Duplex: Unknown -Link Failure Count: 0 -Permanent HW addr: 00:50:56:bf:19:26 -Slave queue ID: 0 -Aggregator ID: 2 -Actor Churn State: churned -Partner Churn State: churned -Actor Churned Count: 1 -Partner Churned Count: 1 -::: -``` \ No newline at end of file diff --git a/docs/configuration/interfaces/md-bridge.md b/docs/configuration/interfaces/md-bridge.md deleted file mode 100644 index 77775767..00000000 --- a/docs/configuration/interfaces/md-bridge.md +++ /dev/null @@ -1,431 +0,0 @@ ---- -lastproofread: '2025-12-22' ---- - -(bridge-interface)= - -# Bridge - -VyOS bridges connect Ethernet segments by grouping multiple interfaces into a -single bridge interface, which acts as a virtual software switch. Unlike -routers, which forward traffic based on Layer 3 IP addresses, bridges operate -at Layer 2 and forward traffic based on MAC addresses. Operating at Layer 2, -bridges are protocol-agnostic and transparently forward all Ethernet- -encapsulated traffic, whether it is IPv4, IPv6, or specialized industrial -protocols. - -This implementation utilizes the Linux bridge subsystem to support a subset of -the ANSI/IEEE 802.1d standard for transparent bridging and MAC address learning. - -:::{note} -{abbr}`STP (Spanning Tree Protocol)` is disabled by default in VyOS -and must be explicitly enabled if required. See {ref}`stp` for details. -::: - -## Configuration - -### Common interface configuration - -```{cmdincludemd} /_include/interface-common-with-dhcp.txt -:var0: bridge -:var1: br0 -``` - - -### Member interfaces - -```{cfgcmd} set interfaces bridge \ member interface \ - -**Configure an interface as a bridge member.** - -Valid interface types are: {ref}`ethernet-interface`, {ref}`bond-interface`, -{ref}`l2tpv3-interface`, {ref}`openvpn`, {ref}`vxlan-interface`, -{ref}`wireless-interface`, {ref}`tunnel-interface`, and -{ref}`geneve-interface`. - -Use tab completion to list interfaces that can be bridged. -``` - -```{cfgcmd} set interfaces bridge \ member interface \ priority \ - -**Configure the** {abbr}`STP (Spanning Tree Protocol)` **port priority -for a specific member interface within a bridge.** - -Within the {abbr}`STP (Spanning Tree Protocol)` topology, each member interface -in a bridge operates as a port with an assigned **priority** and **path cost**. -{abbr}`STP (Spanning Tree Protocol)` uses these values to determine the -**lowest-cost path** to the root bridge, maintaining a loop-free topology. -Traffic flows through the path with the lowest path cost, while alternate -paths remain in standby. - -A **lower** priority value means **higher** precedence in path selection. - -{abbr}`STP (Spanning Tree Protocol)` considers the port priority only if -multiple member interfaces have the same path costs. -``` - -```{cfgcmd} set interfaces bridge \ member interface \ cost \ - -**Configure the** {abbr}`STP (Spanning Tree Protocol)` **path cost for a -specific member interface within the bridge.** - -Path cost is the primary metric {abbr}`STP (Spanning Tree Protocol)` uses to -determine the path to the root bridge. This value is based on interface -bandwidth; faster interfaces receive lower costs. - -By assigning a lower cost, you give the interface higher precedence during -path selection. -``` - -```{cfgcmd} set interfaces bridge \ member interface \ disable-learning - -**Disable MAC address learning for a specific member interface -within a bridge.** - -When learning is disabled, the bridge will not add source MAC addresses -observed on this port to its forwarding database (FDB). Frames destined -to MACs not present in the FDB are then flooded to all bridge ports -rather than unicast-forwarded. -``` - - -### Bridge options - -Configure how bridge interfaces maintain their {abbr}`FDB (Forwarding Database)` -, react to topology changes, and optimize multicast data streams. - -```{cfgcmd} set interfaces bridge \ aging \ - -**Configure the MAC address aging time for the bridge.** - -The duration in seconds that a MAC address remains in the bridge’s {abbr}`FDB -(Forwarding Database)` before removal if no traffic is received from that -address. - -The default value is 300 seconds. -``` - -```{cfgcmd} set interfaces bridge \ max-age \ - -**Configure the** {abbr}`STP (Spanning Tree Protocol)` **max age timer for -the bridge.** - -The duration in seconds that the bridge waits for a {abbr}`BPDU (Bridge -Protocol Data Unit)` from the root bridge. - -If the bridge does not receive a {abbr}`BPDU (Bridge Protocol Data Unit)` -within this period, it recalculates the path to the root bridge or initiates -a new root bridge election. -``` - -```{cfgcmd} set interfaces bridge \ igmp querier - -**Configure the bridge interface to act as the** {abbr}`IGMP (Internet Group -Management Protocol)`/{abbr}`MLD (Multicast Listener Discovery)` **Querier.** - -**When configured:** The bridge interface sends {abbr}`IGMP (Internet Group -Management Protocol)` (IPv4) and {abbr}`MLD (Multicast Listener Discovery)` -(IPv6) general queries to all connected hosts to identify active multicast -listeners. -``` - -```{cfgcmd} set interfaces bridge \ igmp snooping - -**Configure the bridge interface to perform** {abbr}`IGMP (Internet Group -Management Protocol)`/{abbr}`MLD (Multicast Listener Discovery)` -**snooping.** - -**When configured:** The bridge interface monitors {abbr}`IGMP (Internet Group -Management Protocol)` (IPv4) and {abbr}`MLD (Multicast Listener Discovery)` -(IPv6) join requests and restricts multicast traffic forwarding to only active -listeners. This prevents network flooding. -``` - -(stp)= - -#### STP configuration - -{abbr}`STP (Spanning Tree Protocol)` is a Layer 2 protocol that prevents loops -in Ethernet networks by ensuring only one logical path exists between any two -bridges. This creates a loop-free topology and prevents broadcast storms that -can crash the network. - -By default, {abbr}`STP (Spanning Tree Protocol)` is disabled on bridge interfaces. -To activate loop prevention, you must explicitly enable the protocol and -configure its parameters. - -```{cfgcmd} set interfaces bridge \ stp - -Enable {abbr}`STP (Spanning Tree Protocol)` on the bridge interface. -``` - -```{cfgcmd} set interfaces bridge \ forwarding-delay \ - -**Configure the** {abbr}`STP (Spanning Tree Protocol)` **delay, in seconds, -for the bridge interface.** - -This parameter defines how long the bridge interface remains in the listening -and learning states before forwarding traffic. The delay ensures that the -bridge has sufficient time to detect loops (in the listening state) and learn -the MAC addresses of connected devices (in the learning state). - -The default value is 15 seconds. The total time before forwarding begins is -twice this value. -``` - -```{cfgcmd} set interfaces bridge \ hello-time \ - -**Configure the** {abbr}`STP (Spanning Tree Protocol)` **Hello advertisement -interval, in seconds.** - -This parameter sets the frequency at which the bridge interface transmits -Hello packets ({abbr}`BPDUs (Bridge Protocol Data Units)`). These packets -originate from the root bridge and are propagated by designated bridges. If -neighbors stop receiving Hello packets, they assume a connection failure and -trigger a topology recalculation. - -The default value is 2 seconds. -``` - - -### VLAN - -#### VLAN-aware bridges - -```{cfgcmd} set interfaces bridge \ enable-vlan - -**Enable VLAN filtering (also known as VLAN awareness) on the bridge interface.** - -When enabled, the bridge strictly segregates traffic among VLANs configured -on its member interfaces. - -:::{note} -Do not configure **vif 1** on a VLAN-aware bridge. The main bridge -interface acts as VLAN 1 (the default native VLAN) and automatically -handles all untagged traffic. -::: -``` - -```{cfgcmd} set interfaces bridge \ protocol \<802.1ad | 802.1q\> - -**Configure the VLAN protocol (EtherType) for the bridge interface.** - -The following options are available: -* ``802.1q`` (default): Sets the EtherType to ``0x8100``. Used for standard -enterprise VLANs. -* ``802.1ad``: Sets the EtherType to ``0x88a8``. Used for QinQ (provider bridging). -``` - - -#### VLAN configuration - -```{cmdincludemd} /_include/interface-vlan-8021q.txt -:var0: bridge -:var1: br0 -``` - -```{cfgcmd} set interfaces bridge \ member interface \ native-vlan \ - -**Configure the native VLAN ID for a specific member interface within a -VLAN-aware bridge.** - -This assigns the specified ```` to untagged traffic entering the member -interface. The bridge strips the VLAN tag from outgoing traffic matching this -ID. - -**Example:** - -Set the native VLAN ID to 2 for the member interface ``eth0``: - -:::{code-block} none -set interfaces bridge br1 member interface eth0 native-vlan 2 -::: -``` - -```{cfgcmd} set interfaces bridge \ member interface \ allowed-vlan \ - -**Configure allowed VLAN IDs for a specific member interface within a -VLAN-aware bridge.** - -Enter a single VLAN ID or a range of VLAN IDs separated by a hyphen. - -**Example:** - -To allow VLAN ID 4 on member interface ``eth0``: - -:::{code-block} none -set interfaces bridge br1 member interface eth0 allowed-vlan 4 -::: -**Example:** - -To allow VLAN IDs 6 through 8 on member interface ``eth0``: - -:::{code-block} none -set interfaces bridge br1 member interface eth0 allowed-vlan 6-8 -::: -``` - - -### SPAN port mirroring - -```{cmdincludemd} ../../_include/interface-mirror.txt -:var0: bridge -:var1: br1 -:var2: eth3 -``` - - -## Examples - -### Configure a standard bridge - -The following example creates a bridge named br100 with {abbr}`STP (Spanning -Tree Protocol)` enabled. - -Configuration requirements: -- **Bridge name:** `br100` -- **Member interfaces:** Physical interface `eth1` and VLAN interface `eth2.10`. -- **STP:** Enabled. -- **Bridge IP addresses:** `192.0.2.1/24` (IPv4) and `2001:db8::ffff/64` (IPv6). - -```none -set interfaces bridge br100 address 192.0.2.1/24 -set interfaces bridge br100 address 2001:db8::ffff/64 -set interfaces bridge br100 member interface eth1 -set interfaces bridge br100 member interface eth2.10 -set interfaces bridge br100 stp -``` - -Verify the configuration: - -```none -vyos@vyos# show interfaces bridge br100 - address 192.0.2.1/24 - address 2001:db8::ffff/64 - member { - interface eth1 { - } - interface eth2.10 { - } - } - stp -``` - - -### Configure a VLAN-aware bridge - -The following example creates a VLAN-aware bridge named br100. In this setup, -one member interface is configured as a trunk port, and the other as an access -port. The VLAN interface is configured with IP addresses. - -**Configuration requirements:** -- **Bridge name:** `br100`. -- **Trunk port** (`eth1`): Handles **tagged** traffic for VLAN 10. -- **Access port** (`eth2`): Handles **untagged** traffic (assigned to native - VLAN 10). -- **STP:** Enabled. -- **VLAN IP addresses** (`vif 10`): `192.0.2.1/24` (IPv4) and - `2001:db8::ffff/64` (IPv6). - -```none -set interfaces bridge br100 enable-vlan -set interfaces bridge br100 member interface eth1 allowed-vlan 10 -set interfaces bridge br100 member interface eth2 native-vlan 10 -set interfaces bridge br100 vif 10 address 192.0.2.1/24 -set interfaces bridge br100 vif 10 address 2001:db8::ffff/64 -set interfaces bridge br100 stp -``` - -Verify the configuration: - -```none -vyos@vyos# show interfaces bridge br100 - enable-vlan - member { - interface eth1 { - allowed-vlan 10 - } - interface eth2 { - native-vlan 10 - } - } - stp - vif 10 { - address 192.0.2.1/24 - address 2001:db8::ffff/64 - } -``` - - -### Operation - -```{opcmd} show bridge - -Show the status of member interfaces for all configured bridges. - -:::{code-block} none -vyos@vyos:~$ show bridge -3: eth1: mtu 1500 master br0 state forwarding -priority 32 cost 100 -4: eth2: mtu 1500 master br0 state forwarding -priority 32 cost 100 -::: -``` - -```{opcmd} show bridge \ fdb - -Show the {abbr}`FDB (Forwarding Database)` for the specified bridge. - -:::{code-block} none -vyos@vyos:~$ show bridge br0 fdb -50:00:00:08:00:01 dev eth1 vlan 20 master br0 permanent -50:00:00:08:00:01 dev eth1 vlan 10 master br0 permanent -50:00:00:08:00:01 dev eth1 master br0 permanent -33:33:00:00:00:01 dev eth1 self permanent -33:33:00:00:00:02 dev eth1 self permanent -01:00:5e:00:00:01 dev eth1 self permanent -50:00:00:08:00:02 dev eth2 vlan 20 master br0 permanent -50:00:00:08:00:02 dev eth2 vlan 10 master br0 permanent -50:00:00:08:00:02 dev eth2 master br0 permanent -33:33:00:00:00:01 dev eth2 self permanent -33:33:00:00:00:02 dev eth2 self permanent -01:00:5e:00:00:01 dev eth2 self permanent -33:33:00:00:00:01 dev br0 self permanent -33:33:00:00:00:02 dev br0 self permanent -33:33:ff:08:00:01 dev br0 self permanent -01:00:5e:00:00:6a dev br0 self permanent -33:33:00:00:00:6a dev br0 self permanent -01:00:5e:00:00:01 dev br0 self permanent -33:33:ff:00:00:00 dev br0 self permanent -::: -``` - -```{opcmd} show bridge \ mdb - -Show the {abbr}`MDB (Multicast group Database)` for the specified bridge. - -The {abbr}`MDB (Multicast group Database)` is populated by {abbr}`IGMP -(Internet Group Management Protocol)`/{abbr}`MLD (Multicast Listener -Discovery)` snooping and lists the multicast groups currently active on the -bridge. - -:::{code-block} none -vyos@vyos:~$ show bridge br0 mdb -dev br0 port br0 grp ff02::1:ff00:0 temp vid 1 -dev br0 port br0 grp ff02::2 temp vid 1 -dev br0 port br0 grp ff02::1:ff08:1 temp vid 1 -dev br0 port br0 grp ff02::6a temp vid 1 -::: -``` - -```{opcmd} show bridge \ macs - -Show the learned {abbr}`MAC (Media Access Control)` address table for the -specified bridge. - -:::{code-block} none -vyos@vyos:~$ show bridge br100 macs -port no mac addr is local? ageing timer - 1 00:53:29:44:3b:19 yes 0.00 -::: -``` \ No newline at end of file diff --git a/docs/configuration/interfaces/md-dummy.md b/docs/configuration/interfaces/md-dummy.md deleted file mode 100644 index d2d27c5d..00000000 --- a/docs/configuration/interfaces/md-dummy.md +++ /dev/null @@ -1,87 +0,0 @@ ---- -lastproofread: '2026-01-23' ---- - -(dummy-interface)= - -# Dummy - -A dummy interface is a virtual network interface that operates like the -loopback interface, accepting traffic and routing it back to the local host. -Unlike the loopback interface, which is limited to one per system and reserved -for internal system use, multiple dummy interfaces can be created, removed, and -managed without impacting core operations. - -As a software-based interface, the dummy interface does not depend on physical -link state and remains active as long as the operating system is running. - -Dummy interfaces are commonly used in environments with multiple redundant -uplinks (e.g., a server connected to two different switches), where assigning a -management IP address to a specific physical interface is risky. If that -interface fails, the management IP address becomes unreachable. - -Assigning the management IP address to a dummy interface and advertising it -over all available physical links ensures the address remains reachable as long -as at least one physical path is active. - -Dummy interfaces are also used for testing and simulation purposes. - -## Configuration - -### Common interface configuration - -```{cmdincludemd} /_include/interface-address.txt -:var0: dummy -:var1: dum0 -``` - -```{cmdincludemd} /_include/interface-description.txt -:var0: dummy -:var1: dum0 -``` - -```{cmdincludemd} /_include/interface-disable.txt -:var0: dummy -:var1: dum0 -``` - -```{cmdincludemd} /_include/interface-vrf.txt -:var0: dummy -:var1: dum0 -``` - - -## Operation - -```{opcmd} show interfaces dummy - -Show brief interface information. - -:::{code-block} none -vyos@vyos:~$ show interfaces dummy -Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down -Interface IP Address S/L Description ---------- ---------- --- ----------- -dum0 172.18.254.201/32 u/u -::: -``` - -```{opcmd} show interfaces dummy \ - -Show detailed interface information. - -:::{code-block} none -vyos@vyos:~$ show interfaces dummy dum0 -dum0: mtu 1500 qdisc noqueue state UNKNOWN group default qlen 1000 - link/ether 26:7c:8e:bc:fc:f5 brd ff:ff:ff:ff:ff:ff - inet 172.18.254.201/32 scope global dum0 - valid_lft forever preferred_lft forever - inet6 fe80::247c:8eff:febc:fcf5/64 scope link - valid_lft forever preferred_lft forever - - RX: bytes packets errors dropped overrun mcast - 0 0 0 0 0 0 - TX: bytes packets errors dropped carrier collisions - 1369707 4267 0 0 0 0 -::: -``` \ No newline at end of file diff --git a/docs/configuration/interfaces/md-ethernet.md b/docs/configuration/interfaces/md-ethernet.md deleted file mode 100644 index eac0b443..00000000 --- a/docs/configuration/interfaces/md-ethernet.md +++ /dev/null @@ -1,515 +0,0 @@ ---- -lastproofread: '2026-01-19' ---- - -(ethernet-interface)= - -# Ethernet - -Ethernet interfaces (e.g., `eth0`, `eth1`) represent the host's physical -or virtual network ports. - -They are the most common interface type, serving as the base layer upon which -IP addresses, VLANs, and tunnels are configured to carry traffic across both -LANs and WANs. - -## Configuration - -### Common interface configuration - -```{cmdincludemd} /_include/interface-common-with-dhcp.txt -:var0: ethernet -:var1: eth0 -``` - -```{cfgcmd} set interfaces ethernet \ switchdev - -**Enable** ``switchdev`` **mode for the interface.** - -In ``switchdev`` mode, the interface offloads traffic switching between ports -to the hardware, bypassing the host CPU. This increases the interface’s -traffic-handling capacity and reduces its forwarding delay. -``` - -:::{note} -`switchdev` mode is available only on certain physical network -interfaces and requires a switchdev-compatible driver. -::: - -### Ethernet options - -```{cfgcmd} set interfaces ethernet \ duplex \ - -**Configure duplex mode for the interface.** - -The following duplex modes are available: - -* ``auto``: The interface negotiates the duplex mode with the connected device. -* ``full``: The interface sends and receives data simultaneously. The - connected device must also be set to full-duplex to avoid a duplex mismatch. -* ``half``: The interface either sends or receives data, but not both at the - same time. - -The default duplex mode is ``auto``. -``` - -```{cfgcmd} set interfaces ethernet \ speed \ - -**Configure the interface's speed, in Mbit/s.** - -The following options are available: - -* ``auto``: The interface negotiates the speed with the connected device. -* ``10, 100, 1000 ...``: The interface operates at the selected speed. The - connected device must be set to the same speed to establish a connection. - -The default option is ``auto``. -``` - -```{cfgcmd} set interfaces ethernet \ ring-buffer rx \ - -**Configure the receive (RX) ring buffer size for the interface.** - -The RX ring buffer size defines the number of incoming packets the interface -can queue in hardware before the CPU processes them. - -Higher values reduce the risk of drops when the NIC receives network traffic -faster than the CPU can process it, though latency may increase. Lower values -reduce latency but increase the risk of packet drops during incoming traffic -bursts. - -To view supported values for a specific interface, use: -``` - -```none -ethtool -g -``` - -```{cfgcmd} set interfaces ethernet \ ring-buffer tx \ - -**Configure the transmit (TX) ring buffer size.** - -The TX ring buffer size defines the number of outgoing packets the interface -can queue in hardware before they are transmitted onto the network. - -Higher values reduce the risk of drops when the CPU generates traffic faster -than the NIC can handle, though latency may increase. Lower values reduce -latency but increase the risk of packet drops during outgoing traffic bursts. - -To view supported values for a specific interface, use: -``` - -```none -ethtool -g -``` - - -#### Interrupt Coalescing - -Interrupt coalescing is a mechanism that reduces CPU interrupt load by bundling -multiple packets into a single interrupt event instead of interrupting -the CPU for every packet arrival or transmission. - -:::{note} -Not all network drivers or virtual interfaces support all -coalescing parameters. Use `ethtool --show-coalesce ` -to verify which settings are supported by your hardware and driver. -::: - -**Basic adaptive coalescing** - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing adaptive-rx - -``` -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing adaptive-tx - -Enable adaptive interrupt coalescing. The NIC automatically tunes RX/TX -interrupt pacing based on traffic patterns to reduce CPU utilization -during high throughput while preserving latency at low packet rates. -``` - -**Basic interrupt delay** - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing rx-usecs \<0-16384\> -``` - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing tx-usecs \<0-16384\> - -Set the delay in microseconds before generating an RX/TX interrupt after -receiving or transmitting a packet. Lower values reduce latency; higher -values reduce CPU load. -``` - -**Interrupt frame thresholds** - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing rx-frames \ -``` - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing tx-frames \ - -Generate an RX/TX interrupt only after the specified number of packets -have been received or transmitted. -``` - -**IRQ-specific coalescing** - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing rx-usecs-irq \ -``` - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing rx-frames-irq \ -``` - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing tx-usecs-irq \ -``` - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing tx-frames-irq \ - -Control interrupt coalescing parameters while the driver is already -servicing an interrupt (IRQ context). These settings allow finer tuning -of interrupt behavior under sustained load. -``` - -**Adaptive rate thresholds** - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing pkt-rate-low \ -``` - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing pkt-rate-high \ - -Define packet-rate thresholds (packets per second) used by adaptive -coalescing to switch between low-rate and high-rate interrupt coalescing -profiles. -``` - -**Low-rate adaptive parameters** - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing rx-usecs-low \ -``` - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing rx-frame-low \ -``` - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing tx-usecs-low \ -``` - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing tx-frame-low \ - -Interrupt coalescing parameters applied when the packet rate is below -``pkt-rate-low``. Typically optimized for lower latency. -``` - -**High-rate adaptive parameters** - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing rx-usecs-high \ -``` - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing rx-frame-high \ -``` - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing tx-usecs-high \ -``` - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing tx-frame-high \ - -Interrupt coalescing parameters applied when the packet rate exceeds -``pkt-rate-high``. Typically optimized for maximum throughput and -reduced CPU utilization. -``` - -**Statistics and sampling** - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing stats-block-usecs \ -``` - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing sample-interval \ - -Control how frequently coalescing statistics are updated and how often -the NIC samples traffic rates for adaptive coalescing decisions. -``` - -**Completion queue (CQE) mode** - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing cqe-mode-rx -``` - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing cqe-mode-tx - -Enable RX/TX Completion Queue Entry (CQE) mode, if supported by the -driver. CQE mode can improve performance on high-speed NICs by -optimizing completion handling. -``` - -**Transmit aggregation** - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing tx-aggr-max-bytes \ -``` - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing tx-aggr-max-frames \ -``` - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing tx-aggr-time-usecs \ - -Control transmit packet aggregation. Packets may be buffered and sent -together until one of the configured limits (bytes, frames, or time) -is reached, reducing interrupt and DMA overhead. -``` - -#### Offloading - -```{cfgcmd} set interfaces ethernet \ offload \ - -**Configure the offloading features for the interface.** - -The interface offloading features define whether specific packet-processing tasks -are performed by hardware (the NIC) or by software (the kernel). You can enable -multiple offloading features for a single interface. - - * ``lro`` **(Large Receive Offload):** Instructs the NIC to merge multiple - incoming packets into one larger packet before sending it to the CPU. - - :::{note} - {abbr}`LRO (Large Receive Offload)` hardware support is often limited - to TCP/IPv4 packets. For details on LRO limitations, see - https://lwn.net/Articles/358910/ - ::: - :::{warning} - {abbr}`LRO (Large Receive Offload)` irreversibly alters packet - headers during merging. This prevents the merged packet from being correctly - split back into the original packets, causing packet drops and forwarding - failures on routers and bridges. Use {abbr}`LRO (Large Receive Offload)` only - for end-hosts that do not forward traffic. - ::: - * ``tso`` **(TCP Segmentation Offload):** Instructs the NIC to split large TCP - packets into smaller ones before transmitting them to the network. - - **Important:** {abbr}`SG (Scatter-Gather/Scatter-Gather DMA)` must be enabled - for {abbr}`TSO (TCP Segmentation Offload)` to work. Additionally, {abbr}`GSO - (Generic Segmentation Offload)` should be enabled as a safety fallback; it - ensures that if traffic is rerouted to hardware without {abbr}`TSO (TCP - Segmentation Offload)` support, the kernel can still segment the packets, - preventing transmission failures. - - * ``gso`` **(Generic Segmentation Offload):** Instructs the kernel to split - large packets into smaller ones before sending them to the NIC. - - {abbr}`GSO (Generic Segmentation Offload)` serves as a software fallback for - hardware that does not support {abbr}`TSO (TCP Segmentation Offload)` or for - protocols (like UDP) that hardware cannot offload. - - **Important:** {abbr}`SG (Scatter-Gather/Scatter-Gather DMA)` must be enabled - for {abbr}`GSO (Generic Segmentation Offload)` to work. - - * ``gro`` **(Generic Receive Offload):** Instructs the kernel to merge multiple - incoming packets into one larger packet before passing it to upper protocol - layers. - - Unlike LRO, GRO preserves the necessary packet metadata so the merged packet - can be correctly split back into the original packets. This makes GRO safe for - use on routers and bridges. - - :::{note} -The exception is for IPv4 IDs. If the "Don't Fragment" (DF) bit is -set and IDs are not sequential, {abbr}`GSO (Generic Segmentation Offload)` -alters them to maintain a consistent sequence for {abbr}`GSO (Generic -Segmentation Offload)` compatibility. - ::: - * ``rps`` **(Receive Packet Steering):** Instructs the kernel to distribute - the processing of incoming packets across multiple CPU cores. - - The kernel calculates a hash from packet headers (IP addresses and ports) to - ensure packets from the same flow are processed by the same CPU core. - - :::{note} -{abbr}`RPS (Receive Packet Steering)` is a software version of -{abbr}`RSS (Receive Side Scaling)` and is useful for NICs without hardware -multi-queue support. - ::: - * ``sg`` **(Scatter-Gather/Scatter-Gather DMA):** Instructs the NIC to fetch - data fragments from various RAM locations and transmit them as a single packet - to the network, eliminating the need for the kernel to copy them into a - contiguous block first. -``` - -#### 802.1X (EAPOL) authentication - -```{cmdincludemd} /_include/interface-eapol.txt -:var0: ethernet -:var1: eth0 -``` - -#### EVPN Multihoming - -Uplink/core tracking. - -```{cmdincludemd} /_include/interface-evpn-uplink.txt -:var0: ethernet -:var1: eth0 -``` - -### VLAN -#### Regular VLANs (802.1q) - -```{cmdincludemd} /_include/interface-vlan-8021q.txt -:var0: ethernet -:var1: eth0 -``` - -#### 802.1ad (QinQ) - -```{cmdincludemd} /_include/interface-vlan-8021ad.txt -:var0: ethernet -:var1: eth0 -``` - -### SPAN port mirroring - -```{cmdincludemd} ../../_include/interface-mirror.txt -:var0: ethernet -:var1: eth1 -:var2: eth3 -``` - -## Operation - -```{opcmd} show interfaces ethernet - -Show brief interface information. - -:::{code-block} none -vyos@vyos:~$ show interfaces ethernet -Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down -Interface IP Address S/L Description ---------- ---------- --- ----------- -eth0 172.18.201.10/24 u/u LAN -eth1 172.18.202.11/24 u/u WAN -eth2 - u/D -::: -``` - -```{opcmd} show interfaces ethernet \ - -Show detailed interface information. - -:::{code-block} none -vyos@vyos:~$ show interfaces ethernet eth0 -eth0: mtu 1500 qdisc pfifo_fast state UP group default qlen 1000 - link/ether 00:50:44:00:f5:c9 brd ff:ff:ff:ff:ff:ff - inet6 fe80::250:44ff:fe00:f5c9/64 scope link - valid_lft forever preferred_lft forever - - RX: bytes packets errors dropped overrun mcast - 56735451 179841 0 0 0 142380 - TX: bytes packets errors dropped carrier collisions - 5601460 62595 0 0 0 0 -::: -``` - -```{opcmd} show interfaces ethernet \ physical - -Show interface hardware-level and driver details. - -:::{code-block} none -vyos@vyos:~$ show interfaces ethernet eth0 physical -Settings for eth0: - Supported ports: [ TP ] - Supported link modes: 1000baseT/Full - 10000baseT/Full - Supported pause frame use: No - Supports auto-negotiation: No - Supported FEC modes: Not reported - Advertised link modes: Not reported - Advertised pause frame use: No - Advertised auto-negotiation: No - Advertised FEC modes: Not reported - Speed: 10000Mb/s - Duplex: Full - Port: Twisted Pair - PHYAD: 0 - Transceiver: internal - Auto-negotiation: off - MDI-X: Unknown - Supports Wake-on: uag - Wake-on: d - Link detected: yes -driver: vmxnet3 -version: 1.4.16.0-k-NAPI -firmware-version: -expansion-rom-version: -bus-info: 0000:0b:00.0 -supports-statistics: yes -supports-test: no -supports-eeprom-access: no -supports-register-dump: yes -supports-priv-flags: no -::: -``` - -```{opcmd} show interfaces ethernet \ physical offload - -Show the status of the interface offloading features. - -:::{code-block} none -vyos@vyos:~$ show interfaces ethernet eth0 physical offload -rx-checksumming on -tx-checksumming on -tx-checksum-ip-generic on -scatter-gather off -tx-scatter-gather off -tcp-segmentation-offload off -tx-tcp-segmentation off -tx-tcp-mangleid-segmentation off -tx-tcp6-segmentation off -udp-fragmentation-offload off -generic-segmentation-offload off -generic-receive-offload off -large-receive-offload off -rx-vlan-offload on -tx-vlan-offload on -ntuple-filters off -receive-hashing on -tx-gre-segmentation on -tx-gre-csum-segmentation on -tx-udp_tnl-segmentation on -tx-udp_tnl-csum-segmentation on -tx-gso-partial on -tx-nocache-copy off -rx-all off -::: -``` - -```{opcmd} show interfaces ethernet \ transceiver - -Show information about the transceiver module plugged into the interface -(e.g., SFP+, QSFP). - -:::{code-block} none -vyos@vyos:~$ show interfaces ethernet eth5 transceiver - Identifier : 0x03 (SFP) - Extended identifier : 0x04 (GBIC/SFP defined by 2-wire interface ID) - Connector : 0x07 (LC) - Transceiver codes : 0x00 0x00 0x00 0x01 0x00 0x00 0x00 0x00 0x00 - Transceiver type : Ethernet: 1000BASE-SX - Encoding : 0x01 (8B/10B) - BR, Nominal : 1300MBd - Rate identifier : 0x00 (unspecified) - Length (SMF,km) : 0km - Length (SMF) : 0m - Length (50um) : 550m - Length (62.5um) : 270m - Length (Copper) : 0m - Length (OM3) : 0m - Laser wavelength : 850nm - Vendor name : CISCO-FINISAR - Vendor OUI : 00:90:65 - Vendor PN : FTRJ-8519-7D-CS4 - Vendor rev : A - Option values : 0x00 0x1a - Option : RX_LOS implemented - Option : TX_FAULT implemented - Option : TX_DISABLE implemented - BR margin, max : 0% - BR margin, min : 0% - Vendor SN : FNS092xxxxx - Date code : 0506xx -::: -``` \ No newline at end of file diff --git a/docs/configuration/interfaces/md-geneve.md b/docs/configuration/interfaces/md-geneve.md deleted file mode 100644 index 1fce1119..00000000 --- a/docs/configuration/interfaces/md-geneve.md +++ /dev/null @@ -1,105 +0,0 @@ ---- -lastproofread: '2026-02-02' ---- - -(geneve-interface)= - -# Geneve - -{abbr}`Geneve (Generic Network Virtualization Encapsulation)` interfaces -operate as virtual network ports. Administrators can apply standard network -configurations on them, such as IP addressing, bridging, or firewall rules, -just as they would on physical Ethernet ports. - -The Geneve protocol encapsulates Layer 2 Ethernet frames originating from -endpoints such as virtual machines, containers, or physical servers inside UDP -packets. It unifies the features of earlier encapsulation protocols, including -VXLAN, NVGRE, and STT, and addresses their limitations, such as fixed header -structures and a lack of metadata support. Because of its extensibility, Geneve -may eventually replace those older protocols. - -Geneve tunnels are used to connect virtual switches residing within -hypervisors, physical switches, middleboxes, and other network appliances. - -Geneve tunnels operate over any standard IP network. In larger deployments, -the underlying network (underlay) is often built using a **Clos** topology, -also known as a *leaf-and-spine* or *fat-tree* topology. - -Geneve header: - -```none -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -|Ver| Opt Len |O|C| Rsvd. | Protocol Type | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Virtual Network Identifier (VNI) | Reserved | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Variable Length Options | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -``` - - -## Configuration - -### Common interface configuration - -```{cmdincludemd} /_include/interface-address.txt -:var0: geneve -:var1: gnv0 -``` - -```{cmdincludemd} /_include/interface-description.txt -:var0: geneve -:var1: gnv0 -``` - -```{cmdincludemd} /_include/interface-disable.txt -:var0: geneve -:var1: gnv0 -``` - -```{cmdincludemd} /_include/interface-mac.txt -:var0: geneve -:var1: gnv0 -``` - -```{cmdincludemd} /_include/interface-mtu.txt -:var0: geneve -:var1: gnv0 -``` - -```{cmdincludemd} /_include/interface-ip.txt -:var0: geneve -:var1: gnv0 -``` - -```{cmdincludemd} /_include/interface-ipv6.txt -:var0: geneve -:var1: gnv0 -``` - - -### Geneve options - -```{cfgcmd} set interfaces geneve gnv0 remote \ - -Configure the remote endpoint IP address for the Geneve tunnel. -``` - -```{cfgcmd} set interfaces geneve gnv0 vni \ - -**Configure** {abbr}`VNI (Virtual Network Identifier)` **for the Geneve -interface.** - -The VNI is a virtual network identifier. It allows multiple virtual networks to -share the same physical infrastructure and remain isolated. - -The VNI is also used to distribute traffic after it leaves the tunnel, for -example, to map packets with overlapping IP addresses to specific routing -tables. -``` - -```{cfgcmd} set interfaces gnv0 \ port \ - -**Configure the destination UDP port for the remote Geneve tunnel endpoint.** -Ensure the remote peer is configured to listen on this specific port. -``` \ No newline at end of file diff --git a/docs/configuration/interfaces/md-index.md b/docs/configuration/interfaces/md-index.md deleted file mode 100644 index 9082cd80..00000000 --- a/docs/configuration/interfaces/md-index.md +++ /dev/null @@ -1,26 +0,0 @@ -# Interfaces - -```{toctree} -:includehidden: true -:maxdepth: 1 - -bonding -bridge -dummy -ethernet -geneve -l2tpv3 -loopback -macsec -openvpn -wireguard -pppoe -pseudo-ethernet -sstp-client -tunnel -virtual-ethernet -vti -vxlan -wireless -wwan -``` diff --git a/docs/configuration/interfaces/md-l2tpv3.md b/docs/configuration/interfaces/md-l2tpv3.md deleted file mode 100644 index 324840fa..00000000 --- a/docs/configuration/interfaces/md-l2tpv3.md +++ /dev/null @@ -1,170 +0,0 @@ ---- -lastproofread: '2026-02-05' ---- - -(l2tpv3-interface)= - -# L2TPv3 - -{abbr}`L2TPv3 (Layer 2 Tunneling Protocol version 3)` interfaces let you -establish L2TPv3 tunnels to transport Layer 2 traffic over IP networks. - -The L2TPv3 protocol (defined in RFC 3931) wraps Layer 2 frames (e.g., Ethernet, -Frame Relay, HDLC) within IP packets, allowing them to traverse the underlying -IP infrastructure. - -Unlike L2TPv2, which strictly requires UDP encapsulation, the L2TPv3 protocol -is more flexible and supports two encapsulation types: - -> - **Direct IP:** Tunnel data is encapsulated directly inside IP packets -> (Protocol 115) for lower overhead. -> - **UDP:** Tunnel data is encapsulated inside a UDP datagram. This allows the -> tunnel to traverse NAT more easily. - -L2TPv3 tunnels connect geographically separated sites, serving as a simpler -alternative to {ref}`mpls` by operating over basic IP connectivity rather than -requiring a full MPLS infrastructure. - -L2TPv3 tunnels can be established over both IPv4 and IPv6 underlying networks. - -## Configuration - -### Common interface configuration - -```{cmdincludemd} /_include/interface-common-without-dhcp.txt -:var0: l2tpv3 -:var1: l2tpeth0 -``` - - -### L2TPv3 options - -Use the following commands to configure the L2TPv3 tunnel's specific parameters. - -```{cfgcmd} set interfaces l2tpv3 \ encapsulation \ - -**Configure the encapsulation type for the L2TPv3 tunnel.** - -Valid values are ``udp`` and ``ip``. - -The default encapsulation type is ``udp``. -``` - -:::{note} -The encapsulation type must match on both the local and remote peers -for the tunnel to establish. -::: - -```{cfgcmd} set interfaces l2tpv3 \ source-address \ - -**Configure the L2TPv3 tunnel source IP address.** - -The specified address must be a local interface IP address and can be either -IPv4 or IPv6. -``` - -```{cfgcmd} set interfaces l2tpv3 \ remote \ - -**Configure the L2TPv3 tunnel destination IP address.** - -The specified address must be a remote peer’s interface IP address and can be -either IPv4 or IPv6. -``` - -```{cfgcmd} set interfaces l2tpv3 \ session-id \ - -**Configure the local session ID within the L2TPv3 tunnel.** - -The ``session-id`` is a 32-bit value that identifies an incoming tunnel session -on the local peer. - -The ``peer-session-id`` that identifies this session on the remote peer must be -set to the same value. -``` - -```{cfgcmd} set interfaces l2tpv3 \ peer-session-id \ - -**Configure the peer session ID within the L2TPv3 tunnel.** - -The ``peer-session-id`` is a 32-bit value that identifies an outgoing tunnel -session from the local peer. - -The ``peer-session-id`` must match the ``session-id`` configured for this -session on the remote peer. -``` - -```{cfgcmd} set interfaces l2tpv3 \ tunnel-id \ - -**Configure the local identifier for the L2TPv3 tunnel.** - -The ``tunnel-id`` is a 32-bit value that identifies the L2TPv3 tunnel on the -local peer. - -The ``peer-tunnel-id`` that identifies this tunnel on the remote peer must be -set to the same value. -``` - -```{cfgcmd} set interfaces l2tpv3 \ peer-tunnel-id \ - -**Configure the peer identifier for the L2TPv3 tunnel.** - -The ``peer-tunnel-id`` is a 32-bit value that identifies the L2TPv3 tunnel on -the remote peer and must correspond to the ``tunnel-id`` configured for that -tunnel on that peer. - -The ``peer-tunnel-id`` must match the ``tunnel-id`` that identifies this tunnel -on the remote peer. -``` - - -## Example - -### L2TPv3 tunnel with IP encapsulation - -The following example shows the configuration of an L2TPv3 tunnel using direct -IP encapsulation: - -```none -# show interfaces l2tpv3 -l2tpv3 l2tpeth10 { - address 192.168.37.1/27 - encapsulation ip - source-address 192.0.2.1 - peer-session-id 100 - peer-tunnel-id 200 - remote 203.0.113.24 - session-id 100 - tunnel-id 200 -} -``` - -The inverse configuration must be applied to the remote peer. - -### L2TPv3 tunnel with UDP encapsulation - -The following example shows the configuration of an L2TPv3 tunnel using UDP -encapsulation. - -This setup is recommended when the tunnel traverses NAT devices. - -Configuration notes: -- Use a local LAN IP address as the `source-address`. -- Configure a forwarding rule to allow tunnel traffic on the specified UDP port - on the upstream NAT device. -- Use a distinct UDP port for each individual tunnel. - -```none -# show interfaces l2tpv3 -l2tpv3 l2tpeth10 { - address 192.168.37.1/27 - destination-port 9001 - encapsulation udp - source-address 192.0.2.1 - peer-session-id 100 - peer-tunnel-id 200 - remote 203.0.113.24 - session-id 100 - source-port 9000 - tunnel-id 200 -} -``` diff --git a/docs/configuration/interfaces/md-loopback.md b/docs/configuration/interfaces/md-loopback.md deleted file mode 100644 index 72f14c16..00000000 --- a/docs/configuration/interfaces/md-loopback.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -lastproofread: '2026-01-23' ---- - -(loopback-interface)= - -# Loopback - -The loopback interface is a virtual, software-based network interface. All -traffic sent to it loops back and only targets services on the local host. - -:::{note} -Only one loopback `lo` interface is allowed per operating system. -If you require multiple virtual interfaces, use the {ref}`dummy-interface` -interface type. -::: - -## Configuration - -### Common interface configuration - -```{cmdincludemd} /_include/interface-address.txt -:var0: loopback -:var1: lo -``` - -```{cmdincludemd} /_include/interface-description.txt -:var0: loopback -:var1: lo -``` - - -## Operation - -```{opcmd} show interfaces loopback - -Show brief interface information. - -:::{code-block} none -vyos@vyos:~$ show interfaces loopback -Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down -Interface IP Address S/L Description ---------- ---------- --- ----------- -lo 127.0.0.1/8 u/u - ::1/128 -::: -``` - -```{opcmd} show interfaces loopback lo - -Show detailed interface information. - -:::{code-block} none -vyos@vyos:~$ show interfaces loopback lo -lo: mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1000 - link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00 - inet 127.0.0.1/8 scope host lo - valid_lft forever preferred_lft forever - inet6 ::1/128 scope host - valid_lft forever preferred_lft forever - - RX: bytes packets errors dropped overrun mcast - 300 6 0 0 0 0 - TX: bytes packets errors dropped carrier collisions - 300 6 0 0 0 0 -::: -``` \ No newline at end of file diff --git a/docs/configuration/interfaces/md-macsec.md b/docs/configuration/interfaces/md-macsec.md deleted file mode 100644 index b3c70362..00000000 --- a/docs/configuration/interfaces/md-macsec.md +++ /dev/null @@ -1,319 +0,0 @@ ---- -lastproofread: '2026-02-13' ---- - -(macsec-interface)= - -# MACsec - -MACsec is an IEEE standard (IEEE 802.1AE) for MAC security, introduced in -2006\. It enables protocol-independent connectivity between two hosts, providing -data confidentiality, authenticity, and integrity using GCM-AES ciphers. MACsec -operates at the Ethernet layer as a Layer 2 protocol and secures traffic within -Layer 2 networks, including DHCP and ARP requests. It does not compete with -other security solutions, such as IPsec (Layer 3) or TLS (Layer 4), as each -addresses distinct use cases. - -## Configuration - -### Common interface configuration - -```{cmdincludemd} /_include/interface-common-with-dhcp.txt -:var0: macsec -:var1: macsec0 -``` - - -### MACsec options - -```{cfgcmd} set interfaces macsec \ security cipher \ - -**Configure the cipher suite for the MACsec interface.** - -This configuration parameter is mandatory. -``` - -```{cfgcmd} set interfaces macsec \ security encrypt - -**Enable encryption on the MACsec interface.** - -By default, MACsec interfaces only provide authentication; encryption is -optional. -When enabled, outgoing packets are encrypted using the configured cipher suite. -``` - -```{cfgcmd} set interfaces macsec \ source-interface \ - -**Configure a physical source interface for the MACsec interface.** - -Traffic transmitted through this interface is authenticated and, if configured, -encrypted. -``` - - -#### MACsec key management - -**Static** {abbr}`SAK (Secure Authentication Key)` **mode** - -In static SAK mode, administrators must manually configure and update SAKs on -each MACsec peer. {abbr}`MKA (MACsec Key Agreement protocol)` cannot be used in -this mode. - -```{cfgcmd} set interfaces macsec \ security static key \ - -**Configure the Transmit (TX) SAK for the MACsec interface.** - -The key must be a 16-byte (GCM-AES-128) or 64-byte (GCM-AES-256) hexadecimal -string. -``` - -```{cfgcmd} set interfaces macsec \ security static peer \ mac \ - -**Configure the MAC address associated with the MACsec peer.** -``` - -```{cfgcmd} set interfaces macsec \ security static peer \ key \ - -**Configure the RX SAK for traffic from the MACsec peer.** - -The key must be a 16-byte (GCM-AES-128) or 64-byte (GCM-AES-256) hexadecimal -string. -``` - -```{cfgcmd} set interfaces macsec \ security static peer \ disable -``` - -**Dynamic** {abbr}`MKA (MACsec Key Agreement protocol)` **mode** - -In this mode, the {abbr}`MKA (MACsec Key Agreement protocol)` protocol is used -to generate, distribute, and update {abbr}`CAKs (MACsec Connectivity -Association Keys)`, and to authenticate MACsec peers. - -```{cfgcmd} set interfaces macsec \ security mka cak \ - -**Configure the** {abbr}`CAK (MACsec Connectivity Association Key)` **for the -MACsec interface.** - -The {abbr}`CAK (MACsec Connectivity Association Key)` and its {abbr}`CKN -(MACsec Connectivity Association Key Name)` form the pre-shared master key pair -used to authenticate MACsec peers. -``` - -```{cfgcmd} set interfaces macsec \ security mka ckn \ - -Configure the {abbr}`CKN (MACsec Connectivity Association Key Name)` for the -MACsec interface. -``` - -```{cfgcmd} set interfaces macsec \ security mka priority \ - -Configure the MKA key server priority for the MACsec interface. -The peer with the lowest priority is elected as the key server. -``` - -#### Replay protection - -```{cfgcmd} set interfaces macsec \ security replay-window \ - -The replay protection window defines how many out-of-order frames can be -received before they are dropped as a potential replay attack. -The following values are valid: -- ``0``: Any out-of-order frame is immediately dropped. -- ``1-4294967295``: Allows the specified number of out-of-order frames. -``` - -## Operation - -```{opcmd} run generate macsec mka cak \ - -Generate a 128-bit (GCM-AES-128) or 256-bit (GCM-AES-256) {abbr}`MKA (MACsec -Key Agreement protocol)` {abbr}`CAK (MACsec Connectivity Association Key)`. - -:::{code-block} none -vyos@vyos:~$ generate macsec mka cak gcm-aes-128 -20693b6e08bfa482703a563898c9e3ad -::: -``` - -```{opcmd} run generate macsec mka ckn - -Generate an {abbr}`MKA (MACsec Key Agreement protocol)` {abbr}`CAK (MACsec -Connectivity Association Key)`. - -:::{code-block} none -vyos@vyos:~$ generate macsec mka ckn -88737efef314ee319b2cbf30210a5f164957d884672c143aefdc0f5f6bc49eb2 -::: -``` - -```{opcmd} show interfaces macsec - -Show all MACsec interfaces. - -:::{code-block} none -vyos@vyos:~$ show interfaces macsec -17: macsec1: protect on validate strict sc off sa off encrypt on send_sci on end_station off scb off replay off -cipher suite: GCM-AES-128, using ICV length 16 -TXSC: 005056bfefaa0001 on SA 0 -20: macsec0: protect on validate strict sc off sa off encrypt off send_sci on end_station off scb off replay off -cipher suite: GCM-AES-128, using ICV length 16 -TXSC: 005056bfefaa0001 on SA 0 -::: -``` - -```{opcmd} show interfaces macsec \ - -Show information for a specific MACsec interface. - -:::{code-block} none -vyos@vyos:~$ show interfaces macsec macsec1 -17: macsec1: protect on validate strict sc off sa off encrypt on send_sci on end_station off scb off replay off -cipher suite: GCM-AES-128, using ICV length 16 -TXSC: 005056bfefaa0001 on SA 0 -::: -``` - -## Examples - -**Site-to-site MACsec with dynamic MKA over an untrusted network** - -In the following example, two routers (R1 and R2) are connected via an -untrusted switch, using their `eth1` interfaces as the underlay. The MACsec -interface (`macsec1`) with dynamic MKA encrypts traffic between them. - -Topology details: -- R1 IP addresses: `192.0.2.1/24` and `2001:db8::1/64`. -- R2 IP addresses: `192.0.2.2/24` and `2001:db8::2/64`. - -**R1** - -```none -set interfaces macsec macsec1 address '192.0.2.1/24' -set interfaces macsec macsec1 address '2001:db8::1/64' -set interfaces macsec macsec1 security cipher 'gcm-aes-128' -set interfaces macsec macsec1 security encrypt -set interfaces macsec macsec1 security mka cak '232e44b7fda6f8e2d88a07bf78a7aff4' -set interfaces macsec macsec1 security mka ckn '40916f4b23e3d548ad27eedd2d10c6f98c2d21684699647d63d41b500dfe8836' -set interfaces macsec macsec1 source-interface 'eth1' -``` - -**R2** - -```none -set interfaces macsec macsec1 address '192.0.2.2/24' -set interfaces macsec macsec1 address '2001:db8::2/64' -set interfaces macsec macsec1 security cipher 'gcm-aes-128' -set interfaces macsec macsec1 security encrypt -set interfaces macsec macsec1 security mka cak '232e44b7fda6f8e2d88a07bf78a7aff4' -set interfaces macsec macsec1 security mka ckn '40916f4b23e3d548ad27eedd2d10c6f98c2d21684699647d63d41b500dfe8836' -set interfaces macsec macsec1 source-interface 'eth1' -``` - -Pinging (IPv6) the other host and intercepting traffic on `eth1` confirm that -the content is encrypted. - -```none -17:35:44.586668 00:50:56:bf:ef:aa > 00:50:56:b3:ad:d6, ethertype Unknown (0x88e5), length 150: - 0x0000: 2c00 0000 000a 0050 56bf efaa 0001 d9fb ,......PV....... - 0x0010: 920a 8b8d 68ed 9609 29dd e767 25a4 4466 ....h...)..g%.Df - 0x0020: 5293 487b 9990 8517 3b15 22c7 ea5c ac83 R.H{....;."..\.. - 0x0030: 4c6e 13cf 0743 f917 2c4e 694e 87d1 0f09 Ln...C..,NiN.... - 0x0040: 0f77 5d53 ed75 cfe1 54df 0e5a c766 93cb .w]S.u..T..Z.f.. - 0x0050: c4f2 6e23 f200 6dfe 3216 c858 dcaa a73b ..n#..m.2..X...; - 0x0060: 4dd1 9358 d9e4 ed0e 072f 1acc 31c4 f669 M..X...../..1..i - 0x0070: e93a 9f38 8a62 17c6 2857 6ac5 ec11 8b0e .:.8.b..(Wj..... - 0x0080: 6b30 92a5 7ccc 720b k0..|.r. -``` - -Disabling encryption on the MACsec interface by removing the `security -encrypt` option shows the unencrypted but authenticated content. - -```none -17:37:00.746155 00:50:56:bf:ef:aa > 00:50:56:b3:ad:d6, ethertype Unknown (0x88e5), length 150: - 0x0000: 2000 0000 0009 0050 56bf efaa 0001 86dd .......PV....... - 0x0010: 6009 86f3 0040 3a40 2001 0db8 0000 0000 `....@:@........ - 0x0020: 0000 0000 0000 0001 2001 0db8 0000 0000 ................ - 0x0030: 0000 0000 0000 0002 8100 d977 0f30 0003 ...........w.0.. - 0x0040: 1ca0 c65e 0000 0000 8d93 0b00 0000 0000 ...^............ - 0x0050: 1011 1213 1415 1617 1819 1a1b 1c1d 1e1f ................ - 0x0060: 2021 2223 2425 2627 2829 2a2b 2c2d 2e2f .!"#$%&'()*+,-./ - 0x0070: 3031 3233 3435 3637 87d5 eed3 3a39 d52b 01234567....:9.+ - 0x0080: a282 c842 5254 ef28 ...BRT.( -``` - -**Site-to-site MACsec with static SAK over an untrusted network** - -This example uses the same topology as above, but applies static SAK mode to -the MACsec interface configuration. - -**R1** - -```none -set interfaces macsec macsec1 address '192.0.2.1/24' -set interfaces macsec macsec1 address '2001:db8::1/64' -set interfaces macsec macsec1 security cipher 'gcm-aes-128' -set interfaces macsec macsec1 security encrypt -set interfaces macsec macsec1 security static key 'ddd6f4a7be4d8bbaf88b26f10e1c05f7' -set interfaces macsec macsec1 security static peer R2 mac 00:11:22:33:44:02 -set interfaces macsec macsec1 security static peer R2 key 'eadcc0aa9cf203f3ce651b332bd6e6c7' -set interfaces macsec macsec1 source-interface 'eth1' -``` - -**R2** - -```none -set interfaces macsec macsec1 address '192.0.2.2/24' -set interfaces macsec macsec1 address '2001:db8::2/64' -set interfaces macsec macsec1 security cipher 'gcm-aes-128' -set interfaces macsec macsec1 security encrypt -set interfaces macsec macsec1 security static key 'eadcc0aa9cf203f3ce651b332bd6e6c7' -set interfaces macsec macsec1 security static peer R1 mac 00:11:22:33:44:01 -set interfaces macsec macsec1 security static peer R1 key 'ddd6f4a7be4d8bbaf88b26f10e1c05f7' -set interfaces macsec macsec1 source-interface 'eth1' -``` - -## MACsec over WAN - -MACsec offers an alternative to traditional tunneling solutions by securing -Layer 2 with integrity, origin authentication, and optional encryption. - -While typically deployed between hosts and access switches, MACsec can also -secure traffic over a WAN. In the following example, we combine VXLAN (for -transport) and MACsec (for security) to create a secure tunnel between two -sites. - -**R1 MACsec01** - -```none -set interfaces macsec macsec1 address '192.0.2.1/24' -set interfaces macsec macsec1 address '2001:db8::1/64' -set interfaces macsec macsec1 security cipher 'gcm-aes-128' -set interfaces macsec macsec1 security encrypt -set interfaces macsec macsec1 security static key 'ddd6f4a7be4d8bbaf88b26f10e1c05f7' -set interfaces macsec macsec1 security static peer SEC02 key 'eadcc0aa9cf203f3ce651b332bd6e6c7' -set interfaces macsec macsec1 security static peer SEC02 mac '00:11:22:33:44:02' -set interfaces macsec macsec1 source-interface 'vxlan1' -set interfaces vxlan vxlan1 mac '00:11:22:33:44:01' -set interfaces vxlan vxlan1 remote '10.1.3.3' -set interfaces vxlan vxlan1 source-address '172.16.100.1' -set interfaces vxlan vxlan1 vni '10' -set protocols static route 10.1.3.3/32 next-hop 172.16.100.2 -``` - -**R2 MACsec02** - -```none -set interfaces macsec macsec1 address '192.0.2.2/24' -set interfaces macsec macsec1 address '2001:db8::2/64' -set interfaces macsec macsec1 security cipher 'gcm-aes-128' -set interfaces macsec macsec1 security encrypt -set interfaces macsec macsec1 security static key 'eadcc0aa9cf203f3ce651b332bd6e6c7' -set interfaces macsec macsec1 security static peer SEC01 key 'ddd6f4a7be4d8bbaf88b26f10e1c05f7' -set interfaces macsec macsec1 security static peer SEC01 mac '00:11:22:33:44:01' -set interfaces macsec macsec1 source-interface 'vxlan1' -set interfaces vxlan vxlan1 mac '00:11:22:33:44:02' -set interfaces vxlan vxlan1 remote '10.1.2.2' -set interfaces vxlan vxlan1 source-address '172.16.100.2' -set interfaces vxlan vxlan1 vni '10' -set protocols static route 10.1.2.2/32 next-hop 172.16.100.1 -``` diff --git a/docs/configuration/interfaces/md-openvpn-examples.md b/docs/configuration/interfaces/md-openvpn-examples.md deleted file mode 100644 index 817e6868..00000000 --- a/docs/configuration/interfaces/md-openvpn-examples.md +++ /dev/null @@ -1,769 +0,0 @@ -# Site-to-site - -:::{todo} -Convert raw command blocks in this file to cfgcmd/opcmd directives for command coverage tracking. -::: - -OpenVPN is popular for client-server setups, but its site-to-site mode is less common and often not supported by router appliances. Despite limited support, it is effective for quickly establishing tunnels between routers. - -As of VyOS 1.4, OpenVPN site-to-site mode can use either pre-shared keys or x.509 certificates. - -Pre-shared key mode is now deprecated and will be removed from future OpenVPN versions. VyOS will also discontinue support for this option because pre-shared keys are significantly less secure than TLS. - -We will configure OpenVPN with self-signed certificates, and then discuss the legacy pre-shared key mode. - -In both cases, we will use the following settings: - -- The public IP address of the local VPN endpoint is 198.51.100.10. -- The public IP address of the remote VPN endpoint is 203.0.113.11. -- The tunnel uses 10.255.1.1 for the local IP address and 10.255.1.2 for the remote IP address. -- The local site has a subnet of 10.0.0.0/16. -- The remote site has a subnet of 10.1.0.0/16. -- The official OpenVPN port 1194 is reserved for client VPN. For site-to-site VPN, port 1195 is used. -- The `persistent-tunnel` directive allows us to configure tunnel-related attributes, such as firewall policy, as we would on any standard network interface. -- If known, the remote router\'s IP address can be configured using the `remote-host` directive. If unknown, it can be omitted. We assume the remote router has a dynamic IP address. - -![](/_static/images/openvpn_site2site_diagram.webp) - -## Set up site-to-site certificates - -Deploying a complete Public Key Infrastructure (PKI) with a Certificate Authority (CA) would overcomplicate site-to-site OpenVPN setups, which are primarily designed for simplicity. To keep their configuration simple without compromising security, VyOS 1.4 and later lets you verify self-signed certificates using certificate fingerprints. - -Generate a self-signed certificate on each router, preferably using the Elliptic Curve (EC) type. In configuration mode, run the following command: `run generate pki certificate self-signed install `. This adds the certificate to the configuration session\'s `pki` subtree. Review and commit the changes. - -``` none -vyos@vyos# run generate pki certificate self-signed install openvpn-local -Enter private key type: [rsa, dsa, ec] (Default: rsa) ec -Enter private key bits: (Default: 256) -Enter country code: (Default: GB) -Enter state: (Default: Some-State) -Enter locality: (Default: Some-City) -Enter organization name: (Default: VyOS) -Enter common name: (Default: vyos.io) -Do you want to configure Subject Alternative Names? [y/N] -Enter how many days certificate will be valid: (Default: 365) -Enter certificate type: (client, server) (Default: server) -Note: If you plan to use the generated key on this router, do not encrypt the private key. -Do you want to encrypt the private key with a passphrase? [y/N] -2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. -[edit] - -vyos@vyos# compare -[pki] -+ certificate openvpn-local { -+ certificate "MIICJTCCAcugAwIBAgIUMXLfRNJ5iOjk/uAZqUe4phW8MdgwCgYIKoZIzj0EAwIwVzELMAkGA1UEBhMCR0IxEzARBgNVBAgMClNvbWUtU3RhdGUxEjAQBgNVBAcMCVNvbWUtQ2l0eTENMAsGA1UECgwEVnlPUzEQMA4GA1UEAwwHdnlvcy5pbzAeFw0yMzA5MDcyMTQzMTNaFw0yNDA5MDYyMTQzMTNaMFcxCzAJBgNVBAYTAkdCMRMwEQYDVQQIDApTb21lLVN0YXRlMRIwEAYDVQQHDAlTb21lLUNpdHkxDTALBgNVBAoMBFZ5T1MxEDAOBgNVBAMMB3Z5b3MuaW8wWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAASp7D0vE3SKSAWAzr/lw9Eq9Q89r247AJR6ec/GT26AIcVA1bsongV1YaWvRwzTPC/yi5pkzV/PcT/WU7JQIyMWo3UwczAMBgNVHRMBAf8EAjAAMA4GA1UdDwEB/wQEAwIHgDATBgNVHSUEDDAKBggrBgEFBQcDATAdBgNVHQ4EFgQUBrAxRdFppdG/UBRdo7qNyHutaTQwHwYDVR0jBBgwFoAUBrAxRdFppdG/UBRdo7qNyHutaTQwCgYIKoZIzj0EAwIDSAAwRQIhAI2+8C92z9wTcTWkQ/goRxs10EBC+h78O+vgo9k97z5iAiBSeqfaVr5taQTS31+McGTAK3cYWNTg0DlOBI8aKO2oRg==" -+ private { -+ key "MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQgtOeEb0dMb5P/2Exi09WWvk6Cvz0oOBoDuP68ZimS2LShRANCAASp7D0vE3SKSAWAzr/lw9Eq9Q89r247AJR6ec/GT26AIcVA1bsongV1YaWvRwzTPC/yi5pkzV/PcT/WU7JQIyMW" -+ } -+ } - -[edit] - -vyos@vyos# commit -``` - -You do **not** need to copy the certificate to the other router. Instead, retrieve its SHA-256 fingerprint. Since OpenVPN currently supports only SHA-256 fingerprints, use the following command: - -``` none -vyos@vyos# run show pki certificate openvpn-local fingerprint sha256 -5C:B8:09:64:8B:59:51:DC:F4:DF:2C:12:5C:B7:03:D1:68:94:D7:5B:62:C2:E1:83:79:F1:F0:68:B2:81:26:79 -``` - -::::{note} -Certificate names are arbitrary. While `openvpn-local` and `openvpn-remote` are used here, you may choose any names. -:::: - -Repeat the procedure on the other router. - -## Set up site-to-site OpenVPN - -Local configuration: - -``` none -Configure the tunnel: - -set interfaces openvpn vtun1 mode site-to-site -set interfaces openvpn vtun1 protocol udp -set interfaces openvpn vtun1 persistent-tunnel -set interfaces openvpn vtun1 remote-host '203.0.113.11' # Public IP of the other side -set interfaces openvpn vtun1 local-port '1195' -set interfaces openvpn vtun1 remote-port '1195' -set interfaces openvpn vtun1 local-address '10.255.1.1' # Local IP of vtun interface -set interfaces openvpn vtun1 remote-address '10.255.1.2' # Remote IP of vtun interface -set interfaces openvpn vtun1 tls certificate 'openvpn-local' # The self-signed certificate -set interfaces openvpn vtun1 tls peer-fingerprint # The output of 'run show pki certificate fingerprint sha256' on the remote router -set interfaces openvpn vtun1 tls role active -``` - -Remote configuration: - -``` none -set interfaces openvpn vtun1 mode site-to-site -set interfaces openvpn vtun1 protocol udp -set interfaces openvpn vtun1 persistent-tunnel -set interfaces openvpn vtun1 remote-host '198.51.100.10' # Pub IP of other site -set interfaces openvpn vtun1 local-port '1195' -set interfaces openvpn vtun1 remote-port '1195' -set interfaces openvpn vtun1 local-address '10.255.1.2' # Local IP of vtun interface -set interfaces openvpn vtun1 remote-address '10.255.1.1' # Remote IP of vtun interface -set interfaces openvpn vtun1 tls certificate 'openvpn-remote' # The self-signed certificate -set interfaces openvpn vtun1 tls peer-fingerprint # The output of 'run show pki certificate fingerprint sha256 on the local router -set interfaces openvpn vtun1 tls role passive -``` - - -## Set up pre-shared keys - -Before VyOS 1.4, site-to-site OpenVPN without PKI required pre-shared keys. This option is still available but is deprecated and will be removed in future releases. If you need to set up a tunnel to an older VyOS version or a system with older OpenVPN, you still need to use pre-shared keys. - -First, generate a key by running `run generate pki openvpn shared-secret install ` in configuration mode. You can use any name; in this example, we use `s2s`. - -``` none -vyos@local# run generate pki openvpn shared-secret install s2s -2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. -[edit] -vyos@local# compare -[pki openvpn shared-secret] -+ s2s { -+ key "7c73046a9da91e874d31c7ad894a32688cda054bde157c64270f28eceebc0bb2f44dbb70335fad45148b0456aaa78cb34a34c0958eeed4f75e75fd99ff519ef940f7029a316c436d2366a2b0fb8ea1d1c792a65f67d10a461af83ef4530adc25d1c872de6d9c7d5f338223d1f3b66dc3311bbbddc0e05228c47b91c817c721aadc7ed18f0662df52ad14f898904372679e3d9697d062b0869d12de47ceb2e626fa12e1926a3119be37dd29c9b0ad81997230f4038926900d5edb78522d2940cfe207f8e2b948e0d459fa137ebb18064ac5982b28dd1899020b4f2b082a20d5d4eb65710fbb1e62b5e061df39620267eab429d3eedd9a1ae85957457c8e4655f3" -+ version "1" -+ } - -[edit] - -vyos@local# commit -[edit] -``` - -Next, install the key on the remote router: - -``` none -vyos@remote# set pki openvpn shared-secret s2s key -``` - -Finally, configure the key in your OpenVPN interface settings: - -``` none -set interfaces openvpn vtun1 shared-secret-key s2s -``` - - -## Set up firewall exceptions - -To allow OpenVPN traffic to pass through the WAN interface, create a firewall exception: - -``` none -set firewall ipv4 name OUTSIDE_LOCAL rule 10 action 'accept' -set firewall ipv4 name OUTSIDE_LOCAL rule 10 description 'Allow established/related' -set firewall ipv4 name OUTSIDE_LOCAL rule 10 state 'established' -set firewall ipv4 name OUTSIDE_LOCAL rule 10 state 'related' -set firewall ipv4 name OUTSIDE_LOCAL rule 20 action 'accept' -set firewall ipv4 name OUTSIDE_LOCAL rule 20 description 'OpenVPN_IN' -set firewall ipv4 name OUTSIDE_LOCAL rule 20 destination port '1195' -set firewall ipv4 name OUTSIDE_LOCAL rule 20 log -set firewall ipv4 name OUTSIDE_LOCAL rule 20 protocol 'udp' -``` - -Apply the OUTSIDE_LOCAL firewall group to the WAN interface and to the input filter for traffic destined for the router itself: - -``` none -set firewall ipv4 input filter rule 10 action 'jump' -set firewall ipv4 input filter rule 10 inbound-interface name eth0 -set firewall ipv4 input filter rule 10 jump-target OUTSIDE_LOCAL -``` - -Static routing: - -Configure static routes by referencing the tunnel interface. For example, if the local router\'s network is `10.0.0.0/16` and the remote router\'s network is `10.1.0.0/16`, define the routes as follows: - -Local configuration: - -``` none -set protocols static route 10.1.0.0/16 interface vtun1 -``` - -Remote configuration: - -``` none -set protocols static route 10.0.0.0/16 interface vtun1 -``` - -As with standard Ethernet interfaces, you can apply firewall policies to the tunnel interface for input, output, and forward directions. - -If you use multiple tunnels, OpenVPN must distinguish between them beyond just the pre-shared key. To achieve this, assign either unique IP addresses or unique ports to each tunnel. - -Verify OpenVPN status using the show openvpn operational commands. - -``` none -vyos@vyos:~$ show openvpn site-to-site - -OpenVPN status on vtun1 - -Client CN Remote Host Tunnel IP Local Host TX bytes RX bytes Connected Since ------------ ----------------- ----------- ------------ ---------- ---------- ----------------- -N/A 10.110.12.54:1195 N/A N/A 504.0 B 656.0 B N/A -``` - - -### Server-client - -In OpenVPN's server-client mode, the server acts as a central hub, allowing multiple clients to connect and securely route their traffic or access a private network. Multi-client server is the most popular OpenVPN mode for routers. - -## Set up server-client certificates - -Server-client mode always uses x.509 authentication and therefore requires a PKI setup. The PKI utility now simplifies the creation of Certificate Authorities (CAs), server and client certificates, and Diffie-Hellman keys directly in VyOS using configuration or operational mode commands. - -On the server, generate all certificates by running the following commands in configuration mode. The certificates will be added to the configuration session\'s PKI subtree. - -Certificate Authority (CA): - -``` none -vyos@vyos# run generate pki ca install ca-1 -Enter private key type: [rsa, dsa, ec] (Default: rsa) -Enter private key bits: (Default: 2048) -Enter country code: (Default: GB) -Enter state: (Default: Some-State) -Enter locality: (Default: Some-City) -Enter organization name: (Default: VyOS) -Enter common name: (Default: vyos.io) ca-1 -Enter how many days certificate will be valid: (Default: 1825) -Note: If you plan to use the generated key on this router, do not encrypt the private key. -Do you want to encrypt the private key with a passphrase? [y/N] -2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. -[edit] -vyos@vyos# compare -[pki] -+ ca ca-1 { -+ certificate "MIIDlzCCAn+gAwIBAgIUQW7AtPu0Qzp7VzT0TyYx83/ME8swDQYJKoZIhvcNAQELBQAwVDELMAkGA1UEBhMCR0IxEzARBgNVBAgMClNvbWUtU3RhdGUxEjAQBgNVBAcMCVNvbWUtQ2l0eTENMAsGA1UECgwEVnlPUzENMAsGA1UEAwwEY2EtMTAeFw0yNTA2MTExMTIyMjJaFw0zMDA2MTAxMTIyMjJaMFQxCzAJBgNVBAYTAkdCMRMwEQYDVQQIDApTb21lLVN0YXRlMRIwEAYDVQQHDAlTb21lLUNpdHkxDTALBgNVBAoMBFZ5T1MxDTALBgNVBAMMBGNhLTEwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDi+v6i241T9ABxq1ngjWxDQITkqjV0nq2Jb3HSSuQpXRCu7DWdQZlbvnMHnkV/WTL0RNgkhS4iV/WYhE+bLihwiZ0GTeQnUd1QJSkusFROX46w6kKXYUR5IQtcBC+vdky8PESynPd+DXsJn5X9JTWqDeviUAQz/ZjDzWk+71MBCqa+Zps1zpIjK0ywn7pR/HnDrxJOQXlBMNgvbv8U3IAZ2jJp0jTB8TnuDtWSA+XZejMm/EN/AWUQyliX6OJFSCIhBL2BZ9lmVms4/HkRpbd50k3vvCoz+lAOEE6VsH0fEdLC3lZ+CtXZ7kjp2wdWWuSs5ggIJYZZkixsCisbtEmbAgMBAAGjYTBfMA8GA1UdEwEB/wQFMAMBAf8wDgYDVR0PAQH/BAQDAgGGMB0GA1UdJQQWMBQGCCsGAQUFBwMCBggrBgEFBQcDATAdBgNVHQ4EFgQUAG9lvr7AzJ/y4vY/XlWxXru+6m0wDQYJKoZIhvcNAQELBQADggEBAKsu4eZa8Fha9aKfuKqlGQHPpEFfVDaVJmebw0uMw+b5Y8EpBxzZrgbqbk3Mty8pBjNa9jkZzph04gHN4pR6kg3iQlUKGxZUfsB9ZUjKhkgNdUI9zq1323MKEvuIuYdt61DCfBHwY6Xax5Ge+BahR2bXdPaQH452/+xMTqkukkpLbioTeIDg6FCU2HYPY5emDF5DDZAZWXtTqi0zdT3Y6FqiTvs5VuWwXCcp+HM+Lwe1/VVJhwi4CHTq0CKWnQIH5blYjmyxzRBlrlZm4ntWlL5Mtepa1A3DJirY4kw/SqMAAh/Q9lh41JzBc8epf+OdnOzK55YmtmctGO2o+NBCFi0=" -+ private { -+ key "MIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQDi+v6i241T9ABxq1ngjWxDQITkqjV0nq2Jb3HSSuQpXRCu7DWdQZlbvnMHnkV/WTL0RNgkhS4iV/WYhE+bLihwiZ0GTeQnUd1QJSkusFROX46w6kKXYUR5IQtcBC+vdky8PESynPd+DXsJn5X9JTWqDeviUAQz/ZjDzWk+71MBCqa+Zps1zpIjK0ywn7pR/HnDrxJOQXlBMNgvbv8U3IAZ2jJp0jTB8TnuDtWSA+XZejMm/EN/AWUQyliX6OJFSCIhBL2BZ9lmVms4/HkRpbd50k3vvCoz+lAOEE6VsH0fEdLC3lZ+CtXZ7kjp2wdWWuSs5ggIJYZZkixsCisbtEmbAgMBAAECggEAZdykF6wV8Z4n8NsoG4j8E/ZJbWEhWjO3x1y3JNutJw735LhmmysMSsreToXtxGfgYRTgNwt5l7oHoqmGHCsLxO1NBb5A7JBllIkIwUYqn31syOJofg0NsJpuwZ2zVLfvWe5mGg4tV2lvVPNEWXWwbp+Ow2KLcFWXkA+H8tFuW6F2mH3ntYlIi/WiCNjsEotNx8Kk7OVwt43DbkN/rbF5lxquuLedaSspOHuhIAOfZB5ZySfqohQalSAaguVD66rGPMrerZ2Vc7B1iJ6Mn/KZrSaQeHwyWrwDDHdzVwG9waydevtGTVO0dvH4etWnRypDx8p1FPJJKD4XVcsl3rR6oQKBgQD497Ep2RJcbNnKVj+kNXGriSGmyRSp6CL61KotepzgucK0RtGMeFJge56/otMHMAxIOcDMX6vRn2MB2pqVqwqUBQy6JfLrSemdpIjMN9xlX6Dw3BWP39SdewZ896/Eo0Q1ythMj1ORp+u3PqOlSa14Cy9aPwDWmNy2deD68YDnsQKBgQDpZE/T84BMQ0FzL6NRijZRzR6Dc775hRfmmSTYI0KqpG0gXNSc5UgrWSLN5H7fnx36mT01P7UkgXCInV0AlJOfkt4a8QTqM1Fh/rZbLLWpQE55S6Fs28GDiFYl2kvZT/TtxhA/E0POf/YXl/8KITS7ZVAZxE8rxBe1hVUfDbnlCwKBgQDeWUguGaGeTdCMNk8MNnbYPdaCAB+mRp3G6ls51sF4qi5Lltva2jKn3H/AoohZaP3vGzUm0WLACdsAct2QQXtnCsN9FBtJK2+qzKEn0dPR7X/s3IGdRse6BX+b6BFgSnfGmuxmI7L86L1JoHXCTnTQOx0FOjNjdI3ZnplZRIpdYQKBgFJacASU9l9yl+SiGZnLEDG7FBpEPE3lVbKrtSGDB6IY1NzHhMo76URKdop6Jv6XMcfcTIm+ihdwiRnblRaAVrrG4xJUm2xcYUoXy5bOZudq5oXMVxCHVngoImXG6l6q5P0Fl3P6Q0HZSye2HWsgnm/FZwdAisMhtU/61TdY65BTAoGBAM4jKeImiXta5lz1RgNiW/TPhft3UbOLj3TbzchNCNAamqCv4Tmh9YKB2d/mz2hNxbnAGe2cYn4iRYKcjJLMZ0UfBL2WxlrgQYQPPGzSD0fH1pLIXPohpBZpsGqNR3Nc8Jd+Uw3IiIJ2oxPCOPTOJsklNB0Xf1AlUUagB16bhhZZ" -+ } -+ } - -[edit] -vyos@vyos# commit -``` - -Server certificate: - -``` none -vyos@vyos# run generate pki certificate sign ca-1 install srv-1 -Do you already have a certificate request? [y/N] N -Enter private key type: [rsa, dsa, ec] (Default: rsa) -Enter private key bits: (Default: 2048) -Enter country code: (Default: GB) -Enter state: (Default: Some-State) -Enter locality: (Default: Some-City) -Enter organization name: (Default: VyOS) -Enter common name: (Default: vyos.io) srv-1 -Do you want to configure Subject Alternative Names? [y/N] -Enter how many days certificate will be valid: (Default: 365) -Enter certificate type: (client, server) (Default: server) server -Note: If you plan to use the generated key on this router, do not encrypt the private key. -Do you want to encrypt the private key with a passphrase? [y/N] -2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. -[edit] -vyos@vyos# compare -[pki certificate] -+ srv-1 { -+ certificate "MIIDrDCCApSgAwIBAgIULpu+qZjfG01kUI58XNmqXbQC3qQwDQYJKoZIhvcNAQELBQAwVDELMAkGA1UEBhMCR0IxEzARBgNVBAgMClNvbWUtU3RhdGUxEjAQBgNVBAcMCVNvbWUtQ2l0eTENMAsGA1UECgwEVnlPUzENMAsGA1UEAwwEY2EtMTAeFw0yNTA2MTExMTMxMDJaFw0yNjA2MTExMTMxMDJaMFUxCzAJBgNVBAYTAkdCMRMwEQYDVQQIDApTb21lLVN0YXRlMRIwEAYDVQQHDAlTb21lLUNpdHkxDTALBgNVBAoMBFZ5T1MxDjAMBgNVBAMMBXNydi0xMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAysTrMfVH63aVidJT7bIf+zLwkLse07nGsv4aliGEbufr239RBHV4Jn8LbQ+nB/8mhYGjNY4OnZ7NYz3FU/iglo8qFtaZ26mWtPWpv2xW1F8JAEK7l5BAg42cBucxiIZFeRm+jkE6VN1bcNU0utnn3sbCwZMyH6pS9k08G1qrrFLA7ZFhv5AmgJcODmO8sigSAu7rRS/6O3eO6ICnVjvIfHLb+9DKKUEffHzFV8RrkqVCGmgisz9fF+j1Rvg9s+ylNc2lZJTbb1XnzixvSRro4t9I3uIWdpJ0iOu09YiTXGQgH9ER6V3rFiX00RdSiSXf+MJCV64hC1msg+8V3Nrw9QIDAQABo3UwczAMBgNVHRMBAf8EAjAAMA4GA1UdDwEB/wQEAwIHgDATBgNVHSUEDDAKBggrBgEFBQcDATAdBgNVHQ4EFgQUzH0h4vBxma89HF9rUQ+DW052c5swHwYDVR0jBBgwFoAUAG9lvr7AzJ/y4vY/XlWxXru+6m0wDQYJKoZIhvcNAQELBQADggEBAI/Cyd0y7AJ7wY3yRssCud2iJAl9/ZjgxzXOUo6ibawYIYOnSf9tS3eD4CIH4BgppDXoJZ/qEA4WvIsLx3yvnyOxiqyk3TQmKIZ27VJH+yQkgzPeiKrHn1pCXBKEb1/jlT8Ozu4Lmn/oFwDH6nk8toxI8DM+qsTxqUFlTA3ea9yaRtxeNPMWJdaxZSUYGVSZL0wVKw5ZuQ1Gn7vGVApWlYDKYbMozCuZUG1q8wMzFBRa7x0anvh5hM4bksLz+Y1ujCS8f8b4Xtb8KIdFrZtTvtl97crv62bN05VueAcbwtYbIBNWNoT/CvmqV7k3uPg95GYSNddFqEMbQHoyd8hdDCo=" -+ private { -+ key "MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQDKxOsx9UfrdpWJ0lPtsh/7MvCQux7Tucay/hqWIYRu5+vbf1EEdXgmfwttD6cH/yaFgaM1jg6dns1jPcVT+KCWjyoW1pnbqZa09am/bFbUXwkAQruXkECDjZwG5zGIhkV5Gb6OQTpU3Vtw1TS62efexsLBkzIfqlL2TTwbWqusUsDtkWG/kCaAlw4OY7yyKBIC7utFL/o7d47ogKdWO8h8ctv70MopQR98fMVXxGuSpUIaaCKzP18X6PVG+D2z7KU1zaVklNtvVefOLG9JGuji30je4hZ2knSI67T1iJNcZCAf0RHpXesWJfTRF1KJJd/4wkJXriELWayD7xXc2vD1AgMBAAECggEACsUk3PVzSX11+ekTDigM7NHK11UpEQPoGu/GR70mBKIK9BCyI/N9W0YaPEO9kn4p9KNrINgXzKV3sVLBnXEyTmzyRl5Fs9YxLBF0X7eIcSVPHBVvU2CVHKez5uX2ypKfNAx7A6FRUNqlFbwtXdNfLoUOKSwBWI86ctytWaKaRb/TTSGQkaP/z/cwIsXOLfG9m6iFkw98ShUzalrUWNo/4fJKlO1+DvXVYE9sv9rjD8J7DtAbr5KykQ5n0AAlZTCWQ7jwMybSnjjY9ypZUms0l17raJrfhrdbWayc6xMDvtrmNIDebkF+J7cHU06aEV+yQXV/7yjyZgUSM2ANcHMdzQKBgQDmTi5tUeaj1JUSl9lAP/XUzcElw2tcU1B8qpX69J4ofjTNgj5okLWQZVIy1UyAfLOI3LJbHTBUtSvedhH0VaMulq99NXs5qnbPGG3//RBAc0wKhJknB5Qv0D3FxMI14kMO6jzPly+aIGEk4dTtHvZuHbbVHbKSZ5MMouLyT+SS7wKBgQDhZETARZ0MazeWRaPJwdkjlfNcqqcsnDicdcppCkcDCjeLxkVPZc8ej37rshOvw2Pf1D0PddGyOhJoWCWA8QE2LQoDHLaDnQ0L6aQ3yjN5Gxx9RCDFi3Zuat/mPcv3tFO7uUmeYvRC5fGYrghq29NADmUefOopAc06Izd4A3iqWwKBgQC1uPrpR7a1jwgRo7/I8q8HO1MseQY903+u3ut5GYuyZ+NCRYL4/zZEua4ibivvNnZzh7E0M9PvAwWag4+nO+uG11+hbJHO7rLQtnYVh5lLQa6+neI66cAD+kzDwH1+BwriufFB3Amzk9kTQR7B+6x3NvsNLmG5JADj96Mbj+7MAQKBgFIevEXplyzdK6WevexWqoyip8aNjtdcG+w1pofa7MCYymAs3zfseihCVBYADdguModsxsqJPNvY+Lf31cJDDRP2GP3FSmJtqEE84U5KZ7KqRBkH54DSLVZRrj4vKc+YbiGpgr8ogqKVMQ9V6U81xKREGmefT5mdRG74Qc+CREadAoGAFtdsH5js1yFEeGFad4BZJ69grEavD3pNCfIe9oIPtXvvFdzxd+QbKgqFf3JMJp/HYi8A0iv/i4mzf00KXzF4JU7bIJYrUVlk/w8x77gzDRIphsPqpMBJkTI0jisQHZKWNEe7IbmM/dWW2S4jvCkrhB7F5Szf72Q+j/lPbfx2g/8=" -+ } -+ } - -[edit] -vyos@vyos# commit -``` - -Diffie-Hellman key: - -``` none -vyos@vyos# run generate pki dh install dh-1 -Enter DH parameters key size: (Default: 2048) -Generating parameters... -1 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. -[edit] -vyos@vyos# compare -[pki] -+ dh dh-1 { -+ parameters "MIIBCAKCAQEAp25kxwZeLZ7wcbRii5E5RD4uWCUOBxarzKEE0msa84omh5nZ9dv/4bfJw4gIXlA2+sGc2lLV/jajZminMryiSwJdisyVuUdOB7sJWZwrzHBAY0qFbNyaRMVJBar2xVm+XcKd3A2eNTEgn10G7rPPvf6CJ5isUKFaKT8ymUv+mI0upLneYdGs8/yS3sAojzeulCf49fa5SiaGCcZZkdOI3Nby1u/ZG4okqJ2wE2c2hRVLs1k5qrrono0OF4Dh0B91ihnywRfp1xPYeqpiln+OPh+PPgTuBxkz4VxwRDoQ+NhVr/LOCb3vbhnyFisxI0w4r3109cA3QiDmo1L14aKl1wIBAg==" -+ } - -[edit] -vyos@vyos# commit -``` - -Client certificate: - -``` none -vyos@vyos:~$ generate pki certificate sign ca-1 install client1 -Do you already have a certificate request? [y/N] N -Enter private key type: [rsa, dsa, ec] (Default: rsa) -Enter private key bits: (Default: 2048) -Enter country code: (Default: GB) -Enter state: (Default: Some-State) -Enter locality: (Default: Some-City) -Enter organization name: (Default: VyOS) -Enter common name: (Default: vyos.io) client1 -Do you want to configure Subject Alternative Names? [y/N] -Enter how many days certificate will be valid: (Default: 365) -Enter certificate type: (client, server) (Default: server) client -Note: If you plan to use the generated key on this router, do not encrypt the private key. -Do you want to encrypt the private key with a passphrase? [y/N] -You are not in configure mode, commands to install manually from configure mode: -set pki certificate client1 certificate 'MIIDrjCCApagAwIBAgIUPvtffeYTdoOiHxu++wdrjHwwVX4wDQYJKoZIhvcNAQELBQAwVDELMAkGA1UEBhMCR0IxEzARBgNVBAgMClNvbWUtU3RhdGUxEjAQBgNVBAcMCVNvbWUtQ2l0eTENMAsGA1UECgwEVnlPUzENMAsGA1UEAwwEY2EtMTAeFw0yNTA2MTExMTQxMDlaFw0yNjA2MTExMTQxMDlaMFcxCzAJBgNVBAYTAkdCMRMwEQYDVQQIDApTb21lLVN0YXRlMRIwEAYDVQQHDAlTb21lLUNpdHkxDTALBgNVBAoMBFZ5T1MxEDAOBgNVBAMMB2NsaWVudDEwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQC9H6E6gm0PfXO1n/WoA9xlg89/bnScLmfztVDn1uyNn8epE6zAi2GWBhtj4ixLllIwLdkJ7L2mF3yUZtA1Q0oYbGIqTbnaZ37JydCygVGnlLT7UX9zfRfS3KebCIvIte7OyCmnUfVfFzdIsp+4LI3S2wX/9Vyn4UBAR8QQNbezRB3XPMk9gzULnuLhmEDP6GVcPq7RzGXoXUMqsCxfEOJBjej0y4ANKH07HGVVrfVRiY+zlGkM4TFjVuZKnEA0BO6dhOA0E+7gsIXsC06UzzatkjsyWHpb2/DOECIifBoYej9DITu8VxyyZmgaINHEn2gGb0LRHO7rvQapc+XZ2z9DAgMBAAGjdTBzMAwGA1UdEwEB/wQCMAAwDgYDVR0PAQH/BAQDAgeAMBMGA1UdJQQMMAoGCCsGAQUFBwMCMB0GA1UdDgQWBBQnUyqEzG+AqZzsdSud5MDqsOxiXTAfBgNVHSMEGDAWgBQAb2W+vsDMn/Li9j9eVbFeu77qbTANBgkqhkiG9w0BAQsFAAOCAQEAplItvZpoX/joG3QREu9tHVKwDTmXB2lwUM5G8iKPgd6D6oOILZMe2KuvWt12dcdEzUCGfJwJJ8M8R2WD0OmcLdFqvM/8UM1hYzUP2BCnFCLtElVD+b4wMlQNpdHqNbdckw8J4MLQlhUgu9rZAZ0XjWCprr+U50bX++vYRw7Un3Ds6ETEvjflm5WAPb2e0V1hhISPl8K+VXO7RAwxy0DHcDuR+YaD+hnNgMsJV3/QwA17Iy8x86RpOgqmesbt0U7e9Rmo81aVgiy/V4OCV7u6bPX03fmZNS8UwwJuRUlxkjO+epHNYB2cnOcjSkUxaIJ9Hv3tMWHQEtbVZsNYSOZozw==' -set pki certificate client1 private key 'MIIEvAIBADANBgkqhkiG9w0BAQEFAASCBKYwggSiAgEAAoIBAQC9H6E6gm0PfXO1n/WoA9xlg89/bnScLmfztVDn1uyNn8epE6zAi2GWBhtj4ixLllIwLdkJ7L2mF3yUZtA1Q0oYbGIqTbnaZ37JydCygVGnlLT7UX9zfRfS3KebCIvIte7OyCmnUfVfFzdIsp+4LI3S2wX/9Vyn4UBAR8QQNbezRB3XPMk9gzULnuLhmEDP6GVcPq7RzGXoXUMqsCxfEOJBjej0y4ANKH07HGVVrfVRiY+zlGkM4TFjVuZKnEA0BO6dhOA0E+7gsIXsC06UzzatkjsyWHpb2/DOECIifBoYej9DITu8VxyyZmgaINHEn2gGb0LRHO7rvQapc+XZ2z9DAgMBAAECggEAPS/Fhtt5k2BgFivZW3FcVc+OS0keGwV8hkFsGoXTZIKEIzSFWIn/mX0CUY90C0Rn9MRwiqB4PwssOAsHY6QQjdRK8irRbVK8l2ZeydHC7DfVUdXtKR0YnxTaePML3nTV/TqPF14Rx6EINtHrkLeBbu2DhGsKfhoHIoTVbvUiKLHa2TkGJOkhvjsyMSPKzUXa1AzLmu+UBIhRYpEPHj0SQUUJJnKgIb7mTR2fhJScHcKwsrPq6S8OpChvsYZ6zatgrTFz9tuhD4IjL7NBiYP45BwGaLIaQjph8yAJwwHWoOP+TTj5WYflkW6Uu8F9gC0ve6dPGPNEi2TUdirvAe4LYQKBgQD0UfAPm6tQg8pdkvfMBvYc21fk8zqmgcA4OtvDi60aXuv5jI5+faISvOG2JLuFhKIDOb5ZerzGvkN+LvWgzr9H7YdGZNNtwKgpS/MGqcuuHncTxWBAwYgKhf26a/tqFZRNurJ6GowxDiAcQEc1mWnmdngRa+dvvCwNbXvGVqfVEQKBgQDGKi447TqD76QfvRPn/fRSjM+QE1duk+XorEJ0HHIha5HV9kCrZdV/olGRjDLwPJO6JW7iE2FUsS9SsIrccFE/9P2ZUqfYP2wL5vNO5kAmoLLUl0gwqg1WnBTPJfXeKReTj2uGmOdEuuMPXpL/49hDuPViiE2Q4MGe2Z+oEYN/EwKBgHfQMuTEl2e9qaDn8OM6SrluC5V4fjunh6dLnfgwaCx1fk1702lOnQuJWzsiml9o4raoO6PP4AGqzphz2PsKSJ2ya1NnIJRDFXRjDYQoAn2Z7RViBsja36chfINObxXgDUFtHBdrK3LnFXIlR4aOfHOLh2grvWx7IDNZjIiAeH+xAoGAJlmFZnjqiRv4bDgAQTZRcSRVCvHjSsAOj0++8I+MutEBgSHN9B2aCsBT/tHeDcX7ZNvXsKLFhElh+iO2S+DkqHb2GRT47I2hkFAaqBtBMPiKgz/ftaNDP46nLEuRYHQdXu4zhfHTV+a/CHtqAWGLuddyjaYJNM96SQ6eqjzxcMcCgYAzdxOF2e27hIgo2ttjsROMGqW0/0r/HsKGKPnao7xHQNCAswTnBT+QGugPCe0NXjuxbySP7V1GeWMWF+WV5khtteWerT1/ELAC48NSDpaMxVa4GP8Q/0w6+ZyJty3UGbCYQzZZue81dU+42LUIaVJ4NAc2tYj3jD780udasawS6w==' -``` - -Manually copy the CA, client certificate, and Diffie-Hellman key to the client device, then commit them before configuring the OpenVPN interface. - -For more options, refer to {ref}`configuration/pki/index:pki`. - -## Set up server-client OpenVPN - -The following example demonstrates the most complicated scenario: each client acts as a router with its own subnet (e.g., an HQ and multiple branch offices). Simpler setups are subsets of it. - -In this scenario, the 10.23.1.0/24 network is used for client tunnel endpoints, and all client subnets belong to 10.23.0.0/20. Each client needs access to the 192.168.0.0/16 network. - -Server configuration: - -``` none -set interfaces openvpn vtun10 encryption data-ciphers 'aes256' -set interfaces openvpn vtun10 hash 'sha512' -set interfaces openvpn vtun10 local-host '172.18.201.10' -set interfaces openvpn vtun10 local-port '1194' -set interfaces openvpn vtun10 mode 'server' -set interfaces openvpn vtun10 persistent-tunnel -set interfaces openvpn vtun10 protocol 'udp' -set interfaces openvpn vtun10 server client client1 ip '10.23.1.10' -set interfaces openvpn vtun10 server client client1 subnet '10.23.2.0/25' -set interfaces openvpn vtun10 server domain-name 'vyos.net' -set interfaces openvpn vtun10 server max-connections '250' -set interfaces openvpn vtun10 server name-server '172.16.254.30' -set interfaces openvpn vtun10 server subnet '10.23.1.0/24' -set interfaces openvpn vtun10 server topology 'subnet' -set interfaces openvpn vtun10 tls ca-certificate ca-1 -set interfaces openvpn vtun10 tls certificate srv-1 -set interfaces openvpn vtun10 tls dh-params dh-1 -``` - -The configuration above uses the default 1194/UDP port, 256-bit AES encryption, SHA-512 for HMAC authentication, and the persistent-tunnel option. Persistent-tunnel is recommended as it keeps the TUN/TAP device active during connection resets or daemon reloads. Clients are identified by the CN attribute in their SSL certificates. - -To grant clients access to a specific network behind the router, use the push-route option to automatically install the appropriate route on each client. - -``` none -set interfaces openvpn vtun10 server push-route 192.168.0.0/16 -``` - -OpenVPN does not automatically create kernel routes for client subnets when clients connect; it only uses client-subnet association internally. Therefore, you must manually create a route to the 10.23.0.0/20 network: - -``` none -set protocols static route 10.23.0.0/20 interface vtun10 -``` - - -## Set up OpenVPN client - -VyOS can operate not only as an OpenVPN site-to-site peer or a server for multiple clients, but also as an OpenVPN client. Any VyOS OpenVPN interface can be configured to connect to another VyOS or third-party OpenVPN server. - -Client configuration: - -``` none -set interfaces openvpn vtun10 encryption data-ciphers 'aes256' -set interfaces openvpn vtun10 hash 'sha512' -set interfaces openvpn vtun10 mode 'client' -set interfaces openvpn vtun10 persistent-tunnel -set interfaces openvpn vtun10 protocol 'udp' -set interfaces openvpn vtun10 remote-host '172.18.201.10' -set interfaces openvpn vtun10 remote-port '1194' -set interfaces openvpn vtun10 tls ca-certificate ca-1 -set interfaces openvpn vtun10 tls certificate client1 -``` - - -## Verification - -Check the tunnel status: - -``` none -vyos@vyos:~$ show openvpn server - -OpenVPN status on vtun10 - -Client CN Remote Host Tunnel IP Local Host TX bytes RX bytes Connected Since ------------ ------------------ ----------- ---------------- ---------- ---------- ------------------- -client1 172.16.12.54:33166 10.23.1.10 172.18.201.10:1194 3.4 KB 3.4 KB 2024-06-11 12:07:25 -``` - - -### Server bridge - -In Ethernet bridging configurations, an OpenVPN interface operating in server mode with the device type set to TAP can be added to a bridge. By encapsulating entire Ethernet frames (up to 1514 bytes) rather than just IP packets (up to 1500 bytes), this setup enables clients to transmit Layer 2 frames through the OpenVPN tunnel. - -The following is a basic configuration example: - -Server side: - -``` none -set interfaces bridge br10 member interface eth1.10 -set interfaces bridge br10 member interface vtun10 -set interfaces openvpn vtun10 device-type 'tap' -set interfaces openvpn vtun10 encryption data-ciphers 'aes192' -set interfaces openvpn vtun10 hash 'sha256' -set interfaces openvpn vtun10 local-host '172.18.201.10' -set interfaces openvpn vtun10 local-port '1194' -set interfaces openvpn vtun10 mode 'server' -set interfaces openvpn vtun10 server bridge gateway '10.10.0.1' -set interfaces openvpn vtun10 server bridge start '10.10.0.100' -set interfaces openvpn vtun10 server bridge stop '10.10.0.200' -set interfaces openvpn vtun10 server bridge subnet-mask '255.255.255.0' -set interfaces openvpn vtun10 server topology 'subnet' -set interfaces openvpn vtun10 tls ca-certificate 'ca-1' -set interfaces openvpn vtun10 tls certificate 'srv-1' -set interfaces openvpn vtun10 tls dh-params 'dh-1' -``` - -Client side: - -``` none -set interfaces openvpn vtun10 device-type 'tap' -set interfaces openvpn vtun10 encryption data-ciphers 'aes192' -set interfaces openvpn vtun10 hash 'sha256' -set interfaces openvpn vtun10 mode 'client' -set interfaces openvpn vtun10 protocol 'udp' -set interfaces openvpn vtun10 remote-host '172.18.201.10' -set interfaces openvpn vtun10 remote-port '1194' -set interfaces openvpn vtun10 tls ca-certificate 'ca-1' -set interfaces openvpn vtun10 tls certificate 'client-1' -``` - - -### Server LDAP authentication - -## LDAP - -Enterprise installations usually include a directory service to centralize employee password management. VyOS and OpenVPN support using LDAP and Active Directory as a single user backend. - -Authentication is performed by the `openvpn-auth-ldap.so` plugin, included with every VyOS installation. To use it, you must create a dedicated configuration file. -**Best practice:** Store the configuration file in the `/config` directory to ensure it is preserved after image updates. - -``` none -set interfaces openvpn vtun0 openvpn-option "--plugin /usr/lib/openvpn/openvpn-auth-ldap.so /config/auth/ldap-auth.config" -``` - -A sample configuration file is shown below: - -``` none - -# LDAP server URL -URL ldap://ldap.example.com -# Bind DN (If your LDAP server doesn't support anonymous binds) -BindDN cn=LDAPUser,dc=example,dc=com -# Bind Password password -Password S3cr3t -# Network timeout (in seconds) -Timeout 15 - - - -# Base DN -BaseDN "ou=people,dc=example,dc=com" -# User Search Filter -SearchFilter "(&(uid=%u)(objectClass=shadowAccount))" -# Require Group Membership - allow all users -RequireGroup false - -``` - - -### Active Directory - -A sample configuration file is shown below: - -``` none - - # LDAP server URL - URL ldap://dc01.example.com - # Bind DN (If your LDAP server doesn’t support anonymous binds) - BindDN CN=LDAPUser,DC=example,DC=com - # Bind Password - Password mysecretpassword - # Network timeout (in seconds) - Timeout 15 - # Enable Start TLS - TLSEnable no - # Follow LDAP Referrals (anonymously) - FollowReferrals no - - - - # Base DN - BaseDN "DC=example,DC=com" - # User Search Filter, user must be a member of the VPN AD group - SearchFilter "(&(sAMAccountName=%u)(memberOf=CN=VPN,OU=Groups,DC=example,DC=com))" - # Require Group Membership - RequireGroup false # already handled by SearchFilter - - BaseDN "OU=Groups,DC=example,DC=com" - SearchFilter "(|(cn=VPN))" - MemberAttribute memberOf - - -``` - -If you only want to check that the user account is enabled and can authenticate (against the primary group), the following snippet is sufficient: - -``` none - - URL ldap://dc01.example.com - BindDN CN=SA_OPENVPN,OU=ServiceAccounts,DC=example,DC=com - Password ThisIsTopSecret - Timeout 15 - TLSEnable no - FollowReferrals no - - - - BaseDN "DC=example,DC=com" - SearchFilter "sAMAccountName=%u" - RequireGroup false - -``` - -A complete example of an LDAP authentication configuration for OpenVPN is shown below: - -``` none -vyos@vyos# show interfaces openvpn - openvpn vtun0 { - mode server - openvpn-option "--tun-mtu 1500 --fragment 1300 --mssfix" - openvpn-option "--plugin /usr/lib/openvpn/openvpn-auth-ldap.so /config/auth/ldap-auth.config" - openvpn-option "--push redirect-gateway" - openvpn-option --duplicate-cn - openvpn-option "--verify-client-cert none" - openvpn-option --comp-lzo - openvpn-option --persist-key - openvpn-option --persist-tun - server { - domain-name example.com - max-connections 5 - name-server 203.0.113.0.10 - name-server 198.51.100.3 - subnet 172.18.100.128/29 - } - tls { - ca-certificate ca.crt - certificate server.crt - dh-params dh1024.pem - } - } -``` - -For a detailed example, refer to {doc}`OpenVPN with LDAP`. - -### Multi-factor authentication - -VyOS supports multi-factor authentication (MFA) or two-factor authentication using Time-based One-Time Passwords (TOTP). It is compatible with Google Authenticator and other software tokens. - -## Server side - -``` none -set interfaces openvpn vtun20 encryption cipher 'aes256' -set interfaces openvpn vtun20 hash 'sha512' -set interfaces openvpn vtun20 mode 'server' -set interfaces openvpn vtun20 persistent-tunnel -set interfaces openvpn vtun20 server client user1 -set interfaces openvpn vtun20 server mfa totp challenge 'disable' -set interfaces openvpn vtun20 server subnet '10.10.2.0/24' -set interfaces openvpn vtun20 server topology 'subnet' -set interfaces openvpn vtun20 tls ca-certificate 'openvpn_vtun20' -set interfaces openvpn vtun20 tls certificate 'openvpn_vtun20' -set interfaces openvpn vtun20 tls dh-params 'dh-pem' -``` - -A TOTP secret is created for each client in the OpenVPN server configuration. To display authentication information, use the following command: `show interfaces openvpn vtun20 user user1 mfa qrcode`. - -Example: - -``` none -vyos@vyos:~$ sh interfaces openvpn vtun20 user user1 mfa qrcode -█████████████████████████████████████ -█████████████████████████████████████ -████ ▄▄▄▄▄ █▀▄▀ ▀▀▄▀ ▀▀▄ █ ▄▄▄▄▄ ████ -████ █ █ █▀▀▄ █▀▀▀█▀██ █ █ █ ████ -████ █▄▄▄█ █▀█ ▄ █▀▀ █▄▄▄█ █▄▄▄█ ████ -████▄▄▄▄▄▄▄█▄█ █ █ ▀ █▄▀▄█▄▄▄▄▄▄▄████ -████▄▄ ▄ █▄▄ ▄▀▄█▄ ▄▀▄█ ▄▄▀ ▀▄█ ▀████ -████ ▀██▄▄▄█▄ ██ █▄▄▄▄ █▄▀█ █ █▀█████ -████ ▄█▀▀▄▄ ▄█▀ ▀▄ ▄▄▀▄█▀▀▀ ▄▄▀████ -████▄█ ▀▄▄▄▀ ▀ ▄█ ▄ █▄█▀ █▀ █▀█████ -████▀█▀ ▀ ▄█▀▄▀▀█▄██▄█▀▀ ▀ ▀ ▄█▀████ -████ ██▄▄▀▄▄█ ██ ▀█ ▄█ ▀▄█ █▀██▀████ -████▄███▄█▄█ ▀█▄ ██▄▄▄█▀ ▄▄▄ █ ▀ ████ -████ ▄▄▄▄▄ █▄█▀▄ ▀▄ ▀█▀ █▄█ ██▀█████ -████ █ █ █ ▄█▀█▀▀▄ ▄▀▀▄▄▄▄▄▄ ████ -████ █▄▄▄█ █ ▄ ▀ █▄▄▄██▄▀█▄▀▄█▄ █████ -████▄▄▄▄▄▄▄█▄██▄█▄▄▄▄▄█▄█▄█▄██▄██████ -█████████████████████████████████████ -█████████████████████████████████████ -``` - -Scan the QR code to add the user account to Google Authenticator. On the client side, use the generated OTP as the password. - -### Authentication with username/password - -An OpenVPN server can securely obtain a username and password from a connecting client and use this information for authentication. - -First, configure the server to use an authentication plugin or script. The server calls this plugin every time a client tries to connect, passing it the client\'s credentials. - -In the following example, the `--auth-user-pass-verify` directive is used with the via-env method and a specified script path to validate the client\'s username and password. - -## Server configuration - -``` none -set interfaces openvpn vtun10 local-port '1194' -set interfaces openvpn vtun10 mode 'server' -set interfaces openvpn vtun10 openvpn-option '--auth-user-pass-verify /config/auth/check_user.sh via-env' -set interfaces openvpn vtun10 openvpn-option '--script-security 3' -set interfaces openvpn vtun10 persistent-tunnel -set interfaces openvpn vtun10 protocol 'udp' -set interfaces openvpn vtun10 server client client-1 ip '10.10.10.55' -set interfaces openvpn vtun10 server push-route 192.0.2.0/24 -set interfaces openvpn vtun10 server subnet '10.10.10.0/24' -set interfaces openvpn vtun10 server topology 'subnet' -set interfaces openvpn vtun10 tls ca-certificate 'ca-1' -set interfaces openvpn vtun10 tls certificate 'srv-1' -set interfaces openvpn vtun10 tls dh-params 'dh-1' -``` - -The /config/auth/check_user.sh example includes two test users: - -``` none -#!/bin/bash -USERNAME="$username" -PASSWORD="$password" - -# Replace this with real user checking logic or use getent -if [[ "$USERNAME" == "client1" && "$PASSWORD" == "pass123" ]]; then - exit 0 -elif [[ "$USERNAME" == "peter" && "$PASSWORD" == "qwerty" ]]; then - exit 0 -else - exit 1 -fi -``` - - -## Client configuration - -Storing the client certificate locally lets you generate the OpenVPN client configuration file. Use the following command: - -``` none -vyos@vyos:~$ generate openvpn client-config interface vtun10 ca ca-1 certificate client1 -``` - -Copy the output and save it as a .ovpn file. Add the `auth-user-pass` directive to the file. This instructs the OpenVPN client to prompt the user for a username and password, which are then sent to the server over the TLS channel. You can now import this file into any OpenVPN client application. - -``` none -client -dev tun -proto udp -remote 192.168.77.10 1194 - -remote-cert-tls server -proto udp -dev tun -dev-type tun -persist-key -persist-tun -verb 3 -auth-user-pass - - - ------BEGIN CERTIFICATE----- -MIIDlzCCAn+gAwIBAgIUQW7AtPu0Qzp7VzT0TyYx83/ME8swDQYJKoZIhvcNAQEL -BQAwVDELMAkGA1UEBhMCR0IxEzARBgNVBAgMClNvbWUtU3RhdGUxEjAQBgNVBAcM -CVNvbWUtQ2l0eTENMAsGA1UECgwEVnlPUzENMAsGA1UEAwwEY2EtMTAeFw0yNTA2 -MTExMTIyMjJaFw0zMDA2MTAxMTIyMjJaMFQxCzAJBgNVBAYTAkdCMRMwEQYDVQQI -DApTb21lLVN0YXRlMRIwEAYDVQQHDAlTb21lLUNpdHkxDTALBgNVBAoMBFZ5T1Mx -DTALBgNVBAMMBGNhLTEwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDi -+v6i241T9ABxq1ngjWxDQITkqjV0nq2Jb3HSSuQpXRCu7DWdQZlbvnMHnkV/WTL0 -RNgkhS4iV/WYhE+bLihwiZ0GTeQnUd1QJSkusFROX46w6kKXYUR5IQtcBC+vdky8 -PESynPd+DXsJn5X9JTWqDeviUAQz/ZjDzWk+71MBCqa+Zps1zpIjK0ywn7pR/HnD -rxJOQXlBMNgvbv8U3IAZ2jJp0jTB8TnuDtWSA+XZejMm/EN/AWUQyliX6OJFSCIh -BL2BZ9lmVms4/HkRpbd50k3vvCoz+lAOEE6VsH0fEdLC3lZ+CtXZ7kjp2wdWWuSs -5ggIJYZZkixsCisbtEmbAgMBAAGjYTBfMA8GA1UdEwEB/wQFMAMBAf8wDgYDVR0P -AQH/BAQDAgGGMB0GA1UdJQQWMBQGCCsGAQUFBwMCBggrBgEFBQcDATAdBgNVHQ4E -FgQUAG9lvr7AzJ/y4vY/XlWxXru+6m0wDQYJKoZIhvcNAQELBQADggEBAKsu4eZa -8Fha9aKfuKqlGQHPpEFfVDaVJmebw0uMw+b5Y8EpBxzZrgbqbk3Mty8pBjNa9jkZ -zph04gHN4pR6kg3iQlUKGxZUfsB9ZUjKhkgNdUI9zq1323MKEvuIuYdt61DCfBHw -Y6Xax5Ge+BahR2bXdPaQH452/+xMTqkukkpLbioTeIDg6FCU2HYPY5emDF5DDZAZ -WXtTqi0zdT3Y6FqiTvs5VuWwXCcp+HM+Lwe1/VVJhwi4CHTq0CKWnQIH5blYjmyx -zRBlrlZm4ntWlL5Mtepa1A3DJirY4kw/SqMAAh/Q9lh41JzBc8epf+OdnOzK55Ym -tmctGO2o+NBCFi0= ------END CERTIFICATE----- - - - - ------BEGIN CERTIFICATE----- -MIIDrjCCApagAwIBAgIUN6vPxDEW89cfbEFPa0tZlnsW1GkwDQYJKoZIhvcNAQEL -BQAwVDELMAkGA1UEBhMCR0IxEzARBgNVBAgMClNvbWUtU3RhdGUxEjAQBgNVBAcM -CVNvbWUtQ2l0eTENMAsGA1UECgwEVnlPUzENMAsGA1UEAwwEY2EtMTAeFw0yNTA2 -MTExMTQ0MjlaFw0yNjA2MTExMTQ0MjlaMFcxCzAJBgNVBAYTAkdCMRMwEQYDVQQI -DApTb21lLVN0YXRlMRIwEAYDVQQHDAlTb21lLUNpdHkxDTALBgNVBAoMBFZ5T1Mx -EDAOBgNVBAMMB2NsaWVudDEwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIB -AQCdOWq8vdO8CznGN83uAXCuN4PcdTJaRFEdJIEfqHjlcG0MZQuPIAlDbOU+IWmu -QBmeCj7SlbYtVYo1uQOMUaIrAvxLIQUaL1Y60oLVTF5eAPrGV+NSTQR5uMApcH9/ -RcZcW530pu/QpYinKTbGkEd54so6YRVPmYbIOPNUMbnZbccpinYi5t2dqubBb585 -A7L40043VtsVVbPjQq5V0HDursvqlaMqMRcffhR8H4B4ByU/EPRK4yTKm1hi19v3 -UtRHiq74CfGtJzYtplgrLJBON7TsbIi/fEux4q1yhbKA0S66L6e5DZldRxNZOXG6 -QjEL0RkYloMgkbv/2HLCu09hAgMBAAGjdTBzMAwGA1UdEwEB/wQCMAAwDgYDVR0P -AQH/BAQDAgeAMBMGA1UdJQQMMAoGCCsGAQUFBwMCMB0GA1UdDgQWBBQCkfdfq3hv -7UtqAxq/5VDRIdgJLTAfBgNVHSMEGDAWgBQAb2W+vsDMn/Li9j9eVbFeu77qbTAN -BgkqhkiG9w0BAQsFAAOCAQEAJ43+aDVRC+y2vsu6WRG2l6zYnLoIJZW4afdKMC1a -nhTWhj4AhAt8evhVbAxi/8qhQX3yXF2bUQKdS++8AVcvZFlSES32S5eBx83AwGLt -QkgvGx+QThKmoJwrelyuS2X0XX3P0WzohYI6HzSr6p9F8KhTvSW97E6SnldpdvEM -uG1C+61/Vys7WLmDBh1PZTGE03nRp3H4Q9ynyXEEf1MK3eZkzg5H3Evj66p82pD5 -8IauRfghMHJf3tOC+y0YIoXshF3lPq4nYso5Jc/HGCHlsboCODMCnY3CZsH7/O1n -/MI710KpzZTCLnv4Qtx9JpZxR7FTddl36OOuYUXU3Gcnsg== ------END CERTIFICATE----- - - - - ------BEGIN PRIVATE KEY----- -MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQCdOWq8vdO8CznG -N83uAXCuN4PcdTJaRFEdJIEfqHjlcG0MZQuPIAlDbOU+IWmuQBmeCj7SlbYtVYo1 -uQOMUaIrAvxLIQUaL1Y60oLVTF5eAPrGV+NSTQR5uMApcH9/RcZcW530pu/QpYin -KTbGkEd54so6YRVPmYbIOPNUMbnZbccpinYi5t2dqubBb585A7L40043VtsVVbPj -Qq5V0HDursvqlaMqMRcffhR8H4B4ByU/EPRK4yTKm1hi19v3UtRHiq74CfGtJzYt -plgrLJBON7TsbIi/fEux4q1yhbKA0S66L6e5DZldRxNZOXG6QjEL0RkYloMgkbv/ -2HLCu09hAgMBAAECggEAOR3xRVUO9Sr816JRSQwz486eNDpNSxazgwtOb3JUTUH9 -E7onq1y/kMOgOmSIEHoP9GaTcQxbbPe86IxomhLT/50ri52YzWzx/heY2SVPyQXB -FMo79putKw0vnj5UyydNiyLrbMQyrhFc5iFmWVdz5/c4cWHwjIThPp7V4znXYwHZ -OB/Xn1NNHDNy872oQn5wZWzuA4ml0OqjU5D+Ne9srODl3r4OTo3lb1N3JuH3aOSA -cACl1JnN/KElN8IotIdweeUFAdn2jsGjZnCpGaJvZQ+2iMn6doJXHgFiF5+GMF7o -aOatglElIuqgPtB/4nvnegSL0DSnB36ojqv2PAh24wKBgQDPBt4S4muqo8SqP2e0 -8X78MyK3tz1VmgPKn3O68Vdi1V7FPz0RHRGsw/kdgxXsJlfZTWgzcq2NNFu0yPBJ -A/h7qo16mv8GW7cJCd2exjb+/oq4r5iWeqLdSsMUXN87x02LRaMNd9wz1mls1Z73 -oQ5hJ7zTtlyYXnvKPQo8X1ImjwKBgQDCaptQxZ/a3tcUQQlXAFMAScviODZd0LCL -30ZalwpNs6nVVIPoZHD3tlzWN5Es74gndfkC7/Gm2cnsOW9QQaU56q+5LeNXItW8 -rc6yXq3vNQerqJxHNUmKWwLCQtSyLRjFqpGTl/PyX2bGXQ7/zjTL3W8VMD5otf4Y -SJJB+sKjDwKBgHSVX3WvAAamFtfwwMwKuwH3IfPnQqj0BHKUfK2nvxgvJCFbzV3X -yt5Jtf3ClhPYO9xpVOa0C7va4lHaXkYf8Exj7SxAIKFKALccUStaYBoU6bW7XOhQ -w2pu8ZCEBEo7oBVv77Rj7SNb+R6K5ex5TAm2QQXQSjCb9IYc/ail3TNNAoGBALu6 -GPMrgKnlFyV1j0E1DPBwUbDEuqpoArFtDRAYXFifLVTS4PQbWIG403f9++659Gy2 -G5ZcfqiwD6xL4VJLsPF1zewvhR/0gRJJehb+GVGrkRaOHykbKUGxk75kreDGbu8f -PqaXyXS17hWIch1Lzes0jDiXdwvA//QOzztqmVq9AoGAVMbmf04+QtzckLolAP4q -Uwr5svfy14A7V3IGkwlsHZdm37L26lfxW0kpOOE7g7D6gdinuALo6oopP7RN/IDq -PLaaHaGrIoLAEVFa0bRLGsrU2q87ytwfSgdra4jmsTn+xEabdI4IgmqWgwSRvGVf -KN18e19Ssw5x7Wq0Rsw/3VM= ------END PRIVATE KEY----- - - -``` - -When prompted, log in with the username and password. diff --git a/docs/configuration/interfaces/md-openvpn.md b/docs/configuration/interfaces/md-openvpn.md deleted file mode 100644 index 170c585d..00000000 --- a/docs/configuration/interfaces/md-openvpn.md +++ /dev/null @@ -1,614 +0,0 @@ -(openvpn)= - -# OpenVPN - -Traditionally, hardware routers use IPsec exclusively because it is easy to -implement in hardware, and their CPUs lack sufficient power for software-based -encryption. This limitation is less relevant for VyOS, as it is a software -router. - -OpenVPN has been widely used on UNIX platforms for a long time and is a popular -choice for remote-access VPNs. It also supports site-to-site connections. - -OpenVPN offers the following advantages: - -- It uses a single TCP or UDP connection and does not rely on packet source - addresses, so it works even through double NAT. This makes it well-suited for - public hotspots. -- It is easy to set up and offers very flexible split tunneling. -- A variety of client GUI frontends are available for any platform. - -Disadvantages include: - -- It is slower than IPsec due to higher protocol overhead and because it runs - in user mode, while IPsec on Linux runs in kernel mode. -- No operating system includes OpenVPN client software by default. - -In the VyOS CLI, OpenVPN is configured as a network interface using `set -interfaces openvpn` rather than `set vpn`, which is often overlooked. - -## Configuration - -```{cfgcmd} set interfaces openvpn \ authentication password \ - - **Configure the password for the** ``auth-user-pass`` **authentication method.** - - This option applies only to OpenVPN clients. -``` - - -```{cfgcmd} set interfaces openvpn \ authentication username \ - -**Configure the username for the** ``auth-user-pass`` **authentication method.** - -This option applies only to OpenVPN clients. -``` - - -```{cfgcmd} set interfaces openvpn \ description \ - -Configure the description for the OpenVPN interface. -``` - - -```{cfgcmd} set interfaces openvpn \ device-type \ - -**Configure the virtual network device type for the OpenVPN interface:** - -* ``tun`` **(default)**: Operates at Layer 3, encapsulating IPv4 or IPv6 packets. -* ``tap``: Operates at Layer 2, encapsulating Ethernet 802.3 frames. -``` - - -```{cfgcmd} set interfaces openvpn \ disable - -Disable the specific OpenVPN interface. -``` - - -```{cfgcmd} set interfaces openvpn \ encryption cipher \< 3des | aes128 | aes128gcm | aes192 | aes192gcm | aes256 | aes256gcm | none \> - -**Configure the static encryption cipher for the OpenVPN tunnel.** - -The ``cipher`` option maps to OpenVPN’s ``--cipher`` directive and specifies -the symmetric encryption algorithm for both control and data channels. - -This was previously the default encryption method in all OpenVPN modes. In -newer OpenVPN versions, the ``--cipher`` directive is considered **legacy** -and should be used only in compatibility scenarios. -``` - - -```{cfgcmd} set interfaces openvpn \ encryption data-ciphers \< 3des | aes128 | aes128gcm | aes192 | aes192gcm | aes256 | aes256gcm | none \> - -**Configure a prioritized list of negotiated ciphers for OpenVPN in** -``client`` **or** ``server`` **mode.** - -The ``data-ciphers`` option represents a list of supported encryption -algorithms. It corresponds to OpenVPN’s ``--data-ciphers`` directive and -enables cipher negotiation, where both peers automatically agree on a mutually -supported cipher during session startup. - -:::{note} -This option is not compatible with ``site-to-site`` mode. -::: -``` - - -```{cfgcmd} set interfaces openvpn \ encryption data-ciphers-fallback \< 3des | aes128 | aes128gcm | aes192 | aes192gcm | aes256 | aes256gcm | none \> - -**Configure the fallback cipher for** ``site-to-site`` **mode.** - -The ``data-ciphers-fallback`` option maps to OpenVPN’s ``--data-ciphers- -fallback`` directive. It defines the cipher to use if negotiation is **not -supported**. - -:::{note} -This option ensures consistent encryption between two static peers -without cipher negotiation capability. -::: -``` - - -```{cfgcmd} set interfaces openvpn \ hash \ - -Configure the hashing algorithm for the OpenVPN interface. -``` - - -```{cmdincludemd} /_include/interface-ip.txt -:var0: openvpn -:var1: vtun0 -``` - - -```{cmdincludemd} /_include/interface-ipv6.txt -:var0: openvpn -:var1: vtun0 -``` - - -```{cfgcmd} set interfaces openvpn \ keep-alive failure-count \ - -**Configure the number of tolerated keepalive packet failures.** - -Default: 60 consecutive failures. -``` - - -```{cfgcmd} set interfaces openvpn \ keep-alive interval \ - -**Configure the frequency, in seconds, at which keepalive packets are sent.** - -Default: 10 seconds. -``` - - -```{cfgcmd} set interfaces openvpn \ local-address \ - -Configure the local tunnel IP address for ``site-to-site`` mode. -``` - - -```{cfgcmd} set interfaces openvpn \ local-host \ - -**Configure the local IP address to accept connections.** - -If configured, OpenVPN binds to this IP address only. - -By default, OpenVPN binds to all interfaces. -``` - - -```{cfgcmd} set interfaces openvpn \ local-port \ - -Configure the local port to accept connections. -``` - - -```{cfgcmd} set interfaces openvpn \ mirror egress \ - -Configure mirroring of outgoing traffic from this OpenVPN interface to the -designated monitor interface. -``` - - -```{cfgcmd} set interfaces openvpn \ mirror ingress \ - -Configure mirroring of incoming traffic from this OpenVPN interface to the -designated monitor interface. -``` - - -```{cfgcmd} set interfaces openvpn \ mode \ - -**Configure OpenVPN operation mode:** - -* ``site-to-site``: Establishes a site-to-site VPN connection. -* ``client``: Operates as a client in server-client mode. -* ``server``: Operates as a server in server-client mode. -``` - -### OpenVPN Data Channel Offload (DCO) - -OpenVPN {abbr}`DCO (Data Channel Offload)` improves the performance of -encrypted OpenVPN data processing by keeping most data handling in the kernel -and avoiding frequent context switches between the kernel and user space. - -As a result, packet processing becomes more efficient and may utilize hardware -encryption offload support available in the kernel. - -:::{note} -- {abbr}`DCO (Data Channel Offload)` is an **experimental**, not fully supported - OpenVPN feature. Some OpenVPN features and deployment scenarios are **not - compatible** with {abbr}`DCO (Data Channel Offload)`. - - For a complete list of supported features, visit: - -- {abbr}`DCO (Data Channel Offload)` is configured per tunnel and disabled - by default. Existing tunnels operate without {abbr}`DCO (Data Channel - Offload)` unless it is explicitly enabled. -- Enabling {abbr}`DCO (Data Channel Offload)` resets the interface. -::: - -**Best practice:** Create a new tunnel with {abbr}`DCO (Data Channel Offload)` -enabled to avoid compatibility issues with existing clients. - -```{cfgcmd} set interfaces openvpn \ offload dco - - **Enable** {abbr}`DCO (Data Channel Offload)` **for the specified OpenVPN - interface.** - - Example: - - :::{code-block} none - set interfaces openvpn vtun0 offload dco - ::: - This command enables {abbr}`DCO (Data Channel Offload)` and loads the required - kernel module. -``` - - -```{cfgcmd} set interfaces openvpn \ openvpn-option \ - -**Add raw OpenVPN configuration options to the openvpn.conf file.** - -OpenVPN provides many configuration options, but not all are available in the -VyOS CLI. - -If a required option is missing, you may submit a feature request at -Phabricator so all users can benefit from it (see Contributing/Issues and Features). - -Alternatively, use ``openvpn-option`` to pass raw OpenVPN configuration options -to the openvpn.conf file. - -:::{warning} -Use this option only as a last resort. Invalid options or syntax -may prevent OpenVPN from starting. Check system logs for errors after applying -changes. -::: -Example: - -:::{code-block} none -set interfaces openvpn vtun0 openvpn-option 'persist-key' -::: -This command adds ``persist-key`` to the configuration file. This solves the -problem by persisting keys across resets, so they do not need to be re-read. - -:::{code-block} none -set interfaces openvpn vtun0 openvpn-option 'route-up "/config/auth/tun_up.sh arg1"' -::: -This command adds ``route-up "/config/auth/tun_up.sh arg1"`` to the -configuration file. This option is executed after connection authentication, -either immediately or after a short delay, as defined. - -Ensure the path and arguments are enclosed in single or double quotes. - -:::{note} -Some raw configuration options require quotes. To include them, use -the " statement. -::: -``` - - -```{cfgcmd} set interfaces openvpn \ persistent-tunnel - -**Enable always-active mode for the TUN/TAP device.** - -When enabled, the TUN/TAP device remains active upon connection resets or -daemon reloads. -``` - - -```{cfgcmd} set interfaces openvpn \ protocol \ - -**Configure the protocol for OpenVPN communication with a remote host:** - -* ``udp`` **(default)**: Uses the UDP protocol. -* ``tcp-passive``: Uses the TCP protocol and accepts connections passively. -* ``tcp-active``: Uses the TCP protocol and initiates connections actively. -``` - - -```{cfgcmd} set interfaces openvpn \ redirect \ - -Enable redirection of incoming packets to the specified interface. -``` - - -```{cfgcmd} set interfaces openvpn \ remote-address \ - -Configure the remote tunnel IP address for site-to-site mode. -``` - - -```{cfgcmd} set interfaces openvpn \ remote-host \
- -**Configure the IPv4/IPv6 address or hostname for a server device if OpenVPN -runs in client mode.** - -This setting is not used in server mode. -``` - - -```{cfgcmd} set interfaces openvpn \ remote-port \ - -Configure the remote port to connect to the server. -``` - - -```{cfgcmd} set interfaces openvpn \ replace-default-route - -Configure the OpenVPN tunnel as the default route. -``` - - -```{cfgcmd} set interfaces openvpn \ server bridge disable - -Disable the given instance. -``` - - -```{cfgcmd} set interfaces openvpn \ server bridge gateway \ - -Configure the gateway IP address. -``` - - -```{cfgcmd} set interfaces openvpn \ server bridge start \ - -Configure the first IP address in the pool to allocate to connecting clients. -``` - - -```{cfgcmd} set interfaces openvpn \ server bridge stop \ - -Configure the last IP address in the pool to allocate to connecting clients. -``` - - -```{cfgcmd} set interfaces openvpn \ server bridge subnet-mask \ - -Configure the subnet mask pushed to dynamic clients. -``` - - -```{cfgcmd} set interfaces openvpn \ server client \ - -Configure the Common Name (CN) specified in the client certificate. -``` - - -```{cfgcmd} set interfaces openvpn \ server client \ disable - -Disable the client connection. -``` - - -```{cfgcmd} set interfaces openvpn \ server client \ ip \ - -Configure the IPv4/IPv6 address for the client. -``` - - -```{cfgcmd} set interfaces openvpn \ server client \ push-route \ - -Configure a route to be pushed to the specific client. -``` - - -```{cfgcmd} set interfaces openvpn \ server client \ subnet \ - -**Configure a fixed subnet to be routed from the server to the specified -client.** - -Used as OpenVPN’s ``iroute`` directive. -``` - - -```{cfgcmd} set interfaces openvpn \ server client-ip-pool start \ - -Configure the first IP address in the subnet's IPv4 pool to be dynamically -allocated to connecting clients. -``` - - -```{cfgcmd} set interfaces openvpn \ server client-ip-pool stop \ - -Configure the last IP address in the subnet's IPv4 pool to be dynamically -allocated to connecting clients. -``` - - -```{cfgcmd} set interfaces openvpn \ server client-ip-pool subnet \ - -**Configure the subnet mask pushed to dynamic clients.** - -Use this command only for the TAP device type. Do not use it for bridged -interfaces. -``` - - -```{cfgcmd} set interfaces openvpn \ server client-ipv6-pool base \ - -Configure the IPv6 address pool for dynamic assignment to clients. -``` - - -```{cfgcmd} set interfaces openvpn \ server domain-name \ - -Configure the DNS suffix to be pushed to all clients. -``` - - -```{cfgcmd} set interfaces openvpn \ server max-connections \<1-4096\> - -Configure the maximum number of client connections. -``` - - -```{cfgcmd} set interfaces openvpn \ server mfa totp challenge \ - -If enabled, openvpn-otp expects a password as a result of the challenge/ -response protocol. -``` - - -```{cfgcmd} set interfaces openvpn \ server mfa totp digits \<1-65535\> - -**Configure the number of digits to use for the** {abbr}`TOTP (Time-based -One-Time Password)` **hash.** - -Default: 6. -``` - - -```{cfgcmd} set interfaces openvpn \ server mfa totp drift \<1-65535\> - -**Configure the time drift in seconds.** - -Default: 0. -``` - - -```{cfgcmd} set interfaces openvpn \ server mfa totp slop \<1-65535\> - -**Configure the allowed clock slop in seconds.** - -Default: 180. -``` - - -```{cfgcmd} set interfaces openvpn \ server mfa totp step \<1-65535\> - -**Configure the step value for** {abbr}`TOTP (Time-based One-Time Password)` -**in seconds.** - -Default: 30. -``` - - -```{cfgcmd} set interfaces openvpn \ server name-server \ - -Define the client DNS configuration to be used with the connection. -``` - - -```{cfgcmd} set interfaces openvpn \ server push-route \ - -Configure the route to be pushed to all clients. -``` - - -```{cfgcmd} set interfaces openvpn \ server reject-unconfigured-client - -Reject connections from clients that are not explicitly configured. -``` - - -```{cfgcmd} set interfaces openvpn \ server subnet \ - -**Configure the IPv4 or IPv6 network.** - -This parameter is mandatory when operating in server mode. -``` - - -```{cfgcmd} set interfaces openvpn \ server topology \< net30 | point-to-point | subnet\> - -**Configure the virtual addressing topology for** ``tun`` **mode.** - -This command does not affect ``tap`` mode, which always uses the ``subnet`` -topology. - -* ``subnet`` **(default)**: Allocates a single IP address to each connecting client. -This is the recommended topology. -* ``net30``: Allocates a /30 subnet to each connecting client. This is a legacy -topology used to support Windows clients. It is now effectively deprecated. -* ``point-to-point``: Creates a point-to-point topology where the remote -endpoint of the client’s ``tun`` interface always points to the local endpoint -of the server’s ``tun`` interface. - -Like ``subnet``, this topology allocates a single IP address per client. Use it -only if no clients run Windows operating systems. -``` -```{cfgcmd} set interfaces openvpn \ shared-secret-key \ - -Configure the static secret key for a site-to-site OpenVPN connection. -``` -```{cfgcmd} set interfaces openvpn \ tls auth-key \ - -**Configure the TLS secret key for tls-auth.** - -This adds an HMAC signature to all SSL/TLS handshake packets to verify -integrity. - -Use ``run generate pki openvpn shared-secret install `` to generate -the key. -``` -```{cfgcmd} set interfaces openvpn \ tls ca-certificate \ - -Configure the Certificate Authority chain in the PKI configuration. -``` -```{cfgcmd} set interfaces openvpn \ tls certificate \ - -Configure the certificate name in the PKI configuration. -``` -```{cfgcmd} set interfaces openvpn \ tls crypt-key - -Configure a shared secret key to provide an additional level of security, -a variant similar to tls-auth. -``` -```{cfgcmd} set interfaces openvpn \ tls dh-params - -Configure Diffie-Hellman parameters for server mode. -``` -```{cfgcmd} set interfaces openvpn \ tls peer-fingerprint \ - -Configure the peer certificate SHA256 fingerprint for site-to-site mode. -``` -```{cfgcmd} set interfaces openvpn \ tls role \ - -**Configure the TLS negotiation role, preferably used in site-to-site mode:** -* ``active``: Initiates TLS negotiation actively. -* ``passive``: Waits for incoming TLS connections. -``` -```{cfgcmd} set interfaces openvpn \ tls tls-version-min \<1.0 | 1.1 | 1.2 | 1.3 \> - -Configure the minimum TLS version to be accepted from the peer. -``` -```{cfgcmd} set interfaces openvpn \ use-lzo-compression - -Configure fast LZO compression on this TUN/TAP interface. -``` -```{cfgcmd} set interfaces openvpn \ vrf \ - -Assign the interface to a specific VRF instance. -``` - -## Operation mode - -```{opcmd} show openvpn site-to-site - -Show tunnel status for OpenVPN site-to-site interfaces. -``` -```{opcmd} show openvpn server - -Show tunnel status for OpenVPN server interfaces. -``` -```{opcmd} show openvpn client - -Show tunnel status for OpenVPN client interfaces. -``` -```{opcmd} show log openvpn - -Show logs for all OpenVPN interfaces. -``` -```{opcmd} show log openvpn interface \ - -Show logs for the specific OpenVPN interface. -``` -```{opcmd} reset openvpn client \ - -Reset the specified OpenVPN client. -``` -```{opcmd} reset openvpn interface \ - -Reset the OpenVPN process on the specified interface. -``` -```{opcmd} generate openvpn client-config interface \ ca \ certificate \ - -Generate an OpenVPN client configuration file in the .ovpn format for client machines. -``` - -## Examples - -This section covers examples of OpenVPN configurations for various deployments. - -```{toctree} -:includehidden: true -:maxdepth: 1 - -openvpn-examples -``` - diff --git a/docs/configuration/interfaces/md-pppoe.md b/docs/configuration/interfaces/md-pppoe.md deleted file mode 100644 index b79f41a2..00000000 --- a/docs/configuration/interfaces/md-pppoe.md +++ /dev/null @@ -1,419 +0,0 @@ ---- -lastproofread: '2026-03-03' ---- - -(pppoe-interface)= - -# PPPoE - -{abbr}`PPPoE (Point-to-Point Protocol over Ethernet)` is a network protocol -that encapsulates PPP frames within Ethernet frames. -It's often used for connecting ISP clients to a broadband access server. - -## Configuration - -### Common interface configuration - -```{cmdincludemd} /_include/interface-description.txt -:var0: pppoe -:var1: pppoe0 -``` - -```{cmdincludemd} /_include/interface-disable.txt -:var0: pppoe -:var1: pppoe0 -``` - -```{cmdincludemd} /_include/interface-mtu.txt -:var0: pppoe -:var1: pppoe0 -``` - -```{cmdincludemd} /_include/interface-vrf.txt -:var0: pppoe -:var1: pppoe0 -``` - - -### PPPoE options - -```{cfgcmd} set interfaces pppoe \ access-concentrator \ - -**Configure the name of the target access concentrator for the PPPoE session.** - -During the PPPoE discovery process, the client sends a PPPoE initiation packet. -Multiple access concentrators may respond with offer packets, and the client -selects one of them. - -This setting restricts the client to establishing sessions only with the -specified access concentrator. -``` - -```{cfgcmd} set interfaces pppoe \ authentication username \ - -**Configure the username for PPPoE session authentication.** - -Although authentication is optional in the interface configuration, most ISPs -require it to establish a connection. -``` - -```{cfgcmd} set interfaces pppoe \ authentication password \ - -**Configure the password for PPPoE session authentication.** - -Although authentication is optional in the interface configuration, most ISPs -require it to establish a connection. -``` - -```{cfgcmd} set interfaces pppoe \ connect-on-demand - -**Enable dial-on-demand on the PPPoE interface.** - -When enabled, the system establishes a PPPoE connection only when traffic -passes through the interface. If the connection fails, it is reestablished when -traffic resumes. - -For on-demand connections, you must also configure an ``idle-timeout`` period -to disconnect the session after inactivity. - -:::{note} -Setting the idle timeout to zero, or leaving it unconfigured, keeps -the connection active continuously once established. -::: - -By default, the PPPoE connection is established at boot and remains active -continuously; if the connection fails, it is reestablished immediately. -``` - -```{cfgcmd} set interfaces pppoe \ no-default-route - -Request an IP address from the PPPoE server without installing a default route. - -Example: - -:::{code-block} none -set interfaces pppoe pppoe0 no-default-route -::: - -:::{note} -Introduced in VyOS 1.4, this command inverts the logic of the former -``default-route`` CLI option. -::: -``` - -```{cfgcmd} set interfaces pppoe \ default-route-distance \ - -Configure the distance for the default gateway provided by the PPPoE server. - -Example: - -:::{code-block} none -set interfaces pppoe pppoe0 default-route-distance 220 -::: -``` - -```{cfgcmd} set interfaces pppoe \ mru \ - -**Configure the** {abbr}`MRU (Maximum Receive Unit)` **for the PPPoE -interface.** - -This setting instructs the pppd daemon to restrict the remote peer from sending -packets larger than the configured MRU. Allowed MRU values range from 128 to -16384 bytes. - -An MRU of 296 is suitable for very slow links (40 bytes for the TCP/IP header -and 256 bytes for data). - -The default MRU is 1492 bytes. - -:::{note} -When using the IPv6 protocol, the MRU must be at least 1280 bytes. -::: -``` - -```{cfgcmd} set interfaces pppoe \ idle-timeout \ - -**Configure the idle timeout for on-demand PPPoE sessions.** - -This setting defines how long the connection remains active without any traffic -before being disconnected. - -:::{note} -Setting the idle timeout to zero, or leaving it unconfigured, keeps -the connection active continuously once established. -::: -``` - -```{cfgcmd} set interfaces pppoe \ holdoff \ - -**Configure the redial delay for persistent PPPoE sessions.** - -If a persistent session (with ``connect-on-demand`` disabled) is terminated by -the remote peer or drops unexpectedly, the router waits the specified interval -before attempting to reconnect. - -The default redial delay is 30 seconds. -``` - -```{cfgcmd} set interfaces pppoe \ local-address \ - -**Configure the local endpoint IP address for PPPoE sessions.** - -By default, this IP address is negotiated. -``` - -```{cfgcmd} set interfaces pppoe \ no-peer-dns - -Disable the installation of advertised DNS nameservers on the local system. -``` - -```{cfgcmd} set interfaces pppoe \ remote-address \ - -**Configure the remote endpoint IP address for PPPoE sessions.** - -By default, this IP address is negotiated. -``` - -```{cfgcmd} set interfaces pppoe \ service-name \ - -**Configure the service name of the target access concentrator for the PPPoE -session.** - -By default, the PPPoE interface connects to any available access concentrator. -``` - -```{cfgcmd} set interfaces pppoe \ source-interface \ - -**Configure the underlying interface for the PPPoE connection.** - -Each PPPoE connection is established over an underlying interface, which can be -an Ethernet interface, a VIF, or a bonding interface. -``` - -```{cfgcmd} set interfaces pppoe \ ip adjust-mss \ - -**Configure the** {abbr}`MSS (Maximum Segment Size)` **advertised in outgoing -TCP SYN packets on the specified interface.** - -By clamping the MSS value in TCP SYN packets, you instruct the remote side not -to send packets larger than the specified size. This helps prevent connection -issues if {abbr}`PMTUD (Path MTU Discovery)` fails. - -The following options are available: - -* ``mss``: Sets the MSS to a specific value in bytes. -* ``clamp-mss-to-pmtu``: Sets the MSS to the interface’s MTU minus 40 bytes for - IPv4 traffic (20 bytes for the IPv4 header and 20 bytes for the TCP header). - This option is recommended to automatically set the proper value. - -:::{note} -Introduced in VyOS 1.4, this command replaces the older ``set firewall -options interface adjust-mss `` syntax. -::: -``` - -```{cfgcmd} set interfaces pppoe \ ip disable-forwarding - -**Configure the interface for host or router behavior.** - -If configured, the interface switches to host mode, and IPv4 forwarding is -disabled on it. -``` - -```{cfgcmd} set interfaces pppoe \ ip source-validation \ - -**Configure source IP address validation using** -{abbr}`RPF (Reverse Path Forwarding)` **on this interface, as specified in** -{rfc}`3704`. - -The following options are available: - -* ``strict``: Each incoming packet’s source IP address is checked against the - {abbr}`FIB (Forwarding Information Base)`. If the interface is not the best - route back to that source, validation fails, and the packet is dropped. -* ``loose``: Each incoming packet’s source IP address is checked against the - {abbr}`FIB (Forwarding Information Base)`. If the source IP address is - unreachable through any interface, validation fails. -* ``disable``: No source IP address validation is performed. All incoming - packets are accepted. - -{rfc}`3704` recommends enabling ``strict`` mode to prevent IP spoofing, such as -DDoS attacks. For asymmetric or other complex routing scenarios, use ``loose`` -mode. -``` - - -#### IPv6 - -```{cfgcmd} set interfaces pppoe \ ipv6 address autoconf - -Enable IPv6 address assignment via {abbr}`SLAAC (Stateless Address -Auto-Configuration)` on this interface. -``` - -```{cfgcmd} set interfaces pppoe \ ipv6 adjust-mss \ - -**Configure the** {abbr}`MSS (Maximum Segment Size)` **advertised in outgoing -TCP SYN packets on the specified interface.** - -By clamping the MSS value in TCP SYN packets, you instruct the remote side not -to send packets larger than the specified size. This helps prevent connection -issues if {abbr}`PMTUD (Path MTU Discovery)` fails. - -The following options are available: - -* ``mss``: Sets the MSS to a specific value in bytes. -* ``clamp-mss-to-pmtu``: Sets the MSS to the interface’s MTU minus 60 bytes for - IPv6 traffic (40 bytes for the IPv6 header and 20 bytes for the TCP header). - This option is recommended to automatically set the proper value. - -:::{note} -Introduced in VyOS 1.4, this command replaces the older ``set firewall -options interface adjust-mss `` syntax. -::: -``` - -```{cfgcmd} set interfaces pppoe \ ipv6 disable-forwarding - -**Configure the interface for host or router behavior.** - -If configured, the interface switches to host mode, and IPv6 forwarding is -disabled on it. -``` - -```{cmdincludemd} /_include/interface-dhcpv6-prefix-delegation.txt -:var0: pppoe -:var1: pppoe0 -``` - - -## Operation - -```{opcmd} show interfaces pppoe \ - -Show detailed information about a specific PPPoE interface. - -:::{code-block} none -vyos@vyos:~$ show interfaces pppoe pppoe0 -pppoe0: mtu 1492 qdisc pfifo_fast state UNKNOWN group default qlen 3 - link/ppp - inet 192.0.2.1 peer 192.0.2.255/32 scope global pppoe0 - valid_lft forever preferred_lft forever - - RX: bytes packets errors dropped overrun mcast - 7002658233 5064967 0 0 0 0 - TX: bytes packets errors dropped carrier collisions - 533822843 1620173 0 0 0 0 -::: -``` - -```{opcmd} show interfaces pppoe \ queue - -Show queue information for a specific PPPoE interface. - -:::{code-block} none -vyos@vyos:~$ show interfaces pppoe pppoe0 queue -qdisc pfifo_fast 0: root refcnt 2 bands 3 priomap 1 2 2 2 1 2 0 0 1 1 1 1 1 1 1 1 - Sent 534625359 bytes 1626761 pkt (dropped 62, overlimits 0 requeues 0) - backlog 0b 0p requeues 0 -::: -``` - - -### Connect/disconnect - -```{opcmd} disconnect interface \ - -Disconnect the specified interface. -``` - -```{opcmd} connect interface \ - -Initiate a session on the specified interface. -``` - - -## Example - -### PPPoE over DSL - -**Configuration scenario:** - -- Your ISP's DSL modem is connected to the `eth0` interface on your VyOS - router. -- Your ISP does not require VLAN tagging. -- PPPoE credentials are provided by your ISP. The typical username format is - `name@host.net`, though this may vary. - -**Configuration notes:** - -- The maximum MTU size for DSL is 1492 because of PPPoE overhead. If you are - switching from a DHCP-based ISP (e.g., a standard cable connection), ensure - VPN links have MTU sizes adjusted accordingly. -- To ignore ISP-provided nameservers and use only your statically configured - ones, set the `name-server` option to `none`. -- A default route is automatically installed once the interface is up. To - change this behavior, use the `no-default-route` CLI option. - -:::{note} -The PPPoE configuration syntax changed after VyOS 1.2 (Crux) and is -automatically migrated during an upgrade. -::: - -```none -set interfaces pppoe pppoe0 authentication username 'userid' -set interfaces pppoe pppoe0 authentication password 'secret' -set interfaces pppoe pppoe0 source-interface 'eth0' -``` - -Secure your setup by creating rules matching the `pppoe0` interface in the -firewall chains: - -```none -set firewall ipv4 input filter rule 10 inbound-interface name 'pppoe0' -set firewall ipv4 forward filter rule 10 inbound-interface name 'pppoe0' -``` - - -### PPPoE over VLAN - -Some ISPs require PPPoE connections to be -established over a VLAN interface. This specific topology is fully supported by -VyOS. - -The following configuration establishes the PPPoE connection through VLAN 7, -which is the default VLAN for Deutsche Telekom: - -```none -set interfaces pppoe pppoe0 authentication username 'userid' -set interfaces pppoe pppoe0 authentication password 'secret' -set interfaces pppoe pppoe0 source-interface 'eth0.7' -``` - - -#### IPv6 DHCPv6 prefix delegation - -**Configuration scenario:** - -The following configuration establishes a PPPoE session on the `eth1` -interface, requests a `/56` IPv6 prefix delegation from the ISP, and assigns -a `/64` subnet from that delegation to the `eth0` interface. - -**Configuration notes:** - -- The IPv6 address assigned to `eth0` is `::1/64`. -- If you do not know your delegated prefix size, begin with `sla-len 0`. -- To advertise the prefix on the `eth0` link, configure IPv6 Router - Advertisement. - -```none -set interfaces pppoe pppoe0 authentication username vyos -set interfaces pppoe pppoe0 authentication password vyos -set interfaces pppoe pppoe0 dhcpv6-options pd 0 interface eth0 address '1' -set interfaces pppoe pppoe0 dhcpv6-options pd 0 interface eth0 sla-id '0' -set interfaces pppoe pppoe0 dhcpv6-options pd 0 length '56' -set interfaces pppoe pppoe0 ipv6 address autoconf -set interfaces pppoe pppoe0 source-interface eth1 - -set service router-advert interface eth0 prefix ::/64 -``` diff --git a/docs/configuration/interfaces/md-pseudo-ethernet.md b/docs/configuration/interfaces/md-pseudo-ethernet.md deleted file mode 100644 index fc8833eb..00000000 --- a/docs/configuration/interfaces/md-pseudo-ethernet.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -lastproofread: '2026-03-05' ---- - -(pseudo-ethernet-interface)= - -# MACVLAN (pseudo-Ethernet) - -MACVLAN, or pseudo-Ethernet interfaces, operate as logical subinterfaces of -standard Ethernet interfaces. Each subinterface has a unique MAC address but -shares a single physical Ethernet port. -That allows the user to send packets from different source IPv4 or IPv6 addresses -using a different MAC address. - -Pseudo-Ethernet interfaces behave like physical Ethernet interfaces. They -support IPv4 and IPv6 addressing, can obtain IP addresses through DHCP or -DHCPv6, and are mapped to a physical Ethernet port. They inherit -characteristics such as speed and duplex from their parent interface and can -be referenced like standard Ethernet interfaces once created. - -```{eval-rst} -Pseudo-Ethernet interfaces may not work in environments that require a - :abbr:`NIC (Network Interface Card)` to have only one MAC address. - This includes: - - * VMware machines with default settings. - * Network switches that permit only a single MAC address. - * xDSL modems that learn the NIC's MAC address. -``` - -## Configuration - -### Common interface configuration - -```{cmdincludemd} /_include/interface-common-with-dhcp.txt -:var0: pseudo-ethernet -:var1: peth0 -``` - -### MACVLAN (pseudo-Ethernet) options - -```{cfgcmd} set interfaces pseudo-ethernet \ source-interface \ - -Assign a physical Ethernet interface to the specified pseudo-Ethernet interface. -``` - -### VLAN - -```{cmdincludemd} /_include/interface-vlan-8021q.txt -:var0: pseudo-ethernet -:var1: peth0 -``` \ No newline at end of file diff --git a/docs/configuration/interfaces/md-sstp-client.md b/docs/configuration/interfaces/md-sstp-client.md deleted file mode 100644 index da98aecd..00000000 --- a/docs/configuration/interfaces/md-sstp-client.md +++ /dev/null @@ -1,170 +0,0 @@ ---- -lastproofread: '2026-03-16' ---- - -(sstp-client-interface)= - -# SSTP client - -{abbr}`SSTP (Secure Socket Tunneling Protocol)` transports PPP traffic over an -SSL/TLS channel, providing transport-level security through key negotiation, -encryption, and traffic integrity checking. The use of SSL/TLS over TCP port -443 (by default, the port can be changed) allows SSTP to pass through virtually -all firewalls and proxy servers, except for authenticated web proxies. - -:::{note} -VyOS includes a built-in SSTP server. For more information, see -{ref}`sstp`. -::: - -## Configuration - -### Common interface configuration - -```{cmdincludemd} /_include/interface-description.txt -:var0: sstpc -:var1: sstpc0 -``` - -```{cmdincludemd} /_include/interface-disable.txt -:var0: sstpc -:var1: sstpc0 -``` - -```{cmdincludemd} /_include/interface-mtu.txt -:var0: sstpc -:var1: sstpc0 -``` - -```{cmdincludemd} /_include/interface-vrf.txt -:var0: sstpc -:var1: sstpc0 -``` - - -### SSTP client options - -```{cfgcmd} set interfaces sstpc \ no-default-route - -Request an IP address from the SSTP server without installing a default route. - -Example: - -:::{code-block} none -set interfaces sstpc sstpc0 no-default-route -::: -:::{note} Introduced in VyOS 1.4, this command inverts the logic of the former -``default-route`` CLI option. -::: -``` - -```{cfgcmd} set interfaces sstpc \ default-route-distance \ - -Configure the distance for the default gateway provided by the SSTP server. - -Example: - -:::{code-block} none -set interfaces sstpc sstpc0 default-route-distance 220 -::: -``` - -```{cfgcmd} set interfaces sstpc \ no-peer-dns - -Disable the installation of advertised DNS nameservers on the local system. -``` - -```{cfgcmd} set interfaces sstpc \ server \ - -**Configure the remote SSTP server address for the client connection.** - -The address can be either an IP address or a {abbr}`FQDN (Fully Qualified -Domain Name)`. -``` - -```{cfgcmd} set interfaces sstpc \ ip adjust-mss \ - -**Configure the** {abbr}`MSS (Maximum Segment Size)` **advertised in outgoing -TCP SYN packets on the specified interface.** - -By clamping the MSS value in TCP SYN packets, you instruct the remote side not -to send packets larger than the specified size. This helps prevent connection -issues if {abbr}`PMTUD (Path MTU Discovery)` fails. - -The following options are available: - -* ``mss``: Sets the MSS to a specific value in bytes. -* ``clamp-mss-to-pmtu``: Sets the MSS to the interface’s MTU minus 40 bytes for -IPv4 traffic (20 bytes for the IPv4 header and 20 bytes for the TCP header). -This option is recommended to automatically set the proper value. - -:::{note} Introduced in VyOS 1.4, this command replaces the older ``set firewall -options interface adjust-mss `` syntax. -::: -``` - -```{cfgcmd} set interfaces sstpc \ ip disable-forwarding - -**Configure the interface for host or router behavior.** - -If configured, the interface switches to host mode, and IPv4 forwarding is -disabled on it. -``` - -```{cfgcmd} set interfaces sstpc \ ip source-validation \ - -**Configure source IP address validation using** -{abbr}`RPF (Reverse Path Forwarding)` **on this interface, as specified in** -{rfc}`3704`. - -The following options are available: - -* ``strict``: Each incoming packet’s source IP address is checked against the -{abbr}`FIB (Forwarding Information Base)`. If the interface is not the best -route back to that source, validation fails, and the packet is dropped. -* ``loose``: Each incoming packet’s source IP address is checked against the -{abbr}`FIB (Forwarding Information Base)`. If the source IP address is -unreachable through any interface, validation fails. -* ``disable``: No source IP address validation is performed. All incoming -packets are accepted. - -{rfc}`3704` recommends enabling ``strict`` mode to prevent IP spoofing, such as -DDoS attacks. For asymmetric or other complex routing scenarios, use ``loose`` -mode. -``` - - -## Operation - -```{opcmd} show interfaces sstpc \ - -Show detailed information about the specified interface. - -:::{code-block} none -vyos@vyos:~$ show interfaces sstpc sstpc10 -sstpc10: mtu 1500 qdisc pfifo_fast state UNKNOWN group default qlen 3 - link/ppp - inet 192.0.2.5 peer 192.0.2.254/32 scope global sstpc10 - valid_lft forever preferred_lft forever - inet6 fe80::fd53:c7ff:fe8b:144f/64 scope link - valid_lft forever preferred_lft forever - - RX: bytes packets errors dropped overrun mcast - 215 9 0 0 0 0 - TX: bytes packets errors dropped carrier collisions - 539 14 0 0 0 0 -::: -``` - - -### Connect/disconnect - -```{opcmd} disconnect interface \ - -Disconnect the specified interface. -``` - -```{opcmd} connect interface \ - -Initiate a session on the specified interface. -``` \ No newline at end of file diff --git a/docs/configuration/interfaces/md-tunnel.md b/docs/configuration/interfaces/md-tunnel.md deleted file mode 100644 index 9c9885d2..00000000 --- a/docs/configuration/interfaces/md-tunnel.md +++ /dev/null @@ -1,309 +0,0 @@ ---- -lastproofread: '2026-01-23' ---- - -(tunnel-interface)= - -# Tunnel - -Tunnel interfaces are virtual links that transmit encapsulated traffic between -private networks or hosts across public infrastructure, such as the Internet. -They operate using encapsulation protocols to wrap original traffic for -transport. The supported protocols include {abbr}`GRE (Generic Routing -Encapsulation)`, IPIP, IPIP6, IP6IP6, and 6in4 (SIT). - -While {abbr}`GRE (Generic Routing Encapsulation)` is often the preferred -one-size-fits-all solution due to its versatility, other encapsulation -protocols may be better suited for specific use cases. - -VyOS uses a single tunnel interface type for all of these protocols. There are -no separate {abbr}`GRE (Generic Routing Encapsulation)`, IPIP, or IP6IP6 -interface types; instead, the desired encapsulation protocol is selected within -the `set interfaces tunnel` configuration. - -Configuration options for each protocol are described below. - -:::{warning} -Do not change the encapsulation type for already configured tunnel -interfaces, as this may break their dependent configurations. -::: - -## Common interface configuration - -```{cmdincludemd} /_include/interface-address.txt -:var0: tunnel -:var1: tun0 -``` - -```{cmdincludemd} /_include/interface-common-without-mac.txt -:var0: tunnel -:var1: tun0 -``` - - -## IPIP - -IPIP is a straightforward encapsulation protocol defined in RFC 2003. It -encapsulates one IPv4 packet inside another IPv4 packet. - -Tunnels with IPIP encapsulation do not have protocol-specific configuration -options except for explicitly defining the encapsulation type as IPIP (see -the example below). - -Example: - -```none -set interfaces tunnel tun0 encapsulation ipip -set interfaces tunnel tun0 source-address 192.0.2.10 -set interfaces tunnel tun0 remote 203.0.113.20 -set interfaces tunnel tun0 address 192.168.100.200/24 -``` - - -## IP6IP6 - -IP6IP6 is the IPv6 counterpart to IPIP. It encapsulates one IPv6 packet inside -another IPv6 packet. - -Similar to their IPIP counterparts, tunnels with IP6IP6 encapsulation do not -have protocol-specific configuration options except for explicitly defining -the encapsulation type as IP6IP6. - -Example: - -```none -set interfaces tunnel tun0 encapsulation ip6ip6 -set interfaces tunnel tun0 source-address 2001:db8:aa::1 -set interfaces tunnel tun0 remote 2001:db8:aa::2 -set interfaces tunnel tun0 address 2001:db8:bb::1/64 -``` - - -## IPIP6 - -IPIP6 is an encapsulation protocol that wraps IPv4 packets inside IPv6 packets. - -Similar to IPIP and IP6IP6, protocol-specific configuration for tunnels with -IPIP6 encapsulation only requires defining the encapsulation type as IP6IP6. - -Example: - -```none -set interfaces tunnel tun0 encapsulation ipip6 -set interfaces tunnel tun0 source-address 2001:db8:aa::1 -set interfaces tunnel tun0 remote 2001:db8:aa::2 -set interfaces tunnel tun0 address 192.168.70.80/24 -``` - - -## 6in4 (SIT) - -6in4, also known as {abbr}`SIT (Simple Internet Transition)`, is an -encapsulation protocol defined in {rfc}`4213` that wraps IPv6 packets -inside IPv4 packets. The encapsulating IPv4 headers use IP protocol number 41, -which is reserved exclusively for IPv6 encapsulation. - -The encapsulation process adds a 20-byte IPv4 header to each IPv6 packet. -Consequently, 6in4 tunnel interfaces can transmit IPv6 packets up to 1480 bytes -over an underlying network with a standard MTU of 1500 bytes without -fragmentation. - -6in4 tunnel interfaces are frequently used by IPv6 tunnel brokers (such as -[Hurricane Electric]) to connect isolated IPv6 networks or individual hosts to -the IPv6 internet. - -Example: - -```none -set interfaces tunnel tun0 encapsulation sit -set interfaces tunnel tun0 source-address 192.0.2.10 -set interfaces tunnel tun0 remote 192.0.2.20 -set interfaces tunnel tun0 address 2001:db8:bb::1/64 -``` - -:::{seealso} -For a practical configuration example, see the -{ref}`Tunnelbroker.net (IPv6) ` section. -::: - -## Generic Routing Encapsulation (GRE) - -{abbr}`GRE (Generic Routing Encapsulation)` is a versatile encapsulation -protocol defined in RFC 2784. Unlike simpler protocols such as IPIP, it allows -both IPv4 and IPv6 to be transported through the same tunnel. - -{abbr}`GRE (Generic Routing Encapsulation)` encapsulates original data packets -by adding a {abbr}`GRE (Generic Routing Encapsulation)` header, followed by an -IP header (the delivery header). The delivery header uses IP protocol number 47 -to identify {abbr}`GRE (Generic Routing Encapsulation)`-encapsulated traffic. - -In VyOS, {abbr}`GRE (Generic Routing Encapsulation)` tunnels can be established -over both IPv4 (encapsulation `gre`) and IPv6 (encapsulation `ip6gre`) -transport networks. - -### Configuration - -To configure a {abbr}`GRE (Generic Routing Encapsulation)` tunnel, you need to -define a tunnel source IP address, a tunnel destination IP address, an -encapsulation type ({abbr}`GRE (Generic Routing Encapsulation)`), and a tunnel -interface IP address. - -Example: - -The following example shows how to configure an IPv4/IPv6-over-IPv6 {abbr}`GRE -(Generic Routing Encapsulation)` tunnel between a VyOS router and a Linux host -running `systemd-networkd`. - -**VyOS router:** - -```none -set interfaces tunnel tun101 address '2001:db8:feed:beef::1/126' -set interfaces tunnel tun101 address '192.168.5.1/30' -set interfaces tunnel tun101 encapsulation 'ip6gre' -set interfaces tunnel tun101 source-address '2001:db8:babe:face::3afe:3' -set interfaces tunnel tun101 remote '2001:db8:9bb:3ce::5' -``` - -**Linux** `systemd-networkd`: - -The `systemd-networkd` setup requires two configuration files: `xxx.netdev` -to create the {abbr}`GRE (Generic Routing Encapsulation)` tunnel interface, and -`xxx.network` to assign IP addresses to it. - -```none -# cat /etc/systemd/network/gre-example.netdev -[NetDev] -Name=gre-example -Kind=ip6gre -MTUBytes=14180 - -[Tunnel] -Remote=2001:db8:babe:face::3afe:3 - - -# cat /etc/systemd/network/gre-example.network -[Match] -Name=gre-example - -[Network] -Address=2001:db8:feed:beef::2/126 - -[Address] -Address=192.168.5.2/30 -``` - - -### GRE keys - -A GRE key is an optional 32-bit field in the GRE header that allows multiple -GRE tunnels to operate between the same source and destination endpoints. When -a packet arrives, the receiver checks the GRE key to determine which tunnel -interface should process it. - -Although it may sound security-related, the GRE key is only an identifier and -provides no encryption or data protection. - -Example: - -```none -set interfaces tunnel tun0 source-address 192.0.2.10 -set interfaces tunnel tun0 remote 192.0.2.20 -set interfaces tunnel tun0 address 10.40.50.60/24 -set interfaces tunnel tun0 parameters ip key 10 -``` - -```none -set interfaces tunnel tun1 source-address 192.0.2.10 -set interfaces tunnel tun1 remote 192.0.2.20 -set interfaces tunnel tun1 address 172.16.17.18/24 -set interfaces tunnel tun1 parameters ip key 20 -``` - - -### GRETAP - -Unlike GRE, which encapsulates only Layer 3 (IP) traffic, GRETAP encapsulates -Layer 2 (Ethernet) frames. - -That means that GRETAP tunnel interfaces can be members of a bridge interface. -This allows two geographically distant sites to connect as if they were on the -same LAN. - -GRETAP tunnels can be established over both IPv4 and IPv6 transport networks. - -Example: - -```none -set interfaces bridge br0 member interface eth0 -set interfaces bridge br0 member interface tun0 -set interfaces tunnel tun0 encapsulation gretap -set interfaces tunnel tun0 source-address 198.51.100.2 -set interfaces tunnel tun0 remote 203.0.113.10 -``` - - -### Troubleshooting - -GRE is a standardized tunneling protocol used in many network environments. - -Although the GRE tunnel setup is straightforward, connectivity failures -frequently occur because ACLs or firewall rules block IP protocol 47 or -prevent direct communication between the tunnel endpoints. - -If your GRE tunnel fails to establish, perform these diagnostic steps: - -1\. Verify that the remote peer is reachable from the configured -`source-address`. - -This ensures that the underlying physical path between the two endpoints is -functional. - -```none -vyos@vyos:~$ ping 203.0.113.10 interface 198.51.100.2 count 4 -PING 203.0.113.10 (203.0.113.10) from 198.51.100.2 : 56(84) bytes of data. -64 bytes from 203.0.113.10: icmp_seq=1 ttl=254 time=0.807 ms -64 bytes from 203.0.113.10: icmp_seq=2 ttl=254 time=1.50 ms -64 bytes from 203.0.113.10: icmp_seq=3 ttl=254 time=0.624 ms -64 bytes from 203.0.113.10: icmp_seq=4 ttl=254 time=1.41 ms - ---- 203.0.113.10 ping statistics --- -4 packets transmitted, 4 received, 0% packet loss, time 3007ms -rtt min/avg/max/mdev = 0.624/1.087/1.509/0.381 ms -``` - -2\. Verify that the tunnel interface is correctly configured (with the link type -set to GRE) and is actively processing traffic. - -```none -vyos@vyos:~$ show interfaces tunnel tun100 -tun100@NONE: mtu 1476 qdisc noqueue state UNKNOWN group default qlen 1000 - link/gre 198.51.100.2 peer 203.0.113.10 - inet 10.0.0.1/30 brd 10.0.0.3 scope global tun100 - valid_lft forever preferred_lft forever - inet6 fe80::5efe:c612:2/64 scope link - valid_lft forever preferred_lft forever - - RX: bytes packets errors dropped overrun mcast - 2183 27 0 0 0 0 - TX: bytes packets errors dropped carrier collisions - 836 9 0 0 0 0 -``` - -3\. Test the connection through the tunnel using the private IP addresses -assigned to each tunnel endpoint. - -```none -vyos@vyos:~$ ping 10.0.0.2 interface 10.0.0.1 count 4 -PING 10.0.0.2 (10.0.0.2) from 10.0.0.1 : 56(84) bytes of data. -64 bytes from 10.0.0.2: icmp_seq=1 ttl=255 time=1.05 ms -64 bytes from 10.0.0.2: icmp_seq=2 ttl=255 time=1.88 ms -64 bytes from 10.0.0.2: icmp_seq=3 ttl=255 time=1.98 ms -64 bytes from 10.0.0.2: icmp_seq=4 ttl=255 time=1.98 ms - ---- 10.0.0.2 ping statistics --- -4 packets transmitted, 4 received, 0% packet loss, time 3008ms -rtt min/avg/max/mdev = 1.055/1.729/1.989/0.395 ms -``` - -[hurricane electric]: https://tunnelbroker.net/ -[other proposals]: https://www.isc.org/othersoftware/ diff --git a/docs/configuration/interfaces/md-virtual-ethernet.md b/docs/configuration/interfaces/md-virtual-ethernet.md deleted file mode 100644 index dee1b332..00000000 --- a/docs/configuration/interfaces/md-virtual-ethernet.md +++ /dev/null @@ -1,119 +0,0 @@ ---- -lastproofread: '2026-01-26' ---- - -(virtual-ethernet)= - -# Virtual Ethernet - -Virtual Ethernet (veth) interfaces are software-based interfaces that operate -in pairs, creating a tunnel between each other. Traffic transmitted into one -interface of the pair (e.g., `veth0`) is delivered directly to its peer -interface (e.g., `veth1`). - -Veth interfaces are commonly used to connect network namespaces or VRFs, but -they can also function as standalone virtual network interfaces. - -:::{note} -Veth interfaces must be created in pairs, where each interface acts -as the peer of the other. -::: - -## Configuration - -### Common interface configuration - -```{cmdincludemd} /_include/interface-address-with-dhcp.txt -:var0: virtual-ethernet -:var1: veth0 -``` - -```{cmdincludemd} /_include/interface-description.txt -:var0: virtual-ethernet -:var1: veth0 -``` - - -### VLAN - -#### Regular VLANs (802.1q) - -```{cmdincludemd} /_include/interface-vlan-8021q.txt -:var0: virtual-ethernet -:var1: veth0 -``` - - -#### 802.1ad (QinQ) - -```{cmdincludemd} /_include/interface-vlan-8021ad.txt -:var0: virtual-ethernet -:var1: veth0 -``` - -```{cmdincludemd} /_include/interface-disable.txt -:var0: virtual-ethernet -:var1: veth0 -``` - -```{cmdincludemd} /_include/interface-vrf.txt -:var0: virtual-ethernet -:var1: veth0 -``` - - -## Operation - -```{opcmd} show interfaces virtual-ethernet - -Show brief interface information. - -:::{code-block} none -vyos@vyos:~$ show interfaces virtual-ethernet -Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down -Interface IP Address S/L Description ---------- ---------- --- ----------- -veth10 100.64.0.0/31 u/u -veth11 100.64.0.1/31 u/u -::: -``` - -```{opcmd} show interfaces virtual-ethernet \ - -Show detailed interface information. - -:::{code-block} none -vyos@vyos:~$ show interfaces virtual-ethernet veth11 -10: veth11@veth10: mtu 1500 qdisc noqueue master red state UP group default qlen 1000 -link/ether b2:7b:df:47:e9:11 brd ff:ff:ff:ff:ff:ff -inet 100.64.0.1/31 scope global veth11 -valid_lft forever preferred_lft forever -inet6 fe80::b07b:dfff:fe47:e911/64 scope link -valid_lft forever preferred_lft forever - -RX: bytes packets errors dropped overrun mcast -0 0 0 0 0 0 -TX: bytes packets errors dropped carrier collisions -1369707 4267 0 0 0 0 -::: -``` - - -## Example - -The following example shows how to connect the global VRF to VRF ‘red ‘ using -the `veth10` and `veth11` veth pair. - -```none -set interfaces virtual-ethernet veth10 address '100.64.0.0/31' -set interfaces virtual-ethernet veth10 peer-name 'veth11' -set interfaces virtual-ethernet veth11 address '100.64.0.1/31' -set interfaces virtual-ethernet veth11 peer-name 'veth10' -set interfaces virtual-ethernet veth11 vrf 'red' -set vrf name red table '1000' - -vyos@vyos:~$ ping 100.64.0.1 -PING 100.64.0.1 (100.64.0.1) 56(84) bytes of data. -64 bytes from 100.64.0.1: icmp_seq=1 ttl=64 time=0.080 ms -64 bytes from 100.64.0.1: icmp_seq=2 ttl=64 time=0.119 ms -``` diff --git a/docs/configuration/interfaces/md-vti.md b/docs/configuration/interfaces/md-vti.md deleted file mode 100644 index dbd2c88c..00000000 --- a/docs/configuration/interfaces/md-vti.md +++ /dev/null @@ -1,121 +0,0 @@ -(vti-interface)= - -# VTI (virtual tunnel interface) - -{abbr}`VTIs (virtual tunnel interfaces)` let you create secure, encrypted -tunnels between private networks or hosts across public infrastructure, such as -the Internet. They operate alongside an underlying IPsec tunnel, which handles -encapsulation and encryption, while VTIs function exclusively as routing -interfaces. - -## Configuration - -### Common interface configuration - -```{cmdincludemd} /_include/interface-address.txt -:var0: vti -:var1: vti0 -``` - -```{cmdincludemd} /_include/interface-description.txt -:var0: vti -:var1: vti0 -``` - -```{cmdincludemd} /_include/interface-disable.txt -:var0: vti -:var1: vti0 -``` - -```{cmdincludemd} /_include/interface-ip.txt -:var0: vti -:var1: vti0 -``` - -```{cmdincludemd} /_include/interface-ipv6.txt -:var0: vti -:var1: vti0 -``` - -```{cmdincludemd} /_include/interface-mtu.txt -:var0: vti -:var1: vti0 -``` - -```{cfgcmd} set interfaces vti \ mirror egress \ - -Configure mirroring of outgoing traffic from the specified VTI to the -designated monitor interface. -``` - -```{cfgcmd} set interfaces vti \ mirror ingress \ - -Configure mirroring of incoming traffic from the specified VTI to the -designated monitor interface. -``` - -```{cfgcmd} set interfaces vti \ redirect \ - -Enable redirection of incoming packets to the specified interface. -``` - -```{cmdincludemd} /_include/interface-vrf.txt -:var0: vti -:var1: vti0 -``` - - -## Operation - -```{opcmd} show interfaces vti \ - -Show the operational status and traffic statistics for the specified VTI. -``` - -```{opcmd} show interfaces vti \ brief - -Show a brief operational status summary for the specified VTI. -``` - - -## Example - -**Configure a VTI** - -Assign IPv4 and IPv6 addresses to the VTI, along with a brief description: - -```none -set interfaces vti vti0 address 192.168.2.249/30 -set interfaces vti vti0 address 2001:db8:2::249/64 -set interfaces vti vti0 description "Description" -``` - -Resulting configuration: - -```none -vyos@vyos# show interfaces vti -vti vti0 { - address 192.168.2.249/30 - address 2001:db8:2::249/64 - description "Description" -} -``` - -:::{warning} -When configuring site-to-site IPsec with VTIs, ensure that route -autoinstall is disabled. -::: - -```none -set vpn ipsec options disable-route-autoinstall -``` - -For more information about the IPsec and VTI issue, as well as the -`disable-route-autoinstall` option, see: - - -The root cause of the problem is that VTI tunnels require their traffic -selectors to be set to `0.0.0.0/0` for traffic to match the tunnel, even -though routing decisions are based on netfilter marks. Unless route insertion -is explicitly disabled, strongSWAN incorrectly inserts a default route through -the VTI peer address, causing all traffic to be misrouted. diff --git a/docs/configuration/interfaces/md-vxlan.md b/docs/configuration/interfaces/md-vxlan.md deleted file mode 100644 index 8dae75ff..00000000 --- a/docs/configuration/interfaces/md-vxlan.md +++ /dev/null @@ -1,373 +0,0 @@ ---- -lastproofread: '2026-03-16' ---- - -(vxlan-interface)= - -# VXLAN - -{abbr}`VXLAN (Virtual Extensible LAN)` is a network virtualization technology -that addresses scalability challenges in large cloud computing environments. -It encapsulates Ethernet frames (Layer 2) within UDP datagrams (Layer 4), which -are then transmitted via UDP port 4789, as assigned by IANA. VXLAN endpoints, -called {abbr}`VTEPs (VXLAN tunnel endpoints)`, terminate VXLAN tunnels and can -be either virtual or physical switch ports. - -VXLAN supports up to 16 million logical networks and enables Layer 2 adjacency -across Layer 3 IP networks. It uses multicast or unicast with head-end -replication (HER) to flood broadcast, unknown unicast, and multicast (BUM) -traffic. - -The VXLAN specification was initially developed by VMware, Arista Networks, and -Cisco. Other supporters include Huawei, Broadcom, Citrix, Pica8, Big Switch -Networks, Cumulus Networks, Dell EMC, Ericsson, Mellanox, FreeBSD, OpenBSD, Red -Hat, Joyent, and Juniper Networks. - -VXLAN is officially documented by the IETF in {rfc}`7348`. - -When configuring VXLAN in a VyOS virtual machine, ensure that MAC spoofing -(Hyper-V) or Forged Transmits (ESX) are permitted. Otherwise, the hypervisor -may block forwarded frames. - -:::{note} -Although the IANA-assigned VXLAN port is **4789**, VyOS uses the -Linux default UDP port **8472** for VXLAN interfaces. To ensure compatibility -with other vendors, set the port to the IANA standard **4789**. -::: - -## Configuration - -### Common interface configuration - -```{cmdincludemd} /_include/interface-common-without-dhcp.txt -:var0: vxlan -:var1: vxlan0 -``` - - -### VXLAN-specific options - -```{cfgcmd} set interfaces vxlan \ vni \ - -**Configure a** {abbr}`VNI (VXLAN Network Identifier)` **for the VXLAN -interface.** - -Each VXLAN segment is identified by this 24-bit VNI, allowing up to 16 million -segments to coexist within the same administrative domain. -``` - -```{cfgcmd} set interfaces vxlan \ port \ - -Configure the UDP port of the remote VXLAN endpoint. - -:::{note} -Although the IANA-assigned VXLAN port is **4789**, VyOS uses the -Linux default UDP port **8472** for VXLAN interfaces. -::: -``` - -```{cfgcmd} set interfaces vxlan \ source-address \ - -Configure the source IP address for the VXLAN underlay. - -:::{warning} -This setting is mandatory when deploying VXLAN via L2VPN/EVPN. -::: -``` - -```{cfgcmd} set interfaces vxlan \ gpe - -**Enable the** {abbr}`GPE (Generic Protocol Extension)` **for the VXLAN -interface.** - -To use this feature, you must configure the interface with the ``external`` -parameter. -``` - -```{cfgcmd} set interfaces vxlan \ parameters external - -**Configure the VXLAN interface to use an external control plane, such as BGP -L2VPN/EVPN, for remote endpoint discovery.** - -If not configured, the internal {abbr}`FDB (Forwarding Database)` is used. -``` - -```{cfgcmd} set interfaces vxlan \ parameters neighbor-suppress - -**Enable ARP and ND suppression on the VXLAN interface.** - -This reduces ARP and ND message flooding across the VXLAN network. As defined -in {rfc}`7432#section-10`, participating VTEPs use known MAC-to-IP bindings -to reply to local requests on behalf of remote hosts. -``` - -```{cfgcmd} set interfaces vxlan \ parameters nolearning - -Disable {abbr}`SLLA (Source Link-Layer Address)` and IP address learning on -the VXLAN interface. -``` - -```{cfgcmd} set interfaces vxlan \ parameters vni-filter - -**Enable** {abbr}`VNI (VXLAN Network Identifier)` **filtering on the VXLAN -interface.** - -When enabled, the interface only receives packets with VNIs configured in its -VNI filtering table. - -:::{note} -VNI filtering works only if the interface is configured with the -``external`` parameter. -::: -``` - - -#### Unicast - -```{cfgcmd} set interfaces vxlan \ remote \ - -**Configure the IPv4 or IPv6 address of the remote VTEP.** - -Unlike multicast setups, this command allows you to directly configure the -remote IPv4 or IPv6 address. -``` - - -#### Multicast - -```{cfgcmd} set interfaces vxlan \ source-interface \ - -**Configure the source interface for the VXLAN underlay.** - -All VXLAN traffic is sent and received through the specified interface. -This setting is mandatory when deploying VXLAN over a multicast network. -``` - -```{cfgcmd} set interfaces vxlan \ group \ - -**Configure the IPv4 or IPv6 multicast group address for the VXLAN interface.** - -VXLAN tunnels can be built using either multicast group or unicast IP addresses. -``` - - -## Multicast VXLAN - -Topology: PC4 - Leaf2 - Spine1 - Leaf3 - PC5 - -PC4 uses the IP address `10.0.0.4/24`, and PC5 uses the IP address -`10.0.0.5/24`. Both devices assume they reside within the same broadcast -domain. - -Assume PC4 on Leaf2 pings PC5 on Leaf3. Rather than manually specifying Leaf3 -as the remote endpoint, Leaf2 encapsulates the packet into a UDP datagram and -sends it to the designated multicast address via Spine1. Spine1 forwards the -packet to all leaves in the same multicast group, including Leaf3. Upon -receiving the datagram, Leaf3 forwards it to PC5 and learns that PC4 is -reachable through Leaf2 by inspecting the source IP in the encapsulated -datagram. - -PC5 receives the ping and responds with an echo reply. Leaf3, now aware of -PC4's location, forwards the reply directly to Leaf2's unicast address. Upon -receiving the echo reply, Leaf2 learns that PC5 is reachable through Leaf3. - -After this discovery, subsequent traffic between PC4 and PC5 will not use the -multicast address between the leaves, as both leaves have learned the PCs' -locations. This reduces multicast traffic and network load, improving -scalability as more leaves are added. - -## Single VXLAN device (SVD) - -In VyOS, you can configure multiple **VLAN-to-VNI mappings** for EVPN-VXLAN on -a single container interface, known as a single VXLAN device (SVD). This -enables significant VNI scaling because a separate VXLAN interface is not -required for each VNI. - -```{cfgcmd} set interfaces vxlan \ vlan-to-vni \ vni \ - -**Map a VLAN ID to a VNI on the specified VXLAN interface.** - -The VXLAN interface can be added to a bridge. - -The following example shows an SVD configuration with multiple VLAN-to-VNI -mappings. - -:::{code-block} none -set interfaces bridge br0 member interface vxlan0 -set interfaces vxlan vxlan0 parameters external -set interfaces vxlan vxlan0 source-interface 'dum0' -set interfaces vxlan vxlan0 vlan-to-vni 10 vni '10010' -set interfaces vxlan vxlan0 vlan-to-vni 11 vni '10011' -set interfaces vxlan vxlan0 vlan-to-vni 30 vni '10030' -set interfaces vxlan vxlan0 vlan-to-vni 31 vni '10031' -::: -``` - - -### Example - -The following example demonstrates a multicast VXLAN deployment. - -The setup includes three routers: Spine1, a Cisco IOS router, and Leaf2 and -Leaf3, which are VyOS routers. - -**Topology:** Leaf2 - Spine1 - Leaf3. - -The topology is built using GNS3. - -```none -Spine1: -fa0/2 towards Leaf2, IP-address: 10.1.2.1/24 -fa0/3 towards Leaf3, IP-address: 10.1.3.1/24 - -Leaf2: -Eth0 towards Spine1, IP-address: 10.1.2.2/24 -Eth1 towards a VLAN-aware switch - -Leaf3: -Eth0 towards Spine1, IP-address 10.1.3.3/24 -Eth1 towards a VLAN-aware switch -``` - -**Spine1 configuration:** - -```none -conf t -ip multicast-routing -! -interface fastethernet0/2 - ip address 10.1.2.1 255.255.255.0 - ip pim sparse-dense-mode -! -interface fastethernet0/3 - ip address 10.1.3.1 255.255.255.0 - ip pim sparse-dense-mode -! -router ospf 1 - network 10.0.0.0 0.255.255.255 area 0 -``` - -Multicast routing is required for scalable traffic forwarding between leaves. -{abbr}`PIM (Protocol Independent Multicast)` must be enabled towards the leaves -so the spine can learn from which multicast groups each leaf expects traffic. - -**Leaf2 configuration:** - -```none -set interfaces ethernet eth0 address '10.1.2.2/24' -set protocols ospf area 0 network '10.0.0.0/8' - -! First VXLAN interface -set interfaces bridge br241 address '172.16.241.1/24' -set interfaces bridge br241 member interface 'eth1.241' -set interfaces bridge br241 member interface 'vxlan241' - -set interfaces vxlan vxlan241 group '239.0.0.241' -set interfaces vxlan vxlan241 source-interface 'eth0' -set interfaces vxlan vxlan241 vni '241' - -! Second VXLAN interface -set interfaces bridge br242 address '172.16.242.1/24' -set interfaces bridge br242 member interface 'eth1.242' -set interfaces bridge br242 member interface 'vxlan242' - -set interfaces vxlan vxlan242 group '239.0.0.242' -set interfaces vxlan vxlan242 source-interface 'eth0' -set interfaces vxlan vxlan242 vni '242' -``` - -**Leaf3 configuration:** - -```none -set interfaces ethernet eth0 address '10.1.3.3/24' -set protocols ospf area 0 network '10.0.0.0/8' - -! First VXLAN interface -set interfaces bridge br241 address '172.16.241.1/24' -set interfaces bridge br241 member interface 'eth1.241' -set interfaces bridge br241 member interface 'vxlan241' - -set interfaces vxlan vxlan241 group '239.0.0.241' -set interfaces vxlan vxlan241 source-interface 'eth0' -set interfaces vxlan vxlan241 vni '241' - -! Second VXLAN interface -set interfaces bridge br242 address '172.16.242.1/24' -set interfaces bridge br242 member interface 'eth1.242' -set interfaces bridge br242 member interface 'vxlan242' - -set interfaces vxlan vxlan242 group '239.0.0.242' -set interfaces vxlan vxlan242 source-interface 'eth0' -set interfaces vxlan vxlan242 vni '242' -``` - -The configurations for Leaf2 and Leaf3 are nearly identical. Detailed -explanations for each command are provided below. - -```none -set interfaces bridge br241 address '172.16.241.1/24' -``` - -This command creates a bridge to bind traffic on `eth1` VLAN 241 with the -`vxlan241` interface. The IP address is optional. If configured, it can serve -as the default gateway for each leaf, allowing devices on the VLAN to reach -other subnets. Subnets must be redistributed by {abbr}`OSPF (Open Shortest Path -First)` so the spine can learn how to reach them. To advertise `172.16/12` -networks, change the {abbr}`OSPF (Open Shortest Path First)` network from -`10.0.0.0/8` to `0.0.0.0/0`. - -```none -set interfaces bridge br241 member interface 'eth1.241' -set interfaces bridge br241 member interface 'vxlan241' -``` - -These commands bind `eth1.241` and `vxlan241` as member interfaces of the -same bridge. - -```none -set interfaces vxlan vxlan241 group '239.0.0.241' -``` - -This command configures the multicast group used by all leaves for this VLAN -extension. It must be the same on all leaves that have this interface. - -```none -set interfaces vxlan vxlan241 source-interface 'eth0' -``` - -This command configures the interface that listens for multicast packets. It -can also be a loopback interface. - -```none -set interfaces vxlan vxlan241 vni '241' -``` - -This command configures the unique ID for the VXLAN interface. - -```none -set interfaces vxlan vxlan241 port 12345 -``` - -VyOS uses the Linux default UDP port **8472** for VXLAN interfaces. This -command allows you to configure a different UDP port. - -## Unicast VXLAN - -As an alternative to multicast, you can configure the VXLAN tunnel by -specifying the remote IPv4 address directly. The following updates the previous -multicast example: - -```none -# leaf2 and leaf3 -delete interfaces vxlan vxlan241 group '239.0.0.241' -delete interfaces vxlan vxlan241 source-interface 'eth0' - -# leaf2 -set interfaces vxlan vxlan241 remote 10.1.3.3 - -# leaf3 -set interfaces vxlan vxlan241 remote 10.1.2.2 -``` - -The default UDP port is 8472. To configure a different port, use `set -interfaces vxlan port `. diff --git a/docs/configuration/interfaces/md-wireguard.md b/docs/configuration/interfaces/md-wireguard.md deleted file mode 100644 index 121d1df0..00000000 --- a/docs/configuration/interfaces/md-wireguard.md +++ /dev/null @@ -1,434 +0,0 @@ ---- -lastproofread: '2026-03-02' ---- - -(wireguard)= - -# WireGuard - -WireGuard is an extremely simple, fast, and modern VPN that utilizes -state-of-the-art cryptography. See for more -information. - -## Site-to-site VPN - -The following diagram illustrates a site-to-site VPN setup. - -:::{figure} /_static/images/wireguard_site2site_diagram.webp -::: - -## Keypairs - -WireGuard requires a keypair, which includes a **private** key -to decrypt incoming traffic, and a **public** key for peer(s) to encrypt -outgoing traffic. - -### Generate keypair - -```{opcmd} generate pki wireguard key-pair - -Generate a keypair: a public and a private key. - -:::{note} -This command only outputs the keys to your console. It neither stores -them in the system nor applies them to the system configuration. -::: - -:::{code-block} none -vyos@vyos:~$ generate pki wireguard key-pair -Private key: iJJyEARGK52Ls1GYRCcFvPuTj7WyWYDo//BknoDU0XY= -Public key: EKY0dxRrSD98QHjfHOK13mZ5PJ7hnddRZt5woB3szyw= -::: -``` - - -```{opcmd} generate pki wireguard key-pair install interface \ - -Generate a keypair and output the private key assignment command for the -specified interface. - -:::{code-block} none -vyos@vyos:~$ generate pki wireguard key-pair install interface wg10 -"generate" CLI command executed from operational level. -Generated private key is not automatically added to the VyOS configuration, use the following configuration mode commands to install key: - -set interfaces wireguard wg10 private-key '4Krkv8h6NkAYMMaBWI957yYDJDMvj9URTHstdlOcDU0=' - -Corresponding public-key to use on peer system is: 'UxDsYT6EnpTIOKUzvMlw2p0sNOKQvFxEdSVrnNrX1Ro=' -::: - -:::{note} -If you invoke this command from configuration mode with the ``run`` -prefix, the generated private key is automatically assigned to the specified -interface. -::: - -:::{code-block} none -vyos@vyos# run generate pki wireguard key-pair install interface wg10 -"generate" CLI command executed from config session. -Generated private-key was imported to CLI! - -Use the following command to verify: show interfaces wireguard wg10 -Corresponding public-key to use on peer system is: '7d9KwabjLhHpJiEJeIGd0CBlao/eTwFOh6xyCovTfG8=' - -vyos@vyos# compare -[edit interfaces] -+wireguard wg10 { -+ private-key CJweb8FC6BU3Loj4PC2pn5V82cDjIPs7G1saW0ZfLWc= -+} -::: -``` - - -```{opcmd} show interfaces wireguard \ public-key - -Show the public key assigned to the interface. - -:::{code-block} none -vyos@vyos:~$ show interfaces wireguard wg01 public-key -EKY0dxRrSD98QHjfHOK13mZ5PJ7hnddRZt5woB3szyw= -::: -``` - -#### Optional - -```{opcmd} generate pki wireguard preshared-key - -Generate a pre-shared key. - -The pre-shared key is optional. It adds an additional layer of symmetric-key -cryptography on top of the asymmetric cryptography. - -:::{code-block} none -vyos@vyos:~$ generate pki wireguard preshared-key -Pre-shared key: OHH2EwZfMNK+1L6BXbYw3bKCtMrfjpR4mCAEeBlFnRs= -::: -``` - -```{opcmd} generate pki wireguard preshared-key install interface \ peer \ - -Generate a pre-shared key and output the key assignment command for the -specified peer. - -:::{code-block} none -vyos@vyos:~$ generate pki wireguard preshared-key install interface wg10 peer foo -"generate" CLI command executed from operational level. -Generated preshared-key is not stored to CLI, use configure mode commands to install key: - -set interfaces wireguard wg10 peer foo preshared-key '32vQ1w1yFKTna8n7Gu7EimubSe2Y63m8bafz55EG3Ro=' - -Pre-shared key: +LuaZ8W6DjsDFJFX3jJzoNqrsXHhvq08JztM9z8LHCs= -::: - -:::{note} -If you invoke this command from configuration mode with the run -prefix, the generated key is automatically assigned to the specified peer. -::: -``` - -## Interface configuration - -The next step is to configure your local WireGuard interface and define the -networks you want to tunnel (`allowed-ips`). - -If your system only initiates connections, specifying the listen port is -optional. If your system accepts incoming connections, you must define a port -for peers to connect to. Otherwise, WireGuard selects a random port at each -reboot, and that may break your peers' ability to connect if that port is not enabled in your firewall rules. - -To configure a WireGuard tunnel, you also need your peer's public key. - -:::{note} -The public key specified in the peer configuration block is always -the **remote** peer's public key, never your local one. -::: - -**Local side configuration** - -The local side is configured with the following parameters: -- Local WireGuard interface IP: `10.1.0.1/30` -- Local listen port: `51820` -- Remote peer name: `to-wg02` -- Remote peer endpoint: `192.0.2.1` on port `51820` -- Remote peer public key: `XMrlPykaxhdAAiSjhtPlvi30NVkvLQliQuKP7AI7CyI=` -- Allowed networks: `192.168.2.0/24` - -```none -set interfaces wireguard wg01 address '10.1.0.1/30' -set interfaces wireguard wg01 description 'VPN-to-wg02' -set interfaces wireguard wg01 peer to-wg02 allowed-ips '192.168.2.0/24' -set interfaces wireguard wg01 peer to-wg02 address '192.0.2.1' -set interfaces wireguard wg01 peer to-wg02 port '51820' -set interfaces wireguard wg01 peer to-wg02 public-key 'XMrlPykaxhdAAiSjhtPlvi30NVkvLQliQuKP7AI7CyI=' -set interfaces wireguard wg01 port '51820' - -set protocols static route 192.168.2.0/24 interface wg01 -``` - -To send traffic destined for `192.168.2.0/24` through the WireGuard interface -(`wg01`), configure a static route. Multiple IP addresses or networks can be -defined and routed. The final check is performed against `allowed-ips`, which -either permits or drops the traffic. - -:::{warning} -You cannot assign the same `allowed-ips` to multiple WireGuard -peers. This is a strict design restriction. For more information, check the -[WireGuard mailing list]. -::: - -```{cfgcmd} set interfaces wireguard \ private-key \ - -Assign a private key to the specified WireGuard interface. - -Example: - -:::{code-block} none -set interfaces wireguard wg01 private-key 'iJJyEARGK52Ls1GYRCcFvPuTj7WyWYDo//BknoDU0XY=' -::: - -To generate a private key, use the following command: -{opcmd}`generate pki wireguard key-pair`. - -To view the public key assigned to the interface so you can share it with a -peer, use the following command: -{opcmd}`show interfaces wireguard wg01 public-key`. -``` - - -```{cmdincludemd} /_include/interface-per-client-thread.txt -:var0: wireguard -:var1: wg01 -``` - -**Remote side configuration** - -```none -set interfaces wireguard wg01 address '10.1.0.2/30' -set interfaces wireguard wg01 description 'VPN-to-wg01' -set interfaces wireguard wg01 peer to-wg01 allowed-ips '192.168.1.0/24' -set interfaces wireguard wg01 peer to-wg01 address '192.0.2.2' -set interfaces wireguard wg01 peer to-wg01 port '51820' -set interfaces wireguard wg01 peer to-wg01 public-key 'EKY0dxRrSD98QHjfHOK13mZ5PJ7hnddRZt5woB3szyw=' -set interfaces wireguard wg01 port '51820' -set interfaces wireguard wg01 private-key 'OLTQY3HuK5qWDgVs6fJR093SwPgOmCKkDI1+vJLGoFU=' - -set protocols static route 192.168.1.0/24 interface wg01 -``` - -## Firewall exceptions - - -To allow WireGuard traffic through the WAN interface, create a firewall -exception: - -```none -set firewall ipv4 name OUTSIDE_LOCAL rule 10 action accept -set firewall ipv4 name OUTSIDE_LOCAL rule 10 description 'Allow established/related' -set firewall ipv4 name OUTSIDE_LOCAL rule 10 state established enable -set firewall ipv4 name OUTSIDE_LOCAL rule 10 state related enable -set firewall ipv4 name OUTSIDE_LOCAL rule 20 action accept -set firewall ipv4 name OUTSIDE_LOCAL rule 20 description WireGuard_IN -set firewall ipv4 name OUTSIDE_LOCAL rule 20 destination port 51820 -set firewall ipv4 name OUTSIDE_LOCAL rule 20 log enable -set firewall ipv4 name OUTSIDE_LOCAL rule 20 protocol udp -``` - -Ensure that the OUTSIDE_LOCAL firewall group is applied to the WAN interface -and in an input (local) direction. - -```none -set firewall ipv4 input filter rule 10 action jump -set firewall ipv4 input filter rule 10 jump-target 'OUTSIDE_LOCAL' -set firewall ipv4 input filter rule 10 inbound-interface name 'eth0' -``` - -Verify that your firewall rules permit traffic. If so, your WireGuard VPN -should be operational. - -```none -wg01# ping 192.168.1.1 -PING 192.168.1.1 (192.168.1.1) 56(84) bytes of data. -64 bytes from 192.168.1.1: icmp_seq=1 ttl=64 time=1.16 ms -64 bytes from 192.168.1.1: icmp_seq=2 ttl=64 time=1.77 ms - -wg02# ping 192.168.2.1 -PING 192.168.2.1 (192.168.2.1) 56(84) bytes of data. -64 bytes from 192.168.2.1: icmp_seq=1 ttl=64 time=4.40 ms -64 bytes from 192.168.2.1: icmp_seq=2 ttl=64 time=1.02 ms -``` - -An additional layer of symmetric-key cryptography can be used on top of the -asymmetric cryptography. This is optional. - -```none -vyos@vyos:~$ generate pki wireguard preshared-key -Pre-shared key: rvVDOoc2IYEnV+k5p7TNAmHBMEGTHbPU8Qqg8c/sUqc= -``` - -Copy the key, as it is not stored locally. Since it is a symmetric key, only -you and your peer should know its contents. Distribute the key securely. - -```none -wg01# set interfaces wireguard wg01 peer to-wg02 preshared-key 'rvVDOoc2IYEnV+k5p7TNAmHBMEGTHbPU8Qqg8c/sUqc=' -wg02# set interfaces wireguard wg01 peer to-wg01 preshared-key 'rvVDOoc2IYEnV+k5p7TNAmHBMEGTHbPU8Qqg8c/sUqc=' -``` - -## Remote access (road warrior) - - -With WireGuard, a road warrior VPN configuration is similar to a site-to-site -VPN. It just omits the `address` and `port` statements. - - -In the following example, the IP addresses for remote clients are defined -within each peer configuration. This allows peers to communicate with each -other. - - -Additionally, this setup uses a `persistent-keepalive` flag set to 15 seconds -to keep the connection alive. This setting is mainly relevant if a peer is -behind NAT and cannot be reached if the connection is lost. For effectiveness, -the value should be lower than the UDP timeout. - -```none -wireguard wg01 { - address 10.172.24.1/24 - address 2001:db8:470:22::1/64 - description RoadWarrior - peer MacBook { - allowed-ips 10.172.24.30/32 - allowed-ips 2001:db8:470:22::30/128 - persistent-keepalive 15 - pubkey F5MbW7ye7DsoxdOaixjdrudshjjxN5UdNV+pGFHqehc= - } - peer iPhone { - allowed-ips 10.172.24.20/32 - allowed-ips 2001:db8:470:22::20/128 - persistent-keepalive 15 - pubkey BknHcLFo8nOo8Dwq2CjaC/TedchKQ0ebxC7GYn7Al00= - } - port 2224 - private-key OLTQY3HuK5qWDgVs6fJR093SwPgOmCKkDI1+vJLGoFU= -} -``` - -Below is the configuration for the iPhone peer. The `AllowedIPs` wildcard -setting directs all IPv4 and IPv6 traffic through the VPN connection. - -```none -[Interface] -PrivateKey = ARAKLSDJsadlkfjasdfiowqeruriowqeuasdf= -Address = 10.172.24.20/24, 2001:db8:470:22::20/64 -DNS = 10.0.0.53, 10.0.0.54 - -[Peer] -PublicKey = RIbtUTCfgzNjnLNPQ/ulkGnnB2vMWHm7l2H/xUfbyjc= -AllowedIPs = 0.0.0.0/0, ::/0 -Endpoint = 192.0.2.1:2224 -PersistentKeepalive = 15 -``` - -To enable split tunneling, specify the remote subnets. This ensures that only -traffic destined for the remote site is sent through the tunnel, while all -other traffic remains unaffected. - -```none -[Interface] -PrivateKey = 8Iasdfweirousd1EVGUk5XsT+wYFZ9mhPnQhmjzaJE6Go= -Address = 10.172.24.30/24, 2001:db8:470:22::30/64 - -[Peer] -PublicKey = RIbtUTCfgzNjnLNPQ/ulkGnnB2vMWHm7l2H/xUfbyjc= -AllowedIPs = 10.172.24.30/24, 2001:db8:470:22::/64 -Endpoint = 192.0.2.1:2224 -PersistentKeepalive = 15 -``` - -## Operational commands - - -### Status - -```{opcmd} show interfaces wireguard wg01 summary - -Show information about the WireGuard service, including the latest handshake. - -:::{code-block} none -vyos@vyos:~$ show interfaces wireguard wg01 summary -interface: wg01 -public key: -private key: (hidden) -listening port: 51820 - -peer: -endpoint: -allowed ips: 10.69.69.2/32 -latest handshake: 23 hours, 45 minutes, 26 seconds ago -transfer: 1.26 MiB received, 6.47 MiB sent -::: -``` - - -```{opcmd} show interfaces wireguard - -Show a list of all WireGuard interfaces. - -:::{code-block} none -Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down -Interface IP Address S/L Description ---------- ---------- --- ----------- -wg01 10.0.0.1/24 u/u -::: -``` - -```{opcmd} show interfaces wireguard \ - -Show general information about a specific WireGuard interface. - -:::{code-block} none -vyos@vyos:~$ show interfaces wireguard wg01 -interface: wg01 -address: 10.0.0.1/24 -public key: h1HkYlSuHdJN6Qv4Hz4bBzjGg5WUty+U1L7DJsZy1iE= -private key: (hidden) -listening port: 41751 -RX: bytes packets errors dropped overrun mcast -0 0 0 0 0 0 -TX: bytes packets errors dropped carrier collisions -0 0 0 0 0 0 -::: -``` - -## Remote access (road warrior) clients - -Some users connect mobile devices to their VyOS router using WireGuard. To -simplify deployment, generate a per-mobile configuration from the VyOS CLI. - -:::{warning} -From a security perspective, it is not recommended to let a third -party create and share the private key for a secure connection. You should -create the private portion yourself and hand out only the public key. -::: - -```{opcmd} generate wireguard client-config \ interface \ server \ address \ - -**Generate a client configuration file that establishes a connection to the -specified interface.** - -The public key from the specified interface is automatically included in the -configuration file. - -The command also generates a configuration snippet that can be copied into the -VyOS CLI. The ```` you provide will be used as the peer name in the -snippet. - -You must also specify the IP address or FQDN of the server the client connects -to. The address parameter can be used twice to assign both an IPv4 (/32) and -an IPv6 (/128) address to the client. - -:::{figure} /_static/images/wireguard_qrcode.webp -:alt: WireGuard Client QR code -::: -``` - -[wireguard mailing list]: https://lists.zx2c4.com/pipermail/wireguard/2018-December/003704.html diff --git a/docs/configuration/interfaces/md-wireless.md b/docs/configuration/interfaces/md-wireless.md deleted file mode 100644 index 9e6b7c99..00000000 --- a/docs/configuration/interfaces/md-wireless.md +++ /dev/null @@ -1,923 +0,0 @@ ---- -lastproofread: '2026-03-23' ---- - -(wireless-interface)= - -# Wireless LAN / Wi-Fi - -{abbr}`WLAN (Wireless LAN)` interfaces provide 802.11 (a/b/g/n/ac) wireless -connectivity, referred to as Wi-Fi, and operate in one of the following -modes: - -- {abbr}`WAP (Wireless Access-Point)` mode provides network access to connecting - stations if the physical hardware supports acting as a WAP -- Station mode acts as a Wi-Fi client accessing the network through an available - WAP -- Monitor mode lets the system passively monitor wireless traffic - -If the system detects an unconfigured wireless device, it will be automatically -added to the configuration tree, specifying any detected settings (for example, -its MAC address) and configured to run in monitor mode. - -## Configuration - -### Common interface configuration - -```{cmdincludemd} /_include/interface-common-with-dhcp.txt -:var0: wireless -:var1: wlan0 -``` - - -### System-wide configuration - -```{cfgcmd} set system wireless country-code \ - -Country code (ISO/IEC 3166-1). Used to set regulatory domain. Set as needed -to indicate country in which device is operating. This can limit available -channels and transmit power. - -:::{note} -This option is mandatory in ``access-point`` mode. -::: -``` - - -### Wireless options - -```{cfgcmd} set interfaces wireless \ channel \ - -Configure the IEEE 802.11 wireless radio channel for the interface. -Channel allocation depends on the frequency band: -* **2.4 GHz** (802.11b/g/n/ax): Channels range from 1 to 14. -* **5 GHz** (802.11a/h/j/n/ac/ax): Channels range from 34 to 177. -* **6 GHz** (802.11ax): Channels range from 1 to 233. -* **Automatic channel selection:** 0. -``` - -```{cfgcmd} set interfaces wireless \ disable-broadcast-ssid - -Send empty SSID in beacons and ignore probe request frames that do not specify -full SSID, i.e., require stations to know the SSID. -``` - -```{cfgcmd} set interfaces wireless \ expunge-failing-stations - -Disassociate stations based on excessive transmission failures or other -indications of connection loss. - -This depends on the driver capabilities and may not be available with all -drivers. -``` - -```{cfgcmd} set interfaces wireless \ isolate-stations - -Client isolation can be used to prevent low-level bridging of frames between -associated stations in the BSS. - -By default, this bridging is allowed. -``` - -```{cfgcmd} set interfaces wireless \ max-stations \ - -Maximum number of stations allowed in station table. New stations will be -rejected after the station table is full. IEEE 802.11 has a limit of 2007 -different association IDs, so this number should not be larger than that. - -This defaults to 2007. -``` - -```{cfgcmd} set interfaces wireless \ mgmt-frame-protection - -Management Frame Protection (MFP) according to IEEE 802.11w - -:::{note} -{abbr}`MFP (Management Frame Protection)` is required for WPA3. -::: -``` - -```{cfgcmd} set interfaces wireless \ enable-bf-protection - -Beacon Protection: management frame protection for Beacon frames. - -:::{note} -This option requires {abbr}`MFP (Management Frame Protection)` -to be enabled. -::: -``` - -```{cfgcmd} set interfaces wireless \ mode \ - -Operation mode of wireless radio. -* ``a`` - 802.11a - 54 Mbits/sec -* ``b`` - 802.11b - 11 Mbits/sec -* ``g`` - 802.11g - 54 Mbits/sec (default) -* ``n`` - 802.11n - 600 Mbits/sec -* ``ac`` - 802.11ac - 1300 Mbits/sec -* ``ax`` - 802.11ax - exceeds 1GBit/sec - -:::{note} -In VyOS, 802.11ax is only implemented for 2.4GHz and 6GHz. -::: -``` - -```{cfgcmd} set interfaces wireless \ physical-device \ - -Wireless hardware device used as underlay radio. - -This defaults to phy0. -``` - -```{cfgcmd} set interfaces wireless \ reduce-transmit-power \ - -Adds the Power Constraint information element to Beacon and Probe Response -frames. - -This option adds the Power Constraint information element when applicable -and the Country information element is configured. The Power Constraint -element is required by Transmit Power Control. - -Valid values are 0..255. -``` - -```{cfgcmd} set interfaces wireless \ ssid \ - -SSID to be used in IEEE 802.11 management frames -``` - -```{cfgcmd} set interfaces wireless \ type \ - -Wireless device type for this interface -* ``access-point``: Forwards packets between other nodes. -* ``station``: Connects to another {abbr}`AP (Access Point)`. -* ``monitor``: Passively monitors all packets on the frequency/channel. -``` - -```{cmdincludemd} /_include/interface-per-client-thread.txt -:var0: wireless -:var1: wlan0 -``` - - -#### PPDU - -```{cfgcmd} set interfaces wireless \ capabilities require-ht - -``` -```{cfgcmd} set interfaces wireless \ capabilities require-vht -``` - -```{cfgcmd} set interfaces wireless \ capabilities require-he -``` - -##### HT (High Throughput) capabilities (802.11n) - -> Configuring HT mode options is required when using 802.11n or -> 802.11ax at 2.4GHz. - -```{cfgcmd} set interfaces wireless \ capabilities ht 40mhz-incapable - -Device is incapable of 40 MHz, do not advertise. This sets ``[40-INTOLERANT]`` -``` - -```{cfgcmd} set interfaces wireless \ capabilities ht auto-powersave - -WMM-PS Unscheduled Automatic Power Save Delivery [U-APSD] -``` - -```{cfgcmd} set interfaces wireless \ capabilities ht channel-set-width \ - -Supported channel width set. -* ``ht20`` - 20 MHz channel width -* ``ht40-`` - Both 20 MHz and 40 MHz with secondary channel below the primary -channel -* ``ht40+`` - Both 20 MHz and 40 MHz with secondary channel above the primary -channel - -:::{note} -Channel availability for HT40- and HT40+ is limited. The following -table lists channels permitted for HT40- and HT40+ according to IEEE -802.11n Annex J. Channel availability may vary by location. - - ::::{code-block} none - freq HT40- HT40+ - 2.4 GHz 5-13 1-7 (1-9 in Europe/Japan) - 5 GHz 40,48,56,64 36,44,52,60 - :::: -::: - -:::{note} -40 MHz channels may switch their primary and secondary channels if -needed or creation of 40 MHz channel may be rejected based on overlapping -BSSes. These changes are done automatically when hostapd is setting up the -40 MHz channel. -::: -``` - -```{cfgcmd} set interfaces wireless \ capabilities ht delayed-block-ack - -Enable HT-delayed Block Ack ``[DELAYED-BA]`` -``` - -```{cfgcmd} set interfaces wireless \ capabilities ht dsss-cck-40 - -DSSS/CCK Mode in 40 MHz, this sets ``[DSSS_CCK-40]`` -``` - -```{cfgcmd} set interfaces wireless \ capabilities ht greenfield - -This enables the greenfield option which sets the ``[GF]`` option -``` - -```{cfgcmd} set interfaces wireless \ capabilities ht ldpc - -Enable LDPC coding capability -``` - -```{cfgcmd} set interfaces wireless \ capabilities ht lsig-protection - -Enable L-SIG TXOP protection capability -``` - -```{cfgcmd} set interfaces wireless \ capabilities ht max-amsdu \<3839 | 7935\> - -Maximum A-MSDU length 3839 (default) or 7935 octets -``` - -```{cfgcmd} set interfaces wireless \ capabilities ht short-gi \<20 | 40\> - -Short GI capabilities for 20 and 40 MHz -``` - -```{cfgcmd} set interfaces wireless \ capabilities ht smps \ - -Spatial Multiplexing Power Save (SMPS) settings -``` - -```{cfgcmd} set interfaces wireless \ capabilities ht stbc rx \ - -Enable receiving PPDU using STBC (Space Time Block Coding) -``` - -```{cfgcmd} set interfaces wireless \ capabilities ht stbc tx - -Enable sending PPDU using STBC (Space Time Block Coding) -``` - -##### VHT (Very High Throughput) capabilities (802.11ac) - -```{cfgcmd} set interfaces wireless \ capabilities vht antenna-count \ -``` - -% -% Number of antennas on this card - -```{cfgcmd} set interfaces wireless \ capabilities vht antenna-pattern-fixed - -Set if antenna pattern does not change during the lifetime of an association -``` - -```{cfgcmd} set interfaces wireless \ capabilities vht beamform \ - -Beamforming capabilities: -* ``single-user-beamformer`` - Support for operation as -single user beamformer -* ``single-user-beamformee`` - Support for operation as -single user beamformee -* ``multi-user-beamformer`` - Support for operation as -multi user beamformer -* ``multi-user-beamformee`` - Support for operation as -multi user beamformee -``` - -```{cfgcmd} set interfaces wireless \ capabilities vht center-channel-freq \ \ - -VHT operating channel center frequency - center freq 1 -(for use with 80, 80+80 and 160 modes) - -VHT operating channel center frequency - center freq 2 -(for use with the 80+80 mode) - -\ must be from 34 - 173. For 80 MHz channels it should be channel + 6. -``` - -```{cfgcmd} set interfaces wireless \ capabilities vht channel-set-width \<0 | 1 | 2 | 3\> - -* ``0`` - 20 or 40 MHz channel width (default) -* ``1`` - 80 MHz channel width -* ``2`` - 160 MHz channel width -* ``3`` - 80+80 MHz channel width -``` - -```{cfgcmd} set interfaces wireless \ capabilities vht ldpc - -Enable LDPC (Low Density Parity Check) coding capability -``` - -```{cfgcmd} set interfaces wireless \ capabilities vht link-adaptation - -VHT link adaptation capabilities -``` - -```{cfgcmd} set interfaces wireless \ capabilities vht max-mpdu \ - -Increase Maximum MPDU length to 7991 or 11454 octets (default 3895 octets) -``` - -```{cfgcmd} set interfaces wireless \ capabilities vht max-mpdu-exp \ - -Set the maximum length of A-MPDU pre-EOF padding that the station can -receive -``` - -```{cfgcmd} set interfaces wireless \ capabilities vht short-gi \<80 | 160\> - -Short GI capabilities -``` - -```{cfgcmd} set interfaces wireless \ capabilities vht stbc rx \ - -Enable receiving PPDU using STBC (Space Time Block Coding) -``` - -```{cfgcmd} set interfaces wireless \ capabilities vht stbc tx - -Enable sending PPDU using STBC (Space Time Block Coding) -``` - -```{cfgcmd} set interfaces wireless \ capabilities vht tx-powersave - -Enable VHT TXOP Power Save Mode -``` - -```{cfgcmd} set interfaces wireless \ capabilities vht vht-cf - -Station supports receiving VHT variant HT Control field -``` - -##### HE (High Efficiency) capabilities (802.11ax) - -```{cfgcmd} set interfaces wireless \ capabilities he antenna-pattern-fixed - -Tell the AP that antenna positions are fixed and will not change -during the lifetime of an association. -``` - -```{cfgcmd} set interfaces wireless \ capabilities he beamform \ - -Beamforming capabilities: -* ``single-user-beamformer`` - Support for operation as -single user beamformer -* ``single-user-beamformee`` - Support for operation as -single user beamformee -* ``multi-user-beamformer`` - Support for operation as multi -user beamformer -``` - -```{cfgcmd} set interfaces wireless \ capabilities he bss-color \ - -BSS coloring helps to prevent channel jamming when multiple APs use -the same channels. - -Valid values are 1..63 -``` - -```{cfgcmd} set interfaces wireless \ capabilities he center-channel-freq \ \ - -HE operating channel center frequency - center freq 1 -(for use with 80, 80+80 and 160 modes) - -HE operating channel center frequency - center freq 2 -(for use with the 80+80 mode) - -\ must be within 1..233. For 80 MHz channels it should be -channel + 6 and for 160 MHz channels, it should be channel + 14. -``` - -```{cfgcmd} set interfaces wireless \ capabilities he channel-set-width \ - -\ must be one of: - -* ``81`` - 20 MHz channel width (2.4GHz) -* ``83`` - 40 MHz channel width, secondary 20MHz channel above primary -channel (2.4GHz) -* ``84`` - 40 MHz channel width, secondary 20MHz channel below primary -channel (2.4GHz) -* ``131`` - 20 MHz channel width (6GHz) -* ``132`` - 40 MHz channel width (6GHz) -* ``133`` - 80 MHz channel width (6GHz) -* ``134`` - 160 MHz channel width (6GHz) -* ``135`` - 80+80 MHz channel width (6GHz) -``` - -```{cfgcmd} set interfaces wireless \ capabilities he coding-scheme \ - -This setting configures Spatial Stream and Modulation Coding Scheme -settings for HE mode (HE-MCS). It is usually not needed to set this -explicitly, but it might help with some WiFi adapters. - -\ must be one of: -* ``0`` - HE-MCS 0-7 -* ``1`` - HE-MCS 0-9 -* ``2`` - HE-MCS 0-11 -* ``3`` - HE-MCS is not supported -``` - -### Wireless options (Station/Client) - -The example creates a wireless station (commonly referred to as Wi-Fi client) -that accesses the network through the WAP defined in the above example. The -default physical device (`phy0`) is used. - -```none -set system wireless country-code de -set interfaces wireless wlan0 type station -set interfaces wireless wlan0 address dhcp -set interfaces wireless wlan0 ssid 'TEST' -set interfaces wireless wlan0 security wpa passphrase '12345678' -``` - -Resulting configuration: - -```none -system { - wireless { - country-code de - } -} -interfaces { - wireless wlan0 { - address dhcp - security { - wpa { - passphrase "12345678" - } - } - ssid TEST - type station - } -``` - -### Security - -{abbr}`WPA (Wi-Fi Protected Access)`, WPA2 Enterprise and WPA3 Enterprise in -combination with 802.1X based authentication can be used to authenticate -users or computers in a domain. - -The wireless client (supplicant) authenticates against the RADIUS server -(authentication server) using an {abbr}`EAP (Extensible Authentication -Protocol)` method configured on the RADIUS server. The WAP (also referred -to as authenticator) role is to send all authentication messages between the -supplicant and the configured authentication server, thus the RADIUS server -is responsible for authenticating the users. - -The WAP in this example has the following characteristics: -- IP address `192.168.2.1/24` -- Network ID (SSID) `Enterprise-TEST` -- WPA passphrase `12345678` -- Use 802.11n protocol -- Wireless channel `1` -- RADIUS server at `192.168.3.10` with shared-secret `VyOSPassword` - -```none -set system wireless country-code de -set interfaces wireless wlan0 address '192.168.2.1/24' -set interfaces wireless wlan0 type access-point -set interfaces wireless wlan0 channel 1 -set interfaces wireless wlan0 mode n -set interfaces wireless wlan0 ssid 'Enterprise-TEST' -set interfaces wireless wlan0 security wpa mode wpa2 -set interfaces wireless wlan0 security wpa cipher CCMP -set interfaces wireless wlan0 security wpa radius server 192.168.3.10 key 'VyOSPassword' -set interfaces wireless wlan0 security wpa radius server 192.168.3.10 port 1812 -``` - -Resulting configuration: - -```none -system { - wireless { - country-code de - } -} -interfaces { - [...] - wireless wlan0 { - address 192.168.2.1/24 - channel 1 - mode n - security { - wpa { - cipher CCMP - mode wpa2 - radius { - server 192.168.3.10 { - key 'VyOSPassword' - port 1812 - } - } - } - } - ssid "Enterprise-TEST" - type access-point - } -} -``` - -### VLAN -#### Regular VLANs (802.1q) - -```{cmdincludemd} /_include/interface-vlan-8021q.txt -:var0: wireless -:var1: wlan0 -``` - -#### QinQ (802.1ad) - -```{cmdincludemd} /_include/interface-vlan-8021ad.txt -:var0: wireless -:var1: wlan0 -``` - -## Operation - -```{opcmd} show interfaces wireless info -``` - -Use this command to view operational status and wireless-specific information -about all wireless interfaces. - -```none -vyos@vyos:~$ show interfaces wireless info -Interface Type SSID Channel -wlan0 access-point VyOS-TEST-0 1 -``` - -```{opcmd} show interfaces wireless detail -``` - -Show the operational status and detailed wireless-specific -information about all wireless interfaces. - -```none -vyos@vyos:~$ show interfaces wireless detail -wlan0: mtu 1500 qdisc noqueue state UP group default qlen 1000 - link/ether XX:XX:XX:XX:XX:c3 brd XX:XX:XX:XX:XX:ff - inet xxx.xxx.99.254/24 scope global wlan0 - valid_lft forever preferred_lft forever - inet6 fe80::xxxx:xxxx:fe54:2fc3/64 scope link - valid_lft forever preferred_lft forever - - RX: bytes packets errors dropped overrun mcast - 66072 282 0 0 0 0 - TX: bytes packets errors dropped carrier collisions - 83413 430 0 0 0 0 - -wlan1: mtu 1500 qdisc noqueue state UP group default qlen 1000 - link/ether XX:XX:XX:XX:XX:c3 brd XX:XX:XX:XX:XX:ff - inet xxx.xxx.100.254/24 scope global wlan0 - valid_lft forever preferred_lft forever - inet6 fe80::xxxx:xxxx:ffff:2ed3/64 scope link - valid_lft forever preferred_lft forever - - RX: bytes packets errors dropped overrun mcast - 166072 5282 0 0 0 0 - TX: bytes packets errors dropped carrier collisions - 183413 5430 0 0 0 0 -``` - -```{opcmd} show interfaces wireless \ -``` - -This command shows both status and statistics on the specified wireless -interface. The wireless interface identifier can range from wlan0 to wlan999. - -```none -vyos@vyos:~$ show interfaces wireless wlan0 -wlan0: mtu 1500 qdisc noqueue state UP group default qlen 1000 - link/ether XX:XX:XX:XX:XX:c3 brd XX:XX:XX:XX:XX:ff - inet xxx.xxx.99.254/24 scope global wlan0 - valid_lft forever preferred_lft forever - inet6 fe80::xxxx:xxxx:fe54:2fc3/64 scope link - valid_lft forever preferred_lft forever - - RX: bytes packets errors dropped overrun mcast - 66072 282 0 0 0 0 - TX: bytes packets errors dropped carrier collisions - 83413 430 0 0 0 0 -``` - -```{opcmd} show interfaces wireless \ brief -``` - -This command gives a brief status overview of a specified wireless interface. -The wireless interface identifier can range from wlan0 to wlan999. - -```none -vyos@vyos:~$ show interfaces wireless wlan0 brief -Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down -Interface IP Address S/L Description ---------- ---------- --- ----------- -wlan0 192.168.2.254/24 u/u -``` - -```{opcmd} show interfaces wireless \ queue -``` - -Use this command to view wireless interface queue information. -The wireless interface identifier can range from wlan0 to wlan999. - -```none -vyos@vyos:~$ show interfaces wireless wlan0 queue -qdisc pfifo_fast 0: root bands 3 priomap 1 2 2 2 1 2 0 0 1 1 1 1 1 1 1 1 - Sent 810323 bytes 6016 pkt (dropped 0, overlimits 0 requeues 0) - rate 0bit 0pps backlog 0b 0p requeues 0 -``` - -```{opcmd} show interfaces wireless \ scan -``` - -This command is used to retrieve information about WAP within the range of your -wireless interface. This command is useful on wireless interfaces configured -in station mode. - -:::{note} -Scanning is not supported on all wireless drivers and wireless -hardware. Refer to your driver and wireless hardware documentation for -further details. -::: -```none -vyos@vyos:~$ show interfaces wireless wlan0 scan -Address SSID Channel Signal (dbm) -00:53:3b:88:6e:d8 WLAN-576405 1 -64.00 -00:53:3b:88:6e:da Telekom_FON 1 -64.00 -00:53:00:f2:c2:a4 BabyView_F2C2A4 6 -60.00 -00:53:3b:88:6e:d6 Telekom_FON 100 -72.00 -00:53:3b:88:6e:d4 WLAN-576405 100 -71.00 -00:53:44:a4:96:ec KabelBox-4DC8 56 -81.00 -00:53:d9:7a:67:c2 WLAN-741980 1 -75.00 -00:53:7c:99:ce:76 Vodafone Homespot 1 -86.00 -00:53:44:a4:97:21 KabelBox-4DC8 1 -78.00 -00:53:44:a4:97:21 Vodafone Hotspot 1 -79.00 -00:53:44:a4:97:21 Vodafone Homespot 1 -79.00 -00:53:86:40:30:da Telekom_FON 1 -86.00 -00:53:7c:99:ce:76 Vodafone Hotspot 1 -86.00 -00:53:44:46:d2:0b Vodafone Hotspot 1 -87.00 -``` - -## Examples - -The following example creates a WAP. When configuring multiple WAP interfaces, -you must specify unique IP addresses, channels, Network IDs commonly referred -to as {abbr}`SSID (Service Set Identifier)`, and MAC addresses. - -The WAP in this example has the following characteristics: -- IP address `192.168.2.1/24` -- Network ID (SSID) `TEST` -- WPA passphrase `12345678` -- Use 802.11n protocol -- Wireless channel `1` - -```none -set system wireless country-code de -set interfaces wireless wlan0 address '192.168.2.1/24' -set interfaces wireless wlan0 type access-point -set interfaces wireless wlan0 channel 1 -set interfaces wireless wlan0 mode n -set interfaces wireless wlan0 ssid 'TEST' -set interfaces wireless wlan0 security wpa mode wpa2 -set interfaces wireless wlan0 security wpa cipher CCMP -set interfaces wireless wlan0 security wpa passphrase '12345678' -``` - -Resulting configuration: - -```none -system { - wireless { - country-code de - } -} -interfaces { - [...] - wireless wlan0 { - address 192.168.2.1/24 - channel 1 - mode n - security { - wpa { - cipher CCMP - mode wpa2 - passphrase "12345678" - } - } - ssid "TEST" - type access-point - } -} -``` - -To enable access point functionality, configure a DHCP server for this -interface's network, or add the interface to an existing local bridge -(see {ref}`bridge-interface` for details). - -### Wi-Fi 6/6E (802.11ax) - -The following examples configure Wi-Fi 6 (2.4 GHz) and Wi-Fi 6E (6 GHz) -{abbr}`APs (Access Points)` with the following parameters: -- Network ID (SSID): `test.ax` -- WPA passphrase: `super-dooper-secure-passphrase` -- Protocol: 802.11ax -- Wireless channel for 2.4 GHz: `11` -- Wireless channel for 6 GHz: `5` - -#### Example configuration: Wi-Fi 6 at 2.4 GHz - -You may expect real throughput around 10 MB/s or higher in crowded areas. - -```none -set system wireless country-code de -set interfaces wireless wlan0 capabilities he antenna-pattern-fixed -set interfaces wireless wlan0 capabilities he beamform multi-user-beamformer -set interfaces wireless wlan0 capabilities he beamform single-user-beamformee -set interfaces wireless wlan0 capabilities he beamform single-user-beamformer -set interfaces wireless wlan0 capabilities he bss-color 13 -set interfaces wireless wlan0 capabilities he channel-set-width 81 -set interfaces wireless wlan0 capabilities ht 40mhz-incapable -set interfaces wireless wlan0 capabilities ht channel-set-width ht20 -set interfaces wireless wlan0 capabilities ht channel-set-width ht40+ -set interfaces wireless wlan0 capabilities ht channel-set-width ht40- -set interfaces wireless wlan0 capabilities ht short-gi 20 -set interfaces wireless wlan0 capabilities ht short-gi 40 -set interfaces wireless wlan0 capabilities ht stbc rx 2 -set interfaces wireless wlan0 capabilities ht stbc tx -set interfaces wireless wlan0 channel 11 -set interfaces wireless wlan0 description "802.11ax 2.4GHz" -set interfaces wireless wlan0 mode ax -set interfaces wireless wlan0 security wpa cipher CCMP -set interfaces wireless wlan0 security wpa cipher CCMP-256 -set interfaces wireless wlan0 security wpa cipher GCMP-256 -set interfaces wireless wlan0 security wpa cipher GCMP -set interfaces wireless wlan0 security wpa mode wpa2 -set interfaces wireless wlan0 security wpa passphrase super-dooper-secure-passphrase -set interfaces wireless wlan0 ssid test.ax -set interfaces wireless wlan0 type access-point -commit -``` - -Resulting configuration: - -```none -system { - wireless { - country-code de - } -} -interfaces { - [...] - wireless wlan0 { - capabilities { - he { - antenna-pattern-fixed - beamform { - multi-user-beamformer - single-user-beamformee - single-user-beamformer - } - bss-color 13 - channel-set-width 81 - } - ht { - 40mhz-incapable - channel-set-width ht20 - channel-set-width ht40+ - channel-set-width ht40- - short-gi 20 - short-gi 40 - stbc { - rx 2 - tx - } - } - } - channel 11 - description "802.11ax 2.4GHz" - hw-id [...] - mode ax - physical-device phy0 - security { - wpa { - cipher CCMP - cipher CCMP-256 - cipher GCMP-256 - cipher GCMP - mode wpa2 - passphrase super-dooper-secure-passphrase - } - } - ssid test.ax - type access-point - } -} -``` - -#### Example configuration: Wi-Fi 6E at 6 GHz - -You may expect real throughput between 50 MB/s and 150 MB/s, depending on -obstructions from walls, water, metal, or other materials -with high electromagnetic damping at 6 GHz. Best results are achieved -with the AP being in the same room and in line-of-sight. - -```none -set system wireless country-code de -set interfaces wireless wlan0 capabilities he antenna-pattern-fixed -set interfaces wireless wlan0 capabilities he beamform multi-user-beamformer -set interfaces wireless wlan0 capabilities he beamform single-user-beamformee -set interfaces wireless wlan0 capabilities he beamform single-user-beamformer -set interfaces wireless wlan0 capabilities he bss-color 13 -set interfaces wireless wlan0 capabilities he channel-set-width 134 -set interfaces wireless wlan0 capabilities he center-channel-freq freq-1 15 -set interfaces wireless wlan0 channel 5 -set interfaces wireless wlan0 description "802.11ax 6GHz" -set interfaces wireless wlan0 mode ax -set interfaces wireless wlan0 security wpa cipher CCMP -set interfaces wireless wlan0 security wpa cipher CCMP-256 -set interfaces wireless wlan0 security wpa cipher GCMP-256 -set interfaces wireless wlan0 security wpa cipher GCMP -set interfaces wireless wlan0 security wpa mode wpa3 -set interfaces wireless wlan0 security wpa passphrase super-dooper-secure-passphrase -set interfaces wireless wlan0 mgmt-frame-protection required -set interfaces wireless wlan0 enable-bf-protection -set interfaces wireless wlan0 ssid test.ax -set interfaces wireless wlan0 type access-point -set interfaces wireless wlan0 stationary-ap -commit -``` - -Resulting configuration: - -```none -system { - wireless { - country-code de - } -} -interfaces { - [...] - wireless wlan0 { - capabilities { - he { - antenna-pattern-fixed - beamform { - multi-user-beamformer - single-user-beamformee - single-user-beamformer - } - bss-color 13 - center-channel-freq { - freq-1 15 - } - channel-set-width 134 - } - } - channel 5 - description "802.11ax 6GHz" - enable-bf-protection - hw-id [...] - mgmt-frame-protection required - mode ax - physical-device phy0 - security { - wpa { - cipher CCMP - cipher CCMP-256 - cipher GCMP-256 - cipher GCMP - mode wpa3 - passphrase super-dooper-secure-passphrase - } - } - ssid test.ax - stationary-ap - type access-point - } -} -``` - -(wireless-interface-intel-ax200)= - -### Intel AX200 - -The Intel AX200 card does not work out of the box in AP mode. You can -still put this card into AP mode using the following configuration: - -```none -set system wireless country-code 'us' -set interfaces wireless wlan0 channel '1' -set interfaces wireless wlan0 mode 'n' -set interfaces wireless wlan0 physical-device 'phy0' -set interfaces wireless wlan0 ssid 'VyOS' -set interfaces wireless wlan0 type 'access-point' -``` - diff --git a/docs/configuration/interfaces/md-wwan.md b/docs/configuration/interfaces/md-wwan.md deleted file mode 100644 index e8121f28..00000000 --- a/docs/configuration/interfaces/md-wwan.md +++ /dev/null @@ -1,355 +0,0 @@ ---- -lastproofread: '2026-03-30' ---- - -(wwan-interface)= - -# WWAN - -{abbr}`WWAN (Wireless Wide Area Network)` interfaces provide access to cellular -networks via a cellular modem or card. - -Configure these interfaces under the `interfaces wwan` node. - -## Configuration - -### Common interface configuration - -```{cmdincludemd} /_include/interface-address-with-dhcp.txt -:var0: wwan -:var1: wwan0 -``` - -```{cmdincludemd} /_include/interface-description.txt -:var0: wwan -:var1: wwan0 -``` - -```{cmdincludemd} /_include/interface-disable.txt -:var0: wwan -:var1: wwan0 -``` - -```{cmdincludemd} /_include/interface-disable-link-detect.txt -:var0: wwan -:var1: wwan0 -``` - -```{cmdincludemd} /_include/interface-mtu.txt -:var0: wwan -:var1: wwan0 -``` - -```{cmdincludemd} /_include/interface-ip.txt -:var0: wwan -:var1: wwan0 -``` - -```{cmdincludemd} /_include/interface-ipv6.txt -:var0: wwan -:var1: wwan0 -``` - -```{cmdincludemd} /_include/interface-vrf.txt -:var0: wwan -:var1: wwan0 -``` - -**DHCP(v6)** - -```{cmdincludemd} /_include/interface-dhcp-options.txt -:var0: wwan -:var1: wwan0 -``` - -```{cmdincludemd} /_include/interface-dhcpv6-options.txt -:var0: wwan -:var1: wwan0 -``` - -```{cmdincludemd} /_include/interface-dhcpv6-prefix-delegation.txt -:var0: wwan -:var1: wwan0 -``` - - -### WWAN options - -```{cfgcmd} set interfaces wwan \ apn \ - -**Configure the** {abbr}`APN (Access Point Name)` **for the WWAN connection.** - -Every WWAN connection requires an {abbr}`APN (Access Point Name)` to connect to -the cellular network. - -This parameter is mandatory. Contact your service provider for the correct -{abbr}`APN (Access Point Name)`. -``` - - -## Operation - -```{opcmd} show interfaces wwan \ - -Show the operational status and traffic statistics for the specified WWAN -interface. - -:::{code-block} none -vyos@vyos:~$ show interfaces wwan wwan0 -wwan0: mtu 1500 qdisc pfifo_fast state UNKNOWN group default qlen 1000 -link/ether 02:c2:f3:00:01:02 brd ff:ff:ff:ff:ff:ff -inet 10.155.144.12/30 brd 10.155.144.15 scope global dynamic wwan0 -valid_lft 7012sec preferred_lft 7012sec -inet6 fe80::c2:f3ff:fe00:0102/64 scope link -valid_lft forever preferred_lft forever - -RX: bytes packets errors dropped overrun mcast -640 2 0 0 0 0 -TX: bytes packets errors dropped carrier collisions -3229 16 0 0 0 0 -::: -``` - - -```{opcmd} show interfaces wwan \ summary - -Show WWAN module hardware characteristics and connection information. - -:::{code-block} none -vyos@vyos:~$ show interfaces wwan wwan0 summary --------------------------------- -General | dbus path: /org/freedesktop/ModemManager1/Modem/0 -| device id: 79f4e9cc2e9fc8d4a3b8c8f6327c2e363170194d --------------------------------- -Hardware | manufacturer: Sierra Wireless, Incorporated -| model: MC7710 -| revision: SWI9200X_03.05.29.03ap r6485 CNSHZ-ED-XP0031 2014/12/02 17:53:15 -| h/w revision: 1.0 -| supported: gsm-umts, lte -| current: gsm-umts, lte -| equipment id: 358xxxxxxxxxxxx --------------------------------- -System | device: /sys/devices/pci0000:00/0000:00:13.0/usb3/3-1/3-1.3 -| drivers: qcserial, qmi_wwan -| plugin: Generic -| primary port: cdc-wdm0 -| ports: ttyUSB0 (qcdm), ttyUSB2 (at), cdc-wdm0 (qmi), wwan0 (net) --------------------------------- -Numbers | own: 4917xxxxxxxx --------------------------------- -Status | lock: sim-pin2 -| unlock retries: sim-pin (3), sim-pin2 (3), sim-puk (10), sim-puk2 (10) -| state: connected -| power state: on -| access tech: lte -| signal quality: 63% (recent) --------------------------------- -Modes | supported: allowed: 2g; preferred: none -| allowed: 3g; preferred: none -| allowed: 4g; preferred: none -| allowed: 2g, 3g; preferred: 3g -| allowed: 2g, 3g; preferred: 2g -| allowed: 2g, 4g; preferred: 4g -| allowed: 2g, 4g; preferred: 2g -| allowed: 3g, 4g; preferred: 3g -| allowed: 3g, 4g; preferred: 4g -| allowed: 2g, 3g, 4g; preferred: 4g -| allowed: 2g, 3g, 4g; preferred: 3g -| allowed: 2g, 3g, 4g; preferred: 2g -| current: allowed: 2g, 3g, 4g; preferred: 2g --------------------------------- -Bands | supported: egsm, dcs, pcs, utran-1, utran-8, eutran-1, eutran-3, -| eutran-7, eutran-8, eutran-20 -| current: egsm, dcs, pcs, utran-1, utran-8, eutran-1, eutran-3, -| eutran-7, eutran-8, eutran-20 --------------------------------- -IP | supported: ipv4, ipv6, ipv4v6 --------------------------------- -3GPP | imei: 358xxxxxxxxxxxx -| operator id: 26201 -| operator name: Telekom.de -| registration: home --------------------------------- -3GPP EPS | ue mode of operation: ps-1 --------------------------------- -SIM | dbus path: /org/freedesktop/ModemManager1/SIM/0 --------------------------------- -Bearer | dbus path: /org/freedesktop/ModemManager1/Bearer/0 -::: -``` - -```{opcmd} show interfaces wwan \ capabilities - -Show WWAN module radio capabilities. - -:::{code-block} none -vyos@vyos:~$ show interfaces wwan wwan0 capabilities -Max TX channel rate: '50000000' -Max RX channel rate: '100000000' -Data Service: 'simultaneous-cs-ps' -SIM: 'supported' -Networks: 'gsm, umts, lte' -Bands: 'gsm-dcs-1800, gsm-900-extended, gsm-900-primary, gsm-pcs-1900, wcdma-2100, wcdma-900' -LTE bands: '1, 3, 7, 8, 20' -::: -``` - - -```{opcmd} show interfaces wwan \ firmware - -Show WWAN module firmware information. - -:::{code-block} none -vyos@vyos:~$ show interfaces wwan wwan0 firmware -Model: MC7710 -Boot version: SWI9200X_03.05.29.03bt r6485 CNSHZ-ED-XP0031 2014/12/02 17:33:08 -AMSS version: SWI9200X_03.05.29.03ap r6485 CNSHZ-ED-XP0031 2014/12/02 17:53:15 -SKU ID: unknown -Package ID: unknown -Carrier ID: 0 -Config version: unknown -::: -``` - -```{opcmd} show interfaces wwan \ imei - -Show WWAN module IMEI. - -:::{code-block} none -vyos@vyos:~$ show interfaces wwan wwan0 imei -ESN: '0' -IMEI: '358xxxxxxxxxxxx' -MEID: 'unknown' -::: -``` - -```{opcmd} show interfaces wwan \ imsi - -Show the IMSI of the associated SIM card. - -:::{code-block} none -vyos@vyos:~$ show interfaces wwan wwan0 imsi -IMSI: '262xxxxxxxxxxxx' -::: -``` - -```{opcmd} show interfaces wwan \ model - -Show WWAN module model. - -:::{code-block} none -vyos@vyos:~$ show interfaces wwan wwan0 model -Model: 'MC7710' -::: -``` - -```{opcmd} show interfaces wwan \ msisdn - -Show the MSISDN of the associated SIM card. - -:::{code-block} none -vyos@vyos:~$ show interfaces wwan wwan0 msisdn -MSISDN: '4917xxxxxxxx' -::: -``` - -```{opcmd} show interfaces wwan \ revision - -Show WWAN module hardware revision. - -:::{code-block} none -vyos@vyos:~$ show interfaces wwan wwan0 revision -Revision: 'SWI9200X_03.05.29.03ap r6485 CNSHZ-ED-XP0031 2014/12/02 17:53:15' -::: -``` - -```{opcmd} show interfaces wwan \ signal - -Show signal information for the cellular connection. - -:::{code-block} none -vyos@vyos:~$ show interfaces wwan wwan0 signal -LTE: -RSSI: '-74 dBm' -RSRQ: '-7 dB' -RSRP: '-100 dBm' -SNR: '13.0 dB' -Radio Interface: 'lte' -Active Band Class: 'eutran-3' -Active Channel: '1300' -::: -``` - -```{opcmd} show interfaces wwan \ sim - -Show WWAN module SIM card information. - -:::{code-block} none -vyos@vyos:~$ show interfaces wwan wwan0 sim -Provisioning applications: -Primary GW: slot '1', application '1' -Primary 1X: session doesn't exist -Secondary GW: session doesn't exist -Secondary 1X: session doesn't exist -Slot [1]: -Card state: 'present' -UPIN state: 'not-initialized' -UPIN retries: '0' -UPUK retries: '0' -Application [1]: -Application type: 'usim (2)' -Application state: 'ready' -Application ID: -A0:00:00:00:87:10:02:FF:49:94:20:89:03:10:00:00 -Personalization state: 'ready' -UPIN replaces PIN1: 'no' -PIN1 state: 'disabled' -PIN1 retries: '3' -PUK1 retries: '10' -PIN2 state: 'enabled-not-verified' -PIN2 retries: '3' -PUK2 retries: '10' -::: -``` - - -## Example - -The following example shows how to configure a cellular connection using a -Sierra Wireless MC7710 miniPCIe card that operates over USB despite its form -factor. The card is installed in a {ref}`pc-engines-apu4`. - -```none -set interfaces wwan wwan0 apn 'internet.telekom' -set interfaces wwan wwan0 address 'dhcp' -``` - - -## Supported hardware - -The following WWAN modules have been successfully tested with a -{ref}`pc-engines-apu4` board: -- Sierra Wireless AirPrime MC7304 miniPCIe card (LTE) -- Sierra Wireless AirPrime MC7430 miniPCIe card (LTE) -- Sierra Wireless AirPrime MC7455 miniPCIe card (LTE) -- Sierra Wireless AirPrime MC7710 miniPCIe card (LTE) -- Huawei ME909u-521 miniPCIe card (LTE) -- Huawei ME909s-120 miniPCIe card (LTE) -- HP LT4120 Snapdragon X5 LTE - -## Firmware update - -WWAN modules include reprogrammable firmware, and most vendors regularly -provide updates for it. - -Since VyOS communicates with these devices via the QMI interface, you can -update firmware directly within the system using the `qmi-firmware-update` -utility. - -The following example shows how to update the firmware for a Sierra Wireless -MC7710 module using the provided .cwe file. - -```bash -$ sudo qmi-firmware-update --update -d 1199:68a2 \ - 9999999_9999999_9200_03.05.14.00_00_generic_000.000_001_SPKG_MC.cwe -``` diff --git a/docs/configuration/loadbalancing/md-haproxy.md b/docs/configuration/loadbalancing/md-haproxy.md deleted file mode 100644 index d60c5248..00000000 --- a/docs/configuration/loadbalancing/md-haproxy.md +++ /dev/null @@ -1,510 +0,0 @@ ---- -lastproofread: '2026-04-06' ---- - -# HAproxy - -```{include} /_include/need_improvement.txt -``` - -HAProxy is a load balancer and proxy server that provides -high-availability, load balancing, and proxying for TCP (level 4) and -HTTP-based (level 7) applications. - -## Configuration - -Service configuration specifies the port to bind to. Backend -configuration defines the load balancing method and specifies the backend -servers. - -### Service - -```{cfgcmd} set load-balancing haproxy service \ listen-address \ - -Set the IP address for the service to bind to. By default, the service -listens on all IPv4 and IPv6 addresses. -``` - -```{cfgcmd} set load-balancing haproxy service \ port \ - -Create service ** to listen on \ -``` - -```{cfgcmd} set load-balancing haproxy service \ mode \ - -Configure service ** mode TCP or HTTP -``` - -```{cfgcmd} set load-balancing haproxy service \ backend \ - -Configure service ** to use the backend \ -``` - -```{cfgcmd} set load-balancing haproxy service \ ssl certificate \ - -Set the SSL certificate \ for service \. You can define -multiple certificates. -``` - -```{cfgcmd} set load-balancing haproxy service \ http-response-headers \ value \ - -Set custom HTTP headers to include in all responses. -``` - -```{cfgcmd} set load-balancing haproxy service \ logging facility \ level \ - -Specify facility and level for logging. -For an explanation on {ref}`syslog_facilities` and -{ref}`syslog_severity_level`, -see tables in the syslog configuration section. -``` - -```{cfgcmd} set load-balancing haproxy service \ timeout client \ - -Set the maximum inactivity time on the client side for this service. -Value range 1-3600 seconds. -``` - -```{cfgcmd} set load-balancing haproxy service \ http-compression algorithm \ - -Set the compression algorithm to be used when compressing HTTP responses. -``` - -```{cfgcmd} set load-balancing haproxy service \ http-compression mime-type \ - -Set the list of HTTP response MIME types which haproxy will attempt to -compress, if received uncompressed from backend server. -``` - -#### Rules - -Rules control and route incoming traffic to specific backends based on -predefined conditions. Rules define matching criteria and specify actions -to perform. - -```{cfgcmd} set load-balancing haproxy service \ rule \ domain-name \ - -Match domain name -``` - -````{cfgcmd} set load-balancing haproxy service \ rule \ ssl \ - -```{eval-rst} -SSL match Server Name Indication (SNI) option: - * ``req-ssl-sni`` SSL Server Name Indication (SNI) request match - * ``ssl-fc-sni`` SSL frontend connection Server Name Indication match - * ``ssl-fc-sni-end`` SSL frontend match end of connection Server Name - - Indication -``` -```` - -````{cfgcmd} set load-balancing haproxy service \ rule \ url-path \ \ - -Define URL path matching rules for a specific service. Use this command -to specify how to match the URL path against incoming requests. - -```{eval-rst} -The available options for are: - * ``begin`` Matches the beginning of the URL path - * ``end`` Matches the end of the URL path. - * ``exact`` Matches the URL path exactly. -``` -```` - -```{cfgcmd} set load-balancing haproxy service \ rule \ set backend \ - -Assign a specific backend to a rule -``` - -```{cfgcmd} set load-balancing haproxy service \ rule \ redirect-location \ - -Redirect URL to a new location. -``` - -### Backend - -````{cfgcmd} set load-balancing haproxy backend \ balance \ - -Specify the load balancing algorithm for distributing requests among -available servers. - -```{eval-rst} -Balance algorithms: - * ``source-address`` Distributes requests based on the source IP address - of the client. - * ``round-robin`` Distributes requests in a circular manner, - sequentially sending each request to the next server in line. - * ``least-connection`` Distributes requests to the server with the fewest - active connections. -``` -```` - -```{cfgcmd} set load-balancing haproxy backend \ mode \ - -Configure backend ** mode TCP or HTTP. -``` - -```{cfgcmd} set load-balancing haproxy backend \ server \ address \ - -Set the address of the backend server that receives incoming traffic. -``` - -```{cfgcmd} set load-balancing haproxy backend \ server \ port \ - -Set the address of the backend port. -``` - -```{cfgcmd} set load-balancing haproxy backend \ server \ check - -Active health check backend server. -``` - -```{cfgcmd} set load-balancing haproxy backend \ server \ check port \ - -Set an alternative port number for health checks. -Overrides the default server port used for TCP/HTTP checks. -``` - -```{cfgcmd} set load-balancing haproxy backend \ server \ send-proxy - -Send a Proxy Protocol version 1 header (text format). -``` - -```{cfgcmd} set load-balancing haproxy backend \ server \ send-proxy-v2 - -Send a Proxy Protocol version 2 header (binary format). -``` - -```{cfgcmd} set load-balancing haproxy backend \ ssl ca-certificate \ - -Use SSL encryption for backend requests and authenticate the backend -against ````. -``` - -```{cfgcmd} set load-balancing haproxy backend \ ssl no-verify - -Use SSL encryption for backend requests without validating the server -certificate. -``` - -```{cfgcmd} set load-balancing haproxy backend \ http-response-headers \ value \ - -Set custom HTTP headers to include in all responses from the backend. -``` - -```{cfgcmd} set load-balancing haproxy backend \ logging facility \ level \ - -Specify facility and level for logging. -For an explanation on {ref}`syslog_facilities` and -{ref}`syslog_severity_level`, -see tables in the syslog configuration section. -``` - -```{cfgcmd} set load-balancing haproxy backend \ timeout check \ - -Set the timeout in seconds for established connections. -Value range 1-3600 seconds. -``` -```{cfgcmd} set load-balancing haproxy backend \ timeout connect \ - -Set the maximum time to wait for a connection attempt to a server to succeed. -Value range 1-3600 seconds. -``` - - -```{cfgcmd} set load-balancing haproxy backend \ timeout server \ - -Set the maximum inactivity time on the server side. -Value range 1-3600 seconds. -``` - -### Global - -Global configuration parameters: - -```{cfgcmd} set load-balancing haproxy global-parameters max-connections \ - -Limit maximum number of connections -``` - - -```{cfgcmd} set load-balancing haproxy global-parameters ssl-bind-ciphers \ - -Limit the cipher algorithms allowed during SSL/TLS handshake. -``` - - -```{cfgcmd} set load-balancing haproxy global-parameters tls-version-min \ - -Specify the minimum required TLS version 1.2 or 1.3 -``` - - -```{cfgcmd} set load-balancing haproxy global-parameters logging facility \ level \ - -Specify facility and level for logging. -For an explanation on {ref}`syslog_facilities` and -{ref}`syslog_severity_level`, -see tables in the syslog configuration section. -``` - - -```{cfgcmd} set load-balancing haproxy timeout check \ - -Set the timeout in seconds for established connections. -Value range 1-3600 seconds. Default is 5 seconds. -``` - - -```{cfgcmd} set load-balancing haproxy timeout client \ - -Set the maximum inactivity time on the client side. -Value range 1-3600 seconds. Default is 50 seconds. -``` - - -```{cfgcmd} set load-balancing haproxy timeout connect \ - -Set the maximum time to wait for a connection attempt to a server to succeed. -Value range 1-3600 seconds. Default is 10 seconds. -``` - - -```{cfgcmd} set load-balancing haproxy timeout server \ - -Set the maximum inactivity time on the server side. -Value range 1-3600 seconds. Default is 50 seconds. -``` - -## Health checks - - -### HTTP checks - - -Use HTTP health checks to monitor web applications that provide health status -information and determine their availability. - -```{cfgcmd} set load-balancing haproxy backend \ http-check - -Enables HTTP health checks using OPTION HTTP requests against '/' and -expecting a successful response code in the 200-399 range. -``` - - -```{cfgcmd} set load-balancing haproxy backend \ http-check method \ - -Set the HTTP method: ``OPTION``, ``GET``, ``POST``, or ``PUT``. -``` - - -```{cfgcmd} set load-balancing haproxy backend \ http-check uri \ - -Set the endpoint to use for health checks. -``` - - -````{cfgcmd} set load-balancing haproxy backend \ http-check expect \ - -Set the expected result condition for a server to be considered healthy. - -```{eval-rst} -Some possible examples are: - * ``status 200`` Expecting a 200 response code - * ``status 200-399`` Expecting a non-failure response code - * ``string success`` Expecting the string success in the response body -``` -```` - -### TCP checks - -Configure health checks for TCP mode backends. You can configure protocol-aware -checks for a range of Layer 7 protocols: - -````{cfgcmd} set load-balancing haproxy backend \ health-check \ - -```{eval-rst} -Available health check protocols: - * ``ldap`` LDAP protocol check. - * ``redis`` Redis protocol check. - * ``mysql`` MySQL protocol check. - * ``pgsql`` PostgreSQL protocol check. - * ``smtp`` SMTP protocol check. -``` -```` - -:::{note} -If you specify a server to check but do not configure a -protocol, HAProxy performs a basic TCP health check. A server is online if -it responds to a connection attempt with a valid `SYN/ACK` packet. -::: -## Redirect HTTP to HTTPS - -Configure a HAProxy service for HTTP that listens on port 80 and redirects -incoming requests to HTTPS: - -```none -set load-balancing haproxy service http port '80' -set load-balancing haproxy service http redirect-http-to-https -``` - -You can use a different service name; in this example, `http` is just for -convenience. - -## Examples -### Level 4 balancing - -This configuration enables the TCP reverse proxy for the `my-tcp-api` -service. Incoming TCP connections on port 8888 are load balanced across the -backend servers (srv01 and srv02) using the round-robin load balancing -algorithm. - -```none -set load-balancing haproxy service my-tcp-api backend 'bk-01' -set load-balancing haproxy service my-tcp-api mode 'tcp' -set load-balancing haproxy service my-tcp-api port '8888' - -set load-balancing haproxy backend bk-01 balance 'round-robin' -set load-balancing haproxy backend bk-01 mode 'tcp' - -set load-balancing haproxy backend bk-01 server srv01 address '192.0.2.11' -set load-balancing haproxy backend bk-01 server srv01 port '8881' -set load-balancing haproxy backend bk-01 server srv02 address '192.0.2.12' -set load-balancing haproxy backend bk-01 server srv02 port '8882' -``` - -### Balancing based on domain name - -The following configuration demonstrates how to use VyOS -to achieve load balancing based on the domain name: - -The HTTP service listens on TCP port 80. - -Rule 10 matches requests with the domain name `node1.example.com` and -forwards them to the backend `bk-api-01`. - -Rule 20 matches requests with the domain name `node2.example.com` and -forwards them to the backend `bk-api-02`. - -```none -set load-balancing haproxy service http description 'bind app listen on 443 port' -set load-balancing haproxy service http mode 'tcp' -set load-balancing haproxy service http port '80' - -set load-balancing haproxy service http rule 10 domain-name 'node1.example.com' -set load-balancing haproxy service http rule 10 set backend 'bk-api-01' -set load-balancing haproxy service http rule 20 domain-name 'node2.example.com' -set load-balancing haproxy service http rule 20 set backend 'bk-api-02' - -set load-balancing haproxy backend bk-api-01 description 'My API-1' -set load-balancing haproxy backend bk-api-01 mode 'tcp' -set load-balancing haproxy backend bk-api-01 server api01 address '127.0.0.1' -set load-balancing haproxy backend bk-api-01 server api01 port '4431' -set load-balancing haproxy backend bk-api-02 description 'My API-2' -set load-balancing haproxy backend bk-api-02 mode 'tcp' -set load-balancing haproxy backend bk-api-02 server api01 address '127.0.0.2' -set load-balancing haproxy backend bk-api-02 server api01 port '4432' -``` - -### Terminate SSL - -The following configuration terminates SSL on the router. - -The `http` service listens on port 80 and redirects HTTP requests to -HTTPS. - -The `https` service listens on port 443 with the `bk-default` backend -and handles HTTPS traffic using the `cert` certificate for SSL termination. -The HSTS header is set with a 1-year expiry to tell browsers to always use -SSL for the site. - -Rule 10 matches requests with the exact URL path `/.well-known/xxx` and -redirects them to `/certs/`. - -Rule 20 matches requests with URL paths ending in `/mail` or the exact -path `/email/bar` and redirects them to `/postfix/`. - -Global parameters include a maximum connection limit of 4000 and a minimum -TLS version of 1.3. - -```none -set load-balancing haproxy service http description 'Force redirect to HTTPS' -set load-balancing haproxy service http port '80' -set load-balancing haproxy service http redirect-http-to-https - -set load-balancing haproxy service https backend 'bk-default' -set load-balancing haproxy service https description 'listen on 443 port' -set load-balancing haproxy service https mode 'http' -set load-balancing haproxy service https port '443' -set load-balancing haproxy service https ssl certificate 'cert' -set load-balancing haproxy service https http-response-headers Strict-Transport-Security value 'max-age=31536000' - -set load-balancing haproxy service https rule 10 url-path exact '/.well-known/xxx' -set load-balancing haproxy service https rule 10 set redirect-location '/certs/' -set load-balancing haproxy service https rule 20 url-path end '/mail' -set load-balancing haproxy service https rule 20 url-path exact '/email/bar' -set load-balancing haproxy service https rule 20 set redirect-location '/postfix/' - -set load-balancing haproxy backend bk-default description 'Default backend' -set load-balancing haproxy backend bk-default mode 'http' -set load-balancing haproxy backend bk-default server sr01 address '192.0.2.23' -set load-balancing haproxy backend bk-default server sr01 port '80' - -set load-balancing haproxy global-parameters max-connections '4000' -set load-balancing haproxy global-parameters tls-version-min '1.3' -``` - -### SSL Bridging - -The following configuration terminates incoming HTTPS traffic on the router, -then re-encrypts the traffic and sends it to the backend server via HTTPS. -Use this when encryption is required for both paths but you do not want to -install publicly trusted certificates on each backend server. - -Backend service certificates are checked against the certificate authority -specified in the configuration, which could be an internal CA. - -The `https` service listens on port 443 with backend `bk-bridge-ssl` to -handle HTTPS traffic. It uses certificate named `cert` for SSL termination. - -The `bk-bridge-ssl` backend connects to `sr01` server on port 443 via HTTPS -and checks backend server has a valid certificate trusted by CA `cacert` - -```none -set load-balancing haproxy service https backend 'bk-bridge-ssl' -set load-balancing haproxy service https description 'listen on 443 port' -set load-balancing haproxy service https mode 'http' -set load-balancing haproxy service https port '443' -set load-balancing haproxy service https ssl certificate 'cert' - -set load-balancing haproxy backend bk-bridge-ssl description 'SSL backend' -set load-balancing haproxy backend bk-bridge-ssl mode 'http' -set load-balancing haproxy backend bk-bridge-ssl ssl ca-certificate 'cacert' -set load-balancing haproxy backend bk-bridge-ssl server sr01 address '192.0.2.23' -set load-balancing haproxy backend bk-bridge-ssl server sr01 port '443' -``` - -### Balancing with HTTP health checks - -This configuration enables HTTP health checks for backend servers. - -```none -set load-balancing haproxy service my-tcp-api backend 'bk-01' -set load-balancing haproxy service my-tcp-api mode 'tcp' -set load-balancing haproxy service my-tcp-api port '8888' - -set load-balancing haproxy backend bk-01 balance 'round-robin' -set load-balancing haproxy backend bk-01 mode 'tcp' - -set load-balancing haproxy backend bk-01 http-check method 'get' -set load-balancing haproxy backend bk-01 http-check uri '/health' -set load-balancing haproxy backend bk-01 http-check expect 'status 200' - -set load-balancing haproxy backend bk-01 server srv01 address '192.0.2.11' -set load-balancing haproxy backend bk-01 server srv01 port '8881' -set load-balancing haproxy backend bk-01 server srv01 check -set load-balancing haproxy backend bk-01 server srv02 address '192.0.2.12' -set load-balancing haproxy backend bk-01 server srv02 port '8882' -set load-balancing haproxy backend bk-01 server srv02 check port '8892' -``` diff --git a/docs/configuration/loadbalancing/md-index.md b/docs/configuration/loadbalancing/md-index.md deleted file mode 100644 index 3241edb7..00000000 --- a/docs/configuration/loadbalancing/md-index.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -lastproofread: '2026-04-06' ---- - -(load-balancing)= - -# Load-balancing - -```{toctree} -:includehidden: true -:maxdepth: 1 - -wan -haproxy -``` diff --git a/docs/configuration/loadbalancing/md-wan.md b/docs/configuration/loadbalancing/md-wan.md deleted file mode 100644 index a19bbfae..00000000 --- a/docs/configuration/loadbalancing/md-wan.md +++ /dev/null @@ -1,306 +0,0 @@ ---- -lastproofread: '2026-04-06' ---- - -# WAN load balancing - -```{todo} -Convert raw command blocks in this file to cfgcmd/opcmd -directives for command coverage tracking. -``` - -The load balancer distributes outbound traffic across two or more -interfaces. If a path fails, the load balancer balances traffic across the -remaining healthy paths. When a path recovers, it is automatically added back -to the routing table. The load balancer adds routes for each path and -distributes traffic based on interface health and weight. - -In a minimal configuration, the following must be provided: -> - An interface with a `nexthop`. -> - One rule with a LAN (inbound-interface) and the WAN (interface). - -The following examples uses two DHCP WAN interfaces and one LAN (`eth2`): - -```none -set load-balancing wan interface-health eth0 nexthop 'dhcp' -set load-balancing wan interface-health eth1 nexthop 'dhcp' -set load-balancing wan rule 1 inbound-interface 'eth2' -set load-balancing wan rule 1 interface eth0 -set load-balancing wan rule 1 interface eth1 -``` - -:::{note} -Do not use WAN load balancing with dynamic routing protocols. This -feature creates customized routing tables and firewall rules that are -incompatible with routing protocols. -::: - -## Load balancing rules - -You define interfaces, their weight, and the traffic type to balance in -numbered rule sets. The load balancer executes rules in numerical order -against outgoing packets. When a packet matches a rule, it is sent through the -specified interface. Packets that do not match any rule use the system routing -table. You cannot change rule numbers. - -Create a load balancing rule, it can be a number between 1 and 9999: - -```none -vyos@vyos# set load-balancing wan rule 1 -Possible completions: -description Description for this rule -> destination Destination -exclude Exclude packets matching this rule from wan load balance -failover Enable failover for packets matching this rule from wan load balance -inbound-interface Inbound interface name (e.g., "eth0") [REQUIRED] -+> interface Interface name [REQUIRED] -> limit Enable packet limit for this rule -per-packet-balancing Option to match traffic per-packet instead of the default, per-flow -protocol Protocol to match -> source Source information -``` - - -### Interface weight - -By default, the load balancer distributes outbound -traffic randomly across available interfaces. You can assign weights to -interfaces to influence the distribution. If `eth0` has more bandwidth -than `eth1`, you can assign a higher weight to `eth0` to send more -traffic through it: - -```none -set load-balancing wan rule 1 interface eth0 weight 2 -set load-balancing wan rule 1 interface eth1 weight 1 -``` - -In this example,\`\`eth0\`\` receives 66% of traffic, and `eth1` receives -33% of traffic. - -### Rate limit - -Set a packet rate limit for a rule to apply it to traffic above or below a -specified threshold. To configure rate limiting, use: - -```none -set load-balancing wan rule limit -``` - -- `burst`: Number of packets allowed to overshoot the limit within `period`. - Default 5. -- `period`: Time window for rate calculation. Possible values: - `second` (one second), `minute` (one minute), `hour` (one hour). - Default is `second`. -- `rate`: Number of packets. Default: `5`. -- `threshold`: `below` or `above` the specified rate limit. - -### Flow and packet-based balancing - -The load balancer balances outgoing traffic by flow. A connection tracking -table tracks flows by source address, destination address, and port. Each -flow is assigned to an interface based on the balancing rules, and subsequent -packets use the same interface. This ensures packets arrive in order when links -have different speeds. - -Packet-based balancing can improve balance across interfaces when packet -order is not critical. Enable per-packet balancing for a rule with: - -```none -set load-balancing wan rule per-packet-balancing -``` - - -### Exclude traffic - -To exclude traffic from load balancing, traffic matching an exclude rule -bypasses load balancing and uses the system routing table instead: - -```none -set load-balancing wan rule exclude -``` - - -## Health checks - -The load balancer periodically checks the health of interfaces and paths by -sending ICMP packets (ping) to remote destinations, performing TTL tests, or -executing a user-defined script. If an interface fails the health check, the -load balancer removes it from its interface pool. -To enable health checking for an interface: - -```none -vyos@vyos# set load-balancing wan interface-health -Possible completions: -failure-count Failure count -nexthop Outbound interface nexthop address. Can be 'dhcp or ip address' [REQUIRED] -success-count Success count -+> test Rule number -``` - -Specify the nexthop on the path to the destination. You can set -`ipv4-address` to `dhcp`. - -```none -set load-balancing wan interface-health nexthop -``` - -Set the number of health check failures before the load balancer marks an -interface as unavailable (range 1-10, default 1). Or set the number of -successful health checks before adding an interface back to the pool -(range 1-10, default 1). - -```none -set load-balancing wan interface-health failure-count -set load-balancing wan interface-health success-count -``` - -Configure each health check in its own test. Tests are numbered and processed -in numeric order. You can define multiple tests for multi-target health -checking: - -```none -vyos@vyos# set load-balancing wan interface-health eth1 test 0 -Possible completions: -resp-time Ping response time (seconds) -target Health target address -test-script Path to user defined script -ttl-limit Ttl limit (hop count) -type WLB test type -``` - -- `resp-time`: The maximum response time for ping in seconds. Range - 1-30, default `5`. -- `target`: The target to receive ICMP packets. The address can be an IPv4 - address or hostname. -- `test-script`: A user-defined script must return 0 to succeed and - non-zero to fail. Scripts reside in `/config/scripts`. For other locations, - provide the full path. -- `ttl-limit`: For the UDP TTL limit test, specify the hop count limit. - The limit must be shorter than the path length. The test succeeds when an - ICMP time-expired message is returned. Default `1`. -- `type`: Specify the test type: `ping`, `ttl`, or a user-defined - script. - -## Source NAT rules - -By default, interfaces in a load balancing pool replace the source IP of -each outgoing packet with their own address to ensure replies arrive on the -same interface. The load balancer handles this through automatically generated -Source NAT (SNAT) rules applied only to balanced traffic. To disable the -automatic generation of SNAT rules when this behavior is not desired, use: - -```none -set load-balancing wan disable-source-nat -``` - - -## Sticky connections - -Inbound connections to a WAN interface can be improperly handled when -replies are sent back to the client. - -```{image} /_static/images/sticky-connections.webp -:align: center -:width: 80% -``` - -When responding to an incoming packet, you may want to ensure the response -leaves from the same interface as the incoming packet. Enable sticky -connections in the load balancer to do this: - -```none -set load-balancing wan sticky-connections inbound -``` - - -## Failover - -In failover mode, one interface is primary and other interfaces are -secondary or spare. The load balancer uses only the primary interface. If it -fails, a secondary interface from the available pool takes over. The load -balancer selects the primary interface based on its weight and health. Other -interfaces become secondary. Secondary interfaces are chosen based on their -weight and health. You can also select interface roles based on rule order by -including interfaces in balancing rules and ordering those rules accordingly. -To enable failover mode, create a failover rule: - -```none -set load-balancing wan rule failover -``` - -Existing sessions do not automatically fail over to a new path. Flush the -session table on each connection state change to enable failover: - -```none -set load-balancing wan flush-connections -``` - -:::{warning} -Flushing the session table causes other connections to revert from -flow-based to packet-based balancing until each flow is reestablished. -::: - -## Script execution - -Run a script when an interface state changes. Scripts run from the -`/config/scripts` directory. To use a script in another location, -specify the full path: - -```none -set load-balancing wan hook script-name -``` - -Two environment variables are available: -- `WLB_INTERFACE_NAME=[interfacename]`: Interface to be monitored -- `WLB_INTERFACE_STATE=[ACTIVE|FAILED]`: Interface state - -:::{warning} -Blocking call with no timeout: VyOS becomes unresponsive if the -script does not return. -::: - -## Handling and monitoring - -The following command shows WAN load balancer information including test -types and targets. The character at the start of each line indicates the test -state: -- `+` successful. -- `-` failed. -- A blank indicates that no test has been carried out. - -```none -vyos@vyos:~$ show wan-load-balance -Interface: eth0 -Status: failed -Last Status Change: Tue Jun 11 20:12:19 2019 --Test: ping Target: - Last Interface Success: 55s - Last Interface Failure: 0s - # Interface Failure(s): 5 - -Interface: eth1 -Status: active -Last Status Change: Tue Jun 11 20:06:42 2019 -+Test: ping Target: - Last Interface Success: 0s - Last Interface Failure: 6m26s - # Interface Failure(s): 0 -``` - -Show connection data of load balanced traffic: - -```none -vyos@vyos:~$ show wan-load-balance connection -conntrack v1.4.2 (conntrack-tools): 3 flow entries have been shown. -Type State Src Dst Packets Bytes -tcp TIME_WAIT 10.1.1.13:38040 203.0.113.2:80 203.0.113.2 192.168.188.71 -udp 10.1.1.13:41891 198.51.100.3:53 198.51.100.3 192.168.188.71 -udp 10.1.1.13:55437 198.51.100.3:53 198.51.100.3 192.168.188.71 -``` - - -### Restart - -```none -restart wan-load-balance -``` diff --git a/docs/configuration/md-index.md b/docs/configuration/md-index.md deleted file mode 100644 index 3e215502..00000000 --- a/docs/configuration/md-index.md +++ /dev/null @@ -1,23 +0,0 @@ -# Configuration Guide - -The following structure represents the CLI structure. - -```{toctree} -:includehidden: true -:maxdepth: 1 - -container/index -firewall/index -highavailability/index -interfaces/index -loadbalancing/index -nat/index -policy/index -pki/index -protocols/index -service/index -system/index -trafficpolicy/index -vpn/index -vrf/index -``` diff --git a/docs/configuration/nat/md-cgnat.md b/docs/configuration/nat/md-cgnat.md deleted file mode 100644 index 914a466b..00000000 --- a/docs/configuration/nat/md-cgnat.md +++ /dev/null @@ -1,200 +0,0 @@ -(cgnat)= - -# CGNAT - -{abbr}`CGNAT (Carrier-Grade Network Address Translation)` , also known as -Large-Scale NAT (LSN), is a type of network address translation used by -Internet Service Providers (ISPs) to enable multiple private IP addresses to -share a single public IP address. This technique helps to conserve the limited -IPv4 address space. -The 100.64.0.0/10 address block is reserved for use in carrier-grade NAT - -## Overview - -CGNAT works by placing a NAT device within the ISP's network. This device -translates private IP addresses from customer networks to a limited pool of -public IP addresses assigned to the ISP. This allows many customers to share a -smaller number of public IP addresses. - -Not all {rfc}`6888` requirements are implemented in CGNAT. - -Implemented the following {rfc}`6888` requirements: - -- REQ 2: A CGN must have a default "IP address pooling" behavior of "Paired". - CGN must use the same external IP address mapping for all sessions associated - with the same internal IP address, be they TCP, UDP, ICMP, something else, - or a mix of different protocols. -- REQ 3: The CGN function should not have any limitations on the size or the - contiguity of the external address pool. -- REQ 4: A CGN must support limiting the number of external ports (or, - equivalently, "identifiers" for ICMP) that are assigned per subscriber - -### Advantages of CGNAT - -- **IPv4 Address Conservation**: CGNAT helps mitigate the exhaustion of IPv4 addresses by allowing multiple customers to share a single public IP address. -- **Scalability**: ISPs can support more customers without needing a proportional increase in public IP addresses. -- **Cost-Effective**: Reduces the cost associated with acquiring additional public IPv4 addresses. - -### Considerations - -- **Traceability Issues**: Since multiple users share the same public IP address, tracking individual users for security and legal purposes can be challenging. -- **Performance Overheads**: The translation process can introduce latency and potential performance bottlenecks, especially under high load. -- **Application Compatibility**: Some applications and protocols may not work well with CGNAT due to their reliance on unique public IP addresses. -- **Port Allocation Limits**: Each public IP address has a limited number of ports, which can be exhausted, affecting the ability to establish new connections. -- **Port Control Protocol**: PCP is not implemented. - -## Port calculation - -When implementing CGNAT, ensuring that there are enough ports allocated per subscriber is critical. Below is a summary based on RFC 6888. - -1. **Total Ports Available**: - - - Total Ports: 65536 (0 to 65535) - - Reserved Ports: Assume 1024 ports are reserved for well-known services and administrative purposes. - - Usable Ports: 65536 - 1024 = 64512 - -2. **Estimate Ports Needed per Subscriber**: - - - Example: A household might need 1000 ports to ensure smooth operation for multiple devices and applications. - -3. **Calculate the Number of Subscribers per Public IP**: - - - Usable Ports / Ports per Subscriber - - 64512 / 1000 ≈ 64 subscribers per public IP - -## Configuration - -```{cfgcmd} set nat cgnat pool external \ external-port-range \ - -Set an external port-range for the external pool, the default range is -1024-65535. Multiple entries can be added to the same pool. -``` - - -```{cfgcmd} set nat cgnat pool external \ per-user-limit port \ - -Set external source port limits that will be allocated to each subscriber -individually. The default value is 2000. -``` - - -```{cfgcmd} set nat cgnat pool external \ range [address | address range | network] [seq] - -Set the range of external IP addresses for the CGNAT pool. -The sequence is optional; if set, a lower value means higher priority. -``` - - -```{cfgcmd} set nat cgnat pool internal \ range [address range | network] - -Set the range of internal IP addresses for the CGNAT pool. -``` - - -```{cfgcmd} set nat cgnat rule \ source pool \ - -Set the rule for the source pool. -``` - - -```{cfgcmd} set nat cgnat rule \ translation pool \ - -Set the rule for the translation pool. -``` - - -```{cfgcmd} set nat cgnat log-allocation - -Enable logging of IP address and ports allocations. -``` - - -## Configuration Examples - -### Single external address - -Example of setting up a basic CGNAT configuration: -In the following example, we define an external pool named `ext-1` with one -external IP address. - -Each subscriber will be allocated a maximum of 2000 ports from the external pool. - -```none -set nat cgnat pool external ext1 external-port-range '1024-65535' -set nat cgnat pool external ext1 per-user-limit port '2000' -set nat cgnat pool external ext1 range '192.0.2.222/32' -set nat cgnat pool internal int1 range '100.64.0.0/28' -set nat cgnat rule 10 source pool 'int1' -set nat cgnat rule 10 translation pool 'ext1' -``` - - -### Multiple external addresses - -```none -set nat cgnat pool external ext1 external-port-range '1024-65535' -set nat cgnat pool external ext1 per-user-limit port '8000' -set nat cgnat pool external ext1 range '192.0.2.1-192.0.2.2' -set nat cgnat pool external ext1 range '203.0.113.253-203.0.113.254' -set nat cgnat pool internal int1 range '100.64.0.1-100.64.0.32' -set nat cgnat rule 10 source pool 'int1' -set nat cgnat rule 10 translation pool 'ext1' -``` - - -### External address sequences - -```none -set nat cgnat pool external ext-01 per-user-limit port '16000' -set nat cgnat pool external ext-01 range 203.0.113.1/32 seq '10' -set nat cgnat pool external ext-01 range 192.0.2.1/32 seq '20' -set nat cgnat pool internal int-01 range '100.64.0.0/29' -set nat cgnat rule 10 source pool 'int-01' -set nat cgnat rule 10 translation pool 'ext-01' -``` - - -## Operation commands - -```{opcmd} show nat cgnat allocation - -Show address and port allocations -``` - -```{opcmd} show nat cgnat allocation external-address \ - -Show all allocations for an external IP address -``` - -```{opcmd} show nat cgnat allocation internal-address \ - -Show all allocations for an internal IP address -``` - - -### Show CGNAT allocations - -```none -vyos@vyos:~$ show nat cgnat allocation -Internal IP External IP Port range -------------- ------------- ------------ -100.64.0.0 203.0.113.1 1024-17023 -100.64.0.1 203.0.113.1 17024-33023 -100.64.0.2 203.0.113.1 33024-49023 -100.64.0.3 203.0.113.1 49024-65023 -100.64.0.4 192.0.2.1 1024-17023 -100.64.0.5 192.0.2.1 17024-33023 -100.64.0.6 192.0.2.1 33024-49023 -100.64.0.7 192.0.2.1 49024-65023 - -vyos@vyos:~$ show nat cgnat allocation internal-address 100.64.0.4 -Internal IP External IP Port range -------------- ------------- ------------ -100.64.0.4 192.0.2.1 1024-17023 -``` - - -## Further Reading - -- {rfc}`6598` - IANA-Reserved IPv4 Prefix for Shared Address Space -- {rfc}`6888` - Requirements for CGNAT diff --git a/docs/configuration/nat/md-index.md b/docs/configuration/nat/md-index.md deleted file mode 100644 index 35e5d32b..00000000 --- a/docs/configuration/nat/md-index.md +++ /dev/null @@ -1,13 +0,0 @@ -(nat)= - -# NAT - -```{toctree} -:includehidden: true -:maxdepth: 1 - -nat44 -nat64 -nat66 -cgnat -``` diff --git a/docs/configuration/nat/md-nat44.md b/docs/configuration/nat/md-nat44.md deleted file mode 100644 index 4f5bd580..00000000 --- a/docs/configuration/nat/md-nat44.md +++ /dev/null @@ -1,788 +0,0 @@ -(nat44)= - -# NAT44 - -{abbr}`NAT (Network Address Translation)` is a common method of -remapping one IP address space into another by modifying network address -information in the IP header of packets while they are in transit across -a traffic routing device. The technique was originally used as a -shortcut to avoid the need to readdress every host when a network was -moved. It has become a popular and essential tool in conserving global -address space in the face of IPv4 address exhaustion. One -Internet-routable IP address of a NAT gateway can be used for an entire -private network. - -IP masquerading is a technique that hides an entire IP address space, -usually consisting of private IP addresses, behind a single IP address -in another, usually public address space. The hidden addresses are -changed into a single (public) IP address as the source address of the -outgoing IP packets so they appear as originating not from the hidden -host but from the routing device itself. Because of the popularity of -this technique to conserve IPv4 address space, the term NAT has become -virtually synonymous with IP masquerading. - -As network address translation modifies the IP address information in -packets, NAT implementations may vary in their specific behavior in -various addressing cases and their effect on network traffic. The -specifics of NAT behavior are not commonly documented by vendors of -equipment containing NAT implementations. - -The computers on an internal network can use any of the addresses set -aside by the {abbr}`IANA (Internet Assigned Numbers Authority)` for -private addressing (see {rfc}`1918`). These reserved IP addresses are -not in use on the Internet, so an external machine will not directly -route to them. The following addresses are reserved for private use: - -- 10.0.0.0 to 10.255.255.255 (CIDR: 10.0.0.0/8) -- 172.16.0.0 to 172.31.255.255 (CIDR: 172.16.0.0/12) -- 192.168.0.0 to 192.168.255.255 (CIDR: 192.168.0.0/16) - -If an ISP deploys a {abbr}`CGN (Carrier-grade NAT)`, and uses -{rfc}`1918` address space to number customer gateways, the risk of -address collision, and therefore routing failures, arises when the -customer network already uses an {rfc}`1918` address space. - -This prompted some ISPs to develop a policy within the {abbr}`ARIN -(American Registry for Internet Numbers)` to allocate new private -address space for CGNs, but ARIN deferred to the IETF before -implementing the policy indicating that the matter was not a typical -allocation issue but a reservation of addresses for technical purposes -(per {rfc}`2860`). - -IETF published {rfc}`6598`, detailing a shared address space for use in -ISP CGN deployments that can handle the same network prefixes occurring -both on inbound and outbound interfaces. ARIN returned address space to -the {abbr}`IANA (Internet Assigned Numbers Authority)` for this -allocation. - -The allocated address block is 100.64.0.0/10. - -Devices evaluating whether an IPv4 address is public must be updated to -recognize the new address space. Allocating more private IPv4 address -space for NAT devices might prolong the transition to IPv6. - -## Overview - -### Different NAT Types - -(source-nat)= - -#### SNAT - -{abbr}`SNAT (Source Network Address Translation)` is the most common -form of {abbr}`NAT (Network Address Translation)` and is typically -referred to simply as NAT. To be more correct, what most people refer -to as {abbr}`NAT (Network Address Translation)` is actually the process -of {abbr}`PAT (Port Address Translation)`, or NAT overload. SNAT is -typically used by internal users/private hosts to access the Internet -\- the source address is translated and thus kept private. - -(destination-nat)= - -#### DNAT - -{abbr}`DNAT (Destination Network Address Translation)` changes the -destination address of packets passing through the router, while -{ref}`source-nat` changes the source address of packets. DNAT is -typically used when an external (public) host needs to initiate a -session with an internal (private) host. A customer needs to access a -private service behind the routers public IP. A connection is -established with the routers public IP address on a well known port and -thus all traffic for this port is rewritten to address the internal -(private) host. - -(bidirectional-nat)= - -#### Bidirectional NAT - -This is a common scenario where both {ref}`source-nat` and -{ref}`destination-nat` are configured at the same time. It's commonly -used when internal (private) hosts need to establish a connection with -external resources and external systems need to access internal -(private) resources. - -### NAT, Routing, Firewall Interaction - -There is a very nice picture/explanation in the Vyatta documentation -which should be rewritten here. - -### NAT Ruleset - -{abbr}`NAT (Network Address Translation)` is configured entirely on a -series of so called *rules*. Rules are numbered and evaluated by the -underlying OS in numerical order! The rule numbers can be changes by -utilizing the {cfgcmd}`rename` and {cfgcmd}`copy` commands. - -:::{note} -Changes to the NAT system only affect newly established -connections. Already established connections are not affected. -::: - -:::{hint} -When designing your NAT ruleset leave some space between -consecutive rules for later extension. Your ruleset could start with -numbers 10, 20, 30. You thus can later extend the ruleset and place -new rules between existing ones. -::: - -Rules will be created for both {ref}`source-nat` and -{ref}`destination-nat`. - -For {ref}`bidirectional-nat` a rule for both {ref}`source-nat` and -{ref}`destination-nat` needs to be created. - -(traffic-filters)= - -### Traffic Filters - -Traffic Filters are used to control which packets will have the defined -NAT rules applied. Five different filters can be applied within a NAT -rule. - -- **outbound-interface** - applicable only to {ref}`source-nat`. It - configures the interface which is used for the outside traffic that - this translation rule applies to. Interface groups, inverted - selection and wildcard, are also supported. - - Examples: - - ```none - set nat source rule 20 outbound-interface name eth0 - set nat source rule 30 outbound-interface name bond1* - set nat source rule 20 outbound-interface name !vtun2 - set nat source rule 20 outbound-interface group GROUP1 - set nat source rule 20 outbound-interface group !GROUP2 - ``` - -- **inbound-interface** - applicable only to {ref}`destination-nat`. It - configures the interface which is used for the inside traffic the - translation rule applies to. Interface groups, inverted - selection and wildcard, are also supported. - - Example: - - ```none - set nat destination rule 20 inbound-interface name eth0 - set nat destination rule 30 inbound-interface name bond1* - set nat destination rule 20 inbound-interface name !vtun2 - set nat destination rule 20 inbound-interface group GROUP1 - set nat destination rule 20 inbound-interface group !GROUP2 - ``` - -- **protocol** - specify which types of protocols this translation rule - applies to. Only packets matching the specified protocol are NATed. - By default this applies to *all* protocols. - - Example: - - - Set SNAT rule 20 to only NAT TCP and UDP packets - - Set DNAT rule 20 to only NAT UDP packets - - ```none - set nat source rule 20 protocol tcp_udp - set nat destination rule 20 protocol udp - ``` - -- **source** - specifies which packets the NAT translation rule applies - to based on the packets source IP address and/or source port. Only - matching packets are considered for NAT. - - Example: - - - Set SNAT rule 20 to only NAT packets arriving from the 192.0.2.0/24 - network - - Set SNAT rule 30 to only NAT packets arriving from the 203.0.113.0/24 - network with a source port of 80 and 443 - - ```none - set nat source rule 20 source address 192.0.2.0/24 - set nat source rule 30 source address 203.0.113.0/24 - set nat source rule 30 source port 80,443 - ``` - -- **destination** - specify which packets the translation will be - applied to, only based on the destination address and/or port number - configured. - - :::{note} - If no destination is specified the rule will match on any - destination address and port. - ::: - - Example: - - - Configure SNAT rule (40) to only NAT packets with a destination - address of 192.0.2.1. - - ```none - set nat source rule 40 destination address 192.0.2.1 - ``` - -### Address Conversion - -Every NAT rule has a translation command defined. The address defined -for the translation is the address used when the address information in -a packet is replaced. - -#### Source Address - -For {ref}`source-nat` rules the packets source address will be replaced -with the address specified in the translation command. A port -translation can also be specified and is part of the translation -address. - -:::{note} -The translation address must be set to one of the available -addresses on the configured *outbound-interface* or it must be set to -*masquerade* which will use the primary IP address of the -*outbound-interface* as its translation address. -::: - -:::{note} -When using NAT for a large number of host systems it -recommended that a minimum of 1 IP address is used to NAT every 256 -private host systems. This is due to the limit of 65,000 port numbers -available for unique translations and a reserving an average of -200-300 sessions per host system. -::: - -Example: - -- Define a discrete source IP address of 100.64.0.1 for SNAT rule 20 -- Use address *masquerade* (the interfaces primary address) on rule 30 -- For a large amount of private machines behind the NAT your address - pool might to be bigger. Use any address in the range 100.64.0.10 - - 100.64.0.20 on SNAT rule 40 when doing the translation - -```none -set nat source rule 20 translation address 100.64.0.1 -set nat source rule 30 translation address 'masquerade' -set nat source rule 40 translation address 100.64.0.10-100.64.0.20 -``` - -#### Destination Address - -For {ref}`destination-nat` rules the packets destination address will be -replaced by the specified address in the *translation address* command. - -Example: - -- DNAT rule 10 replaces the destination address of an inbound packet - with 192.0.2.10 - -```none -set nat destination rule 10 translation address 192.0.2.10 -``` - -Also, in {ref}`destination-nat`, redirection to localhost is supported. -The redirect statement is a special form of dnat which always translates -the destination address to the local host’s one. - -Example of redirection: - -```none -set nat destination rule 10 translation redirect port 22 -``` - -### NAT Load Balance - -Advanced configuration can be used in order to apply source or destination NAT, -and within a single rule, be able to define multiple translated addresses, -so NAT balances the translations among them. - -NAT Load Balance uses an algorithm that generates a hash and based on it, then -it applies corresponding translation. This hash can be generated randomly, or -can use data from the ip header: source-address, destination-address, -source-port and/or destination-port. By default, it will generate the hash -randomly. - -When defining the translated address, called `backends`, a `weight` must -be configured. This lets the user define load balance distribution according -to their needs. Them sum of all the weights defined for the backends should -be equal to 100. In oder words, the weight defined for the backend is the -percentage of the connections that will receive such backend. - -```{cfgcmd} set nat [source | destination] rule \ load-balance hash [source-address | destination-address | source-port | destination-port | random] -``` - -```{cfgcmd} set nat [source | destination] rule \ load-balance backend \ weight \<1-100\> -``` - -## Configuration Examples - -To setup SNAT, we need to know: -- The internal IP addresses we want to translate -- The outgoing interface to perform the translation on -- The external IP address to translate to - -In the example used for the Quick Start configuration above, we -demonstrate the following configuration: - -```none -set nat source rule 100 outbound-interface name 'eth0' -set nat source rule 100 source address '192.168.0.0/24' -set nat source rule 100 translation address 'masquerade' -``` - -Which generates the following configuration: - -```none -rule 100 { - outbound-interface { - name eth0 - } - source { - address 192.168.0.0/24 - } - translation { - address masquerade - } -} -``` - -In this example, we use **masquerade** as the translation address -instead of an IP address. The **masquerade** target is effectively an -alias to say "use whatever IP address is on the outgoing interface", -rather than a statically configured IP address. This is useful if you -use DHCP for your outgoing interface and do not know what the external -address will be. - -When using NAT for a large number of host systems it recommended that a -minimum of 1 IP address is used to NAT every 256 host systems. This is -due to the limit of 65,000 port numbers available for unique -translations and a reserving an average of 200-300 sessions per host -system. - -Example: For an ~8,000 host network a source NAT pool of 32 IP addresses -is recommended. - -A pool of addresses can be defined by using a hyphen between two IP -addresses: - -```none -set nat source rule 100 translation address '203.0.113.32-203.0.113.63' -``` - -(avoidng-leaky-nat)= - -### Avoiding "leaky" NAT - -Linux netfilter will not NAT traffic marked as INVALID. This often -confuses people into thinking that Linux (or specifically VyOS) has a -broken NAT implementation because non-NATed traffic is seen leaving an -external interface. This is actually working as intended, and a packet -capture of the "leaky" traffic should reveal that the traffic is either -an additional TCP "RST", "FIN,ACK", or "RST,ACK" sent by client systems -after Linux netfilter considers the connection closed. The most common -is the additional TCP RST some host implementations send after -terminating a connection (which is implementation-specific). - -In other words, connection tracking has already observed the connection -be closed and has transition the flow to INVALID to prevent attacks from -attempting to reuse the connection. - -You can avoid the "leaky" behavior by using a firewall policy that drops -"invalid" state packets. - -Having control over the matching of INVALID state traffic, e.g. the -ability to selectively log, is an important troubleshooting tool for -observing broken protocol behavior. For this reason, VyOS does not -globally drop invalid state traffic, instead allowing the operator to -make the determination on how the traffic is handled. - -(hairpin-nat-reflection)= - -### Hairpin NAT/NAT Reflection - -A typical problem with using NAT and hosting public servers is the -ability for internal systems to reach an internal server using it's -external IP address. The solution to this is usually the use of -split-DNS to correctly point host systems to the internal address when -requests are made internally. Because many smaller networks lack DNS -infrastructure, a work-around is commonly deployed to facilitate the -traffic by NATing the request from internal hosts to the source address -of the internal interface on the firewall. - -This technique is commonly referred to as NAT Reflection or Hairpin NAT. - -Example: - -- Redirect Microsoft RDP traffic from the outside (WAN, external) world - via {ref}`destination-nat` in rule 100 to the internal, private host - 192.0.2.40. -- Redirect Microsoft RDP traffic from the internal (LAN, private) - network via {ref}`destination-nat` in rule 110 to the internal, - private host 192.0.2.40. We also need a {ref}`source-nat` rule 110 for - the reverse path of the traffic. The internal network 192.0.2.0/24 is - reachable via interface *eth0.10*. - -```none -set nat destination rule 100 description 'Regular destination NAT from external' -set nat destination rule 100 destination port '3389' -set nat destination rule 100 inbound-interface name 'pppoe0' -set nat destination rule 100 protocol 'tcp' -set nat destination rule 100 translation address '192.0.2.40' - -set nat destination rule 110 description 'NAT Reflection: INSIDE' -set nat destination rule 110 destination port '3389' -set nat destination rule 110 inbound-interface name 'eth0.10' -set nat destination rule 110 protocol 'tcp' -set nat destination rule 110 translation address '192.0.2.40' - -set nat source rule 110 description 'NAT Reflection: INSIDE' -set nat source rule 110 destination address '192.0.2.0/24' -set nat source rule 110 outbound-interface name 'eth0.10' -set nat source rule 110 protocol 'tcp' -set nat source rule 110 source address '192.0.2.0/24' -set nat source rule 110 translation address 'masquerade' -``` - -Which results in a configuration of: - -```none -vyos@vyos# show nat - destination { - rule 100 { - description "Regular destination NAT from external" - destination { - port 3389 - } - inbound-interface { - name pppoe0 - } - protocol tcp - translation { - address 192.0.2.40 - } - } - rule 110 { - description "NAT Reflection: INSIDE" - destination { - port 3389 - } - inbound-interface { - name eth0.10 - } - protocol tcp - translation { - address 192.0.2.40 - } - } - } - source { - rule 110 { - description "NAT Reflection: INSIDE" - destination { - address 192.0.2.0/24 - } - outbound-interface { - name eth0.10 - } - protocol tcp - source { - address 192.0.2.0/24 - } - translation { - address masquerade - } - } - } -``` - -### Destination NAT - -DNAT is typically referred to as a **Port Forward**. When using VyOS as -a NAT router and firewall, a common configuration task is to redirect -incoming traffic to a system behind the firewall. - -In this example, we will be using the example Quick Start configuration -above as a starting point. - -To setup a destination NAT rule we need to gather: -- The interface traffic will be coming in on; -- The protocol and port we wish to forward; -- The IP address of the internal system we wish to forward traffic to. - -In our example, we will be forwarding web server traffic to an internal -web server on 192.168.0.100. HTTP traffic makes use of the TCP protocol -on port 80. For other common port numbers, see: - - -Our configuration commands would be: - -```none -set nat destination rule 10 description 'Port Forward: HTTP to 192.168.0.100' -set nat destination rule 10 destination port '80' -set nat destination rule 10 inbound-interface name 'eth0' -set nat destination rule 10 protocol 'tcp' -set nat destination rule 10 translation address '192.168.0.100' -``` - -Which would generate the following NAT destination configuration: - -```none -nat { - destination { - rule 10 { - description "Port Forward: HTTP to 192.168.0.100" - destination { - port 80 - } - inbound-interface { - name eth0 - } - protocol tcp - translation { - address 192.168.0.100 - } - } - } -} -``` -:::{note} -If forwarding traffic to a different port than it is arriving -on, you may also configure the translation port using -*set nat destination rule [n] translation port*. -::: - -This establishes our Port Forward rule, but if we created a firewall -policy it will likely block the traffic. - -#### Firewall rules for Destination NAT - -It is important to note that when creating firewall rules, the DNAT -translation occurs **before** traffic traverses the firewall. In other -words, the destination address has already been translated to -192.168.0.100. - -So in our firewall ruleset, we want to allow traffic which previously matched -a destination nat rule. In order to avoid creating many rules, one for each -destination nat rule, we can accept all **'dnat'** connections with one simple -rule, using `connection-status` matcher: - -```none -set firewall ipv4 forward filter rule 10 action accept -set firewall ipv4 forward filter rule 10 connection-status nat destination -set firewall ipv4 forward filter rule 10 state new -``` - -This would generate the following configuration: - -```none -ipv4 { - forward { - filter { - rule 10 { - action accept - connection-status { - nat destination - } - state new - } - } - } -} -``` - -### 1-to-1 NAT - -Another term often used for DNAT is **1-to-1 NAT**. For a 1-to-1 NAT -configuration, both DNAT and SNAT are used to NAT all traffic from an -external IP address to an internal IP address and vice-versa. - -Typically, a 1-to-1 NAT rule omits the destination port (all ports) and -replaces the protocol with either **all** or **ip**. - -Then a corresponding SNAT rule is created to NAT outgoing traffic for -the internal IP to a reserved external IP. This dedicates an external IP -address to an internal IP address and is useful for protocols which -don't have the notion of ports, such as GRE. - -Here's an extract of a simple 1-to-1 NAT configuration with one internal -and one external interface: - -```none -set interfaces ethernet eth0 address '192.168.1.1/24' -set interfaces ethernet eth0 description 'Inside interface' -set interfaces ethernet eth1 address '192.0.2.30/24' -set interfaces ethernet eth1 description 'Outside interface' -set nat destination rule 2000 description '1-to-1 NAT example' -set nat destination rule 2000 destination address '192.0.2.30' -set nat destination rule 2000 inbound-interface name 'eth1' -set nat destination rule 2000 translation address '192.168.1.10' -set nat source rule 2000 description '1-to-1 NAT example' -set nat source rule 2000 outbound-interface name 'eth1' -set nat source rule 2000 source address '192.168.1.10' -set nat source rule 2000 translation address '192.0.2.30' -``` - -Firewall rules are written as normal, using the internal IP address as -the source of outbound rules and the destination of inbound rules. - -### NAT before VPN - -Some application service providers (ASPs) operate a VPN gateway to -provide access to their internal resources, and require that a -connecting organisation translate all traffic to the service provider -network to a source address provided by the ASP. - -### Load Balance - -Here we provide two examples on how to apply NAT Load Balance. - -First scenario: apply destination NAT for all HTTP traffic comming through -interface eth0, and user 4 backends. First backend should received 30% of -the request, second backend should get 20%, third 15% and the fourth 35% -We will use source and destination address for hash generation. - -```none -set nat destination rule 10 inbound-interface name eth0 -set nat destination rule 10 protocol tcp -set nat destination rule 10 destination port 80 -set nat destination rule 10 load-balance hash source-address -set nat destination rule 10 load-balance hash destination-address -set nat destination rule 10 load-balance backend 198.51.100.101 weight 30 -set nat destination rule 10 load-balance backend 198.51.100.102 weight 20 -set nat destination rule 10 load-balance backend 198.51.100.103 weight 15 -set nat destination rule 10 load-balance backend 198.51.100.104 weight 35 -``` - -Second scenario: apply source NAT for all outgoing connections from -LAN 10.0.0.0/8, using 3 public addresses and equal distribution. -We will generate the hash randomly. - -```none -set nat source rule 10 outbound-interface name eth0 -set nat source rule 10 source address 10.0.0.0/8 -set nat source rule 10 load-balance hash random -set nat source rule 10 load-balance backend 192.0.2.251 weight 33 -set nat source rule 10 load-balance backend 192.0.2.252 weight 33 -set nat source rule 10 load-balance backend 192.0.2.253 weight 34 -``` - -#### Example Network - -Here's one example of a network environment for an ASP. -The ASP requests that all connections from this company should come from -172.29.41.89 - an address that is assigned by the ASP and not in use at -the customer site. - -```{eval-rst} -.. figure:: /_static/images/nat_before_vpn_topology.webp - :scale: 100 % - :alt: NAT before VPN Topology - - NAT before VPN Topology -``` -#### Configuration - -The required configuration can be broken down into 4 major pieces: -- A dummy interface for the provider-assigned IP; -- NAT (specifically, Source NAT); -- IPSec IKE and ESP Groups; -- IPSec VPN tunnels. - -##### Dummy interface - -The dummy interface allows us to have an equivalent of the Cisco IOS -Loopback interface - a router-internal interface we can use for IP -addresses the router must know about, but which are not actually -assigned to a real network. - -We only need a single step for this interface: - -```none -set interfaces dummy dum0 address '172.29.41.89/32' -``` - -##### NAT Configuration - -```none -set nat source rule 110 description 'Internal to ASP' -set nat source rule 110 destination address '172.27.1.0/24' -set nat source rule 110 source address '192.168.43.0/24' -set nat source rule 110 translation address '172.29.41.89' -set nat source rule 120 description 'Internal to ASP' -set nat source rule 120 destination address '10.125.0.0/16' -set nat source rule 120 source address '192.168.43.0/24' -set nat source rule 120 translation address '172.29.41.89' -``` - -##### IPSec IKE and ESP - -The ASP has documented their IPSec requirements: -- IKE Phase: - - aes256 Encryption - - sha256 Hashes -- ESP Phase: - - aes256 Encryption - - sha256 Hashes - - DH Group 14 - -Additionally, we want to use VPNs only on our eth1 interface (the -external interface in the image above) - -```none -set vpn ipsec ike-group my-ike key-exchange 'ikev1' -set vpn ipsec ike-group my-ike lifetime '7800' -set vpn ipsec ike-group my-ike proposal 1 dh-group '14' -set vpn ipsec ike-group my-ike proposal 1 encryption 'aes256' -set vpn ipsec ike-group my-ike proposal 1 hash 'sha256' - -set vpn ipsec esp-group my-esp lifetime '3600' -set vpn ipsec esp-group my-esp mode 'tunnel' -set vpn ipsec esp-group my-esp pfs 'disable' -set vpn ipsec esp-group my-esp proposal 1 encryption 'aes256' -set vpn ipsec esp-group my-esp proposal 1 hash 'sha256' - -set vpn ipsec interface 'eth1' -``` - -##### IPSec VPN Tunnels - -We'll use the IKE and ESP groups created above for this VPN. Because we -need access to 2 different subnets on the far side, we will need two -different tunnels. If you changed the names of the ESP group and IKE -group in the previous step, make sure you use the correct names here -too. - -```none -set vpn ipsec authentication psk vyos id '203.0.113.46' -set vpn ipsec authentication psk vyos id '198.51.100.243' -set vpn ipsec authentication psk vyos secret 'MYSECRETPASSWORD' -set vpn ipsec site-to-site peer branch authentication local-id '203.0.113.46' -set vpn ipsec site-to-site peer branch authentication mode 'pre-shared-secret' -set vpn ipsec site-to-site peer branch authentication remote-id '198.51.100.243' -set vpn ipsec site-to-site peer branch connection-type 'initiate' -set vpn ipsec site-to-site peer branch default-esp-group 'my-esp' -set vpn ipsec site-to-site peer branch ike-group 'my-ike' -set vpn ipsec site-to-site peer branch ikev2-reauth 'inherit' -set vpn ipsec site-to-site peer branch local-address '203.0.113.46' -set vpn ipsec site-to-site peer branch remote-address '198.51.100.243' -set vpn ipsec site-to-site peer branch tunnel 0 local prefix '172.29.41.89/32' -set vpn ipsec site-to-site peer branch tunnel 0 remote prefix '172.27.1.0/24' -set vpn ipsec site-to-site peer branch tunnel 1 local prefix '172.29.41.89/32' -set vpn ipsec site-to-site peer branch tunnel 1 remote prefix '10.125.0.0/16' -``` - -##### Testing and Validation - -If you've completed all the above steps you no doubt want to see if it's -all working. - -Start by checking for IPSec SAs (Security Associations) with: - -```none -$ show vpn ipsec sa - -Peer ID / IP Local ID / IP ------------- ------------- -198.51.100.243 203.0.113.46 - - Tunnel State Bytes Out/In Encrypt Hash NAT-T A-Time L-Time Proto - ------ ----- ------------- ------- ---- ----- ------ ------ ----- - 0 up 0.0/0.0 aes256 sha256 no 1647 3600 all - 1 up 0.0/0.0 aes256 sha256 no 865 3600 all -``` - -That looks good - we defined 2 tunnels and they're both up and running. diff --git a/docs/configuration/nat/md-nat64.md b/docs/configuration/nat/md-nat64.md deleted file mode 100644 index c1b1c994..00000000 --- a/docs/configuration/nat/md-nat64.md +++ /dev/null @@ -1,73 +0,0 @@ -(nat64)= - -# NAT64 - -{abbr}`NAT64 (IPv6-to-IPv4 Prefix Translation)` is a critical component in -modern networking, facilitating communication between IPv6 and IPv4 networks. -This documentation outlines the setup, configuration, and usage of the NAT64 -feature in your project. Whether you are transitioning to IPv6 or need to -seamlessly connect IPv4 and IPv6 devices. -NAT64 is a stateful translation mechanism that translates IPv6 addresses to -IPv4 addresses and IPv4 addresses to IPv6 addresses. NAT64 is used to enable -IPv6-only clients to contact IPv4 servers using unicast UDP, TCP, or ICMP. - -## Overview - -### Different NAT Types - -(source-nat64)= - -#### SNAT64 - -{abbr}`SNAT64 (IPv6-to-IPv4 Source Address Translation)` is a stateful -translation mechanism that translates IPv6 addresses to IPv4 addresses. - -`64:ff9b::/96` is the well-known prefix for IPv4-embedded IPv6 addresses. -The prefix is used to represent IPv4 addresses in an IPv6 address format. -The IPv4 address is encoded in the low-order 32 bits of the IPv6 address. -The high-order 32 bits are set to the well-known prefix 64:ff9b::/96. - -## Configuration Examples - -The following examples show how to configure NAT64 on a VyOS router. -The 192.0.2.10 address is used as the IPv4 address for the translation pool. - -NAT64 server configuration: - -```none -set interfaces ethernet eth0 address '192.0.2.1/24' -set interfaces ethernet eth0 address '192.0.2.10/24' -set interfaces ethernet eth0 description 'WAN' -set interfaces ethernet eth1 address '2001:db8::1/64' -set interfaces ethernet eth1 description 'LAN' - -set service dns forwarding allow-from '2001:db8::/64' -set service dns forwarding dns64-prefix '64:ff9b::/96' -set service dns forwarding listen-address '2001:db8::1' - -set nat64 source rule 100 source prefix '64:ff9b::/96' -set nat64 source rule 100 translation pool 10 address '192.0.2.10' -set nat64 source rule 100 translation pool 10 port '1-65535' -``` - -NAT64 client configuration: - -```none -set interfaces ethernet eth1 address '2001:db8::2/64' -set protocols static route6 64:ff9b::/96 next-hop 2001:db8::1 -set system name-server '2001:db8::1' -``` - -Test from the IPv6 only client: - -```none -vyos@r1:~$ ping 64:ff9b::192.0.2.1 count 2 -PING 64:ff9b::192.0.2.1(64:ff9b::c000:201) 56 data bytes -64 bytes from 64:ff9b::c000:201: icmp_seq=1 ttl=63 time=0.351 ms -64 bytes from 64:ff9b::c000:201: icmp_seq=2 ttl=63 time=0.373 ms - ---- 64:ff9b::192.0.2.1 ping statistics --- -2 packets transmitted, 2 received, 0% packet loss, time 1023ms -rtt min/avg/max/mdev = 0.351/0.362/0.373/0.011 ms -``` - diff --git a/docs/configuration/nat/md-nat66.md b/docs/configuration/nat/md-nat66.md deleted file mode 100644 index 1cbe3317..00000000 --- a/docs/configuration/nat/md-nat66.md +++ /dev/null @@ -1,243 +0,0 @@ -(nat66)= - -# NAT66(NPTv6) - -```{todo} -Convert raw command blocks in this file to cfgcmd/opcmd -directives for command coverage tracking. -``` - -{abbr}`NPTv6 (IPv6-to-IPv6 Network Prefix Translation)` is an address -translation technology based on IPv6 networks, used to convert an IPv6 -address prefix in an IPv6 message into another IPv6 address prefix. -We call this address translation method NAT66. Devices that support the NAT66 -function are called NAT66 devices, which can provide NAT66 source -and destination address translation functions. - -## Overview - -### Different NAT Types - -(source-nat66)= - -#### SNAT66 - -{abbr}`SNPTv6 (Source IPv6-to-IPv6 Network Prefix Translation)` The conversion -function is mainly used in the following scenarios: -- A single internal network and external network. Use the NAT66 device to - connect a single internal network and public network, and the hosts in - the internal network use IPv6 address prefixes that only support - routing within the local range. When a host in the internal network - accesses the external network, the source IPv6 address prefix in - the message will be converted into a global unicast IPv6 address - prefix by the NAT66 device. -- Redundancy and load sharing. There are multiple NAT66 devices at the edge - of an IPv6 network to another IPv6 network. The path through the NAT66 - device to another IPv6 network forms an equivalent route, and traffic - can be load-shared on these NAT66 devices. In this case, you - can configure the same source address translation rules on these - NAT66 devices, so that any NAT66 device can handle IPv6 traffic between - different sites. -- Multi-homed. In a multi-homed network environment, the NAT66 device - connects to an internal network and simultaneously connects to - different external networks. Address translation can be configured - on each external network side interface of the NAT66 device to - convert the same internal network address into different external - network addresses, and realize the mapping of the same internal - address to multiple external addresses. -(destination-nat66)= - -#### DNAT66 - -The {abbr}`DNPTv6 (Destination IPv6-to-IPv6 Network Prefix Translation)` -destination address translation function is used in scenarios where the -server in the internal network provides services to the external network, -such as providing Web services or FTP services to the external network. -By configuring the mapping relationship between the internal server -address and the external network address on the external network -side interface of the NAT66 device, external network users can -access the internal network server through the designated -external network address. - -### Prefix Conversion - -#### Source Prefix - -Every SNAT66 rule has a translation command defined. The prefix defined -for the translation is the prefix used when the address information in -a packet is replaced.、 - -The {ref}`source-nat66` rule replaces the source address of the packet -and calculates the converted address using the prefix specified in the rule. - -Example: -- Convert the address prefix of a single `fc01::/64` network to `fc00::/64` -- Output from `eth0` network interface - -```none -set nat66 source rule 1 outbound-interface name 'eth0' -set nat66 source rule 1 source prefix 'fc01::/64' -set nat66 source rule 1 translation address 'fc00::/64' -``` - - -#### Destination Prefix - -For the {ref}`destination-nat66` rule, the destination address of -the packet isreplaced by the address calculated from the specified -address or prefix in the `translation address` command - -Example: -- Convert the address prefix of a single `fc00::/64` network - to `fc01::/64` -- Input from `eth0` network interface - -```none -set nat66 destination rule 1 inbound-interface name 'eth0' -set nat66 destination rule 1 destination address 'fc00::/64' -set nat66 destination rule 1 translation address 'fc01::/64' -``` - -For the destination, groups can also be used instead of an address. - -Example: - -```none -set firewall group ipv6-address-group ADR-INSIDE-v6 address fc00::1 - -set nat66 destination rule 1 inbound-interface name 'eth0' -set nat66 destination rule 1 destination group address-group ADR-INSIDE-v6 -set nat66 destination rule 1 translation address 'fc01::/64' -``` - - -## Configuration Examples - -Use the following topology to build a nat66 based isolated -network between internal and external networks (dynamic prefix is -not supported): - -:::{figure} /_static/images/vyos_1_4_nat66_simple.webp -:alt: VyOS NAT66 Simple Configure -::: - -R1: - -```none -set interfaces ethernet eth0 ipv6 address autoconf -set interfaces ethernet eth1 address 'fc01::1/64' -set nat66 destination rule 1 destination address 'fc00:470:f1cd:101::/64' -set nat66 destination rule 1 inbound-interface name 'eth0' -set nat66 destination rule 1 translation address 'fc01::/64' -set nat66 source rule 1 outbound-interface name 'eth0' -set nat66 source rule 1 source prefix 'fc01::/64' -set nat66 source rule 1 translation address 'fc00:470:f1cd:101::/64' -``` - -R2: - -```none -set interfaces bridge br1 address 'fc01::2/64' -set interfaces bridge br1 member interface eth0 -set interfaces bridge br1 member interface eth1 -set protocols static route6 ::/0 next-hop fc01::1 -set service router-advert interface br1 prefix ::/0 -``` - -Use the following topology to translate internal user local addresses -(`fc::/7`) to DHCPv6-PD provided prefixes from an ISP connected to -a VyOS HA pair. - -:::{figure} /_static/images/vyos_1_5_nat66_dhcpv6_wdummy.webp -:alt: VyOS NAT66 DHCPv6 using a dummy interface -::: - -Configure both routers (a and b) for DHCPv6-PD via dummy interface: - -```none -set interfaces dummy dum1 description 'DHCPv6-PD NPT dummy' -set interfaces bonding bond0 vif 20 dhcpv6-options pd 0 interface dum1 address '0' -set interfaces bonding bond0 vif 20 dhcpv6-options pd 1 interface dum1 address '0' -set interfaces bonding bond0 vif 20 dhcpv6-options pd 2 interface dum1 address '0' -set interfaces bonding bond0 vif 20 dhcpv6-options pd 3 interface dum1 address '0' -set interfaces bonding bond0 vif 20 dhcpv6-options rapid-commit -commit -``` - -Get the DHCPv6-PD prefixes from both routers: - -```none -trae@cr01a-vyos# run show interfaces dummy dum1 br -Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down -Interface IP Address S/L Description ---------- ---------- --- ----------- -dum1 2001:db8:123:b008::/64 u/u DHCPv6-PD NPT dummy - 2001:db8:123:b00a::/64 - 2001:db8:123:b00b::/64 - 2001:db8:123:b009::/64 - -trae@cr01b-vyos# run show int dummy dum1 brief -Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down -Interface IP Address S/L Description ---------- ---------- --- ----------- -dum1 2001:db8:123:b00d::/64 u/u DHCPv6-PD NPT dummy - 2001:db8:123:b00c::/64 - 2001:db8:123:b00e::/64 - 2001:db8:123:b00f::/64 -``` - -Configure the A-side router for NPTv6 using the prefixes above: - -```none -set nat66 source rule 10 description 'NPT to VLAN 10' -set nat66 source rule 10 outbound-interface name 'bond0.20' -set nat66 source rule 10 source prefix 'fd52:d62e:8011:a::/64' -set nat66 source rule 10 translation address '2001:db8:123:b008::/64' -set nat66 source rule 20 description 'NPT to VLAN 70' -set nat66 source rule 20 outbound-interface name 'bond0.20' -set nat66 source rule 20 source prefix 'fd52:d62e:8011:46::/64' -set nat66 source rule 20 translation address '2001:db8:123:b009::/64' -set nat66 source rule 30 description 'NPT to VLAN 200' -set nat66 source rule 30 outbound-interface name 'bond0.20' -set nat66 source rule 30 source prefix 'fd52:d62e:8011:c8::/64' -set nat66 source rule 30 translation address '2001:db8:123:b00a::/64' -set nat66 source rule 40 description 'NPT to VLAN 240' -set nat66 source rule 40 outbound-interface name 'bond0.20' -set nat66 source rule 40 source prefix 'fd52:d62e:8011:f0::/64' -set nat66 source rule 40 translation address '2001:db8:123:b00b::/64' -commit -``` - -Configure the B-side router for NPTv6 using the prefixes above: - -```none -set nat66 source rule 10 description 'NPT to VLAN 10' -set nat66 source rule 10 outbound-interface name 'bond0.20' -set nat66 source rule 10 source prefix 'fd52:d62e:8011:a::/64' -set nat66 source rule 10 translation address '2001:db8:123:b00c::/64' -set nat66 source rule 20 description 'NPT to VLAN 70' -set nat66 source rule 20 outbound-interface name 'bond0.20' -set nat66 source rule 20 source prefix 'fd52:d62e:8011:46::/64' -set nat66 source rule 20 translation address '2001:db8:123:b00d::/64' -set nat66 source rule 30 description 'NPT to VLAN 200' -set nat66 source rule 30 outbound-interface name 'bond0.20' -set nat66 source rule 30 source prefix 'fd52:d62e:8011:c8::/64' -set nat66 source rule 30 translation address '2001:db8:123:b00e::/64' -set nat66 source rule 40 description 'NPT to VLAN 240' -set nat66 source rule 40 outbound-interface name 'bond0.20' -set nat66 source rule 40 source prefix 'fd52:d62e:8011:f0::/64' -set nat66 source rule 40 translation address '2001:db8:123:b00f::/64' -commit -``` - -Verify that connections are hitting the rule on both sides: - -```none -trae@cr01a-vyos# run show nat66 source statistics -Rule Packets Bytes Interface ------- --------- ------- ----------- -10 1 104 bond0.20 -20 1 104 bond0.20 -30 8093 669445 bond0.20 -40 2446 216912 bond0.20 -``` diff --git a/docs/configuration/pki/md-index.md b/docs/configuration/pki/md-index.md deleted file mode 100644 index e7d793de..00000000 --- a/docs/configuration/pki/md-index.md +++ /dev/null @@ -1,583 +0,0 @@ ---- -lastproofread: '2024-01-05' ---- - -```{include} /_include/need_improvement.txt -``` - -(pki)= - -# PKI - -VyOS 1.4 changed the way in how encryption keys or certificates are stored on the -system. In the pre VyOS 1.4 era, certificates got stored under /config and every -service referenced a file. That made copying a running configuration from system -A to system B a bit harder, as you had to copy the files and their permissions -by hand. - -{vytask}`T3642` describes a new CLI subsystem that serves as a "certstore" to -all services requiring any kind of encryption key(s). In short, public and -private certificates are now stored in PKCS#8 format in the regular VyOS CLI. -Keys can now be added, edited, and deleted using the regular set/edit/delete -CLI commands. - -VyOS not only can now manage certificates issued by 3rd party Certificate -Authorities, it can also act as a CA on its own. You can create your own root -CA and sign keys with it by making use of some simple op-mode commands. - -Don't be afraid that you need to re-do your configuration. Key transformation is -handled, as always, by our migration scripts, so this will be a smooth transition -for you! - -## Key Generation - -### Certificate Authority (CA) - -VyOS now also has the ability to create CAs, keys, Diffie-Hellman and other -keypairs from an easy to access operational level command. - -```{opcmd} generate pki ca - -Create a new {abbr}`CA (Certificate Authority)` and output the CAs public and -private key on the console. -``` - -```{opcmd} generate pki ca install \ - -Create a new {abbr}`CA (Certificate Authority)` and output the CAs public and -private key on the console. - -:::{note} -In addition to the command above, the output is in a format which can be used -to directly import the key into the VyOS CLI by simply copy-pasting the output -from op-mode into configuration mode. - -``name`` is used for the VyOS CLI command to identify this key. This -key ``name`` is then used in the CLI configuration to reference the key -instance. -::: -``` - -```{opcmd} generate pki ca sign \ - -Create a new subordinate {abbr}`CA (Certificate Authority)` and sign it using -the private key referenced by ca-name. -``` - -```{opcmd} generate pki ca sign \ install \ - -Create a new subordinate {abbr}`CA (Certificate Authority)` and sign it using -the private key referenced by `name`. - -:::{note} -In addition to the command above, the output is in a format which can be used -to directly import the key into the VyOS CLI by simply copy-pasting the output -from op-mode into configuration mode. - -``name`` is used for the VyOS CLI command to identify this key. This -key ``name`` is then used in the CLI configuration to reference the key -instance. -::: -``` - -### Certificates - -```{opcmd} generate pki certificate - -Create a new public/private keypair and output the certificate on the console. -``` - -```{opcmd} generate pki certificate install \ - -Create a new public/private keypair and output the certificate on the console. - -:::{note} -In addition to the command above, the output is in a format which can be used -to directly import the key into the VyOS CLI by simply copy-pasting the output -from op-mode into configuration mode. - -``name`` is used for the VyOS CLI command to identify this key. This -key ``name`` is then used in the CLI configuration to reference the key -instance. -::: -``` - -```{opcmd} generate pki certificate self-signed - -Create a new self-signed certificate. The public/private is then shown on the -console. -``` - -```{opcmd} generate pki certificate self-signed install \ - -Create a new self-signed certificate. The public/private is then shown on the -console. - -:::{note} -In addition to the command above, the output is in a format which can be used -to directly import the key into the VyOS CLI by simply copy-pasting the output -from op-mode into configuration mode. - -``name`` is used for the VyOS CLI command to identify this key. This -key ``name`` is then used in the CLI configuration to reference the key -instance. -::: -``` - -```{opcmd} generate pki certificate sign \ - -Create a new public/private keypair which is signed by the CA referenced by -ca-name. The signed certificate is then output to the console. -``` - -```{opcmd} generate pki certificate sign \ install \ - -Create a new public/private keypair which is signed by the CA referenced by -ca-name. The signed certificate is then output to the console. - -:::{note} -In addition to the command above, the output is in a format which can be used -to directly import the key into the VyOS CLI by simply copy-pasting the output -from op-mode into configuration mode. - -``name`` is used for the VyOS CLI command to identify this key. This -key ``name`` is then used in the CLI configuration to reference the key -instance. -::: -``` - -### Diffie-Hellman parameters - -```{opcmd} generate pki dh - -Generate a new set of {abbr}`DH (Diffie-Hellman)` parameters. The key size -is requested by the CLI and defaults to 2048 bit. - -The generated parameters are then output to the console. -``` - -```{opcmd} generate pki dh install \ - -Generate a new set of {abbr}`DH (Diffie-Hellman)` parameters. The key size -is requested by the CLI and defaults to 2048 bit. - -:::{note} -In addition to the command above, the output is in a format which can be used -to directly import the key into the VyOS CLI by simply copy-pasting the output -from op-mode into configuration mode. - -``name`` is used for the VyOS CLI command to identify this key. This -key ``name`` is then used in the CLI configuration to reference the key -instance. -::: -``` - -### OpenVPN - -```{opcmd} generate pki openvpn shared-secret - -Generate a new OpenVPN shared secret. The generated secret is the output to -the console. -``` - -```{opcmd} generate pki openvpn shared-secret install \ - -Generate a new OpenVPN shared secret. The generated secret is the output to -the console. - -:::{note} -In addition to the command above, the output is in a format which can be used -to directly import the key into the VyOS CLI by simply copy-pasting the output -from op-mode into configuration mode. - -``name`` is used for the VyOS CLI command to identify this key. This -key ``name`` is then used in the CLI configuration to reference the key -instance. -::: -``` - -### WireGuard - -```{opcmd} generate pki wireguard key-pair - -Generate a new WireGuard public/private key portion and output the result to -the console. -``` - -```{opcmd} generate pki wireguard key-pair install \ - -Generate a new WireGuard public/private key portion and output the result to -the console. - -:::{note} -In addition to the command above, the output is in a format which can -be used to directly import the key into the VyOS CLI by simply copy-pasting -the output from op-mode into configuration mode. - -``interface`` is used for the VyOS CLI command to identify the WireGuard -interface where this private key is to be used. -::: -``` - -```{opcmd} generate pki wireguard preshared-key - -Generate a WireGuard pre-shared secret used for peers to communicate. -``` - -```{opcmd} generate pki wireguard preshared-key install \ - -Generate a WireGuard pre-shared secret used for peers to communicate. - -:::{note} -In addition to the command above, the output is in a format which can -be used to directly import the key into the VyOS CLI by simply copy-pasting -the output from op-mode into configuration mode. - -``peer`` is used for the VyOS CLI command to identify the WireGuard peer where -this secret is to be used. -::: -``` - -## Key usage (CLI) -### CA (Certificate Authority) - -```{cfgcmd} set pki ca \ certificate - -Add the public CA certificate for the CA named `name` to the VyOS CLI. - -:::{note} -When loading the certificate you need to manually strip the -``-----BEGIN CERTIFICATE-----`` and ``-----END CERTIFICATE-----`` tags. -Also, the certificate/key needs to be presented in a single line without -line breaks (``\n``), this can be done using the following shell command: - -``$ tail -n +2 ca.pem | head -n -1 | tr -d '\n'`` -::: -``` - -```{cfgcmd} set pki ca \ crl - -Certificate revocation list in PEM format. -``` - -```{cfgcmd} set pki ca \ description - -A human readable description what this CA is about. -``` - -```{cfgcmd} set pki ca \ private key - -Add the CAs private key to the VyOS CLI. This should never leave the system, -and is only required if you use VyOS as your certificate generator as -mentioned above. - -:::{note} -When loading the certificate you need to manually strip the -``-----BEGIN KEY-----`` and ``-----END KEY-----`` tags. Also, the -certificate/key needs to be presented in a single line without line -breaks (``\n``), this can be done using the following shell command: - -``$ tail -n +2 ca.key | head -n -1 | tr -d '\n'`` -::: -``` - -```{cfgcmd} set pki ca \ private password-protected - -Mark the CAs private key as password protected. User is asked for the password -when the key is referenced. -``` - -### Server Certificate - -After we have imported the CA certificate(s) we can now import and add -certificates used by services on this router. - -```{cfgcmd} set pki certificate \ certificate - -Add public key portion for the certificate named `name` to the VyOS CLI. - -:::{note} -When loading the certificate you need to manually strip the -``-----BEGIN CERTIFICATE-----`` and ``-----END CERTIFICATE-----`` tags. -Also, the certificate/key needs to be presented in a single line without -line breaks (``\n``), this can be done using the following shell command: - -``$ tail -n +2 cert.pem | head -n -1 | tr -d '\n'`` -::: -``` - -```{cfgcmd} set pki certificate \ description - -A human readable description what this certificate is about. -``` - -```{cfgcmd} set pki certificate \ private key - -Add the private key portion of this certificate to the CLI. This should never -leave the system as it is used to decrypt the data. - -:::{note} -When loading the certificate you need to manually strip the -``-----BEGIN KEY-----`` and ``-----END KEY-----`` tags. Also, the -certificate/key needs to be presented in a single line without line -breaks (``\n``), this can be done using the following shell command: - -``$ tail -n +2 cert.key | head -n -1 | tr -d '\n'`` -::: -``` - -```{cfgcmd} set pki certificate \ private password-protected - -Mark the private key as password protected. User is asked for the password -when the key is referenced. -``` - -```{cfgcmd} set pki certificate \ revoke - -If CA is present, this certificate will be included in generated CRLs -``` - -### Import files to PKI format - -VyOS provides this utility to import existing certificates/key files directly -into PKI from op-mode. Previous to VyOS 1.4, certificates were stored under the -/config folder permanently and will be retained post upgrade. - -```{opcmd} import pki ca \ file \ - -Import the public CA certificate from the defined file to VyOS CLI. -``` - -```{opcmd} import pki ca \ key-file \ - -Import the CAs private key portion to the CLI. This should never leave the -system as it is used to decrypt the data. The key is required if you use -VyOS as your certificate generator. -``` - -```{opcmd} import pki certificate \ file \ - -Import the certificate from the file to VyOS CLI. -``` - -```{opcmd} import pki certificate \ key-file \ - -Import the private key of the certificate to the VyOS CLI. This should never -leave the system as it is used to decrypt the data. -``` - -```{opcmd} import pki openvpn shared-secret \ file \ - -Import the OpenVPN shared secret stored in file to the VyOS CLI. -``` - -#### ACME - -The VyOS PKI subsystem can also be used to automatically retrieve Certificates -using the {abbr}`ACME (Automatic Certificate Management Environment)` protocol. - -```{cfgcmd} set pki certificate \ acme domain-name \ - -Domain names to apply, multiple domain-names can be specified. - -This is a mandatory option -``` - -```{cfgcmd} set pki certificate \ acme email \ - -Email used for registration and recovery contact. - -This is a mandatory option -``` - -```{cfgcmd} set pki certificate \ acme listen-address \ - -The address the server listens to during http-01 challenge -``` - -```{cfgcmd} set pki certificate \ acme rsa-key-size \<2048 | 3072 | 4096\> - -Size of the RSA key. - -This options defaults to 2048 -``` - -```{cfgcmd} set pki certificate \ acme url \ - -ACME Directory Resource URI. - -This defaults to https://acme-v02.api.letsencrypt.org/directory - -:::{note} -During initial deployment we recommend using the staging API -of LetsEncrypt to prevent and blacklisting of your system. The API -endpoint is https://acme-staging-v02.api.letsencrypt.org/directory -::: -``` - -## Operation - -VyOS operational mode commands are not only available for generating keys but -also to display them. - -```{opcmd} show pki ca - -Show a list of installed {abbr}`CA (Certificate Authority)` certificates. - -:::{code-block} none -vyos@vyos:~$ show pki ca -Certificate Authorities: -Name Subject Issuer CN Issued Expiry Private Key Parent --------------- ------------------------------------------------------- ----------------- ------------------- ------------------- ------------- -------------- -DST_Root_CA_X3 CN=ISRG Root X1,O=Internet Security Research Group,C=US CN=DST Root CA X3 2021-01-20 19:14:03 2024-09-30 18:14:03 No N/A -R3 CN=R3,O=Let's Encrypt,C=US CN=ISRG Root X1 2020-09-04 00:00:00 2025-09-15 16:00:00 No DST_Root_CA_X3 -vyos_rw CN=VyOS RW CA,O=VyOS,L=Some-City,ST=Some-State,C=GB CN=VyOS RW CA 2021-07-05 13:46:03 2026-07-04 13:46:03 Yes N/A -::: -``` - -```{opcmd} show pki ca \ - -Show only information for specified Certificate Authority. -``` - -```{opcmd} show pki certificate - -Show a list of installed certificates - -:::{code-block} none -vyos@vyos:~$ show pki certificate -Certificates: -Name Type Subject CN Issuer CN Issued Expiry Revoked Private Key CA Present ---------- ------ --------------------- ------------- ------------------- ------------------- --------- ------------- ------------- -ac2 Server CN=ac2.vyos.net CN=R3 2021-07-05 07:29:59 2021-10-03 07:29:58 No Yes Yes (R3) -rw_server Server CN=VyOS RW CN=VyOS RW CA 2021-07-05 13:48:02 2022-07-05 13:48:02 No Yes Yes (vyos_rw) -::: -``` - -```{opcmd} show pki certificate \ - -Show only information for specified certificate. -``` - -```{opcmd} show pki crl - -Show a list of installed {abbr}`CRLs (Certificate Revocation List)`. -``` - -```{opcmd} renew certbot - -Manually trigger certificate renewal. This will be done twice a day. -``` - -## Examples - -### Create a CA chain and leaf certificates - -This configuration generates & installs into the VyOS PKI system a root -certificate authority, alongside two intermediary certificate authorities for -client & server certificates. These CAs are then used to generate a server -certificate for the router, and a client certificate for a user. -- `vyos_root_ca` is the root certificate authority. -- `vyos_client_ca` and `vyos_server_ca` are intermediary certificate authorities, - which are signed by the root CA. -- `vyos_cert` is a leaf server certificate used to identify the VyOS router, - signed by the server intermediary CA. -- `vyos_example_user` is a leaf client certificate used to identify a user, - signed by client intermediary CA. - -First, we create the root certificate authority. - -```none -[edit] -vyos@vyos# run generate pki ca install vyos_root_ca -Enter private key type: [rsa, dsa, ec] (Default: rsa) rsa -Enter private key bits: (Default: 2048) 2048 -Enter country code: (Default: GB) GB -Enter state: (Default: Some-State) Some-State -Enter locality: (Default: Some-City) Some-City -Enter organization name: (Default: VyOS) VyOS -Enter common name: (Default: vyos.io) VyOS Root CA -Enter how many days certificate will be valid: (Default: 1825) 1825 -Note: If you plan to use the generated key on this router, do not encrypt the private key. -Do you want to encrypt the private key with a passphrase? [y/N] n -2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. -``` - -Secondly, we create the intermediary certificate authorities, which are used to -sign the leaf certificates. - -```none -[edit] -vyos@vyos# run generate pki ca sign vyos_root_ca install vyos_server_ca -Do you already have a certificate request? [y/N] n -Enter private key type: [rsa, dsa, ec] (Default: rsa) rsa -Enter private key bits: (Default: 2048) 2048 -Enter country code: (Default: GB) GB -Enter state: (Default: Some-State) Some-State -Enter locality: (Default: Some-City) Some-City -Enter organization name: (Default: VyOS) VyOS -Enter common name: (Default: vyos.io) VyOS Intermediary Server CA -Enter how many days certificate will be valid: (Default: 1825) 1095 -Note: If you plan to use the generated key on this router, do not encrypt the private key. -Do you want to encrypt the private key with a passphrase? [y/N] n -2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. - - -[edit] -vyos@vyos# run generate pki ca sign vyos_root_ca install vyos_client_ca -Do you already have a certificate request? [y/N] n -Enter private key type: [rsa, dsa, ec] (Default: rsa) rsa -Enter private key bits: (Default: 2048) 2048 -Enter country code: (Default: GB) GB -Enter state: (Default: Some-State) Some-State -Enter locality: (Default: Some-City) Some-City -Enter organization name: (Default: VyOS) VyOS -Enter common name: (Default: vyos.io) VyOS Intermediary Client CA -Enter how many days certificate will be valid: (Default: 1825) 1095 -Note: If you plan to use the generated key on this router, do not encrypt the private key. -Do you want to encrypt the private key with a passphrase? [y/N] n -2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. -``` - -Lastly, we can create the leaf certificates that devices and users will utilise. - -```none -[edit] -vyos@vyos# run generate pki certificate sign vyos_server_ca install vyos_cert -Do you already have a certificate request? [y/N] n -Enter private key type: [rsa, dsa, ec] (Default: rsa) rsa -Enter private key bits: (Default: 2048) 2048 -Enter country code: (Default: GB) GB -Enter state: (Default: Some-State) Some-State -Enter locality: (Default: Some-City) Some-City -Enter organization name: (Default: VyOS) VyOS -Enter common name: (Default: vyos.io) vyos.net -Do you want to configure Subject Alternative Names? [y/N] y -Enter alternative names in a comma separate list, example: ipv4:1.1.1.1,ipv6:fe80::1,dns:vyos.net -Enter Subject Alternative Names: dns:vyos.net,dns:www.vyos.net -Enter how many days certificate will be valid: (Default: 365) 365 -Enter certificate type: (client, server) (Default: server) server -Note: If you plan to use the generated key on this router, do not encrypt the private key. -Do you want to encrypt the private key with a passphrase? [y/N] n -2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. - - -[edit] -vyos@vyos# run generate pki certificate sign vyos_client_ca install vyos_example_user -Do you already have a certificate request? [y/N] n -Enter private key type: [rsa, dsa, ec] (Default: rsa) rsa -Enter private key bits: (Default: 2048) 2048 -Enter country code: (Default: GB) GB -Enter state: (Default: Some-State) Some-State -Enter locality: (Default: Some-City) Some-City -Enter organization name: (Default: VyOS) VyOS -Enter common name: (Default: vyos.io) Example User -Do you want to configure Subject Alternative Names? [y/N] y -Enter alternative names in a comma separate list, example: ipv4:1.1.1.1,ipv6:fe80::1,dns:vyos.net,rfc822:user@vyos.net -Enter Subject Alternative Names: rfc822:example.user@vyos.net -Enter how many days certificate will be valid: (Default: 365) 365 -Enter certificate type: (client, server) (Default: server) client -Note: If you plan to use the generated key on this router, do not encrypt the private key. -Do you want to encrypt the private key with a passphrase? [y/N] n -2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. -``` diff --git a/docs/configuration/policy/md-access-list.md b/docs/configuration/policy/md-access-list.md deleted file mode 100644 index c3a92e56..00000000 --- a/docs/configuration/policy/md-access-list.md +++ /dev/null @@ -1,70 +0,0 @@ -# Access List Policy - -Filtering is used for both input and output of the routing information. Once -filtering is defined, it can be applied in any direction. VyOS makes filtering -possible using acls and prefix lists. - -Basic filtering can be done using access-list and access-list6. - -## Configuration - -### Access Lists - -```{cfgcmd} set policy access-list \ - -This command creates the new access list policy, where `` must be -a number from 1 to 2699. -``` - -```{cfgcmd} set policy access-list \ description \ - -Set description for the access list. -``` - -```{cfgcmd} set policy access-list \ rule \<1-65535\> action \ - -This command creates a new rule in the access list and defines an action. -``` - -```{cfgcmd} set policy access-list \ rule \<1-65535\> \ \ - -This command defines matching parameters for access list rule. Matching -criteria could be applied to destination or source parameters: - -* any: any IP address to match. -* host: single host IP address to match. -* inverse-match: network/netmask to match (requires network be defined). -* network: network/netmask to match (requires inverse-match be defined). -``` - - -### IPv6 Access List - -Basic filtering could also be applied to IPv6 traffic. - -```{cfgcmd} set policy access-list6 \ - -This command creates the new IPv6 access list, identified by `` -``` - -```{cfgcmd} set policy access-list6 \ description \ - -Set description for the IPv6 access list. -``` - -```{cfgcmd} set policy access-list6 \ rule \<1-65535\> action \ - -This command creates a new rule in the IPv6 access list and defines an -action. -``` - -```{cfgcmd} set policy access-list6 \ rule \<1-65535\> source \ - -This command defines matching parameters for IPv6 access list rule. Matching -criteria could be applied to source parameters: - -* any: any IPv6 address to match. -* exact-match: exact match of the network prefixes. -* network: network/netmask to match (requires inverse-match be defined) BUG, -NO invert-match option in access-list6 -``` \ No newline at end of file diff --git a/docs/configuration/policy/md-as-path-list.md b/docs/configuration/policy/md-as-path-list.md deleted file mode 100644 index 1fcece91..00000000 --- a/docs/configuration/policy/md-as-path-list.md +++ /dev/null @@ -1,29 +0,0 @@ -# BGP - AS Path Policy - -VyOS provides policies commands exclusively for BGP traffic filtering and -manipulation: **as-path-list** is one of them. - -## Configuration - -### policy as-path-list - -```{cfgcmd} set policy as-path-list \ - -Create as-path-policy identified by name ``. -``` -```{cfgcmd} set policy as-path-list \ description \ - -Set description for as-path-list policy. -``` -```{cfgcmd} set policy as-path-list \ rule \<1-65535\> action \ - -Set action to take on entries matching this rule. -``` -```{cfgcmd} set policy as-path-list \ rule \<1-65535\> description \ - -Set description for rule. -``` -```{cfgcmd} set policy as-path-list \ rule \<1-65535\> regex \ - -Regular expression to match against an AS path. For example "64501 64502". -``` \ No newline at end of file diff --git a/docs/configuration/policy/md-community-list.md b/docs/configuration/policy/md-community-list.md deleted file mode 100644 index bdcf4140..00000000 --- a/docs/configuration/policy/md-community-list.md +++ /dev/null @@ -1,29 +0,0 @@ -# BGP - Community List - -VyOS provides policies commands exclusively for BGP traffic filtering and -manipulation: **community-list** is one of them. - -## Configuration - -### policy community-list - -```{cfgcmd} set policy community-list \ - -Creat community-list policy identified by name ``. -``` -```{cfgcmd} set policy community-list \ description \ - -Set description for community-list policy. -``` -```{cfgcmd} set policy community-list \ rule \<1-65535\> action \ - -Set action to take on entries matching this rule. -``` -```{cfgcmd} set policy community-list \ rule \<1-65535\> description \ - -Set description for rule. -``` -```{cfgcmd} set policy community-list \ rule \<1-65535\> regex \ - -Regular expression to match against a community-list. -``` \ No newline at end of file diff --git a/docs/configuration/policy/md-examples.md b/docs/configuration/policy/md-examples.md deleted file mode 100644 index 2b5d54d2..00000000 --- a/docs/configuration/policy/md-examples.md +++ /dev/null @@ -1,205 +0,0 @@ -# BGP Example - -**Policy definition:** - -```none -# Create policy -set policy route-map setmet rule 2 action 'permit' -set policy route-map setmet rule 2 set as-path prepend '2 2 2' - -# Apply policy to BGP -set protocols bgp system-as 1 -set protocols bgp neighbor 203.0.113.2 address-family ipv4-unicast route-map import 'setmet' -set protocols bgp neighbor 203.0.113.2 address-family ipv4-unicast soft-reconfiguration 'inbound' -``` - -Using 'soft-reconfiguration' we get the policy update without bouncing the -neighbor. - -**Routes learned before routing policy applied:** - -```none -vyos@vos1:~$ show ip bgp -BGP table version is 0, local router ID is 192.168.56.101 -Status codes: s suppressed, d damped, h history, * valid, > best, i - internal, - r RIB-failure, S Stale, R Removed -Origin codes: i - IGP, e - EGP, ? - incomplete - - Network Next Hop Metric LocPrf Weight Path -*> 198.51.100.3/32 203.0.113.2 1 0 2 i < Path - -Total number of prefixes 1 -``` - -**Routes learned after routing policy applied:** - -```none -vyos@vos1:~$ show ip bgp -BGP table version is 0, local router ID is 192.168.56.101 -Status codes: s suppressed, d damped, h history, * valid, > best, i - internal, - r RIB-failure, S Stale, R Removed -Origin codes: i - IGP, e - EGP, ? - incomplete - - Network Next Hop Metric LocPrf Weight Path -*> 198.51.100.3/32 203.0.113.2 1 0 2 2 2 2 i - -Total number of prefixes 1 -vyos@vos1:~$ -``` - -You now see the longer AS path. - -# Transparent Proxy - -The following example will show how VyOS can be used to redirect web -traffic to an external transparent proxy: - -```none -set policy route FILTER-WEB rule 1000 destination port 80 -set policy route FILTER-WEB rule 1000 protocol tcp -set policy route FILTER-WEB rule 1000 set table 100 -``` - -This creates a route policy called FILTER-WEB with one rule to set the -routing table for matching traffic (TCP port 80) to table ID 100 -instead of the default routing table. - -To create routing table 100 and add a new default gateway to be used by -traffic matching our route policy: - -```none -set protocols static table 100 route 0.0.0.0/0 next-hop 10.255.0.2 -``` - -This can be confirmed using the `show ip route table 100` operational -command. - -Finally, to apply the policy route to ingress traffic on our LAN -interface, we use: - -```none -set policy route FILTER-WEB interface eth1 -``` - - -# Multiple Uplinks - -VyOS Policy-Based Routing (PBR) works by matching source IP address -ranges and forwarding the traffic using different routing tables. - -Routing tables that will be used in this example are: - -- `table 10` Routing table used for VLAN 10 (192.168.188.0/24) -- `table 11` Routing table used for VLAN 11 (192.168.189.0/24) -- `main` Routing table used by VyOS and other interfaces not - participating in PBR - -:::{figure} /_static/images/pbr_example_1.webp -:alt: PBR multiple uplinks -:scale: 80 % - -Policy-Based Routing with multiple ISP uplinks -(source ./draw.io/pbr_example_1.drawio) -::: - -Add default routes for routing `table 10` and `table 11` - -```none -set protocols static table 10 route 0.0.0.0/0 next-hop 192.0.2.1 -set protocols static table 11 route 0.0.0.0/0 next-hop 192.0.2.2 -``` - -Add policy route matching VLAN source addresses - -```none -set policy route PBR rule 20 set table '10' -set policy route PBR rule 20 description 'Route VLAN10 traffic to table 10' -set policy route PBR rule 20 source address '192.168.188.0/24' - -set policy route PBR rule 30 set table '11' -set policy route PBR rule 30 description 'Route VLAN11 traffic to table 11' -set policy route PBR rule 30 source address '192.168.189.0/24' -``` - -Apply routing policy to **inbound** direction of out VLAN interfaces - -```none -set policy route 'PBR' interface eth0.10 -set policy route 'PBR' interface eth0.11 -``` - -**OPTIONAL:** Exclude Inter-VLAN traffic (between VLAN10 and VLAN11) -from PBR - -```none -set firewall group network-group VLANS-GR description 'VLANs networks' -set firewall group network-group VLANS-GR network '192.168.188.0/24' -set firewall group network-group VLANS-GR network '192.168.189.0/24' - -set policy route PBR rule 10 description 'VLAN10 <-> VLAN11 shortcut' -set policy route PBR rule 10 destination group network-group 'VLANS-GR' -set policy route PBR rule 10 set table 'main' -``` - -These commands allow the VLAN10 and VLAN11 hosts to communicate with -each other using the main routing table. - -## Local route - -The following example allows VyOS to use {abbr}`PBR (Policy-Based Routing)` -for traffic, which originated from the router itself. That solution for multiple -ISP's and VyOS router will respond from the same interface that the packet was -received. Also, it used, if we want that one VPN tunnel to be through one -provider, and the second through another. - -- `203.0.113.254` IP addreess on VyOS eth1 from ISP1 -- `192.168.2.254` IP addreess on VyOS eth2 from ISP2 -- `table 10` Routing table used for ISP1 -- `table 11` Routing table used for ISP2 - -```none -set policy local-route rule 101 set table '10' -set policy local-route rule 101 source address '203.0.113.254' -set policy local-route rule 102 set table '11' -set policy local-route rule 102 source address '192.0.2.254' -set protocols static table 10 route 0.0.0.0/0 next-hop '203.0.113.1' -set protocols static table 11 route 0.0.0.0/0 next-hop '192.0.2.2' -``` - -Add multiple source IP in one rule with same priority - -```none -set policy local-route rule 101 set table '10' -set policy local-route rule 101 source address '203.0.113.254' -set policy local-route rule 101 source address '203.0.113.253' -set policy local-route rule 101 source address '198.51.100.0/24' -``` - - -# Clamp MSS for a specific IP - -This example shows how to target an MSS clamp (in our example to 1360 bytes) -to a specific destination IP. - -```none -set policy route IP-MSS-CLAMP rule 10 description 'Clamp TCP session MSS to 1360 for 198.51.100.30' -set policy route IP-MSS-CLAMP rule 10 destination address '198.51.100.30/32' -set policy route IP-MSS-CLAMP rule 10 protocol 'tcp' -set policy route IP-MSS-CLAMP rule 10 set tcp-mss '1360' -set policy route IP-MSS-CLAMP rule 10 tcp flags 'SYN' -``` - -To apply this policy to the correct interface, configure it on the -interface the inbound local host will send through to reach our -destined target host (in our example eth1). - -```none -set policy route IP-MSS-CLAMP interface eth1 -``` - -You can view that the policy is being correctly (or incorrectly) utilised -with the following command: - -```none -show policy route statistics -``` diff --git a/docs/configuration/policy/md-extcommunity-list.md b/docs/configuration/policy/md-extcommunity-list.md deleted file mode 100644 index 5247c13c..00000000 --- a/docs/configuration/policy/md-extcommunity-list.md +++ /dev/null @@ -1,33 +0,0 @@ -# BGP - Extended Community List - -VyOS provides policies commands exclusively for BGP traffic filtering and -manipulation: **extcommunity-list** is one of them. - -## Configuration - -### policy extcommunity-list - -```{cfgcmd} set policy extcommunity-list \ - -Creat extcommunity-list policy identified by name \. -``` -```{cfgcmd} set policy extcommunity-list \ description \ - -Set description for extcommunity-list policy. -``` -```{cfgcmd} set policy extcommunity-list \ rule \<1-65535\> action \ - -Set action to take on entries matching this rule. -``` -```{cfgcmd} set policy extcommunity-list \ rule \<1-65535\> description \ - -Set description for rule. -``` -```{cfgcmd} set policy extcommunity-list \ rule \<1-65535\> regex \ - -Regular expression to match against an extended community list, where text -could be: -* \: Extended community list regular expression. -* \: Route Target regular expression. -* \: Site of Origin regular expression. -``` \ No newline at end of file diff --git a/docs/configuration/policy/md-index.md b/docs/configuration/policy/md-index.md deleted file mode 100644 index f919e70a..00000000 --- a/docs/configuration/policy/md-index.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -lastproofread: '2021-07-12' ---- - -```{include} /_include/need_improvement.txt -``` - - -# Policy - -Policies are used for filtering and traffic management. With policies, network -administrators could filter and treat traffic -according to their needs. - -There could be a wide range of routing policies. Some examples are listed -below: -- Filter traffic based on source/destination address. -- Set some metric to routes learned from a particular neighbor. -- Set some attributes (like AS PATH or Community value) to advertised routes - to neighbors. -- Prefer a specific routing protocol routes over another routing protocol - running on the same router. - -Policies, in VyOS, are implemented using FRR filtering and route maps. Detailed -information of FRR could be found in - -## Policy Sections - -```{toctree} -:includehidden: true -:maxdepth: 1 - -access-list -prefix-list -route -route-map -local-route -as-path-list -community-list -extcommunity-list -large-community-list -``` - -## Examples - -Examples of policies usage: - -```{toctree} -:includehidden: true -:maxdepth: 1 - -examples -``` diff --git a/docs/configuration/policy/md-large-community-list.md b/docs/configuration/policy/md-large-community-list.md deleted file mode 100644 index 23b9a85a..00000000 --- a/docs/configuration/policy/md-large-community-list.md +++ /dev/null @@ -1,29 +0,0 @@ -# BGP - Large Community List - -VyOS provides policies commands exclusively for BGP traffic filtering and -manipulation: **large-community-list** is one of them. - -## Configuration - -### policy large-community-list - -```{cfgcmd} set policy large-community-list \ - -Create large-community-list policy identified by name ``. -``` -```{cfgcmd} set policy large-community-list \ description \ - -Set description for large-community-list policy. -``` -```{cfgcmd} set policy large-community-list \ rule \<1-65535\> action \ - -Set action to take on entries matching this rule. -``` -```{cfgcmd} set policy large-community-list \ rule \<1-65535\> description \ - -Set description for rule. -``` -```{cfgcmd} set policy large-community-list \ rule \<1-65535\> regex \ - -Regular expression to match against a large community list. -``` \ No newline at end of file diff --git a/docs/configuration/policy/md-local-route.md b/docs/configuration/policy/md-local-route.md deleted file mode 100644 index 527a2380..00000000 --- a/docs/configuration/policy/md-local-route.md +++ /dev/null @@ -1,100 +0,0 @@ -# Local Route Policy - -Policies for local traffic are defined in this section. - -## Configuration - -### Local Route IPv4 - -```{cfgcmd} set policy local-route rule \<1-32765\> set table \<1-200|main\> - -Set the routing table to use for forwarding matching packets. -``` - -```{cfgcmd} set policy local-route rule \<1-32765\> set vrf \ - -Set the VRF to use for forwarding matching packets. -``` - -```{cfgcmd} set policy local-route rule \<1-32765\> protocol \ - -Match specified protocol (name or number). -``` - -```{cfgcmd} set policy local-route rule \<1-32765\> fwmark \<1-2147483647\> - -Match specified firewall mark (fwmark). -``` - -```{cfgcmd} set policy local-route rule \<1-32765\> source address \ - -Match specified source address or prefix. -``` - -```{cfgcmd} set policy local-route rule \<1-32765\> source port \<1-65535\> - -Match specified source port. -``` - -```{cfgcmd} set policy local-route rule \<1-32765\> destination address \ - -Match specified destination address or prefix. -``` - -```{cfgcmd} set policy local-route rule \<1-32765\> destination port \<1-65535\> - -Match specified destination port. -``` - -```{cfgcmd} set policy local-route rule \<1-32765\> inbound-interface \ - -Match specified inbound interface. -``` - - -### Local Route IPv6 - -```{cfgcmd} set policy local-route6 rule \<1-32765\> set table \<1-200|main\> - -Set the routing table to use for forwarding matching packets. -``` - -```{cfgcmd} set policy local-route6 rule \<1-32765\> set vrf \ - -Set the VRF to use for forwarding matching packets. -``` - -```{cfgcmd} set policy local-route6 rule \<1-32765\> protocol \ - -Match specified protocol (name or number). -``` - -```{cfgcmd} set policy local-route6 rule \<1-32765\> fwmark \<1-2147483647\> - -Match specified firewall mark (fwmark). -``` - -```{cfgcmd} set policy local-route6 rule \<1-32765\> source address \ - -Match specified source address or prefix. -``` - -```{cfgcmd} set policy local-route6 rule \<1-32765\> source port \<1-65535\> - -Match specified source port. -``` - -```{cfgcmd} set policy local-route6 rule \<1-32765\> destination address \ - -Match specified destination address or prefix. -``` - -```{cfgcmd} set policy local-route6 rule \<1-32765\> destination port \<1-65535\> - -Match specified destination port. -``` - -```{cfgcmd} set policy local-route6 rule \<1-32765\> inbound-interface \ - -Match specified inbound interface. -``` \ No newline at end of file diff --git a/docs/configuration/policy/md-prefix-list.md b/docs/configuration/policy/md-prefix-list.md deleted file mode 100644 index eb827c77..00000000 --- a/docs/configuration/policy/md-prefix-list.md +++ /dev/null @@ -1,152 +0,0 @@ -# Prefix List Policy - -Prefix lists provides the most powerful prefix based filtering mechanism. In -addition to access-list functionality, ip prefix-list has prefix length range -specification. - -If no ip prefix list is specified, it acts as permit. If ip prefix list is -defined, and no match is found, default deny is applied. - -Prefix filtering can be done using prefix-list and prefix-list6. - -## Configuration - -### IPv4 Prefix Lists (prefix-list) - -```{cfgcmd} set policy prefix-list \ - -This command creates the new prefix-list policy, identified by ``. -``` - -```{cfgcmd} set policy prefix-list \ description \ - -Set description for the prefix-list policy. -``` - -```{cfgcmd} set policy prefix-list \ rule \<1-65535\> action \ - -This command creates a new rule in the prefix-list and defines an action. -``` - -```{cfgcmd} set policy prefix-list \ rule \<1-65535\> description \ - -Set description for rule in the prefix-list. -``` - -```{cfgcmd} set policy prefix-list \ rule \<1-65535\> prefix \ - -Prefix to match against. -``` - -```{cfgcmd} set policy prefix-list \ rule \<1-65535\> ge \<0-32\> - -Netmask greater than length. -``` - -```{cfgcmd} set policy prefix-list \ rule \<1-65535\> le \<0-32\> - -Netmask less than length -``` - - -### Example: IPv4 Prefix Lists (prefix-list) - -This example creates an IPv4 prefix-list named PL4-EXAMPLE-NAME, defines 3 -rules each with 1 prefix, and matches le (less than/equal to) /32. - -```{cfgcmd} set policy prefix-list PL4-EXAMPLE-NAME rule 10 action 'permit' - -``` -```{cfgcmd} set policy prefix-list PL4-EXAMPLE-NAME rule 10 le '32' -``` - -```{cfgcmd} set policy prefix-list PL4-EXAMPLE-NAME rule 10 prefix '192.0.2.0/24' -``` - -```{cfgcmd} set policy prefix-list PL4-EXAMPLE-NAME rule 20 action 'permit' -``` - -```{cfgcmd} set policy prefix-list PL4-EXAMPLE-NAME rule 20 le '32' -``` - -```{cfgcmd} set policy prefix-list PL4-EXAMPLE-NAME rule 20 prefix '198.51.100.0/24' -``` - -```{cfgcmd} set policy prefix-list PL4-EXAMPLE-NAME rule 30 action 'permit' -``` - -```{cfgcmd} set policy prefix-list PL4-EXAMPLE-NAME rule 30 le '32' -``` - -```{cfgcmd} set policy prefix-list PL4-EXAMPLE-NAME rule 30 prefix '203.0.113.0/24' -``` - -### IPv6 Prefix Lists (prefix-list6) - -```{cfgcmd} set policy prefix-list6 \ - -This command creates the new IPv6 prefix-list policy, identified by ``. -``` - -```{cfgcmd} set policy prefix-list6 \ description \ - -Set description for the IPv6 prefix-list policy. -``` - -```{cfgcmd} set policy prefix-list6 \ rule \<1-65535\> action \ - -This command creates a new rule in the IPv6 prefix-list and defines an -action. -``` - -```{cfgcmd} set policy prefix-list6 \ rule \<1-65535\> description \ - -Set description for rule in IPv6 prefix-list. -``` - -```{cfgcmd} set policy prefix-list6 \ rule \<1-65535\> prefix \ - -IPv6 prefix. -``` - -```{cfgcmd} set policy prefix-list6 \ rule \<1-65535\> ge \<0-128\> - -Netmask greater than length. -``` - -```{cfgcmd} set policy prefix-list6 \ rule \<1-65535\> le \<0-128\> - -Netmask less than length -``` - -### Example: IPv6 Prefix Lists (prefix-list6) - -This example creates an IPv6 prefix-list6 named PL6-EXAMPLE-NAME, defines 3 -rules each with 1 prefix, and matches le (less than/equal to) /128. - -```{cfgcmd} set policy prefix-list6 PL6-EXAMPLE-NAME rule 10 action 'permit' -``` - -```{cfgcmd} set policy prefix-list6 PL6-EXAMPLE-NAME rule 10 le '128' -``` - -```{cfgcmd} set policy prefix-list6 PL6-EXAMPLE-NAME rule 10 prefix '2001:db8:0:0::/64' -``` - -```{cfgcmd} set policy prefix-list6 PL6-EXAMPLE-NAME rule 20 action 'permit' -``` - -```{cfgcmd} set policy prefix-list6 PL6-EXAMPLE-NAME rule 20 le '128' -``` - -```{cfgcmd} set policy prefix-list6 PL6-EXAMPLE-NAME rule 20 prefix '2001:db8:0:1::/64' -``` - -```{cfgcmd} set policy prefix-list6 PL6-EXAMPLE-NAME rule 30 action 'permit' -``` - -```{cfgcmd} set policy prefix-list6 PL6-EXAMPLE-NAME rule 30 le '128' -``` - -```{cfgcmd} set policy prefix-list6 PL6-EXAMPLE-NAME rule 30 prefix '2001:db8:0:2::/64' -``` \ No newline at end of file diff --git a/docs/configuration/policy/md-route-map.md b/docs/configuration/policy/md-route-map.md deleted file mode 100644 index 624b542c..00000000 --- a/docs/configuration/policy/md-route-map.md +++ /dev/null @@ -1,439 +0,0 @@ -# Route Map Policy - -Route map is a powerfull command, that gives network administrators a very -useful and flexible tool for traffic manipulation. - -## Configuration - -### Route Map - -```{cfgcmd} set policy route-map \ - - This command creates a new route-map policy, identified by \. -``` - - -```{cfgcmd} set policy route-map \ description \ - -Set description for the route-map policy. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> action \ - -Set action for the route-map policy. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> call \ - -Call another route-map policy on match. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> continue \<1-65535\> - -Jump to a different rule in this route-map on a match. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> description \ - -Set description for the rule in the route-map policy. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> match as-path \ - -BGP as-path list to match. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> match community community-list \ - -BGP community-list to match. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> match community exact-match - -Set BGP community-list to exactly match. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> match extcommunity \ - -BGP extended community to match. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> match interface \ - -First hop interface of a route to match. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> match ip address access-list \<1-2699\> - -IP address of route to match, based on access-list. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> match ip address prefix-list \ - -IP address of route to match, based on prefix-list. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> match ip address prefix-len \<0-32\> - -IP address of route to match, based on specified prefix-length. -Note that this can be used for kernel routes only. -Do not apply to the routes of dynamic routing protocols (e.g. BGP, -RIP, OSFP), as this can lead to unexpected results.. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> match ip nexthop access-list \<1-2699\> - -IP next-hop of route to match, based on access-list. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> match ip nexthop address \ - -IP next-hop of route to match, based on ip address. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> match ip nexthop prefix-len \<0-32\> - -IP next-hop of route to match, based on prefix length. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> match ip nexthop prefix-list \ - -IP next-hop of route to match, based on prefix-list. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> match ip nexthop type \ - -IP next-hop of route to match, based on type. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> match ip route-source access-list \<1-2699\> - -IP route source of route to match, based on access-list. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> match ip route-source prefix-list \ - -IP route source of route to match, based on prefix-list. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> match ipv6 address access-list \ - -IPv6 address of route to match, based on IPv6 access-list. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> match ipv6 address prefix-list \ - -IPv6 address of route to match, based on IPv6 prefix-list. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> match ipv6 address prefix-len \<0-128\> - -IPv6 address of route to match, based on specified prefix-length. -Note that this can be used for kernel routes only. -Do not apply to the routes of dynamic routing protocols (e.g. BGP, -RIP, OSFP), as this can lead to unexpected results.. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> match ipv6 nexthop \ - -Nexthop IPv6 address to match. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> match large-community large-community-list \ - -Match BGP large communities. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> match local-preference \<0-4294967295\> - -Match local preference. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> match metric \<1-65535\> - -Match route metric. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> match origin \ - -Boarder Gateway Protocol (BGP) origin code to match. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> match peer \ - -Peer IP address to match. -``` - - -````{cfgcmd} set policy route-map \ rule \<1-65535\> match protocol \ - -```{eval-rst} -Source protocol to match. - * ``babel`` - Babel routing protocol (Babel) - * ``bgp`` - Border Gateway Protocol (BGP) - * ``connected`` - Connected routes (directly attached subnet or host) - * ``isis`` - Intermediate System to Intermediate System (IS-IS) - * ``kernel`` - Kernel routes - * ``ospf`` - Open Shortest Path First (OSPFv2) - * ``ospfv3`` - Open Shortest Path First (IPv6) (OSPFv3) - * ``rip`` - Routing Information Protocol (RIP) - * ``ripng`` - Routing Information Protocol next-generation (IPv6) (RIPng) - * ``static`` - Statically configured routes - * ``table`` - Non-main Kernel Routing Table - * ``vnc`` - Virtual Network Control (VNC) -``` -```` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> match rpki \ - -Match RPKI validation result. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> match source-vrf \ - -Source VRF to match. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> match tag \<1-65535\> - -Route tag to match. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> on-match goto \<1-65535\> - -Exit policy on match: go to rule <1-65535> -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> on-match next - -Exit policy on match: go to next sequence number. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> set aggregator \ \<1-4294967295|x.x.x.x\> - -BGP aggregator attribute: AS number or IP address of an aggregation. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> set as-path exclude \<1-4294967295 | all\> - -Drop AS-NUMBER from the BGP AS path. - -If ``all`` is specified, remove all AS numbers from the AS_PATH of the BGP -path's NLRI. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> set as-path prepend \<1-4294967295\> - -Prepend the given string of AS numbers to the AS_PATH of the BGP path's NLRI. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> set as-path prepend-last-as \ - -Prepend the existing last AS number (the leftmost ASN) to the AS_PATH. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> set atomic-aggregate - -BGP atomic aggregate attribute. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> set community \ \ - -Add or replace BGP community attribute in format ``<0-65535:0-65535>`` -or from well-known community list -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> set community none - -Delete all BGP communities -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> set community delete \ - -Delete BGP communities matching the community-list. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> set large-community \ \ - -Add or replace BGP large-community attribute in format -``<0-4294967295:0-4294967295:0-4294967295>`` -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> set large-community none - -Delete all BGP large-communities -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> set large-community delete \ - -Delete BGP communities matching the large-community-list. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> set extcommunity bandwidth \<1-25600|cumulative|num-multipaths\> - -Set extcommunity bandwidth -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> set extcommunity bandwidth-non-transitive - -The link bandwidth extended community is encoded as non-transitive -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> set extcommunity rt \ - -Set route target value in format ``<0-65535:0-4294967295>`` or ````. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> set extcommunity soo \ - -Set site of origin value in format ``<0-65535:0-4294967295>`` or ````. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> set extcommunity none - -Clear all BGP extcommunities. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> set distance \<0-255\> - -Locally significant administrative distance. -``` -```{cfgcmd} set policy route-map \ rule \<1-65535\> set ip-next-hop \ - -Nexthop IP address. -``` -```{cfgcmd} set policy route-map \ rule \<1-65535\> set ip-next-hop unchanged - -Set the next-hop as unchanged. Pass through the route-map without -changing its value -``` -```{cfgcmd} set policy route-map \ rule \<1-65535\> set ip-next-hop peer-address - -Set the BGP nexthop address to the address of the peer. For an incoming -route-map this means the ip address of our peer is used. For an -outgoing route-map this means the ip address of our self is used to -establish the peering with our neighbor. -``` -```{cfgcmd} set policy route-map \ rule \<1-65535\> set ipv6-next-hop \ \ - -Nexthop IPv6 address. -``` -```{cfgcmd} set policy route-map \ rule \<1-65535\> set ipv6-next-hop peer-address - -Set the BGP nexthop address to the address of the peer. For an incoming -route-map this means the ip address of our peer is used. For an -outgoing route-map this means the ip address of our self is used to -establish the peering with our neighbor. -``` -```{cfgcmd} set policy route-map \ rule \<1-65535\> set ipv6-next-hop prefer-global - -For Incoming and Import Route-maps if we receive a v6 global and v6 LL -address for the route, then prefer to use the global address as the -nexthop. -``` -```{cfgcmd} set policy route-map \ rule \<1-65535\> set local-preference \<0-4294967295\> - -Set BGP local preference attribute. -``` -```{cfgcmd} set policy route-map \ rule \<1-65535\> set metric \<+/-metric|0-4294967295|rtt|+rtt|-rtt\> - -Set the route metric. When used with BGP, set the BGP attribute MED -to a specific value. Use ``+/-`` to add or subtract the specified value -to/from the existing/MED. Use ``rtt`` to set the MED to the round trip -time or ``+rtt/-rtt`` to add/subtract the round trip time to/from the MED. -``` -```{cfgcmd} set policy route-map \ rule \<1-65535\> set metric-type \ - -Set OSPF external metric-type. -``` -```{cfgcmd} set policy route-map \ rule \<1-65535\> set origin \ - -Set BGP origin code. -``` -```{cfgcmd} set policy route-map \ rule \<1-65535\> set originator-id \ - -Set BGP originator ID attribute. -``` -```{cfgcmd} set policy route-map \ rule \<1-65535\> set src \ - -Set source IP/IPv6 address for route. -``` -```{cfgcmd} set policy route-map \ rule \<1-65535\> set table \<1-200\> - -Set prefixes to table. -``` -```{cfgcmd} set policy route-map \ rule \<1-65535\> set tag \<1-65535\> - -Set tag value for routing protocol. -``` -```{cfgcmd} set policy route-map \ rule \<1-65535\> set weight \<0-4294967295\> - -Set BGP weight attribute -``` - -### List of well-known communities - -> - `local-as` - Well-known communities value NO_EXPORT_SUBCONFED 0xFFFFFF03 -> - `no-advertise` - Well-known communities value NO_ADVERTISE 0xFFFFFF02 -> - `no-export` - Well-known communities value NO_EXPORT 0xFFFFFF01 -> - `graceful-shutdown` - Well-known communities value GRACEFUL_SHUTDOWN 0xFFFF0000 -> - `accept-own` - Well-known communities value ACCEPT_OWN 0xFFFF0001 -> - `route-filter-translated-v4` - Well-known communities value ROUTE_FILTER_TRANSLATED_v4 0xFFFF0002 -> - `route-filter-v4` - Well-known communities value ROUTE_FILTER_v4 0xFFFF0003 -> - `route-filter-translated-v6` - Well-known communities value ROUTE_FILTER_TRANSLATED_v6 0xFFFF0004 -> - `route-filter-v6` - Well-known communities value ROUTE_FILTER_v6 0xFFFF0005 -> - `llgr-stale` - Well-known communities value LLGR_STALE 0xFFFF0006 -> - `no-llgr` - Well-known communities value NO_LLGR 0xFFFF0007 -> - `accept-own-nexthop` - Well-known communities value accept-own-nexthop 0xFFFF0008 -> - `blackhole` - Well-known communities value BLACKHOLE 0xFFFF029A -> - `no-peer` - Well-known communities value NOPEER 0xFFFFFF04 diff --git a/docs/configuration/policy/md-route.md b/docs/configuration/policy/md-route.md deleted file mode 100644 index 828bd0f1..00000000 --- a/docs/configuration/policy/md-route.md +++ /dev/null @@ -1,424 +0,0 @@ -# Route and Route6 Policy - -IPv4 route and IPv6 route policies are defined in this section. These route -policies can then be associated to interfaces. - -## Rule-Sets - -A rule-set is a named collection of rules that can be applied to an interface. -Each rule is numbered, has an action to apply if the rule is matched, and the -ability to specify the criteria to match. Data packets go through the rules -from 1 - 999999, at the first match the action of the rule will be executed. - -```{cfgcmd} set policy route \ description \ - -``` -```{cfgcmd} set policy route6 \ description \ - -Provide a rule-set description. -``` - -```{cfgcmd} set policy route \ default-log -``` - -```{cfgcmd} set policy route6 \ default-log - -Option to log packets hitting default-action. -``` - -```{cfgcmd} set policy route \ interface \ -``` - -```{cfgcmd} set policy route6 \ interface \ - -Apply routing policy to interface -``` - -```{cfgcmd} set policy route \ rule \ description \ -``` - -```{cfgcmd} set policy route6 \ rule \ description \ - -Provide a description for each rule. -``` - -```{cfgcmd} set policy route \ rule \ log \ -``` - -```{cfgcmd} set policy route6 \ rule \ log \ - -Option to enable or disable log matching rule. -``` - -### Matching criteria - -There are a lot of matching criteria options available, both for -`policy route` and `policy route6`. These options are listed -in this section. - -```{cfgcmd} set policy route \ rule \ connection-mark \<1-2147483647\> -``` - -```{cfgcmd} set policy route6 \ rule \ connection-mark \<1-2147483647\> - -Set match criteria based on connection mark. -``` - -```{cfgcmd} set policy route \ rule \ mark \ -``` - -```{cfgcmd} set policy route6 \ rule \ mark \ - -Match based on the firewall mark (fwmark), where \ can be: - * \<0-2147483647\> a single fwmark - * !\<0-2147483647\> everything except a single fwmark - * <start-end> a range of marks - * !<start-end> everything except the range of marks - -:::{note} -When using the ``set table`` or ``set vrf`` commands the mark -settings are ignored and overwritten with a table-specific mark that -is set to 0x7FFFFFFF - the id of the table/VRF. -::: -``` - -```{cfgcmd} set policy route \ rule \ source address \ -``` - -```{cfgcmd} set policy route \ rule \ destination address \ -``` - -```{cfgcmd} set policy route6 \ rule \ source address \ -``` - -```{cfgcmd} set policy route6 \ rule \ destination address \ - -Set match criteria based on source or destination ipv4|ipv6 address, where -<match_criteria> could be: -``` - -For ipv4: -: - \: IP address to match. - - \: Subnet to match. - - \-\: IP range to match. - - !\: Match everything except the specified address. - - !\: Match everything except the specified subnet. - - !\-\: Match everything except the specified range. - -And for ipv6: -: - \: IPv6 address to match. - - \: IPv6 prefix to match. - - \-\: IPv6 range to match. - - !\: Match everything except the specified address. - - !\: Match everything except the specified prefix. - - !\-\: Match everything except the - specified range. - -```{cfgcmd} set policy route \ rule \ source group \ \ -``` - -```{cfgcmd} set policy route \ rule \ destination group \ \ -``` - -```{cfgcmd} set policy route6 \ rule \ source group \ \ -``` - -```{cfgcmd} set policy route6 \ rule \ destination group \ \ - -Set match criteria based on source or destination groups, where <text> -would be the group name/identifier. Prepend character '!' for inverted -matching criteria. -``` - -```{cfgcmd} set policy route \ rule \ destination port \ -``` - -```{cfgcmd} set policy route6 \ rule \ destination port \ - -Set match criteria based on destination port, where \ could -be: -* <port name>: Named port (any name in /etc/services, e.g., http). -* \<1-65535\>: Numbered port. -* <start>-<end>: Numbered port range (e.g., 1001-1005). - -Multiple destination ports can be specified as a comma-separated list. The -whole list can also be "negated" using '!'. For example: -'!22,telnet,http,123,1001-1005' -``` - -```{cfgcmd} set policy route \ rule \ disable -``` - -```{cfgcmd} set policy route6 \ rule \ disable - -Option to disable rule. -``` - -```{cfgcmd} set policy route \ rule \ dscp \ -``` - -```{cfgcmd} set policy route6 \ rule \ dscp \ -``` - -```{cfgcmd} set policy route \ rule \ dscp-exclude \ -``` - -```{cfgcmd} set policy route6 \ rule \ dscp-exclude \ - -Match based on dscp value criteria. Multiple values from 0 to 63 -and ranges are supported. -``` - -```{cfgcmd} set policy route \ rule \ fragment \ -``` - -```{cfgcmd} set policy route6 \ rule \ fragment \ - -Set IP fragment match, where: -* match-frag: Second and further fragments of fragmented packets. -* match-non-frag: Head fragments or unfragmented packets. -``` - -```{cfgcmd} set policy route \ rule \ icmp \ -``` - -```{cfgcmd} set policy route6 \ rule \ icmpv6 \ - -Match based on icmp|icmpv6 code and type. -``` - -```{cfgcmd} set policy route \ rule \ icmp type-name \ -``` - -```{cfgcmd} set policy route6 \ rule \ icmpv6 type-name \ - -Match based on icmp|icmpv6 type-name criteria. Use tab for information -about what type-name criteria are supported. -``` - -```{cfgcmd} set policy route \ rule \ ipsec \ -``` - -```{cfgcmd} set policy route6 \ rule \ ipsec \ - -Set IPSec inbound match criterias, where: -* match-ipsec: match inbound IPsec packets. -* match-none: match inbound non-IPsec packets. -``` - -```{cfgcmd} set policy route \ rule \ limit burst \<0-4294967295\> -``` - -```{cfgcmd} set policy route6 \ rule \ limit burst \<0-4294967295\> - -Set maximum number of packets to alow in excess of rate. -``` - -```{cfgcmd} set policy route \ rule \ limit rate \ -``` - -```{cfgcmd} set policy route6 \ rule \ limit rate \ - -Set maximum average matching rate. Format for rate: integer/time_unit, where -time_unit could be any one of second, minute, hour or day.For example -1/second implies rule to be matched at an average of once per second. -``` - -```{cfgcmd} set policy route \ rule \ protocol \ -``` - -```{cfgcmd} set policy route6 \ rule \ protocol \ - -Match a protocol criteria. A protocol number or a name which is defined in: -``/etc/protocols``. Special names are ``all`` for all protocols and -``tcp_udp`` for tcp and udp based packets. The ``!`` negates the selected -protocol. -``` - -```{cfgcmd} set policy route \ rule \ packet-length \ -``` - -```{cfgcmd} set policy route6 \ rule \ packet-length \ -``` - -```{cfgcmd} set policy route \ rule \ packet-length-exclude \ -``` - -```{cfgcmd} set policy route6 \ rule \ packet-length-exclude \ - -Match based on packet length criteria. Multiple values from 1 to 65535 -and ranges are supported. -``` - -```{cfgcmd} set policy route \ rule \ packet-type \[broadcast | host | multicast | other\] -``` - -```{cfgcmd} set policy route6 \ rule \ packet-type \[broadcast | host | multicast | other\] - -Match based on packet type criteria. -``` - -```{cfgcmd} set policy route \ rule \ recent count \<1-255\> -``` - -```{cfgcmd} set policy route6 \ rule \ recent count \<1-255\> -``` - -```{cfgcmd} set policy route \ rule \ recent time \<1-4294967295\> -``` - -```{cfgcmd} set policy route6 \ rule \ recent time \<1-4294967295\> - -Set parameters for matching recently seen sources. This match could be used -by seeting count (source address seen more than <1-255> times) and/or time -(source address seen in the last <0-4294967295> seconds). -``` - -```{cfgcmd} set policy route \ rule \ state \ -``` - -```{cfgcmd} set policy route6 \ rule \ state \ - -Set match criteria based on session state. -``` - -```{cfgcmd} set policy route \ rule \ tcp flags \ -``` - -```{cfgcmd} set policy route6 \ rule \ tcp flags \ - -Set match criteria based on tcp flags. Allowed values for TCP flags: SYN ACK -FIN RST URG PSH ALL. When specifying more than one flag, flags should be -comma-separated. For example : value of 'SYN,!ACK,!FIN,!RST' will only match -packets with the SYN flag set, and the ACK, FIN and RST flags unset. -``` - -```{cfgcmd} set policy route \ rule \ time monthdays \ -``` - -```{cfgcmd} set policy route6 \ rule \ time monthdays \ -``` - -```{cfgcmd} set policy route \ rule \ time startdate \ -``` - -```{cfgcmd} set policy route6 \ rule \ time startdate \ -``` - -```{cfgcmd} set policy route \ rule \ time starttime \ -``` - -```{cfgcmd} set policy route6 \ rule \ time starttime \ -``` - -```{cfgcmd} set policy route \ rule \ time stopdate \ -``` - -```{cfgcmd} set policy route6 \ rule \ time stopdate \ -``` - -```{cfgcmd} set policy route \ rule \ time stoptime \ -``` - -```{cfgcmd} set policy route6 \ rule \ time stoptime \ -``` - -```{cfgcmd} set policy route \ rule \ time weekdays \ -``` - -```{cfgcmd} set policy route6 \ rule \ time weekdays \ -``` - -```{cfgcmd} set policy route \ rule \ time utc -``` - -```{cfgcmd} set policy route6 \ rule \ time utc - -Time to match the defined rule. -``` - -```{cfgcmd} set policy route rule \ ttl \ \<0-255\> - -Match time to live parameter, where 'eq' stands for 'equal'; 'gt' stands for -'greater than', and 'lt' stands for 'less than'. -``` - -```{cfgcmd} set policy route6 rule \ hop-limit \ \<0-255\> - -Match hop-limit parameter, where 'eq' stands for 'equal'; 'gt' stands for -'greater than', and 'lt' stands for 'less than'. -``` - -### Actions - -When mathcing all patterns defined in a rule, then different actions can -be made. This includes droping the packet, modifying certain data, or -setting a different routing table. - -```{cfgcmd} set policy route \ rule \ action drop -``` - -```{cfgcmd} set policy route6 \ rule \ action drop - -Set rule action to drop. -``` - -```{cfgcmd} set policy route \ rule \ set connection-mark \<1-2147483647\> -``` - -```{cfgcmd} set policy route6 \ rule \ set connection-mark \<1-2147483647\> - -Set a specific connection mark. -``` - -```{cfgcmd} set policy route \ rule \ set dscp \<0-63\> -``` - -```{cfgcmd} set policy route6 \ rule \ set dscp \<0-63\> - -Set packet modifications: Packet Differentiated Services Codepoint (DSCP) -``` - -```{cfgcmd} set policy route \ rule \ set mark \<1-2147483647\> -``` - -```{cfgcmd} set policy route6 \ rule \ set mark \<1-2147483647\> - -Set a specific packet mark. -``` - -```{cfgcmd} set policy route \ rule \ set table \
-``` - -```{cfgcmd} set policy route6 \ rule \ set table \
- -Set the routing table to forward packet with. - -:::{note} -When using the ``set table`` or ``set vrf`` commands matching -against the mark is not possible, because it gets overwritten with a -table-specific mark that is 0x7FFFFFFF - the id of the table/VRF. -::: -``` - -```{cfgcmd} set policy route \ rule \ set tcp-mss \<500-1460\> -``` - -```{cfgcmd} set policy route6 \ rule \ set tcp-mss \<500-1460\> - -Set packet modifications: Explicitly set TCP Maximum segment size value. -``` - -```{cfgcmd} set policy route \ rule \ set vrf \ -``` - -```{cfgcmd} set policy route6 \ rule \ set vrf \ - -Set the VRF to forward packet with. - -:::{note} -When using the ``set table`` or ``set vrf`` commands matching -against the mark is not possible, because it gets overwritten with a -table-specific mark that is 0x7FFFFFFF - the id of the table/VRF. -::: -``` \ No newline at end of file diff --git a/docs/configuration/protocols/md-arp.md b/docs/configuration/protocols/md-arp.md deleted file mode 100644 index 7d9bf4f9..00000000 --- a/docs/configuration/protocols/md-arp.md +++ /dev/null @@ -1,72 +0,0 @@ -```{eval-rst} -.. meta:: - :description: The Address Resolution Protocol (ARP) resolves - network-layer addresses to link-layer MAC addresses. - :keywords: arp, network, protocol, mac, address, ipv4, static -``` - -(routing_static_arp)= - -# ARP - -The {abbr}`ARP (Address Resolution Protocol)` resolves IPv4 network layer addresses -to link layer MAC addresses. -addresses. This mapping is essential for communication within the Internet -Protocol suite. ARP was standardized in 1982 by {rfc}`826` (STD 37). - -:::{note} -In Internet Protocol version 6 (IPv6) networks, address resolution is -performed by the Neighbor Discovery Protocol (NDP). -::: - -Use the following commands to configure or view ARP table entries. - -## Configuration - -```{eval-rst} -.. cfgcmd:: set protocols static arp interface address mac - - **Configure a static ARP entry on the specified interface.** - - This creates a permanent mapping between an IP address and a MAC address - on the specified interface. - - Example: - - .. code-block:: none - - set protocols static arp interface eth0 address 192.0.2.1 mac 01:23:45:67:89:01 -``` - -## Operation - -```{eval-rst} -.. opcmd:: show protocols static arp - - Show all ARP table entries across all interfaces. - - .. code-block:: none - - vyos@vyos:~$ show protocols static arp - Address HWtype HWaddress Flags Mask Iface - 10.1.1.1 ether 00:53:00:de:23:2e C eth1 - 10.1.1.100 ether 00:53:00:de:23:aa CM eth1 -``` - -```{eval-rst} -.. opcmd:: show protocols static arp interface - - Show all ARP table entries for the specific interface. - - Example for ``eth1``: - - .. code-block:: none - - vyos@vyos:~$ show protocols static arp interface eth1 - Address HWtype HWaddress Flags Mask Iface - 10.1.1.1 ether 00:53:00:de:23:2e C eth1 - 10.1.1.100 ether 00:53:00:de:23:aa CM eth1 -``` - -[arp]: https://en.wikipedia.org/wiki/Address_Resolution_Protocol - diff --git a/docs/configuration/protocols/md-babel.md b/docs/configuration/protocols/md-babel.md deleted file mode 100644 index b03e9fa4..00000000 --- a/docs/configuration/protocols/md-babel.md +++ /dev/null @@ -1,296 +0,0 @@ -```{eval-rst} -.. meta:: - :description: The Babel routing protocol provides robust and efficient - routing for wired and wireless mesh networks. - :keywords: babel, routing, protocol, wireless, mesh, network, metric, - ipv4, ipv6 -``` - -(babel)= - -# Babel - -The Babel protocol provides robust and efficient routing for both wired and -wireless mesh networks. By default, Babel uses hop-count metrics on wired links -and a variant of Expected Transmission Count (ETX) on wireless links. -Administrators can configure Babel to account for radio diversity, -automatically compute link latency, and include that latency in the routing -metric. {rfc}`8966` defines the Babel protocol. - -Babel is a dual-stack protocol. A single Babel instance routes both IPv4 and -IPv6 traffic simultaneously. - -## General configuration - -VyOS does not require a specific command to start the Babel process. The system -automatically starts the routing process when you configure the first -Babel-enabled interface. - -```{cfgcmd} set protocols babel interface \ - -**Enable Babel routing on the specified interface.** - -The system immediately begins sending and receiving Babel packets on this -interface. -``` - -## Optional configuration - -```{cfgcmd} set protocols babel parameters diversity - -**Enable radio-frequency diversity routing for the Babel process.** - -Enabling this feature is highly recommended for networks with many -wireless nodes. - -:::{note} -When you enable diversity routing, you should also configure the -``diversity-factor`` and ``channel`` parameters. -::: -``` - -```{cfgcmd} set protocols babel parameters diversity-factor \<1-256\> - -**Configure the multiplicative factor for diversity routing, in units of -1/256.** - -Lower multiplicative factors give greater weight to diversity in route -selection. The default value is 256, which disables diversity routing. -On nodes with multiple independent radios, configure a value of 128 or less. -``` - -```{cfgcmd} set protocols babel parameters resend-delay \<20-655340\> - -**Configure the delay in milliseconds before the system resends an -important request or update.** - -The default value is 2000 ms. -``` - -```{cfgcmd} set protocols babel parameters smoothing-half-life \<0-65534\> - -**Configure the time constant, in seconds, for the smoothing algorithm used -to implement hysteresis.** - -Higher values reduce route oscillation but slightly increase convergence -time. A value of 0 disables hysteresis and is suitable for wired networks. -The default is 4 seconds. -``` - -## Interfaces configuration - -```{cfgcmd} set protocols babel interface \ type \ - -**Configure the network type for the Babel-enabled interface.** - -Choose from the following: - -* ``auto``: Babel automatically detects if an interface is wired or - wireless. -* ``wired``: Babel enables optimizations for wired interfaces. -* ``wireless``: Babel disables optimizations suitable only for wired - interfaces. Specifying wireless is always correct, but may cause slower - convergence and increased routing traffic. -``` - -```{cfgcmd} set protocols babel interface \ split-horizon \ - -**Configure the split-horizon routing behavior for the specified -interface.** - -Use one of the following options: - -* ``default``: Babel automatically enables split-horizon on wired - interfaces and disables it on wireless interfaces. -* ``enable``: Babel enables split-horizon on the interface. This - optimization should be used only on symmetric, transitive (wired) - networks. -* ``disable``: Babel disables split-horizon on the interface. Disabling - split-horizon is always safe and correct. -``` - -```{cfgcmd} set protocols babel interface \ hello-interval \<20-655340\> - -**Configure the interval, in milliseconds, between scheduled hello messages -on the specified interface.** - -On wired links, Babel detects link failures within two hello intervals. -On wireless links, link quality is reestimated at each interval. The -default is 4000 ms. -``` - -```{cfgcmd} set protocols babel interface \ update-interval \<20-655340\> - -**Configure the interval, in milliseconds, between scheduled routing -updates on the specified interface.** - -Because Babel uses triggered updates extensively, you can increase this -value on reliable links with minimal packet loss. The default is 20000 ms. -``` - -```{cfgcmd} set protocols babel interface \ rxcost \<1-65534\> - -**Configure the base receive cost for the specified interface.** - -Babel applies this value based on the configured network type: - -* ``wired``: The value is the routing cost advertised to neighboring - routers. -* ``wireless``: The value is a multiplier used to compute the ETX - (Expected Transmission Count) reception cost. - -The default value is 256. -``` - -```{cfgcmd} set protocols babel interface \ rtt-decay \<1-256\> - -**Configure the decay factor for the exponential moving average of RTT -samples, in units of 1/256.** - -Higher values discard older samples faster. The default value is 42. -``` - -```{cfgcmd} set protocols babel interface \ rtt-min \<1-65535\> - -**Configure the minimum RTT, in milliseconds, at which the cost to a -neighbor begins to increase.** - -The additional cost is linear in (rtt - rtt-min). The default value is 10 ms. -``` - -```{cfgcmd} set protocols babel interface \ rtt-max \<1-65535\> - -**Configure the maximum RTT, in milliseconds, above which the cost to a -neighbor stops increasing.** - -The default value is 120 ms. -``` - -```{cfgcmd} set protocols babel interface \ max-rtt-penalty \<0-65535\> - -**Configure the maximum cost added to a neighbor when RTT meets or exceeds -rtt-max.** - -Setting this value to 0 disables RTT-based costs. The default value is 150. -``` - -```{cfgcmd} set protocols babel interface \ enable-timestamps - -**Configure adding timestamps to each Hello and IHU message to calculate -RTT values.** - -Enabling timestamps is recommended for tunnel interfaces. -``` - -```{cfgcmd} set protocols babel interface \ channel \<1-254|interfering|noninterfering\> - -**Configure the channel identifier that diversity routing uses for the -specified interface.** - -Interfaces interfere with each other based on the assigned channel -identifier: - -* ``1–254``: The interface interferes with interfaces sharing the same - channel number and with interfaces configured as ``interfering``. -* ``interfering``: The interface interferes with all others except those - configured as ``noninterfering``. -* ``noninterfering``: The interface interferes only with itself. -``` - -## Redistribution configuration - -```{cfgcmd} set protocols babel redistribute \ \ - -**Configure the redistribution of routing information from the specified -route source into the Babel process.** - -The following route sources are available: - -* **ipv4:** ``bgp``, ``connected``, ``eigrp``, ``isis``, ``kernel``, - ``nhrp``, ``ospf``, ``rip``, ``static`` -* **ipv6:** ``bgp``, ``connected``, ``eigrp``, ``isis``, ``kernel``, - ``nhrp``, ``ospfv3``, ``ripng``, ``static`` -``` - -```{cfgcmd} set protocols babel distribute-list \ access-list \ \ - -**Configure global Babel route filtering using an access list.** - -Specify the direction in which the access list is applied: - -* ``in``: Filters incoming routes. -* ``out``: Filters outgoing routes. -``` - -```{cfgcmd} set protocols babel distribute-list \ interface \ access-list \ \ - -**Configure Babel route filtering on the specified interface using an -access list.** - -Specify the direction in which the access list is applied: - -* ``in``: Filters incoming routes. -* ``out``: Filters outgoing routes. -``` - -```{cfgcmd} set protocols babel distribute-list \ prefix-list \ \ - -**Configure global Babel route filtering using a prefix list.** - -Specify the direction in which the prefix list is applied: - -* ``in``: Filters incoming routes. -* ``out``: Filters outgoing routes. -``` - -```{cfgcmd} set protocols babel distribute-list \ interface \ prefix-list \ \ - -**Configure Babel route filtering on the specified interface using a -prefix list.** - -Specify the direction in which the prefix list is applied: - -* ``in``: Filters incoming routes. -* ``out``: Filters outgoing routes. -``` - -## Configuration example - -### Basic two-node babel network - -**Goal:** The following example connects two routers (Node 1 and Node 2) via -their eth0 interfaces and uses the Babel routing protocol to advertise -(redistribute) each router's locally configured networks (represented by -loopback addresses) to one another. - -**Node 1:** - -```none -# Configure the loopback (local networks) and physical (eth0) addresses -set interfaces loopback lo address 10.1.1.1/32 -set interfaces loopback lo address fd12:3456:dead:beef::1/128 -set interfaces ethernet eth0 address 192.168.1.1/24 - -# Enable Babel on the physical link -set protocols babel interface eth0 type wired - -# Instruct Babel to advertise (redistribute) the locally configured networks -set protocols babel redistribute ipv4 connected -set protocols babel redistribute ipv6 connected -``` - -**Node 2:** - -```none -# Configure the loopback (local networks) and physical (eth0) addresses -set interfaces loopback lo address 10.2.2.2/32 -set interfaces loopback lo address fd12:3456:beef:dead::2/128 -set interfaces ethernet eth0 address 192.168.1.2/24 - -# Enable Babel on the physical link -set protocols babel interface eth0 type wired - -# Tell Babel to advertise (redistribute) the locally configured networks -set protocols babel redistribute ipv4 connected -set protocols babel redistribute ipv6 connected -``` diff --git a/docs/configuration/protocols/md-bfd.md b/docs/configuration/protocols/md-bfd.md deleted file mode 100644 index 59541abc..00000000 --- a/docs/configuration/protocols/md-bfd.md +++ /dev/null @@ -1,205 +0,0 @@ ---- -lastproofread: '2023-01-27' ---- - -```{include} /_include/need_improvement.txt -``` - -(routing-bfd)= - -# BFD - -{abbr}`BFD (Bidirectional Forwarding Detection)` is described and extended by -the following RFCs: {rfc}`5880`, {rfc}`5881` and {rfc}`5883`. - -In the age of very fast networks, a second of unreachability may equal millions of lost packets. -The idea behind BFD is to detect very quickly when a peer is down and take action extremely fast. - -BFD sends lots of small UDP packets very quickly to ensures that the peer is still alive. - -This allows avoiding the timers defined in BGP and OSPF protocol to expires. - -## Configure BFD - -```{cfgcmd} set protocols bfd peer \ - -Set BFD peer IPv4 address or IPv6 address -``` - -```{cfgcmd} set protocols bfd peer \ echo-mode - -Enables the echo transmission mode -``` - -```{cfgcmd} set protocols bfd peer \ multihop - -Allow this BFD peer to not be directly connected -``` - -```{cfgcmd} set protocols bfd peer \ source [address \ | interface \] - -Bind listener to specific interface/address, mandatory for IPv6 -``` - -```{cfgcmd} set protocols bfd peer \ interval echo-interval \<10-60000\> - -The minimal echo receive transmission interval that this system is -capable of handling -``` - -```{cfgcmd} set protocols bfd peer \ interval multiplier \<2-255\> - -Remote transmission interval will be multiplied by this value -``` - -```{cfgcmd} set protocols bfd peer \ interval [receive | transmit] \<10-60000\> - -Interval in milliseconds -``` - -```{cfgcmd} set protocols bfd peer \ shutdown - -Disable a BFD peer -``` - -```{cfgcmd} set protocols bfd peer \ minimum-ttl \<1-254\> - -For multi hop sessions only. Configure the minimum expected TTL for an -incoming BFD control packet. - -This feature serves the purpose of thightening the packet validation -requirements to avoid receiving BFD control packets from other sessions. -``` - -### Enable BFD in BGP - -```{cfgcmd} set protocols bgp neighbor \ bfd - -Enable BFD on a single BGP neighbor -``` - -```{cfgcmd} set protocols bgp peer-group \ bfd - -Enable BFD on a BGP peer group -``` - -### Enable BFD in OSPF - -```{cfgcmd} set protocols ospf interface \ bfd - - Enable BFD for OSPF on an interface - -``` - -```{cfgcmd} set protocols ospfv3 interface \ bfd - -Enable BFD for OSPFv3 on an interface -``` - -### Enable BFD in ISIS - -```{cfgcmd} set protocols isis \ interface \ bfd - -Enable BFD for ISIS on an interface - -``` - -## Operational Commands - -```{opcmd} show bfd peers - - Show all BFD peers - - :::{code-block} none - BFD Peers: - peer 198.51.100.33 vrf default interface eth4.100 - ID: 4182341893 - Remote ID: 12678929647 - Status: up - Uptime: 1 month(s), 16 hour(s), 29 minute(s), 38 second(s) - Diagnostics: ok - Remote diagnostics: ok - Local timers: - Receive interval: 300ms - Transmission interval: 300ms - Echo transmission interval: 50ms - Remote timers: - Receive interval: 300ms - Transmission interval: 300ms - Echo transmission interval: 0ms - - peer 198.51.100.55 vrf default interface eth4.101 - ID: 4618932327 - Remote ID: 3312345688 - Status: up - Uptime: 20 hour(s), 16 minute(s), 19 second(s) - Diagnostics: ok - Remote diagnostics: ok - Local timers: - Receive interval: 300ms - Transmission interval: 300ms - Echo transmission interval: 50ms - Remote timers: - Receive interval: 300ms - Transmission interval: 300ms - Echo transmission interval: 0ms - ::: -``` - -## BFD Static Route Monitoring - - -A monitored static route conditions the installation to the RIB on the BFD -session running state: when BFD session is up the route is installed to RIB, -but when the BFD session is down it is removed from the RIB. - - -### Configuration - -```{cfgcmd} set protocols static route \ next-hop \ bfd profile \ - -Configure a static route for \ using gateway \ -and use the gateway address as BFD peer destination address. -``` - -```{cfgcmd} set protocols static route \ next-hop \ bfd multi-hop source \ profile \ - -Configure a static route for \ using gateway \, -use source address to indentify the peer when is multi-hop session -and the gateway address as BFD peer destination address. -``` - -```{cfgcmd} set protocols static route6 \ next-hop \ bfd profile \ - -Configure a static route for \ using gateway \ -and use the gateway address as BFD peer destination address. -``` - -```{cfgcmd} set protocols static route6 \ next-hop \ bfd multi-hop source \ profile \ - -Configure a static route for \ using gateway \, -use source address to indentify the peer when is multi-hop session -and the gateway address as BFD peer destination address. -``` - -(bfd-operational-commands)= - -## Operational Commands - -```{opcmd} show bfd static routes - -Showing BFD monitored static routes - -:::{code-block} none -Showing BFD monitored static routes: - - Next hops: - VRF default IPv4 Unicast: - 10.10.13.3/32 peer 192.168.2.3 (status: installed) - 172.16.10.3/32 peer 192.168.10.1 (status: uninstalled) - - VRF default IPv4 Multicast: - - VRF default IPv6 Unicast: -::: -``` \ No newline at end of file diff --git a/docs/configuration/protocols/md-bgp.md b/docs/configuration/protocols/md-bgp.md deleted file mode 100644 index 0af79f6e..00000000 --- a/docs/configuration/protocols/md-bgp.md +++ /dev/null @@ -1,1414 +0,0 @@ -(routing-bgp)= - -# BGP - -{abbr}`BGP (Border Gateway Protocol)` is one of the Exterior Gateway Protocols -and the de facto standard interdomain routing protocol. The latest BGP version -is 4. BGP-4 is described in {rfc}`1771` and updated by {rfc}`4271`. {rfc}`2858` -adds multiprotocol support to BGP. - -VyOS makes use of {abbr}`FRR (Free Range Routing)` and we would like to thank -them for their effort! - -## Basic Concepts - -(bgp-autonomous-systems)= - -### Autonomous Systems - -From {rfc}`1930`: - -> An AS is a connected group of one or more IP prefixes run by one or more -> network operators which has a SINGLE and CLEARLY DEFINED routing policy. - -Each {abbr}`AS (Autonomous System)` has an identifying number associated with it -called an {abbr}`ASN (Autonomous System Number)`. This is a two octet value -ranging in value from 1 to 65535. The AS numbers 64512 through 65535 are defined -as private AS numbers. Private AS numbers must not be advertised on the global -Internet. The 2-byte AS number range has been exhausted. 4-byte AS numbers are -specified in {rfc}`6793`, and provide a pool of 4294967296 AS numbers. - -The {abbr}`ASN (Autonomous System Number)` is one of the essential elements of -BGP. BGP is a distance vector routing protocol, and the AS-Path framework -provides distance vector metric and loop detection to BGP. - -```{cfgcmd} set protocols bgp system-as \ - -Set local {abbr}`ASN (Autonomous System Number)` that this router represents. -This is a a mandatory option! -``` - -(bgp-address-families)= - - -### Address Families - - -Multiprotocol extensions enable BGP to carry routing information for multiple -network layer protocols. BGP supports an Address Family Identifier (AFI) for -IPv4 and IPv6. - - -(bgp-route-selection)= - - -### Route Selection - - -The route selection process used by FRR's BGP implementation uses the following -decision criterion, starting at the top of the list and going towards the -bottom until one of the factors can be used. - - -01. **Weight check** - - - Prefer higher local weight routes to lower routes. - - -02. **Local preference check** - - - Prefer higher local preference routes to lower. - - -03. **Local route check** - - - Prefer local routes (statics, aggregates, redistributed) to received routes. - - -04. **AS path length check** - - - Prefer shortest hop-count AS_PATHs. - - -05. **Origin check** - - - Prefer the lowest origin type route. That is, prefer IGP origin routes to - EGP, to Incomplete routes. - - -06. **MED check** - - - Where routes with a MED were received from the same AS, prefer the route - with the lowest MED. - - -07. **External check** - - - Prefer the route received from an external, eBGP peer over routes received - from other types of peers. - - -08. **IGP cost check** - - - Prefer the route with the lower IGP cost. - - -09. **Multi-path check** - - - If multi-pathing is enabled, then check whether the routes not yet - distinguished in preference may be considered equal. If - {cfgcmd}`bgp bestpath as-path multipath-relax` is set, all such routes are - considered equal, otherwise routes received via iBGP with identical AS_PATHs - or routes received from eBGP neighbours in the same AS are considered equal. - - -10. **Already-selected external check** - - - Where both routes were received from eBGP peers, then prefer the route - which is already selected. Note that this check is not applied if - {cfgcmd}`bgp bestpath compare-routerid` is configured. This check can - prevent some cases of oscillation. - - -11. **Router-ID check** - - - Prefer the route with the lowest router-ID. If the route has an - ORIGINATOR_ID attribute, through iBGP reflection, then that router ID is - used, otherwise the router-ID of the peer the route was received from is - used. - - -12. **Cluster-List length check** - - - The route with the shortest cluster-list length is used. The cluster-list - reflects the iBGP reflection path the route has taken. - - -13. **Peer address** - - - Prefer the route received from the peer with the higher transport layer - address, as a last-resort tie-breaker. - - -(bgp-capability-negotiation)= - - -### Capability Negotiation - - -When adding IPv6 routing information exchange feature to BGP. There were some -proposals. {abbr}`IETF (Internet Engineering Task Force)` -{abbr}`IDR (Inter Domain Routing)` adopted a proposal called Multiprotocol -Extension for BGP. The specification is described in {rfc}`2283`. The protocol -does not define new protocols. It defines new attributes to existing BGP. When -it is used exchanging IPv6 routing information it is called BGP-4+. When it is -used for exchanging multicast routing information it is called MBGP. - - -*bgpd* supports Multiprotocol Extension for BGP. So if a remote peer supports -the protocol, *bgpd* can exchange IPv6 and/or multicast routing information. - - -Traditional BGP did not have the feature to detect a remote peer's -capabilities, e.g. whether it can handle prefix types other than IPv4 unicast -routes. This was a big problem using Multiprotocol Extension for BGP in an -operational network. {rfc}`2842` adopted a feature called Capability -Negotiation. *bgpd* use this Capability Negotiation to detect the remote peer's -capabilities. If a peer is only configured as an IPv4 unicast neighbor, *bgpd* -does not send these Capability Negotiation packets (at least not unless other -optional BGP features require capability negotiation). - - -By default, FRR will bring up peering with minimal common capability for the -both sides. For example, if the local router has unicast and multicast -capabilities and the remote router only has unicast capability the local router -will establish the connection with unicast only capability. When there are no -common capabilities, FRR sends Unsupported Capability error and then resets the -connection. - - -## Configuration - - -(bgp-router-configuration)= - - -### BGP Router Configuration - - -First of all you must configure BGP router with the {abbr}`ASN (Autonomous -System Number)`. The AS number is an identifier for the autonomous system. -The BGP protocol uses the AS number for detecting whether the BGP connection -is internal or external. VyOS does not have a special command to start the BGP -process. The BGP process starts when the first neighbor is configured. - -```{cfgcmd} set protocols bgp system-as \ - -Set local autonomous system number that this router represents. This is a -mandatory option! -``` - -#### Peers Configuration - - -##### Defining Peers - -```{cfgcmd} set protocols bgp neighbor \ remote-as \ - -This command creates a new neighbor whose remote-as is \. The neighbor -address can be an IPv4 address or an IPv6 address or an interface to use -for the connection. The command is applicable for peer and peer group. -``` - - -```{cfgcmd} set protocols bgp neighbor \ remote-as internal - -Create a peer as you would when you specify an ASN, except that if the -peers ASN is different than mine as specified under the {cfgcmd}`protocols -bgp ` command the connection will be denied. -``` - - -```{cfgcmd} set protocols bgp neighbor \ remote-as external - -Create a peer as you would when you specify an ASN, except that if the -peers ASN is the same as mine as specified under the {cfgcmd}`protocols -bgp ` command the connection will be denied. -``` - - -```{cfgcmd} set protocols bgp neighbor \ remote-as auto - -Create a peer as you would when you specify an ASN, except that the peers -remote ASN is detected automatically from the OPEN message. -``` - - -```{cfgcmd} set protocols bgp neighbor \ local-role \ [strict] - -BGP roles are defined in RFC {rfc}`9234` and provide an easy way to -add route leak prevention, detection and mitigation. The local Role -value is negotiated with the new BGP Role capability which has a -built-in check of the corresponding value. In case of a mismatch the -new OPEN Roles Mismatch Notification <2, 11> would be sent. -The correct Role pairs are: - -Provider - Customer - -Peer - Peer - -RS-Server - RS-Client - -If {cfgcmd}`strict` is set the BGP session won’t become established -until the BGP neighbor sets local Role on its side. This -configuration parameter is defined in RFC {rfc}`9234` and is used to -enforce the corresponding configuration at your counter-parts side. - -Routes that are sent from provider, rs-server, or the peer local-role -(or if received by customer, rs-client, or the peer local-role) will -be marked with a new Only to Customer (OTC) attribute. - -Routes with this attribute can only be sent to your neighbor if your -local-role is provider or rs-server. Routes with this attribute can -be received only if your local-role is customer or rs-client. - -In case of peer-peer relationship routes can be received only if OTC -value is equal to your neighbor AS number. - -All these rules with OTC will help to detect and mitigate route leaks -and happen automatically if local-role is set. -``` - - -```{cfgcmd} set protocols bgp neighbor \ shutdown - -This command disable the peer or peer group. To reenable the peer use -the delete form of this command. -``` - - -```{cfgcmd} set protocols bgp neighbor \ description \ - -Set description of the peer or peer group. -``` - - -```{cfgcmd} set protocols bgp neighbor \ update-source \ - -Specify the IPv4 source address to use for the BGP session to this neighbor, -may be specified as either an IPv4 address directly or as an interface name. -``` - -(bgp-capability-negotiation-1)= - - -##### Capability Negotiation - -```{cfgcmd} set protocols bgp neighbor \ capability dynamic - -This command would allow the dynamic update of capabilities over an -established BGP session. -``` - - -```{cfgcmd} set protocols bgp neighbor \ capability extended-nexthop - -Allow bgp to negotiate the extended-nexthop capability with it’s peer. -If you are peering over a IPv6 Link-Local address then this capability -is turned on automatically. If you are peering over a IPv6 Global Address -then turning on this command will allow BGP to install IPv4 routes with -IPv6 nexthops if you do not have IPv4 configured on interfaces. -``` - - -```{cfgcmd} set protocols bgp neighbor \ disable-capability-negotiation - -Suppress sending Capability Negotiation as OPEN message optional -parameter to the peer. This command only affects the peer is -configured other than IPv4 unicast configuration. - -When remote peer does not have capability negotiation feature, -remote peer will not send any capabilities at all. In that case, -bgp configures the peer with configured capabilities. - -You may prefer locally configured capabilities more than the negotiated -capabilities even though remote peer sends capabilities. If the peer is -configured by {cfgcmd}`override-capability`, VyOS ignores received -capabilities then override negotiated capabilities with configured values. - -Additionally you should keep in mind that this feature fundamentally -disables the ability to use widely deployed BGP features. BGP unnumbered, -hostname support, AS4, Addpath, Route Refresh, ORF, Dynamic Capabilities, -and graceful restart. -``` - - -```{cfgcmd} set protocols bgp neighbor \ override-capability - -This command allow override the result of Capability Negotiation with -local configuration. Ignore remote peer’s capability value. -``` - - -```{cfgcmd} set protocols bgp neighbor \ strict-capability-match - -This command forces strictly compare remote capabilities and local -capabilities. If capabilities are different, send Unsupported Capability -error then reset connection. - -You may want to disable sending Capability Negotiation OPEN message -optional parameter to the peer when remote peer does not implement -Capability Negotiation. Please use {cfgcmd}`disable-capability-negotiation` -command to disable the feature. -``` - -##### Peer Parameters - -```{cfgcmd} set protocols bgp neighbor \ address-family \ allowas-in number \ - -This command accept incoming routes with AS path containing AS -number with the same value as the current system AS. This is -used when you want to use the same AS number in your sites, -but you can’t connect them directly. - - The number parameter (1-10) configures the amount of accepted - occurences of the system AS number in AS path. - - This command is only allowed for eBGP peers. It is not applicable - for peer groups. -``` - - -```{cfgcmd} set protocols bgp neighbor \ address-family \ as-override - -This command override AS number of the originating router with -the local AS number. - -Usually this configuration is used in PEs (Provider Edge) to -replace the incoming customer AS number so the connected CE ( -Customer Edge) can use the same AS number as the other customer -sites. This allows customers of the provider network to use the -same AS number across their sites. - -This command is only allowed for eBGP peers. -``` - - -```{cfgcmd} set protocols bgp neighbor \ address-family \ attribute-unchanged \ - -This command specifies attributes to be left unchanged for -advertisements sent to a peer or peer group. -``` - - -```{cfgcmd} set protocols bgp neighbor \ address-family \ maximum-prefix \ - -This command specifies a maximum number of prefixes we can receive -from a given peer. If this number is exceeded, the BGP session -will be destroyed. The number range is 1 to 4294967295. -``` - - -```{cfgcmd} set protocols bgp neighbor \ address-family \ nexthop-self - -This command forces the BGP speaker to report itself as the -next hop for an advertised route it advertised to a neighbor. -``` - - -```{cfgcmd} set protocols bgp neighbor \ address-family \ remove-private-as - -This command removes the private ASN of routes that are advertised -to the configured peer. It removes only private ASNs on routes -advertised to EBGP peers. - -If the AS-Path for the route has only private ASNs, the private -ASNs are removed. - -If the AS-Path for the route has a private ASN between public -ASNs, it is assumed that this is a design choice, and the -private ASN is not removed. -``` - - -```{cfgcmd} set protocols bgp neighbor \ address-family \ soft-reconfiguration inbound - -Changes in BGP policies require the BGP session to be cleared. Clearing has a -large negative impact on network operations. Soft reconfiguration enables you -to generate inbound updates from a neighbor, change and activate BGP policies -without clearing the BGP session. - -This command specifies that route updates received from this neighbor will be -stored unmodified, regardless of the inbound policy. When inbound soft -reconfiguration is enabled, the stored updates are processed by the new -policy configuration to create new inbound updates. - -:::{note} -Storage of route updates uses memory. If you enable soft -reconfiguration inbound for multiple neighbors, the amount of memory used -can become significant. -::: -``` - - -```{cfgcmd} set protocols bgp neighbor \ address-family \ weight \ - -This command specifies a default weight value for the neighbor’s -routes. The number range is 1 to 65535. -``` - - -```{cfgcmd} set protocols bgp neighbor \ advertisement-interval \ - -This command specifies the minimum route advertisement interval for -the peer. The interval value is 0 to 600 seconds, with the default -advertisement interval being 0. -``` - - -```{cfgcmd} set protocols bgp neighbor \ disable-connected-check - -This command allows peerings between directly connected eBGP peers -using loopback addresses without adjusting the default TTL of 1. -``` - - -```{cfgcmd} set protocols bgp neighbor \ disable-send-community \ - -This command specifies that the community attribute should not be sent -in route updates to a peer. By default community attribute is sent. -``` - - -```{cfgcmd} set protocols bgp neighbor \ ebgp-multihop \ - -This command allows sessions to be established with eBGP neighbors -when they are multiple hops away. When the neighbor is not directly -connected and this knob is not enabled, the session will not establish. -The number of hops range is 1 to 255. This command is mutually -exclusive with {cfgcmd}`ttl-security hops`. -``` - - -```{cfgcmd} set protocols bgp neighbor \ local-as \ [no-prepend] [replace-as] - -Specify an alternate AS for this BGP process when interacting with -the specified peer or peer group. With no modifiers, the specified -local-as is prepended to the received AS_PATH when receiving routing -updates from the peer, and prepended to the outgoing AS_PATH (after -the process local AS) when transmitting local routes to the peer. - -If the {cfgcmd}`no-prepend` attribute is specified, then the supplied -local-as is not prepended to the received AS_PATH. - -If the {cfgcmd}`replace-as` attribute is specified, then only the supplied -local-as is prepended to the AS_PATH when transmitting local-route -updates to this peer. - -:::{note} -This command is only allowed for eBGP peers. -::: -``` - - -```{cfgcmd} set protocols bgp neighbor \ passive - -Configures the BGP speaker so that it only accepts inbound connections -from, but does not initiate outbound connections to the peer or peer group. -``` - - -```{cfgcmd} set protocols bgp neighbor \ password \ - -This command specifies a MD5 password to be used with the tcp socket that -is being used to connect to the remote peer. -``` - - -```{cfgcmd} set protocols bgp neighbor \ ttl-security hops \ - -This command enforces Generalized TTL Security Mechanism (GTSM), -as specified in {rfc}`5082`. With this command, only neighbors -that are specified number of hops away will be allowed to -become neighbors. The number of hops range is 1 to 254. This -command is mutually exclusive with {cfgcmd}`ebgp-multihop`. -``` - -##### Peer Groups - -Peer groups are used to help improve scaling by generating the same update -information to all members of a peer group. Note that this means that the -routes generated by a member of a peer group will be sent back to that -originating peer with the originator identifier attribute set to indicated -the originating peer. All peers not associated with a specific peer group -are treated as belonging to a default peer group, and will share updates. - -```{cfgcmd} set protocols bgp peer-group \ - - This command defines a new peer group. You can specify to the group the same - parameters that you can specify for specific neighbors. - - :::{note} - If you apply a parameter to an individual neighbor IP address, you - override the action defined for a peer group that includes that IP - address. - ::: -``` - - -```{cfgcmd} set protocols bgp neighbor \ peer-group \ - -This command bind specific peer to peer group with a given name. -``` - -#### Network Advertisement Configuration - -```{cfgcmd} set protocols bgp address-family \ network \ - -This command is used for advertising IPv4 or IPv6 networks. - - :::{note} - By default, the BGP prefix is advertised even if it's not present - in the routing table. This behaviour differs from the implementation of - some vendors. - ::: -``` - - -```{cfgcmd} set protocols bgp parameters network-import-check - -This configuration modifies the behavior of the network statement. If you -have this configured the underlying network must exist in the routing table. -``` - - -```{cfgcmd} set protocols bgp neighbor \ address-family \ default-originate [route-map \] - -By default, VyOS does not advertise a default route (0.0.0.0/0) even if it is -in routing table. When you want to announce default routes to the peer, use -this command. Using optional argument {cfgcmd}`route-map` you can inject the -default route to given neighbor only if the conditions in the route map are -met. -``` - -#### Route Aggregation Configuration - -```{cfgcmd} set protocols bgp address-family \ aggregate-address \ - -This command specifies an aggregate address. The router will also -announce longer-prefixes inside of the aggregate address. -``` - - -```{cfgcmd} set protocols bgp address-family \ aggregate-address \ as-set - -This command specifies an aggregate address with a mathematical set of -autonomous systems. This command summarizes the AS_PATH attributes of -all the individual routes. -``` - - -```{cfgcmd} set protocols bgp address-family \ aggregate-address \ summary-only - -This command specifies an aggregate address and provides that -longer-prefixes inside of the aggregate address are suppressed -before sending BGP updates out to peers. -``` - - -```{cfgcmd} set protocols bgp neighbor \ address-family \ unsuppress-map \ - -This command applies route-map to selectively unsuppress prefixes -suppressed by summarisation. -``` - -#### Redistribution Configuration - -```{cfgcmd} set protocols bgp address-family \ redistribute - -This command redistributes routing information from the given route source -to the BGP process. There are six modes available for route source: -connected, kernel, ospf, rip, static, table. -``` - - -```{cfgcmd} set protocols bgp address-family \ redistribute metric \ - -This command specifies metric (MED) for redistributed routes. The -metric range is 0 to 4294967295. There are six modes available for -route source: connected, kernel, ospf, rip, static, table. -``` - - -```{cfgcmd} set protocols bgp address-family \ redistribute route-map \ - -This command allows to use route map to filter redistributed routes. -There are six modes available for route source: connected, kernel, -ospf, rip, static, table. -``` - -#### General Configuration -##### Common parameters - -```{cfgcmd} set protocols bgp parameters allow-martian-nexthop - - When a peer receives a martian nexthop as part of the NLRI for a route - permit the nexthop to be used as such, instead of rejecting and resetting - the connection. -``` - - -```{cfgcmd} set protocols bgp parameters router-id \ - -This command specifies the router-ID. If router ID is not specified it will -use the highest interface IP address. -``` - - -```{cfgcmd} set protocols bgp address-family \ maximum-paths \ \ - -This command defines the maximum number of parallel routes that -the BGP can support. In order for BGP to use the second path, the -following attributes have to match: Weight, Local Preference, AS -Path (both AS number and AS path length), Origin code, MED, IGP -metric. Also, the next hop address for each path must be different. -``` - - -```{cfgcmd} set protocols bgp parameters no-hard-administrative-reset - -Do not send Hard Reset CEASE Notification for "Administrative Reset" -events. When set and Graceful Restart Notification capability is exchanged -between the peers, Graceful Restart procedures apply, and routes will be retained. -``` - - -```{cfgcmd} set protocols bgp parameters log-neighbor-changes - -This command enable logging neighbor up/down changes and reset reason. -``` - - -```{cfgcmd} set protocols bgp parameters no-client-to-client-reflection - -This command disables route reflection between route reflector clients. -By default, the clients of a route reflector are not required to be -fully meshed and the routes from a client are reflected to other clients. -However, if the clients are fully meshed, route reflection is not required. -In this case, use the {cfgcmd}`no-client-to-client-reflection` command -to disable client-to-client reflection. -``` - - -```{cfgcmd} set protocols bgp parameters no-fast-external-failover - -Disable immediate session reset if peer's connected link goes down. -``` - - -```{cfgcmd} set protocols bgp parameters no-ipv6-auto-ra - -By default, FRR sends router advertisement packets when Extended Next Hop is -on or when a connection is established directly using the device name (Unnumbered BGP). -Setting this option prevents FRR from sending router advertisement packets, but could break Unnumbered BGP. -``` - - -```{cfgcmd} set protocols bgp listen range \ peer-group \ - -This command is useful if one desires to loosen the requirement for BGP -to have strictly defined neighbors. Specifically what is allowed is for -the local router to listen to a range of IPv4 or IPv6 addresses defined -by a prefix and to accept BGP open messages. When a TCP connection -(and subsequently a BGP open message) from within this range tries to -connect the local router then the local router will respond and connect -with the parameters that are defined within the peer group. One must define -a peer-group for each range that is listed. If no peer-group is defined -then an error will keep you from committing the configuration. -``` - - -```{cfgcmd} set protocols bgp listen limit \ - -This command goes hand in hand with the listen range command to limit the -amount of BGP neighbors that are allowed to connect to the local router. -The limit range is 1 to 5000. -``` - - -```{cfgcmd} set protocols bgp parameters ebgp-requires-policy - -This command changes the eBGP behavior of FRR. By default FRR enables -{rfc}`8212` functionality which affects how eBGP routes are advertised, -namely no routes are advertised across eBGP sessions without some -sort of egress route-map/policy in place. In VyOS however we have this -RFC functionality disabled by default so that we can preserve backwards -compatibility with older versions of VyOS. With this option one can -enable {rfc}`8212` functionality to operate. -``` - - -```{cfgcmd} set protocols bgp parameters labeled-unicast \ - -By default, locally advertised prefixes use the implicit-null label to -encode in the outgoing NLRI. - -The following command uses the explicit-null label value for all the -BGP instances. -``` - -##### Administrative Distance - -```{cfgcmd} set protocols bgp parameters distance global \ \ - -This command change distance value of BGP. The arguments are the distance -values for external routes, internal routes and local routes respectively. -The distance range is 1 to 255. -``` - - -```{cfgcmd} set protocols bgp parameters distance prefix \ distance \ - -This command sets the administrative distance for a particular route. The -distance range is 1 to 255. - -:::{note} -Routes with a distance of 255 are effectively disabled and not -installed into the kernel. -::: -``` - -##### Timers - -```{cfgcmd} set protocols bgp timers holdtime \ - - This command specifies hold-time in seconds. The timer range is - 4 to 65535. The default value is 180 second. If you set value to 0 - VyOS will not hold routes. -``` - - -```{cfgcmd} set protocols bgp timers keepalive \ - -This command specifies keep-alive time in seconds. The timer -can range from 4 to 65535. The default value is 60 second. -``` - -##### Route Dampening - -When a route fails, a routing update is sent to withdraw the route from the -network's routing tables. When the route is re-enabled, the change in -availability is also advertised. A route that continually fails and returns -requires a great deal of network traffic to update the network about the -route's status. - -Route dampening wich described in {rfc}`2439` enables you to identify routes -that repeatedly fail and return. If route dampening is enabled, an unstable -route accumulates penalties each time the route fails and returns. If the -accumulated penalties exceed a threshold, the route is no longer advertised. -This is route suppression. Routes that have been suppressed are re-entered -into the routing table only when the amount of their penalty falls below a -threshold. - -A penalty of 1000 is assessed each time the route fails. When the penalties -reach a predefined threshold (suppress-value), the router stops advertising -the route. - -Once a route is assessed a penalty, the penalty is decreased by half each time -a predefined amount of time elapses (half-life-time). When the accumulated -penalties fall below a predefined threshold (reuse-value), the route is -unsuppressed and added back into the BGP routing table. - -No route is suppressed indefinitely. Maximum-suppress-time defines the maximum -time a route can be suppressed before it is re-advertised. - -```{cfgcmd} set protocols bgp parameters dampening half-life \ - -This command defines the amount of time in minutes after -which a penalty is reduced by half. The timer range is -10 to 45 minutes. -``` - - -```{cfgcmd} set protocols bgp parameters dampening re-use \ - -This command defines the accumulated penalty amount at which the -route is re-advertised. The penalty range is 1 to 20000. -``` - - -```{cfgcmd} set protocols bgp parameters dampening start-suppress-time \ - -This command defines the accumulated penalty amount at which the -route is suppressed. The penalty range is 1 to 20000. -``` - - -```{cfgcmd} set protocols bgp parameters dampening max-suppress-time \ - -This command defines the maximum time in minutes that a route is -suppressed. The timer range is 1 to 255 minutes. -``` - -#### Route Selection Configuration - -```{cfgcmd} set protocols bgp parameters always-compare-med - - This command provides to compare the MED on routes, even when they were - received from different neighbouring ASes. Setting this option makes the - order of preference of routes more defined, and should eliminate MED - induced oscillations. -``` - - -```{cfgcmd} set protocols bgp parameters bestpath as-path confed - -This command specifies that the length of confederation path sets and -sequences should be taken into account during the BGP best path -decision process. -``` - - -```{cfgcmd} set protocols bgp parameters bestpath as-path multipath-relax - -This command specifies that BGP decision process should consider paths -of equal AS_PATH length candidates for multipath computation. Without -the knob, the entire AS_PATH must match for multipath computation. -``` - - -```{cfgcmd} set protocols bgp parameters bestpath as-path ignore - -Ignore AS_PATH length when selecting a route -``` - - -```{cfgcmd} set protocols bgp parameters bestpath compare-routerid - -Ensure that when comparing routes where both are equal on most metrics, -including local-pref, AS_PATH length, IGP cost, MED, that the tie is -broken based on router-ID. - -If this option is enabled, then the already-selected check, where -already selected eBGP routes are preferred, is skipped. - -If a route has an ORIGINATOR_ID attribute because it has been reflected, -that ORIGINATOR_ID will be used. Otherwise, the router-ID of the peer -the route was received from will be used. - -The advantage of this is that the route-selection (at this point) will -be more deterministic. The disadvantage is that a few or even one lowest-ID -router may attract all traffic to otherwise-equal paths because of this -check. It may increase the possibility of MED or IGP oscillation, unless -other measures were taken to avoid these. The exact behaviour will be -sensitive to the iBGP and reflection topology. -``` - - -```{cfgcmd} set protocols bgp parameters bestpath med confed - -This command specifies that BGP considers the MED when comparing routes -originated from different sub-ASs within the confederation to which this -BGP speaker belongs. The default state, where the MED attribute is not -considered. -``` - - -```{cfgcmd} set protocols bgp parameters bestpath med missing-as-worst - -This command specifies that a route with a MED is always considered to be -better than a route without a MED by causing the missing MED attribute to -have a value of infinity. The default state, where the missing MED -attribute is considered to have a value of zero. -``` - - -```{cfgcmd} set protocols bgp parameters default local-pref - -This command specifies the default local preference value. The local -preference range is 0 to 4294967295. -``` - - -```{cfgcmd} set protocols bgp parameters deterministic-med - -This command provides to compare different MED values that advertised by -neighbours in the same AS for routes selection. When this command is -enabled, routes from the same autonomous system are grouped together, and -the best entries of each group are compared. -``` - - -```{cfgcmd} set protocols bgp address-family ipv4-unicast network \ backdoor - -This command allows the router to prefer route to specified prefix learned -via IGP through backdoor link instead of a route to the same prefix learned -via EBGP. -``` - -#### Route Filtering Configuration - -In order to control and modify routing information that is exchanged between -peers you can use route-map, filter-list, prefix-list, distribute-list. - -For inbound updates the order of preference is: - -> - route-map -> - filter-list -> - prefix-list, distribute-list - -For outbound updates the order of preference is: -> - prefix-list, distribute-list -> - filter-list -> - route-map -> -> :::{note} -> The attributes {cfgcmd}`prefix-list` and {cfgcmd}`distribute-list` -> are mutually exclusive, and only one command (distribute-list or -> prefix-list) can be applied to each inbound or outbound direction for a -> particular neighbor. -> ::: - -```{cfgcmd} set protocols bgp neighbor \ address-family \ distribute-list \ \ - -This command applies the access list filters named in \ to the -specified BGP neighbor to restrict the routing information that BGP learns -and/or advertises. The arguments {cfgcmd}`export` and {cfgcmd}`import` -specify the direction in which the access list are applied. -``` - - -```{cfgcmd} set protocols bgp neighbor \ address-family \ prefix-list \ \ - -This command applies the prfefix list filters named in \ to the -specified BGP neighbor to restrict the routing information that BGP learns -and/or advertises. The arguments {cfgcmd}`export` and {cfgcmd}`import` -specify the direction in which the prefix list are applied. -``` - - -```{cfgcmd} set protocols bgp neighbor \ address-family \ route-map \ \ - -This command applies the route map named in \ to the specified BGP -neighbor to control and modify routing information that is exchanged -between peers. The arguments {cfgcmd}`export` and {cfgcmd}`import` -specify the direction in which the route map are applied. -``` - - -```{cfgcmd} set protocols bgp neighbor \ address-family \ filter-list \ \ - -This command applies the AS path access list filters named in \ to the -specified BGP neighbor to restrict the routing information that BGP learns -and/or advertises. The arguments {cfgcmd}`export` and {cfgcmd}`import` -specify the direction in which the AS path access list are applied. -``` - - -```{cfgcmd} set protocols bgp neighbor \ address-family \ capability orf \ - -This command enables the ORF capability (described in {rfc}`5291`) on the -local router, and enables ORF capability advertisement to the specified BGP -peer. The {cfgcmd}`receive` keyword configures a router to advertise ORF -receive capabilities. The {cfgcmd}`send` keyword configures a router to -advertise ORF send capabilities. To advertise a filter from a sender, you -must create an IP prefix list for the specified BGP peer applied in inbound -derection. -``` - - -```{cfgcmd} set protocols bgp neighbor \ solo - -This command prevents from sending back prefixes learned from the neighbor. -``` - -#### BGP Scaling Configuration - - -BGP routers connected inside the same AS through BGP belong to an internal BGP -session, or IBGP. In order to prevent routing table loops, IBGP speaker does -not advertise IBGP-learned routes to other IBGP speaker (Split Horizon -mechanism). As such, IBGP requires a full mesh of all peers. For large -networks, this quickly becomes unscalable. - - -There are two ways that help us to mitigate the BGPs full-mesh requirement in -a network: - - -> - Using BGP route-reflectors -> - Using BGP confederation - - -##### Route Reflector Configuration - - -Introducing route reflectors removes the need for the full-mesh. When you -configure a route reflector you have to tell the router whether the other IBGP -router is a client or non-client. A client is an IBGP router that the route -reflector will “reflect” routes to, the non-client is just a regular IBGP -neighbor. Route reflectors mechanism is described in {rfc}`4456` and updated -by {rfc}`7606`. - -```{cfgcmd} set protocols bgp neighbor \ address-family \ route-reflector-client - -This command specifies the given neighbor as route reflector client. -``` - - -```{cfgcmd} set protocols bgp parameters cluster-id \ - -This command specifies cluster ID which identifies a collection of route -reflectors and their clients, and is used by route reflectors to avoid -looping. By default cluster ID is set to the BGP router id value, but can be -set to an arbitrary 32-bit value. -``` - -##### Confederation Configuration - -A BGP confederation divides our AS into sub-ASes to reduce the number of -required IBGP peerings. Within a sub-AS we still require full-mesh IBGP but -between these sub-ASes we use something that looks like EBGP but behaves like -IBGP (called confederation BGP). Confederation mechanism is described in -{rfc}`5065` - -```{cfgcmd} set protocols bgp parameters confederation identifier \ - -This command specifies a BGP confederation identifier. \ is the number -of the autonomous system that internally includes multiple sub-autonomous -systems (a confederation). -``` - - -```{cfgcmd} set protocols bgp parameters confederation peers \ - -This command sets other confederations \ as members of autonomous -system specified by {cfgcmd}`confederation identifier `. -``` - -## Operational Mode Commands -### Show - -```{opcmd} show bgp \ - - This command displays all entries in BGP routing table. -``` - - -```none -BGP table version is 10, local router ID is 10.0.35.3, vrf id 0 -Default local pref 100, local AS 65000 -Status codes: s suppressed, d damped, h history, * valid, > best, = multipath, - i internal, r RIB-failure, S Stale, R Removed -Nexthop codes: @NNN nexthop's vrf id, < announce-nh-self -Origin codes: i - IGP, e - EGP, ? - incomplete -RPKI validation codes: V valid, I invalid, N Not found - - Network Next Hop Metric LocPrf Weight Path -*> 198.51.100.0/24 10.0.34.4 0 0 65004 i -*> 203.0.113.0/24 10.0.35.5 0 0 65005 i - -Displayed 2 routes and 2 total paths -``` - - -```{opcmd} show bgp \ \ - -This command displays information about the particular entry in the BGP -routing table. -``` - - -```none -BGP routing table entry for 198.51.100.0/24 -Paths: (1 available, best #1, table default) - Advertised to non peer-group peers: - 10.0.13.1 10.0.23.2 10.0.34.4 10.0.35.5 - 65004 - 10.0.34.4 from 10.0.34.4 (10.0.34.4) - Origin IGP, metric 0, valid, external, best (First path received) - Last update: Wed Jan 6 12:18:53 2021 -``` - - -```{opcmd} show bgp cidr-only - -This command displays routes with classless interdomain routing (CIDR). -``` - - -```{opcmd} show bgp \ community \ - -This command displays routes that belong to specified BGP communities. -Valid value is a community number in the range from 1 to 4294967200, -or AA:NN (autonomous system-community number/2-byte number), no-export, -local-as, or no-advertise. -``` - - -```{opcmd} show bgp \ community-list \ - -This command displays routes that are permitted by the BGP -community list. -``` - - -```{opcmd} show bgp \ dampening dampened-paths - -This command displays BGP dampened routes. -``` - - -```{opcmd} show bgp \ dampening flap-statistics - -This command displays information about flapping BGP routes. -``` - - -```{opcmd} show bgp \ filter-list \ - -This command displays BGP routes allowed by the specified AS Path -access list. -``` - - -```{opcmd} show bgp \ neighbors \ advertised-routes - -This command displays BGP routes advertised to a neighbor. -``` - - -```{opcmd} show bgp \ neighbors \ received-routes - -This command displays BGP routes originating from the specified BGP -neighbor before inbound policy is applied. To use this command inbound -soft reconfiguration must be enabled. -``` - - -```{opcmd} show bgp \ neighbors \ routes - -This command displays BGP received-routes that are accepted after filtering. -``` - - -```{opcmd} show bgp \ neighbors \ dampened-routes - -This command displays dampened routes received from BGP neighbor. -``` - - -```{opcmd} show bgp \ regexp \ - -This command displays information about BGP routes whose AS path -matches the specified regular expression. -``` - - -```{opcmd} show bgp \ summary - -This command displays the status of all BGP connections. -``` - - -```none -IPv4 Unicast Summary: -BGP router identifier 10.0.35.3, local AS number 65000 vrf-id 0 -BGP table version 11 -RIB entries 5, using 920 bytes of memory -Peers 4, using 82 KiB of memory - -Neighbor V AS MsgRcvd MsgSent TblVer InQ OutQ Up/Down State/PfxRcd -10.0.13.1 4 65000 148 159 0 0 0 02:16:01 0 -10.0.23.2 4 65000 136 143 0 0 0 02:13:21 0 -10.0.34.4 4 65004 161 163 0 0 0 02:16:01 1 -10.0.35.5 4 65005 162 166 0 0 0 02:16:01 1 - -Total number of neighbors 4 -``` - -### Reset - -```{opcmd} reset bgp \ \ [soft [in|out]] - -This command resets BGP connections to the specified neighbor IP address. -With argument {cfgcmd}`soft` this command initiates a soft reset. If -you do not specify the {cfgcmd}`in` or {cfgcmd}`out` options, both -inbound and outbound soft reconfiguration are triggered. -``` - - -```{opcmd} reset bgp all - -This command resets all BGP connections of given router. -``` - - -```{opcmd} reset bgp \ external - -This command resets all external BGP peers of given router. -``` - - -```{opcmd} reset bgp \ peer-group \ [soft [in|out]] - -This command resets BGP connections to the specified peer group. -With argument {cfgcmd}`soft` this command initiates a soft reset. If -you do not specify the {cfgcmd}`in` or {cfgcmd}`out` options, both -inbound and outbound soft reconfiguration are triggered. -``` - -## Examples -### IPv4 peering - -A simple eBGP configuration: - -**Node 1:** - -```none -set protocols bgp system-as 65534 -set protocols bgp neighbor 192.168.0.2 ebgp-multihop '2' -set protocols bgp neighbor 192.168.0.2 remote-as '65535' -set protocols bgp neighbor 192.168.0.2 update-source '192.168.0.1' -set protocols bgp neighbor 192.168.0.2 address-family ipv4-unicast -set protocols bgp address-family ipv4-unicast network '172.16.0.0/16' -set protocols bgp parameters router-id '192.168.0.1' -``` - -**Node 2:** - -```none -set protocols bgp system-as 65535 -set protocols bgp neighbor 192.168.0.1 ebgp-multihop '2' -set protocols bgp neighbor 192.168.0.1 remote-as '65534' -set protocols bgp neighbor 192.168.0.1 update-source '192.168.0.2' -set protocols bgp neighbor 192.168.0.1 address-family ipv4-unicast -set protocols bgp address-family ipv4-unicast network '172.17.0.0/16' -set protocols bgp parameters router-id '192.168.0.2' -``` - -Don't forget, the CIDR declared in the network statement MUST **exist in your -routing table (dynamic or static), the best way to make sure that is true is -creating a static route:** - -**Node 1:** - -```none -set protocols static route 172.16.0.0/16 blackhole distance '254' -``` - -**Node 2:** - -```none -set protocols static route 172.17.0.0/16 blackhole distance '254' -``` - -### IPv6 peering - -A simple BGP configuration via IPv6. - -**Node 1:** - -```none -set protocols bgp system-as 65534 -set protocols bgp neighbor 2001:db8::2 ebgp-multihop '2' -set protocols bgp neighbor 2001:db8::2 remote-as '65535' -set protocols bgp neighbor 2001:db8::2 update-source '2001:db8::1' -set protocols bgp neighbor 2001:db8::2 address-family ipv6-unicast -set protocols bgp address-family ipv6-unicast network '2001:db8:1::/48' -set protocols bgp parameters router-id '10.1.1.1' -``` - -**Node 2:** - -```none -set protocols bgp system-as 65535 -set protocols bgp neighbor 2001:db8::1 ebgp-multihop '2' -set protocols bgp neighbor 2001:db8::1 remote-as '65534' -set protocols bgp neighbor 2001:db8::1 update-source '2001:db8::2' -set protocols bgp neighbor 2001:db8::1 address-family ipv6-unicast -set protocols bgp address-family ipv6-unicast network '2001:db8:2::/48' -set protocols bgp parameters router-id '10.1.1.2' -``` - -Don't forget, the CIDR declared in the network statement **MUST exist in your -routing table (dynamic or static), the best way to make sure that is true is -creating a static route:** - -**Node 1:** - -```none -set protocols static route6 2001:db8:1::/48 blackhole distance '254' -``` - -**Node 2:** - -```none -set protocols static route6 2001:db8:2::/48 blackhole distance '254' -``` - -### Route Filtering - -Route filter can be applied using a route-map: - -**Node1:** - -```none -set policy prefix-list AS65535-IN rule 10 action 'permit' -set policy prefix-list AS65535-IN rule 10 prefix '172.16.0.0/16' -set policy prefix-list AS65535-OUT rule 10 action 'deny' -set policy prefix-list AS65535-OUT rule 10 prefix '172.16.0.0/16' -set policy prefix-list6 AS65535-IN rule 10 action 'permit' -set policy prefix-list6 AS65535-IN rule 10 prefix '2001:db8:2::/48' -set policy prefix-list6 AS65535-OUT rule 10 action 'deny' -set policy prefix-list6 AS65535-OUT rule 10 prefix '2001:db8:2::/48' - -set policy route-map AS65535-IN rule 10 action 'permit' -set policy route-map AS65535-IN rule 10 match ip address prefix-list 'AS65535-IN' -set policy route-map AS65535-IN rule 10 match ipv6 address prefix-list 'AS65535-IN' -set policy route-map AS65535-IN rule 20 action 'deny' -set policy route-map AS65535-OUT rule 10 action 'deny' -set policy route-map AS65535-OUT rule 10 match ip address prefix-list 'AS65535-OUT' -set policy route-map AS65535-OUT rule 10 match ipv6 address prefix-list 'AS65535-OUT' -set policy route-map AS65535-OUT rule 20 action 'permit' - -set protocols bgp system-as 65534 -set protocols bgp neighbor 2001:db8::2 address-family ipv4-unicast route-map export 'AS65535-OUT' -set protocols bgp neighbor 2001:db8::2 address-family ipv4-unicast route-map import 'AS65535-IN' -set protocols bgp neighbor 2001:db8::2 address-family ipv6-unicast route-map export 'AS65535-OUT' -set protocols bgp neighbor 2001:db8::2 address-family ipv6-unicast route-map import 'AS65535-IN' -``` - -**Node2:** - -```none -set policy prefix-list AS65534-IN rule 10 action 'permit' -set policy prefix-list AS65534-IN rule 10 prefix '172.17.0.0/16' -set policy prefix-list AS65534-OUT rule 10 action 'deny' -set policy prefix-list AS65534-OUT rule 10 prefix '172.17.0.0/16' -set policy prefix-list6 AS65534-IN rule 10 action 'permit' -set policy prefix-list6 AS65534-IN rule 10 prefix '2001:db8:1::/48' -set policy prefix-list6 AS65534-OUT rule 10 action 'deny' -set policy prefix-list6 AS65534-OUT rule 10 prefix '2001:db8:1::/48' - -set policy route-map AS65534-IN rule 10 action 'permit' -set policy route-map AS65534-IN rule 10 match ip address prefix-list 'AS65534-IN' -set policy route-map AS65534-IN rule 10 match ipv6 address prefix-list 'AS65534-IN' -set policy route-map AS65534-IN rule 20 action 'deny' -set policy route-map AS65534-OUT rule 10 action 'deny' -set policy route-map AS65534-OUT rule 10 match ip address prefix-list 'AS65534-OUT' -set policy route-map AS65534-OUT rule 10 match ipv6 address prefix-list 'AS65534-OUT' -set policy route-map AS65534-OUT rule 20 action 'permit' - -set protocols bgp system-as 65535 -set protocols bgp neighbor 2001:db8::1 address-family ipv4-unicast route-map export 'AS65534-OUT' -set protocols bgp neighbor 2001:db8::1 address-family ipv4-unicast route-map import 'AS65534-IN' -set protocols bgp neighbor 2001:db8::1 address-family ipv6-unicast route-map export 'AS65534-OUT' -set protocols bgp neighbor 2001:db8::1 address-family ipv6-unicast route-map import 'AS65534-IN' -``` - -We could expand on this and also deny link local and multicast in the rule 20 -action deny. diff --git a/docs/configuration/protocols/md-failover.md b/docs/configuration/protocols/md-failover.md deleted file mode 100644 index 96374d11..00000000 --- a/docs/configuration/protocols/md-failover.md +++ /dev/null @@ -1,237 +0,0 @@ ---- -description: |- - Failover routes are static routes that are installed in the routing - table only while a configured health-check target responds. VyOS uses them - to switch traffic to a backup path when the primary next hop becomes - unreachable, and to restore the primary path automatically once it recovers. -keywords: |- - failover, failover route, static route, health check, icmp probe, - next hop, route metric ---- - -# Failover - -Failover routes are manually configured network paths used only while their -health-check targets are reachable. If the target stops responding, VyOS -removes the route from the routing table and reinstalls it once the target -recovers. - -## Configuration - -Use the following commands to configure failover routes for a specific remote -`` reachable via next-hop `
`. - -```{eval-rst} -.. cfgcmd:: set protocols failover route next-hop
check target - - **Configure the health check target IP address.** - - This is typically a highly available host, either within the destination - subnet or on the public internet. - - Example: - - .. code-block:: none - - set protocols failover route 203.0.113.1/32 next-hop 10.217.37.254 check target 8.8.8.8 -``` - -```{eval-rst} -.. cfgcmd:: set protocols failover route next-hop
check timeout - - **Configure the timeout interval, in seconds, between target health checks.** - - The valid range is 1 to 300 seconds. The default is 10 seconds. - - Example: - - .. code-block:: none - - set protocols failover route 203.0.113.1/32 next-hop 10.217.37.254 check timeout 2 -``` - -```{eval-rst} -.. cfgcmd:: set protocols failover route next-hop
check type - - **Configure the protocol to use for health checks.** - - The following protocols are available: - - * ``icmp``: VyOS sends two ICMP echo request packets with a 1-second - response timeout. The health check is successful if at least one response - is received. - * ``arp``: VyOS sends two ARP requests with a 1-second response timeout. - The health check is successful if at least one response is received. - * ``tcp``: VyOS verifies whether the destination TCP port is open. The - health check is successful if a TCP connection is successfully - established with the target port. - - The default protocol is ``icmp``. - - .. note:: - - When the check type is set to ``tcp``, you must also define the target - TCP port. - - Example: - - .. code-block:: none - - set protocols failover route 203.0.113.1/32 next-hop 10.217.37.254 check type tcp -``` - -```{eval-rst} -.. cfgcmd:: set protocols failover route next-hop
check port - - **Configure the destination TCP port on the health check target.** - - This parameter applies only when the check type is configured as ``tcp``. - - The valid port range is 1 to 65535. - - Example: - - .. code-block:: none - - set protocols failover route 203.0.113.1/32 next-hop 10.217.37.254 check port 443 -``` - -```{eval-rst} -.. cfgcmd:: set protocols failover route next-hop
check policy - - **Configure the health check success policy for multiple targets.** - - The following policies are available: - - * ``any-available``: The health check succeeds if at least one of the - configured targets responds successfully. - * ``all-available``: The health check succeeds only if every configured - target responds successfully. - - The default policy is ``any-available``. - - Example: - - .. code-block:: none - - set protocols failover route 203.0.113.1/32 next-hop 10.217.37.254 check policy all-available -``` - -```{eval-rst} -.. cfgcmd:: set protocols failover route next-hop
interface - - **Configure the local interface used to reach the next-hop address.** - - This parameter is mandatory. - - Example: - - .. code-block:: none - - set protocols failover route 203.0.113.1/32 next-hop 10.217.37.254 interface eth0 -``` - -```{eval-rst} -.. cfgcmd:: set protocols failover route next-hop
metric <1-255> - - **Configure the metric (cost) for the failover route.** - - The metric defines the route priority. A lower metric value indicates a - more preferred route. - - The default value is 1. - - Example: - - .. code-block:: none - - set protocols failover route 203.0.113.1/32 next-hop 10.217.37.254 metric 50 -``` - -```{eval-rst} -.. cfgcmd:: set protocols failover route next-hop
onlink - - Configure the next-hop to be reachable via the assigned interface, even - when ``
`` is outside any subnet configured on that interface. - - Example: - - .. code-block:: none - - set protocols failover route 203.0.113.1/32 next-hop 10.217.37.254 onlink -``` - -## Examples - -### Failover route with a single next-hop and ICMP health check - -The following example configures a failover route to `203.0.113.1/32` -through next-hop `192.0.2.1` on `eth0`. The next-hop is monitored with -ICMP probes to `192.0.2.1` every 5 seconds, and the route is installed with -a metric of 10. - -```none -set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 check target '192.0.2.1' -set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 check timeout '5' -set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 check type 'icmp' -set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 interface 'eth0' -set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 metric '10' -``` - -Verify the route: - -```none -vyos@vyos:~$ show ip route 203.0.113.1 -Routing entry for 203.0.113.1/32 - Known via "kernel", distance 0, metric 10, best - Last update 00:00:39 ago - Flags: Selected - Status: Installed - * 192.0.2.1, via eth0, weight 1 -``` - -### Two failover routes with different metrics - -The following example configures two failover routes to `203.0.113.1/32`, -each through a different next-hop. The primary next-hop `192.0.2.1` is -reached on `eth0` with metric 10, and the backup next-hop `198.51.100.1` -is reached on `eth2` with metric 20. Both next-hops are monitored with ICMP -probes every 5 seconds. - -While both health checks succeed, the lower-metric route through `eth0` is -preferred. If the primary target stops responding, its route is removed from -the routing table, and traffic falls over to `198.51.100.1` via `eth2`. - -```none -set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 check target '192.0.2.1' -set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 check timeout '5' -set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 check type 'icmp' -set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 interface 'eth0' -set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 metric '10' - -set protocols failover route 203.0.113.1/32 next-hop 198.51.100.1 check target '198.51.100.99' -set protocols failover route 203.0.113.1/32 next-hop 198.51.100.1 check timeout '5' -set protocols failover route 203.0.113.1/32 next-hop 198.51.100.1 check type 'icmp' -set protocols failover route 203.0.113.1/32 next-hop 198.51.100.1 interface 'eth2' -set protocols failover route 203.0.113.1/32 next-hop 198.51.100.1 metric '20' -``` - -Verify routes: - -```none -vyos@vyos:~$ show ip route 203.0.113.1 -Routing entry for 203.0.113.1/32 - Known via "kernel", distance 0, metric 10, best - Last update 00:08:06 ago - Flags: Selected - Status: Installed - * 192.0.2.1, via eth0, weight 1 - -Routing entry for 203.0.113.1/32 - Known via "kernel", distance 0, metric 20 - Last update 00:08:14 ago - Flags: None - Status: Installed - * 198.51.100.1, via eth2, weight 1 -``` - diff --git a/docs/configuration/protocols/md-igmp-proxy.md b/docs/configuration/protocols/md-igmp-proxy.md deleted file mode 100644 index 961f921b..00000000 --- a/docs/configuration/protocols/md-igmp-proxy.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -lastproofread: '2023-11-13' ---- - -(igmp-proxy)= - -# IGMP Proxy - -{abbr}`IGMP (Internet Group Management Protocol)` proxy sends IGMP host messages -on behalf of a connected client. The configuration must define one, and only one -upstream interface, and one or more downstream interfaces. - -## Configuration - -```{cfgcmd} set protocols igmp-proxy interface \ role \ - -* **upstream:** The upstream network interface is the outgoing interface -which is responsible for communicating to available multicast data sources. -There can only be one upstream interface. - -* **downstream:** Downstream network interfaces are the distribution -interfaces to the destination networks, where multicast clients can join -groups and receive multicast data. One or more downstream interfaces must -be configured. -``` - -```{cfgcmd} set protocols igmp-proxy interface \ alt-subnet \ - -Defines alternate sources for multicasting and IGMP data. The network address -must be on the following format 'a.b.c.d/n'. By default, the router will -accept data from sources on the same network as configured on an interface. -If the multicast source lies on a remote network, one must define from where -traffic should be accepted. - -This is especially useful for the upstream interface, since the source for -multicast traffic is often from a remote location. - -This option can be supplied multiple times. -``` - -```{cfgcmd} set protocols igmp-proxy disable-quickleave - -Disables quickleave mode. In this mode the daemon will not send a Leave IGMP -message upstream as soon as it receives a Leave message for any downstream -interface. The daemon will not ask for Membership reports on the downstream -interfaces, and if a report is received the group is not joined again the -upstream. - -If it's vital that the daemon should act exactly like a real multicast client -on the upstream interface, this function should be enabled. - -Enabling this function increases the risk of bandwidth saturation. -``` - -```{cfgcmd} set protocols igmp-proxy disable - -Disable this service. -``` - -(igmp-proxy-example)= - -### Example - -Interface eth1 LAN is behind NAT. In order to subscribe 10.0.0.0/23 subnet -multicast which is in eth0 WAN we need to configure igmp-proxy. - -```none -set protocols igmp-proxy interface eth0 role upstream -set protocols igmp-proxy interface eth0 alt-subnet 10.0.0.0/23 -set protocols igmp-proxy interface eth1 role downstream -``` - - -## Operation - -```{opcmd} restart igmp-proxy - -Restart the IGMP proxy process. -``` \ No newline at end of file diff --git a/docs/configuration/protocols/md-index.md b/docs/configuration/protocols/md-index.md deleted file mode 100644 index 5f190ce1..00000000 --- a/docs/configuration/protocols/md-index.md +++ /dev/null @@ -1,25 +0,0 @@ -# Protocols - -```{toctree} -:includehidden: true -:maxdepth: 1 - -arp -babel -bfd -bgp -failover -igmp-proxy -isis -mpls -multicast -segment-routing -traffic-engineering -openfabric -ospf -pim -pim6 -rip -rpki -static -``` diff --git a/docs/configuration/protocols/md-isis.md b/docs/configuration/protocols/md-isis.md deleted file mode 100644 index ac6db346..00000000 --- a/docs/configuration/protocols/md-isis.md +++ /dev/null @@ -1,746 +0,0 @@ -```{include} /_include/need_improvement.txt -``` - -(routing-isis)= - -# IS-IS - -{abbr}`IS-IS (Intermediate System to Intermediate System)` is a link-state -interior gateway protocol (IGP) which is described in ISO10589, -{rfc}`1195`, {rfc}`5308`. IS-IS runs the Dijkstra shortest-path first (SPF) -algorithm to create a database of the network’s topology, and -from that database to determine the best (that is, lowest cost) path to a -destination. The intermediate systems (the name for routers) exchange topology -information with their directly connected neighbors. IS-IS runs directly on -the data link layer (Layer 2). IS-IS addresses are called -{abbr}`NETs (Network Entity Titles)` and can be 8 to 20 bytes long, but are -generally 10 bytes long. The tree database that is created with IS-IS is -similar to the one that is created with OSPF in that the paths chosen should -be similar. Comparisons to OSPF are inevitable and often are reasonable ones -to make in regards to the way a network will respond with either IGP. - -## General - -### Configuration - -#### Mandatory Settings - -For IS-IS top operate correctly, one must do the equivalent of a Router ID in -CLNS. This Router ID is called the {abbr}`NET (Network Entity Title)`. This -must be unique for each and every router that is operating in IS-IS. It also -must not be duplicated otherwise the same issues that occur within OSPF will -occur within IS-IS when it comes to said duplication. - -```{cfgcmd} set protocols isis net \ - -This command sets network entity title (NET) provided in ISO format. - -Here is an example {abbr}`NET (Network Entity Title)` value: - -:::{code-block} none -49.0001.1921.6800.1002.00 -::: -The CLNS address consists of the following parts: - -* {abbr}`AFI (Address family authority identifier)` - ``49`` The AFI value - 49 is what IS-IS uses for private addressing. - -* Area identifier: ``0001`` IS-IS area number (numerical area ``1``) - -* System identifier: ``1921.6800.1002`` - for system identifiers we recommend - to use IP address or MAC address of the router itself. The way to construct - this is to keep all of the zeroes of the router IP address, and then change - the periods from being every three numbers to every four numbers. The - address that is listed here is ``192.168.1.2``, which if expanded will turn - into ``192.168.001.002``. Then all one has to do is move the dots to have - four numbers instead of three. This gives us ``1921.6800.1002``. - -* {abbr}`NET (Network Entity Title)` selector: ``00`` Must always be 00. This - setting indicates "this system" or "local system." - -``` - -```{cfgcmd} set protocols isis interface \ - -This command enables IS-IS on this interface, and allows for -adjacency to occur. Note that the name of IS-IS instance must be -the same as the one used to configure the IS-IS process. -``` - -#### IS-IS Global Configuration - -```{cfgcmd} set protocols isis dynamic-hostname - -This command enables support for dynamic hostname TLV. Dynamic hostname -mapping determined as described in {rfc}`2763`, Dynamic Hostname -Exchange Mechanism for IS-IS. -``` - -```{cfgcmd} set protocols isis level \ - -This command defines the IS-IS router behavior: - -* **level-1** - Act as a station (Level 1) router only. -* **level-1-2** - Act as a station (Level 1) router and area (Level 2) router. -* **level-2-only** - Act as an area (Level 2) router only. -``` - -```{cfgcmd} set protocols isis lsp-mtu \ - -This command configures the maximum size of generated -{abbr}`LSPs (Link State PDUs)`, in bytes. The size range is 128 to 4352. -``` - -```{cfgcmd} set protocols isis metric-style \ - -This command sets old-style (ISO 10589) or new style packet formats: - -* **narrow** - Use old style of TLVs with narrow metric. -* **transition** - Send and accept both styles of TLVs during transition. -* **wide** - Use new style of TLVs to carry wider metric. -``` - -```{cfgcmd} set protocols isis purge-originator - -This command enables {rfc}`6232` purge originator identification. Enable -purge originator identification (POI) by adding the type, length and value -(TLV) with the Intermediate System (IS) identification to the LSPs that do -not contain POI information. If an IS generates a purge, VyOS adds this TLV -with the system ID of the IS to the purge. -``` - -```{cfgcmd} set protocols isis set-attached-bit - -This command sets ATT bit to 1 in Level1 LSPs. It is described in {rfc}`3787`. -``` - -```{cfgcmd} set protocols isis set-overload-bit - -This command sets overload bit to avoid any transit traffic through this -router. It is described in {rfc}`3787`. -``` - -```{cfgcmd} set protocols isis default-information originate \ level-1 - -This command will generate a default-route in L1 database. -``` - -```{cfgcmd} set protocols isis default-information originate \ level-2 - -This command will generate a default-route in L2 database. -``` - -```{cfgcmd} set protocols isis ldp-sync - -This command will enable IGP-LDP synchronization globally for ISIS. This -requires for LDP to be functional. This is described in {rfc}`5443`. By -default all interfaces operational in IS-IS are enabled for synchronization. -Loopbacks are exempt. - -``` - -```{cfgcmd} set protocols isis ldp-sync holddown \ - -This command will change the hold down value globally for IGP-LDP -synchronization during convergence/interface flap events. -``` - -#### Interface Configuration - -```{cfgcmd} set protocols isis interface \ circuit-type \ - -This command specifies circuit type for interface: - -* **level-1** - Level-1 only adjacencies are formed. -* **level-1-2** - Level-1-2 adjacencies are formed -* **level-2-only** - Level-2 only adjacencies are formed - -``` - -```{cfgcmd} set protocols isis interface \ hello-interval \ - -This command sets hello interval in seconds on a given interface. -The range is 1 to 600. -``` - -```{cfgcmd} set protocols isis interface \ hello-multiplier \ - -This command sets multiplier for hello holding time on a given -interface. The range is 2 to 100. -``` - -```{cfgcmd} set protocols isis interface \ hello-padding - -This command configures padding on hello packets to accommodate asymmetrical -maximum transfer units (MTUs) from different hosts as described in -{rfc}`3719`. This helps to prevent a premature adjacency Up state when one -routing devices MTU does not meet the requirements to establish the adjacency. -``` - -```{cfgcmd} set protocols isis interface \ metric \ - -This command set default metric for circuit. - -The metric range is 1 to 16777215 (Max value depend if metric support narrow -or wide value). -``` - -```{cfgcmd} set protocols isis interface \ network point-to-point - -This command specifies network type to Point-to-Point. The default -network type is broadcast. -``` - -```{cfgcmd} set protocols isis interface \ passive - -This command configures the passive mode for this interface. -``` - -```{cfgcmd} set protocols isis interface \ password plaintext-password \ - -This command configures the authentication password for the interface. -``` - -```{cfgcmd} set protocols isis interface \ priority \ - -This command sets priority for the interface for -{abbr}`DIS (Designated Intermediate System)` election. The priority -range is 0 to 127. -``` - -```{cfgcmd} set protocols isis interface \ psnp-interval \ - -This command sets PSNP interval in seconds. The interval range is 0 -to 127. -``` - -```{cfgcmd} set protocols isis interface \ no-three-way-handshake - -This command disables Three-Way Handshake for P2P adjacencies which -described in {rfc}`5303`. Three-Way Handshake is enabled by default. -``` - -```{cfgcmd} set protocols isis interface \ ldp-sync disable - -This command disables IGP-LDP sync for this specific interface. -``` - -```{cfgcmd} set protocols isis interface \ ldp-sync holddown \ - -This command will change the hold down value for IGP-LDP synchronization -during convergence/interface flap events, but for this interface only. -``` - -```{cfgcmd} set protocols isis interface \ fast-reroute lfa [level-1 | level-2] enable - -This command enables per-prefix local LFA fast reroute link protection. -``` - -```{cfgcmd} set protocols isis interface \ fast-reroute lfa [level-1 | level-2] exclude - -This command excludes an interface from the local LFA backup nexthop computation. -``` - -```{cfgcmd} set protocols isis interface \ fast-reroute remote-lfa [level-1 | level-2] tunnel mpls-ldp - -This command enables per-prefix Remote LFA fast reroute link protection. -Note that other routers in the network need to be configured to accept LDP -targeted hello messages in order for RLFA to work. -``` - -```{cfgcmd} set protocols isis interface \ fast-reroute remote-lfa [level-1 | level-2] maximum-metric \ - -This command limits Remote LFA PQ node selection within the specified metric. Metric value range (1-16777215). -``` - -```{cfgcmd} set protocols isis interface \ fast-reroute ti-lfa [level-1|level-2] [node-protection [link-fallback]] - -This command enables per-prefix TI-LFA fast reroute link or node protection. -When node protection is used, option link-fallback enables the computation -and use of link-protecting LFAs for destinations unprotected by node -protection. -``` - -#### Route Redistribution - -```{cfgcmd} set protocols isis redistribute ipv4 \ level-1 - -This command redistributes routing information from the given route source -into the ISIS database as Level-1. There are six modes available for route -source: bgp, connected, kernel, ospf, rip, static. -``` - -```{cfgcmd} set protocols isis redistribute ipv4 \ level-2 - -This command redistributes routing information from the given route source -into the ISIS database as Level-2. There are six modes available for route -source: bgp, connected, kernel, ospf, rip, static. -``` - -```{cfgcmd} set protocols isis redistribute ipv4 \ \ metric \ - -This command specifies metric for redistributed routes from the given route -source. There are six modes available for route source: bgp, connected, -kernel, ospf, rip, static. The metric range is 1 to 16777215. -``` - -```{cfgcmd} set protocols isis redistribute ipv4 \ \ route-map \ - -This command allows to use route map to filter redistributed routes from -the given route source. There are six modes available for route source: -bgp, connected, kernel, ospf, rip, static. -``` - -#### Timers - -```{cfgcmd} set protocols isis lsp-gen-interval \ - -This command sets minimum interval in seconds between regenerating same -LSP. The interval range is 1 to 120. -``` - -```{cfgcmd} set protocols isis lsp-refresh-interval \ - -This command sets LSP refresh interval in seconds. IS-IS generates LSPs -when the state of a link changes. However, to ensure that routing -databases on all routers remain converged, LSPs in stable networks are -generated on a regular basis even though there has been no change to -the state of the links. The interval range is 1 to 65235. The default -value is 900 seconds. -``` - -```{cfgcmd} set protocols isis max-lsp-lifetime \ - -This command sets LSP maximum LSP lifetime in seconds. The interval range -is 350 to 65535. LSPs remain in a database for 1200 seconds by default. -If they are not refreshed by that time, they are deleted. You can change -the LSP refresh interval or the LSP lifetime. The LSP refresh interval -should be less than the LSP lifetime or else LSPs will time out before -they are refreshed. -``` - -```{cfgcmd} set protocols isis spf-interval \ - -This command sets minimum interval between consecutive SPF calculations in -seconds.The interval range is 1 to 120. -``` - -```{cfgcmd} set protocols isis spf-delay-ietf holddown \ -``` - -```{cfgcmd} set protocols isis spf-delay-ietf init-delay \ -``` - -```{cfgcmd} set protocols isis spf-delay-ietf long-delay \ -``` - -```{cfgcmd} set protocols isis spf-delay-ietf short-delay \ -``` - -```{cfgcmd} set protocols isis spf-delay-ietf time-to-learn \ - -This commands specifies the Finite State Machine (FSM) intended to -control the timing of the execution of SPF calculations in response -to IGP events. The process described in {rfc}`8405`. -``` - -#### Loop Free Alternate (LFA) - -```{cfgcmd} set protocols isis fast-reroute lfa remote prefix-list \ \ - -This command enables IP fast re-routing that is part of {rfc}`5286`. -Specifically this is a prefix list which references a prefix in which -will select eligible PQ nodes for remote LFA backups. -``` - -```{cfgcmd} set protocols isis fast-reroute lfa local load-sharing disable \ - -This command disables the load sharing across multiple LFA backups. -``` - -```{cfgcmd} set protocols isis fast-reroute lfa local tiebreaker \ index \ \ - -This command will configure a tie-breaker for multiple local LFA backups. -The lower index numbers will be processed first. -``` - -```{cfgcmd} set protocols isis fast-reroute lfa local priority-limit \ \ - -This command will limit LFA backup computation up to the specified -prefix priority. -``` - -#### Segment Routing over IPv6 (SRv6) - -```{cfgcmd} set protocols isis segment-routing srv6 interface \ - -The dummy interface used -to install SRv6 SIDs into the Linux data plane. The interface must exist and -must be present when configuring IS-IS with -SRv6. -``` - -```{cfgcmd} set protocols isis segment-routing srv6 locator \ - -Specifies the SRv6 locator to use for IS-IS. IS-IS automatically allocates -prefix and adjacency SIDs, creates local SID entries and advertises them -into the IGP domain. -``` - -```{cfgcmd} set protocols isis segment-routing srv6 node-msd max-end-d \<0-255\> - -The Maximum End D MSD Type specifies the maximum number of SIDs present in an -SRH when performing decapsulation. As specified in {rfc}`8986`, the permitted -SID types include, but are not limited to, End.DX6, End.DT4, End.DT46, End -with USD, and End.X with USD. - -If the advertised value is zero or no value is advertised, then the router -cannot apply any behavior that results in decapsulation and forwarding of the -inner packet if the outer IPv6 header contains an SRH. - -Reference: {rfc}`9352` -``` - -```{cfgcmd} set protocols isis segment-routing srv6 node-msd max-end-pop \<0-255\> - -The Maximum End Pop MSD Type signals the maximum number of SIDs in the SRH to -which the router can apply "Penultimate Segment Pop (PSP) of the SRH" or -"Ultimate Segment Pop (USP) of the SRH" behavior, as defined in "Flavors" -(Section 4.16 of {rfc}`8986`). - -If the advertised value is zero or no value is advertised, then the router -cannot apply PSP or USP flavors. - -Reference: {rfc}`9352` -``` - -```{cfgcmd} set protocols isis segment-routing srv6 node-msd max-h-encaps \<0-255\> - -The Maximum H.Encaps MSD Type signals the maximum number of SIDs that can be -added to the segment list of an SRH as part of the "H.Encaps" behavior, as -defined in {rfc}`8986`. - -If the advertised value is zero or no value is advertised, then the headend -can apply an SR Policy that only contains one segment without inserting any -SRH header. A non-zero SRH Max H.encaps MSD indicates that the headend can -insert an SRH up to the advertised number of SIDs. - -Reference: {rfc}`9352` -``` - -```{cfgcmd} set protocols isis segment-routing srv6 node-msd max-segs-left \<0-255\> - -The Maximum Segments Left MSD Type signals the maximum value of the -"Segments Left" field ({rfc}`8754`) in the SRH of a received packet before -applying the Endpoint behavior associated with a SID. - -If no value is advertised, the supported value is 0. - -Reference: {rfc}`9352` -``` - -## Examples - -### Enable IS-IS - -**Node 1:** - -```none -set interfaces loopback lo address '192.168.255.255/32' -set interfaces ethernet eth1 address '192.0.2.1/24' - -set protocols isis interface eth1 -set protocols isis interface lo -set protocols isis net '49.0001.1921.6825.5255.00' -``` - -**Node 2:** - -```none -set interfaces ethernet eth1 address '192.0.2.2/24' - -set interfaces loopback lo address '192.168.255.254/32' -set interfaces ethernet eth1 address '192.0.2.2/24' - -set protocols isis interface eth1 -set protocols isis interface lo -set protocols isis net '49.0001.1921.6825.5254.00' -``` - -This gives us the following neighborships, Level 1 and Level 2: - -```none -Node-1@vyos:~$ show isis neighbor -Area VyOS: - System Id Interface L State Holdtime SNPA - vyos eth1 1 Up 28 0c87.6c09.0001 - vyos eth1 2 Up 28 0c87.6c09.0001 - -Node-2@vyos:~$ show isis neighbor -Area VyOS: - System Id Interface L State Holdtime SNPA - vyos eth1 1 Up 29 0c33.0280.0001 - vyos eth1 2 Up 28 0c33.0280.0001 -``` - -Here's the IP routes that are populated. Just the loopback: - -```none -Node-1@vyos:~$ show ip route isis -Codes: K - kernel route, C - connected, S - static, R - RIP, - O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, - T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, - f - OpenFabric, - > - selected route, * - FIB route, q - queued, r - rejected, b - backup - t - trapped, o - offload failure - -I 192.0.2.0/24 [115/20] via 192.0.2.2, eth1 inactive, weight 1, 00:02:22 -I>* 192.168.255.254/32 [115/20] via 192.0.2.2, eth1, weight 1, 00:02:22 - -Node-2@vyos:~$ show ip route isis -Codes: K - kernel route, C - connected, S - static, R - RIP, - O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, - T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, - f - OpenFabric, - > - selected route, * - FIB route, q - queued, r - rejected, b - backup - t - trapped, o - offload failure - -I 192.0.2.0/24 [115/20] via 192.0.2.1, eth1 inactive, weight 1, 00:02:21 -I>* 192.168.255.255/32 [115/20] via 192.0.2.1, eth1, weight 1, 00:02:21 -``` - -### Enable IS-IS and redistribute routes not natively in IS-IS - -**Node 1:** - -```none -set interfaces dummy dum0 address '203.0.113.1/24' -set interfaces ethernet eth1 address '192.0.2.1/24' - -set policy prefix-list EXPORT-ISIS rule 10 action 'permit' -set policy prefix-list EXPORT-ISIS rule 10 prefix '203.0.113.0/24' -set policy route-map EXPORT-ISIS rule 10 action 'permit' -set policy route-map EXPORT-ISIS rule 10 match ip address prefix-list 'EXPORT-ISIS' - -set protocols isis interface eth1 -set protocols isis net '49.0001.1921.6800.1002.00' -set protocols isis redistribute ipv4 connected level-2 route-map 'EXPORT-ISIS' -``` - -**Node 2:** - -```none -set interfaces ethernet eth1 address '192.0.2.2/24' - -set protocols isis interface eth1 -set protocols isis net '49.0001.1921.6800.2002.00' -``` - -Routes on Node 2: - -```none -Node-2@r2:~$ show ip route isis -Codes: K - kernel route, C - connected, S - static, R - RIP, - O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, - T - Table, v - VNC, V - VNC-Direct, A - Babel, D - SHARP, - F - PBR, f - OpenFabric, - > - selected route, * - FIB route, q - queued route, r - rejected route - -I 203.0.113.0/24 [115/10] via 192.0.2.1, eth1, 00:03:42 -``` - -### Enable IS-IS and IGP-LDP synchronization - -**Node 1:** - -```none -set interfaces loopback lo address 192.168.255.255/32 -set interfaces ethernet eth0 address 192.0.2.1/24 - -set protocols isis interface eth0 -set protocols isis interface lo passive -set protocols isis ldp-sync -set protocols isis net 49.0001.1921.6825.5255.00 - -set protocols mpls interface eth0 -set protocols mpls ldp discovery transport-ipv4-address 192.168.255.255 -set protocols mpls ldp interface lo -set protocols mpls ldp interface eth0 -set protocols mpls ldp parameters transport-prefer-ipv4 -set protocols mpls ldp router-id 192.168.255.255 -``` - -This gives us IGP-LDP synchronization for all non-loopback interfaces with -a holddown timer of zero seconds: - -```none -Node-1@vyos:~$ show isis mpls ldp-sync -eth0 - LDP-IGP Synchronization enabled: yes - holddown timer in seconds: 0 - State: Sync achieved -``` - -### Enable IS-IS with Segment Routing (Experimental) - -**Node 1:** - -```none -set interfaces loopback lo address '192.168.255.255/32' -set interfaces ethernet eth1 address '192.0.2.1/24' - -set protocols isis interface eth1 -set protocols isis interface lo -set protocols isis net '49.0001.1921.6825.5255.00' -set protocols isis segment-routing global-block high-label-value '599' -set protocols isis segment-routing global-block low-label-value '550' -set protocols isis segment-routing prefix 192.168.255.255/32 index value '1' -set protocols isis segment-routing prefix 192.168.255.255/32 index explicit-null -set protocols mpls interface 'eth1' -``` - -**Node 2:** - -```none -set interfaces loopback lo address '192.168.255.254/32' -set interfaces ethernet eth1 address '192.0.2.2/24' - -set protocols isis interface eth1 -set protocols isis interface lo -set protocols isis net '49.0001.1921.6825.5254.00' -set protocols isis segment-routing global-block high-label-value '599' -set protocols isis segment-routing global-block low-label-value '550' -set protocols isis segment-routing prefix 192.168.255.254/32 index value '2' -set protocols isis segment-routing prefix 192.168.255.254/32 index explicit-null -set protocols mpls interface 'eth1' -``` - -This gives us MPLS segment routing enabled and labels for far end loopbacks: - -```none -Node-1@vyos:~$ show mpls table - Inbound Label Type Nexthop Outbound Label - ---------------------------------------------------------------------- - 552 SR (IS-IS) 192.0.2.2 IPv4 Explicit Null <-- Node-2 loopback learned on Node-1 - 15000 SR (IS-IS) 192.0.2.2 implicit-null - 15001 SR (IS-IS) fe80::e87:6cff:fe09:1 implicit-null - 15002 SR (IS-IS) 192.0.2.2 implicit-null - 15003 SR (IS-IS) fe80::e87:6cff:fe09:1 implicit-null - -Node-2@vyos:~$ show mpls table - Inbound Label Type Nexthop Outbound Label - --------------------------------------------------------------------- - 551 SR (IS-IS) 192.0.2.1 IPv4 Explicit Null <-- Node-1 loopback learned on Node-2 - 15000 SR (IS-IS) 192.0.2.1 implicit-null - 15001 SR (IS-IS) fe80::e33:2ff:fe80:1 implicit-null - 15002 SR (IS-IS) 192.0.2.1 implicit-null - 15003 SR (IS-IS) fe80::e33:2ff:fe80:1 implicit-null -``` - -Here is the routing tables showing the MPLS segment routing label operations: - -```none -Node-1@vyos:~$ show ip route isis -Codes: K - kernel route, C - connected, S - static, R - RIP, - O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, - T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, - f - OpenFabric, - > - selected route, * - FIB route, q - queued, r - rejected, b - backup - t - trapped, o - offload failure - -I 192.0.2.0/24 [115/20] via 192.0.2.2, eth1 inactive, weight 1, 00:07:48 -I>* 192.168.255.254/32 [115/20] via 192.0.2.2, eth1, label IPv4 Explicit Null, weight 1, 00:03:39 - -Node-2@vyos:~$ show ip route isis -Codes: K - kernel route, C - connected, S - static, R - RIP, - O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, - T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, - f - OpenFabric, - > - selected route, * - FIB route, q - queued, r - rejected, b - backup - t - trapped, o - offload failure - -I 192.0.2.0/24 [115/20] via 192.0.2.1, eth1 inactive, weight 1, 00:07:46 -I>* 192.168.255.255/32 [115/20] via 192.0.2.1, eth1, label IPv4 Explicit Null, weight 1, 00:03:43 -``` - -### Enable IS-IS with Segment Routing over IPv6 (Experimental) - -**Node 1:** - -```none -set interfaces dummy dum6 description "SRv6 IS-IS" -set interfaces ethernet eth1 address '192.0.2.1/24' -set interfaces loopback lo address '192.168.255.255/32' - -set protocols segment-routing srv6 locator MAIN prefix 2001:db8:1::/64 -set protocols segment-routing interface eth1 - -set protocols isis interface eth1 -set protocols isis interface lo -set protocols isis net '49.0001.1921.6825.5255.00' -set protocols isis segment-routing srv6 locator MAIN -set protocols isis segment-routing srv6 interface dum6 -``` - -**Node 2:** - -```none -set interfaces dummy dum6 description "SRv6 IS-IS" -set interfaces ethernet eth1 address '192.0.2.2/24' -set interfaces loopback lo address '192.168.255.254/32' - -set protocols segment-routing srv6 locator MAIN prefix 2001:db8:2::/64 -set protocols segment-routing interface eth1 - -set protocols isis interface eth1 -set protocols isis interface lo -set protocols isis net '49.0001.1921.6825.5254.00' -set protocols isis segment-routing srv6 locator MAIN -set protocols isis segment-routing srv6 interface dum6 -``` - -### Enable IS-IS with Segment Routing over IPv6 (uSID) (Experimental) - -**Node 1:** - -```none -set interfaces dummy dum6 description "SRv6 IS-IS" -set interfaces ethernet eth1 address '192.0.2.1/24' -set interfaces loopback lo address '192.168.255.255/32' - -set protocols segment-routing interface eth1 -set protocols segment-routing srv6 locator MAIN prefix 2001:db8:1::/48 -set protocols segment-routing srv6 locator MAIN behavior-usid -set protocols segment-routing srv6 locator MAIN block-len 32 -set protocols segment-routing srv6 locator MAIN format usid-f3216 -set protocols segment-routing srv6 locator MAIN func-bits 16 -set protocols segment-routing srv6 locator MAIN node-len 16 - -set protocols isis interface eth1 -set protocols isis interface lo -set protocols isis net '49.0001.1921.6825.5255.00' -set protocols isis segment-routing srv6 interface dum6 -set protocols isis segment-routing srv6 locator MAIN -``` - -**Node 2:** - -```none -set interfaces dummy dum6 description "SRv6 IS-IS" -set interfaces ethernet eth1 address '192.0.2.2/24' -set interfaces loopback lo address '192.168.255.254/32' - -set protocols segment-routing interface eth1 -set protocols segment-routing srv6 locator MAIN prefix 2001:db8:2::/48 -set protocols segment-routing srv6 locator MAIN behavior-usid -set protocols segment-routing srv6 locator MAIN block-len 32 -set protocols segment-routing srv6 locator MAIN format usid-f3216 -set protocols segment-routing srv6 locator MAIN func-bits 16 -set protocols segment-routing srv6 locator MAIN node-len 16 - -set protocols isis interface eth1 -set protocols isis interface lo -set protocols isis net '49.0001.1921.6825.5254.00' -set protocols isis segment-routing srv6 interface dum6 -set protocols isis segment-routing srv6 locator MAIN -``` diff --git a/docs/configuration/protocols/md-mpls.md b/docs/configuration/protocols/md-mpls.md deleted file mode 100644 index 71b14be2..00000000 --- a/docs/configuration/protocols/md-mpls.md +++ /dev/null @@ -1,285 +0,0 @@ -(mpls)= - -# MPLS - -{abbr}`MPLS (Multi-Protocol Label Switching)` is a packet forwarding paradigm -which differs from regular IP forwarding. Instead of IP addresses being used to -make the decision on finding the exit interface, a router will instead use an -exact match on a 32 bit/4 byte header called the MPLS label. This label is -inserted between the ethernet (layer 2) header and the IP (layer 3) header. -One can statically or dynamically assign label allocations, but we will focus -on dynamic allocation of labels using some sort of label distribution protocol -(such as the aptly named Label Distribution Protocol / LDP, Resource Reservation -Protocol / RSVP, or Segment Routing through OSPF/ISIS). These protocols allow -for the creation of a unidirectional/unicast path called a labeled switched -path (initialized as LSP) throughout the network that operates very much like -a tunnel through the network. An easy way of thinking about how an MPLS LSP -actually forwards traffic throughout a network is to think of a GRE tunnel. -They are not the same in how they operate, but they are the same in how they -handle the tunneled packet. It would be good to think of MPLS as a tunneling -technology that can be used to transport many different types of packets, to -aid in traffic engineering by allowing one to specify paths throughout the -network (using RSVP or SR), and to generally allow for easier intra/inter -network transport of data packets. - -For more information on how MPLS label switching works, please go visit -[Wikipedia (MPLS)]. - -:::{note} -MPLS support in VyOS is not finished yet, and therefore its -functionality is limited. Currently there is no support for MPLS enabled VPN -services such as L2VPNs and mVPNs. RSVP support is also not present as the -underlying routing stack (FRR) does not implement it. Currently VyOS -implements LDP as described in RFC 5036; other LDP standard are the -following ones: RFC 6720, RFC 6667, RFC 5919, RFC 5561, RFC 7552, RFC 4447. -Because MPLS is already available (FRR also supports RFC 3031). -::: - -## Label Distribution Protocol - -The {abbr}`MPLS (Multi-Protocol Label Switching)` architecture does not assume -a single protocol to create MPLS paths. VyOS supports the Label Distribution -Protocol (LDP) as implemented by FRR, based on {rfc}`5036`. - -{abbr}`LDP (Label Distribution Protocol)` is a TCP based MPLS signaling protocol -that distributes labels creating MPLS label switched paths in a dynamic manner. -LDP is not a routing protocol, as it relies on other routing protocols for -forwarding decisions. LDP cannot bootstrap itself, and therefore relies on said -routing protocols for communication with other routers that use LDP. - -In order to allow for LDP on the local router to exchange label advertisements -with other routers, a TCP session will be established between automatically -discovered and statically assigned routers. LDP will try to establish a TCP -session to the **transport address** of other routers. Therefore for LDP to -function properly please make sure the transport address is shown in the -routing table and reachable to traffic at all times. - -It is highly recommended to use the same address for both the LDP router-id and -the discovery transport address, but for VyOS MPLS LDP to work both parameters -must be explicitly set in the configuration. - -Another thing to keep in mind with LDP is that much like BGP, it is a protocol -that runs on top of TCP. It however does not have an ability to do something -like a refresh capability like BGPs route refresh capability. Therefore one -might have to reset the neighbor for a capability change or a configuration -change to work. - -## Configuration Options - -```{cfgcmd} set protocols mpls interface \ - -Use this command to enable MPLS processing on the interface you define. -``` - - -```{cfgcmd} set protocols mpls ldp interface \ - -Use this command to enable LDP on the interface you define. -``` - - -```{cfgcmd} set protocols mpls ldp router-id \ - -Use this command to configure the IP address used as the LDP router-id of the -local device. -``` - - -```{cfgcmd} set protocols mpls ldp discovery transport-ipv4-address \ - -``` -```{cfgcmd} set protocols mpls ldp discovery transport-ipv6-address \ - -Use this command to set the IPv4 or IPv6 transport-address used by LDP. -``` - -```{cfgcmd} set protocols mpls ldp neighbor \ password \ - -Use this command to configure authentication for LDP peers. Set the -IP address of the LDP peer and a password that should be shared in -order to become neighbors. -``` - -```{cfgcmd} set protocols mpls ldp neighbor \ session-holdtime \ - -Use this command to configure a specific session hold time for LDP peers. -Set the IP address of the LDP peer and a session hold time that should be -configured for it. You may have to reset the neighbor for this to work. -``` - -```{cfgcmd} set protocols mpls ldp neighbor \ ttl-security \ - -Use this command to enable, disable, or specify hop count for TTL security -for LDP peers. By default the value is set to 255 (or max TTL). -``` - -```{eval-rst} -.. cfgcmd:: set protocols mpls ldp discovery hello-ipv4-interval -.. cfgcmd:: set protocols mpls ldp discovery hello-ipv4-holdtime -.. cfgcmd:: set protocols mpls ldp discovery hello-ipv6-interval -.. cfgcmd:: set protocols mpls ldp discovery hello-ipv6-holdtime - - Use these commands if you would like to set the discovery hello and hold time - parameters. -``` - -```{eval-rst} -.. cfgcmd:: set protocols mpls ldp discovery session-ipv4-holdtime -.. cfgcmd:: set protocols mpls ldp discovery session-ipv6-holdtime - - Use this command if you would like to set the TCP session hold time intervals. -``` - -```{eval-rst} -.. cfgcmd:: set protocols mpls ldp import ipv4 import-filter filter-access-list - -.. cfgcmd:: set protocols mpls ldp import ipv6 import-filter filter-access-list6 - - - Use these commands to control the importing of forwarding equivalence classes - (FECs) for LDP from neighbors. This would be useful for example on only - accepting the labeled routes that are needed and not ones that are not - needed, such as accepting loopback interfaces and rejecting all others. -``` - -```{eval-rst} -.. cfgcmd:: set protocols mpls ldp export ipv4 export-filter filter-access-list - -.. cfgcmd:: set protocols mpls ldp export ipv6 export-filter filter-access-list6 - - - Use these commands to control the exporting of forwarding equivalence classes - (FECs) for LDP to neighbors. This would be useful for example on only - announcing the labeled routes that are needed and not ones that are not - needed, such as announcing loopback interfaces and no others. -``` - -```{eval-rst} -.. cfgcmd:: set protocols mpls ldp export ipv4 explicit-null -.. cfgcmd:: set protocols mpls ldp export ipv6 explicit-null - - Use this command if you would like for the router to advertise FECs with a - label of 0 for explicit null operations. -``` - -```{eval-rst} -.. cfgcmd:: set protocols mpls ldp allocation ipv4 access-list -.. cfgcmd:: set protocols mpls ldp allocation ipv6 access-list6 - - Use this command if you would like to control the local FEC allocations for - LDP. A good example would be for your local router to not allocate a label for - everything. Just a label for what it's useful. A good example would be just a - loopback label. -``` - -```{cfgcmd} set protocols mpls ldp parameters cisco-interop-tlv - -Use this command to use a Cisco non-compliant format to send and interpret -the Dual-Stack capability TLV for IPv6 LDP communications. This is related to -{rfc}`7552`. -``` - -```{cfgcmd} set protocols mpls ldp parameters ordered-control - -Use this command to use ordered label distribution control mode. FRR -by default uses independent label distribution control mode for label -distribution. This is related to {rfc}`5036`. -``` - -```{cfgcmd} set protocols mpls ldp parameters transport-prefer-ipv4 - -Use this command to prefer IPv4 for TCP peer transport connection for LDP -when both an IPv4 and IPv6 LDP address are configured on the same interface. -``` - -```{cfgcmd} set protocols mpls ldp targeted-neighbor ipv4 enable -``` - -```{cfgcmd} set protocols mpls ldp targeted-neighbor ipv6 enable - -Use this command to enable targeted LDP sessions to the local router. The -router will then respond to any sessions that are trying to connect to it that -are not a link local type of TCP connection. -``` - -```{cfgcmd} set protocols mpls ldp targeted-neighbor ipv4 address \ -``` - -```{cfgcmd} set protocols mpls ldp targeted-neighbor ipv6 address \ - -Use this command to enable the local router to try and connect with a targeted -LDP session to another router. -``` - -```{cfgcmd} set protocols mpls ldp targeted-neighbor ipv4 hello-holdtime \ -``` - -```{cfgcmd} set protocols mpls ldp targeted-neighbor ipv4 hello-interval \ -``` - -```{cfgcmd} set protocols mpls ldp targeted-neighbor ipv6 hello-holdtime \ -``` - -```{cfgcmd} set protocols mpls ldp targeted-neighbor ipv6 hello-interval \ - -Use these commands if you would like to set the discovery hello and hold time -parameters for the targeted LDP neighbors. -``` - -### Sample configuration to setup LDP on VyOS - -```none -set protocols ospf area 0 network '192.168.255.252/32' <--- Routing for loopback -set protocols ospf area 0 network '192.168.0.5/32' <--- Routing for an interface connecting to the network -set protocols ospf parameters router-id '192.168.255.252' <--- Router ID setting for OSPF -set protocols mpls interface 'eth1' <--- Enable MPLS for an interface connecting to network -set protocols mpls ldp discovery transport-ipv4-address '192.168.255.252' <--- Transport address for LDP for TCP sessions to connect to -set protocols mpls ldp interface 'eth1' <--- Enable LDP for an interface connecting to network -set protocols mpls ldp interface 'lo' <--- Enable LDP on loopback for future services connectivity -set protocols mpls ldp router-id '192.168.255.252' <--- Router ID setting for LDP -set interfaces ethernet eth1 address '192.168.0.5/31' <--- Interface IP for connecting to network -set interfaces loopback lo address '192.168.255.252/32' <--- Interface loopback IP for router ID and other uses -``` - -## Operational Mode Commands - -When LDP is working, you will be able to see label information in the outcome -of `show ip route`. Besides that information, there are also specific *show* -commands for LDP: - -### Show - -```{opcmd} show mpls ldp binding - -Use this command to see the Label Information Base. - -``` - -```{opcmd} show mpls ldp discovery - -Use this command to see discovery hello information -``` - -```{opcmd} show mpls ldp interface - -Use this command to see LDP interface information -``` - -```{opcmd} show mpls ldp neighbor - -Use this command to see LDP neighbor information -``` - -```{opcmd} show mpls ldp neighbor detail - -Use this command to see detailed LDP neighbor information -``` - -### Reset - -```{opcmd} reset mpls ldp neighbor \ - -Use this command to reset an LDP neighbor/TCP session that is established -``` - -[wikipedia (mpls)]: diff --git a/docs/configuration/protocols/md-multicast.md b/docs/configuration/protocols/md-multicast.md deleted file mode 100644 index 27150a29..00000000 --- a/docs/configuration/protocols/md-multicast.md +++ /dev/null @@ -1,31 +0,0 @@ -(routing-static)= - -# Multicast - -In order to influence Multicast {abbr}`RPF (Reverse Path Forwarding)` lookup, -it is possible to insert into zebra routes for the Multicast -{abbr}`RIB (Routing Information Base)`. These routes are only used for RPF -lookup and will not be used by ZEBRA for insertion into the kernel or for -normal RIB processing. As such it is possible to create weird states with -these commands. - -Use with caution. Most of the time this will not be necessary. - -```{cfgcmd} set protocols static mroute \ next-hop \ [distance \] - -Insert into the Multicast RIB Route `` with specified next-hop. -The distance can be specified as well if desired. -``` -```{cfgcmd} set protocols static mroute \ next-hop \ disable - -Do not install route for `` into the Multicast RIB. -``` -```{cfgcmd} set protocols static mroute \ interface \ [distance \] - -Insert into the Multicast RIB Route `` with specified ``. -The distance can be specified as well if desired. -``` -```{cfgcmd} set protocols static mroute \ interface \ disable - -Do not install route for `` into the Multicast RIB. -``` \ No newline at end of file diff --git a/docs/configuration/protocols/md-openfabric.md b/docs/configuration/protocols/md-openfabric.md deleted file mode 100644 index 09ff5900..00000000 --- a/docs/configuration/protocols/md-openfabric.md +++ /dev/null @@ -1,242 +0,0 @@ -(openfabric)= - -# OpenFabric - -OpenFabric, specified in [draft-white-openfabric-06.txt](https://datatracker.ietf.org/doc/html/draft-white-openfabric-06), is -a routing protocol derived from IS-IS, providing link-state routing with -efficient flooding for topologies like spine-leaf networks. - -OpenFabric a dual stack protocol. -A single OpenFabric instance is able to perform routing for both IPv4 and IPv6. - -## General - -### Configuration - -#### Mandatory Settings - -For OpenFabric to operate correctly, one must do the equivalent of a Router ID -in Connectionless Network Service (CLNS). This Router ID is called the -{abbr}`NET (Network Entity Title)`. The system identifier must be unique within -the network - -```{cfgcmd} set protocols openfabric net \ - -This command sets network entity title (NET) provided in ISO format. - -Here is an example {abbr}`NET (Network Entity Title)` value: - -:::{code-block} none -49.0001.1921.6800.1002.00 -::: -The CLNS address consists of the following parts: - -* {abbr}`AFI (Address family authority identifier)` - ``49`` The AFI value - 49 is what OpenFabric uses for private addressing. - -* Area identifier: ``0001`` OpenFabric area number (numerical area ``1``) - -* System identifier: ``1921.6800.1002`` - for system identifiers we recommend - to use IP address or MAC address of the router itself. The way to construct - this is to keep all of the zeroes of the router IP address, and then change - the periods from being every three numbers to every four numbers. The - address that is listed here is ``192.168.1.2``, which if expanded will turn - into ``192.168.001.002``. Then all one has to do is move the dots to have - four numbers instead of three. This gives us ``1921.6800.1002``. - -* {abbr}`NET (Network Entity Title)` selector: ``00`` Must always be 00. This - setting indicates "this system" or "local system." -``` - - -```{cfgcmd} set protocols openfabric domain \ interface \ address-family \ - -This command enables OpenFabric instance with \ on this interface, and -allows for adjacency to occur for address family (IPv4 or IPv6 or both). -``` - -#### OpenFabric Global Configuration - -```{cfgcmd} set protocols openfabric domain-password \ \ - -This command configures the authentication password for a routing domain, -as clear text or md5 one. -``` - - -```{cfgcmd} set protocols openfabric domain \ purge-originator - -This command enables {rfc}`6232` purge originator identification. -``` - - -```{cfgcmd} set protocols openfabric domain \ set-overload-bit - -This command sets overload bit to avoid any transit traffic through this -router. -``` - - -```{cfgcmd} set protocols openfabric domain \ log-adjacency-changes - -Log changes in adjacency state. -``` - - -```{cfgcmd} set protocols openfabric domain \ fabric-tier \ - -This command sets a static tier number to advertise as location -in the fabric. -``` - -#### Interface Configuration - -```{cfgcmd} set protocols openfabric interface \ hello-interval \ - -This command sets hello interval in seconds on a given interface. -The range is 1 to 600. Hello packets are used to establish and maintain -adjacency between OpenFabric neighbors. -``` - - -```{cfgcmd} set protocols openfabric domain \ interface \ hello-multiplier \ - -This command sets multiplier for hello holding time on a given -interface. The range is 2 to 100. -``` - - -```{cfgcmd} set protocols openfabric domain \ interface \ metric \ - -This command sets default metric for circuit. -The metric range is 1 to 16777215. -``` - - -```{cfgcmd} set protocols openfabric interface \ passive - -This command enables the passive mode for this interface. -``` - - -```{cfgcmd} set protocols openfabric domain \ interface \ password plaintext-password \ - -This command sets the authentication password for the interface. -``` - - -```{cfgcmd} set protocols openfabric domain \ interface \ csnp-interval \ - -This command sets Complete Sequence Number Packets (CSNP) interval in seconds. -The interval range is 1 to 600. -``` - - -```{cfgcmd} set protocols openfabric domain \ interface \ psnp-interval \ - -This command sets Partial Sequence Number Packets (PSNP) interval in seconds. -The interval range is 1 to 120. -``` - -#### Timers - -```{cfgcmd} set protocols openfabric domain \ lsp-gen-interval \ - -This command sets minimum interval at which link-state packets (LSPs) are -generated. The interval range is 1 to 120. -``` - - -```{cfgcmd} set protocols openfabric domain \ lsp-refresh-interval \ - -This command sets LSP refresh interval in seconds. The interval range -is 1 to 65235. -``` - - -```{cfgcmd} set protocols openfabric domain \ max-lsp-lifetime \ - -This command sets LSP maximum LSP lifetime in seconds. The interval range -is 360 to 65535. LSPs remain in a database for 1200 seconds by default. -If they are not refreshed by that time, they are deleted. You can change -the LSP refresh interval or the LSP lifetime. The LSP refresh interval -should be less than the LSP lifetime or else LSPs will time out before -they are refreshed. -``` - - -```{cfgcmd} set protocols openfabric domain \ spf-interval \ - -This command sets minimum interval between consecutive shortest path first -(SPF) calculations in seconds.The interval range is 1 to 120. -``` - -## Examples -### Enable OpenFabric - -**Node 1:** - -```none -set interfaces loopback lo address '192.168.255.255/32' -set interfaces ethernet eth1 address '192.0.2.1/24' - -set protocols openfabric domain VyOS interface eth1 address-family ipv4 -set protocols openfabric domain VyOS interface lo address-family ipv4 -set protocols openfabric net '49.0001.1921.6825.5255.00' -``` - -**Node 2:** - -```none -set interfaces loopback lo address '192.168.255.254/32' -set interfaces ethernet eth1 address '192.0.2.2/24' - -set protocols openfabric domain VyOS interface eth1 address-family ipv4 -set protocols openfabric domain VyOS interface lo address-family ipv4 -set protocols openfabric net '49.0001.1921.6825.5254.00' -``` - -This gives us the following neighborships: - -```none -Node-1@vyos:~$ show openfabric neighbor -show openfabric neighbor -Area VyOS: - System Id Interface L State Holdtime SNPA - vyos eth1 2 Up 27 2020.2020.2020 - - -Node-2@vyos:~$ show openfabric neighbor -show openfabric neighbor -Area VyOS: - System Id Interface L State Holdtime SNPA - vyos eth1 2 Up 30 2020.2020.2020 -``` - -Here's the IP routes that are populated: - -```none -Node-1@vyos:~$ show ip route openfabric -show ip route openfabric -Codes: K - kernel route, C - connected, S - static, R - RIP, - O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, - T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, - f - OpenFabric, - > - selected route, * - FIB route, q - queued, r - rejected, b - backup - t - trapped, o - offload failure - -f 192.0.2.0/24 [115/20] via 192.0.2.2, eth1 onlink, weight 1, 00:00:10 -f>* 192.168.255.254/32 [115/20] via 192.0.2.2, eth1 onlink, weight 1, 00:00:10 - -Node-2@vyos:~$ show ip route openfabric -show ip route openfabric -Codes: K - kernel route, C - connected, S - static, R - RIP, - O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, - T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, - f - OpenFabric, - > - selected route, * - FIB route, q - queued, r - rejected, b - backup - t - trapped, o - offload failure - -f 192.0.2.0/24 [115/20] via 192.0.2.1, eth1 onlink, weight 1, 00:00:48 -f>* 192.168.255.255/32 [115/20] via 192.0.2.1, eth1 onlink, weight 1, 00:00:48 -``` diff --git a/docs/configuration/protocols/md-ospf.md b/docs/configuration/protocols/md-ospf.md deleted file mode 100644 index 72fefb84..00000000 --- a/docs/configuration/protocols/md-ospf.md +++ /dev/null @@ -1,1504 +0,0 @@ -(routing-ospf)= - -# OSPF - -{abbr}`OSPF (Open Shortest Path First)` is a routing protocol for Internet -Protocol (IP) networks. It uses a link state routing (LSR) algorithm and falls -into the group of interior gateway protocols (IGPs), operating within a single -autonomous system (AS). It is defined as OSPF Version 2 in {rfc}`2328` (1998) -for IPv4. Updates for IPv6 are specified as OSPF Version 3 in {rfc}`5340` -(2008). OSPF supports the {abbr}`CIDR (Classless Inter-Domain Routing)` -addressing model. - -OSPF is a widely used IGP in large enterprise networks. - -## OSPFv2 (IPv4) - -### Configuration - -#### General - -VyOS does not have a special command to start the OSPF process. The OSPF process -starts when the first ospf enabled interface is configured. - -```{cfgcmd} set protocols ospf area \ network \ - - This command specifies the OSPF enabled interface(s). If the interface has - an address from defined range then the command enables OSPF on this - interface so router can provide network information to the other ospf - routers via this interface. - - This command is also used to enable the OSPF process. The area number can be - specified in decimal notation in the range from 0 to 4294967295. Or it - can be specified in dotted decimal notation similar to ip address. - - Prefix length in interface must be equal or bigger (i.e. smaller network) - than prefix length in network statement. For example statement above doesn't - enable ospf on interface with address 192.168.1.1/23, but it does on - interface with address 192.168.1.129/25. - - In some cases it may be more convenient to enable OSPF on a per - interface/subnet - basis {cfgcmd}`set protocols ospf interface area ` -``` - - -```{cfgcmd} set protocols ospf auto-cost reference-bandwidth \ - -This command sets the reference bandwidth for cost calculations, where -bandwidth can be in range from 1 to 4294967, specified in Mbits/s. The -default is 100Mbit/s (i.e. a link of bandwidth 100Mbit/s or higher will -have a cost of 1. Cost of lower bandwidth links will be scaled with -reference to this cost). -``` - - -```{cfgcmd} set protocols ospf parameters router-id \ - -This command sets the router-ID of the OSPF process. The router-ID may be an -IP address of the router, but need not be – it can be any arbitrary 32bit -number. However it MUST be unique within the entire OSPF domain to the OSPF -speaker – bad things will happen if multiple OSPF speakers are configured -with the same router-ID! -``` - -#### Optional - -```{cfgcmd} set protocols ospf default-information originate [always] [metric \] [metric-type \<1|2\>] [route-map \] - -Originate an AS-External (type-5) LSA describing a default route into all -external-routing capable areas, of the specified metric and metric type. -If the {cfgcmd}`always` keyword is given then the default is always -advertised, even when there is no default present in the routing table. -The argument {cfgcmd}`route-map` specifies to advertise the default route -if the route map is satisfied. -``` - - -```{cfgcmd} set protocols ospf distance global \ - -This command change distance value of OSPF globally. -The distance range is 1 to 255. -``` - - -```{cfgcmd} set protocols ospf distance ospf \ \ - -This command change distance value of OSPF. The arguments are the distance -values for external routes, inter-area routes and intra-area routes -respectively. The distance range is 1 to 255. - -:::{note} -Routes with a distance of 255 are effectively disabled and not -installed into the kernel. -::: -``` - - -```{cfgcmd} set protocols ospf log-adjacency-changes [detail] - -This command allows to log changes in adjacency. With the optional -{cfgcmd}`detail` argument, all changes in adjacency status are shown. -Without {cfgcmd}`detail`, only changes to full or regressions are shown. -``` - - -```{cfgcmd} set protocols ospf max-metric router-lsa \|on-startup \> - -This enables {rfc}`3137` support, where the OSPF process describes its -transit links in its router-LSA as having infinite distance so that other -routers will avoid calculating transit paths through the router while -still being able to reach networks through the router. - -This support may be enabled administratively (and indefinitely) with the -{cfgcmd}`administrative` command. It may also be enabled conditionally. -Conditional enabling of max-metric router-lsas can be for a period of -seconds after startup with the {cfgcmd}`on-startup ` command -and/or for a period of seconds prior to shutdown with the -{cfgcmd}`on-shutdown ` command. The time range is 5 to 86400. -``` - - -```{cfgcmd} set protocols ospf parameters abr-type \ - -This command selects ABR model. OSPF router supports four ABR models: - -**cisco** – a router will be considered as ABR if it has several configured -links to the networks in different areas one of which is a backbone area. -Moreover, the link to the backbone area should be active (working). -**ibm** – identical to "cisco" model but in this case a backbone area link -may not be active. -**standard** – router has several active links to different areas. -**shortcut** – identical to "standard" but in this model a router is -allowed to use a connected areas topology without involving a backbone -area for inter-area connections. - -Detailed information about "cisco" and "ibm" models differences can be -found in {rfc}`3509`. A "shortcut" model allows ABR to create routes -between areas based on the topology of the areas connected to this router -but not using a backbone area in case if non-backbone route will be -cheaper. For more information about "shortcut" model, -see ospf-shortcut-abr-02.txt -``` - - -```{cfgcmd} set protocols ospf parameters rfc1583-compatibility - -{rfc}`2328`, the successor to {rfc}`1583`, suggests according to section -G.2 (changes) in section 16.4.1 a change to the path preference algorithm -that prevents possible routing loops that were possible in the old version -of OSPFv2. More specifically it demands that inter-area paths and -intra-area backbone path are now of equal preference but still both -preferred to external paths. - -This command should NOT be set normally. -``` - - -```{cfgcmd} set protocols ospf interface \ passive [disable] - -This command specifies interface as passive. Passive interface advertises -its address, but does not run the OSPF protocol (adjacencies are not formed -and hello packets are not generated). - -The optional disable option allows to exclude interface from passive state. -This command is used if the command {cfgcmd}`passive-interface default` was -configured. -``` - - -```{cfgcmd} set protocols ospf passive-interface default - -This command specifies all interfaces as passive by default. Because this -command changes the configuration logic to a default passive; therefore, -interfaces where router adjacencies are expected need to be configured -with the {cfgcmd}`passive-interface-exclude` command. -``` - - -```{cfgcmd} set protocols ospf maximum-paths \<1-64\> - -Use this command to control the maximum number of equal cost paths to reach -a specific destination. The upper limit may differ if you change the value -of MULTIPATH_NUM during compilation. The default is MULTIPATH_NUM (64). -``` - - -```{cfgcmd} set protocols ospf refresh timers \ - -The router automatically updates link-state information with its neighbors. -Only an obsolete information is updated which age has exceeded a specific -threshold. This parameter changes a threshold value, which by default is -1800 seconds (half an hour). The value is applied to the whole OSPF router. -The timer range is 10 to 1800. -``` - - -```{cfgcmd} set protocols ospf timers throttle spf \ \ - -This command sets the initial delay, the initial-holdtime and the -maximum-holdtime between when SPF is calculated and the event which -triggered the calculation. The times are specified in milliseconds and must -be in the range of 0 to 600000 milliseconds. {cfgcmd}`delay` sets the -initial SPF schedule delay in milliseconds. The default value is 200 ms. -{cfgcmd}`initial-holdtime` sets the minimum hold time between two -consecutive SPF calculations. The default value is 1000 ms. -{cfgcmd}`max-holdtime` sets the maximum wait time between two -consecutive SPF calculations. The default value is 10000 ms. -``` - - -```{cfgcmd} set protocols ospf ldp-sync - -This command will enable IGP-LDP synchronization globally for OSPF. This -requires for LDP to be functional. This is described in {rfc}`5443`. By -default all interfaces operational in OSPF are enabled for synchronization. -Loopbacks are exempt. -``` - - -```{cfgcmd} set protocols ospf ldp-sync holddown \ - -This command will change the hold down value globally for IGP-LDP -synchronization during convergence/interface flap events. -``` - - -```{cfgcmd} set protocols ospf capability opaque - -ospfd supports Opaque LSA {rfc}`2370` as partial support for MPLS Traffic -Engineering LSAs. The opaque-lsa capability must be enabled in the -configuration. - -An alternate command could be "mpls-te on" (Traffic Engineering) - -:::{note} -FRR offers only partial support for some of the routing -protocol extensions that are used with MPLS-TE; it does not -support a complete RSVP-TE solution. -::: -``` - -#### Area Configuration - -```{cfgcmd} set protocols ospf area \ area-type stub - -This command specifies the area to be a Stub Area. That is, an area where -no router originates routes external to OSPF and hence an area where all -external routes are via the ABR(s). Hence, ABRs for such an area do not -need to pass AS-External LSAs (type-5) or ASBR-Summary LSAs (type-4) into -the area. They need only pass Network-Summary (type-3) LSAs into such an -area, along with a default-route summary. -``` - - -```{cfgcmd} set protocols ospf area \ area-type stub no-summary - -This command specifies the area to be a Totally Stub Area. In addition to -stub area limitations this area type prevents an ABR from injecting -Network-Summary (type-3) LSAs into the specified stub area. Only default -summary route is allowed. -``` - - -```{cfgcmd} set protocols ospf area \ area-type stub default-cost \ - -This command sets the cost of default-summary LSAs announced to stubby -areas. The cost range is 0 to 16777215. -``` - - -```{cfgcmd} set protocols ospf area \ area-type nssa - -This command specifies the area to be a Not So Stubby Area. External -routing information is imported into an NSSA in Type-7 LSAs. Type-7 LSAs -are similar to Type-5 AS-external LSAs, except that they can only be -flooded into the NSSA. In order to further propagate the NSSA external -information, the Type-7 LSA must be translated to a Type-5 AS-external-LSA -by the NSSA ABR. -``` - - -```{cfgcmd} set protocols ospf area \ area-type nssa no-summary - -This command specifies the area to be a NSSA Totally Stub Area. ABRs for -such an area do not need to pass Network-Summary (type-3) LSAs (except the -default summary route), ASBR-Summary LSAs (type-4) and AS-External LSAs -(type-5) into the area. But Type-7 LSAs that convert to Type-5 at the NSSA -ABR are allowed. -``` - - -```{cfgcmd} set protocols ospf area \ area-type nssa default-cost \ - -This command sets the default cost of LSAs announced to NSSA areas. -The cost range is 0 to 16777215. -``` - - -```{cfgcmd} set protocols ospf area \ area-type nssa translate \ - -Specifies whether this NSSA border router will unconditionally translate -Type-7 LSAs into Type-5 LSAs. When role is Always, Type-7 LSAs are -translated into Type-5 LSAs regardless of the translator state of other -NSSA border routers. When role is Candidate, this router participates in -the translator election to determine if it will perform the translations -duties. When role is Never, this router will never translate Type-7 LSAs -into Type-5 LSAs. -``` - - -```{cfgcmd} set protocols ospf area \ authentication plaintext-password - -This command specifies that simple password authentication should be used -for the given area. The password must also be configured on a per-interface -basis. -``` - - -```{cfgcmd} set protocols ospf area \ authentication md5 - -This command specify that OSPF packets must be authenticated with MD5 HMACs -within the given area. Keying material must also be configured on a -per-interface basis. -``` - - -```{cfgcmd} set protocols ospf area \ range \ [cost \] - -This command summarizes intra area paths from specified area into one -summary-LSA (Type-3) announced to other areas. This command can be used -only in ABR and ONLY router-LSAs (Type-1) and network-LSAs (Type-2) -(i.e. LSAs with scope area) can be summarized. AS-external-LSAs (Type-5) -can’t be summarized - their scope is AS. The optional argument -{cfgcmd}`cost` specifies the aggregated link metric. The metric range is 0 -to 16777215. -``` - - -```{cfgcmd} set protocols ospf area \ range \ not-advertise - -This command instead of summarizing intra area paths filter them - i.e. -intra area paths from this range are not advertised into other areas. -This command makes sense in ABR only. -``` - - -```{cfgcmd} set protocols ospf area \ export-list \ - -Filter Type-3 summary-LSAs announced to other areas originated from -intra- area paths from specified area. -This command makes sense in ABR only. -``` - - -```{cfgcmd} set protocols ospf area \ import-list \ - -Same as export-list, but it applies to paths announced into specified -area as Type-3 summary-LSAs. -This command makes sense in ABR only. -``` - - -```{cfgcmd} set protocols ospf area \ range \ substitute \ - -One Type-3 summary-LSA with routing info is announced into -backbone area if defined area contains at least one intra-area network -(i.e. described with router-LSA or network-LSA) from range . -This command makes sense in ABR only. -``` - - -```{cfgcmd} set protocols ospf area \ shortcut \ - -This parameter allows to "shortcut" routes (non-backbone) for inter-area -routes. There are three modes available for routes shortcutting: - -**default** – this area will be used for shortcutting only if ABR does not -have a link to the backbone area or this link was lost. -**enable** – the area will be used for shortcutting every time the route -that goes through it is cheaper. -**disable** – this area is never used by ABR for routes shortcutting. -``` - - -```{cfgcmd} set protocols ospf area \ virtual-link \ - -Provides a backbone area coherence by virtual link establishment. - -In general, OSPF protocol requires a backbone area (area 0) to be coherent -and fully connected. I.e. any backbone area router must have a route to any -other backbone area router. Moreover, every ABR must have a link to -backbone area. However, it is not always possible to have a physical link -to a backbone area. In this case between two ABR (one of them has a link to -the backbone area) in the area (not stub area) a virtual link is organized. - -\ – area identifier through which a virtual link goes. -\ – ABR router-id with which a virtual link is established. Virtual -link must be configured on both routers. - -Formally, a virtual link looks like a point-to-point network connecting two -ABR from one area one of which physically connected to a backbone area. -This pseudo-network is considered to belong to a backbone area. -``` - -#### Interface Configuration - -```{cfgcmd} set protocols ospf interface \ area \ - - Enable ospf on an interface and set associated area. - - If you have a lot of interfaces, and/or a lot of subnets, then enabling - OSPF via this command may result in a slight performance improvement. -``` - - -```{cfgcmd} set protocols ospf interface \ authentication plaintext-password \ - -This command sets OSPF authentication key to a simple password. After -setting, all OSPF packets are authenticated. Key has length up to 8 chars. - -Simple text password authentication is insecure and deprecated in favour of -MD5 HMAC authentication. -``` - - -```{cfgcmd} set protocols ospf interface \ authentication md5 key-id \ md5-key \ - -This command specifys that MD5 HMAC authentication must be used on this -interface. It sets OSPF authentication key to a cryptographic password. -Key-id identifies secret key used to create the message digest. This ID -is part of the protocol and must be consistent across routers on a link. -The key can be long up to 16 chars (larger strings will be truncated), -and is associated with the given key-id. -``` - - -```{cfgcmd} set protocols ospf interface \ bandwidth \ - -This command sets the interface bandwidth for cost calculations, where -bandwidth can be in range from 1 to 100000, specified in Mbits/s. -``` - - -```{cfgcmd} set protocols ospf interface \ cost \ - -This command sets link cost for the specified interface. The cost value is -set to router-LSA’s metric field and used for SPF calculation. The cost -range is 1 to 65535. -``` - - -```{cfgcmd} set protocols ospf interface \ dead-interval \ - -Set number of seconds for router Dead Interval timer value used for Wait -Timer and Inactivity Timer. This value must be the same for all routers -attached to a common network. The default value is 40 seconds. The -interval range is 1 to 65535. -``` - - -```{cfgcmd} set protocols ospf interface \ hello-multiplier \ - -The hello-multiplier specifies how many Hellos to send per second, from 1 -(every second) to 10 (every 100ms). Thus one can have 1s convergence time -for OSPF. If this form is specified, then the hello-interval advertised in -Hello packets is set to 0 and the hello-interval on received Hello packets -is not checked, thus the hello-multiplier need NOT be the same across -multiple routers on a common link. -``` - - -```{cfgcmd} set protocols ospf interface \ hello-interval \ - -Set number of seconds for Hello Interval timer value. Setting this value, -Hello packet will be sent every timer value seconds on the specified -interface. This value must be the same for all routers attached to a -common network. The default value is 10 seconds. The interval range is 1 -to 65535. -``` - - -```{cfgcmd} set protocols ospf interface \ bfd - -This command enables {abbr}`BFD (Bidirectional Forwarding Detection)` on -this OSPF link interface. -``` - - -```{cfgcmd} set protocols ospf interface \ mtu-ignore - -This command disables check of the MTU value in the OSPF DBD packets. Thus, -use of this command allows the OSPF adjacency to reach the FULL state even -though there is an interface MTU mismatch between two OSPF routers. -``` - - -```{cfgcmd} set protocols ospf interface \ network \ - -This command allows to specify the distribution type for the network -connected to this interface: - -**broadcast** – broadcast IP addresses distribution. -**non-broadcast** – address distribution in NBMA networks topology. -**point-to-multipoint** – address distribution in point-to-multipoint -networks. -**point-to-point** – address distribution in point-to-point networks. -``` - - -```{cfgcmd} set protocols ospf interface \ priority \ - -This command sets Router Priority integer value. The router with the -highest priority will be more eligible to become Designated Router. -Setting the value to 0, makes the router ineligible to become -Designated Router. The default value is 1. The interval range is 0 to 255. -``` - - -```{cfgcmd} set protocols ospf interface \ retransmit-interval \ - -This command sets number of seconds for RxmtInterval timer value. This -value is used when retransmitting Database Description and Link State -Request packets if acknowledge was not received. The default value is 5 -seconds. The interval range is 3 to 65535. -``` - - -```{cfgcmd} set protocols ospf interface \ transmit-delay \ - -This command sets number of seconds for InfTransDelay value. It allows to -set and adjust for each interface the delay interval before starting the -synchronizing process of the router's database with all neighbors. The -default value is 1 seconds. The interval range is 3 to 65535. -``` - - -```{cfgcmd} set protocols ospf interface \ ldp-sync disable - -This command disables IGP-LDP sync for this specific interface. -``` - - -```{cfgcmd} set protocols ospf interface \ ldp-sync holddown \ - -This command will change the hold down value for IGP-LDP synchronization -during convergence/interface flap events, but for this interface only. -``` - -#### External Route Summarisation - - -This feature summarises originated external LSAs (Type-5 and Type-7). Summary -Route will be originated on-behalf of all matched external LSAs. - -```{cfgcmd} set protocols ospf aggregation timer \ - -Configure aggregation delay timer interval. - -Summarisation starts only after this delay timer expiry. -``` - - -```{cfgcmd} set protocols ospf summary-address x.x.x.x/y [tag (1-4294967295)] - -This command enable/disables summarisation for the configured address range. - -Tag is the optional parameter. If tag configured Summary route will be -originated with the configured tag. -``` - - -```{cfgcmd} set protocols ospf summary-address x.x.x.x/y no-advertise - -This command to ensure not advertise the summary lsa for the matched -external LSAs. -``` - -#### Graceful Restart - -```{cfgcmd} set protocols ospf graceful-restart [grace-period (1-1800)] - -Configure Graceful Restart {rfc}`3623` restarting support. When enabled, -the default grace period is 120 seconds. - -To perform a graceful shutdown, the FRR ``graceful-restart prepare ip -ospf`` EXEC-level command needs to be issued before restarting the -ospfd daemon. -``` - - -```{cfgcmd} set protocols ospf graceful-restart helper enable [router-id A.B.C.D] - -Configure Graceful Restart {rfc}`3623` helper support. By default, helper support -is disabled for all neighbours. This config enables/disables helper support -on this router for all neighbours. - -To enable/disable helper support for a specific neighbour, the router-id -(A.B.C.D) has to be specified. -``` - - -```{cfgcmd} set protocols ospf graceful-restart helper no-strict-lsa-checking - -By default strict-lsa-checking is configured then the helper will abort -the Graceful Restart when a LSA change occurs which affects the restarting -router. - -This command disables it. -``` - - -```{cfgcmd} set protocols ospf graceful-restart helper supported-grace-time - -Supports as HELPER for configured grace period. -``` - - -```{cfgcmd} set protocols ospf graceful-restart helper planned-only - -It helps to support as HELPER only for planned restarts. - -By default, it supports both planned and unplanned outages. -``` - -#### Manual Neighbor Configuration - - -OSPF routing devices normally discover their neighbors dynamically by -listening to the broadcast or multicast hello packets on the network. -Because an NBMA network does not support broadcast (or multicast), the -device cannot discover its neighbors dynamically, so you must configure all -the neighbors statically. - -```{cfgcmd} set protocols ospf neighbor \ - -This command specifies the IP address of the neighboring device. -``` - - -```{cfgcmd} set protocols ospf neighbor \ poll-interval \ - -This command specifies the length of time, in seconds, before the routing -device sends hello packets out of the interface before it establishes -adjacency with a neighbor. The range is 1 to 65535 seconds. The default -value is 60 seconds. -``` - - -```{cfgcmd} set protocols ospf neighbor \ priority \ - -This command specifies the router priority value of the nonbroadcast -neighbor associated with the IP address specified. The default is 0. -This keyword does not apply to point-to-multipoint interfaces. -``` - -#### Redistribution Configuration - -```{cfgcmd} set protocols ospf redistribute \ - - This command redistributes routing information from the given route source - to the OSPF process. There are five modes available for route source: bgp, - connected, kernel, rip, static. -``` - - -```{cfgcmd} set protocols ospf default-metric \ - -This command specifies the default metric value of redistributed routes. -The metric range is 0 to 16777214. -``` - - -```{cfgcmd} set protocols ospf redistribute \ metric \ - -This command specifies metric for redistributed routes from the given -route source. There are five modes available for route source: bgp, -connected, kernel, rip, static. The metric range is 1 to 16777214. -``` - - -```{cfgcmd} set protocols ospf redistribute \ metric-type \<1|2\> - -This command specifies metric type for redistributed routes. Difference -between two metric types that metric type 1 is a metric which is -"commensurable" with inner OSPF links. When calculating a metric to the -external destination, the full path metric is calculated as a metric sum -path of a router which had advertised this link plus the link metric. -Thus, a route with the least summary metric will be selected. If external -link is advertised with metric type 2 the path is selected which lies -through the router which advertised this link with the least metric -despite of the fact that internal path to this router is longer (with more -cost). However, if two routers advertised an external link and with metric -type 2 the preference is given to the path which lies through the router -with a shorter internal path. If two different routers advertised two -links to the same external destimation but with different metric type, -metric type 1 is preferred. If type of a metric left undefined the router -will consider these external links to have a default metric type 2. -``` - - -```{cfgcmd} set protocols ospf redistribute \ route-map \ - -This command allows to use route map to filter redistributed routes from -the given route source. There are five modes available for route source: -bgp, connected, kernel, rip, static. -``` - -#### Operational Mode Commands - -```{opcmd} show ip ospf neighbor - - This command displays the neighbors status. -``` - - -```none -Neighbor ID Pri State Dead Time Address Interface RXmtL RqstL DBsmL -10.0.13.1 1 Full/DR 38.365s 10.0.13.1 eth0:10.0.13.3 0 0 0 -10.0.23.2 1 Full/Backup 39.175s 10.0.23.2 eth1:10.0.23.3 0 0 0 -``` - - -```{opcmd} show ip ospf neighbor detail - -This command displays the neighbors information in a detailed form, not -just a summary table. -``` - - -```none - Neighbor 10.0.13.1, interface address 10.0.13.1 - - In the area 0.0.0.0 via interface eth0 - - Neighbor priority is 1, State is Full, 5 state changes - - Most recent state change statistics: - - Progressive change 11m55s ago - - DR is 10.0.13.1, BDR is 10.0.13.3 - - Options 2 *|-|-|-|-|-|E|- - - Dead timer due in 34.854s - - Database Summary List 0 - - Link State Request List 0 - - Link State Retransmission List 0 - - Thread Inactivity Timer on - - Thread Database Description Retransmision off - - Thread Link State Request Retransmission on - - Thread Link State Update Retransmission on - - -Neighbor 10.0.23.2, interface address 10.0.23.2 - - In the area 0.0.0.1 via interface eth1 - - Neighbor priority is 1, State is Full, 4 state changes - - Most recent state change statistics: - - Progressive change 41.193s ago - - DR is 10.0.23.3, BDR is 10.0.23.2 - - Options 2 *|-|-|-|-|-|E|- - - Dead timer due in 35.661s - - Database Summary List 0 - - Link State Request List 0 - - Link State Retransmission List 0 - - Thread Inactivity Timer on - - Thread Database Description Retransmision off - - Thread Link State Request Retransmission on - - Thread Link State Update Retransmission on -``` - - -```{opcmd} show ip ospf neighbor \ - -This command displays the neighbors information in a detailed form for a -neighbor whose IP address is specified. -``` - - -```{opcmd} show ip ospf neighbor \ - -This command displays the neighbors status for a neighbor on the specified -interface. -``` - - -```{opcmd} show ip ospf interface [\] - -This command displays state and configuration of OSPF the specified -interface, or all interfaces if no interface is given. -``` - - -```none -eth0 is up - ifindex 2, MTU 1500 bytes, BW 4294967295 Mbit - Internet Address 10.0.13.3/24, Broadcast 10.0.13.255, Area 0.0.0.0 - MTU mismatch detection: enabled - Router ID 10.0.23.3, Network Type BROADCAST, Cost: 1 - Transmit Delay is 1 sec, State Backup, Priority 1 - Backup Designated Router (ID) 10.0.23.3, Interface Address 10.0.13.3 - Multicast group memberships: OSPFAllRouters OSPFDesignatedRouters - Timer intervals configured, Hello 10s, Dead 40s, Wait 40s, Retransmit 5 - Hello due in 4.470s - Neighbor Count is 1, Adjacent neighbor count is 1 -eth1 is up - ifindex 3, MTU 1500 bytes, BW 4294967295 Mbit - Internet Address 10.0.23.3/24, Broadcast 10.0.23.255, Area 0.0.0.1 - MTU mismatch detection: enabled - Router ID 10.0.23.3, Network Type BROADCAST, Cost: 1 - Transmit Delay is 1 sec, State DR, Priority 1 - Backup Designated Router (ID) 10.0.23.2, Interface Address 10.0.23.2 - Saved Network-LSA sequence number 0x80000002 - Multicast group memberships: OSPFAllRouters OSPFDesignatedRouters - Timer intervals configured, Hello 10s, Dead 40s, Wait 40s, Retransmit 5 - Hello due in 4.563s - Neighbor Count is 1, Adjacent neighbor count is 1 -``` - - -```{opcmd} show ip ospf route [detail] - -This command displays the OSPF routing table, as determined by the most -recent SPF calculation. With the optional {cfgcmd}`detail` argument, -each route item's advertiser router and network attribute will be shown. -``` - - -```none -============ OSPF network routing table ============ -N IA 10.0.12.0/24 [3] area: 0.0.0.0 - via 10.0.13.3, eth0 -N 10.0.13.0/24 [1] area: 0.0.0.0 - directly attached to eth0 -N IA 10.0.23.0/24 [2] area: 0.0.0.0 - via 10.0.13.3, eth0 -N 10.0.34.0/24 [2] area: 0.0.0.0 - via 10.0.13.3, eth0 - -============ OSPF router routing table ============= -R 10.0.23.3 [1] area: 0.0.0.0, ABR - via 10.0.13.3, eth0 -R 10.0.34.4 [2] area: 0.0.0.0, ASBR - via 10.0.13.3, eth0 - -============ OSPF external routing table =========== -N E2 172.16.0.0/24 [2/20] tag: 0 - via 10.0.13.3, eth0 -``` - -The table consists of following data: - - -**OSPF network routing table** – includes a list of acquired routes for all -accessible networks (or aggregated area ranges) of OSPF system. "IA" flag -means that route destination is in the area to which the router is not -connected, i.e. it’s an inter-area path. In square brackets a summary metric -for all links through which a path lies to this network is specified. "via" -prefix defines a router-gateway, i.e. the first router on the way to the -destination (next hop). -**OSPF router routing table** – includes a list of acquired routes to all -accessible ABRs and ASBRs. -**OSPF external routing table** – includes a list of acquired routes that are -external to the OSPF process. "E" flag points to the external link metric type -(E1 – metric type 1, E2 – metric type 2). External link metric is printed in -the "\/\" format. - -```{opcmd} show ip ospf border-routers - -This command displays a table of paths to area boundary and autonomous -system boundary routers. -``` - - -```{opcmd} show ip ospf database - -This command displays a summary table with a database contents (LSA). -``` - - -```none - OSPF Router with ID (10.0.13.1) - - Router Link States (Area 0.0.0.0) - -Link ID ADV Router Age Seq# CkSum Link count -10.0.13.1 10.0.13.1 984 0x80000005 0xd915 1 -10.0.23.3 10.0.23.3 1186 0x80000008 0xfe62 2 -10.0.34.4 10.0.34.4 1063 0x80000004 0x4e3f 1 - - Net Link States (Area 0.0.0.0) - -Link ID ADV Router Age Seq# CkSum -10.0.13.1 10.0.13.1 994 0x80000003 0x30bb -10.0.34.4 10.0.34.4 1188 0x80000001 0x9411 - - Summary Link States (Area 0.0.0.0) - -Link ID ADV Router Age Seq# CkSum Route -10.0.12.0 10.0.23.3 1608 0x80000001 0x6ab6 10.0.12.0/24 -10.0.23.0 10.0.23.3 981 0x80000003 0xe232 10.0.23.0/24 - - AS External Link States - -Link ID ADV Router Age Seq# CkSum Route -172.16.0.0 10.0.34.4 1063 0x80000001 0xc40d E2 172.16.0.0/24 [0x0] -``` - - -```{opcmd} show ip ospf database \ [A.B.C.D] [adv-router \|self-originate] - - This command displays a database contents for a specific link advertisement - type. - - The type can be the following: - asbr-summary, external, network, nssa-external, opaque-area, opaque-as, - opaque-link, router, summary. - - [A.B.C.D] – link-state-id. With this specified the command displays portion - of the network environment that is being described by the advertisement. - The value entered depends on the advertisement’s LS type. It must be - entered in the form of an IP address. - - {cfgcmd}`adv-router ` – router id, which link advertisements need - to be reviewed. - - {cfgcmd}`self-originate` displays only self-originated LSAs from the local - router. -``` - - -```none - OSPF Router with ID (10.0.13.1) - - Router Link States (Area 0.0.0.0) - -LS age: 1213 -Options: 0x2 : *|-|-|-|-|-|E|- -LS Flags: 0x3 -Flags: 0x0 -LS Type: router-LSA -Link State ID: 10.0.13.1 -Advertising Router: 10.0.13.1 -LS Seq Number: 80000009 -Checksum: 0xd119 -Length: 36 - - Number of Links: 1 - - Link connected to: a Transit Network - (Link ID) Designated Router address: 10.0.13.1 - (Link Data) Router Interface address: 10.0.13.1 - Number of TOS metrics: 0 - TOS 0 Metric: 1 -``` - - -```{opcmd} show ip ospf database max-age - -This command displays LSAs in MaxAge list. -``` - -#### Examples -### Enable OSPF - -**Node 1** - -```none -set interfaces loopback lo address 10.1.1.1/32 -set interfaces ethernet eth0 address 192.168.0.1/24 -set protocols ospf area 0 network 192.168.0.0/24 -set protocols ospf area 0 network 10.1.1.1/32 -set protocols ospf parameters router-id 10.1.1.1 -``` - -**Node 2** - -```none -set interfaces loopback lo address 10.1.1.2/32 -set interfaces ethernet eth0 address 192.168.0.2/24 -set protocols ospf area 0 network 192.168.0.0/24 -set protocols ospf area 0 network 10.1.1.2/32 -set protocols ospf parameters router-id 10.1.1.2 -``` - -Here's the neighbors up: - -```none -Node-1@vyos:~$ show ip ospf neighbor - -Neighbor ID Pri State Up Time Dead Time Address Interface RXmtL RqstL DBsmL -10.1.1.2 1 Full/DR 3m43s 36.094s 192.168.0.2 eth0:192.168.0.1 0 0 0 - - -Node-2@vyos:~$ show ip ospf neighbor - -Neighbor ID Pri State Up Time Dead Time Address Interface RXmtL RqstL DBsmL -10.1.1.1 1 Full/Backup 3m47s 31.736s 192.168.0.1 eth0:192.168.0.2 0 0 0 -``` - -Here's the routes: - -```none -Node-1@vyos:~$ show ip route ospf -Codes: K - kernel route, C - connected, S - static, R - RIP, - O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, - T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, - f - OpenFabric, - > - selected route, * - FIB route, q - queued, r - rejected, b - backup - t - trapped, o - offload failure - -O 10.1.1.1/32 [110/0] is directly connected, lo, weight 1, 00:00:14 -O>* 10.1.1.2/32 [110/1] via 192.168.0.2, eth0, weight 1, 00:00:07 -O 192.168.0.0/24 [110/1] is directly connected, eth0, weight 1, 00:03:32 - -Node-2@vyos:~$ show ip route ospf -Codes: K - kernel route, C - connected, S - static, R - RIP, - O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, - T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, - f - OpenFabric, - > - selected route, * - FIB route, q - queued, r - rejected, b - backup - t - trapped, o - offload failure - -O>* 10.1.1.1/32 [110/1] via 192.168.0.1, eth0, weight 1, 00:00:11 -O 10.1.1.2/32 [110/0] is directly connected, lo, weight 1, 00:00:04 -O 192.168.0.0/24 [110/1] is directly connected, eth0, weight 1, 00:03:18 -``` - -### Enable OSPF with route redistribution of the loopback and default originate: - -**Node 1** - -```none -set interfaces loopback lo address 10.1.1.1/32 -set protocols ospf area 0 network 192.168.0.0/24 -set protocols ospf default-information originate always -set protocols ospf default-information originate metric 10 -set protocols ospf default-information originate metric-type 2 -set protocols ospf log-adjacency-changes -set protocols ospf parameters router-id 10.1.1.1 -set protocols ospf redistribute connected metric-type 2 -set protocols ospf redistribute connected route-map CONNECT - -set policy route-map CONNECT rule 10 action permit -set policy route-map CONNECT rule 10 match interface lo -``` - -**Node 2** - -```none -set interfaces loopback lo address 10.2.2.2/32 -set protocols ospf area 0 network 192.168.0.0/24 -set protocols ospf log-adjacency-changes -set protocols ospf parameters router-id 10.2.2.2 -set protocols ospf redistribute connected metric-type 2 -set protocols ospf redistribute connected route-map CONNECT - -set policy route-map CONNECT rule 10 action permit -set policy route-map CONNECT rule 10 match interface lo -``` - -### Enable OSPF and IGP-LDP synchronization: - -**Node 1:** - -```none -set interfaces loopback lo address 10.1.1.1/32 -set interfaces ethernet eth0 address 192.168.0.1/24 - -set protocols ospf area 0 network '192.168.0.0/24' -set protocols ospf area 0 network '10.1.1.1/32' -set protocols ospf parameters router-id '10.1.1.1' -set protocols ospf ldp-sync - -set protocols mpls interface eth0 -set protocols mpls ldp discovery transport-ipv4-address 10.1.1.1 -set protocols mpls ldp interface lo -set protocols mpls ldp interface eth0 -set protocols mpls ldp parameters transport-prefer-ipv4 -set protocols mpls ldp router-id 10.1.1.1 -``` - -This gives us IGP-LDP synchronization for all non-loopback interfaces with -a holddown timer of zero seconds: - -```none -Node-1@vyos:~$ show ip ospf mpls ldp-sync - eth0 - LDP-IGP Synchronization enabled: yes - Holddown timer in seconds: 0 - State: Sync achieved -``` - -### Enable OSPF with Segment Routing (Experimental): - -**Node 1** - -```none -set interfaces loopback lo address 10.1.1.1/32 -set interfaces ethernet eth0 address 192.168.0.1/24 - -set protocols ospf area 0 network '192.168.0.0/24' -set protocols ospf area 0 network '10.1.1.1/32' -set protocols ospf parameters opaque-lsa -set protocols ospf parameters router-id '10.1.1.1' -set protocols ospf segment-routing global-block high-label-value '1100' -set protocols ospf segment-routing global-block low-label-value '1000' -set protocols ospf segment-routing prefix 10.1.1.1/32 index explicit-null -set protocols ospf segment-routing prefix 10.1.1.1/32 index value '1' -``` - -**Node 2** - -```none -set interfaces loopback lo address 10.1.1.2/32 -set interfaces ethernet eth0 address 192.168.0.2/24 - -set protocols ospf area 0 network '192.168.0.0/24' -set protocols ospf area 0 network '10.1.1.2/32' -set protocols ospf parameters opaque-lsa -set protocols ospf parameters router-id '10.1.1.2' -set protocols ospf segment-routing global-block high-label-value '1100' -set protocols ospf segment-routing global-block low-label-value '1000' -set protocols ospf segment-routing prefix 10.1.1.2/32 index explicit-null -set protocols ospf segment-routing prefix 10.1.1.2/32 index value '2' -``` - -This gives us MPLS segment routing enabled and labels for far end loopbacks: - -```none -Node-1@vyos:~$ show mpls table - Inbound Label Type Nexthop Outbound Label - ----------------------------------------------------------- - 1002 SR (OSPF) 192.168.0.2 IPv4 Explicit Null <-- Node-2 loopback learned on Node-1 - 15000 SR (OSPF) 192.168.0.2 implicit-null - 15001 SR (OSPF) 192.168.0.2 implicit-null - -Node-2@vyos:~$ show mpls table - Inbound Label Type Nexthop Outbound Label - ----------------------------------------------------------- - 1001 SR (OSPF) 192.168.0.1 IPv4 Explicit Null <-- Node-1 loopback learned on Node-2 - 15000 SR (OSPF) 192.168.0.1 implicit-null - 15001 SR (OSPF) 192.168.0.1 implicit-null -``` - -Here is the routing tables showing the MPLS segment routing label operations: - -```none -Node-1@vyos:~$ show ip route ospf -Codes: K - kernel route, C - connected, S - static, R - RIP, - O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, - T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, - f - OpenFabric, - > - selected route, * - FIB route, q - queued, r - rejected, b - backup - t - trapped, o - offload failure - -O 10.1.1.1/32 [110/0] is directly connected, lo, weight 1, 00:03:43 -O>* 10.1.1.2/32 [110/1] via 192.168.0.2, eth0, label IPv4 Explicit Null, weight 1, 00:03:32 -O 192.168.0.0/24 [110/1] is directly connected, eth0, weight 1, 00:03:43 - -Node-2@vyos:~$ show ip route ospf -Codes: K - kernel route, C - connected, S - static, R - RIP, - O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, - T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, - f - OpenFabric, - > - selected route, * - FIB route, q - queued, r - rejected, b - backup - t - trapped, o - offload failure - -O>* 10.1.1.1/32 [110/1] via 192.168.0.1, eth0, label IPv4 Explicit Null, weight 1, 00:03:36 -O 10.1.1.2/32 [110/0] is directly connected, lo, weight 1, 00:03:51 -O 192.168.0.0/24 [110/1] is directly connected, eth0, weight 1, 00:03:51 -``` - -(routing-ospfv3)= - -## OSPFv3 (IPv6) - -(ospf-v3-configuration)= - -### Configuration - -(ospf-v3-general)= - -#### General - -VyOS does not have a special command to start the OSPFv3 process. The OSPFv3 -process starts when the first ospf enabled interface is configured. - -```{cfgcmd} set protocols ospfv3 interface \ area \ - - This command specifies the OSPFv3 enabled interface. This command is also - used to enable the OSPF process. The area number can be specified in - decimal notation in the range from 0 to 4294967295. Or it can be specified - in dotted decimal notation similar to ip address. -``` - - -```{cfgcmd} set protocols ospfv3 parameters router-id \ - -This command sets the router-ID of the OSPFv3 process. The router-ID may be -an IP address of the router, but need not be – it can be any arbitrary -32bit number. However it MUST be unique within the entire OSPFv3 domain to -the OSPFv3 speaker – bad things will happen if multiple OSPFv3 speakers are -configured with the same router-ID! -``` - -(ospf-v3-optional)= - -#### Optional - -```{cfgcmd} set protocols ospfv3 distance global \ - -This command change distance value of OSPFv3 globally. -The distance range is 1 to 255. -``` -```{cfgcmd} set protocols ospfv3 distance ospfv3 \ \ - -This command change distance value of OSPFv3. The arguments are the -distance values for external routes, inter-area routes and intra-area -routes respectively. The distance range is 1 to 255. -``` - -(ospf-v3-area-configuration)= - -#### Area Configuration - -```{cfgcmd} set protocols ospfv3 area \ range \ - -This command summarizes intra area paths from specified area into one -Type-3 Inter-Area Prefix LSA announced to other areas. This command can be -used only in ABR. -``` -```{cfgcmd} set protocols ospfv3 area \ range \ not-advertise - -This command instead of summarizing intra area paths filter them - i.e. -intra area paths from this range are not advertised into other areas. This -command makes sense in ABR only. -``` - -(ospf-v3-interface-config)= - -#### Interface Configuration - -```{cfgcmd} set protocols ospfv3 interface \ ipv6 cost \ - -This command sets link cost for the specified interface. The cost value is -set to router-LSA’s metric field and used for SPF calculation. The cost -range is 1 to 65535. -``` -```{cfgcmd} set protocols ospfv3 interface \ dead-interval \ - -Set number of seconds for router Dead Interval timer value used for Wait -Timer and Inactivity Timer. This value must be the same for all routers -attached to a common network. The default value is 40 seconds. The -interval range is 1 to 65535. -``` -```{cfgcmd} set protocols ospfv3 interface \ hello-interval \ - -Set number of seconds for Hello Interval timer value. Setting this value, -Hello packet will be sent every timer value seconds on the specified -interface. This value must be the same for all routers attached to a -common network. The default value is 10 seconds. The interval range is 1 -to 65535. -``` -```{cfgcmd} set protocols ospfv3 interface \ mtu-ignore - -This command disables check of the MTU value in the OSPF DBD packets. -Thus, use of this command allows the OSPF adjacency to reach the FULL -state even though there is an interface MTU mismatch between two OSPF -routers. -``` -```{cfgcmd} set protocols ospfv3 interface \ network \ - -This command allows to specify the distribution type for the network -connected to this interface: - -**broadcast** – broadcast IP addresses distribution. -**point-to-point** – address distribution in point-to-point networks. -``` -```{cfgcmd} set protocols ospfv3 interface \ priority \ - -This command sets Router Priority integer value. The router with the -highest priority will be more eligible to become Designated Router. -Setting the value to 0, makes the router ineligible to become Designated -Router. The default value is 1. The interval range is 0 to 255. -``` -```{cfgcmd} set protocols ospfv3 interface \ passive - -This command specifies interface as passive. Passive interface advertises -its address, but does not run the OSPF protocol (adjacencies are not formed -and hello packets are not generated). -``` -```{cfgcmd} set protocols ospfv3 interface \ retransmit-interval \ - -This command sets number of seconds for RxmtInterval timer value. This -value is used when retransmitting Database Description and Link State -Request packets if acknowledge was not received. The default value is 5 -seconds. The interval range is 3 to 65535. -``` -```{cfgcmd} set protocols ospfv3 interface \ transmit-delay \ - -This command sets number of seconds for InfTransDelay value. It allows to -set and adjust for each interface the delay interval before starting the -synchronizing process of the router's database with all neighbors. The -default value is 1 seconds. The interval range is 3 to 65535. -``` - -(ospf-v3-graceful-restart)= - -#### Graceful Restart - -```{cfgcmd} set protocols ospfv3 graceful-restart [grace-period (1-1800)] - -Configure Graceful Restart {rfc}`3623` restarting support. When enabled, -the default grace period is 120 seconds. - -To perform a graceful shutdown, the FRR ``graceful-restart prepare ip -ospf`` EXEC-level command needs to be issued before restarting the -ospfd daemon. -``` -```{cfgcmd} set protocols ospfv3 graceful-restart helper enable [router-id A.B.C.D] - -Configure Graceful Restart {rfc}`3623` helper support. By default, helper support -is disabled for all neighbours. This config enables/disables helper support -on this router for all neighbours. - -To enable/disable helper support for a specific neighbour, the router-id -(A.B.C.D) has to be specified. -``` -```{cfgcmd} set protocols ospfv3 graceful-restart helper lsa-check-disable - -By default strict-lsa-checking is configured then the helper will abort -the Graceful Restart when a LSA change occurs which affects the restarting -router. - -This command disables it. -``` -```{cfgcmd} set protocols ospfv3 graceful-restart helper supported-grace-time - -Supports as HELPER for configured grace period. -``` -```{cfgcmd} set protocols ospfv3 graceful-restart helper planned-only - -It helps to support as HELPER only for planned restarts. -By default, it supports both planned and unplanned outages. -``` - -(ospf-v3-redistribution-config)= - -#### Redistribution Configuration - -```{cfgcmd} set protocols ospfv3 redistribute \ - -This command redistributes routing information from the given route source -to the OSPFv3 process. There are five modes available for route source: -bgp, connected, kernel, ripng, static. -``` -```{cfgcmd} set protocols ospf redistribute \ route-map \ - -This command allows to use route map to filter redistributed routes from -given route source. There are five modes available for route source: bgp, -connected, kernel, ripng, static. -``` - -(ospf-v3-op-cmd)= - -#### Operational Mode Commands - -```{opcmd} show ipv6 ospfv3 neighbor - -This command displays the neighbors status. -``` -```{opcmd} show ipv6 ospfv3 neighbor detail - -This command displays the neighbors information in a detailed form, not -just a summary table. -``` -```{opcmd} show ipv6 ospfv3 neighbor drchoice - -This command displays the neighbor DR choice information. -``` -```{opcmd} show ipv6 ospfv3 interface [prefix]|[\ [prefix]] - -This command displays state and configuration of OSPF the specified -interface, or all interfaces if no interface is given. Whith the argument -{cfgcmd}`prefix` this command shows connected prefixes to advertise. -``` -```{opcmd} show ipv6 ospfv3 route - -This command displays the OSPF routing table, as determined by the most -recent SPF calculation. -``` -```{opcmd} show ipv6 ospfv3 border-routers - -This command displays a table of paths to area boundary and autonomous -system boundary routers. -``` -```{opcmd} show ipv6 ospfv3 database - -This command displays a summary table with a database contents (LSA). -``` -```{opcmd} show ipv6 ospfv3 database \ [A.B.C.D] [adv-router \|self-originate] - -This command displays a database contents for a specific link -advertisement type. -``` -```{opcmd} show ipv6 ospfv3 redistribute - -This command displays external information redistributed into OSPFv3 -``` - -(ospf-v3-config-example)= - -#### Configuration Example - -A typical configuration using 2 nodes. - -**Node 1:** - -```none -set protocols ospfv3 interface eth1 area 0.0.0.0 -set protocols ospfv3 area 0.0.0.0 range 2001:db8:1::/64 -set protocols ospfv3 parameters router-id 192.168.1.1 -set protocols ospfv3 redistribute connected -``` - -**Node 2:** - -```none -set protocols ospfv3 interface eth1 area 0.0.0.0 -set protocols ospfv3 area 0.0.0.0 range 2001:db8:2::/64 -set protocols ospfv3 parameters router-id 192.168.2.1 -set protocols ospfv3 redistribute connected -``` - -**To see the redistributed routes:** - -```none -show ipv6 ospfv3 redistribute -``` - -Cost calculation wireguard interfaces is unreliable as ospfv3 uses the link speed to calculate the link cost. -You might therefore want to set the link cost to a fixed value on WireGuard tunnels. - -Example configuration for WireGuard interfaces: - -**Node 1** - -```none -set interfaces wireguard wg01 peer ospf02 allowed-ips '::/0' -set interfaces wireguard wg01 peer ospf02 endpoint '10.1.1.101:12345' -set interfaces wireguard wg01 peer ospf02 pubkey 'ie3...=' -set interfaces wireguard wg01 port '12345' -set protocols ospfv3 parameters router-id 192.168.1.1 -set protocols ospfv3 interface 'wg01' area 0.0.0.0 -set protocols ospfv3 interface 'wg01' cost 10 -set protocols ospfv3 interface 'lo' area 0.0.0.0 -``` - -**Node 2** - -```none -set interfaces wireguard wg01 peer ospf01 allowed-ips '::/0' -set interfaces wireguard wg01 peer ospf01 endpoint '10.1.1.100:12345' -set interfaces wireguard wg01 peer ospf01 pubkey 'NHI...=' -set interfaces wireguard wg01 port '12345' -set protocols ospfv3 parameters router-id 192.168.1.2 -set protocols ospfv3 interface 'wg01' area 0.0.0.0 -set protocols ospfv3 interface 'wg01' cost 10 -set protocols ospfv3 interface 'lo' area 0.0.0.0 -``` - -**Status** - -```none -vyos@ospf01:~$ sh ipv6 ospfv3 neighbor -Neighbor ID Pri DeadTime State/IfState Duration I/F[State] -192.168.0.2 1 00:00:37 Full/PointToPoint 00:18:03 wg01[PointToPoint] - -vyos@ospf02# run sh ipv6 ospfv3 neighbor -Neighbor ID Pri DeadTime State/IfState Duration I/F[State] -192.168.0.1 1 00:00:39 Full/PointToPoint 00:19:44 wg01[PointToPoint] -``` diff --git a/docs/configuration/protocols/md-pim.md b/docs/configuration/protocols/md-pim.md deleted file mode 100644 index db8c9fb7..00000000 --- a/docs/configuration/protocols/md-pim.md +++ /dev/null @@ -1,282 +0,0 @@ ---- -lastproofread: '2023-11-13' ---- - -(pim)= - -# PIM – Protocol Independent Multicast - -VyOS supports {abbr}`PIM-SM (PIM Sparse Mode)` as well as -{abbr}`IGMP (Internet Group Management Protocol)` v2 and v3 - -{abbr}`PIM (Protocol Independent Multicast)` must be configured in every -interface of every participating router. Every router must also have the -location of the Rendevouz Point manually configured. Then, unidirectional -shared trees rooted at the Rendevouz Point will automatically be built -for multicast distribution. - -Traffic from multicast sources will go to the Rendezvous Point, and -receivers will pull it from a shared tree using {abbr}`IGMP (Internet -Group Management Protocol)`. - -Multicast receivers will talk IGMP to their local router, so, besides -having PIM configured in every router, IGMP must also be configured in -any router where there could be a multicast receiver locally connected. - -VyOS supports both IGMP version 2 and version 3 (which allows -source-specific multicast). - -## PIM-SM - PIM Sparse Mode - -```{cfgcmd} set protocols pim ecmp - -If PIM has the a choice of ECMP nexthops for a particular -{abbr}`RPF (Reverse Path Forwarding)`, PIM will cause S,G flows to be -spread out amongst the nexthops. If this command is not specified then -the first nexthop found will be used. -``` - -```{cfgcmd} set protocols pim ecmp rebalance - -If PIM is using ECMP and an interface goes down, cause PIM to rebalance all -S,G flows across the remaining nexthops. If this command is not configured -PIM only modifies those S,G flows that were using the interface that went -down. -``` - -```{cfgcmd} set protocols pim join-prune-interval \ - -Modify the join/prune interval that PIM uses to the new value. Time is -specified in seconds. - -The default time is 60 seconds. - -If you enter a value smaller than 60 seconds be aware that this can and -will affect convergence at scale. -``` - -```{cfgcmd} set protocols pim keep-alive-timer \ - -Modify the time out value for a S,G flow from 1-65535 seconds. If choosing -a value below 31 seconds be aware that some hardware platforms cannot see -data flowing in better than 30 second chunks. -``` - -```{cfgcmd} set protocols pim packets \ - -When processing packets from a neighbor process the number of packets -incoming at one time before moving on to the next task. - -The default value is 3 packets. - -This command is only useful at scale when you can possibly have a large -number of PIM control packets flowing. -``` - -```{cfgcmd} set protocols pim register-accept-list \ - -When PIM receives a register packet the source of the packet will be compared -to the prefix-list specified, and if a permit is received normal processing -continues. If a deny is returned for the source address of the register packet -a register stop message is sent to the source. -``` - -```{cfgcmd} set protocols pim register-suppress-time \ - -Modify the time that pim will register suppress a FHR will send register -notifications to the kernel. -``` - -```{cfgcmd} set protocols pim rp \ group \ - -In order to use PIM, it is necessary to configure a {abbr}`RP (Rendezvous Point)` -for join messages to be sent to. Currently the only methodology to do this is -via static rendezvous point commands. - -All routers in the PIM network must agree on these values. - -The first ip address is the RP's address and the second value is the matching -prefix of group ranges covered. -``` - -```{cfgcmd} set protocols pim rp keep-alive-timer \ - -Modify the time out value for a S,G flow from 1-65535 seconds at -{abbr}`RP (Rendezvous Point)`. The normal keepalive period for the KAT(S,G) -defaults to 210 seconds. However, at the {abbr}`RP (Rendezvous Point)`, the -keepalive period must be at least the Register_Suppression_Time, or the RP -may time out the (S,G) state before the next Null-Register arrives. -Thus, the KAT(S,G) is set to max(Keepalive_Period, RP_Keepalive_Period) -when a Register-Stop is sent. - -If choosing a value below 31 seconds be aware that some hardware platforms -cannot see data flowing in better than 30 second chunks. - -See {rfc}`7761#section-4.1` for details. -``` - -```{cfgcmd} set protocols pim no-v6-secondary - -When sending PIM hello packets tell PIM to not send any v6 secondary -addresses on the interface. This information is used to allow PIM to use v6 -nexthops in it's decision for {abbr}`RPF (Reverse Path Forwarding)` lookup -if this option is not set (default). -``` - -```{cfgcmd} set protocols pim spt-switchover infinity-and-beyond [prefix-list \] - -On the last hop router if it is desired to not switch over to the SPT tree -configure this command. - -Optional parameter prefix-list can be use to control which groups to switch or -not switch. If a group is PERMIT as per the prefix-list, then the SPT switchover -does not happen for it and if it is DENY, then the SPT switchover happens. -``` - -```{cfgcmd} set protocols pim ssm prefix-list \ - -Specify a range of group addresses via a prefix-list that forces PIM to never -do {abbr}`SSM (Source-Specific Multicast)` over. -``` - - -### Interface specific commands - -```{cfgcmd} set protocols pim interface \ bfd [profile \] - -Automatically create BFD session for each RIP peer discovered in this -interface. When the BFD session monitor signalize that the link is down -the RIP peer is removed and all the learned routes associated with that -peer are removed. - -If optional profile parameter is used, select a BFD profile for the BFD -sessions created via this interface. -``` - -```{cfgcmd} set protocols pim interface \ dr-priority \ - -Set the {abbr}`DR (Designated Router)` Priority for the interface. -This command is useful to allow the user to influence what node becomes -the DR for a LAN segment. -``` - -```{cfgcmd} set protocols pim interface \ hello \ - -Set the PIM hello and hold interval for a interface. -``` - -```{cfgcmd} set protocols pim interface \ no-bsm - -Tell PIM that we would not like to use this interface to process -bootstrap messages. -``` - -```{cfgcmd} set protocols pim interface \ no-unicast-bsm - -Tell PIM that we would not like to use this interface to process -unicast bootstrap messages. -``` - -```{cfgcmd} set protocols pim interface \ passive - -Disable sending and receiving PIM control packets on the interface. -``` - -```{cfgcmd} set protocols pim interface \ source-address \ - -If you have multiple addresses configured on a particular interface and would -like PIM to use a specific source address associated with that interface. -``` - - -## IGMP - Internet Group Management Protocol) - -```{cfgcmd} set protocols pim igmp watermark-warning \ - -Configure watermark warning generation for an IGMP group limit. Generates -warning once the configured group limit is reached while adding new groups. -``` - -(pim-igmp-interface-commands)= - -### Interface specific commands - -```{cfgcmd} set protocols pim interface \ igmp join \ source-address \ - -Use this command to allow the selected interface to join a multicast -group defining the multicast address you want to join and the source -IP address too. -``` - -```{cfgcmd} set protocols pim interface \ igmp query-interval \ - -Use this command to configure in the selected interface the IGMP -host query interval (1-1800) in seconds that PIM will use. -``` - -```{cfgcmd} set protocols pim interface \ igmp query-max-response-time \ - -Use this command to configure in the selected interface the IGMP -query response timeout value (10-250) in deciseconds. If a report is -not returned in the specified time, it will be assumed the (S,G) or -(\*,G) state {rfc}`7761#section-4.1` has timed out. -``` - -```{cfgcmd} set protocols pim interface \ igmp version \ - -Use this command to define in the selected interface whether you -choose IGMP version 2 or 3. - -The default value is 3. -``` - - -#### Example - -In the following example we can see a basic multicast setup: - -```{image} /_static/images/multicast-basic.webp -:align: center -:alt: Network Topology Diagram -:width: 90% -``` - -**Router 1** - -```none -set interfaces ethernet eth2 address '172.16.0.2/24' -set interfaces ethernet eth1 address '100.64.0.1/24' -set protocols ospf area 0 network '172.16.0.0/24' -set protocols ospf area 0 network '100.64.0.0/24' -set protocols igmp interface eth1 -set protocols pim interface eth1 -set protocols pim interface eth2 -set protocols pim rp address 172.16.255.1 group '224.0.0.0/4' -``` - -**Router 3** - -```none -set interfaces dummy dum0 address '172.16.255.1/24' -set interfaces ethernet eth0 address '172.16.0.1/24' -set interfaces ethernet eth1 address '172.16.1.1/24' -set protocols ospf area 0 network '172.16.0.0/24' -set protocols ospf area 0 network '172.16.255.0/24' -set protocols ospf area 0 network '172.16.1.0/24' -set protocols pim interface dum0 -set protocols pim interface eth0 -set protocols pim interface eth1 -set protocols pim rp address 172.16.255.1 group '224.0.0.0/4' -``` - -**Router 2** - -```none -set interfaces ethernet eth1 address '10.0.0.1/24' -set interfaces ethernet eth2 address '172.16.1.2/24' -set protocols ospf area 0 network '10.0.0.0/24' -set protocols ospf area 0 network '172.16.1.0/24' -set protocols pim interface eth1 -set protocols pim interface eth2 -set protocols pim rp address 172.16.255.1 group '224.0.0.0/4' -``` diff --git a/docs/configuration/protocols/md-pim6.md b/docs/configuration/protocols/md-pim6.md deleted file mode 100644 index 707ae606..00000000 --- a/docs/configuration/protocols/md-pim6.md +++ /dev/null @@ -1,100 +0,0 @@ -(pim6)= - -# PIM6 - Protocol Independent Multicast for IPv6 - -VyOS facilitates IPv6 Multicast by supporting **PIMv6** and **MLD**. - -PIMv6 (Protocol Independent Multicast for IPv6) must be configured in every -interface of every participating router. Every router must also have the -location of the Rendevouz Point manually configured. -Then, unidirectional shared trees rooted at the Rendevouz Point will -automatically be built for multicast distribution. - -Traffic from multicast sources will go to the Rendezvous Point, and receivers -will pull it from a shared tree using MLD (Multicast Listener Discovery). - -Multicast receivers will talk MLD to their local router, so, besides having -PIMv6 configured in every router, MLD must also be configured in any router -where there could be a multicast receiver locally connected. - -VyOS supports both MLD version 1 and version 2 -(which allows source-specific multicast). - -## Basic commands - -These are the commands for a basic setup. - -```{cfgcmd} set protocols pim6 interface \ - - Use this command to enable PIMv6 in the selected interface so that it - can communicate with PIMv6 neighbors. This command also enables MLD reports - and query on the interface unless {cfgcmd}`mld disable` is configured. -``` - - -```{cfgcmd} set protocols pim6 interface \ mld disable - -Disable MLD reports and query on the interface. -``` - - -## Tuning commands - -You can also tune multicast with the following commands. - -```{cfgcmd} set protocols pim6 interface \ mld interval \ - -Use this command to configure in the selected interface the MLD -host query interval (1-65535) in seconds that PIM will use. -The default value is 125 seconds. -``` - -```{cfgcmd} set protocols pim6 interface \ mld join \ - -Use this command to allow the selected interface to join a multicast group. -``` - -```{cfgcmd} set protocols pim6 interface \ mld join \ source \ - -Use this command to allow the selected interface to join a source-specific multicast -group. -``` - -```{cfgcmd} set protocols pim6 interface \ mld last-member-query-count \ - -Set the MLD last member query count. The default value is 2. -``` - -```{cfgcmd} set protocols pim6 interface \ mld last-member-query-interval \ - -Set the MLD last member query interval in milliseconds (100-6553500). The default value is 1000 milliseconds. -``` - -```{cfgcmd} set protocols pim6 interface \ mld max-response-time \ - -Set the MLD query response timeout in milliseconds (100-6553500). The default value is 10000 milliseconds. -``` - -```{cfgcmd} set protocols pim6 interface \ mld version \ - -Set the MLD version used on this interface. The default value is 2. -``` - - -### Configuration Example - -To enable MLD reports and query on interfaces `eth0` and `eth1`: - -```none -set protocols pim6 interface eth0 -set protocols pim6 interface eth1 -``` - -The following configuration explicitly joins multicast group `ff15::1234` on interface `eth1` -and source-specific multicast group `ff15::5678` with source address `2001:db8::1` on interface -`eth1`: - -```none -set protocols pim6 interface eth0 mld join ff15::1234 -set protocols pim6 interface eth1 mld join ff15::5678 source 2001:db8::1 -``` diff --git a/docs/configuration/protocols/md-rip.md b/docs/configuration/protocols/md-rip.md deleted file mode 100644 index 684337d6..00000000 --- a/docs/configuration/protocols/md-rip.md +++ /dev/null @@ -1,294 +0,0 @@ ---- -lastproofread: '2021-10-04' ---- - -(rip)= - -# RIP - -{abbr}`RIP (Routing Information Protocol)` is a widely deployed interior gateway -protocol. RIP was developed in the 1970s at Xerox Labs as part of the XNS -routing protocol. RIP is a distance-vector protocol and is based on the -Bellman-Ford algorithms. As a distance-vector protocol, RIP router send updates -to its neighbors periodically, thus allowing the convergence to a known -topology. In each update, the distance to any given network will be broadcast -to its neighboring router. - -Supported versions of RIP are: - -> - RIPv1 as described in {rfc}`1058` -> - RIPv2 as described in {rfc}`2453` - -## General Configuration - -```{cfgcmd} set protocols rip network \ - -This command enables RIP and sets the RIP enable interface by NETWORK. -The interfaces which have addresses matching with NETWORK are enabled. -``` - - -```{cfgcmd} set protocols rip interface \ - -This command specifies a RIP enabled interface by interface name. Both -the sending and receiving of RIP packets will be enabled on the port -specified in this command. -``` - - -```{cfgcmd} set protocols rip neighbor \ - -This command specifies a RIP neighbor. When a neighbor doesn’t understand -multicast, this command is used to specify neighbors. In some cases, not -all routers will be able to understand multicasting, where packets are -sent to a network or a group of addresses. In a situation where a neighbor -cannot process multicast packets, it is necessary to establish a direct -link between routers. -``` - - -```{cfgcmd} set protocols rip passive-interface interface \ - -This command sets the specified interface to passive mode. On passive mode -interface, all receiving packets are processed as normal and VyOS does not -send either multicast or unicast RIP packets except to RIP neighbors -specified with neighbor command. -``` - - -```{cfgcmd} set protocols rip passive-interface interface default - -This command specifies all interfaces to passive mode. -``` - -## Optional Configuration - -```{cfgcmd} set protocols rip default-distance \ - -This command change the distance value of RIP. The distance range is 1 to 255. - -> :::{note} -> Routes with a distance of 255 are effectively disabled and not -> installed into the kernel. -> ::: -``` - - -```{cfgcmd} set protocols rip network-distance \ distance \ - -This command sets default RIP distance to a specified value when the routes -source IP address matches the specified prefix. -``` - - -```{cfgcmd} set protocols rip network-distance \ access-list \ - -This command can be used with previous command to sets default RIP distance -to specified value when the route source IP address matches the specified -prefix and the specified access-list. -``` - - -```{cfgcmd} set protocols rip default-information originate - -This command generate a default route into the RIP. -``` - - -```{cfgcmd} set protocols rip distribute-list access-list \ \ - -This command can be used to filter the RIP path using access lists. -{cfgcmd}`in` and {cfgcmd}`out` this is the direction in which the access -lists are applied. -``` - - -```{cfgcmd} set protocols rip distribute-list interface \ access-list \ \ - -This command allows you apply access lists to a chosen interface to -filter the RIP path. -``` - - -```{cfgcmd} set protocols rip distribute-list prefix-list \ \ - -This command can be used to filter the RIP path using prefix lists. -{cfgcmd}`in` and {cfgcmd}`out` this is the direction in which the prefix -lists are applied. -``` - - -```{cfgcmd} set protocols rip distribute-list interface \ prefix-list \ \ - -This command allows you apply prefix lists to a chosen interface to -filter the RIP path. -``` - - -```{cfgcmd} set protocols rip route \ - -This command is specific to FRR and VyOS. The route command makes a static -route only inside RIP. This command should be used only by advanced users -who are particularly knowledgeable about the RIP protocol. In most cases, -we recommend creating a static route in VyOS and redistributing it in RIP -using {cfgcmd}`redistribute static`. -``` - - -```{cfgcmd} set protocols rip timers update \ - -This command specifies the update timer. Every update timer seconds, the -RIP process is awakened to send an unsolicited response message containing -the complete routing table to all neighboring RIP routers. The time range -is 5 to 2147483647. The default value is 30 seconds. -``` - - -```{cfgcmd} set protocols rip timers timeout \ - -This command specifies the timeout timer. Upon expiration of the timeout, -the route is no longer valid; however, it is retained in the routing table -for a short time so that neighbors can be notified that the route has been -dropped. The time range is 5 to 2147483647. The default value is 180 -seconds. -``` - - -```{cfgcmd} set protocols rip timers garbage-collection \ - -This command specifies the garbage-collection timer. Upon expiration of -the garbage-collection timer, the route is finally removed from the -routing table. The time range is 5 to 2147483647. The default value is 120 -seconds. -``` - -## Redistribution Configuration - -```{cfgcmd} set protocols rip redistribute \ - -This command redistributes routing information from the given route source -into the RIP tables. There are five modes available for route source: bgp, -connected, kernel, ospf, static. -``` - - -```{cfgcmd} set protocols rip redistribute \ metric \ - -This command specifies metric for redistributed routes from the given route -source. There are five modes available for route source: bgp, connected, -kernel, ospf, static. The metric range is 1 to 16. -``` - - -```{cfgcmd} set protocols rip redistribute \ route-map \ - -This command allows to use route map to filter redistributed routes from -the given route source. There are five modes available for route source: -bgp, connected, kernel, ospf, static. -``` - - -```{cfgcmd} set protocols rip default-metric \ - -This command modifies the default metric (hop count) value for redistributed -routes. The metric range is 1 to 16. The default value is 1. This command -does not affect connected route even if it is redistributed by -{cfgcmd}`redistribute connected`. To modify connected routes metric -value, please use {cfgcmd}`redistribute connected metric`. -``` - -## Interfaces Configuration - -```{cfgcmd} set interfaces \ \ ip rip authentication plaintext-password \ - -This command sets the interface with RIP simple password authentication. -This command also sets authentication string. The string must be shorter -than 16 characters. -``` - - -```{cfgcmd} set interfaces \ \ ip rip authentication md5 \ password \ - -This command sets the interface with RIP MD5 authentication. This command -also sets MD5 Key. The key must be shorter than 16 characters. -``` - - -```{cfgcmd} set interfaces \ \ ip rip split-horizon disable - -This command disables split-horizon on the interface. By default, VyOS does -not advertise RIP routes out the interface over which they were learned -(split horizon).3 -``` - - -```{cfgcmd} set interfaces \ \ ip rip split-horizon poison-reverse - -This command enables poison-reverse on the interface. If both poison reverse -and split horizon are enabled, then VyOS advertises the learned routes -as unreachable over the interface on which the route was learned. -``` - -## Operational Mode Commands - -```{opcmd} show ip rip - -This command displays RIP routes. -``` -```none -Codes: R - RIP, C - connected, S - Static, O - OSPF, B - BGP -Sub-codes: - (n) - normal, (s) - static, (d) - default, (r) - redistribute, - (i) - interface - - Network Next Hop Metric From Tag Time -C(i) 10.0.12.0/24 0.0.0.0 1 self 0 -C(i) 10.0.13.0/24 0.0.0.0 1 self 0 -R(n) 10.0.23.0/24 10.0.12.2 2 10.0.12.2 0 02:53 -``` - -```{opcmd} show ip rip status - -The command displays current RIP status. It includes RIP timer, filtering, -version, RIP enabled interface and RIP peer information. -``` -```none -Routing Protocol is "rip" - Sending updates every 30 seconds with +/-50%, next due in 11 seconds - Timeout after 180 seconds, garbage collect after 120 seconds - Outgoing update filter list for all interface is not set - Incoming update filter list for all interface is not set - Default redistribution metric is 1 - Redistributing: - Default version control: send version 2, receive any version - Interface Send Recv Key-chain - eth0 2 1 2 - eth2 2 1 2 - Routing for Networks: - 10.0.12.0/24 - eth0 - Routing Information Sources: - Gateway BadPackets BadRoutes Distance Last Update - 10.0.12.2 0 0 120 00:00:11 - Distance: (default is 120) -``` - -## Configuration Example - -Simple RIP configuration using 2 nodes and redistributing connected interfaces. - -**Node 1:** - -```none -set interfaces loopback address 10.1.1.1/32 -set protocols rip network 192.168.0.0/24 -set protocols rip redistribute connected -``` - -**Node 2:** - -```none -set interfaces loopback address 10.2.2.2/32 -set protocols rip network 192.168.0.0/24 -set protocols rip redistribute connected -``` diff --git a/docs/configuration/protocols/md-rpki.md b/docs/configuration/protocols/md-rpki.md deleted file mode 100644 index 1f4cf5bf..00000000 --- a/docs/configuration/protocols/md-rpki.md +++ /dev/null @@ -1,210 +0,0 @@ -(rpki)= - -# RPKI - -:::{pull-quote} - -There are two types of Network Admins who deal with BGP, those who have -created an international incident and/or outage, and those who are lying - --- [tweet by EvilMog](https://twitter.com/Evil_Mog/status/1230924170508169216), 2020-02-21 -::: - -{abbr}`RPKI (Resource Public Key Infrastructure)` is a framework designed to -secure the Internet routing infrastructure. It associates BGP route -announcements with the correct originating {abbr}`ASN (Autonomus System -Number)` which BGP routers can then use to check each route against the -corresponding {abbr}`ROA (Route Origin Authorisation)` for validity. RPKI is -described in {rfc}`6480`. - -A BGP-speaking router like VyOS can retrieve ROA information from RPKI -"Relying Party software" (often just called an "RPKI server" or "RPKI -validator") by using {abbr}`RTR (RPKI to Router)` protocol. There are several -open source implementations to choose from, such as NLNetLabs' [Routinator] -(written in Rust), OpenBSD's [rpki-client] (written in C), and [StayRTR] (written -in Go). The RTR protocol is described in {rfc}`8210`. - -:::{tip} -If you are new to these routing security technologies then there is an -[excellent guide to RPKI] by NLnet Labs which will get you up to speed -very quickly. Their documentation explains everything from what RPKI is to -deploying it in production. It also has some -[help and operational guidance] including "What can I do about my route -having an Invalid state?" -::: - -## Getting started - -First you will need to deploy an RPKI validator for your routers to use. NLnet -Labs provides a collection of [software] you can compare and settle on one. -Once your server is running you can start validating announcements. - -Imported prefixes during the validation may have values: - -> valid -> -> : The prefix and ASN that originated it match a signed ROA. These are -> probably trustworthy route announcements. -> -> invalid -> -> : The prefix or prefix length and ASN that originated it doesn't -> match any existing ROA. This could be the result of a prefix hijack, or -> merely a misconfiguration, but should probably be treated as -> untrustworthy route announcements. -> -> notfound -> -> : No ROA exists which covers that prefix. Unfortunately this is the case for -> about 40%-50% of the prefixes which were announced to the {abbr}`DFZ -> (default-free zone)` at the start of 2024. - -:::{note} -If you are responsible for the global addresses assigned to your -network, please make sure that your prefixes have ROAs associated with them -to avoid being `notfound` by RPKI. For most ASNs this will involve -publishing ROAs via your {abbr}`RIR (Regional Internet Registry)` (RIPE -NCC, APNIC, ARIN, LACNIC, or AFRINIC), and is something you are encouraged -to do whenever you plan to announce addresses into the DFZ. - -Particularly large networks may wish to run their own RPKI certificate -authority and publication server instead of publishing ROAs via their RIR. -This is a subject far beyond the scope of VyOS' documentation. Consider -reading about [Krill] if this is a rabbit hole you need or especially want -to dive down. -::: - -### Features of the Current Implementation - -In a nutshell, the current implementation provides the following features: - -- The BGP router can connect to one or more RPKI cache servers to receive - validated prefix to origin AS mappings. Advanced failover can be implemented - by server sockets with different preference values. -- If no connection to an RPKI cache server can be established after a - pre-defined timeout, the router will process routes without prefix origin - validation. It still will try to establish a connection to an RPKI cache - server in the background. -- By default, enabling RPKI does not change best path selection. In particular, - invalid prefixes will still be considered during best path selection. However, - the router can be configured to ignore all invalid prefixes. -- Route maps can be configured to match a specific RPKI validation state. This - allows the creation of local policies, which handle BGP routes based on the - outcome of the Prefix Origin Validation. -- Updates from the RPKI cache servers are directly applied and path selection is - updated accordingly. (Soft reconfiguration must be enabled for this to work). - -## Configuration - -```{cfgcmd} set protocols rpki polling-period \<1-86400\> - -Define the time interval to update the local cache - -The default value is 300 seconds. -``` - -```{cfgcmd} set protocols rpki expire-interval \<600-172800\> - -Set the number of seconds the router waits until the router -expires the cache. - -The default value is 7200 seconds. -``` - -```{cfgcmd} set protocols rpki retry-interval \<1-7200\> - -Set the number of seconds the router waits until retrying to connect -to the cache server. - -The default value is 600 seconds. -``` - -```{cfgcmd} set protocols rpki cache \ port \ - -Defined the IPv4, IPv6 or FQDN and port number of the caching RPKI caching -instance which is used. - -This is a mandatory setting. -``` - -```{cfgcmd} set protocols rpki cache \ preference \ - -Multiple RPKI caching instances can be supplied and they need a preference in -which their result sets are used. - -This is a mandatory setting. -``` - - -### SSH - -Connections to the RPKI caching server can not only be established by TCP using -the RTR protocol but you can also rely on a secure SSH session to the server. -This provides transport integrity and confidentiality and it is a good idea if -your validation software supports it. To enable SSH, first you need to create -an SSH client keypair using `generate ssh client-key -/config/auth/id_rsa_rpki`. Once your key is created you can setup the -connection. - -```{cfgcmd} set protocols rpki cache \ ssh username \ - -SSH username to establish an SSH connection to the cache server. -``` - -```{cfgcmd} set protocols rpki cache \ ssh private-key-file \ - -Local path that includes the private key file of the router. -``` - -```{cfgcmd} set protocols rpki cache \ ssh public-key-file \ - -Local path that includes the public key file of the router. -``` - -:::{note} -When using SSH, private-key-file and public-key-file -are mandatory options. -::: - -## Example - -We can build route-maps for import based on these states. Here is a simple -RPKI configuration, where `routinator` is the RPKI-validating "cache" -server with ip `192.0.2.1`: - -```none -set protocols rpki cache 192.0.2.1 port '3323' -set protocols rpki cache 192.0.2.1 preference '1' -``` - -Here is an example route-map to apply to routes learned at import. In this -filter we reject prefixes with the state `invalid`, and set a higher -`local-preference` if the prefix is RPKI `valid` rather than merely -`notfound`. - -```none -set policy route-map ROUTES-IN rule 10 action 'permit' -set policy route-map ROUTES-IN rule 10 match rpki 'valid' -set policy route-map ROUTES-IN rule 10 set local-preference '300' -set policy route-map ROUTES-IN rule 20 action 'permit' -set policy route-map ROUTES-IN rule 20 match rpki 'notfound' -set policy route-map ROUTES-IN rule 20 set local-preference '125' -set policy route-map ROUTES-IN rule 30 action 'deny' -set policy route-map ROUTES-IN rule 30 match rpki 'invalid' -``` - -Once your routers are configured to reject RPKI-invalid prefixes, you can -test whether the configuration is working correctly using Cloudflare's [test] -website. Keep in mind that in order for this to work, you need to have no -default routes or anything else that would still send traffic to RPKI-invalid -destinations. - -[excellent guide to rpki]: https://rpki.readthedocs.io/ -[help and operational guidance]: https://rpki.readthedocs.io/en/latest/about/help.html -[krill]: https://www.nlnetlabs.nl/projects/rpki/krill/ -[routinator]: https://www.nlnetlabs.nl/projects/rpki/routinator/ -[rpki-client]: https://www.rpki-client.org/ -[software]: https://rpki.readthedocs.io/en/latest/ops/tools.html#relying-party-software -[stayrtr]: https://github.com/bgp/stayrtr/ -[test]: https://isbgpsafeyet.com/ -[tweet by evilmog]: diff --git a/docs/configuration/protocols/md-segment-routing.md b/docs/configuration/protocols/md-segment-routing.md deleted file mode 100644 index 45c89a41..00000000 --- a/docs/configuration/protocols/md-segment-routing.md +++ /dev/null @@ -1,359 +0,0 @@ -(segment-routing)= - -# Segment Routing - -Segment Routing (SR) is a network architecture that is similar to source-routing -. In this architecture, the ingress router adds a list of segments, known as -SIDs, to the packet as it enters the network. These segments represent different -portions of the network path that the packet will take. - -The SR segments are portions of the network path taken by the packet, and are -called SIDs. At each node, the first SID of the list is read, executed as a -forwarding function, and may be popped to let the next node read the next SID of -the list. The SID list completely determines the path where the packet is -forwarded. - -Segment Routing can be applied to an existing MPLS-based data plane and defines -a control plane network architecture. In MPLS networks, segments are encoded as -MPLS labels and are added at the ingress router. These MPLS labels are then -exchanged and populated by Interior Gateway Protocols (IGPs) like IS-IS or OSPF -which are running on most ISPs. - -:::{note} -Segment routing defines a control plane network architecture and -can be applied to an existing MPLS based dataplane. In the MPLS networks, -segments are encoded as MPLS labels and are imposed at the ingress router. -MPLS labels are exchanged and populated by IGPs like IS-IS.Segment Routing -as per RFC8667 for MPLS dataplane. It supports IPv4, IPv6 and ECMP and has -been tested against Cisco & Juniper routers.however,this deployment is still -EXPERIMENTAL for FRR. -::: - -## IS-IS SR Configuration - -Segment routing (SR) is used by the IGP protocols to interconnect network -devices, below configuration shows how to enable SR on IS-IS: - -:::{note} -``Known limitations:`` - -No support for level redistribution (L1 to L2 or L2 to L1) - -No support for binding SID - -No support for SRLB - -Only one SRGB and default SPF Algorithm is supported -::: - -```{cfgcmd} set protocols isis segment-routing global-block high-label-value \ - -Set the Segment Routing Global Block i.e. the label range used by MPLS to -store label in the MPLS FIB for Prefix SID. Note that the block size may -not exceed 65535. -``` - - -```{cfgcmd} set protocols isis segment-routing global-block low-label-value \ - -Set the Segment Routing Global Block i.e. the low label range used by MPLS to -store label in the MPLS FIB for Prefix SID. Note that the block size may -not exceed 65535. -``` - - -```{cfgcmd} set protocols isis segment-routing local-block high-label-value \ - -Set the Segment Routing Local Block i.e. the label range used by MPLS to -store label in the MPLS FIB for Prefix SID. Note that the block size may -not exceed 65535.Segment Routing Local Block, The negative command always -unsets both. -``` - - -```{cfgcmd} set protocols isis segment-routing local-block \ - -Set the Segment Routing Local Block i.e. the low label range used by MPLS to -store label in the MPLS FIB for Prefix SID. Note that the block size may -not exceed 65535.Segment Routing Local Block, The negative command always -unsets both. -``` - - -```{cfgcmd} set protocols isis segment-routing maximum-label-depth \<1-16\> - -Set the Maximum Stack Depth supported by the router. The value depend of -the MPLS dataplane. -``` - - -```{cfgcmd} set protocols isis segment-routing prefix \ index value \<0-65535\> - -A segment ID that contains an IP address prefix calculated by an IGP in the -service provider core network. Prefix SIDs are globally unique, this value -indentify it -``` - - -```{cfgcmd} set protocols isis segment-routing prefix \ index \ - -this option allows to configure prefix-sid on SR. The ‘no-php-flag’ means NO -Penultimate Hop Popping that allows SR node to request to its neighbor to -not pop the label. The ‘explicit-null’ flag allows SR node to request to its -neighbor to send IP packet with the EXPLICIT-NULL label. The ‘n-flag-clear’ -option can be used to explicitly clear the Node flag that is set by default -for Prefix-SIDs associated to loopback addresses. This option is necessary -to configure Anycast-SIDs. -``` - -```{opcmd} show isis segment-routing node - - Show detailed information about all learned Segment Routing Nodes -``` - - -```{opcmd} show isis route prefix-sid - -Show detailed information about prefix-sid and label learned -``` - -:::{note} -more information related IGP - {ref}`routing-isis` -::: - - -## OSPF SR Configuration - - -Segment routing (SR) is used by the IGP protocols to interconnect network -devices, below configuration shows how to enable SR on OSPF: - -```{cfgcmd} set protocols ospf parameters opaque-lsa - -Enable the Opaque-LSA capability (rfc2370), necessary to transport label -on IGP -``` - -```{cfgcmd} set protocols ospf segment-routing global-block high-label-value \ - -Set the Segment Routing Global Block i.e. the label range used by MPLS to -store label in the MPLS FIB for Prefix SID. Note that the block size may -not exceed 65535. -``` - -```{cfgcmd} set protocols ospf segment-routing global-block low-label-value \ - -Set the Segment Routing Global Block i.e. the low label range used by MPLS to -store label in the MPLS FIB for Prefix SID. Note that the block size may -not exceed 65535. -``` - -```{cfgcmd} set protocols ospf segment-routing local-block high-label-value \ - -Set the Segment Routing Local Block i.e. the label range used by MPLS to -store label in the MPLS FIB for Prefix SID. Note that the block size may -not exceed 65535.Segment Routing Local Block, The negative command always -unsets both. -``` - -```{cfgcmd} set protocols ospf segment-routing local-block \ - -Set the Segment Routing Local Block i.e. the low label range used by MPLS to -store label in the MPLS FIB for Prefix SID. Note that the block size may -not exceed 65535.Segment Routing Local Block, The negative command always -unsets both. -``` - -```{cfgcmd} set protocols ospf segment-routing maximum-label-depth \<1-16\> - -Set the Maximum Stack Depth supported by the router. The value depend of -the MPLS dataplane. -``` - -```{cfgcmd} set protocols ospf segment-routing prefix \ index value \<0-65535\> - -A segment ID that contains an IP address prefix calculated by an IGP in the -service provider core network. Prefix SIDs are globally unique, this value -indentify it -``` - -```{cfgcmd} set protocols ospf segment-routing prefix \ index \ - -this option allows to configure prefix-sid on SR. The ‘no-php-flag’ means NO -Penultimate Hop Popping that allows SR node to request to its neighbor to -not pop the label. The ‘explicit-null’ flag allows SR node to request to its -neighbor to send IP packet with the EXPLICIT-NULL label. The ‘n-flag-clear’ -option can be used to explicitly clear the Node flag that is set by default -for Prefix-SIDs associated to loopback addresses. This option is necessary -to configure Anycast-SIDs. -``` - -:::{note} -more information related IGP - {ref}`routing-ospf` -::: - -## Configuration Example - -we described the configuration SR ISIS / SR OSPF using 2 connected with them to -share label information. - -### Enable IS-IS with Segment Routing (Experimental) - -**Node 1:** - -```none -set interfaces loopback lo address '192.168.255.255/32' -set interfaces ethernet eth1 address '192.0.2.1/24' - -set protocols isis interface eth1 -set protocols isis interface lo -set protocols isis net '49.0001.1921.6825.5255.00' -set protocols isis segment-routing global-block high-label-value '599' -set protocols isis segment-routing global-block low-label-value '550' -set protocols isis segment-routing prefix 192.168.255.255/32 index value '1' -set protocols isis segment-routing prefix 192.168.255.255/32 index explicit-null -set protocols mpls interface 'eth1' -``` - -**Node 2:** - -```none -set interfaces loopback lo address '192.168.255.254/32' -set interfaces ethernet eth1 address '192.0.2.2/24' - -set protocols isis interface eth1 -set protocols isis interface lo -set protocols isis net '49.0001.1921.6825.5254.00' -set protocols isis segment-routing global-block high-label-value '599' -set protocols isis segment-routing global-block low-label-value '550' -set protocols isis segment-routing prefix 192.168.255.254/32 index value '2' -set protocols isis segment-routing prefix 192.168.255.254/32 index explicit-null -set protocols mpls interface 'eth1' -``` - -This gives us MPLS segment routing enabled and labels for far end loopbacks: - -```none -Node-1@vyos:~$ show mpls table - Inbound Label Type Nexthop Outbound Label - ---------------------------------------------------------------------- - 552 SR (IS-IS) 192.0.2.2 IPv4 Explicit Null <-- Node-2 loopback learned on Node-1 - 15000 SR (IS-IS) 192.0.2.2 implicit-null - 15001 SR (IS-IS) fe80::e87:6cff:fe09:1 implicit-null - 15002 SR (IS-IS) 192.0.2.2 implicit-null - 15003 SR (IS-IS) fe80::e87:6cff:fe09:1 implicit-null - -Node-2@vyos:~$ show mpls table - Inbound Label Type Nexthop Outbound Label - --------------------------------------------------------------------- - 551 SR (IS-IS) 192.0.2.1 IPv4 Explicit Null <-- Node-1 loopback learned on Node-2 - 15000 SR (IS-IS) 192.0.2.1 implicit-null - 15001 SR (IS-IS) fe80::e33:2ff:fe80:1 implicit-null - 15002 SR (IS-IS) 192.0.2.1 implicit-null - 15003 SR (IS-IS) fe80::e33:2ff:fe80:1 implicit-null -``` - -Here is the routing tables showing the MPLS segment routing label operations: - -```none -Node-1@vyos:~$ show ip route isis -Codes: K - kernel route, C - connected, S - static, R - RIP, - O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, - T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, - f - OpenFabric, - > - selected route, * - FIB route, q - queued, r - rejected, b - backup - t - trapped, o - offload failure - -I 192.0.2.0/24 [115/20] via 192.0.2.2, eth1 inactive, weight 1, 00:07:48 -I>* 192.168.255.254/32 [115/20] via 192.0.2.2, eth1, label IPv4 Explicit Null, weight 1, 00:03:39 - -Node-2@vyos:~$ show ip route isis -Codes: K - kernel route, C - connected, S - static, R - RIP, - O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, - T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, - f - OpenFabric, - > - selected route, * - FIB route, q - queued, r - rejected, b - backup - t - trapped, o - offload failure - -I 192.0.2.0/24 [115/20] via 192.0.2.1, eth1 inactive, weight 1, 00:07:46 -I>* 192.168.255.255/32 [115/20] via 192.0.2.1, eth1, label IPv4 Explicit Null, weight 1, 00:03:43 -``` - - -### Enable OSPF with Segment Routing (Experimental): - -**Node 1** - -```none -set interfaces loopback lo address 10.1.1.1/32 -set interfaces ethernet eth0 address 192.168.0.1/24 -set protocols ospf area 0 network '192.168.0.0/24' -set protocols ospf area 0 network '10.1.1.1/32' -set protocols ospf parameters opaque-lsa -set protocols ospf parameters router-id '10.1.1.1' -set protocols ospf segment-routing global-block high-label-value '1100' -set protocols ospf segment-routing global-block low-label-value '1000' -set protocols ospf segment-routing prefix 10.1.1.1/32 index explicit-null -set protocols ospf segment-routing prefix 10.1.1.1/32 index value '1' -``` - -**Node 2** - -```none -set interfaces loopback lo address 10.1.1.2/32 -set interfaces ethernet eth0 address 192.168.0.2/24 -set protocols ospf area 0 network '192.168.0.0/24' -set protocols ospf area 0 network '10.1.1.2/32' -set protocols ospf parameters opaque-lsa -set protocols ospf parameters router-id '10.1.1.2' -set protocols ospf segment-routing global-block high-label-value '1100' -set protocols ospf segment-routing global-block low-label-value '1000' -set protocols ospf segment-routing prefix 10.1.1.2/32 index explicit-null -set protocols ospf segment-routing prefix 10.1.1.2/32 index value '2' -``` - -This gives us MPLS segment routing enabled and labels for far end loopbacks: - -```none -Node-1@vyos:~$ show mpls table - Inbound Label Type Nexthop Outbound Label - ----------------------------------------------------------- - 1002 SR (OSPF) 192.168.0.2 IPv4 Explicit Null <-- Node-2 loopback learned on Node-1 - 15000 SR (OSPF) 192.168.0.2 implicit-null - 15001 SR (OSPF) 192.168.0.2 implicit-null - -Node-2@vyos:~$ show mpls table - Inbound Label Type Nexthop Outbound Label - ----------------------------------------------------------- - 1001 SR (OSPF) 192.168.0.1 IPv4 Explicit Null <-- Node-1 loopback learned on Node-2 - 15000 SR (OSPF) 192.168.0.1 implicit-null - 15001 SR (OSPF) 192.168.0.1 implicit-null -``` - -Here is the routing tables showing the MPLS segment routing label operations: - -```none -Node-1@vyos:~$ show ip route ospf -Codes: K - kernel route, C - connected, S - static, R - RIP, - O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, - T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, - f - OpenFabric, - > - selected route, * - FIB route, q - queued, r - rejected, b - backup - t - trapped, o - offload failure - -O 10.1.1.1/32 [110/0] is directly connected, lo, weight 1, 00:03:43 -O>* 10.1.1.2/32 [110/1] via 192.168.0.2, eth0, label IPv4 Explicit Null, weight 1, 00:03:32 -O 192.168.0.0/24 [110/1] is directly connected, eth0, weight 1, 00:03:43 - -Node-2@vyos:~$ show ip route ospf -Codes: K - kernel route, C - connected, S - static, R - RIP, - O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, - T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, - f - OpenFabric, - > - selected route, * - FIB route, q - queued, r - rejected, b - backup - t - trapped, o - offload failure - -O>* 10.1.1.1/32 [110/1] via 192.168.0.1, eth0, label IPv4 Explicit Null, weight 1, 00:03:36 -O 10.1.1.2/32 [110/0] is directly connected, lo, weight 1, 00:03:51 -O 192.168.0.0/24 [110/1] is directly connected, eth0, weight 1, 00:03:51 -``` diff --git a/docs/configuration/protocols/md-static.md b/docs/configuration/protocols/md-static.md deleted file mode 100644 index 357f7076..00000000 --- a/docs/configuration/protocols/md-static.md +++ /dev/null @@ -1,298 +0,0 @@ -(routing-static)= - -# Static - -Static routes are manually configured routes, which, in general, cannot be -updated dynamically from information VyOS learns about the network topology from -other routing protocols. However, if a link fails, the router will remove -routes, including static routes, from the {abbr}`RIPB (Routing Information -Base)` that used this interface to reach the next hop. In general, static -routes should only be used for very simple network topologies, or to override -the behavior of a dynamic routing protocol for a small number of routes. The -collection of all routes the router has learned from its configuration or from -its dynamic routing protocols is stored in the RIB. Unicast routes are directly -used to determine the forwarding table used for unicast packet forwarding. - -## IPv4 Unicast Routes - -```{cfgcmd} set protocols static route \ next-hop \ - -Configure next-hop *\* for an IPv4 static route. Multiple static -routes can be created. -``` - -```{cfgcmd} set protocols static route \ next-hop \ disable - -Disable this IPv4 static route entry. -``` - -```{cfgcmd} set protocols static route \ next-hop \ distance \ - -Defines next-hop distance for this route, routes with smaller administrative -distance are elected prior to those with a higher distance. - -Range is 1 to 255, default is 1. - -:::{note} -Routes with a distance of 255 are effectively disabled and not -installed into the kernel. -::: -``` - - -### IPv4 Interface Routes - -```{cfgcmd} set protocols static route \ interface \ - -Allows you to configure the next-hop interface for an interface-based IPv4 -static route. *\* will be the next-hop interface where traffic is -routed for the given *\*. -``` - -```{cfgcmd} set protocols static route \ interface \ disable - -Disables interface-based IPv4 static route. -``` - -```{cfgcmd} set protocols static route \ interface \ distance \ - -Defines next-hop distance for this route, routes with smaller administrative -distance are elected prior to those with a higher distance. - -Range is 1 to 255, default is 1. -``` - - -### IPv4 BFD - -```{cfgcmd} set protocols static route \ next-hop \ bfd - -Configure a static route for *\* using gateway *\* and use the -gateway address as BFD peer destination address. -``` - -```{cfgcmd} set protocols static route \ next-hop \ bfd profile \ - -Configure a static route for *\* using gateway *\* and use the -gateway address as BFD peer destination address with BFD profile *\*. -``` - -```{cfgcmd} set protocols static route \ next-hop \ bfd multi-hop source-address \ - -Configure a static route for *\* using gateway *\* and use the -gateway address as BFD peer destination address with source address -*\* but initiate a multi-hop session. -``` - - -### DHCP Interface Routes - -```{cfgcmd} set protocols static route \ dhcp-interface \ - -Defines route with DHCP interface supplying next-hop IP address. -``` - - -### IPv4 Reject Routes - -```{cfgcmd} set protocol static route \ reject - -Defines route which emits an ICMP unreachable when matched. -``` - -```{cfgcmd} set protocols static route \ reject distance \ - -Defines distance for this route, routes with smaller administrative -distance are elected prior to those with a higher distance. -``` - -```{cfgcmd} set protocols static route \ reject tag \ - -Sets a tag for this route. -``` - -```{cfgcmd} set protocol static route6 \ reject - -Defines route which emits an ICMP unreachable when matched. -``` - - -### IPv4 Blackhole Routes - -```{cfgcmd} set protocols static route \ blackhole - -Use this command to configure a "black-hole" route on the router. A -black-hole route is a route for which the system silently discard packets -that are matched. This prevents networks leaking out public interfaces, but -it does not prevent them from being used as a more specific route inside your -network. -``` - -```{cfgcmd} set protocols static route \ blackhole distance \ - -Defines blackhole distance for this route, routes with smaller administrative -distance are elected prior to those with a higher distance. -``` - -```{cfgcmd} set protocols static route \ blackhole tag \ - -Sets a tag for this route. -``` - - -## IPv6 Unicast Routes - -```{cfgcmd} set protocols static route6 \ next-hop \ - -Configure next-hop *\* for an IPv6 static route. Multiple static -routes can be created. -``` - -```{cfgcmd} set protocols static route6 \ next-hop \ disable - -Disable this IPv6 static route entry. -``` - -```{cfgcmd} set protocols static route6 \ next-hop \ distance \ - -Defines next-hop distance for this route, routes with smaller administrative -distance are elected prior to those with a higher distance. - -Range is 1 to 255, default is 1. - -:::{note} -Routes with a distance of 255 are effectively disabled and not -installed into the kernel. -::: -``` - -```{cfgcmd} set protocols static route6 \ next-hop \ segments \ - -It is possible to specify a static route for ipv6 prefixes using an -SRv6 segments instruction. The ``/`` separator can be used to specify -multiple segment instructions. - -Example: - -:::{code-block} none -set protocols static route6 2001:db8:1000::/36 next-hop 2001:db8:201::ffff segments '2001:db8:aaaa::7/2002::4/2002::3/2002::2' -::: - -:::{code-block} none -vyos@vyos:~$ show ipv6 route -Codes: K - kernel route, C - connected, S - static, R - RIPng, - O - OSPFv3, I - IS-IS, B - BGP, N - NHRP, T - Table, - v - VNC, V - VNC-Direct, A - Babel, F - PBR, - f - OpenFabric, - > - selected route, * - FIB route, q - queued, r - rejected, b - backup - t - trapped, o - offload failure -C>* 2001:db8:201::/64 is directly connected, eth0.201, 00:00:46 -S>* 2001:db8:1000::/36 [1/0] via 2001:db8:201::ffff, eth0.201, seg6 2001:db8:aaaa::7,2002::4,2002::3,2002::2, weight 1, 00:00:08 -::: -``` - - -### IPv6 Interface Routes - -```{cfgcmd} set protocols static route6 \ interface \ - -Allows you to configure the next-hop interface for an interface-based IPv6 -static route. *\* will be the next-hop interface where traffic is -routed for the given *\*. -``` - -```{cfgcmd} set protocols static route6 \ interface \ disable - -Disables interface-based IPv6 static route. -``` - -```{cfgcmd} set protocols static route6 \ interface \ distance \ - -Defines next-hop distance for this route, routes with smaller administrative -distance are elected prior to those with a higher distance. - -Range is 1 to 255, default is 1. -``` - -```{cfgcmd} set protocols static route6 \ interface \ segments \ - -It is possible to specify a static route for ipv6 prefixes using an -SRv6 segments instruction. The ``/`` separator can be used to specify -multiple segment instructions. - -Example: - -:::{code-block} none -set protocols static route6 2001:db8:1000::/36 interface eth0 segments '2001:db8:aaaa::7/2002::4/2002::3/2002::2' -::: -``` - - -### IPv6 BFD - -```{cfgcmd} set protocols static route6 \ next-hop \ bfd - -Configure a static route for *\* using gateway *\* and use the -gateway address as BFD peer destination address. -``` - -```{cfgcmd} set protocols static route6 \ next-hop \ bfd profile \ - -Configure a static route for *\* using gateway *\* and use the -gateway address as BFD peer destination address with BFD profile *\*. -``` - -```{cfgcmd} set protocols static route6 \ next-hop \ bfd multi-hop source-address \ - -Configure a static route for *\* using gateway *\* and use the -gateway address as BFD peer destination address with source address -*\* but initiate a multi-hop session. -``` - - -### IPv6 Reject Routes - -```{cfgcmd} set protocol static route6 \ reject - -Defines route which emits an ICMP unreachable when matched. -``` - -```{cfgcmd} set protocols static route6 \ reject distance \ - -Defines distance for this route, routes with smaller administrative -distance are elected prior to those with a higher distance. -``` - -```{cfgcmd} set protocols static route6 \ reject tag \ - -Sets a tag for this route. -``` - - -### IPv6 Blackhole Routes - -```{cfgcmd} set protocols static route6 \ blackhole - -Use this command to configure a "black-hole" route on the router. A -black-hole route is a route for which the system silently discard packets -that are matched. This prevents networks leaking out public interfaces, but -it does not prevent them from being used as a more specific route inside your -network. -``` - -```{cfgcmd} set protocols static route6 \ blackhole distance \ - -Defines blackhole distance for this route, routes with smaller administrative -distance are elected prior to those with a higher distance. -``` - -```{cfgcmd} set protocols static route6 \ blackhole tag \ - -Sets a tag for this route. -``` - - -## Alternate Routing Tables - -Alternate routing tables are used with policy based routing by utilizing -{ref}`vrf`. diff --git a/docs/configuration/protocols/md-traffic-engineering.md b/docs/configuration/protocols/md-traffic-engineering.md deleted file mode 100644 index 832023a7..00000000 --- a/docs/configuration/protocols/md-traffic-engineering.md +++ /dev/null @@ -1,54 +0,0 @@ -(traffic-engineering)= - -# Traffic Engineering - -Traffic Engineering (TE) is possibility to send traffic from node to node using -alternative path. - -## Common link parameters - -Traffic Engineering parameters are used for both IS-IS and OSPF (not supported yet). - -```{cfgcmd} set protocols traffic-engineering admin-group \ bit-position \ - -Create Administrative group and assosiate bit position with it. These groups can be -used in the following commands. - -\ can have value 0-31. There cannot be two groups with same bit position. -``` - - -```{cfgcmd} set protocols traffic-engineering interface \ admin-group \ - -Set administrative group for interface \. Multiple values can be provided. -``` - - -```{cfgcmd} set protocols traffic-engineering interface \ max-bandwidth \ - -Set maximum bandwidth for interface \. Value given in Mbits per second. -``` - - -```{cfgcmd} set protocols traffic-engineering interface \ max-reservable-bandwidth \ - -Set maximum reservable bandwidth for interface \. Value given in Mbits per second. -``` - -## IS-IS TE Configuration - -Traffic Engineering (TE) can be enabled and exported for IS-IS -using the following commands: - -```{cfgcmd} set protocols isis traffic-engineering enable - -Enable Traffic Engineering for IS-IS. -``` -```{cfgcmd} set protocols isis traffic-engineering export - -Export Traffic Engineering data to neighbors. -``` -```{cfgcmd} set protocols isis traffic-engineering address \ - -Configure IPv4 address for MPLS-TE. -``` \ No newline at end of file diff --git a/docs/configuration/service/md-broadcast-relay.md b/docs/configuration/service/md-broadcast-relay.md deleted file mode 100644 index 4202ad6b..00000000 --- a/docs/configuration/service/md-broadcast-relay.md +++ /dev/null @@ -1,70 +0,0 @@ -(udp-broadcast-relay)= - -# UDP Broadcast Relay - -Certain vendors use broadcasts to identify their equipment within one ethernet -segment. Unfortunately if you split your network with multiple VLANs you loose -the ability of identifying your equipment. - -This is where "UDP broadcast relay" comes into play! It will forward received -broadcasts to other configured networks. - -Every UDP port which will be forward requires one unique ID. Currently we -support 99 IDs! - -## Configuration - -```{cfgcmd} set service broadcast-relay id \ description \ - -A description can be added for each and every unique relay ID. This is -useful to distinguish between multiple different ports/applications. -``` - -```{cfgcmd} set service broadcast-relay id \ interface \ - -The interface used to receive and relay individual broadcast packets. If you -want to receive/relay packets on both `eth1` and `eth2` both interfaces need -to be added. -``` - -```{cfgcmd} set service broadcast-relay id \ address \ - -Set the source IP of forwarded packets, otherwise original senders address -is used. -``` - -```{cfgcmd} set service broadcast-relay id \ port \ - -The UDP port number used by your application. It is mandatory for this kind -of operation. -``` - -```{cfgcmd} set service broadcast-relay id \ disable - -Each broadcast relay instance can be individually disabled without deleting -the configured node by using the following command: -``` - -```{cfgcmd} set service broadcast-relay disable - -In addition you can also disable the whole service without the need to remove -it from the current configuration. -``` - -:::{note} -You can run the UDP broadcast relay service on multiple routers -connected to a subnet. There is **NO** UDP broadcast relay packet storm! -::: - -## Example - -To forward all broadcast packets received on `UDP port 1900` on `eth3`, `eth4` -or `eth5` to all other interfaces in this configuration. - -```none -set service broadcast-relay id 1 description 'SONOS' -set service broadcast-relay id 1 interface 'eth3' -set service broadcast-relay id 1 interface 'eth4' -set service broadcast-relay id 1 interface 'eth5' -set service broadcast-relay id 1 port '1900' -``` diff --git a/docs/configuration/service/md-config-sync.md b/docs/configuration/service/md-config-sync.md deleted file mode 100644 index a575f947..00000000 --- a/docs/configuration/service/md-config-sync.md +++ /dev/null @@ -1,164 +0,0 @@ -(config-sync)= - -# Config Sync - -Configuration synchronization (config sync) is a feature of VyOS that -permits synchronization of the configuration of one VyOS router to -another in a network. - -The main benefit to configuration synchronization is that it eliminates having -to manually replicate configuration changes made on the primary router to the -secondary (replica) router. - -The writing of the configuration to the secondary router is performed through -the VyOS HTTP API. The user can specify which portion(s) of the configuration will -be synchronized and the mode to use - whether to replace or add. - -To prevent issues with divergent configurations between the pair of routers, -synchronization is strictly unidirectional from primary to replica. Both -routers should be online and run the same version of VyOS. - -## Configuration - -```{cfgcmd} set service config-sync secondary \ - -Specify the address, API key, timeout and port of the secondary router. -You need to enable and configure the HTTP API service on the secondary -router for config sync to operate. -``` - -```{cfgcmd} set service config-sync section \ - -Specify the section of the configuration to synchronize. If more than one -section is to be synchronized, repeat the command to add additional -sections as required. -``` - -```{cfgcmd} set service config-sync mode \ - -Two options are available for *mode*: either *load* and replace or *set* -the configuration section. -``` - -```none -Supported options for
include: - firewall - interfaces - nat - nat66 - pki - policy - protocols - qos - service - system - vpn - vrf -``` - - -## Operational Commands - -````{opcmd} show configuration secondary sync [commands] [running | candidate | saved] [\] - -Display configuration differences between the local node and -a config-sync secondary node. - -This command allows operators to compare configurations across nodes -participating in configuration synchronization (e.g., primary and -secondary routers). It helps detect configuration drift and validate -intended changes before synchronization. - -**Parameters:** - -```{eval-rst} -.. list-table:: - :widths: 30 70 - :header-rows: 0 - - * - ``commands`` (optional) - - Show output as a list of configuration commands instead of raw diff. - * - ``running|candidate|saved`` (optional, mutually exclusive) - - Select which configuration to compare: - ``running`` (current active configuration, default), - ``candidate`` (uncommitted changes), or - ``saved`` (last saved configuration). Only one of these may be - specified at a time; if omitted, ``running`` is used. -``` - -**Examples:** - -:::{code-block} none -# compare full running configuration with a secondary node -show configuration secondary sync - -# compare only interface configuration -show configuration secondary sync running interfaces dummy - -# compare candidate configuration and display as a list of commands -show configuration secondary sync commands candidate -::: -```` - -Without a built-in cross-node diff, operators may unintentionally push -changes that conflict with the remote configuration (e.g., mismatched -interfaces, firewall policies, or protocol settings). - - -## Example - -- Synchronize the time-zone and OSPF configuration from Router A to Router B -- The address of Router B is 10.0.20.112 and the port used is 8443 - -Configure the HTTP API service on Router B - -```none -set service https listen-address '10.0.20.112' -set service https port '8443' -set service https api keys id KID key 'foo' -set service https api rest -``` - -Configure the config-sync service on Router A - -```none -set service config-sync mode 'load' -set service config-sync secondary address '10.0.20.112' -set service config-sync secondary port '8443' -set service config-sync secondary key 'foo' -set service config-sync section protocols 'ospf' -set service config-sync section system 'time-zone' -``` - -Make config-sync relevant changes to Router A's configuration - -```none -vyos@vyos-A# set system time-zone 'America/Los_Angeles' -vyos@vyos-A# commit -INFO:vyos_config_sync:Config synchronization: Mode=load, -Secondary=10.0.20.112 -vyos@vyos-A# save - -vyos@vyos-A# set protocols ospf area 0 network '10.0.48.0/30' -vyos@vyos-A# commit -INFO:vyos_config_sync:Config synchronization: Mode=load, -Secondary=10.0.20.112 -yos@vyos-A# save -``` - -Verify configuration changes have been replicated to Router B - -```none -vyos@vyos-B:~$ show configuration commands | match time-zone -set system time-zone 'America/Los_Angeles' - -vyos@vyos-B:~$ show configuration commands | match ospf -set protocols ospf area 0 network '10.0.48.0/30' -``` - - -## Known issues - -Configuration resynchronization. With the current implementation of *service -config-sync*, the secondary node must be online. diff --git a/docs/configuration/service/md-conntrack-sync.md b/docs/configuration/service/md-conntrack-sync.md deleted file mode 100644 index 47a0ae2f..00000000 --- a/docs/configuration/service/md-conntrack-sync.md +++ /dev/null @@ -1,321 +0,0 @@ -(conntrack-sync)= - -# Conntrack Sync - -One of the important features built on top of the Netfilter framework is -connection tracking. Connection tracking allows the kernel to keep track of all -logical network connections or sessions, and thereby relate all of the packets -which may make up that connection. NAT relies on this information to translate -all related packets in the same way, and iptables can use this information to -act as a stateful firewall. - -The connection state however is completely independent of any upper-level -state, such as TCP's or SCTP's state. Part of the reason for this is that when -merely forwarding packets, i.e. no local delivery, the TCP engine may not -necessarily be invoked at all. Even connectionless-mode transmissions such as -UDP, IPsec (AH/ESP), GRE and other tunneling protocols have, at least, a pseudo -connection state. The heuristic for such protocols is often based upon a preset -timeout value for inactivity, after whose expiration a Netfilter connection is -dropped. - -Each Netfilter connection is uniquely identified by a (layer-3 protocol, source -address, destination address, layer-4 protocol, layer-4 key) tuple. The layer-4 -key depends on the transport protocol; for TCP/UDP it is the port numbers, for -tunnels it can be their tunnel ID, but otherwise is just zero, as if it were -not part of the tuple. To be able to inspect the TCP port in all cases, packets -will be mandatorily defragmented. - -It is possible to use either Multicast or Unicast to sync conntrack traffic. -Most examples below show Multicast, but unicast can be specified by using the -"peer" keywork after the specified interface, as in the following example: - -{cfgcmd}`set service conntrack-sync interface eth0 peer 192.168.0.250` - -## Configuration - -```{cfgcmd} set service conntrack-sync accept-protocol - -Accept only certain protocols: You may want to replicate the state of flows -depending on their layer 4 protocol. - -Protocols are: tcp, sctp, dccp, udp, icmp and ipv6-icmp. -``` - - -```{cfgcmd} set service conntrack-sync event-listen-queue-size \ - -The daemon doubles the size of the netlink event socket buffer size if it -detects netlink event message dropping. This clause sets the maximum buffer -size growth that can be reached. - -Queue size for listening to local conntrack events in MB. -``` - - -```{cfgcmd} set service conntrack-sync expect-sync \ - -Protocol for which expect entries need to be synchronized. -``` - - -```{cfgcmd} set service conntrack-sync failover-mechanism vrrp sync-group \ - -Failover mechanism to use for conntrack-sync. - -Only VRRP is supported. Required option. -``` - - -```{cfgcmd} set service conntrack-sync ignore-address \ - -IP addresses or networks for which local conntrack entries will not be synced -``` - - -```{cfgcmd} set service conntrack-sync interface \ - -Interface to use for syncing conntrack entries. -``` - - -```{cfgcmd} set service conntrack-sync interface \ port \ - -Port number used by connection. -``` - - -```{cfgcmd} set service conntrack-sync listen-address \ - -Local IPv4 addresses for service to listen on. -``` - - -```{cfgcmd} set service conntrack-sync mcast-group \ - -Multicast group to use for syncing conntrack entries. - -Defaults to 225.0.0.50. -``` - - -```{cfgcmd} set service conntrack-sync interface \ peer \ - -Peer to send unicast UDP conntrack sync entires to, if not using Multicast -configuration from above above. -``` - - -```{cfgcmd} set service conntrack-sync sync-queue-size \ - -Queue size for syncing conntrack entries in MB. -``` - - -```{cfgcmd} set service conntrack-sync disable-external-cache - -This diable the external cache and directly injects the flow-states into the -in-kernel Connection Tracking System of the backup firewall. -``` - - -```{cfgcmd} set service conntrack-sync purge-timeout \ - -Timeout (in seconds) for purging synchronized entries on handover events. - -On handover, ``conntrackd -t`` is invoked, which schedules a conntrack table -flush after ```` seconds to purge stale (“zombie”) entries and -reduce clashes when multiple handovers occur in a short period. -The default is 60 seconds. -``` - -:::{note} -In VRRP stateful firewall deployments, align VRRP timing with this -behavior: because synchronized conntrack state is purged after the purge -timeout, set **VRRP preempt-delay** to ≥ **purge-timeout** so mastership -can be restored before conntrack state is purged. -::: - -```{cfgcmd} set service conntrack-sync disable-syslog - -Disable connection logging via Syslog. -``` - - -```{cfgcmd} set service conntrack-sync startup-resync - -Order conntrackd to request a complete conntrack table resync against -the other node at startup. -``` - -## Operation - -```{opcmd} show conntrack table ipv4 - -Make sure conntrack is enabled by running and show connection tracking table. - -:::{code-block} none -vyos@vyos:~$ show conntrack table ipv4 -TCP state codes: SS - SYN SENT, SR - SYN RECEIVED, ES - ESTABLISHED, -FW - FIN WAIT, CW - CLOSE WAIT, LA - LAST ACK, -TW - TIME WAIT, CL - CLOSE, LI - LISTEN - -CONN ID Source Destination Protocol TIMEOUT -1015736576 10.35.100.87:58172 172.31.20.12:22 tcp [6] ES 430279 -1006235648 10.35.101.221:57483 172.31.120.21:22 tcp [6] ES 413310 -1006237088 10.100.68.100 172.31.120.21 icmp [1] 29 -1015734848 10.35.100.87:56282 172.31.20.12:22 tcp [6] ES 300 -1015734272 172.31.20.12:60286 239.10.10.14:694 udp [17] 29 -1006239392 10.35.101.221 172.31.120.21 icmp [1] 29 -::: -:::{note} -If the table is empty and you have a warning message, it means -conntrack is not enabled. To enable conntrack, just create a NAT or a firewall -rule. {cfgcmd}`set firewall state-policy established action accept` -::: -``` - - -```{opcmd} show conntrack-sync cache external - -Show connection syncing external cache entries -``` - - -```{opcmd} show conntrack-sync cache internal - -Show connection syncing internal cache entries -``` - - -```{opcmd} show conntrack-sync statistics - -Retrieve current statistics of connection tracking subsystem. - -:::{code-block} none -vyos@vyos:~$ show conntrack-sync statistics -Main Table Statistics: - -cache internal: -current active connections: 19606 -connections created: 6298470 failed: 0 -connections updated: 3786793 failed: 0 -connections destroyed: 6278864 failed: 0 - -cache external: -current active connections: 15771 -connections created: 1660193 failed: 0 -connections updated: 77204 failed: 0 -connections destroyed: 1644422 failed: 0 - -traffic processed: -0 Bytes 0 Pckts - -multicast traffic (active device=eth0.5): -976826240 Bytes sent 212898000 Bytes recv -8302333 Pckts sent 2009929 Pckts recv -0 Error send 0 Error recv - -message tracking: -0 Malformed msgs 263 Lost msgs -::: -``` -```{opcmd} show conntrack-sync status - -Retrieve current status of connection tracking subsystem. - -:::{code-block} none -vyos@vyos:~$ show conntrack-sync status -sync-interface : eth0.5 -failover-mechanism : vrrp [sync-group GEFOEKOM] -last state transition : no transition yet! -ExpectationSync : disabled -::: -``` - -## Example - -The next example is a simple configuration of conntrack-sync. - -:::{figure} /_static/images/service_conntrack_sync-schema.webp -:alt: Conntrack Sync Example -:scale: 60 % -::: - -Now configure conntrack-sync service on `router1` **and** `router2` - -```none -set high-availability vrrp group internal virtual-address ... etc ... -set high-availability vrrp sync-group syncgrp member 'internal' -set service conntrack-sync accept-protocol 'tcp' -set service conntrack-sync accept-protocol 'udp' -set service conntrack-sync accept-protocol 'icmp' -set service conntrack-sync failover-mechanism vrrp sync-group 'syncgrp' -set service conntrack-sync interface 'eth0' -set service conntrack-sync mcast-group '225.0.0.50' -``` - -On the active router, you should have information in the internal-cache of -conntrack-sync. The same current active connections number should be shown in -the external-cache of the standby router - -On active router run: - -```none -$ show conntrack-sync statistics - -Main Table Statistics: - -cache internal: -current active connections: 10 -connections created: 8517 failed: 0 -connections updated: 127 failed: 0 -connections destroyed: 8507 failed: 0 - -cache external: -current active connections: 0 -connections created: 0 failed: 0 -connections updated: 0 failed: 0 -connections destroyed: 0 failed: 0 - -traffic processed: - 0 Bytes 0 Pckts - -multicast traffic (active device=eth0): - 868780 Bytes sent 224136 Bytes recv - 20595 Pckts sent 14034 Pckts recv - 0 Error send 0 Error recv - -message tracking: - 0 Malformed msgs 0 Lost msgs -``` - -On standby router run: - -```none -$ show conntrack-sync statistics - -Main Table Statistics: - -cache internal: -current active connections: 0 -connections created: 0 failed: 0 -connections updated: 0 failed: 0 -connections destroyed: 0 failed: 0 - -cache external: -current active connections: 10 -connections created: 888 failed: 0 -connections updated: 134 failed: 0 -connections destroyed: 878 failed: 0 - -traffic processed: - 0 Bytes 0 Pckts - -multicast traffic (active device=eth0): - 234184 Bytes sent 907504 Bytes recv - 14663 Pckts sent 21495 Pckts recv - 0 Error send 0 Error recv - -message tracking: - 0 Malformed msgs 0 Lost msgs -``` diff --git a/docs/configuration/service/md-console-server.md b/docs/configuration/service/md-console-server.md deleted file mode 100644 index 9402e935..00000000 --- a/docs/configuration/service/md-console-server.md +++ /dev/null @@ -1,139 +0,0 @@ -(console-server)= - -# Console Server - -Starting of with VyOS 1.3 (equuleus) we added support for running VyOS as an -Out-of-Band Management device which provides remote access by means of SSH to -directly attached serial interfaces. - -Serial interfaces can be any interface which is directly connected to the CPU -or chipset (mostly known as a ttyS interface in Linux) or any other USB to -serial converter (Prolific PL2303 or FTDI FT232/FT4232 based chips). - -If you happened to use a Cisco NM-16A - Sixteen Port Async Network Module or -NM-32A - Thirty-two Port Async Network Module - this is your VyOS replacement. - -For USB port information please refor to: {ref}`hardware_usb`. - -## Configuration - -Between computers, the most common configuration used was "8N1": eight bit -characters, with one start bit, one stop bit, and no parity bit. Thus 10 Baud -times are used to send a single character, and so dividing the signalling -bit-rate by ten results in the overall transmission speed in characters per -second. This is also the default setting if none of those options are defined. - -```{cfgcmd} set service console-server device \ data-bits [7 | 8] - -Configure either seven or eight data bits. This defaults to eight data -bits if left unconfigured. -``` - - -```{cfgcmd} set service console-server device \ description \ - -A user friendly description identifying the connected peripheral. -``` - - -```{cfgcmd} set service console-server device \ alias \ - -A user friendly alias for this connection. Can be used instead of the -device name when connecting. -``` - - -```{cfgcmd} set service console-server device \ parity [even | odd | none] - -Set the parity option for the console. If unset this will default to none. -``` - - -```{cfgcmd} set service console-server device \ stop-bits [1 | 2] - -Configure either one or two stop bits. This defaults to one stop bits if -left unconfigured. -``` - - -```{cfgcmd} set service console-server device \ speed [ 300 | 1200 | 2400 | 4800 | 9600 | 19200 | 38400 | 57600 | 115200 ] - -:::{note} -USB to serial converters will handle most of their work in software -so you should be carefull with the selected baudrate as some times they -can't cope with the expected speed. -::: -``` - -### Remote Access - - -Each individual configured console-server device can be directly exposed to -the outside world. A user can directly connect via SSH to the configured -port. - -```{cfgcmd} set service console-server device \ ssh port \ - -Accept SSH connections for the given `` on TCP port ``. -After successfull authentication the user will be directly dropped to -the connected serial device. - -:::{hint} -Multiple users can connect to the same serial device but only -one is allowed to write to the console port. -::: -``` - -## Operation - -```{opcmd} show console-server ports - -Show configured serial ports and their respective interface configuration. - -:::{code-block} none -vyos@vyos:~$ show console-server ports -usb0b2.4p1.0 on /dev/serial/by-bus/usb0b2.4p1.0@ at 9600n -::: -``` - - -```{opcmd} show console-server user - -Show currently connected users. - -:::{code-block} none -vyos@vyos:~$ show console-server user -usb0b2.4p1.0 up vyos@localhost -::: -``` -```{opcmd} connect console \ - -Locally connect to serial port identified by ``. - -:::{code-block} none -vyos@vyos-r1:~$ connect console usb0b2.4p1.0 -[Enter `^Ec?' for help] -[-- MOTD -- VyOS Console Server] - -vyos-r2 login: -::: - -:::{hint} -Multiple users can connect to the same serial device but only -one is allowed to write to the console port. -::: - -:::{hint} -The sequence ``^Ec?`` translates to: ``Ctrl+E c ?``. To quit -the session use: ``Ctrl+E c .`` -::: - -:::{hint} -If ``alias`` is set, it can be used instead of the device when -connecting. -::: -``` -```{opcmd} show log console-server - -Show the console server log. -``` \ No newline at end of file diff --git a/docs/configuration/service/md-dhcp-relay.md b/docs/configuration/service/md-dhcp-relay.md deleted file mode 100644 index a4a10109..00000000 --- a/docs/configuration/service/md-dhcp-relay.md +++ /dev/null @@ -1,205 +0,0 @@ -(dhcp-relay)= - -# DHCP Relay - -If you want your router to forward DHCP requests to an external DHCP server -you can configure the system to act as a DHCP relay agent. The DHCP relay -agent works with IPv4 and IPv6 addresses. - -All interfaces used for the DHCP relay must be configured. This includes the -uplink to the DHCP server. - -## IPv4 relay - -### Configuration - -```{cfgcmd} set service dhcp-relay interface \ - -Interfaces that participate in the DHCP relay process. If this command is -used, at least two entries of it are required: one for the interface that -captures the dhcp-requests, and one for the interface to forward such -requests. A warning message will be shown if this command is used, since -new implementations should use ``listen-interface`` and -``upstream-interface``. -``` - -```{cfgcmd} set service dhcp-relay listen-interface \ - -Interface for DHCP Relay Agent to listen for requests. -``` - -```{cfgcmd} set service dhcp-relay upstream-interface \ - -Interface for DHCP Relay Agent to forward requests out. -``` - -```{cfgcmd} set service dhcp-relay server \ - -Configure IP address of the DHCP `` which will handle the relayed -packets. -``` - -```{cfgcmd} set service dhcp-relay relay-options relay-agents-packets discard - -The router should discard DHCP packages already containing relay agent -information to ensure that only requests from DHCP clients are forwarded. -``` - -```{cfgcmd} set service dhcp-relay disable - -Disable dhcp-relay service. -``` - - -#### Options - -```{cfgcmd} set service dhcp-relay relay-options hop-count \ - -Set the maximum hop `` before packets are discarded. Range 0...255, -default 10. -``` - -```{cfgcmd} set service dhcp-relay relay-options max-size \ - -Set maximum `` of DHCP packets including relay agent information. If a -DHCP packet size surpasses this value it will be forwarded without appending -relay agent information. Range 64...1400, default 576. -``` - -```{cfgcmd} set service dhcp-relay relay-options relay-agents-packets \ - -Four policies for reforwarding DHCP packets exist: -* **append:** The relay agent is allowed to append its own relay information -to a received DHCP packet, disregarding relay information already present -in the packet. -* **discard:** Received packets which already contain relay information will -be discarded. -* **forward:** All packets are forwarded, relay information already present -will be ignored. -* **replace:** Relay information already present in a packet is stripped and -replaced with the router's own relay information set. -``` - - -### Example - -- Listen for DHCP requests on interface `eth1`. -- DHCP server is located at IPv4 address 10.0.1.4 on `eth2`. -- Router receives DHCP client requests on `eth1` and relays them to the - server at 10.0.1.4 on `eth2`. - -:::{figure} /_static/images/service_dhcp-relay01.webp -:alt: DHCP relay example -:scale: 80 % -DHCP relay example -::: - -The generated configuration will look like: - -```none -show service dhcp-relay - listen-interface eth1 - upstream-interface eth2 - server 10.0.1.4 - relay-options { - relay-agents-packets discard - } -``` - -Also, for backwards compatibility this configuration, which uses generic -interface definition, is still valid: - -```none -show service dhcp-relay - interface eth1 - interface eth2 - server 10.0.1.4 - relay-options { - relay-agents-packets discard - } -``` - - -### Operation - -```{opcmd} restart dhcp relay-agent - -Restart DHCP relay service -``` - - -## IPv6 relay - -(dhcp-relay-ipv6-configuration)= - -### Configuration - -```{cfgcmd} set service dhcpv6-relay listen-interface \ - -Set eth1 to be the listening interface for the DHCPv6 relay. - -Multiple interfaces may be specified. -``` - -```{cfgcmd} set service dhcpv6-relay upstream-interface \ address \ - -Specifies an upstream network `` from which replies from -`` and other relay agents will be accepted. -``` - -(dhcp-relay-ipv6-options)= - -```{cfgcmd} set service dhcpv6-relay disable - -Disable dhcpv6-relay service. -``` - -(dhcp-relay-v6-options)= - -#### Options - -```{cfgcmd} set service dhcpv6-relay max-hop-count \ - -Set maximum hop count before packets are discarded, default: 10 -``` - -```{cfgcmd} set service dhcpv6-relay use-interface-id-option - -If this is set the relay agent will insert the interface ID. This option is -set automatically if more than one listening interfaces are in use. -``` - -(dhcp-relay-ipv6-example)= - -### Example - -- DHCPv6 requests are received by the router on `listening interface` `eth1` -- Requests are forwarded through `eth2` as the `upstream interface` -- External DHCPv6 server is at 2001:db8::4 - -:::{figure} /_static/images/service_dhcpv6-relay01.webp -:alt: DHCPv6 relay example -:scale: 80 % -DHCPv6 relay example -::: - -The generated configuration will look like: - -```none -commit -show service dhcpv6-relay - listen-interface eth1 { - } - upstream-interface eth2 { - address 2001:db8::4 - } -``` - -(dhcp-relay-ipv6-op-cmd)= - -### Operation - -```{opcmd} restart dhcpv6 relay-agent - -Restart DHCPv6 relay agent immediately. -``` \ No newline at end of file diff --git a/docs/configuration/service/md-dhcp-server.md b/docs/configuration/service/md-dhcp-server.md deleted file mode 100644 index 96c375da..00000000 --- a/docs/configuration/service/md-dhcp-server.md +++ /dev/null @@ -1,1178 +0,0 @@ -(dhcp-server)= - -# DHCP Server - -VyOS uses Kea DHCP server for both IPv4 and IPv6 address assignment. - -## IPv4 server - -The network topology is declared by shared-network-name and the subnet -declarations. The DHCP service can serve multiple shared networks, with each -shared network having 1 or more subnets. Each subnet must be present on an -interface. A range can be declared inside a subnet to define a pool of dynamic -addresses. Multiple ranges can be defined and can contain holes. Static -mappings can be set to assign "static" addresses to clients based on their MAC -address. - -### Configuration - -```{cfgcmd} set service dhcp-server hostfile-update - - Create DNS record per client lease, by adding clients to /etc/hosts file. - Entry will have format: `_.` -``` - - -```{cfgcmd} set service dhcp-server shared-network-name \ option domain-name \ - -The domain-name parameter should be the domain name that will be appended to -the client's hostname to form a fully-qualified domain-name (FQDN) (DHCP -Option 015). - -This is the configuration parameter for the entire shared network definition. -All subnets will inherit this configuration item if not specified locally. -``` - - -```{cfgcmd} set service dhcp-server shared-network-name \ option domain-search \ - -The domain-name parameter should be the domain name used when completing DNS -request where no full FQDN is passed. This option can be given multiple times -if you need multiple search domains (DHCP Option 119). - -This is the configuration parameter for the entire shared network definition. -All subnets will inherit this configuration item if not specified locally. -``` - - -```{cfgcmd} set service dhcp-server shared-network-name \ option name-server \ - -Inform client that the DNS server can be found at `
`. - -This is the configuration parameter for the entire shared network definition. -All subnets will inherit this configuration item if not specified locally. -Multiple DNS servers can be defined. -``` - - -```{cfgcmd} set service dhcp-server shared-network-name \ option vendor-option \ - -This configuration parameter lets you specify a vendor-option for the -entire shared network definition. All subnets will inherit this -configuration item if not specified locally. An example for Ubiquiti is -shown below: -``` - -**Example:** - - -Pass address of Unifi controller at `172.16.100.1` to all clients of `NET1` - -```none -set service dhcp-server shared-network-name 'NET1' option vendor-option -ubiquiti '172.16.100.1' -``` - - -```{cfgcmd} set service dhcp-server listen-address \ - -This configuration parameter lets the DHCP server to listen for DHCP -requests sent to the specified address, it is only realistically useful for -a server whose only clients are reached via unicasts, such as via DHCP relay -agents. -``` - -#### Individual Client Subnet - -```{cfgcmd} set service dhcp-server shared-network-name \ authoritative - -This says that this device is the only DHCP server for this network. If other -devices are trying to offer DHCP leases, this machine will send 'DHCPNAK' to -any device trying to request an IP address that is not valid for this -network. -``` - - -```{cfgcmd} set service dhcp-server shared-network-name \ subnet \ subnet-id \ - -This configuration parameter is required and must be unique to each subnet. -It is required to map subnets to lease file entries. -``` - - -```{cfgcmd} set service dhcp-server shared-network-name \ subnet \ option default-router \ - -This is a configuration parameter for the ``, saying that as part of -the response, tell the client that the default gateway can be reached at -`
`. -``` - - -```{cfgcmd} set service dhcp-server shared-network-name \ subnet \ option name-server \ - -This is a configuration parameter for the subnet, saying that as part of the -response, tell the client that the DNS server can be found at `
`. - -Multiple DNS servers can be defined. -``` - - -```{cfgcmd} set service dhcp-server shared-network-name \ subnet \ lease \ - -Assign the IP address to this machine for `