From b61087c396860bb507be1adea50244a8c8e3242c Mon Sep 17 00:00:00 2001 From: Yuriy Andamasov Date: Wed, 6 May 2026 17:47:58 +0300 Subject: feat: import MyST swap mechanism, llms.txt feature, and content from current Replaces the broken #1885/#1869/#1875 trio with a single PR for circinus. This PR: - Imports 254 md-*.md files from currents working MyST conversion (the broken converter that produced #1885s md-*.md files is not used here; currents files are correct as verified on /en/rolling/). - Adds the per-page RST-to-MyST swap mechanism: scripts/swap_sources.py, scripts/import_myst.py, tests, _swap.txt, _ext/vyos.py and Makefile swap-wrapped targets, .readthedocs.yml pre/post hooks. - Replaces 175 .jpg/.png with 187 .webp images for swapped pages. - Adds the llms.txt + sitemap feature (sphinx_llms_txt, sphinx_sitemap) with circinus-tailored html_baseurl https://docs.vyos.io/en/1.5/ and curated docs/_html_extra/llms.txt for 1.5.x. - Updates docs/_html_extra/robots.txt with AI crawler Allow rules and the /en/1.5/sitemap.xml reference. - Drops configuration/service/suricata from the swap set (no matching RST sibling on circinus; suricata is a current-only feature). Supersedes: - #1885 (broken md-*.md converter output) - #1869 (LLM doc adaptation backport, bundled here) - #1875 (llms.txt circinus, bundled here) Generated by robots https://vyos.io --- docs/Makefile | 42 +- docs/_ext/vyos.py | 14 +- docs/_html_extra/llms.txt | 52 + docs/_html_extra/robots.txt | 39 +- .../css/DataTables-1.11.5/images/sort_asc.webp | Bin 0 -> 200 bytes .../images/sort_asc_disabled.webp | Bin 0 -> 174 bytes .../css/DataTables-1.11.5/images/sort_both.webp | Bin 0 -> 204 bytes .../css/DataTables-1.11.5/images/sort_desc.webp | Bin 0 -> 206 bytes .../images/sort_desc_disabled.webp | Bin 0 -> 162 bytes docs/_static/images/1u_vyos_back.jpg | Bin 586620 -> 0 bytes docs/_static/images/1u_vyos_back.webp | Bin 0 -> 274242 bytes docs/_static/images/1u_vyos_front.jpg | Bin 363840 -> 0 bytes docs/_static/images/1u_vyos_front.webp | Bin 0 -> 179238 bytes docs/_static/images/1u_vyos_front_10ge_open_1.jpg | Bin 1853769 -> 0 bytes docs/_static/images/1u_vyos_front_10ge_open_1.webp | Bin 0 -> 753068 bytes docs/_static/images/1u_vyos_front_10ge_open_2.jpg | Bin 2294504 -> 0 bytes docs/_static/images/1u_vyos_front_10ge_open_2.webp | Bin 0 -> 927384 bytes docs/_static/images/1u_vyos_front_10ge_open_3.jpg | Bin 2067314 -> 0 bytes docs/_static/images/1u_vyos_front_10ge_open_3.webp | Bin 0 -> 728730 bytes docs/_static/images/1u_vyos_front_10ge_open_4.jpg | Bin 2447196 -> 0 bytes docs/_static/images/1u_vyos_front_10ge_open_4.webp | Bin 0 -> 1029796 bytes docs/_static/images/1u_vyos_front_open_1.jpg | Bin 956435 -> 0 bytes docs/_static/images/1u_vyos_front_open_1.webp | Bin 0 -> 609946 bytes docs/_static/images/1u_vyos_front_open_2.jpg | Bin 1225208 -> 0 bytes docs/_static/images/1u_vyos_front_open_2.webp | Bin 0 -> 816692 bytes docs/_static/images/1u_vyos_front_open_3.jpg | Bin 1337822 -> 0 bytes docs/_static/images/1u_vyos_front_open_3.webp | Bin 0 -> 865004 bytes .../images/480px-Acrosser_ANDJ190N1_Back.jpg | Bin 11340 -> 0 bytes .../images/480px-Acrosser_ANDJ190N1_Back.webp | Bin 0 -> 7182 bytes .../images/480px-Acrosser_ANDJ190N1_Front.jpg | Bin 11138 -> 0 bytes .../images/480px-Acrosser_ANDJ190N1_Front.webp | Bin 0 -> 7064 bytes docs/_static/images/600px-Partaker-i5.jpg | Bin 31015 -> 0 bytes docs/_static/images/600px-Partaker-i5.webp | Bin 0 -> 22500 bytes docs/_static/images/ESP_AH.png | Bin 35607 -> 0 bytes docs/_static/images/ESP_AH.webp | Bin 0 -> 22368 bytes .../_static/images/IPSec_close_action_settings.png | Bin 22371 -> 0 bytes .../images/IPSec_close_action_settings.webp | Bin 0 -> 16040 bytes docs/_static/images/L3VPN_hub_and_spoke.png | Bin 134458 -> 0 bytes docs/_static/images/L3VPN_hub_and_spoke.webp | Bin 0 -> 49718 bytes docs/_static/images/PA-ESP-group.png | Bin 27516 -> 0 bytes docs/_static/images/PA-ESP-group.webp | Bin 0 -> 11374 bytes docs/_static/images/PA-IKE-GW-1.png | Bin 31121 -> 0 bytes docs/_static/images/PA-IKE-GW-1.webp | Bin 0 -> 13074 bytes docs/_static/images/PA-IKE-GW-2.png | Bin 19848 -> 0 bytes docs/_static/images/PA-IKE-GW-2.webp | Bin 0 -> 8956 bytes docs/_static/images/PA-IKE-group.png | Bin 26998 -> 0 bytes docs/_static/images/PA-IKE-group.webp | Bin 0 -> 12356 bytes docs/_static/images/PA-IPsec-tunnel.png | Bin 33519 -> 0 bytes docs/_static/images/PA-IPsec-tunnel.webp | Bin 0 -> 13830 bytes docs/_static/images/PA-tunnel-1.png | Bin 16308 -> 0 bytes docs/_static/images/PA-tunnel-1.webp | Bin 0 -> 6454 bytes docs/_static/images/PA-tunnel-2.png | Bin 18290 -> 0 bytes docs/_static/images/PA-tunnel-2.webp | Bin 0 -> 7788 bytes docs/_static/images/PA-tunnel-3.png | Bin 15779 -> 0 bytes docs/_static/images/PA-tunnel-3.webp | Bin 0 -> 6096 bytes docs/_static/images/VyOS_Dual-Hub_DMVPN.png | Bin 67747 -> 0 bytes docs/_static/images/VyOS_Dual-Hub_DMVPN.webp | Bin 0 -> 38696 bytes docs/_static/images/Wan_load_balancing1.png | Bin 373848 -> 0 bytes docs/_static/images/Wan_load_balancing1.webp | Bin 0 -> 80134 bytes .../_static/images/Wan_load_balancing_exclude1.png | Bin 382563 -> 0 bytes .../images/Wan_load_balancing_exclude1.webp | Bin 0 -> 81692 bytes docs/_static/images/ansible.png | Bin 204124 -> 0 bytes docs/_static/images/ansible.webp | Bin 0 -> 35842 bytes docs/_static/images/apu4_desk_1.jpg | Bin 816206 -> 0 bytes docs/_static/images/apu4_desk_1.webp | Bin 0 -> 188746 bytes docs/_static/images/apu4_desk_2.jpg | Bin 288989 -> 0 bytes docs/_static/images/apu4_desk_2.webp | Bin 0 -> 101176 bytes docs/_static/images/apu4_desk_3.jpg | Bin 831843 -> 0 bytes docs/_static/images/apu4_desk_3.webp | Bin 0 -> 506950 bytes docs/_static/images/apu4_desk_4.jpg | Bin 804070 -> 0 bytes docs/_static/images/apu4_desk_4.webp | Bin 0 -> 502830 bytes docs/_static/images/apu4_rack_1.jpg | Bin 305789 -> 0 bytes docs/_static/images/apu4_rack_1.webp | Bin 0 -> 163172 bytes docs/_static/images/apu4_rack_2.jpg | Bin 623490 -> 0 bytes docs/_static/images/apu4_rack_2.webp | Bin 0 -> 383592 bytes docs/_static/images/apu4_rack_3.jpg | Bin 1113842 -> 0 bytes docs/_static/images/apu4_rack_3.webp | Bin 0 -> 704064 bytes docs/_static/images/apu4_rack_4.jpg | Bin 1676612 -> 0 bytes docs/_static/images/apu4_rack_4.webp | Bin 0 -> 1176470 bytes docs/_static/images/apu4_rack_5.jpg | Bin 1584027 -> 0 bytes docs/_static/images/apu4_rack_5.webp | Bin 0 -> 948240 bytes docs/_static/images/apu4_rack_vyos_print.jpg | Bin 569311 -> 0 bytes docs/_static/images/apu4_rack_vyos_print.webp | Bin 0 -> 354582 bytes docs/_static/images/aws.png | Bin 150759 -> 0 bytes docs/_static/images/aws.webp | Bin 0 -> 22146 bytes docs/_static/images/blueprint-dmvpn.png | Bin 29626 -> 0 bytes docs/_static/images/blueprint-dmvpn.webp | Bin 0 -> 20178 bytes docs/_static/images/boot-options.png | Bin 30582 -> 0 bytes docs/_static/images/boot-options.webp | Bin 0 -> 24560 bytes docs/_static/images/cisco-vpn-ipsec.png | Bin 38659 -> 0 bytes docs/_static/images/cisco-vpn-ipsec.webp | Bin 0 -> 17008 bytes docs/_static/images/cloud-aws-01.png | Bin 54783 -> 0 bytes docs/_static/images/cloud-aws-01.webp | Bin 0 -> 17216 bytes docs/_static/images/cloud-aws-02.png | Bin 88657 -> 0 bytes docs/_static/images/cloud-aws-02.webp | Bin 0 -> 31212 bytes docs/_static/images/cloud-aws-03.png | Bin 48191 -> 0 bytes docs/_static/images/cloud-aws-03.webp | Bin 0 -> 17688 bytes docs/_static/images/cloud-aws-04.png | Bin 131948 -> 0 bytes docs/_static/images/cloud-aws-04.webp | Bin 0 -> 47288 bytes docs/_static/images/cloud-aws-05.png | Bin 103661 -> 0 bytes docs/_static/images/cloud-aws-05.webp | Bin 0 -> 40486 bytes docs/_static/images/cloud-aws-06.png | Bin 111207 -> 0 bytes docs/_static/images/cloud-aws-06.webp | Bin 0 -> 45608 bytes docs/_static/images/cloud-aws-07.png | Bin 72764 -> 0 bytes docs/_static/images/cloud-aws-07.webp | Bin 0 -> 29012 bytes docs/_static/images/cloud-aws-08.png | Bin 20893 -> 0 bytes docs/_static/images/cloud-aws-08.webp | Bin 0 -> 7400 bytes docs/_static/images/cloud-azure-01.png | Bin 90521 -> 0 bytes docs/_static/images/cloud-azure-01.webp | Bin 0 -> 34472 bytes docs/_static/images/cloud-azure-02.png | Bin 56507 -> 0 bytes docs/_static/images/cloud-azure-02.webp | Bin 0 -> 20216 bytes docs/_static/images/cloud-azure-03.png | Bin 47364 -> 0 bytes docs/_static/images/cloud-azure-03.webp | Bin 0 -> 17942 bytes docs/_static/images/cloud-azure-04.png | Bin 87475 -> 0 bytes docs/_static/images/cloud-azure-04.webp | Bin 0 -> 34348 bytes docs/_static/images/cloud-azure-05.png | Bin 77301 -> 0 bytes docs/_static/images/cloud-azure-05.webp | Bin 0 -> 26358 bytes docs/_static/images/cloud-azure-06.png | Bin 57830 -> 0 bytes docs/_static/images/cloud-azure-06.webp | Bin 0 -> 18790 bytes docs/_static/images/cloud-gcp-01.png | Bin 5526 -> 0 bytes docs/_static/images/cloud-gcp-01.webp | Bin 0 -> 1900 bytes docs/_static/images/cloud-gcp-02.png | Bin 46685 -> 0 bytes docs/_static/images/cloud-gcp-02.webp | Bin 0 -> 19684 bytes docs/_static/images/cloud-gcp-03.png | Bin 106217 -> 0 bytes docs/_static/images/cloud-gcp-03.webp | Bin 0 -> 39188 bytes docs/_static/images/cloud-gcp-04.png | Bin 19727 -> 0 bytes docs/_static/images/cloud-gcp-04.webp | Bin 0 -> 6756 bytes docs/_static/images/cloud-gcp-05.png | Bin 26049 -> 0 bytes docs/_static/images/cloud-gcp-05.webp | Bin 0 -> 9378 bytes .../images/dhcp-relay-through-gre-bridge.png | Bin 31261 -> 0 bytes .../images/dhcp-relay-through-gre-bridge.webp | Bin 0 -> 12810 bytes docs/_static/images/dual-hub-DMVPN.png | Bin 88497 -> 0 bytes docs/_static/images/dual-hub-DMVPN.webp | Bin 0 -> 36020 bytes docs/_static/images/eve-ng-vyos.png | Bin 4228 -> 0 bytes docs/_static/images/eve-ng-vyos.webp | Bin 0 -> 956 bytes .../_static/images/firewall-and-vrf-blueprints.png | Bin 84270 -> 0 bytes .../images/firewall-and-vrf-blueprints.webp | Bin 0 -> 28402 bytes docs/_static/images/firewall-bridge-forward.png | Bin 26359 -> 0 bytes docs/_static/images/firewall-bridge-forward.webp | Bin 0 -> 8986 bytes docs/_static/images/firewall-bridge-input.png | Bin 39158 -> 0 bytes docs/_static/images/firewall-bridge-input.webp | Bin 0 -> 13910 bytes docs/_static/images/firewall-bridge-output.png | Bin 34496 -> 0 bytes docs/_static/images/firewall-bridge-output.webp | Bin 0 -> 12086 bytes .../images/firewall-flowtable-packet-flow.png | Bin 47883 -> 0 bytes .../images/firewall-flowtable-packet-flow.webp | Bin 0 -> 15128 bytes docs/_static/images/firewall-fwd-packet-flow.png | Bin 30593 -> 0 bytes docs/_static/images/firewall-fwd-packet-flow.webp | Bin 0 -> 10202 bytes docs/_static/images/firewall-gral-packet-flow.png | Bin 49632 -> 0 bytes docs/_static/images/firewall-gral-packet-flow.webp | Bin 0 -> 18066 bytes docs/_static/images/firewall-input-packet-flow.png | Bin 43944 -> 0 bytes .../_static/images/firewall-input-packet-flow.webp | Bin 0 -> 13918 bytes docs/_static/images/firewall-netfilter.png | Bin 73608 -> 0 bytes docs/_static/images/firewall-netfilter.webp | Bin 0 -> 10638 bytes docs/_static/images/firewall-traditional.png | Bin 53437 -> 0 bytes docs/_static/images/firewall-traditional.webp | Bin 0 -> 4404 bytes docs/_static/images/firewall-zonebased.png | Bin 55621 -> 0 bytes docs/_static/images/firewall-zonebased.webp | Bin 0 -> 6012 bytes docs/_static/images/gns3-01.png | Bin 28912 -> 0 bytes docs/_static/images/gns3-01.webp | Bin 0 -> 10250 bytes docs/_static/images/gns3-02.png | Bin 179730 -> 0 bytes docs/_static/images/gns3-02.webp | Bin 0 -> 67826 bytes docs/_static/images/gns3-03.png | Bin 22829 -> 0 bytes docs/_static/images/gns3-03.webp | Bin 0 -> 7798 bytes docs/_static/images/gns3-04.png | Bin 35150 -> 0 bytes docs/_static/images/gns3-04.webp | Bin 0 -> 12946 bytes docs/_static/images/gns3-05.png | Bin 31728 -> 0 bytes docs/_static/images/gns3-05.webp | Bin 0 -> 12544 bytes docs/_static/images/gns3-06.png | Bin 29168 -> 0 bytes docs/_static/images/gns3-06.webp | Bin 0 -> 9376 bytes docs/_static/images/gns3-07.png | Bin 31199 -> 0 bytes docs/_static/images/gns3-07.webp | Bin 0 -> 9940 bytes docs/_static/images/gns3-08.png | Bin 29636 -> 0 bytes docs/_static/images/gns3-08.webp | Bin 0 -> 9724 bytes docs/_static/images/gns3-09.png | Bin 21881 -> 0 bytes docs/_static/images/gns3-09.webp | Bin 0 -> 7428 bytes docs/_static/images/gns3-10.png | Bin 30788 -> 0 bytes docs/_static/images/gns3-10.webp | Bin 0 -> 10530 bytes docs/_static/images/gns3-11.png | Bin 168937 -> 0 bytes docs/_static/images/gns3-11.webp | Bin 0 -> 63708 bytes docs/_static/images/gns3-12.png | Bin 58597 -> 0 bytes docs/_static/images/gns3-12.webp | Bin 0 -> 21712 bytes docs/_static/images/gns3-13.png | Bin 56994 -> 0 bytes docs/_static/images/gns3-13.webp | Bin 0 -> 18354 bytes docs/_static/images/gns3-14.png | Bin 28821 -> 0 bytes docs/_static/images/gns3-14.webp | Bin 0 -> 9784 bytes docs/_static/images/gns3-15.png | Bin 45453 -> 0 bytes docs/_static/images/gns3-15.webp | Bin 0 -> 16520 bytes docs/_static/images/gns3-16.png | Bin 54790 -> 0 bytes docs/_static/images/gns3-16.webp | Bin 0 -> 17928 bytes docs/_static/images/gns3-17.png | Bin 169380 -> 0 bytes docs/_static/images/gns3-17.webp | Bin 0 -> 62974 bytes docs/_static/images/gns3-20.png | Bin 55168 -> 0 bytes docs/_static/images/gns3-20.webp | Bin 0 -> 19712 bytes docs/_static/images/gns3-21.png | Bin 25663 -> 0 bytes docs/_static/images/gns3-21.webp | Bin 0 -> 7950 bytes docs/_static/images/gns3-215.png | Bin 44485 -> 0 bytes docs/_static/images/gns3-215.webp | Bin 0 -> 16012 bytes docs/_static/images/gns3-22.png | Bin 54674 -> 0 bytes docs/_static/images/gns3-22.webp | Bin 0 -> 17222 bytes docs/_static/images/gowin-01.png | Bin 355723 -> 0 bytes docs/_static/images/gowin-01.webp | Bin 0 -> 24732 bytes docs/_static/images/gowin-02.png | Bin 2613833 -> 0 bytes docs/_static/images/gowin-02.webp | Bin 0 -> 224350 bytes docs/_static/images/gowin-03.png | Bin 2268530 -> 0 bytes docs/_static/images/gowin-03.webp | Bin 0 -> 255730 bytes docs/_static/images/gowin-04.png | Bin 2165023 -> 0 bytes docs/_static/images/gowin-04.webp | Bin 0 -> 223808 bytes docs/_static/images/inter-vrf-routing-vrf-lite.png | Bin 104622 -> 0 bytes .../_static/images/inter-vrf-routing-vrf-lite.webp | Bin 0 -> 36860 bytes docs/_static/images/ipsec-vyos-pa.png | Bin 61250 -> 0 bytes docs/_static/images/ipsec-vyos-pa.webp | Bin 0 -> 22972 bytes docs/_static/images/json.png | Bin 26585 -> 0 bytes docs/_static/images/json.webp | Bin 0 -> 34856 bytes docs/_static/images/key.png | Bin 165894 -> 0 bytes docs/_static/images/key.webp | Bin 0 -> 88726 bytes docs/_static/images/keypairs.png | Bin 49718 -> 0 bytes docs/_static/images/keypairs.webp | Bin 0 -> 28220 bytes docs/_static/images/lac-lns-diagram.jpg | Bin 35665 -> 0 bytes docs/_static/images/lac-lns-diagram.webp | Bin 0 -> 11148 bytes docs/_static/images/lac-lns-winclient.jpg | Bin 90842 -> 0 bytes docs/_static/images/lac-lns-winclient.webp | Bin 0 -> 20246 bytes docs/_static/images/ldapone.png | Bin 88753 -> 0 bytes docs/_static/images/ldapone.webp | Bin 0 -> 51782 bytes docs/_static/images/ldaptwo.png | Bin 58322 -> 0 bytes docs/_static/images/ldaptwo.webp | Bin 0 -> 34450 bytes docs/_static/images/mainschema.png | Bin 78790 -> 0 bytes docs/_static/images/mainschema.webp | Bin 0 -> 25286 bytes docs/_static/images/multicast-basic.png | Bin 43708 -> 0 bytes docs/_static/images/multicast-basic.webp | Bin 0 -> 15932 bytes docs/_static/images/nat_before_vpn_topology.png | Bin 19015 -> 0 bytes docs/_static/images/nat_before_vpn_topology.webp | Bin 0 -> 16422 bytes docs/_static/images/nmp1.png | Bin 128546 -> 0 bytes docs/_static/images/nmp1.webp | Bin 0 -> 30280 bytes docs/_static/images/nmp2.png | Bin 52507 -> 0 bytes docs/_static/images/nmp2.webp | Bin 0 -> 23324 bytes docs/_static/images/nmp3.png | Bin 107595 -> 0 bytes docs/_static/images/nmp3.webp | Bin 0 -> 60334 bytes docs/_static/images/nmp4.png | Bin 72678 -> 0 bytes docs/_static/images/nmp4.webp | Bin 0 -> 40784 bytes docs/_static/images/nmp5.png | Bin 115299 -> 0 bytes docs/_static/images/nmp5.webp | Bin 0 -> 63412 bytes docs/_static/images/nmp6.png | Bin 130524 -> 0 bytes docs/_static/images/nmp6.webp | Bin 0 -> 73202 bytes docs/_static/images/nmp7.png | Bin 100135 -> 0 bytes docs/_static/images/nmp7.webp | Bin 0 -> 35884 bytes docs/_static/images/openvpn_site2site_diagram.jpg | Bin 24179 -> 0 bytes docs/_static/images/openvpn_site2site_diagram.webp | Bin 0 -> 9624 bytes docs/_static/images/pbr_example_1.png | Bin 39170 -> 0 bytes docs/_static/images/pbr_example_1.webp | Bin 0 -> 17460 bytes .../images/policy-based-ipsec-and-firewall.png | Bin 42987 -> 0 bytes .../images/policy-based-ipsec-and-firewall.webp | Bin 0 -> 25992 bytes docs/_static/images/pppoe-ipv6-pd-diagram.jpg | Bin 19993 -> 0 bytes docs/_static/images/pppoe-ipv6-pd-diagram.webp | Bin 0 -> 5368 bytes docs/_static/images/project.png | Bin 18173 -> 0 bytes docs/_static/images/project.webp | Bin 0 -> 8396 bytes docs/_static/images/qos1.png | Bin 135527 -> 0 bytes docs/_static/images/qos1.webp | Bin 0 -> 71136 bytes docs/_static/images/qos10.png | Bin 119669 -> 0 bytes docs/_static/images/qos10.webp | Bin 0 -> 187728 bytes docs/_static/images/qos2.png | Bin 140834 -> 0 bytes docs/_static/images/qos2.webp | Bin 0 -> 74934 bytes docs/_static/images/qos3.png | Bin 16699 -> 0 bytes docs/_static/images/qos3.webp | Bin 0 -> 30634 bytes docs/_static/images/qos4.png | Bin 17273 -> 0 bytes docs/_static/images/qos4.webp | Bin 0 -> 30498 bytes docs/_static/images/qos5.png | Bin 15868 -> 0 bytes docs/_static/images/qos5.webp | Bin 0 -> 8820 bytes docs/_static/images/qos6.png | Bin 139244 -> 0 bytes docs/_static/images/qos6.webp | Bin 0 -> 80314 bytes docs/_static/images/qos7.png | Bin 17775 -> 0 bytes docs/_static/images/qos7.webp | Bin 0 -> 32416 bytes docs/_static/images/qos8.png | Bin 17368 -> 0 bytes docs/_static/images/qos8.webp | Bin 0 -> 32812 bytes docs/_static/images/qos9.png | Bin 17065 -> 0 bytes docs/_static/images/qos9.webp | Bin 0 -> 30238 bytes docs/_static/images/reset-password-step-1.jpg | Bin 37351 -> 0 bytes docs/_static/images/reset-password-step-1.webp | Bin 0 -> 11746 bytes docs/_static/images/reset-password-step-2.jpg | Bin 42278 -> 0 bytes docs/_static/images/reset-password-step-2.webp | Bin 0 -> 13622 bytes docs/_static/images/reset-password-step-3.jpg | Bin 36932 -> 0 bytes docs/_static/images/reset-password-step-3.webp | Bin 0 -> 11670 bytes docs/_static/images/reset-password-step-4.jpg | Bin 31564 -> 0 bytes docs/_static/images/reset-password-step-4.webp | Bin 0 -> 10236 bytes docs/_static/images/reset-password-step-5.jpg | Bin 100973 -> 0 bytes docs/_static/images/reset-password-step-5.webp | Bin 0 -> 51232 bytes docs/_static/images/service.png | Bin 195145 -> 0 bytes docs/_static/images/service.webp | Bin 0 -> 83530 bytes .../images/service_conntrack_sync-schema.png | Bin 56954 -> 0 bytes .../images/service_conntrack_sync-schema.webp | Bin 0 -> 16600 bytes docs/_static/images/service_dhcp-relay01.png | Bin 153617 -> 0 bytes docs/_static/images/service_dhcp-relay01.webp | Bin 0 -> 27266 bytes docs/_static/images/service_dhcpv6-relay01.png | Bin 150157 -> 0 bytes docs/_static/images/service_dhcpv6-relay01.webp | Bin 0 -> 25882 bytes ...rvice_snmp_communication_principles_diagram.png | Bin 56582 -> 0 bytes ...vice_snmp_communication_principles_diagram.webp | Bin 0 -> 53888 bytes docs/_static/images/sg.png | Bin 31817 -> 0 bytes docs/_static/images/sg.webp | Bin 0 -> 19282 bytes docs/_static/images/sticky-connections.jpg | Bin 22252 -> 0 bytes docs/_static/images/sticky-connections.webp | Bin 0 -> 12094 bytes docs/_static/images/traffic.png | Bin 36786 -> 0 bytes docs/_static/images/traffic.webp | Bin 0 -> 21794 bytes docs/_static/images/uefi_secureboot_01.png | Bin 60527 -> 0 bytes docs/_static/images/uefi_secureboot_01.webp | Bin 0 -> 22238 bytes docs/_static/images/uefi_secureboot_02.png | Bin 14091 -> 0 bytes docs/_static/images/uefi_secureboot_02.webp | Bin 0 -> 6232 bytes docs/_static/images/uefi_secureboot_03.png | Bin 14760 -> 0 bytes docs/_static/images/uefi_secureboot_03.webp | Bin 0 -> 6568 bytes docs/_static/images/uefi_secureboot_04.png | Bin 7349 -> 0 bytes docs/_static/images/uefi_secureboot_04.webp | Bin 0 -> 3682 bytes docs/_static/images/uefi_secureboot_05.png | Bin 6636 -> 0 bytes docs/_static/images/uefi_secureboot_05.webp | Bin 0 -> 3308 bytes docs/_static/images/uefi_secureboot_06.png | Bin 7102 -> 0 bytes docs/_static/images/uefi_secureboot_06.webp | Bin 0 -> 3406 bytes docs/_static/images/uefi_secureboot_07.png | Bin 12622 -> 0 bytes docs/_static/images/uefi_secureboot_07.webp | Bin 0 -> 5726 bytes docs/_static/images/virt-libvirt-01.png | Bin 33227 -> 0 bytes docs/_static/images/virt-libvirt-01.webp | Bin 0 -> 13058 bytes docs/_static/images/virt-libvirt-02.png | Bin 30981 -> 0 bytes docs/_static/images/virt-libvirt-02.webp | Bin 0 -> 14020 bytes docs/_static/images/virt-libvirt-03.png | Bin 24547 -> 0 bytes docs/_static/images/virt-libvirt-03.webp | Bin 0 -> 9180 bytes docs/_static/images/virt-libvirt-04.png | Bin 28896 -> 0 bytes docs/_static/images/virt-libvirt-04.webp | Bin 0 -> 12254 bytes docs/_static/images/virt-libvirt-05.png | Bin 38080 -> 0 bytes docs/_static/images/virt-libvirt-05.webp | Bin 0 -> 14698 bytes docs/_static/images/virt-libvirt-06.png | Bin 28784 -> 0 bytes docs/_static/images/virt-libvirt-06.webp | Bin 0 -> 46772 bytes docs/_static/images/virt-libvirt-qc-01.png | Bin 33468 -> 0 bytes docs/_static/images/virt-libvirt-qc-01.webp | Bin 0 -> 13206 bytes docs/_static/images/virt-libvirt-qc-02.png | Bin 26749 -> 0 bytes docs/_static/images/virt-libvirt-qc-02.webp | Bin 0 -> 10610 bytes docs/_static/images/virt-libvirt-qc-03.png | Bin 28278 -> 0 bytes docs/_static/images/virt-libvirt-qc-03.webp | Bin 0 -> 41558 bytes docs/_static/images/vpn_dmvpn_topology01.png | Bin 94382 -> 0 bytes docs/_static/images/vpn_dmvpn_topology01.webp | Bin 0 -> 35722 bytes docs/_static/images/vpn_s2s_ikev2.png | Bin 66279 -> 0 bytes docs/_static/images/vpn_s2s_ikev2.webp | Bin 0 -> 26994 bytes docs/_static/images/vpn_s2s_ikev2_c.png | Bin 69496 -> 0 bytes docs/_static/images/vpn_s2s_ikev2_c.webp | Bin 0 -> 30564 bytes docs/_static/images/vrf-example-topology-01.png | Bin 32567 -> 0 bytes docs/_static/images/vrf-example-topology-01.webp | Bin 0 -> 19256 bytes docs/_static/images/vyos-downloads.png | Bin 65202 -> 0 bytes docs/_static/images/vyos-downloads.webp | Bin 0 -> 19332 bytes docs/_static/images/vyos-logo-icon.webp | Bin 0 -> 1806 bytes docs/_static/images/vyos-logo.webp | Bin 0 -> 3258 bytes docs/_static/images/vyos-sr-isis.png | Bin 45339 -> 0 bytes docs/_static/images/vyos-sr-isis.webp | Bin 0 -> 20016 bytes docs/_static/images/vyos_1_4_nat66_simple.png | Bin 21021 -> 0 bytes docs/_static/images/vyos_1_4_nat66_simple.webp | Bin 0 -> 5488 bytes .../images/vyos_1_5_nat66_dhcpv6_wdummy.png | Bin 349078 -> 0 bytes .../images/vyos_1_5_nat66_dhcpv6_wdummy.webp | Bin 0 -> 82130 bytes docs/_static/images/vyos_arista_bond_lacp.png | Bin 40622 -> 0 bytes docs/_static/images/vyos_arista_bond_lacp.webp | Bin 0 -> 24962 bytes docs/_static/images/vyosnew-downloads.png | Bin 64419 -> 0 bytes docs/_static/images/vyosnew-downloads.webp | Bin 0 -> 37012 bytes docs/_static/images/wireguard_qrcode.jpg | Bin 133939 -> 0 bytes docs/_static/images/wireguard_qrcode.webp | Bin 0 -> 57382 bytes .../_static/images/wireguard_site2site_diagram.jpg | Bin 19987 -> 0 bytes .../images/wireguard_site2site_diagram.webp | Bin 0 -> 9020 bytes docs/_static/images/zone-policy-diagram.png | Bin 113618 -> 0 bytes docs/_static/images/zone-policy-diagram.webp | Bin 0 -> 54546 bytes docs/_swap.txt | 261 ++++ 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/conf.py | 54 +- .../DHCPRelay_through_GRE/_include/topology.webp | Bin 0 -> 20146 bytes .../md-DHCPRelay_through_GRE.md | 89 ++ .../autotest/L3VPN_EVPN/_include/topology.webp | Bin 0 -> 49416 bytes .../autotest/L3VPN_EVPN/md-L3VPN_EVPN.md | 246 +++ .../OpenVPN_with_LDAP/_include/topology.webp | Bin 0 -> 11392 bytes .../OpenVPN_with_LDAP/md-OpenVPN_with_LDAP.md | 238 +++ .../autotest/Wireguard/_include/topology.webp | Bin 0 -> 31422 bytes .../autotest/Wireguard/md-Wireguard.md | 108 ++ .../autotest/tunnelbroker/_include/topology.webp | Bin 0 -> 8464 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 | 129 ++ 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-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/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 ++++++ 621 files changed, 65669 insertions(+), 21 deletions(-) create mode 100644 docs/_html_extra/llms.txt create mode 100644 docs/_static/css/DataTables-1.11.5/images/sort_asc.webp create mode 100644 docs/_static/css/DataTables-1.11.5/images/sort_asc_disabled.webp create mode 100644 docs/_static/css/DataTables-1.11.5/images/sort_both.webp create mode 100644 docs/_static/css/DataTables-1.11.5/images/sort_desc.webp create mode 100644 docs/_static/css/DataTables-1.11.5/images/sort_desc_disabled.webp delete mode 100644 docs/_static/images/1u_vyos_back.jpg create mode 100644 docs/_static/images/1u_vyos_back.webp delete mode 100644 docs/_static/images/1u_vyos_front.jpg create mode 100644 docs/_static/images/1u_vyos_front.webp delete mode 100644 docs/_static/images/1u_vyos_front_10ge_open_1.jpg create mode 100644 docs/_static/images/1u_vyos_front_10ge_open_1.webp delete mode 100644 docs/_static/images/1u_vyos_front_10ge_open_2.jpg create mode 100644 docs/_static/images/1u_vyos_front_10ge_open_2.webp delete mode 100644 docs/_static/images/1u_vyos_front_10ge_open_3.jpg create mode 100644 docs/_static/images/1u_vyos_front_10ge_open_3.webp delete mode 100644 docs/_static/images/1u_vyos_front_10ge_open_4.jpg create mode 100644 docs/_static/images/1u_vyos_front_10ge_open_4.webp delete mode 100644 docs/_static/images/1u_vyos_front_open_1.jpg create mode 100644 docs/_static/images/1u_vyos_front_open_1.webp delete mode 100644 docs/_static/images/1u_vyos_front_open_2.jpg create mode 100644 docs/_static/images/1u_vyos_front_open_2.webp delete mode 100644 docs/_static/images/1u_vyos_front_open_3.jpg create mode 100644 docs/_static/images/1u_vyos_front_open_3.webp delete mode 100644 docs/_static/images/480px-Acrosser_ANDJ190N1_Back.jpg create mode 100644 docs/_static/images/480px-Acrosser_ANDJ190N1_Back.webp delete mode 100644 docs/_static/images/480px-Acrosser_ANDJ190N1_Front.jpg create mode 100644 docs/_static/images/480px-Acrosser_ANDJ190N1_Front.webp delete mode 100644 docs/_static/images/600px-Partaker-i5.jpg create mode 100644 docs/_static/images/600px-Partaker-i5.webp delete mode 100644 docs/_static/images/ESP_AH.png create mode 100644 docs/_static/images/ESP_AH.webp delete mode 100644 docs/_static/images/IPSec_close_action_settings.png create mode 100644 docs/_static/images/IPSec_close_action_settings.webp delete mode 100644 docs/_static/images/L3VPN_hub_and_spoke.png create mode 100644 docs/_static/images/L3VPN_hub_and_spoke.webp delete mode 100644 docs/_static/images/PA-ESP-group.png create mode 100644 docs/_static/images/PA-ESP-group.webp delete mode 100644 docs/_static/images/PA-IKE-GW-1.png create mode 100644 docs/_static/images/PA-IKE-GW-1.webp delete mode 100644 docs/_static/images/PA-IKE-GW-2.png create mode 100644 docs/_static/images/PA-IKE-GW-2.webp delete mode 100644 docs/_static/images/PA-IKE-group.png create mode 100644 docs/_static/images/PA-IKE-group.webp delete mode 100644 docs/_static/images/PA-IPsec-tunnel.png create mode 100644 docs/_static/images/PA-IPsec-tunnel.webp delete mode 100644 docs/_static/images/PA-tunnel-1.png create mode 100644 docs/_static/images/PA-tunnel-1.webp delete mode 100644 docs/_static/images/PA-tunnel-2.png create mode 100644 docs/_static/images/PA-tunnel-2.webp delete mode 100644 docs/_static/images/PA-tunnel-3.png create mode 100644 docs/_static/images/PA-tunnel-3.webp delete mode 100644 docs/_static/images/VyOS_Dual-Hub_DMVPN.png create mode 100644 docs/_static/images/VyOS_Dual-Hub_DMVPN.webp delete mode 100644 docs/_static/images/Wan_load_balancing1.png create mode 100644 docs/_static/images/Wan_load_balancing1.webp delete mode 100644 docs/_static/images/Wan_load_balancing_exclude1.png create mode 100644 docs/_static/images/Wan_load_balancing_exclude1.webp delete mode 100644 docs/_static/images/ansible.png create mode 100644 docs/_static/images/ansible.webp delete mode 100644 docs/_static/images/apu4_desk_1.jpg create mode 100644 docs/_static/images/apu4_desk_1.webp delete mode 100644 docs/_static/images/apu4_desk_2.jpg create mode 100644 docs/_static/images/apu4_desk_2.webp delete mode 100644 docs/_static/images/apu4_desk_3.jpg create mode 100644 docs/_static/images/apu4_desk_3.webp delete mode 100644 docs/_static/images/apu4_desk_4.jpg create mode 100644 docs/_static/images/apu4_desk_4.webp delete mode 100644 docs/_static/images/apu4_rack_1.jpg create mode 100644 docs/_static/images/apu4_rack_1.webp delete mode 100644 docs/_static/images/apu4_rack_2.jpg create mode 100644 docs/_static/images/apu4_rack_2.webp delete mode 100644 docs/_static/images/apu4_rack_3.jpg create mode 100644 docs/_static/images/apu4_rack_3.webp delete mode 100644 docs/_static/images/apu4_rack_4.jpg create mode 100644 docs/_static/images/apu4_rack_4.webp delete mode 100644 docs/_static/images/apu4_rack_5.jpg create mode 100644 docs/_static/images/apu4_rack_5.webp delete mode 100644 docs/_static/images/apu4_rack_vyos_print.jpg create mode 100644 docs/_static/images/apu4_rack_vyos_print.webp delete mode 100644 docs/_static/images/aws.png create mode 100644 docs/_static/images/aws.webp delete mode 100644 docs/_static/images/blueprint-dmvpn.png create mode 100644 docs/_static/images/blueprint-dmvpn.webp delete mode 100644 docs/_static/images/boot-options.png create mode 100644 docs/_static/images/boot-options.webp delete mode 100644 docs/_static/images/cisco-vpn-ipsec.png create mode 100644 docs/_static/images/cisco-vpn-ipsec.webp delete mode 100644 docs/_static/images/cloud-aws-01.png create mode 100644 docs/_static/images/cloud-aws-01.webp delete mode 100644 docs/_static/images/cloud-aws-02.png create mode 100644 docs/_static/images/cloud-aws-02.webp delete mode 100644 docs/_static/images/cloud-aws-03.png create mode 100644 docs/_static/images/cloud-aws-03.webp delete mode 100644 docs/_static/images/cloud-aws-04.png create mode 100644 docs/_static/images/cloud-aws-04.webp delete mode 100644 docs/_static/images/cloud-aws-05.png create mode 100644 docs/_static/images/cloud-aws-05.webp delete mode 100644 docs/_static/images/cloud-aws-06.png create mode 100644 docs/_static/images/cloud-aws-06.webp delete mode 100644 docs/_static/images/cloud-aws-07.png create mode 100644 docs/_static/images/cloud-aws-07.webp delete mode 100644 docs/_static/images/cloud-aws-08.png create mode 100644 docs/_static/images/cloud-aws-08.webp delete mode 100644 docs/_static/images/cloud-azure-01.png create mode 100644 docs/_static/images/cloud-azure-01.webp delete mode 100644 docs/_static/images/cloud-azure-02.png create mode 100644 docs/_static/images/cloud-azure-02.webp delete mode 100644 docs/_static/images/cloud-azure-03.png create mode 100644 docs/_static/images/cloud-azure-03.webp delete mode 100644 docs/_static/images/cloud-azure-04.png create mode 100644 docs/_static/images/cloud-azure-04.webp delete mode 100644 docs/_static/images/cloud-azure-05.png create mode 100644 docs/_static/images/cloud-azure-05.webp delete mode 100644 docs/_static/images/cloud-azure-06.png create mode 100644 docs/_static/images/cloud-azure-06.webp delete mode 100644 docs/_static/images/cloud-gcp-01.png create mode 100644 docs/_static/images/cloud-gcp-01.webp delete mode 100644 docs/_static/images/cloud-gcp-02.png create mode 100644 docs/_static/images/cloud-gcp-02.webp delete mode 100644 docs/_static/images/cloud-gcp-03.png create mode 100644 docs/_static/images/cloud-gcp-03.webp delete mode 100644 docs/_static/images/cloud-gcp-04.png create mode 100644 docs/_static/images/cloud-gcp-04.webp delete mode 100644 docs/_static/images/cloud-gcp-05.png create mode 100644 docs/_static/images/cloud-gcp-05.webp delete mode 100644 docs/_static/images/dhcp-relay-through-gre-bridge.png create mode 100644 docs/_static/images/dhcp-relay-through-gre-bridge.webp delete mode 100644 docs/_static/images/dual-hub-DMVPN.png create mode 100644 docs/_static/images/dual-hub-DMVPN.webp delete mode 100644 docs/_static/images/eve-ng-vyos.png create mode 100644 docs/_static/images/eve-ng-vyos.webp delete mode 100644 docs/_static/images/firewall-and-vrf-blueprints.png create mode 100644 docs/_static/images/firewall-and-vrf-blueprints.webp delete mode 100644 docs/_static/images/firewall-bridge-forward.png create mode 100644 docs/_static/images/firewall-bridge-forward.webp delete mode 100644 docs/_static/images/firewall-bridge-input.png create mode 100644 docs/_static/images/firewall-bridge-input.webp delete mode 100644 docs/_static/images/firewall-bridge-output.png create mode 100644 docs/_static/images/firewall-bridge-output.webp delete mode 100644 docs/_static/images/firewall-flowtable-packet-flow.png create mode 100644 docs/_static/images/firewall-flowtable-packet-flow.webp delete mode 100644 docs/_static/images/firewall-fwd-packet-flow.png create mode 100644 docs/_static/images/firewall-fwd-packet-flow.webp delete mode 100644 docs/_static/images/firewall-gral-packet-flow.png create mode 100644 docs/_static/images/firewall-gral-packet-flow.webp delete mode 100644 docs/_static/images/firewall-input-packet-flow.png create mode 100644 docs/_static/images/firewall-input-packet-flow.webp delete mode 100644 docs/_static/images/firewall-netfilter.png create mode 100644 docs/_static/images/firewall-netfilter.webp delete mode 100644 docs/_static/images/firewall-traditional.png create mode 100644 docs/_static/images/firewall-traditional.webp delete mode 100644 docs/_static/images/firewall-zonebased.png create mode 100644 docs/_static/images/firewall-zonebased.webp delete mode 100644 docs/_static/images/gns3-01.png create mode 100644 docs/_static/images/gns3-01.webp delete mode 100644 docs/_static/images/gns3-02.png create mode 100644 docs/_static/images/gns3-02.webp delete mode 100644 docs/_static/images/gns3-03.png create mode 100644 docs/_static/images/gns3-03.webp delete mode 100644 docs/_static/images/gns3-04.png create mode 100644 docs/_static/images/gns3-04.webp delete mode 100644 docs/_static/images/gns3-05.png create mode 100644 docs/_static/images/gns3-05.webp delete mode 100644 docs/_static/images/gns3-06.png create mode 100644 docs/_static/images/gns3-06.webp delete mode 100644 docs/_static/images/gns3-07.png create mode 100644 docs/_static/images/gns3-07.webp delete mode 100644 docs/_static/images/gns3-08.png create mode 100644 docs/_static/images/gns3-08.webp delete mode 100644 docs/_static/images/gns3-09.png create mode 100644 docs/_static/images/gns3-09.webp delete mode 100644 docs/_static/images/gns3-10.png create mode 100644 docs/_static/images/gns3-10.webp delete mode 100644 docs/_static/images/gns3-11.png create mode 100644 docs/_static/images/gns3-11.webp delete mode 100644 docs/_static/images/gns3-12.png create mode 100644 docs/_static/images/gns3-12.webp delete mode 100644 docs/_static/images/gns3-13.png create mode 100644 docs/_static/images/gns3-13.webp delete mode 100644 docs/_static/images/gns3-14.png create mode 100644 docs/_static/images/gns3-14.webp delete mode 100644 docs/_static/images/gns3-15.png create mode 100644 docs/_static/images/gns3-15.webp delete mode 100644 docs/_static/images/gns3-16.png create mode 100644 docs/_static/images/gns3-16.webp delete mode 100644 docs/_static/images/gns3-17.png create mode 100644 docs/_static/images/gns3-17.webp delete mode 100644 docs/_static/images/gns3-20.png create mode 100644 docs/_static/images/gns3-20.webp delete mode 100644 docs/_static/images/gns3-21.png create mode 100644 docs/_static/images/gns3-21.webp delete mode 100644 docs/_static/images/gns3-215.png create mode 100644 docs/_static/images/gns3-215.webp delete mode 100644 docs/_static/images/gns3-22.png create mode 100644 docs/_static/images/gns3-22.webp delete mode 100644 docs/_static/images/gowin-01.png create mode 100644 docs/_static/images/gowin-01.webp delete mode 100644 docs/_static/images/gowin-02.png create mode 100644 docs/_static/images/gowin-02.webp delete mode 100644 docs/_static/images/gowin-03.png create mode 100644 docs/_static/images/gowin-03.webp delete mode 100644 docs/_static/images/gowin-04.png create mode 100644 docs/_static/images/gowin-04.webp delete mode 100644 docs/_static/images/inter-vrf-routing-vrf-lite.png create mode 100644 docs/_static/images/inter-vrf-routing-vrf-lite.webp delete mode 100644 docs/_static/images/ipsec-vyos-pa.png create mode 100644 docs/_static/images/ipsec-vyos-pa.webp delete mode 100644 docs/_static/images/json.png create mode 100644 docs/_static/images/json.webp delete mode 100644 docs/_static/images/key.png create mode 100644 docs/_static/images/key.webp delete mode 100644 docs/_static/images/keypairs.png create mode 100644 docs/_static/images/keypairs.webp delete mode 100644 docs/_static/images/lac-lns-diagram.jpg create mode 100644 docs/_static/images/lac-lns-diagram.webp delete mode 100644 docs/_static/images/lac-lns-winclient.jpg create mode 100644 docs/_static/images/lac-lns-winclient.webp delete mode 100644 docs/_static/images/ldapone.png create mode 100644 docs/_static/images/ldapone.webp delete mode 100644 docs/_static/images/ldaptwo.png create mode 100644 docs/_static/images/ldaptwo.webp delete mode 100644 docs/_static/images/mainschema.png create mode 100644 docs/_static/images/mainschema.webp delete mode 100644 docs/_static/images/multicast-basic.png create mode 100644 docs/_static/images/multicast-basic.webp delete mode 100644 docs/_static/images/nat_before_vpn_topology.png create mode 100644 docs/_static/images/nat_before_vpn_topology.webp delete mode 100644 docs/_static/images/nmp1.png create mode 100644 docs/_static/images/nmp1.webp delete mode 100644 docs/_static/images/nmp2.png create mode 100644 docs/_static/images/nmp2.webp delete mode 100644 docs/_static/images/nmp3.png create mode 100644 docs/_static/images/nmp3.webp delete mode 100644 docs/_static/images/nmp4.png create mode 100644 docs/_static/images/nmp4.webp delete mode 100644 docs/_static/images/nmp5.png create mode 100644 docs/_static/images/nmp5.webp delete mode 100644 docs/_static/images/nmp6.png create mode 100644 docs/_static/images/nmp6.webp delete mode 100644 docs/_static/images/nmp7.png create mode 100644 docs/_static/images/nmp7.webp delete mode 100644 docs/_static/images/openvpn_site2site_diagram.jpg create mode 100644 docs/_static/images/openvpn_site2site_diagram.webp delete mode 100644 docs/_static/images/pbr_example_1.png create mode 100644 docs/_static/images/pbr_example_1.webp delete mode 100644 docs/_static/images/policy-based-ipsec-and-firewall.png create mode 100644 docs/_static/images/policy-based-ipsec-and-firewall.webp delete mode 100644 docs/_static/images/pppoe-ipv6-pd-diagram.jpg create mode 100644 docs/_static/images/pppoe-ipv6-pd-diagram.webp delete mode 100644 docs/_static/images/project.png create mode 100644 docs/_static/images/project.webp delete mode 100644 docs/_static/images/qos1.png create mode 100644 docs/_static/images/qos1.webp delete mode 100644 docs/_static/images/qos10.png create mode 100644 docs/_static/images/qos10.webp delete mode 100644 docs/_static/images/qos2.png create mode 100644 docs/_static/images/qos2.webp delete mode 100644 docs/_static/images/qos3.png create mode 100644 docs/_static/images/qos3.webp delete mode 100644 docs/_static/images/qos4.png create mode 100644 docs/_static/images/qos4.webp delete mode 100644 docs/_static/images/qos5.png create mode 100644 docs/_static/images/qos5.webp delete mode 100644 docs/_static/images/qos6.png create mode 100644 docs/_static/images/qos6.webp delete mode 100644 docs/_static/images/qos7.png create mode 100644 docs/_static/images/qos7.webp delete mode 100644 docs/_static/images/qos8.png create mode 100644 docs/_static/images/qos8.webp delete mode 100644 docs/_static/images/qos9.png create mode 100644 docs/_static/images/qos9.webp delete mode 100644 docs/_static/images/reset-password-step-1.jpg create mode 100644 docs/_static/images/reset-password-step-1.webp delete mode 100644 docs/_static/images/reset-password-step-2.jpg create mode 100644 docs/_static/images/reset-password-step-2.webp delete mode 100644 docs/_static/images/reset-password-step-3.jpg create mode 100644 docs/_static/images/reset-password-step-3.webp delete mode 100644 docs/_static/images/reset-password-step-4.jpg create mode 100644 docs/_static/images/reset-password-step-4.webp delete mode 100644 docs/_static/images/reset-password-step-5.jpg create mode 100644 docs/_static/images/reset-password-step-5.webp delete mode 100644 docs/_static/images/service.png create mode 100644 docs/_static/images/service.webp delete mode 100644 docs/_static/images/service_conntrack_sync-schema.png create mode 100644 docs/_static/images/service_conntrack_sync-schema.webp delete mode 100644 docs/_static/images/service_dhcp-relay01.png create mode 100644 docs/_static/images/service_dhcp-relay01.webp delete mode 100644 docs/_static/images/service_dhcpv6-relay01.png create mode 100644 docs/_static/images/service_dhcpv6-relay01.webp delete mode 100644 docs/_static/images/service_snmp_communication_principles_diagram.png create mode 100644 docs/_static/images/service_snmp_communication_principles_diagram.webp delete mode 100644 docs/_static/images/sg.png create mode 100644 docs/_static/images/sg.webp delete mode 100644 docs/_static/images/sticky-connections.jpg create mode 100644 docs/_static/images/sticky-connections.webp delete mode 100644 docs/_static/images/traffic.png create mode 100644 docs/_static/images/traffic.webp delete mode 100644 docs/_static/images/uefi_secureboot_01.png create mode 100644 docs/_static/images/uefi_secureboot_01.webp delete mode 100644 docs/_static/images/uefi_secureboot_02.png create mode 100644 docs/_static/images/uefi_secureboot_02.webp delete mode 100644 docs/_static/images/uefi_secureboot_03.png create mode 100644 docs/_static/images/uefi_secureboot_03.webp delete mode 100644 docs/_static/images/uefi_secureboot_04.png create mode 100644 docs/_static/images/uefi_secureboot_04.webp delete mode 100644 docs/_static/images/uefi_secureboot_05.png create mode 100644 docs/_static/images/uefi_secureboot_05.webp delete mode 100644 docs/_static/images/uefi_secureboot_06.png create mode 100644 docs/_static/images/uefi_secureboot_06.webp delete mode 100644 docs/_static/images/uefi_secureboot_07.png create mode 100644 docs/_static/images/uefi_secureboot_07.webp delete mode 100644 docs/_static/images/virt-libvirt-01.png create mode 100644 docs/_static/images/virt-libvirt-01.webp delete mode 100644 docs/_static/images/virt-libvirt-02.png create mode 100644 docs/_static/images/virt-libvirt-02.webp delete mode 100644 docs/_static/images/virt-libvirt-03.png create mode 100644 docs/_static/images/virt-libvirt-03.webp delete mode 100644 docs/_static/images/virt-libvirt-04.png create mode 100644 docs/_static/images/virt-libvirt-04.webp delete mode 100644 docs/_static/images/virt-libvirt-05.png create mode 100644 docs/_static/images/virt-libvirt-05.webp delete mode 100644 docs/_static/images/virt-libvirt-06.png create mode 100644 docs/_static/images/virt-libvirt-06.webp delete mode 100644 docs/_static/images/virt-libvirt-qc-01.png create mode 100644 docs/_static/images/virt-libvirt-qc-01.webp delete mode 100644 docs/_static/images/virt-libvirt-qc-02.png create mode 100644 docs/_static/images/virt-libvirt-qc-02.webp delete mode 100644 docs/_static/images/virt-libvirt-qc-03.png create mode 100644 docs/_static/images/virt-libvirt-qc-03.webp delete mode 100644 docs/_static/images/vpn_dmvpn_topology01.png create mode 100644 docs/_static/images/vpn_dmvpn_topology01.webp delete mode 100644 docs/_static/images/vpn_s2s_ikev2.png create mode 100644 docs/_static/images/vpn_s2s_ikev2.webp delete mode 100644 docs/_static/images/vpn_s2s_ikev2_c.png create mode 100644 docs/_static/images/vpn_s2s_ikev2_c.webp delete mode 100644 docs/_static/images/vrf-example-topology-01.png create mode 100644 docs/_static/images/vrf-example-topology-01.webp delete mode 100644 docs/_static/images/vyos-downloads.png create mode 100644 docs/_static/images/vyos-downloads.webp create mode 100644 docs/_static/images/vyos-logo-icon.webp create mode 100644 docs/_static/images/vyos-logo.webp delete mode 100644 docs/_static/images/vyos-sr-isis.png create mode 100644 docs/_static/images/vyos-sr-isis.webp delete mode 100644 docs/_static/images/vyos_1_4_nat66_simple.png create mode 100644 docs/_static/images/vyos_1_4_nat66_simple.webp delete mode 100644 docs/_static/images/vyos_1_5_nat66_dhcpv6_wdummy.png create mode 100644 docs/_static/images/vyos_1_5_nat66_dhcpv6_wdummy.webp delete mode 100644 docs/_static/images/vyos_arista_bond_lacp.png create mode 100644 docs/_static/images/vyos_arista_bond_lacp.webp delete mode 100644 docs/_static/images/vyosnew-downloads.png create mode 100644 docs/_static/images/vyosnew-downloads.webp delete mode 100644 docs/_static/images/wireguard_qrcode.jpg create mode 100644 docs/_static/images/wireguard_qrcode.webp delete mode 100644 docs/_static/images/wireguard_site2site_diagram.jpg create mode 100644 docs/_static/images/wireguard_site2site_diagram.webp delete mode 100644 docs/_static/images/zone-policy-diagram.png create mode 100644 docs/_static/images/zone-policy-diagram.webp create mode 100644 docs/_swap.txt create mode 100644 docs/automation/md-cloud-init.md create mode 100644 docs/automation/md-command-scripting.md create mode 100644 docs/automation/md-index.md create mode 100644 docs/automation/md-vyos-ansible.md create mode 100644 docs/automation/md-vyos-api.md create mode 100644 docs/automation/md-vyos-govyos.md create mode 100644 docs/automation/md-vyos-napalm.md create mode 100644 docs/automation/md-vyos-netmiko.md create mode 100644 docs/automation/md-vyos-pyvyos.md create mode 100644 docs/automation/md-vyos-salt.md create mode 100644 docs/automation/terraform/md-index.md create mode 100644 docs/automation/terraform/md-terraformAWS.md create mode 100644 docs/automation/terraform/md-terraformAZ.md create mode 100644 docs/automation/terraform/md-terraformGoogle.md create mode 100644 docs/automation/terraform/md-terraformvSphere.md create mode 100644 docs/configexamples/autotest/DHCPRelay_through_GRE/_include/topology.webp create mode 100644 docs/configexamples/autotest/DHCPRelay_through_GRE/md-DHCPRelay_through_GRE.md create mode 100644 docs/configexamples/autotest/L3VPN_EVPN/_include/topology.webp create mode 100644 docs/configexamples/autotest/L3VPN_EVPN/md-L3VPN_EVPN.md create mode 100644 docs/configexamples/autotest/OpenVPN_with_LDAP/_include/topology.webp create mode 100644 docs/configexamples/autotest/OpenVPN_with_LDAP/md-OpenVPN_with_LDAP.md create mode 100644 docs/configexamples/autotest/Wireguard/_include/topology.webp create mode 100644 docs/configexamples/autotest/Wireguard/md-Wireguard.md create mode 100644 docs/configexamples/autotest/tunnelbroker/_include/topology.webp create mode 100644 docs/configexamples/autotest/tunnelbroker/md-tunnelbroker.md create mode 100644 docs/configexamples/md-ansible.md create mode 100644 docs/configexamples/md-azure-vpn-bgp.md create mode 100644 docs/configexamples/md-azure-vpn-dual-bgp.md create mode 100644 docs/configexamples/md-bgp-ipv6-unnumbered.md create mode 100644 docs/configexamples/md-dmvpn-dualhub-dualcloud.md create mode 100644 docs/configexamples/md-firewall.md create mode 100644 docs/configexamples/md-fwall-and-bridge.md create mode 100644 docs/configexamples/md-fwall-and-vrf.md create mode 100644 docs/configexamples/md-ha.md create mode 100644 docs/configexamples/md-index.md create mode 100644 docs/configexamples/md-inter-vrf-routing-vrf-lite.md create mode 100644 docs/configexamples/md-ipsec-cisco-policy-based.md create mode 100644 docs/configexamples/md-ipsec-cisco-route-based.md create mode 100644 docs/configexamples/md-ipsec-pa-route-based.md create mode 100644 docs/configexamples/md-l3vpn-hub-and-spoke.md create mode 100644 docs/configexamples/md-lac-lns.md create mode 100644 docs/configexamples/md-nmp.md create mode 100644 docs/configexamples/md-ospf-unnumbered.md create mode 100644 docs/configexamples/md-policy-based-ipsec-and-firewall.md create mode 100644 docs/configexamples/md-pppoe-ipv6-basic.md create mode 100644 docs/configexamples/md-qos.md create mode 100644 docs/configexamples/md-segment-routing-isis.md create mode 100644 docs/configexamples/md-site-2-site-cisco.md create mode 100644 docs/configexamples/md-wan-load-balancing.md create mode 100644 docs/configexamples/md-zone-policy.md create mode 100644 docs/configuration/container/md-index.md create mode 100644 docs/configuration/firewall/md-bridge.md create mode 100644 docs/configuration/firewall/md-flowtables.md create mode 100644 docs/configuration/firewall/md-global-options.md create mode 100644 docs/configuration/firewall/md-groups.md create mode 100644 docs/configuration/firewall/md-index.md create mode 100644 docs/configuration/firewall/md-ipv4.md create mode 100644 docs/configuration/firewall/md-ipv6.md create mode 100644 docs/configuration/firewall/md-zone.md create mode 100644 docs/configuration/highavailability/md-index.md create mode 100644 docs/configuration/interfaces/md-bonding.md create mode 100644 docs/configuration/interfaces/md-bridge.md create mode 100644 docs/configuration/interfaces/md-dummy.md create mode 100644 docs/configuration/interfaces/md-ethernet.md create mode 100644 docs/configuration/interfaces/md-geneve.md create mode 100644 docs/configuration/interfaces/md-index.md create mode 100644 docs/configuration/interfaces/md-l2tpv3.md create mode 100644 docs/configuration/interfaces/md-loopback.md create mode 100644 docs/configuration/interfaces/md-macsec.md create mode 100644 docs/configuration/interfaces/md-openvpn-examples.md create mode 100644 docs/configuration/interfaces/md-openvpn.md create mode 100644 docs/configuration/interfaces/md-pppoe.md create mode 100644 docs/configuration/interfaces/md-pseudo-ethernet.md create mode 100644 docs/configuration/interfaces/md-sstp-client.md create mode 100644 docs/configuration/interfaces/md-tunnel.md create mode 100644 docs/configuration/interfaces/md-virtual-ethernet.md create mode 100644 docs/configuration/interfaces/md-vti.md create mode 100644 docs/configuration/interfaces/md-vxlan.md create mode 100644 docs/configuration/interfaces/md-wireguard.md create mode 100644 docs/configuration/interfaces/md-wireless.md create mode 100644 docs/configuration/interfaces/md-wwan.md create mode 100644 docs/configuration/loadbalancing/md-haproxy.md create mode 100644 docs/configuration/loadbalancing/md-index.md create mode 100644 docs/configuration/loadbalancing/md-wan.md create mode 100644 docs/configuration/md-index.md create mode 100644 docs/configuration/nat/md-cgnat.md create mode 100644 docs/configuration/nat/md-index.md create mode 100644 docs/configuration/nat/md-nat44.md create mode 100644 docs/configuration/nat/md-nat64.md create mode 100644 docs/configuration/nat/md-nat66.md create mode 100644 docs/configuration/pki/md-index.md create mode 100644 docs/configuration/policy/md-access-list.md create mode 100644 docs/configuration/policy/md-as-path-list.md create mode 100644 docs/configuration/policy/md-community-list.md create mode 100644 docs/configuration/policy/md-examples.md create mode 100644 docs/configuration/policy/md-extcommunity-list.md create mode 100644 docs/configuration/policy/md-index.md create mode 100644 docs/configuration/policy/md-large-community-list.md create mode 100644 docs/configuration/policy/md-local-route.md create mode 100644 docs/configuration/policy/md-prefix-list.md create mode 100644 docs/configuration/policy/md-route-map.md create mode 100644 docs/configuration/policy/md-route.md create mode 100644 docs/configuration/protocols/md-arp.md create mode 100644 docs/configuration/protocols/md-babel.md create mode 100644 docs/configuration/protocols/md-bfd.md create mode 100644 docs/configuration/protocols/md-bgp.md create mode 100644 docs/configuration/protocols/md-failover.md create mode 100644 docs/configuration/protocols/md-igmp-proxy.md create mode 100644 docs/configuration/protocols/md-index.md create mode 100644 docs/configuration/protocols/md-isis.md create mode 100644 docs/configuration/protocols/md-mpls.md create mode 100644 docs/configuration/protocols/md-multicast.md create mode 100644 docs/configuration/protocols/md-openfabric.md create mode 100644 docs/configuration/protocols/md-ospf.md create mode 100644 docs/configuration/protocols/md-pim.md create mode 100644 docs/configuration/protocols/md-pim6.md create mode 100644 docs/configuration/protocols/md-rip.md create mode 100644 docs/configuration/protocols/md-rpki.md create mode 100644 docs/configuration/protocols/md-segment-routing.md create mode 100644 docs/configuration/protocols/md-static.md create mode 100644 docs/configuration/protocols/md-traffic-engineering.md create mode 100644 docs/configuration/service/md-broadcast-relay.md create mode 100644 docs/configuration/service/md-config-sync.md create mode 100644 docs/configuration/service/md-conntrack-sync.md create mode 100644 docs/configuration/service/md-console-server.md create mode 100644 docs/configuration/service/md-dhcp-relay.md create mode 100644 docs/configuration/service/md-dhcp-server.md create mode 100644 docs/configuration/service/md-dns.md create mode 100644 docs/configuration/service/md-eventhandler.md create mode 100644 docs/configuration/service/md-https.md create mode 100644 docs/configuration/service/md-index.md create mode 100644 docs/configuration/service/md-ipoe-server.md create mode 100644 docs/configuration/service/md-lldp.md create mode 100644 docs/configuration/service/md-mdns.md create mode 100644 docs/configuration/service/md-monitoring.md create mode 100644 docs/configuration/service/md-ntp.md create mode 100644 docs/configuration/service/md-pppoe-server.md create mode 100644 docs/configuration/service/md-router-advert.md create mode 100644 docs/configuration/service/md-salt-minion.md create mode 100644 docs/configuration/service/md-snmp.md create mode 100644 docs/configuration/service/md-ssh.md create mode 100644 docs/configuration/service/md-tftp-server.md create mode 100644 docs/configuration/service/md-webproxy.md create mode 100644 docs/configuration/system/md-acceleration.md create mode 100644 docs/configuration/system/md-conntrack.md create mode 100644 docs/configuration/system/md-console.md create mode 100644 docs/configuration/system/md-default-route.md create mode 100644 docs/configuration/system/md-flow-accounting.md create mode 100644 docs/configuration/system/md-frr.md create mode 100644 docs/configuration/system/md-host-name.md create mode 100644 docs/configuration/system/md-index.md create mode 100644 docs/configuration/system/md-ip.md create mode 100644 docs/configuration/system/md-ipv6.md create mode 100644 docs/configuration/system/md-lcd.md create mode 100644 docs/configuration/system/md-login.md create mode 100644 docs/configuration/system/md-name-server.md create mode 100644 docs/configuration/system/md-option.md create mode 100644 docs/configuration/system/md-proxy.md create mode 100644 docs/configuration/system/md-sflow.md create mode 100644 docs/configuration/system/md-sysctl.md create mode 100644 docs/configuration/system/md-syslog.md create mode 100644 docs/configuration/system/md-task-scheduler.md create mode 100644 docs/configuration/system/md-time-zone.md create mode 100644 docs/configuration/system/md-updates.md create mode 100644 docs/configuration/system/md-watchdog.md create mode 100644 docs/configuration/trafficpolicy/md-index.md create mode 100644 docs/configuration/vpn/ipsec/md-index.md create mode 100644 docs/configuration/vpn/ipsec/md-ipsec_general.md create mode 100644 docs/configuration/vpn/ipsec/md-remoteaccess_ipsec.md create mode 100644 docs/configuration/vpn/ipsec/md-site2site_ipsec.md create mode 100644 docs/configuration/vpn/ipsec/md-troubleshooting_ipsec.md create mode 100644 docs/configuration/vpn/md-dmvpn.md create mode 100644 docs/configuration/vpn/md-index.md create mode 100644 docs/configuration/vpn/md-l2tp.md create mode 100644 docs/configuration/vpn/md-openconnect.md create mode 100644 docs/configuration/vpn/md-pptp.md create mode 100644 docs/configuration/vpn/md-rsa-keys.md create mode 100644 docs/configuration/vpn/md-sstp.md create mode 100644 docs/configuration/vrf/md-index.md create mode 100644 docs/contributing/md-build-vyos.md create mode 100644 docs/contributing/md-cla.md create mode 100644 docs/contributing/md-debugging.md create mode 100644 docs/contributing/md-development.md create mode 100644 docs/contributing/md-index.md create mode 100644 docs/contributing/md-issues-features.md create mode 100644 docs/contributing/md-testing.md create mode 100644 docs/contributing/md-upstream-packages.md create mode 100644 docs/installation/cloud/md-aws.md create mode 100644 docs/installation/cloud/md-azure.md create mode 100644 docs/installation/cloud/md-gcp.md create mode 100644 docs/installation/cloud/md-index.md create mode 100644 docs/installation/cloud/md-oracle.md create mode 100644 docs/installation/md-bare-metal.md create mode 100644 docs/installation/md-image.md create mode 100644 docs/installation/md-index.md create mode 100644 docs/installation/md-install.md create mode 100644 docs/installation/md-secure-boot.md create mode 100644 docs/installation/md-update.md create mode 100644 docs/installation/virtual/md-docker.md create mode 100644 docs/installation/virtual/md-eve-ng.md create mode 100644 docs/installation/virtual/md-gns3.md create mode 100644 docs/installation/virtual/md-index.md create mode 100644 docs/installation/virtual/md-libvirt.md create mode 100644 docs/installation/virtual/md-proxmox.md create mode 100644 docs/installation/virtual/md-vmware.md create mode 100644 docs/introducing/md-about.md create mode 100644 docs/introducing/md-history.md create mode 100644 docs/md-404.md create mode 100644 docs/md-cli.md create mode 100644 docs/md-coverage.md create mode 100644 docs/md-documentation.md create mode 100644 docs/md-index.md create mode 100644 docs/md-quick-start.md create mode 100644 docs/operation/md-boot-options.md create mode 100644 docs/operation/md-index.md create mode 100644 docs/operation/md-information.md create mode 100644 docs/operation/md-password-recovery.md create mode 100644 docs/operation/md-raid.md create mode 100644 docs/operation/md-upgrade-recovery.md create mode 100644 docs/troubleshooting/md-connectivity.md create mode 100644 docs/troubleshooting/md-index.md create mode 100644 docs/troubleshooting/md-interfaces.md create mode 100644 docs/troubleshooting/md-monitoring.md create mode 100644 docs/troubleshooting/md-system.md create mode 100644 docs/troubleshooting/md-terminal.md create mode 100644 docs/vpp/configuration/dataplane/md-buffers.md create mode 100644 docs/vpp/configuration/dataplane/md-cpu.md create mode 100644 docs/vpp/configuration/dataplane/md-index.md create mode 100644 docs/vpp/configuration/dataplane/md-interface.md create mode 100644 docs/vpp/configuration/dataplane/md-ipsec.md create mode 100644 docs/vpp/configuration/dataplane/md-ipv6.md create mode 100644 docs/vpp/configuration/dataplane/md-l2learn.md create mode 100644 docs/vpp/configuration/dataplane/md-lcp.md create mode 100644 docs/vpp/configuration/dataplane/md-logging.md create mode 100644 docs/vpp/configuration/dataplane/md-memory.md create mode 100644 docs/vpp/configuration/dataplane/md-system.md create mode 100644 docs/vpp/configuration/dataplane/md-unix.md create mode 100644 docs/vpp/configuration/interfaces/md-bonding.md create mode 100644 docs/vpp/configuration/interfaces/md-bridge.md create mode 100644 docs/vpp/configuration/interfaces/md-gre.md create mode 100644 docs/vpp/configuration/interfaces/md-index.md create mode 100644 docs/vpp/configuration/interfaces/md-ipip.md create mode 100644 docs/vpp/configuration/interfaces/md-loopback.md create mode 100644 docs/vpp/configuration/interfaces/md-vxlan.md create mode 100644 docs/vpp/configuration/interfaces/md-xconnect.md create mode 100644 docs/vpp/configuration/md-acl.md create mode 100644 docs/vpp/configuration/md-index.md create mode 100644 docs/vpp/configuration/md-ipfix.md create mode 100644 docs/vpp/configuration/md-ipsec.md create mode 100644 docs/vpp/configuration/md-sflow.md create mode 100644 docs/vpp/configuration/nat/md-cgnat.md create mode 100644 docs/vpp/configuration/nat/md-index.md create mode 100644 docs/vpp/configuration/nat/md-nat44.md create mode 100644 docs/vpp/md-description.md create mode 100644 docs/vpp/md-index.md create mode 100644 docs/vpp/md-limitations.md create mode 100644 docs/vpp/md-requirements.md create mode 100644 docs/vpp/md-troubleshooting.md (limited to 'docs') diff --git a/docs/Makefile b/docs/Makefile index cb6226af..ae12b802 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -12,22 +12,44 @@ 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 +.PHONY: help Makefile swap restore html dirhtml pdf livehtml defaultvalue -# 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) +swap: + $(SWAP) --swap -livehtml: - sphinx-autobuild --host $(AUTOHOST) --port $(AUTOPORT) $(AUTOOPTS) \ - "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) +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: - @$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) \ No newline at end of file +defaultvalue: html + +# 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) diff --git a/docs/_ext/vyos.py b/docs/_ext/vyos.py index 2f4dede9..527178d1 100644 --- a/docs/_ext/vyos.py +++ b/docs/_ext/vyos.py @@ -364,8 +364,18 @@ class CmdInclude(SphinxDirective): line = re.sub('{{\s?var' + str(i) + '\s?}}',value,line) new_include_lines.append(line) - self.state._renderer.nested_render_text(''.join(new_include_lines), self.lineno) - return [] + 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 class CfgcmdlistDirective(Directive): diff --git a/docs/_html_extra/llms.txt b/docs/_html_extra/llms.txt new file mode 100644 index 00000000..03d8562d --- /dev/null +++ b/docs/_html_extra/llms.txt @@ -0,0 +1,52 @@ +# VyOS + +> VyOS is a free, open-source network operating system based on Debian GNU/Linux. +> It provides routing, firewall, and VPN functionality via a unified CLI using +> `set`/`delete`/`show` command hierarchy. This documentation covers 1.5.x (circinus). + +VyOS configuration follows a tree structure. All configuration commands start with +`set` (to add/change) or `delete` (to remove). Changes are staged and applied with +`commit`. The CLI hierarchy maps directly to the documentation structure. + +## Quick Start + +- [Quick Start Guide](https://docs.vyos.io/en/1.5/quick-start.html): Minimal setup walkthrough +- [CLI Overview](https://docs.vyos.io/en/1.5/cli.html): Command-line interface usage + +## Configuration + +- [Firewall](https://docs.vyos.io/en/1.5/configuration/firewall/index.html): Zone-based firewall, rules, groups +- [Interfaces](https://docs.vyos.io/en/1.5/configuration/interfaces/index.html): Ethernet, bonding, bridge, VLAN, tunnel, wireless +- [Protocols](https://docs.vyos.io/en/1.5/configuration/protocols/index.html): BGP, OSPF, IS-IS, static routing, MPLS +- [VPN](https://docs.vyos.io/en/1.5/configuration/vpn/index.html): IPsec, OpenVPN, WireGuard, L2TP, PPTP +- [NAT](https://docs.vyos.io/en/1.5/configuration/nat/index.html): Source NAT, destination NAT, NAT66 +- [System](https://docs.vyos.io/en/1.5/configuration/system/index.html): DNS, NTP, syslog, users, task scheduler +- [High Availability](https://docs.vyos.io/en/1.5/configuration/highavailability/index.html): VRRP +- [Load Balancing](https://docs.vyos.io/en/1.5/configuration/loadbalancing/index.html): WAN and reverse proxy +- [Containers](https://docs.vyos.io/en/1.5/configuration/container/index.html): Podman-based container support +- [PKI](https://docs.vyos.io/en/1.5/configuration/pki/index.html): Certificate management +- [Policy](https://docs.vyos.io/en/1.5/configuration/policy/index.html): Route maps, prefix lists, access lists +- [Traffic Policy](https://docs.vyos.io/en/1.5/configuration/trafficpolicy/index.html): QoS and shaping +- [Service](https://docs.vyos.io/en/1.5/configuration/service/index.html): DHCP, DNS forwarding, SNMP, SSH, HTTPS API +- [VRF](https://docs.vyos.io/en/1.5/configuration/vrf/index.html): Virtual routing and forwarding + +## Operations + +- [Operational Commands](https://docs.vyos.io/en/1.5/operation/index.html): Show, monitor, restart commands + +## Installation + +- [Installation Guide](https://docs.vyos.io/en/1.5/installation/index.html): Bare metal, virtual, cloud deployments + +## Automation + +- [Automation](https://docs.vyos.io/en/1.5/automation/index.html): Ansible, Terraform, HTTP API, NETCONF + +## Configuration Examples + +- [Blueprints](https://docs.vyos.io/en/1.5/configexamples/index.html): Real-world topology examples + +## Optional + +- [Contributing](https://docs.vyos.io/en/1.5/contributing/index.html): Development workflow +- [VPP](https://docs.vyos.io/en/1.5/vpp/index.html): Vector Packet Processing integration diff --git a/docs/_html_extra/robots.txt b/docs/_html_extra/robots.txt index 627cb18e..98245d28 100644 --- a/docs/_html_extra/robots.txt +++ b/docs/_html_extra/robots.txt @@ -1,7 +1,36 @@ -User-agent: atlassian-bot -Disallow: - User-agent: * -Disallow: # Allow everything +Allow: / + +# AI Training Crawlers +User-agent: GPTBot +Allow: / + +User-agent: ClaudeBot +Allow: / + +User-agent: Google-Extended +Allow: / + +User-agent: CCBot +Allow: / + +User-agent: PerplexityBot +Allow: / + +# AI Search/Retrieval +User-agent: ChatGPT-User +Allow: / + +User-agent: Claude-SearchBot +Allow: / + +User-agent: Claude-User +Allow: / + +User-agent: OAI-SearchBot +Allow: / + +User-agent: Perplexity-User +Allow: / -Sitemap: https://docs.vyos.io/sitemap.xml \ No newline at end of file +Sitemap: https://docs.vyos.io/en/1.5/sitemap.xml diff --git a/docs/_static/css/DataTables-1.11.5/images/sort_asc.webp b/docs/_static/css/DataTables-1.11.5/images/sort_asc.webp new file mode 100644 index 00000000..eebabad0 Binary files /dev/null and b/docs/_static/css/DataTables-1.11.5/images/sort_asc.webp differ diff --git a/docs/_static/css/DataTables-1.11.5/images/sort_asc_disabled.webp b/docs/_static/css/DataTables-1.11.5/images/sort_asc_disabled.webp new file mode 100644 index 00000000..847d4f5d Binary files /dev/null and b/docs/_static/css/DataTables-1.11.5/images/sort_asc_disabled.webp differ diff --git a/docs/_static/css/DataTables-1.11.5/images/sort_both.webp b/docs/_static/css/DataTables-1.11.5/images/sort_both.webp new file mode 100644 index 00000000..1b09597a Binary files /dev/null and b/docs/_static/css/DataTables-1.11.5/images/sort_both.webp differ diff --git a/docs/_static/css/DataTables-1.11.5/images/sort_desc.webp b/docs/_static/css/DataTables-1.11.5/images/sort_desc.webp new file mode 100644 index 00000000..857789c6 Binary files /dev/null and b/docs/_static/css/DataTables-1.11.5/images/sort_desc.webp differ diff --git a/docs/_static/css/DataTables-1.11.5/images/sort_desc_disabled.webp b/docs/_static/css/DataTables-1.11.5/images/sort_desc_disabled.webp new file mode 100644 index 00000000..3368310f Binary files /dev/null and b/docs/_static/css/DataTables-1.11.5/images/sort_desc_disabled.webp differ diff --git a/docs/_static/images/1u_vyos_back.jpg b/docs/_static/images/1u_vyos_back.jpg deleted file mode 100644 index cd00c11c..00000000 Binary files a/docs/_static/images/1u_vyos_back.jpg and /dev/null differ diff --git a/docs/_static/images/1u_vyos_back.webp b/docs/_static/images/1u_vyos_back.webp new file mode 100644 index 00000000..b0dbab1d Binary files /dev/null and b/docs/_static/images/1u_vyos_back.webp differ diff --git a/docs/_static/images/1u_vyos_front.jpg b/docs/_static/images/1u_vyos_front.jpg deleted file mode 100644 index 3d135d56..00000000 Binary files a/docs/_static/images/1u_vyos_front.jpg and /dev/null differ diff --git a/docs/_static/images/1u_vyos_front.webp b/docs/_static/images/1u_vyos_front.webp new file mode 100644 index 00000000..a47e4f9e Binary files /dev/null and b/docs/_static/images/1u_vyos_front.webp 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 deleted file mode 100644 index edfba5a3..00000000 Binary files a/docs/_static/images/1u_vyos_front_10ge_open_1.jpg and /dev/null differ diff --git a/docs/_static/images/1u_vyos_front_10ge_open_1.webp b/docs/_static/images/1u_vyos_front_10ge_open_1.webp new file mode 100644 index 00000000..87f53ddd Binary files /dev/null and b/docs/_static/images/1u_vyos_front_10ge_open_1.webp 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 deleted file mode 100644 index 4f48a116..00000000 Binary files a/docs/_static/images/1u_vyos_front_10ge_open_2.jpg and /dev/null differ diff --git a/docs/_static/images/1u_vyos_front_10ge_open_2.webp b/docs/_static/images/1u_vyos_front_10ge_open_2.webp new file mode 100644 index 00000000..1fe5d4ca Binary files /dev/null and b/docs/_static/images/1u_vyos_front_10ge_open_2.webp 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 deleted file mode 100644 index c102b903..00000000 Binary files a/docs/_static/images/1u_vyos_front_10ge_open_3.jpg and /dev/null differ diff --git a/docs/_static/images/1u_vyos_front_10ge_open_3.webp b/docs/_static/images/1u_vyos_front_10ge_open_3.webp new file mode 100644 index 00000000..2200b448 Binary files /dev/null and b/docs/_static/images/1u_vyos_front_10ge_open_3.webp 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 deleted file mode 100644 index 2f270b7e..00000000 Binary files a/docs/_static/images/1u_vyos_front_10ge_open_4.jpg and /dev/null differ diff --git a/docs/_static/images/1u_vyos_front_10ge_open_4.webp b/docs/_static/images/1u_vyos_front_10ge_open_4.webp new file mode 100644 index 00000000..fd4a43c7 Binary files /dev/null and b/docs/_static/images/1u_vyos_front_10ge_open_4.webp differ diff --git a/docs/_static/images/1u_vyos_front_open_1.jpg b/docs/_static/images/1u_vyos_front_open_1.jpg deleted file mode 100644 index d90d565e..00000000 Binary files a/docs/_static/images/1u_vyos_front_open_1.jpg and /dev/null differ diff --git a/docs/_static/images/1u_vyos_front_open_1.webp b/docs/_static/images/1u_vyos_front_open_1.webp new file mode 100644 index 00000000..00006feb Binary files /dev/null and b/docs/_static/images/1u_vyos_front_open_1.webp differ diff --git a/docs/_static/images/1u_vyos_front_open_2.jpg b/docs/_static/images/1u_vyos_front_open_2.jpg deleted file mode 100644 index 6d112463..00000000 Binary files a/docs/_static/images/1u_vyos_front_open_2.jpg and /dev/null differ diff --git a/docs/_static/images/1u_vyos_front_open_2.webp b/docs/_static/images/1u_vyos_front_open_2.webp new file mode 100644 index 00000000..ad6fa807 Binary files /dev/null and b/docs/_static/images/1u_vyos_front_open_2.webp differ diff --git a/docs/_static/images/1u_vyos_front_open_3.jpg b/docs/_static/images/1u_vyos_front_open_3.jpg deleted file mode 100644 index 198ba3ce..00000000 Binary files a/docs/_static/images/1u_vyos_front_open_3.jpg and /dev/null differ diff --git a/docs/_static/images/1u_vyos_front_open_3.webp b/docs/_static/images/1u_vyos_front_open_3.webp new file mode 100644 index 00000000..15edf863 Binary files /dev/null and b/docs/_static/images/1u_vyos_front_open_3.webp differ diff --git a/docs/_static/images/480px-Acrosser_ANDJ190N1_Back.jpg b/docs/_static/images/480px-Acrosser_ANDJ190N1_Back.jpg deleted file mode 100644 index 6441c54a..00000000 Binary files a/docs/_static/images/480px-Acrosser_ANDJ190N1_Back.jpg and /dev/null differ diff --git a/docs/_static/images/480px-Acrosser_ANDJ190N1_Back.webp b/docs/_static/images/480px-Acrosser_ANDJ190N1_Back.webp new file mode 100644 index 00000000..10c350cc Binary files /dev/null and b/docs/_static/images/480px-Acrosser_ANDJ190N1_Back.webp differ diff --git a/docs/_static/images/480px-Acrosser_ANDJ190N1_Front.jpg b/docs/_static/images/480px-Acrosser_ANDJ190N1_Front.jpg deleted file mode 100644 index 5f216aa1..00000000 Binary files a/docs/_static/images/480px-Acrosser_ANDJ190N1_Front.jpg and /dev/null differ diff --git a/docs/_static/images/480px-Acrosser_ANDJ190N1_Front.webp b/docs/_static/images/480px-Acrosser_ANDJ190N1_Front.webp new file mode 100644 index 00000000..0ea695d4 Binary files /dev/null and b/docs/_static/images/480px-Acrosser_ANDJ190N1_Front.webp differ diff --git a/docs/_static/images/600px-Partaker-i5.jpg b/docs/_static/images/600px-Partaker-i5.jpg deleted file mode 100644 index 68196d41..00000000 Binary files a/docs/_static/images/600px-Partaker-i5.jpg and /dev/null differ diff --git a/docs/_static/images/600px-Partaker-i5.webp b/docs/_static/images/600px-Partaker-i5.webp new file mode 100644 index 00000000..d68d5afa Binary files /dev/null and b/docs/_static/images/600px-Partaker-i5.webp differ diff --git a/docs/_static/images/ESP_AH.png b/docs/_static/images/ESP_AH.png deleted file mode 100644 index 6075c3f4..00000000 Binary files a/docs/_static/images/ESP_AH.png and /dev/null differ diff --git a/docs/_static/images/ESP_AH.webp b/docs/_static/images/ESP_AH.webp new file mode 100644 index 00000000..1c70082e Binary files /dev/null and b/docs/_static/images/ESP_AH.webp differ diff --git a/docs/_static/images/IPSec_close_action_settings.png b/docs/_static/images/IPSec_close_action_settings.png deleted file mode 100644 index 531643f7..00000000 Binary files a/docs/_static/images/IPSec_close_action_settings.png and /dev/null differ diff --git a/docs/_static/images/IPSec_close_action_settings.webp b/docs/_static/images/IPSec_close_action_settings.webp new file mode 100644 index 00000000..6510ba7c Binary files /dev/null and b/docs/_static/images/IPSec_close_action_settings.webp differ diff --git a/docs/_static/images/L3VPN_hub_and_spoke.png b/docs/_static/images/L3VPN_hub_and_spoke.png deleted file mode 100644 index d442cc1a..00000000 Binary files a/docs/_static/images/L3VPN_hub_and_spoke.png and /dev/null differ diff --git a/docs/_static/images/L3VPN_hub_and_spoke.webp b/docs/_static/images/L3VPN_hub_and_spoke.webp new file mode 100644 index 00000000..2f3cafcd Binary files /dev/null and b/docs/_static/images/L3VPN_hub_and_spoke.webp differ diff --git a/docs/_static/images/PA-ESP-group.png b/docs/_static/images/PA-ESP-group.png deleted file mode 100644 index c6411b66..00000000 Binary files a/docs/_static/images/PA-ESP-group.png and /dev/null differ diff --git a/docs/_static/images/PA-ESP-group.webp b/docs/_static/images/PA-ESP-group.webp new file mode 100644 index 00000000..1802c511 Binary files /dev/null and b/docs/_static/images/PA-ESP-group.webp differ diff --git a/docs/_static/images/PA-IKE-GW-1.png b/docs/_static/images/PA-IKE-GW-1.png deleted file mode 100644 index 863eeb3a..00000000 Binary files a/docs/_static/images/PA-IKE-GW-1.png and /dev/null differ diff --git a/docs/_static/images/PA-IKE-GW-1.webp b/docs/_static/images/PA-IKE-GW-1.webp new file mode 100644 index 00000000..ce0a123d Binary files /dev/null and b/docs/_static/images/PA-IKE-GW-1.webp differ diff --git a/docs/_static/images/PA-IKE-GW-2.png b/docs/_static/images/PA-IKE-GW-2.png deleted file mode 100644 index 21a16055..00000000 Binary files a/docs/_static/images/PA-IKE-GW-2.png and /dev/null differ diff --git a/docs/_static/images/PA-IKE-GW-2.webp b/docs/_static/images/PA-IKE-GW-2.webp new file mode 100644 index 00000000..5facbc1e Binary files /dev/null and b/docs/_static/images/PA-IKE-GW-2.webp differ diff --git a/docs/_static/images/PA-IKE-group.png b/docs/_static/images/PA-IKE-group.png deleted file mode 100644 index 06fd535d..00000000 Binary files a/docs/_static/images/PA-IKE-group.png and /dev/null differ diff --git a/docs/_static/images/PA-IKE-group.webp b/docs/_static/images/PA-IKE-group.webp new file mode 100644 index 00000000..f244a3fa Binary files /dev/null and b/docs/_static/images/PA-IKE-group.webp differ diff --git a/docs/_static/images/PA-IPsec-tunnel.png b/docs/_static/images/PA-IPsec-tunnel.png deleted file mode 100644 index 2f8f4cb8..00000000 Binary files a/docs/_static/images/PA-IPsec-tunnel.png and /dev/null differ diff --git a/docs/_static/images/PA-IPsec-tunnel.webp b/docs/_static/images/PA-IPsec-tunnel.webp new file mode 100644 index 00000000..f8aac9b8 Binary files /dev/null and b/docs/_static/images/PA-IPsec-tunnel.webp differ diff --git a/docs/_static/images/PA-tunnel-1.png b/docs/_static/images/PA-tunnel-1.png deleted file mode 100644 index 3c99c6c7..00000000 Binary files a/docs/_static/images/PA-tunnel-1.png and /dev/null differ diff --git a/docs/_static/images/PA-tunnel-1.webp b/docs/_static/images/PA-tunnel-1.webp new file mode 100644 index 00000000..b72c9364 Binary files /dev/null and b/docs/_static/images/PA-tunnel-1.webp differ diff --git a/docs/_static/images/PA-tunnel-2.png b/docs/_static/images/PA-tunnel-2.png deleted file mode 100644 index 6f073513..00000000 Binary files a/docs/_static/images/PA-tunnel-2.png and /dev/null differ diff --git a/docs/_static/images/PA-tunnel-2.webp b/docs/_static/images/PA-tunnel-2.webp new file mode 100644 index 00000000..8b1bfbf8 Binary files /dev/null and b/docs/_static/images/PA-tunnel-2.webp differ diff --git a/docs/_static/images/PA-tunnel-3.png b/docs/_static/images/PA-tunnel-3.png deleted file mode 100644 index ca5a94e9..00000000 Binary files a/docs/_static/images/PA-tunnel-3.png and /dev/null differ diff --git a/docs/_static/images/PA-tunnel-3.webp b/docs/_static/images/PA-tunnel-3.webp new file mode 100644 index 00000000..098c3c4d Binary files /dev/null and b/docs/_static/images/PA-tunnel-3.webp differ diff --git a/docs/_static/images/VyOS_Dual-Hub_DMVPN.png b/docs/_static/images/VyOS_Dual-Hub_DMVPN.png deleted file mode 100644 index 9c25a308..00000000 Binary files a/docs/_static/images/VyOS_Dual-Hub_DMVPN.png and /dev/null differ diff --git a/docs/_static/images/VyOS_Dual-Hub_DMVPN.webp b/docs/_static/images/VyOS_Dual-Hub_DMVPN.webp new file mode 100644 index 00000000..71f6d5e5 Binary files /dev/null and b/docs/_static/images/VyOS_Dual-Hub_DMVPN.webp differ diff --git a/docs/_static/images/Wan_load_balancing1.png b/docs/_static/images/Wan_load_balancing1.png deleted file mode 100644 index bde1edb6..00000000 Binary files a/docs/_static/images/Wan_load_balancing1.png and /dev/null differ diff --git a/docs/_static/images/Wan_load_balancing1.webp b/docs/_static/images/Wan_load_balancing1.webp new file mode 100644 index 00000000..7efb6ab7 Binary files /dev/null and b/docs/_static/images/Wan_load_balancing1.webp differ diff --git a/docs/_static/images/Wan_load_balancing_exclude1.png b/docs/_static/images/Wan_load_balancing_exclude1.png deleted file mode 100644 index 1111535d..00000000 Binary files a/docs/_static/images/Wan_load_balancing_exclude1.png and /dev/null differ diff --git a/docs/_static/images/Wan_load_balancing_exclude1.webp b/docs/_static/images/Wan_load_balancing_exclude1.webp new file mode 100644 index 00000000..cc5fc4d1 Binary files /dev/null and b/docs/_static/images/Wan_load_balancing_exclude1.webp differ diff --git a/docs/_static/images/ansible.png b/docs/_static/images/ansible.png deleted file mode 100644 index 1d80b3f4..00000000 Binary files a/docs/_static/images/ansible.png and /dev/null differ diff --git a/docs/_static/images/ansible.webp b/docs/_static/images/ansible.webp new file mode 100644 index 00000000..746a46e8 Binary files /dev/null and b/docs/_static/images/ansible.webp differ diff --git a/docs/_static/images/apu4_desk_1.jpg b/docs/_static/images/apu4_desk_1.jpg deleted file mode 100644 index b7a3d08e..00000000 Binary files a/docs/_static/images/apu4_desk_1.jpg and /dev/null differ diff --git a/docs/_static/images/apu4_desk_1.webp b/docs/_static/images/apu4_desk_1.webp new file mode 100644 index 00000000..8298c3f2 Binary files /dev/null and b/docs/_static/images/apu4_desk_1.webp differ diff --git a/docs/_static/images/apu4_desk_2.jpg b/docs/_static/images/apu4_desk_2.jpg deleted file mode 100644 index fe356e1f..00000000 Binary files a/docs/_static/images/apu4_desk_2.jpg and /dev/null differ diff --git a/docs/_static/images/apu4_desk_2.webp b/docs/_static/images/apu4_desk_2.webp new file mode 100644 index 00000000..ccf54bb8 Binary files /dev/null and b/docs/_static/images/apu4_desk_2.webp differ diff --git a/docs/_static/images/apu4_desk_3.jpg b/docs/_static/images/apu4_desk_3.jpg deleted file mode 100644 index af7dc406..00000000 Binary files a/docs/_static/images/apu4_desk_3.jpg and /dev/null differ diff --git a/docs/_static/images/apu4_desk_3.webp b/docs/_static/images/apu4_desk_3.webp new file mode 100644 index 00000000..965ff112 Binary files /dev/null and b/docs/_static/images/apu4_desk_3.webp differ diff --git a/docs/_static/images/apu4_desk_4.jpg b/docs/_static/images/apu4_desk_4.jpg deleted file mode 100644 index 37251af2..00000000 Binary files a/docs/_static/images/apu4_desk_4.jpg and /dev/null differ diff --git a/docs/_static/images/apu4_desk_4.webp b/docs/_static/images/apu4_desk_4.webp new file mode 100644 index 00000000..2cbc2bd3 Binary files /dev/null and b/docs/_static/images/apu4_desk_4.webp differ diff --git a/docs/_static/images/apu4_rack_1.jpg b/docs/_static/images/apu4_rack_1.jpg deleted file mode 100644 index 3793cd39..00000000 Binary files a/docs/_static/images/apu4_rack_1.jpg and /dev/null differ diff --git a/docs/_static/images/apu4_rack_1.webp b/docs/_static/images/apu4_rack_1.webp new file mode 100644 index 00000000..c6bd9229 Binary files /dev/null and b/docs/_static/images/apu4_rack_1.webp differ diff --git a/docs/_static/images/apu4_rack_2.jpg b/docs/_static/images/apu4_rack_2.jpg deleted file mode 100644 index b8caf976..00000000 Binary files a/docs/_static/images/apu4_rack_2.jpg and /dev/null differ diff --git a/docs/_static/images/apu4_rack_2.webp b/docs/_static/images/apu4_rack_2.webp new file mode 100644 index 00000000..f2673488 Binary files /dev/null and b/docs/_static/images/apu4_rack_2.webp differ diff --git a/docs/_static/images/apu4_rack_3.jpg b/docs/_static/images/apu4_rack_3.jpg deleted file mode 100644 index 08ff633e..00000000 Binary files a/docs/_static/images/apu4_rack_3.jpg and /dev/null differ diff --git a/docs/_static/images/apu4_rack_3.webp b/docs/_static/images/apu4_rack_3.webp new file mode 100644 index 00000000..a12e7895 Binary files /dev/null and b/docs/_static/images/apu4_rack_3.webp differ diff --git a/docs/_static/images/apu4_rack_4.jpg b/docs/_static/images/apu4_rack_4.jpg deleted file mode 100644 index a88d62fe..00000000 Binary files a/docs/_static/images/apu4_rack_4.jpg and /dev/null differ diff --git a/docs/_static/images/apu4_rack_4.webp b/docs/_static/images/apu4_rack_4.webp new file mode 100644 index 00000000..a3ea439c Binary files /dev/null and b/docs/_static/images/apu4_rack_4.webp differ diff --git a/docs/_static/images/apu4_rack_5.jpg b/docs/_static/images/apu4_rack_5.jpg deleted file mode 100644 index 644b8e0a..00000000 Binary files a/docs/_static/images/apu4_rack_5.jpg and /dev/null differ diff --git a/docs/_static/images/apu4_rack_5.webp b/docs/_static/images/apu4_rack_5.webp new file mode 100644 index 00000000..8310600e Binary files /dev/null and b/docs/_static/images/apu4_rack_5.webp differ diff --git a/docs/_static/images/apu4_rack_vyos_print.jpg b/docs/_static/images/apu4_rack_vyos_print.jpg deleted file mode 100644 index a0bbaab2..00000000 Binary files a/docs/_static/images/apu4_rack_vyos_print.jpg and /dev/null differ diff --git a/docs/_static/images/apu4_rack_vyos_print.webp b/docs/_static/images/apu4_rack_vyos_print.webp new file mode 100644 index 00000000..61b14f3f Binary files /dev/null and b/docs/_static/images/apu4_rack_vyos_print.webp differ diff --git a/docs/_static/images/aws.png b/docs/_static/images/aws.png deleted file mode 100644 index c1c111bb..00000000 Binary files a/docs/_static/images/aws.png and /dev/null differ diff --git a/docs/_static/images/aws.webp b/docs/_static/images/aws.webp new file mode 100644 index 00000000..29fe0684 Binary files /dev/null and b/docs/_static/images/aws.webp differ diff --git a/docs/_static/images/blueprint-dmvpn.png b/docs/_static/images/blueprint-dmvpn.png deleted file mode 100644 index 85f189c1..00000000 Binary files a/docs/_static/images/blueprint-dmvpn.png and /dev/null differ diff --git a/docs/_static/images/blueprint-dmvpn.webp b/docs/_static/images/blueprint-dmvpn.webp new file mode 100644 index 00000000..8a3c38aa Binary files /dev/null and b/docs/_static/images/blueprint-dmvpn.webp differ diff --git a/docs/_static/images/boot-options.png b/docs/_static/images/boot-options.png deleted file mode 100644 index b00350bc..00000000 Binary files a/docs/_static/images/boot-options.png and /dev/null differ diff --git a/docs/_static/images/boot-options.webp b/docs/_static/images/boot-options.webp new file mode 100644 index 00000000..9616a336 Binary files /dev/null and b/docs/_static/images/boot-options.webp differ diff --git a/docs/_static/images/cisco-vpn-ipsec.png b/docs/_static/images/cisco-vpn-ipsec.png deleted file mode 100644 index bc19e8bc..00000000 Binary files a/docs/_static/images/cisco-vpn-ipsec.png and /dev/null differ diff --git a/docs/_static/images/cisco-vpn-ipsec.webp b/docs/_static/images/cisco-vpn-ipsec.webp new file mode 100644 index 00000000..45c570f0 Binary files /dev/null and b/docs/_static/images/cisco-vpn-ipsec.webp differ diff --git a/docs/_static/images/cloud-aws-01.png b/docs/_static/images/cloud-aws-01.png deleted file mode 100644 index cda6542f..00000000 Binary files a/docs/_static/images/cloud-aws-01.png and /dev/null differ diff --git a/docs/_static/images/cloud-aws-01.webp b/docs/_static/images/cloud-aws-01.webp new file mode 100644 index 00000000..94ce4b8f Binary files /dev/null and b/docs/_static/images/cloud-aws-01.webp differ diff --git a/docs/_static/images/cloud-aws-02.png b/docs/_static/images/cloud-aws-02.png deleted file mode 100644 index 639d42fa..00000000 Binary files a/docs/_static/images/cloud-aws-02.png and /dev/null differ diff --git a/docs/_static/images/cloud-aws-02.webp b/docs/_static/images/cloud-aws-02.webp new file mode 100644 index 00000000..ede125c1 Binary files /dev/null and b/docs/_static/images/cloud-aws-02.webp differ diff --git a/docs/_static/images/cloud-aws-03.png b/docs/_static/images/cloud-aws-03.png deleted file mode 100644 index 92d3e63b..00000000 Binary files a/docs/_static/images/cloud-aws-03.png and /dev/null differ diff --git a/docs/_static/images/cloud-aws-03.webp b/docs/_static/images/cloud-aws-03.webp new file mode 100644 index 00000000..d2789ff1 Binary files /dev/null and b/docs/_static/images/cloud-aws-03.webp differ diff --git a/docs/_static/images/cloud-aws-04.png b/docs/_static/images/cloud-aws-04.png deleted file mode 100644 index 3ae4fb2a..00000000 Binary files a/docs/_static/images/cloud-aws-04.png and /dev/null differ diff --git a/docs/_static/images/cloud-aws-04.webp b/docs/_static/images/cloud-aws-04.webp new file mode 100644 index 00000000..c42eca50 Binary files /dev/null and b/docs/_static/images/cloud-aws-04.webp differ diff --git a/docs/_static/images/cloud-aws-05.png b/docs/_static/images/cloud-aws-05.png deleted file mode 100644 index fa3521a6..00000000 Binary files a/docs/_static/images/cloud-aws-05.png and /dev/null differ diff --git a/docs/_static/images/cloud-aws-05.webp b/docs/_static/images/cloud-aws-05.webp new file mode 100644 index 00000000..8206cd66 Binary files /dev/null and b/docs/_static/images/cloud-aws-05.webp differ diff --git a/docs/_static/images/cloud-aws-06.png b/docs/_static/images/cloud-aws-06.png deleted file mode 100644 index c8f88ded..00000000 Binary files a/docs/_static/images/cloud-aws-06.png and /dev/null differ diff --git a/docs/_static/images/cloud-aws-06.webp b/docs/_static/images/cloud-aws-06.webp new file mode 100644 index 00000000..107ff785 Binary files /dev/null and b/docs/_static/images/cloud-aws-06.webp differ diff --git a/docs/_static/images/cloud-aws-07.png b/docs/_static/images/cloud-aws-07.png deleted file mode 100644 index d9f934ac..00000000 Binary files a/docs/_static/images/cloud-aws-07.png and /dev/null differ diff --git a/docs/_static/images/cloud-aws-07.webp b/docs/_static/images/cloud-aws-07.webp new file mode 100644 index 00000000..98dffd0b Binary files /dev/null and b/docs/_static/images/cloud-aws-07.webp differ diff --git a/docs/_static/images/cloud-aws-08.png b/docs/_static/images/cloud-aws-08.png deleted file mode 100644 index db3030a0..00000000 Binary files a/docs/_static/images/cloud-aws-08.png and /dev/null differ diff --git a/docs/_static/images/cloud-aws-08.webp b/docs/_static/images/cloud-aws-08.webp new file mode 100644 index 00000000..97fd28a1 Binary files /dev/null and b/docs/_static/images/cloud-aws-08.webp differ diff --git a/docs/_static/images/cloud-azure-01.png b/docs/_static/images/cloud-azure-01.png deleted file mode 100644 index 2c7b1adb..00000000 Binary files a/docs/_static/images/cloud-azure-01.png and /dev/null differ diff --git a/docs/_static/images/cloud-azure-01.webp b/docs/_static/images/cloud-azure-01.webp new file mode 100644 index 00000000..95ce6eef Binary files /dev/null and b/docs/_static/images/cloud-azure-01.webp differ diff --git a/docs/_static/images/cloud-azure-02.png b/docs/_static/images/cloud-azure-02.png deleted file mode 100644 index 286b8689..00000000 Binary files a/docs/_static/images/cloud-azure-02.png and /dev/null differ diff --git a/docs/_static/images/cloud-azure-02.webp b/docs/_static/images/cloud-azure-02.webp new file mode 100644 index 00000000..ad769a3c Binary files /dev/null and b/docs/_static/images/cloud-azure-02.webp differ diff --git a/docs/_static/images/cloud-azure-03.png b/docs/_static/images/cloud-azure-03.png deleted file mode 100644 index 4661a1fb..00000000 Binary files a/docs/_static/images/cloud-azure-03.png and /dev/null differ diff --git a/docs/_static/images/cloud-azure-03.webp b/docs/_static/images/cloud-azure-03.webp new file mode 100644 index 00000000..018f408a Binary files /dev/null and b/docs/_static/images/cloud-azure-03.webp differ diff --git a/docs/_static/images/cloud-azure-04.png b/docs/_static/images/cloud-azure-04.png deleted file mode 100644 index af12d337..00000000 Binary files a/docs/_static/images/cloud-azure-04.png and /dev/null differ diff --git a/docs/_static/images/cloud-azure-04.webp b/docs/_static/images/cloud-azure-04.webp new file mode 100644 index 00000000..e7bf1df9 Binary files /dev/null and b/docs/_static/images/cloud-azure-04.webp differ diff --git a/docs/_static/images/cloud-azure-05.png b/docs/_static/images/cloud-azure-05.png deleted file mode 100644 index c5a32d2e..00000000 Binary files a/docs/_static/images/cloud-azure-05.png and /dev/null differ diff --git a/docs/_static/images/cloud-azure-05.webp b/docs/_static/images/cloud-azure-05.webp new file mode 100644 index 00000000..280c58e8 Binary files /dev/null and b/docs/_static/images/cloud-azure-05.webp differ diff --git a/docs/_static/images/cloud-azure-06.png b/docs/_static/images/cloud-azure-06.png deleted file mode 100644 index 1cc7cbf1..00000000 Binary files a/docs/_static/images/cloud-azure-06.png and /dev/null differ diff --git a/docs/_static/images/cloud-azure-06.webp b/docs/_static/images/cloud-azure-06.webp new file mode 100644 index 00000000..0f0b8135 Binary files /dev/null and b/docs/_static/images/cloud-azure-06.webp differ diff --git a/docs/_static/images/cloud-gcp-01.png b/docs/_static/images/cloud-gcp-01.png deleted file mode 100644 index f7681d6e..00000000 Binary files a/docs/_static/images/cloud-gcp-01.png and /dev/null differ diff --git a/docs/_static/images/cloud-gcp-01.webp b/docs/_static/images/cloud-gcp-01.webp new file mode 100644 index 00000000..d21fc5ff Binary files /dev/null and b/docs/_static/images/cloud-gcp-01.webp differ diff --git a/docs/_static/images/cloud-gcp-02.png b/docs/_static/images/cloud-gcp-02.png deleted file mode 100644 index 5a17efb4..00000000 Binary files a/docs/_static/images/cloud-gcp-02.png and /dev/null differ diff --git a/docs/_static/images/cloud-gcp-02.webp b/docs/_static/images/cloud-gcp-02.webp new file mode 100644 index 00000000..977f411f Binary files /dev/null and b/docs/_static/images/cloud-gcp-02.webp differ diff --git a/docs/_static/images/cloud-gcp-03.png b/docs/_static/images/cloud-gcp-03.png deleted file mode 100644 index 9881a5a3..00000000 Binary files a/docs/_static/images/cloud-gcp-03.png and /dev/null differ diff --git a/docs/_static/images/cloud-gcp-03.webp b/docs/_static/images/cloud-gcp-03.webp new file mode 100644 index 00000000..dd3a410b Binary files /dev/null and b/docs/_static/images/cloud-gcp-03.webp differ diff --git a/docs/_static/images/cloud-gcp-04.png b/docs/_static/images/cloud-gcp-04.png deleted file mode 100644 index 61ee2d5e..00000000 Binary files a/docs/_static/images/cloud-gcp-04.png and /dev/null differ diff --git a/docs/_static/images/cloud-gcp-04.webp b/docs/_static/images/cloud-gcp-04.webp new file mode 100644 index 00000000..62e4380a Binary files /dev/null and b/docs/_static/images/cloud-gcp-04.webp differ diff --git a/docs/_static/images/cloud-gcp-05.png b/docs/_static/images/cloud-gcp-05.png deleted file mode 100644 index acaafc59..00000000 Binary files a/docs/_static/images/cloud-gcp-05.png and /dev/null differ diff --git a/docs/_static/images/cloud-gcp-05.webp b/docs/_static/images/cloud-gcp-05.webp new file mode 100644 index 00000000..92ed88b0 Binary files /dev/null and b/docs/_static/images/cloud-gcp-05.webp differ diff --git a/docs/_static/images/dhcp-relay-through-gre-bridge.png b/docs/_static/images/dhcp-relay-through-gre-bridge.png deleted file mode 100644 index 1f3e7744..00000000 Binary files a/docs/_static/images/dhcp-relay-through-gre-bridge.png and /dev/null differ diff --git a/docs/_static/images/dhcp-relay-through-gre-bridge.webp b/docs/_static/images/dhcp-relay-through-gre-bridge.webp new file mode 100644 index 00000000..4b626e91 Binary files /dev/null and b/docs/_static/images/dhcp-relay-through-gre-bridge.webp differ diff --git a/docs/_static/images/dual-hub-DMVPN.png b/docs/_static/images/dual-hub-DMVPN.png deleted file mode 100644 index 51ba9c14..00000000 Binary files a/docs/_static/images/dual-hub-DMVPN.png and /dev/null differ diff --git a/docs/_static/images/dual-hub-DMVPN.webp b/docs/_static/images/dual-hub-DMVPN.webp new file mode 100644 index 00000000..db4a4afd Binary files /dev/null and b/docs/_static/images/dual-hub-DMVPN.webp differ diff --git a/docs/_static/images/eve-ng-vyos.png b/docs/_static/images/eve-ng-vyos.png deleted file mode 100644 index fdd196a7..00000000 Binary files a/docs/_static/images/eve-ng-vyos.png and /dev/null differ diff --git a/docs/_static/images/eve-ng-vyos.webp b/docs/_static/images/eve-ng-vyos.webp new file mode 100644 index 00000000..f68b2fba Binary files /dev/null and b/docs/_static/images/eve-ng-vyos.webp differ diff --git a/docs/_static/images/firewall-and-vrf-blueprints.png b/docs/_static/images/firewall-and-vrf-blueprints.png deleted file mode 100644 index 8c3bf9f2..00000000 Binary files a/docs/_static/images/firewall-and-vrf-blueprints.png and /dev/null differ diff --git a/docs/_static/images/firewall-and-vrf-blueprints.webp b/docs/_static/images/firewall-and-vrf-blueprints.webp new file mode 100644 index 00000000..17194880 Binary files /dev/null and b/docs/_static/images/firewall-and-vrf-blueprints.webp differ diff --git a/docs/_static/images/firewall-bridge-forward.png b/docs/_static/images/firewall-bridge-forward.png deleted file mode 100644 index 1294349b..00000000 Binary files a/docs/_static/images/firewall-bridge-forward.png and /dev/null differ diff --git a/docs/_static/images/firewall-bridge-forward.webp b/docs/_static/images/firewall-bridge-forward.webp new file mode 100644 index 00000000..2fde5f14 Binary files /dev/null and b/docs/_static/images/firewall-bridge-forward.webp differ diff --git a/docs/_static/images/firewall-bridge-input.png b/docs/_static/images/firewall-bridge-input.png deleted file mode 100644 index 20a46b2e..00000000 Binary files a/docs/_static/images/firewall-bridge-input.png and /dev/null differ diff --git a/docs/_static/images/firewall-bridge-input.webp b/docs/_static/images/firewall-bridge-input.webp new file mode 100644 index 00000000..1666bff9 Binary files /dev/null and b/docs/_static/images/firewall-bridge-input.webp differ diff --git a/docs/_static/images/firewall-bridge-output.png b/docs/_static/images/firewall-bridge-output.png deleted file mode 100644 index ab2fd3d7..00000000 Binary files a/docs/_static/images/firewall-bridge-output.png and /dev/null differ diff --git a/docs/_static/images/firewall-bridge-output.webp b/docs/_static/images/firewall-bridge-output.webp new file mode 100644 index 00000000..98bb580f Binary files /dev/null and b/docs/_static/images/firewall-bridge-output.webp differ diff --git a/docs/_static/images/firewall-flowtable-packet-flow.png b/docs/_static/images/firewall-flowtable-packet-flow.png deleted file mode 100644 index fca7e13a..00000000 Binary files a/docs/_static/images/firewall-flowtable-packet-flow.png and /dev/null differ diff --git a/docs/_static/images/firewall-flowtable-packet-flow.webp b/docs/_static/images/firewall-flowtable-packet-flow.webp new file mode 100644 index 00000000..6d20ab7a Binary files /dev/null and b/docs/_static/images/firewall-flowtable-packet-flow.webp differ diff --git a/docs/_static/images/firewall-fwd-packet-flow.png b/docs/_static/images/firewall-fwd-packet-flow.png deleted file mode 100644 index 1ca213e8..00000000 Binary files a/docs/_static/images/firewall-fwd-packet-flow.png and /dev/null differ diff --git a/docs/_static/images/firewall-fwd-packet-flow.webp b/docs/_static/images/firewall-fwd-packet-flow.webp new file mode 100644 index 00000000..31b155a9 Binary files /dev/null and b/docs/_static/images/firewall-fwd-packet-flow.webp differ diff --git a/docs/_static/images/firewall-gral-packet-flow.png b/docs/_static/images/firewall-gral-packet-flow.png deleted file mode 100644 index 4fb5d516..00000000 Binary files a/docs/_static/images/firewall-gral-packet-flow.png and /dev/null differ diff --git a/docs/_static/images/firewall-gral-packet-flow.webp b/docs/_static/images/firewall-gral-packet-flow.webp new file mode 100644 index 00000000..add21b1e Binary files /dev/null and b/docs/_static/images/firewall-gral-packet-flow.webp differ diff --git a/docs/_static/images/firewall-input-packet-flow.png b/docs/_static/images/firewall-input-packet-flow.png deleted file mode 100644 index 20d356bd..00000000 Binary files a/docs/_static/images/firewall-input-packet-flow.png and /dev/null differ diff --git a/docs/_static/images/firewall-input-packet-flow.webp b/docs/_static/images/firewall-input-packet-flow.webp new file mode 100644 index 00000000..a5f207a1 Binary files /dev/null and b/docs/_static/images/firewall-input-packet-flow.webp differ diff --git a/docs/_static/images/firewall-netfilter.png b/docs/_static/images/firewall-netfilter.png deleted file mode 100644 index dde3766b..00000000 Binary files a/docs/_static/images/firewall-netfilter.png and /dev/null differ diff --git a/docs/_static/images/firewall-netfilter.webp b/docs/_static/images/firewall-netfilter.webp new file mode 100644 index 00000000..0706a660 Binary files /dev/null and b/docs/_static/images/firewall-netfilter.webp differ diff --git a/docs/_static/images/firewall-traditional.png b/docs/_static/images/firewall-traditional.png deleted file mode 100644 index 7eb2b49d..00000000 Binary files a/docs/_static/images/firewall-traditional.png and /dev/null differ diff --git a/docs/_static/images/firewall-traditional.webp b/docs/_static/images/firewall-traditional.webp new file mode 100644 index 00000000..2804393f Binary files /dev/null and b/docs/_static/images/firewall-traditional.webp differ diff --git a/docs/_static/images/firewall-zonebased.png b/docs/_static/images/firewall-zonebased.png deleted file mode 100644 index 46b2f623..00000000 Binary files a/docs/_static/images/firewall-zonebased.png and /dev/null differ diff --git a/docs/_static/images/firewall-zonebased.webp b/docs/_static/images/firewall-zonebased.webp new file mode 100644 index 00000000..11394be0 Binary files /dev/null and b/docs/_static/images/firewall-zonebased.webp differ diff --git a/docs/_static/images/gns3-01.png b/docs/_static/images/gns3-01.png deleted file mode 100644 index a655d6aa..00000000 Binary files a/docs/_static/images/gns3-01.png and /dev/null differ diff --git a/docs/_static/images/gns3-01.webp b/docs/_static/images/gns3-01.webp new file mode 100644 index 00000000..d0d48d26 Binary files /dev/null and b/docs/_static/images/gns3-01.webp differ diff --git a/docs/_static/images/gns3-02.png b/docs/_static/images/gns3-02.png deleted file mode 100644 index 3dffdd2b..00000000 Binary files a/docs/_static/images/gns3-02.png and /dev/null differ diff --git a/docs/_static/images/gns3-02.webp b/docs/_static/images/gns3-02.webp new file mode 100644 index 00000000..83ec7546 Binary files /dev/null and b/docs/_static/images/gns3-02.webp differ diff --git a/docs/_static/images/gns3-03.png b/docs/_static/images/gns3-03.png deleted file mode 100644 index fcab6c5d..00000000 Binary files a/docs/_static/images/gns3-03.png and /dev/null differ diff --git a/docs/_static/images/gns3-03.webp b/docs/_static/images/gns3-03.webp new file mode 100644 index 00000000..aab36829 Binary files /dev/null and b/docs/_static/images/gns3-03.webp differ diff --git a/docs/_static/images/gns3-04.png b/docs/_static/images/gns3-04.png deleted file mode 100644 index afc30131..00000000 Binary files a/docs/_static/images/gns3-04.png and /dev/null differ diff --git a/docs/_static/images/gns3-04.webp b/docs/_static/images/gns3-04.webp new file mode 100644 index 00000000..722789bb Binary files /dev/null and b/docs/_static/images/gns3-04.webp differ diff --git a/docs/_static/images/gns3-05.png b/docs/_static/images/gns3-05.png deleted file mode 100644 index fee0dc65..00000000 Binary files a/docs/_static/images/gns3-05.png and /dev/null differ diff --git a/docs/_static/images/gns3-05.webp b/docs/_static/images/gns3-05.webp new file mode 100644 index 00000000..db42dd62 Binary files /dev/null and b/docs/_static/images/gns3-05.webp differ diff --git a/docs/_static/images/gns3-06.png b/docs/_static/images/gns3-06.png deleted file mode 100644 index c03cd89f..00000000 Binary files a/docs/_static/images/gns3-06.png and /dev/null differ diff --git a/docs/_static/images/gns3-06.webp b/docs/_static/images/gns3-06.webp new file mode 100644 index 00000000..b41d774c Binary files /dev/null and b/docs/_static/images/gns3-06.webp differ diff --git a/docs/_static/images/gns3-07.png b/docs/_static/images/gns3-07.png deleted file mode 100644 index 89d0a565..00000000 Binary files a/docs/_static/images/gns3-07.png and /dev/null differ diff --git a/docs/_static/images/gns3-07.webp b/docs/_static/images/gns3-07.webp new file mode 100644 index 00000000..360644f8 Binary files /dev/null and b/docs/_static/images/gns3-07.webp differ diff --git a/docs/_static/images/gns3-08.png b/docs/_static/images/gns3-08.png deleted file mode 100644 index aca0ff8a..00000000 Binary files a/docs/_static/images/gns3-08.png and /dev/null differ diff --git a/docs/_static/images/gns3-08.webp b/docs/_static/images/gns3-08.webp new file mode 100644 index 00000000..d7a8f3c3 Binary files /dev/null and b/docs/_static/images/gns3-08.webp differ diff --git a/docs/_static/images/gns3-09.png b/docs/_static/images/gns3-09.png deleted file mode 100644 index 7ae38c30..00000000 Binary files a/docs/_static/images/gns3-09.png and /dev/null differ diff --git a/docs/_static/images/gns3-09.webp b/docs/_static/images/gns3-09.webp new file mode 100644 index 00000000..b68dfdab Binary files /dev/null and b/docs/_static/images/gns3-09.webp differ diff --git a/docs/_static/images/gns3-10.png b/docs/_static/images/gns3-10.png deleted file mode 100644 index 1ee70d58..00000000 Binary files a/docs/_static/images/gns3-10.png and /dev/null differ diff --git a/docs/_static/images/gns3-10.webp b/docs/_static/images/gns3-10.webp new file mode 100644 index 00000000..61ab6d4e Binary files /dev/null and b/docs/_static/images/gns3-10.webp differ diff --git a/docs/_static/images/gns3-11.png b/docs/_static/images/gns3-11.png deleted file mode 100644 index 7990c73a..00000000 Binary files a/docs/_static/images/gns3-11.png and /dev/null differ diff --git a/docs/_static/images/gns3-11.webp b/docs/_static/images/gns3-11.webp new file mode 100644 index 00000000..efac5bb7 Binary files /dev/null and b/docs/_static/images/gns3-11.webp differ diff --git a/docs/_static/images/gns3-12.png b/docs/_static/images/gns3-12.png deleted file mode 100644 index 9ad51f70..00000000 Binary files a/docs/_static/images/gns3-12.png and /dev/null differ diff --git a/docs/_static/images/gns3-12.webp b/docs/_static/images/gns3-12.webp new file mode 100644 index 00000000..f0760510 Binary files /dev/null and b/docs/_static/images/gns3-12.webp differ diff --git a/docs/_static/images/gns3-13.png b/docs/_static/images/gns3-13.png deleted file mode 100644 index 5f9dd783..00000000 Binary files a/docs/_static/images/gns3-13.png and /dev/null differ diff --git a/docs/_static/images/gns3-13.webp b/docs/_static/images/gns3-13.webp new file mode 100644 index 00000000..a246380e Binary files /dev/null and b/docs/_static/images/gns3-13.webp differ diff --git a/docs/_static/images/gns3-14.png b/docs/_static/images/gns3-14.png deleted file mode 100644 index 447fcafe..00000000 Binary files a/docs/_static/images/gns3-14.png and /dev/null differ diff --git a/docs/_static/images/gns3-14.webp b/docs/_static/images/gns3-14.webp new file mode 100644 index 00000000..7e111c58 Binary files /dev/null and b/docs/_static/images/gns3-14.webp differ diff --git a/docs/_static/images/gns3-15.png b/docs/_static/images/gns3-15.png deleted file mode 100644 index 956b9edb..00000000 Binary files a/docs/_static/images/gns3-15.png and /dev/null differ diff --git a/docs/_static/images/gns3-15.webp b/docs/_static/images/gns3-15.webp new file mode 100644 index 00000000..79e7e6db Binary files /dev/null and b/docs/_static/images/gns3-15.webp differ diff --git a/docs/_static/images/gns3-16.png b/docs/_static/images/gns3-16.png deleted file mode 100644 index 4f75ffab..00000000 Binary files a/docs/_static/images/gns3-16.png and /dev/null differ diff --git a/docs/_static/images/gns3-16.webp b/docs/_static/images/gns3-16.webp new file mode 100644 index 00000000..423503ed Binary files /dev/null and b/docs/_static/images/gns3-16.webp differ diff --git a/docs/_static/images/gns3-17.png b/docs/_static/images/gns3-17.png deleted file mode 100644 index 64eff002..00000000 Binary files a/docs/_static/images/gns3-17.png and /dev/null differ diff --git a/docs/_static/images/gns3-17.webp b/docs/_static/images/gns3-17.webp new file mode 100644 index 00000000..8b7e5c01 Binary files /dev/null and b/docs/_static/images/gns3-17.webp differ diff --git a/docs/_static/images/gns3-20.png b/docs/_static/images/gns3-20.png deleted file mode 100644 index 17d92dea..00000000 Binary files a/docs/_static/images/gns3-20.png and /dev/null differ diff --git a/docs/_static/images/gns3-20.webp b/docs/_static/images/gns3-20.webp new file mode 100644 index 00000000..a65c47b4 Binary files /dev/null and b/docs/_static/images/gns3-20.webp differ diff --git a/docs/_static/images/gns3-21.png b/docs/_static/images/gns3-21.png deleted file mode 100644 index e461016a..00000000 Binary files a/docs/_static/images/gns3-21.png and /dev/null differ diff --git a/docs/_static/images/gns3-21.webp b/docs/_static/images/gns3-21.webp new file mode 100644 index 00000000..adc71baa Binary files /dev/null and b/docs/_static/images/gns3-21.webp differ diff --git a/docs/_static/images/gns3-215.png b/docs/_static/images/gns3-215.png deleted file mode 100644 index fde268ba..00000000 Binary files a/docs/_static/images/gns3-215.png and /dev/null differ diff --git a/docs/_static/images/gns3-215.webp b/docs/_static/images/gns3-215.webp new file mode 100644 index 00000000..49755246 Binary files /dev/null and b/docs/_static/images/gns3-215.webp differ diff --git a/docs/_static/images/gns3-22.png b/docs/_static/images/gns3-22.png deleted file mode 100644 index 6ed52c1d..00000000 Binary files a/docs/_static/images/gns3-22.png and /dev/null differ diff --git a/docs/_static/images/gns3-22.webp b/docs/_static/images/gns3-22.webp new file mode 100644 index 00000000..90bc4fa4 Binary files /dev/null and b/docs/_static/images/gns3-22.webp differ diff --git a/docs/_static/images/gowin-01.png b/docs/_static/images/gowin-01.png deleted file mode 100644 index 403ce52a..00000000 Binary files a/docs/_static/images/gowin-01.png and /dev/null differ diff --git a/docs/_static/images/gowin-01.webp b/docs/_static/images/gowin-01.webp new file mode 100644 index 00000000..048252d3 Binary files /dev/null and b/docs/_static/images/gowin-01.webp differ diff --git a/docs/_static/images/gowin-02.png b/docs/_static/images/gowin-02.png deleted file mode 100644 index 413f2948..00000000 Binary files a/docs/_static/images/gowin-02.png and /dev/null differ diff --git a/docs/_static/images/gowin-02.webp b/docs/_static/images/gowin-02.webp new file mode 100644 index 00000000..816c178c Binary files /dev/null and b/docs/_static/images/gowin-02.webp differ diff --git a/docs/_static/images/gowin-03.png b/docs/_static/images/gowin-03.png deleted file mode 100644 index fbdbb142..00000000 Binary files a/docs/_static/images/gowin-03.png and /dev/null differ diff --git a/docs/_static/images/gowin-03.webp b/docs/_static/images/gowin-03.webp new file mode 100644 index 00000000..ebf67368 Binary files /dev/null and b/docs/_static/images/gowin-03.webp differ diff --git a/docs/_static/images/gowin-04.png b/docs/_static/images/gowin-04.png deleted file mode 100644 index c68b8731..00000000 Binary files a/docs/_static/images/gowin-04.png and /dev/null differ diff --git a/docs/_static/images/gowin-04.webp b/docs/_static/images/gowin-04.webp new file mode 100644 index 00000000..b5e94a84 Binary files /dev/null and b/docs/_static/images/gowin-04.webp differ diff --git a/docs/_static/images/inter-vrf-routing-vrf-lite.png b/docs/_static/images/inter-vrf-routing-vrf-lite.png deleted file mode 100644 index 3acefee6..00000000 Binary files a/docs/_static/images/inter-vrf-routing-vrf-lite.png and /dev/null differ diff --git a/docs/_static/images/inter-vrf-routing-vrf-lite.webp b/docs/_static/images/inter-vrf-routing-vrf-lite.webp new file mode 100644 index 00000000..43394ec5 Binary files /dev/null and b/docs/_static/images/inter-vrf-routing-vrf-lite.webp differ diff --git a/docs/_static/images/ipsec-vyos-pa.png b/docs/_static/images/ipsec-vyos-pa.png deleted file mode 100644 index 0929bcc7..00000000 Binary files a/docs/_static/images/ipsec-vyos-pa.png and /dev/null differ diff --git a/docs/_static/images/ipsec-vyos-pa.webp b/docs/_static/images/ipsec-vyos-pa.webp new file mode 100644 index 00000000..1758d65c Binary files /dev/null and b/docs/_static/images/ipsec-vyos-pa.webp differ diff --git a/docs/_static/images/json.png b/docs/_static/images/json.png deleted file mode 100644 index 6c884e8e..00000000 Binary files a/docs/_static/images/json.png and /dev/null differ diff --git a/docs/_static/images/json.webp b/docs/_static/images/json.webp new file mode 100644 index 00000000..2dd0460f Binary files /dev/null and b/docs/_static/images/json.webp differ diff --git a/docs/_static/images/key.png b/docs/_static/images/key.png deleted file mode 100644 index 7d9366f4..00000000 Binary files a/docs/_static/images/key.png and /dev/null differ diff --git a/docs/_static/images/key.webp b/docs/_static/images/key.webp new file mode 100644 index 00000000..24fcceca Binary files /dev/null and b/docs/_static/images/key.webp differ diff --git a/docs/_static/images/keypairs.png b/docs/_static/images/keypairs.png deleted file mode 100644 index 7e772ae9..00000000 Binary files a/docs/_static/images/keypairs.png and /dev/null differ diff --git a/docs/_static/images/keypairs.webp b/docs/_static/images/keypairs.webp new file mode 100644 index 00000000..14df4da3 Binary files /dev/null and b/docs/_static/images/keypairs.webp differ diff --git a/docs/_static/images/lac-lns-diagram.jpg b/docs/_static/images/lac-lns-diagram.jpg deleted file mode 100644 index 4463a3c3..00000000 Binary files a/docs/_static/images/lac-lns-diagram.jpg and /dev/null differ diff --git a/docs/_static/images/lac-lns-diagram.webp b/docs/_static/images/lac-lns-diagram.webp new file mode 100644 index 00000000..0ce052c2 Binary files /dev/null and b/docs/_static/images/lac-lns-diagram.webp differ diff --git a/docs/_static/images/lac-lns-winclient.jpg b/docs/_static/images/lac-lns-winclient.jpg deleted file mode 100644 index 9fa99152..00000000 Binary files a/docs/_static/images/lac-lns-winclient.jpg and /dev/null differ diff --git a/docs/_static/images/lac-lns-winclient.webp b/docs/_static/images/lac-lns-winclient.webp new file mode 100644 index 00000000..95792cad Binary files /dev/null and b/docs/_static/images/lac-lns-winclient.webp differ diff --git a/docs/_static/images/ldapone.png b/docs/_static/images/ldapone.png deleted file mode 100644 index 33ecf628..00000000 Binary files a/docs/_static/images/ldapone.png and /dev/null differ diff --git a/docs/_static/images/ldapone.webp b/docs/_static/images/ldapone.webp new file mode 100644 index 00000000..0f070454 Binary files /dev/null and b/docs/_static/images/ldapone.webp differ diff --git a/docs/_static/images/ldaptwo.png b/docs/_static/images/ldaptwo.png deleted file mode 100644 index 7cb9e0cb..00000000 Binary files a/docs/_static/images/ldaptwo.png and /dev/null differ diff --git a/docs/_static/images/ldaptwo.webp b/docs/_static/images/ldaptwo.webp new file mode 100644 index 00000000..9ee636df Binary files /dev/null and b/docs/_static/images/ldaptwo.webp differ diff --git a/docs/_static/images/mainschema.png b/docs/_static/images/mainschema.png deleted file mode 100644 index c39e5da2..00000000 Binary files a/docs/_static/images/mainschema.png and /dev/null differ diff --git a/docs/_static/images/mainschema.webp b/docs/_static/images/mainschema.webp new file mode 100644 index 00000000..c9db82ca Binary files /dev/null and b/docs/_static/images/mainschema.webp differ diff --git a/docs/_static/images/multicast-basic.png b/docs/_static/images/multicast-basic.png deleted file mode 100644 index 3d4a3de3..00000000 Binary files a/docs/_static/images/multicast-basic.png and /dev/null differ diff --git a/docs/_static/images/multicast-basic.webp b/docs/_static/images/multicast-basic.webp new file mode 100644 index 00000000..8e963421 Binary files /dev/null and b/docs/_static/images/multicast-basic.webp differ diff --git a/docs/_static/images/nat_before_vpn_topology.png b/docs/_static/images/nat_before_vpn_topology.png deleted file mode 100644 index ae23c92d..00000000 Binary files a/docs/_static/images/nat_before_vpn_topology.png and /dev/null differ diff --git a/docs/_static/images/nat_before_vpn_topology.webp b/docs/_static/images/nat_before_vpn_topology.webp new file mode 100644 index 00000000..7f93a3d8 Binary files /dev/null and b/docs/_static/images/nat_before_vpn_topology.webp differ diff --git a/docs/_static/images/nmp1.png b/docs/_static/images/nmp1.png deleted file mode 100644 index 0b761a76..00000000 Binary files a/docs/_static/images/nmp1.png and /dev/null differ diff --git a/docs/_static/images/nmp1.webp b/docs/_static/images/nmp1.webp new file mode 100644 index 00000000..60035421 Binary files /dev/null and b/docs/_static/images/nmp1.webp differ diff --git a/docs/_static/images/nmp2.png b/docs/_static/images/nmp2.png deleted file mode 100644 index 3190a099..00000000 Binary files a/docs/_static/images/nmp2.png and /dev/null differ diff --git a/docs/_static/images/nmp2.webp b/docs/_static/images/nmp2.webp new file mode 100644 index 00000000..6dbf4d42 Binary files /dev/null and b/docs/_static/images/nmp2.webp differ diff --git a/docs/_static/images/nmp3.png b/docs/_static/images/nmp3.png deleted file mode 100644 index 0585b80e..00000000 Binary files a/docs/_static/images/nmp3.png and /dev/null differ diff --git a/docs/_static/images/nmp3.webp b/docs/_static/images/nmp3.webp new file mode 100644 index 00000000..72ab7050 Binary files /dev/null and b/docs/_static/images/nmp3.webp differ diff --git a/docs/_static/images/nmp4.png b/docs/_static/images/nmp4.png deleted file mode 100644 index e0aa893e..00000000 Binary files a/docs/_static/images/nmp4.png and /dev/null differ diff --git a/docs/_static/images/nmp4.webp b/docs/_static/images/nmp4.webp new file mode 100644 index 00000000..d7684b38 Binary files /dev/null and b/docs/_static/images/nmp4.webp differ diff --git a/docs/_static/images/nmp5.png b/docs/_static/images/nmp5.png deleted file mode 100644 index d3149034..00000000 Binary files a/docs/_static/images/nmp5.png and /dev/null differ diff --git a/docs/_static/images/nmp5.webp b/docs/_static/images/nmp5.webp new file mode 100644 index 00000000..6c64707c Binary files /dev/null and b/docs/_static/images/nmp5.webp differ diff --git a/docs/_static/images/nmp6.png b/docs/_static/images/nmp6.png deleted file mode 100644 index c4645e33..00000000 Binary files a/docs/_static/images/nmp6.png and /dev/null differ diff --git a/docs/_static/images/nmp6.webp b/docs/_static/images/nmp6.webp new file mode 100644 index 00000000..85141b11 Binary files /dev/null and b/docs/_static/images/nmp6.webp differ diff --git a/docs/_static/images/nmp7.png b/docs/_static/images/nmp7.png deleted file mode 100644 index 3e518e7e..00000000 Binary files a/docs/_static/images/nmp7.png and /dev/null differ diff --git a/docs/_static/images/nmp7.webp b/docs/_static/images/nmp7.webp new file mode 100644 index 00000000..6f64df83 Binary files /dev/null and b/docs/_static/images/nmp7.webp differ diff --git a/docs/_static/images/openvpn_site2site_diagram.jpg b/docs/_static/images/openvpn_site2site_diagram.jpg deleted file mode 100644 index 05881e7d..00000000 Binary files a/docs/_static/images/openvpn_site2site_diagram.jpg and /dev/null differ diff --git a/docs/_static/images/openvpn_site2site_diagram.webp b/docs/_static/images/openvpn_site2site_diagram.webp new file mode 100644 index 00000000..97d4df3f Binary files /dev/null and b/docs/_static/images/openvpn_site2site_diagram.webp differ diff --git a/docs/_static/images/pbr_example_1.png b/docs/_static/images/pbr_example_1.png deleted file mode 100644 index 3dff6db6..00000000 Binary files a/docs/_static/images/pbr_example_1.png and /dev/null differ diff --git a/docs/_static/images/pbr_example_1.webp b/docs/_static/images/pbr_example_1.webp new file mode 100644 index 00000000..4e8ba882 Binary files /dev/null and b/docs/_static/images/pbr_example_1.webp differ diff --git a/docs/_static/images/policy-based-ipsec-and-firewall.png b/docs/_static/images/policy-based-ipsec-and-firewall.png deleted file mode 100644 index 6e9d43ac..00000000 Binary files a/docs/_static/images/policy-based-ipsec-and-firewall.png and /dev/null differ diff --git a/docs/_static/images/policy-based-ipsec-and-firewall.webp b/docs/_static/images/policy-based-ipsec-and-firewall.webp new file mode 100644 index 00000000..2f57a305 Binary files /dev/null and b/docs/_static/images/policy-based-ipsec-and-firewall.webp differ diff --git a/docs/_static/images/pppoe-ipv6-pd-diagram.jpg b/docs/_static/images/pppoe-ipv6-pd-diagram.jpg deleted file mode 100644 index 430848c8..00000000 Binary files a/docs/_static/images/pppoe-ipv6-pd-diagram.jpg and /dev/null differ diff --git a/docs/_static/images/pppoe-ipv6-pd-diagram.webp b/docs/_static/images/pppoe-ipv6-pd-diagram.webp new file mode 100644 index 00000000..344bbf21 Binary files /dev/null and b/docs/_static/images/pppoe-ipv6-pd-diagram.webp differ diff --git a/docs/_static/images/project.png b/docs/_static/images/project.png deleted file mode 100644 index 6f844c23..00000000 Binary files a/docs/_static/images/project.png and /dev/null differ diff --git a/docs/_static/images/project.webp b/docs/_static/images/project.webp new file mode 100644 index 00000000..617375a2 Binary files /dev/null and b/docs/_static/images/project.webp differ diff --git a/docs/_static/images/qos1.png b/docs/_static/images/qos1.png deleted file mode 100644 index 9c16e6a3..00000000 Binary files a/docs/_static/images/qos1.png and /dev/null differ diff --git a/docs/_static/images/qos1.webp b/docs/_static/images/qos1.webp new file mode 100644 index 00000000..fe9264a6 Binary files /dev/null and b/docs/_static/images/qos1.webp differ diff --git a/docs/_static/images/qos10.png b/docs/_static/images/qos10.png deleted file mode 100644 index 2f90ffe7..00000000 Binary files a/docs/_static/images/qos10.png and /dev/null differ diff --git a/docs/_static/images/qos10.webp b/docs/_static/images/qos10.webp new file mode 100644 index 00000000..646ae67b Binary files /dev/null and b/docs/_static/images/qos10.webp differ diff --git a/docs/_static/images/qos2.png b/docs/_static/images/qos2.png deleted file mode 100644 index 4d351344..00000000 Binary files a/docs/_static/images/qos2.png and /dev/null differ diff --git a/docs/_static/images/qos2.webp b/docs/_static/images/qos2.webp new file mode 100644 index 00000000..7c8a1336 Binary files /dev/null and b/docs/_static/images/qos2.webp differ diff --git a/docs/_static/images/qos3.png b/docs/_static/images/qos3.png deleted file mode 100644 index 97efaeb7..00000000 Binary files a/docs/_static/images/qos3.png and /dev/null differ diff --git a/docs/_static/images/qos3.webp b/docs/_static/images/qos3.webp new file mode 100644 index 00000000..3cf2dd32 Binary files /dev/null and b/docs/_static/images/qos3.webp differ diff --git a/docs/_static/images/qos4.png b/docs/_static/images/qos4.png deleted file mode 100644 index b87b256e..00000000 Binary files a/docs/_static/images/qos4.png and /dev/null differ diff --git a/docs/_static/images/qos4.webp b/docs/_static/images/qos4.webp new file mode 100644 index 00000000..cc108ee8 Binary files /dev/null and b/docs/_static/images/qos4.webp differ diff --git a/docs/_static/images/qos5.png b/docs/_static/images/qos5.png deleted file mode 100644 index 4a615755..00000000 Binary files a/docs/_static/images/qos5.png and /dev/null differ diff --git a/docs/_static/images/qos5.webp b/docs/_static/images/qos5.webp new file mode 100644 index 00000000..d41ae04d Binary files /dev/null and b/docs/_static/images/qos5.webp differ diff --git a/docs/_static/images/qos6.png b/docs/_static/images/qos6.png deleted file mode 100644 index 907d6104..00000000 Binary files a/docs/_static/images/qos6.png and /dev/null differ diff --git a/docs/_static/images/qos6.webp b/docs/_static/images/qos6.webp new file mode 100644 index 00000000..7d238851 Binary files /dev/null and b/docs/_static/images/qos6.webp differ diff --git a/docs/_static/images/qos7.png b/docs/_static/images/qos7.png deleted file mode 100644 index 03ec5cd1..00000000 Binary files a/docs/_static/images/qos7.png and /dev/null differ diff --git a/docs/_static/images/qos7.webp b/docs/_static/images/qos7.webp new file mode 100644 index 00000000..026452c2 Binary files /dev/null and b/docs/_static/images/qos7.webp differ diff --git a/docs/_static/images/qos8.png b/docs/_static/images/qos8.png deleted file mode 100644 index 3566ac00..00000000 Binary files a/docs/_static/images/qos8.png and /dev/null differ diff --git a/docs/_static/images/qos8.webp b/docs/_static/images/qos8.webp new file mode 100644 index 00000000..e1706ce2 Binary files /dev/null and b/docs/_static/images/qos8.webp differ diff --git a/docs/_static/images/qos9.png b/docs/_static/images/qos9.png deleted file mode 100644 index 67d8afd2..00000000 Binary files a/docs/_static/images/qos9.png and /dev/null differ diff --git a/docs/_static/images/qos9.webp b/docs/_static/images/qos9.webp new file mode 100644 index 00000000..2cc6fdaa Binary files /dev/null and b/docs/_static/images/qos9.webp differ diff --git a/docs/_static/images/reset-password-step-1.jpg b/docs/_static/images/reset-password-step-1.jpg deleted file mode 100644 index 3b6f7703..00000000 Binary files a/docs/_static/images/reset-password-step-1.jpg and /dev/null differ diff --git a/docs/_static/images/reset-password-step-1.webp b/docs/_static/images/reset-password-step-1.webp new file mode 100644 index 00000000..fb361d3b Binary files /dev/null and b/docs/_static/images/reset-password-step-1.webp differ diff --git a/docs/_static/images/reset-password-step-2.jpg b/docs/_static/images/reset-password-step-2.jpg deleted file mode 100644 index 265bc73b..00000000 Binary files a/docs/_static/images/reset-password-step-2.jpg and /dev/null differ diff --git a/docs/_static/images/reset-password-step-2.webp b/docs/_static/images/reset-password-step-2.webp new file mode 100644 index 00000000..66262a88 Binary files /dev/null and b/docs/_static/images/reset-password-step-2.webp differ diff --git a/docs/_static/images/reset-password-step-3.jpg b/docs/_static/images/reset-password-step-3.jpg deleted file mode 100644 index 98795757..00000000 Binary files a/docs/_static/images/reset-password-step-3.jpg and /dev/null differ diff --git a/docs/_static/images/reset-password-step-3.webp b/docs/_static/images/reset-password-step-3.webp new file mode 100644 index 00000000..ad6f2899 Binary files /dev/null and b/docs/_static/images/reset-password-step-3.webp differ diff --git a/docs/_static/images/reset-password-step-4.jpg b/docs/_static/images/reset-password-step-4.jpg deleted file mode 100644 index 6f70ea24..00000000 Binary files a/docs/_static/images/reset-password-step-4.jpg and /dev/null differ diff --git a/docs/_static/images/reset-password-step-4.webp b/docs/_static/images/reset-password-step-4.webp new file mode 100644 index 00000000..7dd5efa2 Binary files /dev/null and b/docs/_static/images/reset-password-step-4.webp differ diff --git a/docs/_static/images/reset-password-step-5.jpg b/docs/_static/images/reset-password-step-5.jpg deleted file mode 100644 index 70c586e2..00000000 Binary files a/docs/_static/images/reset-password-step-5.jpg and /dev/null differ diff --git a/docs/_static/images/reset-password-step-5.webp b/docs/_static/images/reset-password-step-5.webp new file mode 100644 index 00000000..b4702618 Binary files /dev/null and b/docs/_static/images/reset-password-step-5.webp differ diff --git a/docs/_static/images/service.png b/docs/_static/images/service.png deleted file mode 100644 index e2a9bbbc..00000000 Binary files a/docs/_static/images/service.png and /dev/null differ diff --git a/docs/_static/images/service.webp b/docs/_static/images/service.webp new file mode 100644 index 00000000..051cd9b1 Binary files /dev/null and b/docs/_static/images/service.webp differ diff --git a/docs/_static/images/service_conntrack_sync-schema.png b/docs/_static/images/service_conntrack_sync-schema.png deleted file mode 100644 index 1b5fe8fb..00000000 Binary files a/docs/_static/images/service_conntrack_sync-schema.png and /dev/null differ diff --git a/docs/_static/images/service_conntrack_sync-schema.webp b/docs/_static/images/service_conntrack_sync-schema.webp new file mode 100644 index 00000000..e347aa19 Binary files /dev/null and b/docs/_static/images/service_conntrack_sync-schema.webp differ diff --git a/docs/_static/images/service_dhcp-relay01.png b/docs/_static/images/service_dhcp-relay01.png deleted file mode 100644 index cd7f30cf..00000000 Binary files a/docs/_static/images/service_dhcp-relay01.png and /dev/null differ diff --git a/docs/_static/images/service_dhcp-relay01.webp b/docs/_static/images/service_dhcp-relay01.webp new file mode 100644 index 00000000..5fbfad3e Binary files /dev/null and b/docs/_static/images/service_dhcp-relay01.webp differ diff --git a/docs/_static/images/service_dhcpv6-relay01.png b/docs/_static/images/service_dhcpv6-relay01.png deleted file mode 100644 index 9a10a10f..00000000 Binary files a/docs/_static/images/service_dhcpv6-relay01.png and /dev/null differ diff --git a/docs/_static/images/service_dhcpv6-relay01.webp b/docs/_static/images/service_dhcpv6-relay01.webp new file mode 100644 index 00000000..1f72f51f Binary files /dev/null and b/docs/_static/images/service_dhcpv6-relay01.webp differ diff --git a/docs/_static/images/service_snmp_communication_principles_diagram.png b/docs/_static/images/service_snmp_communication_principles_diagram.png deleted file mode 100644 index eff2ce45..00000000 Binary files a/docs/_static/images/service_snmp_communication_principles_diagram.png and /dev/null differ diff --git a/docs/_static/images/service_snmp_communication_principles_diagram.webp b/docs/_static/images/service_snmp_communication_principles_diagram.webp new file mode 100644 index 00000000..abb18133 Binary files /dev/null and b/docs/_static/images/service_snmp_communication_principles_diagram.webp differ diff --git a/docs/_static/images/sg.png b/docs/_static/images/sg.png deleted file mode 100644 index 8be51e1f..00000000 Binary files a/docs/_static/images/sg.png and /dev/null differ diff --git a/docs/_static/images/sg.webp b/docs/_static/images/sg.webp new file mode 100644 index 00000000..5ee77e0d Binary files /dev/null and b/docs/_static/images/sg.webp differ diff --git a/docs/_static/images/sticky-connections.jpg b/docs/_static/images/sticky-connections.jpg deleted file mode 100644 index 25fd72a9..00000000 Binary files a/docs/_static/images/sticky-connections.jpg and /dev/null differ diff --git a/docs/_static/images/sticky-connections.webp b/docs/_static/images/sticky-connections.webp new file mode 100644 index 00000000..92e5b769 Binary files /dev/null and b/docs/_static/images/sticky-connections.webp differ diff --git a/docs/_static/images/traffic.png b/docs/_static/images/traffic.png deleted file mode 100644 index 74002b16..00000000 Binary files a/docs/_static/images/traffic.png and /dev/null differ diff --git a/docs/_static/images/traffic.webp b/docs/_static/images/traffic.webp new file mode 100644 index 00000000..f6f9e183 Binary files /dev/null and b/docs/_static/images/traffic.webp differ diff --git a/docs/_static/images/uefi_secureboot_01.png b/docs/_static/images/uefi_secureboot_01.png deleted file mode 100644 index 02ec56b0..00000000 Binary files a/docs/_static/images/uefi_secureboot_01.png and /dev/null differ diff --git a/docs/_static/images/uefi_secureboot_01.webp b/docs/_static/images/uefi_secureboot_01.webp new file mode 100644 index 00000000..dccf8964 Binary files /dev/null and b/docs/_static/images/uefi_secureboot_01.webp differ diff --git a/docs/_static/images/uefi_secureboot_02.png b/docs/_static/images/uefi_secureboot_02.png deleted file mode 100644 index 336d654d..00000000 Binary files a/docs/_static/images/uefi_secureboot_02.png and /dev/null differ diff --git a/docs/_static/images/uefi_secureboot_02.webp b/docs/_static/images/uefi_secureboot_02.webp new file mode 100644 index 00000000..e9175323 Binary files /dev/null and b/docs/_static/images/uefi_secureboot_02.webp differ diff --git a/docs/_static/images/uefi_secureboot_03.png b/docs/_static/images/uefi_secureboot_03.png deleted file mode 100644 index ff126842..00000000 Binary files a/docs/_static/images/uefi_secureboot_03.png and /dev/null differ diff --git a/docs/_static/images/uefi_secureboot_03.webp b/docs/_static/images/uefi_secureboot_03.webp new file mode 100644 index 00000000..bcc5143c Binary files /dev/null and b/docs/_static/images/uefi_secureboot_03.webp differ diff --git a/docs/_static/images/uefi_secureboot_04.png b/docs/_static/images/uefi_secureboot_04.png deleted file mode 100644 index 90242299..00000000 Binary files a/docs/_static/images/uefi_secureboot_04.png and /dev/null differ diff --git a/docs/_static/images/uefi_secureboot_04.webp b/docs/_static/images/uefi_secureboot_04.webp new file mode 100644 index 00000000..a84f426e Binary files /dev/null and b/docs/_static/images/uefi_secureboot_04.webp differ diff --git a/docs/_static/images/uefi_secureboot_05.png b/docs/_static/images/uefi_secureboot_05.png deleted file mode 100644 index b08cb946..00000000 Binary files a/docs/_static/images/uefi_secureboot_05.png and /dev/null differ diff --git a/docs/_static/images/uefi_secureboot_05.webp b/docs/_static/images/uefi_secureboot_05.webp new file mode 100644 index 00000000..0b3c4883 Binary files /dev/null and b/docs/_static/images/uefi_secureboot_05.webp differ diff --git a/docs/_static/images/uefi_secureboot_06.png b/docs/_static/images/uefi_secureboot_06.png deleted file mode 100644 index 784f0eed..00000000 Binary files a/docs/_static/images/uefi_secureboot_06.png and /dev/null differ diff --git a/docs/_static/images/uefi_secureboot_06.webp b/docs/_static/images/uefi_secureboot_06.webp new file mode 100644 index 00000000..4bcf4a2f Binary files /dev/null and b/docs/_static/images/uefi_secureboot_06.webp differ diff --git a/docs/_static/images/uefi_secureboot_07.png b/docs/_static/images/uefi_secureboot_07.png deleted file mode 100644 index 6ff450b4..00000000 Binary files a/docs/_static/images/uefi_secureboot_07.png and /dev/null differ diff --git a/docs/_static/images/uefi_secureboot_07.webp b/docs/_static/images/uefi_secureboot_07.webp new file mode 100644 index 00000000..13ba02d1 Binary files /dev/null and b/docs/_static/images/uefi_secureboot_07.webp differ diff --git a/docs/_static/images/virt-libvirt-01.png b/docs/_static/images/virt-libvirt-01.png deleted file mode 100644 index 06baea8e..00000000 Binary files a/docs/_static/images/virt-libvirt-01.png and /dev/null differ diff --git a/docs/_static/images/virt-libvirt-01.webp b/docs/_static/images/virt-libvirt-01.webp new file mode 100644 index 00000000..02498c96 Binary files /dev/null and b/docs/_static/images/virt-libvirt-01.webp differ diff --git a/docs/_static/images/virt-libvirt-02.png b/docs/_static/images/virt-libvirt-02.png deleted file mode 100644 index b6c4b379..00000000 Binary files a/docs/_static/images/virt-libvirt-02.png and /dev/null differ diff --git a/docs/_static/images/virt-libvirt-02.webp b/docs/_static/images/virt-libvirt-02.webp new file mode 100644 index 00000000..06ad10aa Binary files /dev/null and b/docs/_static/images/virt-libvirt-02.webp differ diff --git a/docs/_static/images/virt-libvirt-03.png b/docs/_static/images/virt-libvirt-03.png deleted file mode 100644 index ac3891f0..00000000 Binary files a/docs/_static/images/virt-libvirt-03.png and /dev/null differ diff --git a/docs/_static/images/virt-libvirt-03.webp b/docs/_static/images/virt-libvirt-03.webp new file mode 100644 index 00000000..e8beae0c Binary files /dev/null and b/docs/_static/images/virt-libvirt-03.webp differ diff --git a/docs/_static/images/virt-libvirt-04.png b/docs/_static/images/virt-libvirt-04.png deleted file mode 100644 index b1218597..00000000 Binary files a/docs/_static/images/virt-libvirt-04.png and /dev/null differ diff --git a/docs/_static/images/virt-libvirt-04.webp b/docs/_static/images/virt-libvirt-04.webp new file mode 100644 index 00000000..586cdedb Binary files /dev/null and b/docs/_static/images/virt-libvirt-04.webp differ diff --git a/docs/_static/images/virt-libvirt-05.png b/docs/_static/images/virt-libvirt-05.png deleted file mode 100644 index 5579c281..00000000 Binary files a/docs/_static/images/virt-libvirt-05.png and /dev/null differ diff --git a/docs/_static/images/virt-libvirt-05.webp b/docs/_static/images/virt-libvirt-05.webp new file mode 100644 index 00000000..65c57a3d Binary files /dev/null and b/docs/_static/images/virt-libvirt-05.webp differ diff --git a/docs/_static/images/virt-libvirt-06.png b/docs/_static/images/virt-libvirt-06.png deleted file mode 100644 index e0983d23..00000000 Binary files a/docs/_static/images/virt-libvirt-06.png and /dev/null differ diff --git a/docs/_static/images/virt-libvirt-06.webp b/docs/_static/images/virt-libvirt-06.webp new file mode 100644 index 00000000..da7a41a9 Binary files /dev/null and b/docs/_static/images/virt-libvirt-06.webp differ diff --git a/docs/_static/images/virt-libvirt-qc-01.png b/docs/_static/images/virt-libvirt-qc-01.png deleted file mode 100644 index 49867bd0..00000000 Binary files a/docs/_static/images/virt-libvirt-qc-01.png and /dev/null differ diff --git a/docs/_static/images/virt-libvirt-qc-01.webp b/docs/_static/images/virt-libvirt-qc-01.webp new file mode 100644 index 00000000..1b19ca60 Binary files /dev/null and b/docs/_static/images/virt-libvirt-qc-01.webp differ diff --git a/docs/_static/images/virt-libvirt-qc-02.png b/docs/_static/images/virt-libvirt-qc-02.png deleted file mode 100644 index a71b8f64..00000000 Binary files a/docs/_static/images/virt-libvirt-qc-02.png and /dev/null differ diff --git a/docs/_static/images/virt-libvirt-qc-02.webp b/docs/_static/images/virt-libvirt-qc-02.webp new file mode 100644 index 00000000..8281ebfb Binary files /dev/null and b/docs/_static/images/virt-libvirt-qc-02.webp differ diff --git a/docs/_static/images/virt-libvirt-qc-03.png b/docs/_static/images/virt-libvirt-qc-03.png deleted file mode 100644 index 4eefaa58..00000000 Binary files a/docs/_static/images/virt-libvirt-qc-03.png and /dev/null differ diff --git a/docs/_static/images/virt-libvirt-qc-03.webp b/docs/_static/images/virt-libvirt-qc-03.webp new file mode 100644 index 00000000..7dc4e7e8 Binary files /dev/null and b/docs/_static/images/virt-libvirt-qc-03.webp differ diff --git a/docs/_static/images/vpn_dmvpn_topology01.png b/docs/_static/images/vpn_dmvpn_topology01.png deleted file mode 100644 index 17433be6..00000000 Binary files a/docs/_static/images/vpn_dmvpn_topology01.png and /dev/null differ diff --git a/docs/_static/images/vpn_dmvpn_topology01.webp b/docs/_static/images/vpn_dmvpn_topology01.webp new file mode 100644 index 00000000..3da35995 Binary files /dev/null and b/docs/_static/images/vpn_dmvpn_topology01.webp differ diff --git a/docs/_static/images/vpn_s2s_ikev2.png b/docs/_static/images/vpn_s2s_ikev2.png deleted file mode 100644 index f8050e3a..00000000 Binary files a/docs/_static/images/vpn_s2s_ikev2.png and /dev/null differ diff --git a/docs/_static/images/vpn_s2s_ikev2.webp b/docs/_static/images/vpn_s2s_ikev2.webp new file mode 100644 index 00000000..615f689c Binary files /dev/null and b/docs/_static/images/vpn_s2s_ikev2.webp differ diff --git a/docs/_static/images/vpn_s2s_ikev2_c.png b/docs/_static/images/vpn_s2s_ikev2_c.png deleted file mode 100644 index 2d9e21b5..00000000 Binary files a/docs/_static/images/vpn_s2s_ikev2_c.png and /dev/null differ diff --git a/docs/_static/images/vpn_s2s_ikev2_c.webp b/docs/_static/images/vpn_s2s_ikev2_c.webp new file mode 100644 index 00000000..f572fc29 Binary files /dev/null and b/docs/_static/images/vpn_s2s_ikev2_c.webp differ diff --git a/docs/_static/images/vrf-example-topology-01.png b/docs/_static/images/vrf-example-topology-01.png deleted file mode 100644 index 57357509..00000000 Binary files a/docs/_static/images/vrf-example-topology-01.png and /dev/null differ diff --git a/docs/_static/images/vrf-example-topology-01.webp b/docs/_static/images/vrf-example-topology-01.webp new file mode 100644 index 00000000..696abad1 Binary files /dev/null and b/docs/_static/images/vrf-example-topology-01.webp differ diff --git a/docs/_static/images/vyos-downloads.png b/docs/_static/images/vyos-downloads.png deleted file mode 100644 index 6bad2b19..00000000 Binary files a/docs/_static/images/vyos-downloads.png and /dev/null differ diff --git a/docs/_static/images/vyos-downloads.webp b/docs/_static/images/vyos-downloads.webp new file mode 100644 index 00000000..9d446701 Binary files /dev/null and b/docs/_static/images/vyos-downloads.webp differ diff --git a/docs/_static/images/vyos-logo-icon.webp b/docs/_static/images/vyos-logo-icon.webp new file mode 100644 index 00000000..d2867b8c Binary files /dev/null and b/docs/_static/images/vyos-logo-icon.webp differ diff --git a/docs/_static/images/vyos-logo.webp b/docs/_static/images/vyos-logo.webp new file mode 100644 index 00000000..d15112e7 Binary files /dev/null and b/docs/_static/images/vyos-logo.webp differ diff --git a/docs/_static/images/vyos-sr-isis.png b/docs/_static/images/vyos-sr-isis.png deleted file mode 100644 index 62430919..00000000 Binary files a/docs/_static/images/vyos-sr-isis.png and /dev/null differ diff --git a/docs/_static/images/vyos-sr-isis.webp b/docs/_static/images/vyos-sr-isis.webp new file mode 100644 index 00000000..8ecad813 Binary files /dev/null and b/docs/_static/images/vyos-sr-isis.webp differ diff --git a/docs/_static/images/vyos_1_4_nat66_simple.png b/docs/_static/images/vyos_1_4_nat66_simple.png deleted file mode 100644 index d7c54115..00000000 Binary files a/docs/_static/images/vyos_1_4_nat66_simple.png and /dev/null differ diff --git a/docs/_static/images/vyos_1_4_nat66_simple.webp b/docs/_static/images/vyos_1_4_nat66_simple.webp new file mode 100644 index 00000000..6dedc08c Binary files /dev/null and b/docs/_static/images/vyos_1_4_nat66_simple.webp 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 deleted file mode 100644 index 297fdd11..00000000 Binary files a/docs/_static/images/vyos_1_5_nat66_dhcpv6_wdummy.png and /dev/null differ diff --git a/docs/_static/images/vyos_1_5_nat66_dhcpv6_wdummy.webp b/docs/_static/images/vyos_1_5_nat66_dhcpv6_wdummy.webp new file mode 100644 index 00000000..352d1f08 Binary files /dev/null and b/docs/_static/images/vyos_1_5_nat66_dhcpv6_wdummy.webp differ diff --git a/docs/_static/images/vyos_arista_bond_lacp.png b/docs/_static/images/vyos_arista_bond_lacp.png deleted file mode 100644 index 6c9ef8ec..00000000 Binary files a/docs/_static/images/vyos_arista_bond_lacp.png and /dev/null differ diff --git a/docs/_static/images/vyos_arista_bond_lacp.webp b/docs/_static/images/vyos_arista_bond_lacp.webp new file mode 100644 index 00000000..6ac71379 Binary files /dev/null and b/docs/_static/images/vyos_arista_bond_lacp.webp differ diff --git a/docs/_static/images/vyosnew-downloads.png b/docs/_static/images/vyosnew-downloads.png deleted file mode 100644 index 294a4589..00000000 Binary files a/docs/_static/images/vyosnew-downloads.png and /dev/null differ diff --git a/docs/_static/images/vyosnew-downloads.webp b/docs/_static/images/vyosnew-downloads.webp new file mode 100644 index 00000000..fbbb21c8 Binary files /dev/null and b/docs/_static/images/vyosnew-downloads.webp differ diff --git a/docs/_static/images/wireguard_qrcode.jpg b/docs/_static/images/wireguard_qrcode.jpg deleted file mode 100644 index 0a9a98c0..00000000 Binary files a/docs/_static/images/wireguard_qrcode.jpg and /dev/null differ diff --git a/docs/_static/images/wireguard_qrcode.webp b/docs/_static/images/wireguard_qrcode.webp new file mode 100644 index 00000000..7eb02d79 Binary files /dev/null and b/docs/_static/images/wireguard_qrcode.webp differ diff --git a/docs/_static/images/wireguard_site2site_diagram.jpg b/docs/_static/images/wireguard_site2site_diagram.jpg deleted file mode 100644 index 4a7a95e4..00000000 Binary files a/docs/_static/images/wireguard_site2site_diagram.jpg and /dev/null differ diff --git a/docs/_static/images/wireguard_site2site_diagram.webp b/docs/_static/images/wireguard_site2site_diagram.webp new file mode 100644 index 00000000..9f73ad4e Binary files /dev/null and b/docs/_static/images/wireguard_site2site_diagram.webp differ diff --git a/docs/_static/images/zone-policy-diagram.png b/docs/_static/images/zone-policy-diagram.png deleted file mode 100644 index cfde4af6..00000000 Binary files a/docs/_static/images/zone-policy-diagram.png and /dev/null differ diff --git a/docs/_static/images/zone-policy-diagram.webp b/docs/_static/images/zone-policy-diagram.webp new file mode 100644 index 00000000..850df285 Binary files /dev/null and b/docs/_static/images/zone-policy-diagram.webp differ diff --git a/docs/_swap.txt b/docs/_swap.txt new file mode 100644 index 00000000..03f667c9 --- /dev/null +++ b/docs/_swap.txt @@ -0,0 +1,261 @@ +# 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/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 new file mode 100644 index 00000000..b6350b54 --- /dev/null +++ b/docs/automation/md-cloud-init.md @@ -0,0 +1,378 @@ +--- +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 new file mode 100644 index 00000000..7e736152 --- /dev/null +++ b/docs/automation/md-command-scripting.md @@ -0,0 +1,225 @@ +--- +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 new file mode 100644 index 00000000..dc787db1 --- /dev/null +++ b/docs/automation/terraform/md-index.md @@ -0,0 +1,29 @@ +--- +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 new file mode 100644 index 00000000..488e7926 --- /dev/null +++ b/docs/automation/terraform/md-terraformAWS.md @@ -0,0 +1,548 @@ +--- +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 new file mode 100644 index 00000000..b1b8fac0 --- /dev/null +++ b/docs/automation/terraform/md-terraformAZ.md @@ -0,0 +1,501 @@ +--- +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 new file mode 100644 index 00000000..f9c002a7 --- /dev/null +++ b/docs/automation/terraform/md-terraformGoogle.md @@ -0,0 +1,703 @@ +--- +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 new file mode 100644 index 00000000..abcef5fa --- /dev/null +++ b/docs/automation/terraform/md-terraformvSphere.md @@ -0,0 +1,388 @@ +--- +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/conf.py b/docs/conf.py index 3e84a34a..6442f2aa 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -13,6 +13,7 @@ # 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")) @@ -48,7 +49,9 @@ extensions = ['sphinx.ext.intersphinx', 'autosectionlabel', 'myst_parser', 'sphinx_design', - 'vyos' + 'vyos', + 'sphinx_llms_txt', + 'sphinx_sitemap', ] # Add any paths that contain templates here, relative to this directory. @@ -64,6 +67,9 @@ 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' @@ -83,7 +89,17 @@ 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'] +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 + ) # The name of the Pygments (syntax highlighting) style to use. pygments_style = 'sphinx' @@ -111,6 +127,8 @@ html_static_path = ['_static'] html_extra_path = ['_html_extra'] +html_baseurl = 'https://docs.vyos.io/en/1.5/' + _rtd_version_type = os.environ.get('READTHEDOCS_VERSION_TYPE', '') _github_version = ( os.environ.get('READTHEDOCS_GIT_COMMIT_HASH', 'circinus') @@ -126,6 +144,13 @@ html_context = { 'conf_py_path': '/docs/', } +# sphinx-sitemap: baseurl already includes /en/1.5/, so skip lang+version +sitemap_url_scheme = '{link}' + +# sphinx-llms-txt: disable auto-generated llms.txt, keep curated one from +# _html_extra; llms-full.txt is still auto-generated +llms_txt_file = False + # Custom sidebar templates, must be a dictionary that maps document names # to template names. # @@ -138,7 +163,7 @@ html_context = { # The name of an image file (relative to this directory) to place at the top # of the sidebar. -html_logo = '_static/images/vyos-logo.png' +html_logo = '_static/images/vyos-logo.webp' # The name of an image file (within the static path) to use as favicon of the # docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 @@ -213,5 +238,26 @@ texinfo_documents = [ ] +def _prefer_webp(app): + """Prepend WebP to supported image types for HTML builders.""" + if app.builder.name in ('html', 'dirhtml', 'readthedocs'): + types = app.builder.supported_image_types + if 'image/webp' not in types: + 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): - pass \ No newline at end of file + app.connect('builder-inited', _prefer_webp) + app.connect('build-finished', _copy_md_sources) diff --git a/docs/configexamples/autotest/DHCPRelay_through_GRE/_include/topology.webp b/docs/configexamples/autotest/DHCPRelay_through_GRE/_include/topology.webp new file mode 100644 index 00000000..592484cb Binary files /dev/null and b/docs/configexamples/autotest/DHCPRelay_through_GRE/_include/topology.webp 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 new file mode 100644 index 00000000..1633b349 --- /dev/null +++ b/docs/configexamples/autotest/DHCPRelay_through_GRE/md-DHCPRelay_through_GRE.md @@ -0,0 +1,89 @@ +# 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.webp b/docs/configexamples/autotest/L3VPN_EVPN/_include/topology.webp new file mode 100644 index 00000000..f3218799 Binary files /dev/null and b/docs/configexamples/autotest/L3VPN_EVPN/_include/topology.webp differ diff --git a/docs/configexamples/autotest/L3VPN_EVPN/md-L3VPN_EVPN.md b/docs/configexamples/autotest/L3VPN_EVPN/md-L3VPN_EVPN.md new file mode 100644 index 00000000..b74452e1 --- /dev/null +++ b/docs/configexamples/autotest/L3VPN_EVPN/md-L3VPN_EVPN.md @@ -0,0 +1,246 @@ +# 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.webp b/docs/configexamples/autotest/OpenVPN_with_LDAP/_include/topology.webp new file mode 100644 index 00000000..13bf2d73 Binary files /dev/null and b/docs/configexamples/autotest/OpenVPN_with_LDAP/_include/topology.webp 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 new file mode 100644 index 00000000..bd1ccfc4 --- /dev/null +++ b/docs/configexamples/autotest/OpenVPN_with_LDAP/md-OpenVPN_with_LDAP.md @@ -0,0 +1,238 @@ +(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.webp b/docs/configexamples/autotest/Wireguard/_include/topology.webp new file mode 100644 index 00000000..3cc5e992 Binary files /dev/null and b/docs/configexamples/autotest/Wireguard/_include/topology.webp differ diff --git a/docs/configexamples/autotest/Wireguard/md-Wireguard.md b/docs/configexamples/autotest/Wireguard/md-Wireguard.md new file mode 100644 index 00000000..7bbf4c55 --- /dev/null +++ b/docs/configexamples/autotest/Wireguard/md-Wireguard.md @@ -0,0 +1,108 @@ +# 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.webp b/docs/configexamples/autotest/tunnelbroker/_include/topology.webp new file mode 100644 index 00000000..c3a812ab Binary files /dev/null and b/docs/configexamples/autotest/tunnelbroker/_include/topology.webp differ diff --git a/docs/configexamples/autotest/tunnelbroker/md-tunnelbroker.md b/docs/configexamples/autotest/tunnelbroker/md-tunnelbroker.md new file mode 100644 index 00000000..6c59a491 --- /dev/null +++ b/docs/configexamples/autotest/tunnelbroker/md-tunnelbroker.md @@ -0,0 +1,206 @@ +(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 new file mode 100644 index 00000000..8bbd9306 --- /dev/null +++ b/docs/configexamples/md-ansible.md @@ -0,0 +1,212 @@ +--- +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 new file mode 100644 index 00000000..83d77e53 --- /dev/null +++ b/docs/configexamples/md-azure-vpn-bgp.md @@ -0,0 +1,134 @@ +--- +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 new file mode 100644 index 00000000..967debd4 --- /dev/null +++ b/docs/configexamples/md-azure-vpn-dual-bgp.md @@ -0,0 +1,160 @@ +--- +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 new file mode 100644 index 00000000..4fa29834 --- /dev/null +++ b/docs/configexamples/md-bgp-ipv6-unnumbered.md @@ -0,0 +1,174 @@ +--- +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 new file mode 100644 index 00000000..20c1a064 --- /dev/null +++ b/docs/configexamples/md-dmvpn-dualhub-dualcloud.md @@ -0,0 +1,552 @@ +--- +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 new file mode 100644 index 00000000..5d170511 --- /dev/null +++ b/docs/configexamples/md-firewall.md @@ -0,0 +1,16 @@ +--- +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 new file mode 100644 index 00000000..5eb7a7fd --- /dev/null +++ b/docs/configexamples/md-fwall-and-bridge.md @@ -0,0 +1,490 @@ +--- +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 +# Bridge 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 analyzed +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 new file mode 100644 index 00000000..da9949db --- /dev/null +++ b/docs/configexamples/md-fwall-and-vrf.md @@ -0,0 +1,121 @@ +# 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 new file mode 100644 index 00000000..c3fd4f84 --- /dev/null +++ b/docs/configexamples/md-ha.md @@ -0,0 +1,556 @@ +--- +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 new file mode 100644 index 00000000..e5a81305 --- /dev/null +++ b/docs/configexamples/md-index.md @@ -0,0 +1,60 @@ +(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 new file mode 100644 index 00000000..2ac36904 --- /dev/null +++ b/docs/configexamples/md-inter-vrf-routing-vrf-lite.md @@ -0,0 +1,797 @@ +# 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 protocols 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 Management), 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 Management), 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 new file mode 100644 index 00000000..7a31601d --- /dev/null +++ b/docs/configexamples/md-ipsec-cisco-policy-based.md @@ -0,0 +1,363 @@ +--- +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 new file mode 100644 index 00000000..40a3985b --- /dev/null +++ b/docs/configexamples/md-ipsec-cisco-route-based.md @@ -0,0 +1,406 @@ +--- +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 new file mode 100644 index 00000000..c4a9e06c --- /dev/null +++ b/docs/configexamples/md-ipsec-pa-route-based.md @@ -0,0 +1,412 @@ +--- +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 new file mode 100644 index 00000000..3c719926 --- /dev/null +++ b/docs/configexamples/md-l3vpn-hub-and-spoke.md @@ -0,0 +1,1091 @@ +# 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 new file mode 100644 index 00000000..51a96f8b --- /dev/null +++ b/docs/configexamples/md-lac-lns.md @@ -0,0 +1,181 @@ +--- +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 new file mode 100644 index 00000000..63231a09 --- /dev/null +++ b/docs/configexamples/md-nmp.md @@ -0,0 +1,76 @@ +--- +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 new file mode 100644 index 00000000..9174d1b4 --- /dev/null +++ b/docs/configexamples/md-ospf-unnumbered.md @@ -0,0 +1,118 @@ +--- +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 new file mode 100644 index 00000000..86bc9318 --- /dev/null +++ b/docs/configexamples/md-policy-based-ipsec-and-firewall.md @@ -0,0 +1,269 @@ +(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 new file mode 100644 index 00000000..76984f4b --- /dev/null +++ b/docs/configexamples/md-pppoe-ipv6-basic.md @@ -0,0 +1,114 @@ +--- +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 new file mode 100644 index 00000000..e8335584 --- /dev/null +++ b/docs/configexamples/md-qos.md @@ -0,0 +1,201 @@ +--- +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 new file mode 100644 index 00000000..41ba2389 --- /dev/null +++ b/docs/configexamples/md-segment-routing-isis.md @@ -0,0 +1,277 @@ +--- +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 new file mode 100644 index 00000000..d8ca2c18 --- /dev/null +++ b/docs/configexamples/md-site-2-site-cisco.md @@ -0,0 +1,170 @@ +(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 new file mode 100644 index 00000000..b9357523 --- /dev/null +++ b/docs/configexamples/md-wan-load-balancing.md @@ -0,0 +1,183 @@ +--- +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 new file mode 100644 index 00000000..2cd773a9 --- /dev/null +++ b/docs/configexamples/md-zone-policy.md @@ -0,0 +1,417 @@ +--- +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 new file mode 100644 index 00000000..db46db38 --- /dev/null +++ b/docs/configuration/container/md-index.md @@ -0,0 +1,479 @@ +--- +lastproofread: '2024-07-03' +--- + +# Container + +The VyOS container implementation is based on [Podman](https://podman.io/) as +a 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 new file mode 100644 index 00000000..f0e94f9e --- /dev/null +++ b/docs/configuration/firewall/md-bridge.md @@ -0,0 +1,685 @@ +--- +lastproofread: '2026-03-28' +--- + +(firewall-configuration)= + +# Bridge Firewall Configuration + +## Overview + +Learn more about bridge firewall configuration +and related op-mode commands. + +The following commands are covered in this section: + +```{cfgcmd} set firewall bridge \ +``` + +From the main structure defined in +{doc}`Firewall Overview` +in this section you can find detailed information only for the next part +of the general structure: + +```none +- set firewall + * bridge + - forward + + filter + - input + + filter + - output + + filter + - prerouting + + filter + - name + + custom_name +``` + +Traffic that is received by the router on an interface that is a member of a +bridge is processed on the **Bridge Layer**. Before the bridge decision is +made, all packets are analyzed at **Prerouting**. First filters can be applied +here, and also rules for ignoring connection tracking system can be configured. +The relevant configuration that acts in **prerouting** is: + + +- `set firewall bridge prerouting filter ...`. + + +For traffic that needs to be switched internally by the bridge, the base +chain is **forward**, and its base command for filtering is `set firewall +bridge forward filter ...`, which happens in stage 4, highlighted with red +color. + + +:::{figure} /_static/images/firewall-bridge-forward.webp +::: + + +For traffic destined to the router itself or that needs to be routed +(assuming a layer3 bridge is configured), the base chain is **input**, and the +base command is `set firewall bridge input filter ...` and the path is: + + +:::{figure} /_static/images/firewall-bridge-input.webp +::: + + +If it's not dropped, then the packet is sent to **IP Layer**, and will be +processed by the **IP Layer** firewall: IPv4 or IPv6 ruleset. Check once again +the {doc}`general packet flow diagram` if +needed. + + +For traffic that originates from the bridge itself, the base chain is +**output**, and the base command is `set firewall bridge output filter +...`, and the path is: + + +:::{figure} /_static/images/firewall-bridge-output.webp +::: + + +Custom bridge firewall chains can be created with the command `set firewall +bridge name ...`. To use such a custom chain, a rule with action jump +and the appropriate target must be defined in a base chain. + + +## Bridge Rules + + +For firewall filtering, firewall rules need to be created. Each rule is +numbered, has an action to apply if the rule is matched, and the ability +to specify multiple matching criteria. Data packets go through the rules +from 1 - 999999, so order is crucial. At the first match the action of the +rule will be executed. + + +### Actions + + +If a rule is defined, an action must also be defined for it. This tells the +firewall what to do if all matching criteria in the rule are met. + + +In firewall bridge rules, the action can be: + + +- `accept`: accept the packet. +- `continue`: continue parsing next rule. +- `drop`: drop the packet. +- `jump`: jump to another custom chain. +- `return`: Return from the current chain and continue at the next rule + of the last chain. +- `queue`: Enqueue packet to userspace. +- `notrack`: ignore connection tracking system. This action is only + available in prerouting chain. + +```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> action [accept | continue | drop | jump | queue | return] +``` + +```{cfgcmd} set firewall bridge input filter rule \<1-999999\> action [accept | continue | drop | jump | queue | return] +``` + +```{cfgcmd} set firewall bridge output filter rule \<1-999999\> action [accept | continue | drop | jump | queue | return] +``` + +```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> action [accept | continue | drop | jump | notrack | queue | return] +``` + +```{cfgcmd} set firewall bridge name \ rule \<1-999999\> action [accept | continue | drop | jump | queue | return] + +This required setting defines the action of the current rule. If action is +set to jump, then jump-target is also needed. +``` + +```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> jump-target \ +``` + +```{cfgcmd} set firewall bridge input filter rule \<1-999999\> jump-target \ +``` + +```{cfgcmd} set firewall bridge output filter rule \<1-999999\> jump-target \ +``` + +```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> jump-target \ +``` + +```{cfgcmd} set firewall bridge name \ rule \<1-999999\> jump-target \ +``` + +If action is set to ``queue``, use next command to specify the queue +target. Range is also supported: + +```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> queue \<0-65535\> +``` + +```{cfgcmd} set firewall bridge input filter rule \<1-999999\> queue \<0-65535\> +``` + +```{cfgcmd} set firewall bridge output filter rule \<1-999999\> queue \<0-65535\> +``` + +```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> queue \<0-65535\> +``` + +```{cfgcmd} set firewall bridge name \ rule \<1-999999\> queue \<0-65535\> + +Also, if action is set to ``queue``, use next command to specify the queue +options. Possible options are ``bypass`` and ``fanout``: +``` + +```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> queue-options bypass +``` + +```{cfgcmd} set firewall bridge input filter rule \<1-999999\> queue-options bypass +``` + +```{cfgcmd} set firewall bridge output filter rule \<1-999999\> queue-options bypass +``` + +```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> queue-options bypass +``` + +```{cfgcmd} set firewall bridge name \ rule \<1-999999\> queue-options bypass +``` + +```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> queue-options fanout +``` + +```{cfgcmd} set firewall bridge input filter rule \<1-999999\> queue-options fanout +``` + +```{cfgcmd} set firewall bridge output filter rule \<1-999999\> queue-options fanout +``` + +```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> queue-options fanout +``` + +```{cfgcmd} set firewall bridge name \ rule \<1-999999\> queue-options fanout +``` + +Also, **default-action** is an action that takes place whenever a packet does +not match any rule in its chain. For base chains, possible options for +**default-action** are **accept** or **drop**. + +```{cfgcmd} set firewall bridge forward filter default-action [accept | drop] +``` + +```{cfgcmd} set firewall bridge input filter default-action [accept | drop] +``` + +```{cfgcmd} set firewall bridge output filter default-action [accept | drop] +``` + +```{cfgcmd} set firewall bridge prerouting filter default-action [accept | drop] +``` + +```{cfgcmd} set firewall bridge name \ default-action [accept | continue | drop | jump | reject | return] + +This sets the default action of the rule-set if a packet does not match +any of the rules in that chain. If default-action is set to ``jump``, then +``default-jump-target`` is also needed. Note that for base chains, default +action can only be set to ``accept`` or ``drop``, while on custom chains +more actions are available. +``` + +```{cfgcmd} set firewall bridge name \ default-jump-target \ + +To be used only when ``default-action`` is set to ``jump``. Use this +command to specify jump target for default rule. +``` +:::{note} +**Important note about default-actions:** +If the default action for any base chain is not defined, then the default +action is set to **accept** for that chain. For custom chains, if the +default action is not defined, then the default-action is set to **drop**. +::: + + +### Firewall Logs + + +You can enable logging for every firewall rule. If enabled, other log options +can be configured. + +```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> log +``` + +```{cfgcmd} set firewall bridge input filter rule \<1-999999\> log +``` + +```{cfgcmd} set firewall bridge output filter rule \<1-999999\> log +``` + +```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> log +``` + +```{cfgcmd} set firewall bridge name \ rule \<1-999999\> log + +Enable logging for the matched packet. If this configuration command is not +present, then the log is not enabled. +``` + +```{cfgcmd} set firewall bridge forward filter default-log +``` + +```{cfgcmd} set firewall bridge input filter default-log +``` + +```{cfgcmd} set firewall bridge output filter default-log +``` + +```{cfgcmd} set firewall bridge prerouting filter default-log +``` + +```{cfgcmd} set firewall bridge name \ default-log + +Use this command to enable the logging of the default action on +the specified chain. +``` + +```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> log-options level [emerg | alert | crit | err | warn | notice | info | debug] +``` + +```{cfgcmd} set firewall bridge input filter rule \<1-999999\> log-options level [emerg | alert | crit | err | warn | notice | info | debug] +``` + +```{cfgcmd} set firewall bridge output filter rule \<1-999999\> log-options level [emerg | alert | crit | err | warn | notice | info | debug] +``` + +```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> log-options level [emerg | alert | crit | err | warn | notice | info | debug] +``` + +```{cfgcmd} set firewall bridge name \ rule \<1-999999\> log-options level [emerg | alert | crit | err | warn | notice | info | debug] + +Define log-level. Only applicable if rule log is enabled. +``` + +```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> log-options group \<0-65535\> +``` + +```{cfgcmd} set firewall bridge input filter rule \<1-999999\> log-options group \<0-65535\> +``` + +```{cfgcmd} set firewall bridge output filter rule \<1-999999\> log-options group \<0-65535\> +``` + +```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> log-options group \<0-65535\> +``` + +```{cfgcmd} set firewall bridge name \ rule \<1-999999\> log-options group \<0-65535\> + +Define the log group to send messages to. Only applicable if rule log is +enabled. +``` + +```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> log-options snapshot-length \<0-9000\> +``` + +```{cfgcmd} set firewall bridge input filter rule \<1-999999\> log-options snapshot-length \<0-9000\> +``` + +```{cfgcmd} set firewall bridge output filter rule \<1-999999\> log-options snapshot-length \<0-9000\> +``` + +```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> log-options snapshot-length \<0-9000\> +``` + +```{cfgcmd} set firewall bridge name \ rule \<1-999999\> log-options snapshot-length \<0-9000\> + +Define length of packet payload to include in netlink message. Only +applicable if rule log is enabled and the log group is defined. +``` + +```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> log-options queue-threshold \<0-65535\> +``` + +```{cfgcmd} set firewall bridge input filter rule \<1-999999\> log-options queue-threshold \<0-65535\> +``` + +```{cfgcmd} set firewall bridge output filter rule \<1-999999\> log-options queue-threshold \<0-65535\> +``` + +```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> log-options queue-threshold \<0-65535\> +``` + +```{cfgcmd} set firewall bridge name \ rule \<1-999999\> log-options queue-threshold \<0-65535\> + +Define the number of packets to queue inside the kernel before sending them +to userspace. Only applicable if rule log is enabled and the log group is +defined. +``` + +### Firewall Description + + +You can define a description for reference for every custom chain. + +```{cfgcmd} set firewall bridge name \ description \ + +Provide a rule-set description to a custom firewall chain. +``` + +```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> description \ +``` + +```{cfgcmd} set firewall bridge input filter rule \<1-999999\> description \ +``` + +```{cfgcmd} set firewall bridge output filter rule \<1-999999\> description \ +``` + +```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> description \ +``` + +```{cfgcmd} set firewall bridge name \ rule \<1-999999\> description \ + +Provide a description for each rule. +``` + +### Rule Status + + +By default, when you define a rule, it is enabled. In some cases, it is +useful to disable the rule instead of removing it. + +```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> disable +``` + +```{cfgcmd} set firewall bridge input filter rule \<1-999999\> disable +``` + +```{cfgcmd} set firewall bridge output filter rule \<1-999999\> disable +``` + +```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> disable +``` + +```{cfgcmd} set firewall bridge name \ rule \<1-999999\> disable + +Command for disabling a rule but keep it in the configuration. +``` + +### Matching criteria + + +There are many matching criteria against which a packet can be tested. Refer +to {doc}`IPv4` and +{doc}`IPv6` matching criteria for more details. + + +Since bridges operate at layer 2, both matchers for IPv4 and IPv6 are +supported in bridge firewall configuration. Same applies to firewall groups. + + +Same specific matching criteria that can be used in bridge firewall are +described in this section: + +```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> ethernet-type [802.1q | 802.1ad | arp | ipv4 | ipv6] +``` + +```{cfgcmd} set firewall bridge input filter rule \<1-999999\> ethernet-type [802.1q | 802.1ad | arp | ipv4 | ipv6] +``` + +```{cfgcmd} set firewall bridge output filter rule \<1-999999\> ethernet-type [802.1q | 802.1ad | arp | ipv4 | ipv6] +``` + +```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> ethernet-type [802.1q | 802.1ad | arp | ipv4 | ipv6] +``` + +```{cfgcmd} set firewall bridge name \ rule \<1-999999\> ethernet-type [802.1q | 802.1ad | arp | ipv4 | ipv6] + +Match based on the Ethernet type of the packet. +``` + +```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> vlan ethernet-type [802.1q | 802.1ad | arp | ipv4 | ipv6] +``` + +```{cfgcmd} set firewall bridge input filter rule \<1-999999\> vlan ethernet-type [802.1q | 802.1ad | arp | ipv4 | ipv6] +``` + +```{cfgcmd} set firewall bridge output filter rule \<1-999999\> vlan ethernet-type [802.1q | 802.1ad | arp | ipv4 | ipv6] +``` + +```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> vlan ethernet-type [802.1q | 802.1ad | arp | ipv4 | ipv6] +``` + +```{cfgcmd} set firewall bridge name \ rule \<1-999999\> vlan ethernet-type [802.1q | 802.1ad | arp | ipv4 | ipv6] + +Match based on the Ethernet type of the packet when it is VLAN tagged. +``` + +```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> vlan id \<0-4096\> +``` + +```{cfgcmd} set firewall bridge input filter rule \<1-999999\> vlan id \<0-4096\> +``` + +```{cfgcmd} set firewall bridge output filter rule \<1-999999\> vlan id \<0-4096\> +``` + +```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> vlan id \<0-4096\> +``` + +```{cfgcmd} set firewall bridge name \ rule \<1-999999\> vlan id \<0-4096\> + +Match based on VLAN identifier. Range is also supported. +``` + +```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> vlan priority \<0-7\> +``` + +```{cfgcmd} set firewall bridge input filter rule \<1-999999\> vlan priority \<0-7\> +``` + +```{cfgcmd} set firewall bridge output filter rule \<1-999999\> vlan priority \<0-7\> +``` + +```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> vlan priority \<0-7\> +``` + +```{cfgcmd} set firewall bridge name \ rule \<1-999999\> vlan priority \<0-7\> + +Match based on VLAN priority (Priority Code Point - PCP). Range is also +supported. +``` + +### Packet Modifications + + +Starting from **VyOS-1.5-rolling-202410060007**, the firewall can modify +packets before they are sent out. This 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 new file mode 100644 index 00000000..24d0675e --- /dev/null +++ b/docs/configuration/firewall/md-flowtables.md @@ -0,0 +1,176 @@ +--- +lastproofread: '2026-03-30' +--- + +(firewall-flowtables-configuration)= + +# Flowtables Firewall Configuration + +```{include} /_include/need_improvement.txt +``` + + +## Overview + +This section provides information on firewall configuration for flowtables. + +```{cfgcmd} set firewall flowtable ... +``` + +To learn about the general traffic flow in VyOS firewalls, +see {doc}`Firewall `. + +```none +- set firewall + * flowtable + - custom_flow_table + + ... +``` + +Flowtables let you define a fastpath through the flowtable datapath. +Flowtables support layer 3 (IPv4 and IPv6) and layer 4 (TCP and UDP) +protocols. + +:::{figure} /_static/images/firewall-flowtable-packet-flow.webp +::: + +After the first packet successfully traverses the IP forwarding path (black +circles path), you can offload subsequent packets to the flowtable through your +ruleset. You specify when to add a flow to the flowtable during forward +filtering (red circle number 6). + +When a packet finds a matching entry in the flowtable (flowtable hit), the +system transmits it to the output netdevice. This means packets bypass the +classic IP forwarding path and use the **Fast Path** (orange circles path). +As a result, you do not see these packets from any Netfilter hooks after +ingress. If no matching entry exists in the flowtable (flowtable miss), the +packet traverses the classic IP forwarding path. + +:::{note} +**Flowtable Reference:** + +::: + +## Flowtable Configuration + +To use flowtables, you need to configure the following: +> - Create a flowtable that includes the interfaces +> that are going to be used by the flowtable. +> - Create a firewall rule. Set the action to +> `offload` and use your desired flowtable for `offload-target`. + +Creating a flow table: + +```{cfgcmd} set firewall flowtable \ interface \ + +Specify interfaces to use in the flowtable. +``` + +```{cfgcmd} set firewall flowtable \ description \ +``` + +Provide a description for the flow table. + +```{cfgcmd} set firewall flowtable \ offload \ + +Specify the offload type the flowtable uses: ``hardware`` or +``software``. The default is ``software`` offload. +``` +:::{note} +**Hardware offload**: Make sure your network interface controller +(NIC) supports hardware offloading and that you have the necessary drivers +> installed before enabling this option. +::: + +Creating rules for using flow tables: + +```{cfgcmd} set firewall [ipv4 | ipv6] forward filter rule \<1-999999\> action offload + +Create a firewall rule in the forward chain with the action set to +``offload``. +``` + +```{cfgcmd} set firewall [ipv4 | ipv6] forward filter rule \<1-999999\> offload-target \ + +Create a firewall rule in the forward chain and specify which flowtable +to use. Only applicable if the action is ``offload``. +``` + +## Configuration Example + +Consider the following in this setup: +> - This example uses two interfaces in the flowtables: `eth0` and `eth1`. +> - The example provides a minimal firewall ruleset with filtering rules +> and rules for using flowtable offload capabilities. + +The first packet is evaluated by the firewall path, so a +desired connection should be explicitly accepted. +The same should occur for traffic in reverse order. +In most cases, state policies are +used to accept a connection in the reverse path. + +In the following example only traffic coming from interface `eth0`, +TCP protocol, and destination port 1122 is accepted. +All other traffic to the router is dropped. + +### Commands + +```none +set firewall flowtable FT01 interface 'eth0' +set firewall flowtable FT01 interface 'eth1' +set firewall ipv4 forward filter default-action 'drop' +set firewall ipv4 forward filter rule 10 action 'offload' +set firewall ipv4 forward filter rule 10 offload-target 'FT01' +set firewall ipv4 forward filter rule 10 state 'established' +set firewall ipv4 forward filter rule 10 state 'related' +set firewall ipv4 forward filter rule 20 action 'accept' +set firewall ipv4 forward filter rule 20 state 'established' +set firewall ipv4 forward filter rule 20 state 'related' +set firewall ipv4 forward filter rule 110 action 'accept' +set firewall ipv4 forward filter rule 110 destination address '192.0.2.100' +set firewall ipv4 forward filter rule 110 destination port '1122' +set firewall ipv4 forward filter rule 110 inbound-interface name 'eth0' +set firewall ipv4 forward filter rule 110 protocol 'tcp' +``` + +### Explanation + +Here's what happens for a desired connection: +> 1. A packet arrives on `eth0` with destination address `192.0.2.100`, TCP +> protocol, and destination port 1122. Assume this address is reachable +> through interface `eth1`. +> 2. For this first packet, the connection state is **new**. Neither rule 10 +> nor rule 20 applies. +> 3. Rule 110 matches, so the connection is accepted. +> 4. When the server 192.0.2.100 replies, the connection state becomes +> **established**, and rule 20 accepts the reply. +> 5. The router receives the second packet for this connection. Because the +> connection state is **established**, rule 10 matches and adds a new +> entry in the flowtable FT01 for this connection. +> 6. Subsequent packets skip the traditional path and use the **Fast Path** +> for offloading. + +### Checks + +Check the conntrack table to verify that the system accepted and properly +offloaded connections. + +```none +vyos@FlowTables:~$ show firewall ipv4 forward filter +Ruleset Information + +--------------------------------- +ipv4 Firewall "forward filter" + +Rule Action Protocol Packets Bytes Conditions +------- -------- ---------- --------- ------- ---------------------------------------------------------------- +10 offload all 8 468 ct state { established, related } flow add @VYOS_FLOWTABLE_FT01 +20 accept all 8 468 ct state { established, related } accept +110 accept tcp 2 120 ip daddr 192.0.2.100 tcp dport 1122 iifname "eth0" accept +default drop all 7 420 + +vyos@FlowTables:~$ sudo conntrack -L | grep tcp +conntrack v1.4.6 (conntrack-tools): 5 flow entries have been shown. +tcp 6 src=198.51.100.100 dst=192.0.2.100 sport=41676 dport=1122 src=192.0.2.100 dst=198.51.100.100 sport=1122 dport=41676 [OFFLOAD] mark=0 use=2 +vyos@FlowTables:~$ +``` diff --git a/docs/configuration/firewall/md-global-options.md b/docs/configuration/firewall/md-global-options.md new file mode 100644 index 00000000..0f6d91ac --- /dev/null +++ b/docs/configuration/firewall/md-global-options.md @@ -0,0 +1,186 @@ +--- +lastproofread: '2026-03-30' +--- + +(firewall-global-options-configuration)= + +# Global Options Firewall Configuration + +## Overview + +Some firewall settings are global and affect the entire system. This section +provides information about these global options that you can configure using +the VyOS CLI. + +Configuration commands covered in this section: + +```{cfgcmd} set firewall global-options ... +``` + +## Configuration + +```{cfgcmd} set firewall global-options all-ping [enable | disable] + +By default, when VyOS receives an ICMP echo request packet destined for +itself, it answers with an ICMP echo reply, unless your firewall prevents +it. + +You can set firewall rules to accept, drop, or reject ICMP in, out, or +local traffic. You can also use the **firewall global-options all-ping** +command. This command affects only LOCAL traffic (packets destined for your +VyOS system), not IN or OUT traffic. + +:::{note} +**firewall global-options all-ping** affects only LOCAL traffic +and always behaves in the most restrictive way +::: +:::{code-block} none +set firewall global-options all-ping enable +::: +When you set this command, VyOS answers every ICMP echo request addressed +to itself, but that response occurs only if no other rule drops or rejects +local echo requests. In case of conflict, VyOS does not answer ICMP echo +requests. + +:::{code-block} none +set firewall global-options all-ping disable +::: +When you set this command, VyOS answers no ICMP echo requests addressed to +itself, regardless of where they come from or what specific rules accept +them. +``` + +```{cfgcmd} set firewall global-options apply-to-bridged-traffic [ipv4 | ipv6] + +Apply IPv4 or IPv6 firewall rules to bridged traffic. +``` + +```{cfgcmd} set firewall global-options broadcast-ping [enable | disable] + +Enable or disable the response to ICMP broadcast messages. The system +alters the following parameter: +* ``net.ipv4.icmp_echo_ignore_broadcasts`` +``` + +```{cfgcmd} set firewall global-options ip-src-route [enable | disable] +``` + +```{cfgcmd} set firewall global-options ipv6-src-route [enable | disable] + +Set whether VyOS accepts packets with a source route option. +The following sysctl parameters will be changed: +* ``net.ipv4.conf.all.accept_source_route`` +* ``net.ipv6.conf.all.accept_source_route`` +``` + +```{cfgcmd} set firewall global-options receive-redirects [enable | disable] +``` + +```{cfgcmd} set firewall global-options ipv6-receive-redirects [enable | disable] + +Allow VyOS to accept ICMPv4 and ICMPv6 redirect messages. +The following sysctl parameters will be changed: +* ``net.ipv4.conf.all.accept_redirects`` +* ``net.ipv6.conf.all.accept_redirects`` +``` + +```{cfgcmd} set firewall global-options send-redirects [enable | disable] + +Allow VyOS to send ICMPv4 redirect messages. +The following sysctl parameter will be changed: +* ``net.ipv4.conf.all.send_redirects`` +``` + +```{cfgcmd} set firewall global-options log-martians [enable | disable] + +Allow VyOS to log martian IPv4 packets. +The following sysctl parameter will be changed: +* ``net.ipv4.conf.all.log_martians`` +``` + +```{cfgcmd} set firewall global-options source-validation [strict | loose | disable] + +Set the IPv4 source validation mode. +The following sysctl parameter will be changed: +* ``net.ipv4.conf.all.rp_filter`` +``` + +```{cfgcmd} set firewall global-options syn-cookies [enable | disable] + +Allow VyOS to use IPv4 TCP SYN Cookies. +The following sysctl parameter will be changed: +* ``net.ipv4.tcp_syncookies`` +``` + +```{cfgcmd} set firewall global-options twa-hazards-protection [enable | disable] + +Enable or disable VyOS {rfc}`1337` conformance. +The following sysctl parameter will be changed: +* ``net.ipv4.tcp_rfc1337`` +``` + +```{cfgcmd} set firewall global-options state-policy established action [accept | drop | reject] +``` + +```{cfgcmd} set firewall global-options state-policy established log +``` + +```{cfgcmd} set firewall global-options state-policy established log-level [emerg | alert | crit | err | warn | notice | info | debug] + +Set the global setting for an established connection. +``` + +```{cfgcmd} set firewall global-options state-policy invalid action [accept | drop | reject] +``` + +```{cfgcmd} set firewall global-options state-policy invalid log +``` + +```{cfgcmd} set firewall global-options state-policy invalid log-level [emerg | alert | crit | err | warn | notice | info | debug] + +Set the global setting for invalid packets. +``` + +```{cfgcmd} set firewall global-options state-policy related action [accept | drop | reject] +``` + +```{cfgcmd} set firewall global-options state-policy related log +``` + +```{cfgcmd} set firewall global-options state-policy related log-level [emerg | alert | crit | err | warn | notice | info | debug] + +Set the global setting for related connections. +``` + +VyOS supports setting timeouts for connections by connection type. You can +set timeout values for generic connections, ICMP connections, UDP +connections, or TCP connections in various states. + +```{eval-rst} +.. cfgcmd:: set firewall global-options timeout icmp <1-21474836> + :defaultvalue: +.. cfgcmd:: set firewall global-options timeout other <1-21474836> + :defaultvalue: +.. cfgcmd:: set firewall global-options timeout tcp close <1-21474836> + :defaultvalue: +.. cfgcmd:: set firewall global-options timeout tcp close-wait <1-21474836> + :defaultvalue: +.. cfgcmd:: set firewall global-options timeout tcp established <1-21474836> + :defaultvalue: +.. cfgcmd:: set firewall global-options timeout tcp fin-wait <1-21474836> + :defaultvalue: +.. cfgcmd:: set firewall global-options timeout tcp last-ack <1-21474836> + :defaultvalue: +.. cfgcmd:: set firewall global-options timeout tcp syn-recv <1-21474836> + :defaultvalue: +.. cfgcmd:: set firewall global-options timeout tcp syn-sent <1-21474836> + :defaultvalue: +.. cfgcmd:: set firewall global-options timeout tcp time-wait <1-21474836> + :defaultvalue: +.. cfgcmd:: set firewall global-options timeout udp other <1-21474836> + :defaultvalue: +.. cfgcmd:: set firewall global-options timeout udp stream <1-21474836> + :defaultvalue: + + Set the timeout in seconds for a protocol or state. +``` \ No newline at end of file diff --git a/docs/configuration/firewall/md-groups.md b/docs/configuration/firewall/md-groups.md new file mode 100644 index 00000000..817f610e --- /dev/null +++ b/docs/configuration/firewall/md-groups.md @@ -0,0 +1,477 @@ +--- +lastproofread: '2026-03-30' +--- + +(firewall-groups-configuration)= + +# Firewall groups + +## Configuration + +Firewall groups represent collections of IP addresses, networks, ports, +MAC addresses, domains, or interfaces. You can reference a group in firewall, +NAT, and policy route rules as either a source or destination matcher, and/or +as inbound or outbound in the case of interface groups. + +### Address Groups + +An **address group** contains a single IP address or IP address range. + +```{cfgcmd} set firewall group address-group \ address [address | address range] + +``` +```{cfgcmd} set firewall group ipv6-address-group \ address \ + +Define an IPv4 or IPv6 address group. + +:::{code-block} none +set firewall group address-group ADR-INSIDE-v4 address 192.168.0.1 +set firewall group address-group ADR-INSIDE-v4 address 10.0.0.1-10.0.0.8 +set firewall group ipv6-address-group ADR-INSIDE-v6 address 2001:db8::1 +::: +``` + +```{cfgcmd} set firewall group address-group \ description \ +``` + +```{cfgcmd} set firewall group ipv6-address-group \ description \ + +Provide an IPv4 or IPv6 address group description. +``` + +### Remote Groups + +A **remote-group** uses a URL that hosts a newline-delimited list of IPv4 +and/or IPv6 addresses, CIDRs, and ranges. VyOS pulls this list periodically +according to the frequency you define in the firewall **resolver-interval** +and loads matching entries into the group for use in rules. The list is cached +in persistent storage, so rules continue to function if updates fail. + +```{cfgcmd} set firewall group remote-group \ url \ + +Specify a remote list of IPv4 and/or IPv6 addresses, ranges, and CIDRs +to fetch. +``` + +```{cfgcmd} set firewall group remote-group \ description \ + +Set a description for a remote group. +``` + +The remote list format is flexible. VyOS attempts to parse the first word of +each line as an entry and skips lines it cannot match. Lines that begin with +an alphanumeric character but do not match valid IPv4 or IPv6 addresses, +ranges, or CIDRs are logged to the system log. The following examples show +acceptable formats that VyOS parses correctly: + +```none +127.0.0.1 +127.0.0.0/24 +127.0.0.1-127.0.0.254 +2001:db8::1 +2001:db8:cafe::/48 +2001:db8:cafe::1-2001:db8:cafe::ffff +``` + +### Network Groups + +**Network groups** accept IP networks in CIDR notation. You can add specific +IP addresses as a 32-bit prefix. If you need to add a mix of addresses and +networks, use a network group. + +```{cfgcmd} set firewall group network-group \ network \ +``` + +```{cfgcmd} set firewall group ipv6-network-group \ network \ + +Define an IPv4 or IPv6 network group. + +:::{code-block} none +set firewall group network-group NET-INSIDE-v4 network 192.168.0.0/24 +set firewall group network-group NET-INSIDE-v4 network 192.168.1.0/24 +set firewall group ipv6-network-group NET-INSIDE-v6 network 2001:db8::/64 +::: +``` + +```{cfgcmd} set firewall group network-group \ description \ +``` + +```{cfgcmd} set firewall group ipv6-network-group \ description \ + +Provide an IPv4 or IPv6 network group description. +``` + +### Interface Groups + +An **interface group** represents a collection of interfaces. + +```{cfgcmd} set firewall group interface-group \ interface \ + +Define an interface group. +Wildcard ``*`` is supported. For example: ``eth3*``. +Prepend the character ``!`` to invert the criteria. For example: ``!eth2``. +``` + +```none +set firewall group interface-group LAN interface bond1001 +set firewall group interface-group LAN interface eth3* +``` + +```{cfgcmd} set firewall group interface-group \ description \ + +Provide an interface group description. +``` + +### Port Groups + +A **port group** represents only port numbers, not the protocol. You can +reference port groups for either TCP or UDP. Create TCP and UDP groups +separately to avoid accidentally filtering unnecessary ports. Specify port +ranges by using `-`. + +```{cfgcmd} set firewall group port-group \ port [portname | portnumber | startport-endport] + +Define a port group. A port name can be any name defined in +/etc/services. For example, ``http``. + +:::{code-block} none +set firewall group port-group PORT-TCP-SERVER1 port http +set firewall group port-group PORT-TCP-SERVER1 port 443 +set firewall group port-group PORT-TCP-SERVER1 port 5000-5010 +::: +``` + +```{cfgcmd} set firewall group port-group \ description \ + +Provide a port group description. +``` + +### MAC Groups + +A **mac group** represents a collection of mac addresses. + +```{cfgcmd} set firewall group mac-group \ mac-address \ + +Define a mac group. +``` + +```none +set firewall group mac-group MAC-G01 mac-address 88:a4:c2:15:b6:4f +set firewall group mac-group MAC-G01 mac-address 4c:d5:77:c0:19:81 +``` + +```{cfgcmd} set firewall group mac-group \ description \ + +Provide a MAC group description. +``` + +### Domain Groups + +A **domain group** represents a collection of domains. + +```{cfgcmd} set firewall group domain-group \ address \ + +Define a domain group. +``` + +```none +set firewall group domain-group DOM address example.com +``` + +```{cfgcmd} set firewall group domain-group \ description \ + +Provide a domain group description. +``` + +### Dynamic Groups + +Firewall dynamic groups differ from other groups because you can use them as +source/destination in firewall rules, and members are not defined statically +in VyOS configuration. Instead, firewall rules dynamically add members to +these groups. + +#### Defining Dynamic Address Groups + +Dynamic address groups support both IPv4 and IPv6 families. Use these +commands to define dynamic IPv4 and IPv6 address groups: + +```{cfgcmd} set firewall group dynamic-group address-group \ +``` + +```{cfgcmd} set firewall group dynamic-group ipv6-address-group \ +``` + +Add description to firewall groups: + +```{cfgcmd} set firewall group dynamic-group address-group \ description \ +``` + +```{cfgcmd} set firewall group dynamic-group ipv6-address-group \ description \ +``` + +#### Adding elements to Dynamic Firewall Groups + +After you define dynamic firewall groups, use them in firewall rules to +dynamically add elements to them. + +Commands used for this task are: +- Add destination IP address of the connection to a dynamic address group: + +```{cfgcmd} set firewall ipv4 [forward | input | output] filter rule \<1-999999\> add-address-to-group destination-address address-group \ +``` + +```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> add-address-to-group destination-address address-group \ +``` + +```{cfgcmd} set firewall ipv6 [forward | input | output] filter rule \<1-999999\> add-address-to-group destination-address address-group \ +``` + +```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> add-address-to-group destination-address address-group \ +``` + +- Add source IP address of the connection to a dynamic address group: + +```{cfgcmd} set firewall ipv4 [forward | input | output] filter rule \<1-999999\> add-address-to-group source-address address-group \ +``` + +```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> add-address-to-group source-address address-group \ +``` + +```{cfgcmd} set firewall ipv6 [forward | input | output] filter rule \<1-999999\> add-address-to-group source-address address-group \ +``` + +```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> add-address-to-group source-address address-group \ +``` + +You can define specific timeouts per rule. When a rule matches, the source or +destination address is added to the group, and the element remains in the group +until the timeout expires. If you do not define a timeout, the element remains +in the group until the next reboot or until you commit firewall configuration +changes. + +```{cfgcmd} set firewall ipv4 [forward | input | output] filter rule \<1-999999\> add-address-to-group [destination-address | source-address] timeout \ +``` + +```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> add-address-to-group [destination-address | source-address] timeout \ +``` + +```{cfgcmd} set firewall ipv6 [forward | input | output] filter rule \<1-999999\> add-address-to-group [destination-address | source-address] timeout \ +``` + +```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> add-address-to-group [destination-address | source-address] timeout \ +``` + +Timeout can be defined using seconds, minutes, hours or days: + +```none +set firewall ipv6 name FOO rule 10 add-address-to-group source-address timeout +Possible completions: +s Timeout value in seconds +m Timeout value in minutes +h Timeout value in hours +d Timeout value in days +``` + +#### Using Dynamic Firewall Groups + +Like other firewall groups, you can use dynamic firewall groups in firewall +rules as matching options. For example: + +```none +set firewall ipv4 input filter rule 10 source group dynamic-address-group FOO +set firewall ipv4 input filter rule 10 destination group dynamic-address-group BAR +``` + +## Examples + +### General example + +After you create firewall groups, you can reference them in firewall, NAT, +NAT66, and/or policy-route rules. The following example creates multiple +groups: + +```{eval-rst} + .. code-block:: none + + set firewall group address-group SERVERS address 198.51.100.101 + set firewall group address-group SERVERS address 198.51.100.102 + set firewall group network-group TRUSTEDv4 network 192.0.2.0/30 + set firewall group network-group TRUSTEDv4 network 203.0.113.128/25 + set firewall group ipv6-network-group TRUSTEDv6 network 2001:db8::/64 + set firewall group interface-group LAN interface eth2.2001 + set firewall group interface-group LAN interface bon0 + set firewall group port-group PORT-SERVERS port http + set firewall group port-group PORT-SERVERS port 443 + set firewall group port-group PORT-SERVERS port 5000-5010 +``` + +And next, some configuration example where groups are used: + +```{eval-rst} + .. code-block:: none + + set firewall ipv4 output filter rule 10 action accept + set firewall ipv4 output filter rule 10 outbound-interface group !LAN + set firewall ipv4 forward filter rule 20 action accept + set firewall ipv4 forward filter rule 20 source group network-group TRUSTEDv4 + set firewall ipv6 input filter rule 10 action accept + set firewall ipv6 input filter rule 10 source group network-group TRUSTEDv6 + set nat destination rule 101 inbound-interface group LAN + set nat destination rule 101 destination group address-group SERVERS + set nat destination rule 101 protocol tcp + set nat destination rule 101 destination group port-group PORT-SERVERS + set nat destination rule 101 translation address 203.0.113.250 + set policy route PBR rule 201 destination group port-group PORT-SERVERS + set policy route PBR rule 201 protocol tcp + set policy route PBR rule 201 set table 15 +``` + +### Port knocking example + +You can use dynamic firewall groups with port knocking to secure access to +the router or any other device. The following example shows a 4-step port +knocking configuration: + +```{eval-rst} + .. code-block:: none + + set firewall global-options state-policy established action 'accept' + set firewall global-options state-policy invalid action 'drop' + set firewall global-options state-policy related action 'accept' + set firewall group dynamic-group address-group ALLOWED + set firewall group dynamic-group address-group PN_01 + set firewall group dynamic-group address-group PN_02 + set firewall ipv4 input filter default-action 'drop' + set firewall ipv4 input filter rule 5 action 'accept' + set firewall ipv4 input filter rule 5 protocol 'icmp' + set firewall ipv4 input filter rule 10 action 'drop' + set firewall ipv4 input filter rule 10 add-address-to-group source-address address-group 'PN_01' + set firewall ipv4 input filter rule 10 add-address-to-group source-address timeout '2m' + set firewall ipv4 input filter rule 10 description 'Port_nock 01' + set firewall ipv4 input filter rule 10 destination port '9990' + set firewall ipv4 input filter rule 10 protocol 'tcp' + set firewall ipv4 input filter rule 20 action 'drop' + set firewall ipv4 input filter rule 20 add-address-to-group source-address address-group 'PN_02' + set firewall ipv4 input filter rule 20 add-address-to-group source-address timeout '3m' + set firewall ipv4 input filter rule 20 description 'Port_nock 02' + set firewall ipv4 input filter rule 20 destination port '9991' + set firewall ipv4 input filter rule 20 protocol 'tcp' + set firewall ipv4 input filter rule 20 source group dynamic-address-group 'PN_01' + set firewall ipv4 input filter rule 30 action 'drop' + set firewall ipv4 input filter rule 30 add-address-to-group source-address address-group 'ALLOWED' + set firewall ipv4 input filter rule 30 add-address-to-group source-address timeout '2h' + set firewall ipv4 input filter rule 30 description 'Port_nock 03' + set firewall ipv4 input filter rule 30 destination port '9992' + set firewall ipv4 input filter rule 30 protocol 'tcp' + set firewall ipv4 input filter rule 30 source group dynamic-address-group 'PN_02' + set firewall ipv4 input filter rule 99 action 'accept' + set firewall ipv4 input filter rule 99 description 'Port_nock 04 - Allow ssh' + set firewall ipv4 input filter rule 99 destination port '22' + set firewall ipv4 input filter rule 99 protocol 'tcp' + set firewall ipv4 input filter rule 99 source group dynamic-address-group 'ALLOWED' +``` + +Before testing, we can check the members of firewall groups: + +```none +vyos@vyos# run show firewall group +Firewall Groups + +Name Type References Members Timeout Expires +------- ---------------------- -------------------- ------------- --------- --------- +ALLOWED address_group(dynamic) ipv4-input-filter-30 N/D N/D N/D +PN_01 address_group(dynamic) ipv4-input-filter-10 N/D N/D N/D +PN_02 address_group(dynamic) ipv4-input-filter-20 N/D N/D N/D +[edit] +vyos@vyos# +``` + +With this configuration, to gain SSH access to the router, the user must: + +1. Create a new TCP connection to destination port 9990. A new entry is added + to dynamic firewall group `PN_01`. + + ```none + vyos@vyos# run show firewall group + Firewall Groups + + Name Type References Members Timeout Expires + ------- ---------------------- -------------------- ------------- --------- --------- + ALLOWED address_group(dynamic) ipv4-input-filter-30 N/D N/D N/D + PN_01 address_group(dynamic) ipv4-input-filter-10 192.168.89.31 120 119 + PN_02 address_group(dynamic) ipv4-input-filter-20 N/D N/D N/D + [edit] + vyos@vyos# + ``` + +2. Create a new TCP connection to destination port 9991. A new entry is added + to dynamic firewall group `PN_02`. + + ```none + vyos@vyos# run show firewall group + Firewall Groups + + Name Type References Members Timeout Expires + ------- ---------------------- -------------------- ------------- --------- --------- + ALLOWED address_group(dynamic) ipv4-input-filter-30 N/D N/D N/D + PN_01 address_group(dynamic) ipv4-input-filter-10 192.168.89.31 120 106 + PN_02 address_group(dynamic) ipv4-input-filter-20 192.168.89.31 180 179 + [edit] + vyos@vyos# + ``` + +3. Create a new TCP connection to destination port 9992. A new entry is added + to dynamic firewall group `ALLOWED`. + + ```none + vyos@vyos# run show firewall group + Firewall Groups + + Name Type References Members Timeout Expires + ------- ---------------------- -------------------- ------------- --------- --------- + ALLOWED address_group(dynamic) ipv4-input-filter-30 192.168.89.31 7200 7199 + PN_01 address_group(dynamic) ipv4-input-filter-10 192.168.89.31 120 89 + PN_02 address_group(dynamic) ipv4-input-filter-20 192.168.89.31 180 170 + [edit] + vyos@vyos# + ``` + +4. Now you can connect via SSH to the router (assuming SSH is + configured). + +## Operation-mode + +```{opcmd} show firewall group +``` + +```{opcmd} show firewall group \ + +Display an overview of defined groups, including the firewall group name, +type, references (where the group is used), members, timeout, and +expiration (the last two only apply to dynamic firewall groups). +``` + +Here is an example of such command: + +```none +vyos@vyos:~$ show firewall group +Firewall Groups + +Name Type References Members Timeout Expires +------------ ---------------------- ---------------------- ---------------- --------- --------- +SERVERS address_group nat-destination-101 198.51.100.101 + 198.51.100.102 +ALLOWED address_group(dynamic) ipv4-input-filter-30 192.168.77.39 7200 7174 +PN_01 address_group(dynamic) ipv4-input-filter-10 192.168.0.245 120 112 + 192.168.77.39 120 85 +PN_02 address_group(dynamic) ipv4-input-filter-20 192.168.77.39 180 151 +LAN interface_group ipv4-output-filter-10 bon0 + nat-destination-101 eth2.2001 +TRUSTEDv6 ipv6_network_group ipv6-input-filter-10 2001:db8::/64 +TRUSTEDv4 network_group ipv4-forward-filter-20 192.0.2.0/30 + 203.0.113.128/25 +PORT-SERVERS port_group route-PBR-201 443 + route-PBR-201 5000-5010 + nat-destination-101 http +vyos@vyos:~$ +``` diff --git a/docs/configuration/firewall/md-index.md b/docs/configuration/firewall/md-index.md new file mode 100644 index 00000000..9108a800 --- /dev/null +++ b/docs/configuration/firewall/md-index.md @@ -0,0 +1,278 @@ +--- +lastproofread: '2026-03-30' +--- + +# Firewall + +:::{warning} +Due to a boot-time race condition, all interfaces initialize +before the firewall. This temporarily leaves the system open to all traffic +and poses a security risk. +::: + +VyOS uses Netfilter. The Netfilter +project developed `iptables` and its successor `nftables` for the Linux +kernel to process packet data flows directly. This extends the concept of +zone-based security to let you manipulate data at multiple stages after the +network interface and driver accept it, and before sending it to its +destination (for example, a web server or another device). + +The following is a simplified traffic flow diagram based on Netfilter +packet flow. +This diagram provides an overview of how packets are processed and the +possible paths traffic can take. + +:::{figure} /_static/images/firewall-gral-packet-flow.webp +::: + +The main points regarding packet flow and terminology in VyOS firewall +are: + +- **Bridge Port?**: Choose the appropriate path based on whether the + interface where the packet was received is part of a bridge. + +If the interface where the packet was received is not part of a bridge, the +packet is processed at the **IP Layer**: + +```{eval-rst} + * **Prerouting**: The router processes all packets in this stage, + regardless of the destination. You can perform several actions in + this stage, and these actions are also defined in different parts of the + VyOS configuration. Order is important. The relevant configuration that + applies in this stage includes: + + * **Firewall prerouting**: Rules you define under ``set firewall + [ipv4 | ipv6] prerouting raw...``. The system processes all rules in + this section before the connection tracking subsystem. + + * **Conntrack Ignore**: Rules you define under ``set system conntrack + ignore [ipv4 | ipv6] ...``. You can configure this section with + ``firewall [ipv4 | ipv6] prerouting ...``. For compatibility reasons, + this feature is supported, but will be deprecated in the future. + + * **Policy Route**: Rules you define under ``set policy [route | + route6] ...``. + + * **Destination NAT**: Rules you define under ``set [nat | nat66] + destination...``. + + * **Destination is the router?**: Choose the appropriate path based on the + destination IP address. Transit traffic continues to **forward**, while + traffic destined for the router continues to **input**. + + * **Input**: The stage where you filter and control traffic destined for + the router itself. This is where you enforce all rules for securing the + router. This includes IPv4 and IPv6 filtering rules, defined in: + + * ``set firewall ipv4 input filter ...``. + + * ``set firewall ipv6 input filter ...``. + + * **Forward**: The stage where you filter and control transit traffic. + This includes IPv4 and IPv6 filtering rules, defined in: + + * ``set firewall ipv4 forward filter ...``. + + * ``set firewall ipv6 forward filter ...``. + + * **Output**: The stage where you filter and control traffic that the + router originates. Note that this traffic comes from either a new + connection that an internal process on the VyOS router (such as NTP) + originates or a response to traffic the router receives externally through + **input** (for example, a response to an SSH login attempt). This includes + IPv4 and IPv6 rules, and two different sections apply: + + * **Output Prerouting**: ``set firewall [ipv4 | ipv6] output + 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 new file mode 100644 index 00000000..e5c0a986 --- /dev/null +++ b/docs/configuration/firewall/md-ipv4.md @@ -0,0 +1,1517 @@ +--- +lastproofread: '2026-03-30' +--- + +(firewall-ipv4-configuration)= + +# IPv4 Firewall Configuration + +## Overview + +This section provides information on IPv4 firewall configuration and +appropriate operation-mode commands. This section covers the following +configuration commands: + +```{cfgcmd} set firewall ipv4 ... +``` + +To learn about the general traffic flow in VyOS firewalls, see {doc}`Firewall `. + +```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_ADDRESSES address_group WAN_IN-170 192.168.5.2 +WAN_IN-171 +PBX ipv6_address_group IPV6-WAN_IN-100 2001:db8::1 +SERVERS ipv6_address_group IPV6-WAN_IN-110 2001:db8::2 +IPV6-WAN_IN-111 2001:db8::3 +IPV6-WAN_IN-112 2001:db8::4 +IPV6-WAN_IN-120 +IPV6-WAN_IN-121 +IPV6-WAN_IN-122 +SUPPORT ipv6_address_group IPV6-VyOS_MANAGEMENT-20 2001:db8::5 +IPV6-WAN_IN-20 +::: +``` + +```{opcmd} show firewall ipv4 [forward | input | output] filter +``` + +```{opcmd} show firewall ipv4 name \ + +This command will give an overview of a single rule-set. + +:::{code-block} none +vyos@vyos:~$ show firewall ipv4 input filter +Ruleset Information +--------------------------------- +IPv4 Firewall "input filter" +Rule Action Protocol Packets Bytes Conditions +------- -------- ---------- --------- ------- ----------------------------------------- +5 jump all 0 0 iifname "eth2" jump NAME_VyOS_MANAGEMENT +default accept all +::: +``` + +```{opcmd} show firewall ipv4 [forward | input | output] filter rule \<1-999999\> +``` + +```{opcmd} show firewall ipv4 name \ rule \<1-999999\> + +This command gives an overview of a rule in a single rule-set, plus +information for default action. +``` +```none +vyos@vyos:~$show firewall ipv4 output filter rule 20 +Rule Information + +--------------------------------- +ipv4 Firewall "output filter" + +Rule Action Protocol Packets Bytes Conditions +------- -------- ---------- --------- ------- ---------------------------------------- +20 accept icmp 2 168 meta l4proto icmp oifname "eth0" accept +default accept all 286 47614 + +vyos@vyos:~$ +``` + +```{opcmd} show firewall statistics + +This will show you statistics of all rule-sets since the last boot. +``` + +### Show Firewall log + +```{opcmd} show log firewall + +``` +```{opcmd} show log firewall ipv4 +``` + +```{opcmd} show log firewall ipv4 [forward | input | output | name] +``` + +```{opcmd} show log firewall ipv4 [forward | input | output] filter +``` + +```{opcmd} show log firewall ipv4 name \ +``` + +```{opcmd} show log firewall ipv4 [forward | input | output] filter rule \ +``` + +```{opcmd} show log firewall ipv4 name \ rule \ + +Show the logs of all firewall; show all IPv4 firewall logs; show all logs +for particular hook; show all logs for particular hook and priority; +show all logs for particular custom chain; show logs for specific rule-set. +``` + +### Example Partial Config + +```none +firewall { + group { + network-group BAD-NETWORKS { + network 198.51.100.0/24 + network 203.0.113.0/24 + } + network-group GOOD-NETWORKS { + network 192.0.2.0/24 + } + port-group BAD-PORTS { + port 65535 + } + } + ipv4 { + forward { + filter { + default-action accept + rule 5 { + action accept + source { + group { + network-group GOOD-NETWORKS + } + } + } + rule 10 { + action drop + description "Bad Networks" + protocol all + source { + group { + network-group BAD-NETWORKS + } + } + } + } + } + } +} +``` + +### Update geoip database + +```{opcmd} update geoip + +Command to update GeoIP database and firewall sets. +``` \ No newline at end of file diff --git a/docs/configuration/firewall/md-ipv6.md b/docs/configuration/firewall/md-ipv6.md new file mode 100644 index 00000000..e9011b4c --- /dev/null +++ b/docs/configuration/firewall/md-ipv6.md @@ -0,0 +1,1567 @@ +--- +lastproofread: '2026-04-01' +--- + +(firewall-ipv6-configuration)= + +# IPv6 Firewall Configuration + +## Overview + +This section covers useful information about IPv6 firewall configuration and +appropriate operation-mode commands. + +This section describes the following configuration commands: + +```{cfgcmd} set firewall ipv6 ... +``` + +To learn about the general traffic flow in VyOS firewalls, see {doc}`Firewall `. + +```none +- set firewall + * ipv6 + - forward + + filter + - input + + filter + - output + + filter + + raw + - prerouting + + raw + - name + + custom_name +``` + +The router first receives all traffic and processes it in the **prerouting** +section. + + +This stage includes: + + +- **Firewall Prerouting**: commands found under `set firewall ipv6 + prerouting raw ...` +- {doc}`Conntrack Ignore`: `set system + conntrack ignore ipv6...` +- {doc}`Policy Route`: commands found under + `set policy route6 ...` +- {doc}`Destination NAT`: commands found under + `set nat66 destination ...` + + +For transit traffic that the router receives and forwards, the base chain is +**forward**. The following diagram shows a simplified packet flow for transit +traffic: + + +:::{figure} /_static/images/firewall-fwd-packet-flow.webp +::: + + +Use `set firewall ipv6 forward filter ...` to configure filtering rules for +transit traffic. This command corresponds to stage 5 and is highlighted in red +in the diagram. + + +For traffic destined to the router, use the **input** chain. For traffic the +router generates, use the **output** chain. The following diagram shows the +packet flow for traffic destined to the router and traffic generated by the +router (starting from circle number 6): + + +:::{figure} /_static/images/firewall-input-packet-flow.webp +::: + + +Use `set firewall ipv6 input filter ...` to configure traffic destined to +the router. + + +Use `set firewall ipv6 output ...` to configure traffic the router generates. +Two sub-chains are available: **filter** and **raw**: + + +- **Output Prerouting**: `set firewall ipv6 output raw ...`. + As described in **Prerouting**, the firewall processes rules in this + section before the connection tracking subsystem. +- **Output Filter**: `set firewall ipv6 output filter ...`. The firewall + processes rules in this section after the connection tracking subsystem. + + +:::{note} +**Important note about default-actions:** +If you do not define a default action for a base chain, the system sets +the default action to **accept** for that chain. For custom chains, if you +do not define a default action, the system sets the default-action to +**drop** +::: + + +Create custom firewall chains using the commands +`set firewall ipv6 name ...`. To use the custom chain, define a +rule with **action jump** and the appropriate **target** in a base chain. + + +## Firewall - IPv6 Rules + + +Create firewall rules for firewall filtering. Each rule is numbered and has +an action to apply when the rule is matched. You can specify multiple matching +criteria. Packets go through rules from 1 - 999999, so order is crucial. The +firewall executes the action of the first matching rule. + + +### Actions + + +If you define a rule, you must define an action for it. The action tells the +firewall what to do when all criteria for that rule are met. + + +The action can be : + + +- `accept`: accept the packet. +- `continue`: continue parsing next rule. +- `drop`: drop the packet. +- `reject`: reject the packet. +- `jump`: jump to another custom chain. +- `return`: Return from the current chain and continue at the next rule + of the last chain. +- `queue`: Enqueue packet to userspace. +- `synproxy`: synproxy the packet. + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> action [accept | continue | drop | jump | queue | reject | return | synproxy] +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> action [accept | continue | drop | jump | queue | reject | return | synproxy] +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> action [accept | continue | drop | jump | queue | reject | return] +``` + +```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> action [accept | continue | drop | jump | queue | reject | return] + +This required setting defines the action of the current rule. If you set +the action to jump, you must also define a jump-target. +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> jump-target \ +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> jump-target \ +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> jump-target \ +``` + +```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> jump-target \ + +Use this command only when action is set to ``jump``. Specify the jump +target. +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> queue \<0-65535\> +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> queue \<0-65535\> +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> queue \<0-65535\> +``` + +```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> queue \<0-65535\> + +Use this command only when action is set to ``queue``. Specify the queue +target. Queue ranges are also supported. +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> queue-options bypass +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> queue-options bypass +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> queue-options bypass +``` + +```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> queue-options bypass + +Use this command only when action is set to ``queue``. This command allows +the packet to go through the firewall when no userspace software is connected +to the queue. +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> queue-options fanout +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> queue-options fanout +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> queue-options fanout +``` + +```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> queue-options fanout + +Use this command only when action is set to ``queue``. This command +distributes packets among multiple queues. +``` + +Also, **default-action** is an action that takes place whenever a packet does +not match any rule in its chain. For base chains, possible options for +**default-action** are **accept** or **drop**. + +```{cfgcmd} set firewall ipv6 forward filter default-action [accept | drop] +``` + +```{cfgcmd} set firewall ipv6 input filter default-action [accept | drop] +``` + +```{cfgcmd} set firewall ipv6 output filter default-action [accept | drop] +``` + +```{cfgcmd} set firewall ipv6 name \ default-action [accept | drop | jump | queue | reject | return] + +Set the default action of the rule-set if a packet does not match any rule +criteria. If you set default-action to ``jump``, you must also define +``default-jump-target``. For base chains, you can only set the default +action to ``accept`` or ``drop``. For custom chains, more actions are +available. +``` + +```{cfgcmd} set firewall ipv6 name \ default-jump-target \ + +To be used only when ``default-action`` is set to ``jump``. Use this +command to specify the jump target for the default rule. +``` +:::{note} +**Important note about default-actions:** +If you do not define the default action for a base chain, the system sets +the default action to **accept** for that chain. For custom chains, if you +do not define a default action, the system sets the default-action to +**drop**. +::: + + +### Firewall Logs + + +You can enable logging for each firewall rule. When enabled, you can also +define other log options. + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> log +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> log +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> log +``` + +```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> log + +Enable logging for matched packets. If this configuration command is not +present, logging is disabled. +``` + +```{cfgcmd} set firewall ipv6 forward filter default-log +``` + +```{cfgcmd} set firewall ipv6 input filter default-log +``` + +```{cfgcmd} set firewall ipv6 output filter default-log +``` + +```{cfgcmd} set firewall ipv6 name \ default-log + +Use this command to enable the logging of the default action on +the specified chain. +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> log-options level [emerg | alert | crit | err | warn | notice | info | debug] +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> log-options level [emerg | alert | crit | err | warn | notice | info | debug] +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> log-options level [emerg | alert | crit | err | warn | notice | info | debug] +``` + +```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> log-options level [emerg | alert | crit | err | warn | notice | info | debug] + +Define log-level. Only applicable if rule log is enabled. +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> log-options group \<0-65535\> +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> log-options group \<0-65535\> +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> log-options group \<0-65535\> +``` + +```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> log-options group \<0-65535\> + +Define the log group to send messages to. Only applicable if rule log is +enabled. +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> log-options snapshot-length \<0-9000\> +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> log-options snapshot-length \<0-9000\> +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> log-options snapshot-length \<0-9000\> +``` + +```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> log-options snapshot-length \<0-9000\> + +Define the length of packet payload to include in a netlink message. Only +applicable when rule logging is enabled and log group is defined. +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> log-options queue-threshold \<0-65535\> +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> log-options queue-threshold \<0-65535\> +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> log-options queue-threshold \<0-65535\> +``` + +```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> log-options queue-threshold \<0-65535\> + +Define the number of packets to queue inside the kernel before sending them +to userspace. Only applicable when rule logging is enabled and log group is +defined. +``` + +### Firewall Description + + +For reference, you can define descriptions on every rule and custom chain. + +```{cfgcmd} set firewall ipv6 name \ description \ + +Provide a rule-set description to a custom firewall chain. +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> description \ +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> description \ +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> description \ +``` + +```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> description \ + +Provide a description for each rule. +``` + +### Rule Status + + +New rules are enabled by default. In some cases, you may want to disable a +rule rather than remove it. + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> disable +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> disable +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> disable +``` + +```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> disable + +Command for disabling a rule but keep it in the configuration. +``` + +### Matching criteria + + +There are a lot of matching criteria against which the packet can be tested. + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> connection-status nat [destination | source] +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> connection-status nat [destination | source] +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> connection-status nat [destination | source] +``` + +```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> connection-status nat [destination | source] + +Match packets based on NAT connection status. +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> connection-mark \<1-2147483647\> +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> connection-mark \<1-2147483647\> +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> connection-mark \<1-2147483647\> +``` + +```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> connection-mark \<1-2147483647\> + +Match packets based on connection mark. +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> source address [address | addressrange | CIDR] +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> source address [address | addressrange | CIDR] +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> source address [address | addressrange | CIDR] +``` + +```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> source address [address | addressrange | CIDR] +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> destination address [address | addressrange | CIDR] +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> destination address [address | addressrange | CIDR] +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> destination address [address | addressrange | CIDR] +``` + +```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> destination address [address | addressrange | CIDR] + +Match based on source or destination address. This is similar to network +groups, but you can negate the matching addresses here. + +:::{code-block} none +set firewall ipv6 name FOO rule 100 source address 2001:db8::202 +::: +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> source address-mask [address] +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> source address-mask [address] +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> source address-mask [address] +``` + +```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> source address-mask [address] +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> destination address-mask [address] +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> destination address-mask [address] +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> destination address-mask [address] +``` + +```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> destination address-mask [address] + +Apply an arbitrary netmask to mask addresses and match only a specific +portion. This is useful for IPv6 because rules remain valid when the IPv6 +prefix changes if the host portion of the system's IPv6 address is static. +Examples include SLAAC and tokenised IPv6 addresses + +This function works for both individual addresses and address groups. + + +:::{code-block} none +# Match any IPv6 address with the suffix ::0000:0000:0000:beef +set firewall ipv6 forward filter rule 100 destination address ::beef +set firewall ipv6 forward filter rule 100 destination address-mask ::ffff:ffff:ffff:ffff +# Address groups +set firewall group ipv6-address-group WEBSERVERS address ::1000 +set firewall group ipv6-address-group WEBSERVERS address ::2000 +set firewall ipv6 forward filter rule 200 source group address-group WEBSERVERS +set firewall ipv6 forward filter rule 200 source address-mask ::ffff:ffff:ffff:ffff +::: +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> source fqdn \ +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> source fqdn \ +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> source fqdn \ +``` + +```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> source fqdn \ +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> destination fqdn \ +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> destination fqdn \ +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> destination fqdn \ +``` + +```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> destination fqdn \ + +Specify a Fully Qualified Domain Name as source or destination to match. +Ensure that the router can resolve the DNS query. +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> source geoip country-code \ +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> source geoip country-code \ +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> source geoip country-code \ +``` + +```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> source geoip country-code \ +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> destination geoip country-code \ +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> destination geoip country-code \ +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> destination geoip country-code \ +``` + +```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> destination geoip country-code \ +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> source geoip inverse-match +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> source geoip inverse-match +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> source geoip inverse-match +``` + +```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> source geoip inverse-match +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> destination geoip inverse-match +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> destination geoip inverse-match +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> destination geoip inverse-match +``` + +```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> destination geoip inverse-match + +Match IP addresses based on their geolocation. For more information, see +GeoIP matching. +Use inverse-match to match anything except the specified country codes. +``` + +DB-IP.com provides data under CC-BY-4.0 license. Attribution is required and +redistribution is permitted, allowing VyOS to include a database in images +(approximately 3 MB compressed). The package includes a cron script that you +can manually call through op-mode update geoip to keep the database and rules +updated. + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> source mac-address \ +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> source mac-address \ +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> source mac-address \ +``` + +```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> source mac-address \ + +You can specify only a source MAC address to match. + +:::{code-block} none +set firewall ipv6 input filter rule 100 source mac-address 00:53:00:11:22:33 +set firewall ipv6 input filter rule 101 source mac-address !00:53:00:aa:12:34 +::: +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> source port [1-65535 | portname | start-end] +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> source port [1-65535 | portname | start-end] +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> source port [1-65535 | portname | start-end] +``` + +```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> source port [1-65535 | portname | start-end] +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> destination port [1-65535 | portname | start-end] +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> destination port [1-65535 | portname | start-end] +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> destination port [1-65535 | portname | start-end] +``` + +```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> destination port [1-65535 | portname | start-end] + +Specify a port by number or by name as defined in ``/etc/services``. + +:::{code-block} none +set firewall ipv6 forward filter rule 10 source port '22' +set firewall ipv6 forward filter rule 11 source port '!http' +set firewall ipv6 forward filter rule 12 source port 'https' +::: +Multiple source ports can be specified as a comma-separated list. +The whole list can also be "negated" using ``!``. For example: + +:::{code-block} none +set firewall ipv6 forward filter rule 10 source port '!22,https,3333-3338' +::: +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> source group address-group \ +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> source group address-group \ +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> source group address-group \ +``` + +```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> source group address-group \ +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> destination group address-group \ +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> destination group address-group \ +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> destination group address-group \ +``` + +```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> destination group address-group \ + +Specify an address group. You can prepend the character ``!`` to invert the +matching criteria. +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> source group dynamic-address-group \ +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> source group dynamic-address-group \ +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> source group dynamic-address-group \ +``` + +```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> source group dynamic-address-group \ +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> destination group dynamic-address-group \ +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> destination group dynamic-address-group \ +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> destination group dynamic-address-group \ +``` + +```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> destination group dynamic-address-group \ + +Specify a dynamic address group. You can prepend the character ``!`` to +invert the matching criteria. +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> source group network-group \ +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> source group network-group \ +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> source group network-group \ +``` + +```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> source group network-group \ +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> destination group network-group \ +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> destination group network-group \ +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> destination group network-group \ +``` + +```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> destination group network-group \ + +Specify a network group. You can prepend the character ``!`` to invert the +matching criteria. +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> source group port-group \ +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> source group port-group \ +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> source group port-group \ +``` + +```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> source group port-group \ +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> destination group port-group \ +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> destination group port-group \ +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> destination group port-group \ +``` + +```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> destination group port-group \ + +Specify a port group. You can prepend the character ``!`` to invert the +matching criteria. +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> source group domain-group \ +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> source group domain-group \ +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> source group domain-group \ +``` + +```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> source group domain-group \ +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> destination group domain-group \ +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> destination group domain-group \ +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> destination group domain-group \ +``` + +```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> destination group domain-group \ + +Specify a domain group. You can prepend the character ``!`` to invert the +matching criteria. +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> source group mac-group \ +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> source group mac-group \ +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> source group mac-group \ +``` + +```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> source group mac-group \ +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> destination group mac-group \ +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> destination group mac-group \ +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> destination group mac-group \ +``` + +```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> destination group mac-group \ + +Specify a MAC group. You can prepend the character ``!`` to invert the +matching criteria. +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> dscp [0-63 | start-end] +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> dscp [0-63 | start-end] +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> dscp [0-63 | start-end] +``` + +```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> dscp [0-63 | start-end] +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> dscp-exclude [0-63 | start-end] +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> dscp-exclude [0-63 | start-end] +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> dscp-exclude [0-63 | start-end] +``` + +```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> dscp-exclude [0-63 | start-end] + +Match based on dscp value. +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> fragment [match-frag | match-non-frag] +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> fragment [match-frag | match-non-frag] +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> fragment [match-frag | match-non-frag] +``` + +```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> fragment [match-frag | match-non-frag] + +Match packets based on fragmentation. +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> icmpv6 [code | type] \<0-255\> +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> icmpv6 [code | type] \<0-255\> +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> icmpv6 [code | type] \<0-255\> +``` + +```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> icmpv6 [code | type] \<0-255\> + +Match packets based on ICMP or ICMPv6 code and type. +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> icmpv6 type-name \ +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> icmpv6 type-name \ +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> icmpv6 type-name \ +``` + +```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> icmpv6 type-name \ + +Match based on ICMPv6 type-name. Press **Tab** for information about +supported **type-name** criteria. +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> inbound-interface name \ +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> inbound-interface name \ +``` + +```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> inbound-interface name \ + +Match based on inbound interface. You can use the wildcard ``*``. For +example: ``eth2*``. You can prepend the character ``!`` to invert the +matching criteria. For example ``!eth2`` +``` +:::{note} +If an interface is attached to a non-default VRF, when using +**inbound-interface**, use the VRF name. For example: +`set firewall ipv6 forward filter rule 10 inbound-interface name MGMT` +::: +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> inbound-interface group \ +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> inbound-interface group \ +``` + +```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> inbound-interface group \ + +Match based on the inbound interface group. You can prepend the character +``!`` to invert the matching criteria. For example ``!IFACE_GROUP`` +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> outbound-interface name \ +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> outbound-interface name \ +``` + +```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> outbound-interface name \ + +Match based on outbound interface. You can use the wildcard ``*``. For +example: ``eth2*``. You can prepend the character ``!`` to invert the +matching criteria. For example ``!eth2`` +``` +:::{note} +If an interface is attached to a non-default VRF, when using +**outbound-interface**, use the physical interface name. For example: +`set firewall ipv6 forward filter rule 10 outbound-interface name eth0` +::: +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> outbound-interface group \ +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> outbound-interface group \ +``` + +```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> outbound-interface group \ + +Match based on outbound interface group. You can prepend the character ``!`` +to invert the matching criteria. For example ``!IFACE_GROUP`` +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> ipsec [match-ipsec-in | match-ipsec-out | match-none-in | match-none-out] +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> ipsec [match-ipsec-in | match-none-in] +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> ipsec [match-ipsec-out | match-none-out] +``` + +```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> ipsec [match-ipsec-in | match-ipsec-out | match-none-in | match-none-out] + +Match packets based on IPsec. +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> limit burst \<0-4294967295\> +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> limit burst \<0-4294967295\> +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> limit burst \<0-4294967295\> +``` + +```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> limit burst \<0-4294967295\> + +Match based on the maximum number of packets allowed to exceed the rate +limit. +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> limit rate \ +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> limit rate \ +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> limit rate \ +``` + +```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> limit rate \ + +Match based on the maximum average rate, specified as ``integer/unit``. +For example, specify ``5/minutes``. +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> packet-length \ +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> packet-length \ +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> packet-length \ +``` + +```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> packet-length \ +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> packet-length-exclude \ +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> packet-length-exclude \ +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> packet-length-exclude \ +``` + +```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> packet-length-exclude \ + +Match based on packet length. You can specify multiple values from 1 to +65535 and ranges. +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> packet-type [broadcast | host | multicast | other] +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> packet-type [broadcast | host | multicast | other] +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> packet-type [broadcast | host | multicast | other] +``` + +```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> packet-type [broadcast | host | multicast | other] + +Match based on packet type. +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> protocol [\ | \<0-255\> | all | tcp_udp] +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> protocol [\ | \<0-255\> | all | tcp_udp] +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> protocol [\ | \<0-255\> | all | tcp_udp] +``` + +```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> protocol [\ | \<0-255\> | all | tcp_udp] + +Match based on protocol number or name as defined in ``/etc/protocols``. +Specify ``all`` for all protocols and ``tcp_udp`` for TCP and UDP packets. +Prepend ``!`` to negate the protocol selection. + +:::{code-block} none +set firewall ipv6 input filter rule 10 protocol tcp +::: +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> recent count \<1-255\> +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> recent count \<1-255\> +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> recent count \<1-255\> +``` + +```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> recent count \<1-255\> +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> recent time [second | minute | hour] +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> recent time [second | minute | hour] +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> recent time [second | minute | hour] +``` + +```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> recent time [second | minute | hour] + +Match packets based on recently seen sources. +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> tcp flags [not] \ +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> tcp flags [not] \ +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> tcp flags [not] \ +``` + +```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> tcp flags [not] \ + +Allowed values for TCP flags: ``ack``, ``cwr``, ``ecn``, ``fin``, ``psh``, +``rst``, ``syn``, and ``urg``. You can specify multiple values. To invert +the selection, use ``not``, as shown in the following example. + +:::{code-block} none +set firewall ipv6 input filter rule 10 tcp flags 'ack' +set firewall ipv6 input filter rule 12 tcp flags 'syn' +set firewall ipv6 input filter rule 13 tcp flags not 'fin' +::: +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> state [established | invalid | new | related] +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> state [established | invalid | new | related] +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> state [established | invalid | new | related] +``` + +```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> state [established | invalid | new | related] + +Match based on packet state. +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> time startdate \ +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> time startdate \ +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> time startdate \ +``` + +```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> time startdate \ +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> time starttime \ +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> time starttime \ +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> time starttime \ +``` + +```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> time starttime \ +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> time stopdate \ +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> time stopdate \ +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> time stopdate \ +``` + +```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> time stopdate \ +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> time stoptime \ +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> time stoptime \ +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> time stoptime \ +``` + +```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> time stoptime \ +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> time weekdays \ +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> time weekdays \ +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> time weekdays \ +``` + +```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> time weekdays \ + +Match packets based on time criteria. +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> hop-limit \ \<0-255\> +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> hop-limit \ \<0-255\> +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> hop-limit \ \<0-255\> +``` + +```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> hop-limit \ \<0-255\> + +Match the hop-limit parameter. Use ``eq`` for equal, ``gt`` for greater than, +and ``lt`` for less than. +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> recent count \<1-255\> +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> recent count \<1-255\> +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> recent count \<1-255\> +``` + +```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> recent count \<1-255\> +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> recent time \ +``` + +```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> recent time \ +``` + +```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> recent time \ +``` + +```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> recent time \ + +Match when the specified number of connections occur within the specified +time period. Use these criteria to block brute-force attempts. +``` + +### Packet Modifications + + +The firewall can modify packets before sending them. +This feature provides more flexibility for packet handling. + +```{cfgcmd} set firewall ipv6 prerouting raw rule \<1-999999\> set dscp \<0-63\> +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> set dscp \<0-63\> +``` + +```{cfgcmd} set firewall ipv6 output [filter | raw] rule \<1-999999\> set dscp \<0-63\> + +Set a specific value of Differentiated Services Codepoint (DSCP). +``` + +```{cfgcmd} set firewall ipv6 prerouting raw rule \<1-999999\> set mark \<1-2147483647\> +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> set mark \<1-2147483647\> +``` + +```{cfgcmd} set firewall ipv6 output [filter | raw] rule \<1-999999\> set mark \<1-2147483647\> + +Set a specific packet mark value. +``` + +```{cfgcmd} set firewall ipv6 prerouting raw rule \<1-999999\> set tcp-mss \<500-1460\> +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> set tcp-mss \<500-1460\> +``` + +```{cfgcmd} set firewall ipv6 output [filter | raw] rule \<1-999999\> set tcp-mss \<500-1460\> + +Set the TCP-MSS (TCP maximum segment size) for the connection. +``` + +```{cfgcmd} set firewall ipv6 prerouting raw rule \<1-999999\> set hop-limit \<0-255\> +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> set hop-limit \<0-255\> +``` + +```{cfgcmd} set firewall ipv6 output [filter | raw] rule \<1-999999\> set hop-limit \<0-255\> + +Set hop limit value. +``` + +```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> set connection-mark \<0-2147483647\> +``` + +```{cfgcmd} set firewall ipv6 output [filter | raw] rule \<1-999999\> set connection-mark \<0-2147483647\> + +Set connection mark value. +``` + +## Synproxy + + +Synproxy connections + +```{cfgcmd} set firewall ipv6 [input | forward] filter rule \<1-999999\> action synproxy +``` + +```{cfgcmd} set firewall ipv6 [input | forward] filter rule \<1-999999\> protocol tcp +``` + +```{cfgcmd} set firewall ipv6 [input | forward] filter rule \<1-999999\> synproxy tcp mss \<501-65535\> + + Set the TCP MSS (maximum segment size) for the connection. +``` + +```{cfgcmd} set firewall ipv6 [input | forward] filter rule \<1-999999\> synproxy tcp window-scale \<1-14\> + + Set the window scale factor for TCP window scaling. +``` + +### Example synproxy + + +Requirements to enable synproxy: + + +- Traffic must be symmetric +- Synproxy relies on syncookies and TCP timestamps, ensure these are enabled +- Disable conntrack loose track option + +```none +set system sysctl parameter net.ipv4.tcp_timestamps value '1' + + +set system conntrack tcp loose disable + +set system conntrack ignore ipv6 rule 10 destination port '8080' + +set system conntrack ignore ipv6 rule 10 protocol 'tcp' + +set system conntrack ignore ipv6 rule 10 tcp flags syn + + +set firewall global-options syn-cookies 'enable' + +set firewall ipv6 input filter rule 10 action 'synproxy' + +set firewall ipv6 input filter rule 10 destination port '8080' + +set firewall ipv6 input filter rule 10 inbound-interface name 'eth1' + +set firewall ipv6 input filter rule 10 protocol 'tcp' + +set firewall ipv6 input filter rule 10 synproxy tcp mss '1460' + +set firewall ipv6 input filter rule 10 synproxy tcp window-scale '7' + +set firewall ipv6 input filter rule 1000 action 'drop' + +set firewall ipv6 input filter rule 1000 state invalid + +``` + +## Operation-mode Firewall + + +### Rule-set overview + +```{opcmd} show firewall + +Show a basic firewall overview for all rule-sets, not only for IPv6: + +:::{code-block} none +vyos@vyos:~$ show firewall +Rulesets Information + +--------------------------------- +IPv4 Firewall "forward filter" + +Rule Action Protocol Packets Bytes Conditions +------- -------- ---------- --------- ------- ----------------------------------------- +5 jump all 0 0 iifname "eth1" jump NAME_VyOS_MANAGEMENT +10 jump all 0 0 oifname "eth1" jump NAME_WAN_IN +15 jump all 0 0 iifname "eth3" jump NAME_WAN_IN +default accept all + +--------------------------------- +IPv4 Firewall "name VyOS_MANAGEMENT" + +Rule Action Protocol Packets Bytes Conditions +------- -------- ---------- --------- ------- -------------------------------- +5 accept all 0 0 ct state established accept +10 drop all 0 0 ct state invalid +20 accept all 0 0 ip saddr @A_GOOD_GUYS accept +30 accept all 0 0 ip saddr @N_ENTIRE_RANGE accept +40 accept all 0 0 ip saddr @A_VyOS_SERVERS accept +50 accept icmp 0 0 meta l4proto icmp accept +default drop all 0 0 + +--------------------------------- +IPv6 Firewall "forward filter" + +Rule Action Protocol +------- -------- ---------- +5 jump all +10 jump all +15 jump all +default accept all + +--------------------------------- +IPv6 Firewall "input filter" + +Rule Action Protocol +------- -------- ---------- +5 jump all +default accept all + +--------------------------------- +IPv6 Firewall "ipv6_name IPV6-VyOS_MANAGEMENT" + +Rule Action Protocol +------- -------- ---------- +5 accept all +10 drop all +20 accept all +30 accept all +40 accept all +50 accept ipv6-icmp +default drop all +::: +``` + +```{opcmd} show firewall summary + +This will show you a summary of rule-sets and groups + +:::{code-block} none +vyos@vyos:~$ show firewall summary +Ruleset Summary + +IPv6 Ruleset: + +Ruleset Hook Ruleset Priority Description +-------------- -------------------- ------------------------- +forward filter +input filter +ipv6_name IPV6-VyOS_MANAGEMENT +ipv6_name IPV6-WAN_IN PUBLIC_INTERNET + +IPv4 Ruleset: + +Ruleset Hook Ruleset Priority Description +-------------- ------------------ ------------------------- +forward filter +input filter +name VyOS_MANAGEMENT +name WAN_IN PUBLIC_INTERNET + +Firewall Groups + +Name Type References Members +----------------------- ------------------ ----------------------- ---------------- +PBX address_group WAN_IN-100 198.51.100.77 +SERVERS address_group WAN_IN-110 192.0.2.10 +WAN_IN-111 192.0.2.11 +WAN_IN-112 192.0.2.12 +WAN_IN-120 +WAN_IN-121 +WAN_IN-122 +SUPPORT address_group VyOS_MANAGEMENT-20 192.168.1.2 +WAN_IN-20 +PHONE_VPN_SERVERS address_group WAN_IN-160 10.6.32.2 +PINGABLE_ADDRESSES address_group WAN_IN-170 192.168.5.2 +WAN_IN-171 +PBX ipv6_address_group IPV6-WAN_IN-100 2001:db8::1 +SERVERS ipv6_address_group IPV6-WAN_IN-110 2001:db8::2 +IPV6-WAN_IN-111 2001:db8::3 +IPV6-WAN_IN-112 2001:db8::4 +IPV6-WAN_IN-120 +IPV6-WAN_IN-121 +IPV6-WAN_IN-122 +SUPPORT ipv6_address_group IPV6-VyOS_MANAGEMENT-20 2001:db8::5 +IPV6-WAN_IN-20 +::: +``` + +```{opcmd} show firewall ipv6 [forward | input | output] filter +``` + +```{opcmd} show firewall ipv6 ipv6-name \ + +This command will give an overview of a single rule-set. + +:::{code-block} none +vyos@vyos:~$ show firewall ipv6 input filter +Ruleset Information + +--------------------------------- +ipv6 Firewall "input filter" + +Rule Action Protocol Packets Bytes Conditions +------- -------- ---------- --------- ------- ------------------------------------------------------------------------------ +10 jump all 13 1456 iifname "eth1" jump NAME6_INP-ETH1 +20 accept ipv6-icmp 10 1112 meta l4proto ipv6-icmp iifname "eth0" prefix "[ipv6-INP-filter-20-A]" accept +default accept all 14 1584 + +vyos@vyos:~$ +::: +``` + +```{opcmd} show firewall ipv6 [forward | input | output] filter rule \<1-999999\> +``` + +```{opcmd} show firewall ipv6 name \ rule \<1-999999\> +``` + +```{opcmd} show firewall ipv6 ipv6-name \ rule \<1-999999\> + +This command will give an overview of a rule in a single rule-set +``` + +```{opcmd} show firewall group \ + +Show an overview of defined groups, including the type, members, and where +the group is used. + +:::{code-block} none +vyos@vyos:~$ show firewall group LAN +Firewall Groups + +Name Type References Members +------------ ------------------ ----------------------- ---------------- +LAN ipv6_network_group IPV6-VyOS_MANAGEMENT-30 2001:db8::0/64 +IPV6-WAN_IN-30 +LAN network_group VyOS_MANAGEMENT-30 192.168.200.0/24 +WAN_IN-30 +::: +``` + +```{opcmd} show firewall statistics + +Show statistics of all rule-sets since the last boot. +``` + +### Show Firewall log + +```{opcmd} show log firewall +``` + +```{opcmd} show log firewall ipv6 +``` + +```{opcmd} show log firewall ipv6 [forward | input | output | name] +``` + +```{opcmd} show log firewall ipv6 [forward | input | output] filter +``` + +```{opcmd} show log firewall ipv6 name \ +``` + +```{opcmd} show log firewall ipv6 [forward | input | output] filter rule \ +``` + +```{opcmd} show log firewall ipv6 name \ rule \ + +Show firewall logs for all firewalls, all IPv6 firewalls, specific hooks, +specific priorities, specific custom chains, or specific rule-sets. +``` + +### Example Partial Config + +```none +firewall { + ipv6 { + input { + filter { + rule 10 { + action jump + inbound-interface { + name eth1 + } + jump-target INP-ETH1 + } + rule 20 { + action accept + inbound-interface { + name eth0 + } + log + protocol ipv6-icmp + } + } + } + name INP-ETH1 { + default-action drop + default-log + rule 10 { + action accept + protocol tcp_udp + } + } + } +} +``` + +### Update geoip database + +```{opcmd} update geoip + +Command used to update GeoIP database and firewall sets. +``` \ No newline at end of file diff --git a/docs/configuration/firewall/md-zone.md b/docs/configuration/firewall/md-zone.md new file mode 100644 index 00000000..bbb93993 --- /dev/null +++ b/docs/configuration/firewall/md-zone.md @@ -0,0 +1,201 @@ +--- +lastproofread: '2026-03-30' +--- + +(firewall-zone)= + +# Zone-Based Firewall + +## Overview + +:::{note} +All VyOS versions built after 2023-10-22 (VyOS 1.4 and 1.5) support +this feature. +::: + +This section provides information on firewall configuration for the +zone-based firewall. This section covers the following configuration +commands: + +```{cfgcmd} set firewall zone ... +``` + +To learn about the general traffic flow in VyOS firewalls, +see {doc}`Firewall `. + +```none +- set firewall + * zone + - custom_zone_name + + ... +``` + +In zone-based policy, you assign interfaces to zones and apply inspection +policy to traffic moving between zones. The firewall acts on traffic +according to rules. A zone is a group of interfaces that have similar +functions or features. It establishes the security borders of a network. +A zone defines a boundary where the system subjects traffic to policy +restrictions as it crosses to another region of a network. + +Key Points: +- A zone must be configured before you assign an interface to it, and you + can assign an interface to only a single zone. +- All traffic to and from an interface within a zone flows freely. +- Existing policies affect all traffic between zones. +- Traffic cannot flow between a zone member interface and any interface that + is not a zone member. +- You must define 2 separate firewalls to define traffic: one for each + direction. + +:::{note} +In {vytask}`T2199` the syntax of the zone configuration was changed. +The zone configuration moved from ``zone-policy zone `` to +``firewall zone ``. +::: + +## Configuration + +As an alternative to applying policy to an interface directly, you can +create a zone-based firewall to simplify configuration when multiple +interfaces belong to the same security zone. Instead of applying rule-sets +to interfaces, you apply them to source-destination zone pairs. + +You can find a basic introduction to zone-based firewalls in the +[VyOS Knowledge Base](https://support.vyos.io/en/kb/articles/a-primer-to-zone-based-firewall), +and an example at {ref}`examples-zone-policy`. + +The following steps are required to create a zone-based firewall: +1. Define both the source and destination zones +2. Define the rule-set +3. Apply the rule-set to the zones + +### Define a Zone + +To define a zone, set up either one with interfaces or as the local zone. + +```{cfgcmd} set firewall zone \ interface \ + +Assign interfaces as a member of a zone. + +:::{note} +* An interface can only be a member of one zone. +* You can have multiple interfaces in a zone. Traffic between +interfaces in the same zone follows the intra-zone-filtering +policy (allowed by default). +::: +``` + +```{cfgcmd} set firewall zone \ local-zone + +Define the zone as the local zone for traffic that originates from or is +destined to the router itself. + +:::{note} +* A local zone cannot have any member interfaces +* You cannot have multiple local zones +::: +``` + +```{cfgcmd} set firewall zone \ default-action [drop | reject] + +Modify the zone default-action, which applies to traffic destined to this +zone that does not match any of the source zone rulesets applied. +``` + +```{cfgcmd} set firewall zone \ default-log + +Enable logging of packets that match this zone's default-action (disabled +by default). +``` + +```{cfgcmd} set firewall zone \ description + +Add a meaningful description. +``` + +### Defining a Rule-Set + +Zone-based firewall rule-sets define traffic from a *Source Zone* to a +*Destination Zone*. + +You create rule-sets as a custom firewall chain using the commands below +(refer to the firewall IPv4/IPv6 sections for the full syntax): +- For {ref}`IPv4`: + `set firewall ipv4 name ...` +- For {ref}`IPv6`: + `set firewall ipv6 name ...` + +It is helpful to name the rule-sets in the format +`--` to make them easily +identifiable. + +### Applying a Rule-Set to a Zone + +After you define a rule-set, apply it to the source and destination zones. +The configuration syntax anchors to the destination zone, with each of the +source zone rule-sets listed against the destination. + +```{cfgcmd} set firewall zone \ from \ firewall name \ +``` + +```{cfgcmd} set firewall zone \ from \ firewall ipv6-name \ +``` + +You should create two rule-sets for each source-destination zone +pair. + +```none +set firewall zone DMZ from LAN firewall name LAN-DMZ-v4 +set firewall zone LAN from DMZ firewall name DMZ-LAN-v4 +``` + +### Applying a Default Rule-Set to a Zone + +When a destination zone shares a common rule-set for multiple source zones, +or when you require a complex set of default policies, you can apply an +optional default rule-set. The default rule-set applies to all zones that do +not have a rule-set configured as defined in +{ref}`IPv4` + +```{cfgcmd} set firewall zone \ default-firewall name \ +``` + +```{cfgcmd} set firewall zone \ default-firewall ipv6-name \ +``` + +## Operation-mode + +```{opcmd} show firewall zone-policy + +Display a basic summary of the zone configuration. + +:::{code-block} none +vyos@vyos:~$ show firewall zone-policy +Zone Interfaces From Zone Firewall IPv4 Firewall IPv6 +------ ------------ ----------- --------------- --------------- +LAN eth1 WAN WAN-LAN-v4 +eth2 +LOCAL LOCAL LAN LAN-LOCAL-v4 +WAN WAN-LOCAL-v4 WAN-LOCAL-v6 +WAN eth3 LAN LAN-WAN-v4 +eth0 LOCAL LOCAL-WAN-v4 +::: +``` + +```{opcmd} show firewall zone-policy zone \ + +Display a basic summary of a particular zone. + +:::{code-block} none +vyos@vyos:~$ show firewall zone-policy zone WAN +Zone Interfaces From Zone Firewall IPv4 Firewall IPv6 +------ ------------ ----------- --------------- --------------- +WAN eth3 LAN LAN-WAN-v4 +eth0 LOCAL LOCAL-WAN-v4 +vyos@vyos:~$ show firewall zone-policy zone LOCAL +Zone Interfaces From Zone Firewall IPv4 Firewall IPv6 +------ ------------ ----------- --------------- --------------- +LOCAL LOCAL LAN LAN-LOCAL-v4 +WAN WAN-LOCAL-v4 WAN-LOCAL-v6 +::: +``` \ No newline at end of file diff --git a/docs/configuration/highavailability/md-index.md b/docs/configuration/highavailability/md-index.md new file mode 100644 index 00000000..e26f5791 --- /dev/null +++ b/docs/configuration/highavailability/md-index.md @@ -0,0 +1,561 @@ +--- +lastproofread: '2021-06-30' +--- + +(high-availability)= + +# High availability + +VRRP (Virtual Router Redundancy Protocol) provides active/backup redundancy for +routers. Every VRRP router has a physical IP/IPv6 address, and a virtual +address. On startup, routers elect the master, and the router with the highest +priority becomes the master and assigns the virtual address to its interface. +All routers with lower priorities become backup routers. The master then starts +sending keepalive packets to notify other routers that it's available. If the +master fails and stops sending keepalive packets, the router with the next +highest priority becomes the new master and takes over the virtual address. + +VRRP keepalive packets use multicast, and VRRP setups are limited to a single +datalink layer segment. You can setup multiple VRRP groups +(also called virtual routers). Virtual routers are identified by a +VRID (Virtual Router IDentifier). If you setup multiple groups on the same +interface, their VRIDs must be unique if they use the same address family, +but it's possible (even if not recommended for readability reasons) to use +duplicate VRIDs on different interfaces. + +## Basic setup + +VRRP groups are created with the +`set high-availability vrrp group $GROUP_NAME` commands. The required +parameters are interface, vrid, and address. + +minimal config + +```none +set high-availability vrrp group Foo vrid 10 +set high-availability vrrp group Foo interface eth0 +set high-availability vrrp group Foo address 192.0.2.1/24 +``` + +You can verify your VRRP group status with the operational mode +`run show vrrp` command: + +```none +vyos@vyos# run show vrrp +Name Interface VRID State Last Transition +---------- ----------- ------ ------- ----------------- +Foo eth1 10 MASTER 2s +``` + +## IPv6 support + +The `address` parameter can be either an IPv4 or IPv6 address, but you can +not mix IPv4 and IPv6 in the same group, and will need to create groups with +different VRIDs specially for IPv4 and IPv6. +If you want to use IPv4 + IPv6 address you can use option `excluded-address` + +## Address + +The `address` can be configured either on the VRRP interface or on not VRRP +interface. + +```none +set high-availability vrrp group Foo address 192.0.2.1/24 +set high-availability vrrp group Foo address 203.0.113.22/24 interface eth2 +set high-availability vrrp group Foo address 198.51.100.33/24 interface eth3 +``` + +## Disabling a VRRP group + +You can disable a VRRP group with `disable` option: + +```none +set high-availability vrrp group Foo disable +``` + +A disabled group will be removed from the VRRP process and your router will not +participate in VRRP for that VRID. It will disappear from operational mode +commands output, rather than enter the backup state. + +## Exclude address + +Exclude IP addresses from `VRRP packets`. This option `excluded-address` is +used when you want to set IPv4 + IPv6 addresses on the same virtual interface +or when used more than 20 IP addresses. + +```none +set high-availability vrrp group Foo excluded-address '203.0.113.254/24' +set high-availability vrrp group Foo excluded-address '2001:db8:aa::1/64' +set high-availability vrrp group Foo excluded-address '2001:db8:22::1/64' +``` + +## Setting VRRP group priority + +VRRP priority can be set with `priority` option: + +```none +set high-availability vrrp group Foo priority 200 +``` + +The priority must be an integer number from 1 to 255. Higher priority value +increases router's precedence in the master elections. + +## Sync groups + +A sync group allows VRRP groups to transition together. + +```none +edit high-availability vrrp +set sync-group MAIN member VLAN9 +set sync-group MAIN member VLAN20 +``` + +In the following example, when VLAN9 transitions, VLAN20 will also transition: + +```none +vrrp { + group VLAN9 { + interface eth0.9 + address 10.9.1.1/24 + priority 200 + vrid 9 + } + group VLAN20 { + interface eth0.20 + priority 200 + address 10.20.20.1/24 + vrid 20 + } + sync-group MAIN { + member VLAN20 + member VLAN9 + } +} +``` + +:::{warning} +All items in a sync group should be similarly configured. +If one VRRP group is set to a different preemption delay or priority, +it would result in an endless transition loop. +::: + +## Preemption + +VRRP can use two modes: preemptive and non-preemptive. In the preemptive mode, +if a router with a higher priority fails and then comes back, routers with lower +priority will give up their master status. In non-preemptive mode, the newly +elected master will keep the master status and the virtual address indefinitely. + +By default VRRP uses preemption. You can disable it with the "no-preempt" +option: + +```none +set high-availability vrrp group Foo no-preempt +``` + +You can also configure the time interval for preemption with the "preempt-delay" +option. For example, to set the higher priority router to take over in 180 +seconds, use: + +```none +set high-availability vrrp group Foo preempt-delay 180 +``` + +## Track + +Track option to track non VRRP interface states. VRRP changes status to +`FAULT` if one of the track interfaces in state `down`. + +```none +set high-availability vrrp group Foo track interface eth0 +set high-availability vrrp group Foo track interface eth1 +``` + +Ignore VRRP main interface faults + +```none +set high-availability vrrp group Foo track exclude-vrrp-interface +``` + +## Unicast VRRP + +By default VRRP uses multicast packets. If your network does not support +multicast for whatever reason, you can make VRRP use unicast communication +instead. + +```none +set high-availability vrrp group Foo peer-address 192.0.2.10 +set high-availability vrrp group Foo hello-source-address 192.0.2.15 +``` + +## rfc3768-compatibility + +RFC 3768 defines a virtual MAC address to each VRRP virtual router. +This virtual router MAC address will be used as the source in all periodic VRRP +messages sent by the active node. When the rfc3768-compatibility option is set, +a new VRRP interface is created, to which the MAC address and the virtual IP +address is automatically assigned. + +```none +set high-availability vrrp group Foo rfc3768-compatibility +``` + +Verification + +```none +$show interfaces ethernet eth0v10 +eth0v10@eth0: mtu 1500 qdisc noqueue +state UP group default qlen 1000 +link/ether 00:00:5e:00:01:0a brd ff:ff:ff:ff:ff:ff +inet 172.25.0.247/16 scope global eth0v10 +valid_lft forever preferred_lft forever +``` + +:::{warning} +RFC 3768 creates a virtual interface. If you want to apply +the destination NAT rule to the traffic sent to the virtual MAC, set +the created virtual interface as `inbound-interface`. +::: + +## Global options + +On most scenarios, there's no need to change specific parameters, and using +default configuration is enough. But there are cases were extra configuration +is needed. + +```{eval-rst} +.. cfgcmd:: set high-availability vrrp global-parameters startup_delay <1-600> + + This option specifies a delay in seconds before vrrp instances start up + after keepalived starts. +``` + +## Gratuitous ARP + +These configuration is not mandatory and in most cases there's no +need to configure it. But if necessary, Gratuitous ARP can be configured in +`global-parameters` and/or in `group` section. + +```{eval-rst} +.. cfgcmd:: set high-availability vrrp global-parameters garp interval + <0.000-1000> +``` + +```{eval-rst} +.. cfgcmd:: set high-availability vrrp group garp interval <0.000-1000> + + Set delay between gratuitous ARP messages sent on an interface. + + 0 if not defined. +``` + +% stop_vyoslinter + +```{eval-rst} +.. cfgcmd:: set high-availability vrrp global-parameters garp master-delay <1-255> +``` + +% start_vyoslinter + +```{eval-rst} +.. cfgcmd:: set high-availability vrrp group garp master-delay <1-255> + + Set delay for second set of gratuitous ARPs after transition to MASTER. + + 5 if not defined. +``` + +```{eval-rst} +.. cfgcmd:: set high-availability vrrp global-parameters garp master-refresh + <1-600> +``` + +```{eval-rst} +.. cfgcmd:: set high-availability vrrp group garp master-refresh + <1-600> + + Set minimum time interval for refreshing gratuitous ARPs while MASTER. + + 0 if not defined, which means no refreshing. +``` + +```{eval-rst} +.. cfgcmd:: set high-availability vrrp global-parameters garp + master-refresh-repeat <1-600> +``` + +```{eval-rst} +.. cfgcmd:: set high-availability vrrp group garp + master-refresh-repeat <1-600> + + Set number of gratuitous ARP messages to send at a time while MASTER. + + 1 if not defined. +``` + +```{eval-rst} +.. cfgcmd:: set high-availability vrrp global-parameters garp master-repeat + <1-600> +``` + +```{eval-rst} +.. cfgcmd:: set high-availability vrrp group garp master-repeat + <1-600> + + Set number of gratuitous ARP messages to send at a time after transition to + MASTER. + + 5 if not defined. +``` + +## Version + +```{eval-rst} +.. cfgcmd:: set high-availability vrrp global-parameters version 2|3 + + Set the default VRRP version to use. This defaults to 2, but IPv6 instances + will always use version 3. +``` + +## Scripting + +VRRP functionality can be extended with scripts. VyOS supports two kinds of +scripts: health check scripts and transition scripts. Health check scripts +execute custom checks in addition to the master router reachability. Transition +scripts are executed when VRRP state changes from master to backup or fault and +vice versa and can be used to enable or disable certain services, for example. + +:::{note} +Simply placing script files in `/config/scripts/` does not mean the +system can execute them. To make custom scripts executable, grant them +**execute permissions**. Use the following command: + +```none +chmod +x /config/scripts/script-name.sh +``` +::: + +:::{warning} +It is not recommended to change VRRP configuration +inside health-check and transition scripts. +::: + +### Health check scripts + +There is the ability to run an arbitrary script at regular intervals +according to health-check parameters. If a script returns 0, it +indicates success. If a script returns anything else, it will indicate +that the VRRP instance should enter the FAULT state. + +This setup will make the VRRP process execute the +`/config/scripts/vrrp-check.sh script` every 60 seconds, and transition the +group to the fault state if it fails (i.e. exits with non-zero status) three +times: + +% stop_vyoslinter + +```none +set high-availability vrrp group Foo health-check script /config/scripts/vrrp-check.sh +set high-availability vrrp group Foo health-check interval 60 +set high-availability vrrp group Foo health-check failure-count 3 +``` + +% start_vyoslinter + +An optional `timeout` can be set to define the maximum number of seconds the +script is allowed to run. This is useful for scripts that may hang or take +longer than expected — setting the timeout higher than the interval allows +longer-running scripts to complete before being considered failed. + +% stop_vyoslinter + +```none +set high-availability vrrp group Foo health-check script /config/scripts/vrrp-check.sh +set high-availability vrrp group Foo health-check interval 20 +set high-availability vrrp group Foo health-check failure-count 3 +set high-availability vrrp group Foo health-check timeout 40 +``` + +% start_vyoslinter + +When the vrrp group is a member of the sync group will use only +the sync group health check script. +This example shows how to configure it for the sync group: + +% stop_vyoslinter + +```none +set high-availability vrrp sync-group Bar health-check script /config/scripts/vrrp-check.sh +set high-availability vrrp sync-group Bar health-check interval 60 +set high-availability vrrp sync-group Bar health-check failure-count 3 +``` + +% start_vyoslinter + +### Transition scripts + +Transition scripts can help you implement various fixups, such as starting and +stopping services, or even modifying the VyOS config on VRRP transition. +This setup will make the VRRP process execute the +`/config/scripts/vrrp-fail.sh` with argument `Foo` when VRRP fails, +and the `/config/scripts/vrrp-master.sh` when the router becomes the master: + +% stop_vyoslinter + +```none +set high-availability vrrp group Foo transition-script backup "/config/scripts/vrrp-fail.sh Foo" +set high-availability vrrp group Foo transition-script fault "/config/scripts/vrrp-fail.sh Foo" +set high-availability vrrp group Foo transition-script master "/config/scripts/vrrp-master.sh Foo" +``` + +% start_vyoslinter + +To know more about scripting, check the {ref}`command-scripting` section. + +## Virtual-server + +```{eval-rst} +.. include:: /_include/need_improvement.txt +``` + +Virtual Server allows to Load-balance traffic destination virtual-address:port +between several real servers. + +### Algorithm + +Load-balancing schedule algorithm: + +- round-robin +- weighted-round-robin +- least-connection +- weighted-least-connection +- source-hashing +- destination-hashing +- locality-based-least-connection + +```none +set high-availability virtual-server 203.0.113.1 algorithm 'least-connection' +``` + +### Forward method + +- NAT +- direct +- tunnel + +```none +set high-availability virtual-server 203.0.113.1 forward-method 'nat' +``` + +### Health-check + +Custom health-check script allows checking real-server availability + +% stop_vyoslinter + +```none +set high-availability virtual-server 203.0.113.1 real-server 192.0.2.11 health-check script +``` + +% start_vyoslinter + +### Fwmark + +Firewall mark. It possible to loadbalancing traffic based on `fwmark` value + +```none +set high-availability virtual-server 203.0.113.1 fwmark '111' +``` + +### Real server + +Real server IP address and port + +% stop_vyoslinter + +```none +set high-availability virtual-server 203.0.113.1 real-server 192.0.2.11 port '80' +``` + +% start_vyoslinter + +### Example + +Virtual-server can be configured with VRRP virtual address or without VRRP. + +In the next example all traffic destined to `203.0.113.1` and port `8280` +protocol TCP is balanced between 2 real servers `192.0.2.11` and +`192.0.2.12` to port `80` + +Real server is auto-excluded if port check with this server fail. + +% stop_vyoslinter + +```none +set interfaces ethernet eth0 address '203.0.113.11/24' +set interfaces ethernet eth1 address '192.0.2.1/24' +set high-availability vrrp group FOO interface 'eth0' +set high-availability vrrp group FOO no-preempt +set high-availability vrrp group FOO priority '150' +set high-availability vrrp group FOO address '203.0.113.1/24' +set high-availability vrrp group FOO vrid '10' + +set high-availability virtual-server 203.0.113.1 algorithm 'source-hashing' +set high-availability virtual-server 203.0.113.1 delay-loop '10' +set high-availability virtual-server 203.0.113.1 forward-method 'nat' +set high-availability virtual-server 203.0.113.1 persistence-timeout '180' +set high-availability virtual-server 203.0.113.1 port '8280' +set high-availability virtual-server 203.0.113.1 protocol 'tcp' +set high-availability virtual-server 203.0.113.1 real-server 192.0.2.11 port '80' +set high-availability virtual-server 203.0.113.1 real-server 192.0.2.12 port '80' +``` + +% start_vyoslinter + +A firewall mark `fwmark` allows using multiple ports for high-availability +virtual-server. +It uses fwmark value. + +In this example all traffic destined to ports "80, 2222, 8888" protocol TCP +marks to fwmark "111" and balanced between 2 real servers. +Port "0" is required if multiple ports are used. + +% stop_vyoslinter + +```none +set interfaces ethernet eth0 address 'dhcp' +set interfaces ethernet eth0 description 'WAN' +set interfaces ethernet eth1 address '192.0.2.1/24' +set interfaces ethernet eth1 description 'LAN' + +set policy route PR interface 'eth0' +set policy route PR rule 10 destination port '80,2222,8888' +set policy route PR rule 10 protocol 'tcp' +set policy route PR rule 10 set mark '111' + +set high-availability virtual-server vyos fwmark '111' +set high-availability virtual-server vyos protocol 'tcp' +set high-availability virtual-server vyos real-server 192.0.2.11 health-check script '/config/scripts/check-real-server-first.sh' +set high-availability virtual-server vyos real-server 192.0.2.11 port '0' +set high-availability virtual-server vyos real-server 192.0.2.12 health-check script '/config/scripts/check-real-server-second.sh' +set high-availability virtual-server vyos real-server 192.0.2.12 port '0' + +set nat source rule 100 outbound-interface name 'eth0' +set nat source rule 100 source address '192.0.2.0/24' +set nat source rule 100 translation address 'masquerade' +``` + +% start_vyoslinter + +Op-mode check virtual-server status + +```none +vyos@r14:~$ run show virtual-server +IP Virtual Server version 1.2.1 (size=4096) +Prot LocalAddress:Port Scheduler Flags + -> RemoteAddress:Port Forward Weight ActiveConn InActConn +FWM 111 lc persistent 300 + -> 192.0.2.11:0 Masq 1 0 0 + -> 192.0.2.12:0 Masq 1 1 0 +``` + diff --git a/docs/configuration/interfaces/md-bonding.md b/docs/configuration/interfaces/md-bonding.md new file mode 100644 index 00000000..7a07a27c --- /dev/null +++ b/docs/configuration/interfaces/md-bonding.md @@ -0,0 +1,764 @@ +--- +lastproofread: '2025-12-09' +--- + +(bond-interface)= + +# Bond / link aggregation + +A **bonding interface** aggregates multiple network interfaces into a single +logical interface (referred to as a bond, {abbr}`LAG (Link Aggregation Group)`, +EtherChannel, or port-channel). + +The behavior of a bonding interface depends on the selected mode. Modes provide +either fault tolerance or a combination of load balancing and fault tolerance. +Additionally, the bonding interface can be configured for link integrity +monitoring. + +## Configuration + +### Common interface configuration + +```{cmdincludemd} /_include/interface-common-with-dhcp.txt +:var0: bonding +:var1: bond0 +``` + +### Member interfaces + +```{cfgcmd} set interfaces bonding \ member interface \ + +**Add an interface to the bonding group.** + +**Example:** + +To configure eth0 and eth1 as members of the bonding interface bond0, execute +the following commands: +``` + +```none +set interfaces bonding bond0 member interface eth0 +set interfaces bonding bond0 member interface eth1 +``` + +### Bond modes + +````{cfgcmd} set interfaces bonding \ mode \<802.3ad | active-backup | broadcast | round-robin | transmit-load-balance | adaptive-load-balance | xor-hash\> + +```{eval-rst} +**Configure the bonding mode on the interface. The default mode is** +``802.3ad``. + +The available modes are: + +* ``802.3ad`` + +.. list-table:: + :widths: 20 80 + + * - **Description:** + - IEEE 802.3ad Dynamic Link Aggregation. Groups only member + interfaces with the same speed (e.g., 1 Gbps) and duplex + settings. Member interfaces with different speed and duplex + settings are not included in the active bond. + + Provides load balancing and fault tolerance. Uses the + :abbr:`LACP (Link Aggregation Control Protocol)` to + negotiate the bond with the switch. + * - **Traffic distribution:** + - Traffic is distributed according to the **transmit hash + policy** (default: XOR). + + The bonding driver applies an XOR operation to specific + packet header fields, generating a hash value that maps to + a particular member interface. This ensures the same network + flow is consistently transmitted over the same member + interface. + + The transmit hash policy is configured via the ``hash-policy`` option. + * - **Failover:** + - If a member interface fails, the hash is recalculated to distribute + traffic among the remaining active member interfaces. + +.. note:: Not all transmit hash policies comply with 802.3ad, particularly + section 43.2.4. Using a non-compliant policy may result in out-of-order + packet delivery. + +* ``active-backup`` + +.. list-table:: + :widths: 20 80 + + * - **Description:** + - Provides fault tolerance. Only one member interface is active + at a time. Other member interfaces remain in a standby mode. + * - **Traffic distribution:** + - All traffic (incoming and outgoing) is routed via one active + member interface. + * - **Failover:** + - If the designated member interface fails, all traffic is + routed to another member interface. The bonding driver sends + a Gratuitous ARP to update the peer's MAC address table, + linking the bond's MAC address to another physical port. + +* ``broadcast`` + +.. list-table:: + :widths: 20 80 + + * - **Description:** + - Provides maximum fault tolerance by duplicating traffic. + * - **Traffic distribution:** + - Every packet is duplicated and transmitted on **all** member + interfaces. + * - **Failover:** + - Traffic flow is not interrupted as long as at least one + member interface remains active. + +* ``round-robin`` + +.. list-table:: + :widths: 20 80 + + * - **Description:** + - Provides load balancing and fault tolerance. + * - **Traffic distribution:** + - Packets are transmitted in sequential order across the member + interfaces (e.g., packet 1 > interface A, packet 2 > + interface B, etc.). + * - **Failover:** + - If a member interface fails, the sequence skips the failed + interface and continues with the remaining active members. + +* ``transmit-load-balance`` + +.. list-table:: + :widths: 20 80 + + * - **Description:** + - Provides adaptive transmit load balancing and fault tolerance. + * - **Traffic distribution:** + - **Outgoing:** Distributed across all active member interfaces + based on the current load. + + **Incoming:** Received by a designated member interface + (active receiver). + * - **Failover:** + - If the active receiver fails, another member interface takes + over as the new active receiver. + +* ``adaptive-load-balance`` + +.. list-table:: + :widths: 20 80 + + * - **Description:** + - Provides adaptive transmit load balancing identical to + ``transmit-load-balance``, receive load balancing for IPv4 + traffic, and fault tolerance for both incoming and outgoing + traffic. + * - **Traffic distribution:** + - **Outgoing:** Identical to ``transmit-load-balance``. + + **Incoming:** Distributed based on ARP manipulation. For + both local and remote connections, the bonding driver + intercepts ARP traffic and changes the source MAC address + to the MAC address of the least loaded member interface. + + All traffic from that peer is then routed to the chosen + member interface. + * - **Failover:** + - If a member interface's state changes (fails, recovers, is + added, or excluded), the traffic is redistributed among all + active member interfaces. + +* ``xor-hash``: Provides load balancing and fault tolerance + based on a hash formula. Distributes traffic and handles + failover identically to ``802.3ad``, but operates without + the :abbr:`LACP (Link Aggregation Control Protocol)`. +``` + +```` + +```{cfgcmd} set interfaces bonding \ min-links \<0-16\> + +**Configure how many member interfaces must be active (in the +link-up state) to mark the bonding interface UP (carrier +asserted).** + +This command applies only when the bonding interface is configured +in 802.3ad mode and functions like the Cisco EtherChannel min-links +feature. It ensures that a bonding interface is marked UP (carrier +asserted) only when a specified number of member interfaces are +active (in the link-up state). This helps guarantee a minimum level +of bandwidth for higher-level services (such as clustering) relying +on the bonding interface. + +The default value is 0. This marks the bonding interface UP +(carrier asserted) whenever an active LACP aggregator exists, +regardless of the number of member interfaces in that aggregator. + +:::{note} +In 802.3ad mode, a bond cannot be active without at least one active +member interface. Therefore, setting min-links to 0 or 1 has the same result: +the bonding interface is marked UP (carrier asserted). +::: +``` + +```{cfgcmd} set interfaces bonding \ lacp-rate \ + +**Configure the rate at which the bonding interface requests its link +partner to send** {abbr}`LACPDUs (Link Aggregation Control Protocol Data +Units)` **in 802.3ad mode.** + +This command applies only when the bonding interface is configured in +802.3ad mode. + +The following options are available: + +* **slow (default):** Requests the link partner to transmit LACPDUs every 30 seconds. + +* **fast:** Requests the link partner to transmit LACPDUs every 1 second. +``` +```{cfgcmd} set interfaces bonding \ system-mac \ + +**Configure a specific MAC address for the bonding interface.** + +This sets the 802.3ad system MAC address, which is used for {abbr}`LACPDU (Link +Aggregation Control Protocol Data Unit)` exchanges with the link partner. +You can assign a fixed MAC address or generate a random one for these +{abbr}`LACPDU (Link Aggregation Control Protocol Data Unit)` exchanges. +``` +```{cfgcmd} set interfaces bonding \ hash-policy \ + +**Configure which transmit hash policy to use for distributing traffic across +member interfaces.** + +The following policies are available: + +* ``layer2`` + +**Description:** Routes all traffic destined for a specific network peer through +the same member interface. The policy is 802.3ad-compliant. + +**Hash inputs:** Source MAC address, destination MAC address, and Ethernet packet +type ID. + +**Formula:** + +:::{code-block} none +hash = source MAC address XOR destination MAC address XOR packet type ID +member interface number = hash modulo member interface count +::: + +* ``layer2+3`` + +**Description:** Similar to ``layer2``, routes all traffic destined for a specific +network peer through the same member interface and is IEEE 802.3ad-compliant. Uses +both Layer 2 and Layer 3 information to provide a more balanced traffic distribution. + +**Hash inputs:** +* Source MAC address, destination MAC address, and Ethernet packet type ID. +* Source IP address, destination IP address. IPv6 addresses are first hashed + using ``IPv6_addr_hash``. + +**Formula:** + +:::{code-block} none +hash = source MAC address XOR destination MAC address XOR packet type ID +hash = hash XOR source IP address XOR destination IP address +hash = hash XOR (hash RSHIFT 16) +hash = hash XOR (hash RSHIFT 8) +member interface number = hash modulo member interface count +::: + +For non-IP traffic, the formula is the same as for ``layer2``. + +* ``layer3+4`` + +**Description:** Routes different connections (flows) destined for a specific +network peer through multiple member interfaces, but ensures each individual +flow is routed through only one member interface. + +:::{note} +This policy is not fully 802.3ad-compliant. When a single TCP or UDP flow +contains both fragmented and unfragmented packets, the algorithm may distribute +them across different member interfaces. This may result in out-of-order packet +delivery, violating the 802.3ad standard. +::: + +**Hash inputs:** +* Source port, destination port (if available). +* Source IP address, destination IP address. IPv6 addresses are first hashed + using ``IPv6_addr_hash``. + +**Formula:** + +:::{code-block} none +hash = source port, destination port (as in the header) +hash = hash XOR source IP address XOR destination IP address +hash = hash XOR (hash RSHIFT 16) +hash = hash XOR (hash RSHIFT 8) +member interface number = hash modulo member interface count +::: + +For fragmented TCP or UDP packets and all other IPv4 and IPv6 traffic, the +source and destination port information is omitted. + +For non-IP traffic, the formula is the same as for ``layer2``. +``` + + +```{cfgcmd} set interfaces bonding \ primary \ + +**Configure the primary member interface in the bond.** + +The primary member interface remains active as long as it is operational; +alternative member interfaces are used only if it fails. + +Use this configuration when a specific member interface is preferred, +such as one with higher throughput. + +This command applies only to ``active-backup``, ``transmit-load-balance``, and +``adaptive-load-balance`` modes. +``` + + +```{cfgcmd} set interfaces bonding \ arp-monitor interval \ + +**Configure the ARP monitoring interval, in seconds, for the bonding interface.** + +ARP monitoring periodically assesses the health of each member interface by +checking whether it has recently sent or received traffic (this criterion +varies depending on the bonding mode and the member interface’s state). ARP +probes are sent to the IP addresses specified with the arp-monitor target option. + +When ARP monitoring is used with EtherChannel-compatible modes (such as +``round-robin`` or ``xor-hash``), the switch should be configured to distribute +traffic across all member interfaces. If the switch distributes traffic using +an XOR-based policy, all ARP replies will be received on one member interface, +causing other member interfaces to be incorrectly marked as failed. + +Setting this value to 0 disables ARP monitoring. + +The default value is 0. +``` + + +```{cfgcmd} set interfaces bonding \ arp-monitor target \ + +**Configure the IP addresses for ARP monitoring requests.** + +The bonding driver sends ARP requests to these IP addresses to check the +state of member interfaces. + +To enable ARP monitoring, configure at least one IP address (up to 16 per +bonding interface). + +By default, no IP addresses are configured. +``` + +### {abbr}`VLAN (Virtual Local Area Network)` + +```{cmdincludemd} /_include/interface-vlan-8021q.txt +:var0: bonding +:var1: bond0 +``` + +### SPAN port mirroring + +```{cmdincludemd} ../../_include/interface-mirror.txt +:var0: bonding +:var1: bond1 +:var2: eth3 +``` + +#### EVPN multihoming + + +EVPN multihoming (EVPN-MH) is a standards-based solution (RFC 7432, RFC 8365) +that enables Customer Edge (CE) devices, such as servers, to connect to two +or more Provider Edge (PE) devices for redundancy and load balancing. + + +EVPN-MH is often used as a modern, standards-based alternative to +{abbr}`MLAG (Multi-Chassis Link Aggregation)` and {abbr}`VTEPs (Virtual +Tunnel Endpoints)`. + + +**Ethernet Segment (ES) and Ethernet Segment Identifier (ESI)** + + +Physical links that connect a CE device to PE devices are bundled using link +aggregation. This logical bundle is called an Ethernet Segment (ES) and is +uniquely identified by an Ethernet Segment Identifier (ESI) within the +EVPN domain. + + +To enable EVPN-MH, configure the same ESI on the bonding interfaces of all +PE devices connected to a single CE device. + + +An ESI is configured by specifying either a system MAC address and a local +discriminator, or an Ethernet Segment Identifier Name (ESINAME). + + +The following two commands generate a 10-byte Type-3 ESI by combining the +system MAC and local discriminator: + +```{cfgcmd} set interfaces bonding \ evpn es-id \<1-16777215|10-byte ID\> + +``` +```{cfgcmd} set interfaces bonding \ evpn es-sys-mac \ + +Alternatively, assign an ESINAME directly as a 10-byte Type-0 ESI using the +following format: 00:AA:BB:CC:DD:EE:FF:GG:HH:II. + +**BGP-EVPN route usage** + +EVPN-MH uses BGP-EVPN route types 1 and 2 for ES discovery and MAC-IP +synchronization: + +* **Type 1 (EAD-per-ES and EAD-per-EVI)** routes advertise the locally +attached ESs and discover remote ESs in the network. +* **Type 2 (MAC-IP advertisement)** routes are advertised with a +destination ESI, enabling MAC-IP synchronization between ES peers. +``` + +```{cfgcmd} set interfaces bonding \ evpn es-df-pref \<1-65535\> + +**Configure the** {abbr}`DF (Designated Forwarder)` **preference (1-65535) for +the interface. A higher value indicates a higher preference to become the** +{abbr}`DF (Designated Forwarder)`. **The** {abbr}`DF (Designated Forwarder)` +**preference is configured per-ES.** + +The DF election process determines which interface in a specific ES forwards +{abbr}`BUM (Broadcast, Unknown Unicast, and Multicast)` traffic from the EVPN +overlay to the connected CE device. EVPN Type-4 (Ethernet Segment) routes are +used to elect the DF, implementing the preference-based election method defined +in RFC 9785. + +Interfaces not elected as the DF drop any BUM traffic from the EVPN overlay +using non-DF filters. Similarly, traffic received from ES peers via the EVPN +overlay is blocked from forwarding to the CE device to maintain split-horizon +filtering with local bias. +``` + +```{cmdincludemd} /_include/interface-evpn-uplink.txt +:var0: bonding +:var1: bond0 +``` + +## Example + + +The following configuration example applies to all listed third-party vendors. +It creates a bonding interface with two member interfaces, defines VLANs 10 +and 100 on the bonding interface, and assigns an IPv4 address to each VLAN +subinterface. + +```none +# Create the bonding interface bond0 with 802.3ad LACP +set interfaces bonding bond0 hash-policy 'layer2' +set interfaces bonding bond0 mode '802.3ad' + +# Add the required VLANs and IPv4 addresses on them +set interfaces bonding bond0 vif 10 address 192.168.0.1/24 +set interfaces bonding bond0 vif 100 address 10.10.10.1/24 + +# Add the member interfaces to the bonding interface +set interfaces bonding bond0 member interface eth1 +set interfaces bonding bond0 member interface eth2 +``` +:::{note} +If you are running this configuration in a virtual environment like +EVE-NG, ensure the e1000 driver is chosen for your VyOS NIC. The default +drivers, such as ``virtio-net-pci`` or ``vmxnet3``, are incompatible with +this configuration. Specifically, ICMP messages will not be processed +correctly. + +To check your NIC driver, use the following command: +``show interfaces ethernet eth0 physical | grep -i driver`` +::: + + +### Cisco Catalyst configuration + + +Configure a Cisco Catalyst switch to integrate with a two-member VyOS bonding +interface. + + +Assign member interfaces to PortChannel: + +```none +interface GigabitEthernet1/0/23 + description VyOS eth1 + channel-group 1 mode active +! +interface GigabitEthernet1/0/24 + description VyOS eth2 + channel-group 1 mode active +! +``` + +A new interface, `Port-channel1`, becomes available; all configuration, +such as allowed VLAN interfaces and STP, is applied here. + +```none +interface Port-channel1 + description LACP Channel for VyOS + switchport trunk encapsulation dot1q + switchport trunk allowed vlan 10,100 + switchport mode trunk + spanning-tree portfast trunk +! +``` + +### Juniper EX Switch configuration + + +Configure a Juniper EX Series switch to integrate with a two-member VyOS bonding +interface. + +```none +# Create aggregated ethernet device with 802.3ad LACP and port speeds of 10gbit/s +set interfaces ae0 aggregated-ether-options link-speed 10g +set interfaces ae0 aggregated-ether-options lacp active + +# Create layer 2 on the aggregated ethernet device with trunking for our VLANs +set interfaces ae0 unit 0 family ethernet-switching port-mode trunk + +# Add the required vlans to the device +set interfaces ae0 unit 0 family ethernet-switching vlan members 10 +set interfaces ae0 unit 0 family ethernet-switching vlan members 100 + +# Add the two interfaces to the aggregated ethernet device, in this setup both +# ports are on the same switch (switch 0, module 1, port 0 and 1) +set interfaces xe-0/1/0 ether-options 802.3ad ae0 +set interfaces xe-0/1/1 ether-options 802.3ad ae0 + +# But this can also be done with multiple switches in a stack, a virtual +# chassis on Juniper (switch 0 and switch 1, module 1, port 0 on both switches) +set interfaces xe-0/1/0 ether-options 802.3ad ae0 +set interfaces xe-1/1/0 ether-options 802.3ad ae0 +``` + +### Aruba/HP configuration + + +Configure an Aruba/HP 2510G switch to integrate with a two-member VyOS bonding +interface. + +```none +# Create trunk with 2 member interfaces (interface 1 and 2) and LACP +trunk 1-2 Trk1 LACP + +# Add the required VLANs to the trunk +vlan 10 tagged Trk1 +vlan 100 tagged Trk1 +``` + +### Arista EOS configuration + + +When deploying VyOS in environments with Arista switches, use the following +blueprint as an initial setup to configure an operational LACP port-channel +between the two devices. + + +Let's assume the following topology: + + +```{eval-rst} +.. figure:: /_static/images/vyos_arista_bond_lacp.webp + :alt: VyOS Arista EOS setup +``` + + +**R1** + +```none +interfaces { + bonding bond10 { + hash-policy layer3+4 + member { + interface eth1 + interface eth2 + } + mode 802.3ad + vif 100 { + address 192.0.2.1/30 + address 2001:db8::1/64 + } + } +``` +**R2** + + + +```none +interfaces { + bonding bond10 { + hash-policy layer3+4 + member { + interface eth1 + interface eth2 + } + mode 802.3ad + vif 100 { + address 192.0.2.2/30 + address 2001:db8::2/64 + } + } +``` +**SW1** + +```none +! +vlan 100 + name FOO +! +interface Port-Channel10 + switchport trunk allowed vlan 100 + switchport mode trunk + spanning-tree portfast +! +interface Port-Channel20 + switchport mode trunk + no spanning-tree portfast auto + spanning-tree portfast network +! +interface Ethernet1 + channel-group 10 mode active +! +interface Ethernet2 + channel-group 10 mode active +! +interface Ethernet3 + channel-group 20 mode active +! +interface Ethernet4 + channel-group 20 mode active +! +``` +**SW2** + + + +```none +! +vlan 100 + name FOO +! +interface Port-Channel10 + switchport trunk allowed vlan 100 + switchport mode trunk + spanning-tree portfast +! +interface Port-Channel20 + switchport mode trunk + no spanning-tree portfast auto + spanning-tree portfast network +! +interface Ethernet1 + channel-group 10 mode active +! +interface Ethernet2 + channel-group 10 mode active +! +interface Ethernet3 + channel-group 20 mode active +! +interface Ethernet4 + channel-group 20 mode active +! +``` +:::{note} +When testing this environment in EVE-NG, ensure the e1000 driver +is chosen for your VyOS network interfaces. If the default virtio driver +is used, VyOS will not transmit LACP PDUs, preventing the port-channel +from ever becoming active. +::: + + +(operation)= + +## Operation + +```{opcmd} show interfaces bonding + +Show brief interface information. + + +:::{code-block} none +vyos@vyos:~$ show interfaces bonding +Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down +Interface IP Address S/L Description +--------- ---------- --- ----------- +bond0 - u/u my-sw1 int 23 and 24 +bond0.10 192.168.0.1/24 u/u office-net +bond0.100 10.10.10.1/24 u/u management-net +::: +``` +```{opcmd} show interfaces bonding \ + +Show detailed interface information. + +:::{code-block} none +vyos@vyos:~$ show interfaces bonding bond5 +bond5: mtu 1500 qdisc noqueue state DOWN group default qlen 1000 + link/ether 00:50:56:bf:ef:aa brd ff:ff:ff:ff:ff:ff + inet6 fe80::e862:26ff:fe72:2dac/64 scope link tentative + valid_lft forever preferred_lft forever + + RX: bytes packets errors dropped overrun mcast + 0 0 0 0 0 0 + TX: bytes packets errors dropped carrier collisions + 0 0 0 0 0 0 +::: +``` +```{opcmd} show interfaces bonding \ detail + +Show detailed information about the underlying physical links on the given +bonding interface. + +:::{code-block} none +vyos@vyos:~$ show interfaces bonding bond5 detail +Ethernet Channel Bonding Driver: v3.7.1 (April 27, 2011) +Bonding Mode: IEEE 802.3ad Dynamic link aggregation +Transmit Hash Policy: layer2 (0) +MII Status: down +MII Polling Interval (ms): 100 +Up Delay (ms): 0 +Down Delay (ms): 0 +802.3ad info +LACP rate: slow +Min links: 0 +Aggregator selection policy (ad_select): stable +Slave Interface: eth1 +MII Status: down +Speed: Unknown +Duplex: Unknown +Link Failure Count: 0 +Permanent HW addr: 00:50:56:bf:ef:aa +Slave queue ID: 0 +Aggregator ID: 1 +Actor Churn State: churned +Partner Churn State: churned +Actor Churned Count: 1 +Partner Churned Count: 1 +Slave Interface: eth2 +MII Status: down +Speed: Unknown +Duplex: Unknown +Link Failure Count: 0 +Permanent HW addr: 00:50:56:bf:19:26 +Slave queue ID: 0 +Aggregator ID: 2 +Actor Churn State: churned +Partner Churn State: churned +Actor Churned Count: 1 +Partner Churned Count: 1 +::: +``` \ No newline at end of file diff --git a/docs/configuration/interfaces/md-bridge.md b/docs/configuration/interfaces/md-bridge.md new file mode 100644 index 00000000..77775767 --- /dev/null +++ b/docs/configuration/interfaces/md-bridge.md @@ -0,0 +1,431 @@ +--- +lastproofread: '2025-12-22' +--- + +(bridge-interface)= + +# Bridge + +VyOS bridges connect Ethernet segments by grouping multiple interfaces into a +single bridge interface, which acts as a virtual software switch. Unlike +routers, which forward traffic based on Layer 3 IP addresses, bridges operate +at Layer 2 and forward traffic based on MAC addresses. Operating at Layer 2, +bridges are protocol-agnostic and transparently forward all Ethernet- +encapsulated traffic, whether it is IPv4, IPv6, or specialized industrial +protocols. + +This implementation utilizes the Linux bridge subsystem to support a subset of +the ANSI/IEEE 802.1d standard for transparent bridging and MAC address learning. + +:::{note} +{abbr}`STP (Spanning Tree Protocol)` is disabled by default in VyOS +and must be explicitly enabled if required. See {ref}`stp` for details. +::: + +## Configuration + +### Common interface configuration + +```{cmdincludemd} /_include/interface-common-with-dhcp.txt +:var0: bridge +:var1: br0 +``` + + +### Member interfaces + +```{cfgcmd} set interfaces bridge \ member interface \ + +**Configure an interface as a bridge member.** + +Valid interface types are: {ref}`ethernet-interface`, {ref}`bond-interface`, +{ref}`l2tpv3-interface`, {ref}`openvpn`, {ref}`vxlan-interface`, +{ref}`wireless-interface`, {ref}`tunnel-interface`, and +{ref}`geneve-interface`. + +Use tab completion to list interfaces that can be bridged. +``` + +```{cfgcmd} set interfaces bridge \ member interface \ priority \ + +**Configure the** {abbr}`STP (Spanning Tree Protocol)` **port priority +for a specific member interface within a bridge.** + +Within the {abbr}`STP (Spanning Tree Protocol)` topology, each member interface +in a bridge operates as a port with an assigned **priority** and **path cost**. +{abbr}`STP (Spanning Tree Protocol)` uses these values to determine the +**lowest-cost path** to the root bridge, maintaining a loop-free topology. +Traffic flows through the path with the lowest path cost, while alternate +paths remain in standby. + +A **lower** priority value means **higher** precedence in path selection. + +{abbr}`STP (Spanning Tree Protocol)` considers the port priority only if +multiple member interfaces have the same path costs. +``` + +```{cfgcmd} set interfaces bridge \ member interface \ cost \ + +**Configure the** {abbr}`STP (Spanning Tree Protocol)` **path cost for a +specific member interface within the bridge.** + +Path cost is the primary metric {abbr}`STP (Spanning Tree Protocol)` uses to +determine the path to the root bridge. This value is based on interface +bandwidth; faster interfaces receive lower costs. + +By assigning a lower cost, you give the interface higher precedence during +path selection. +``` + +```{cfgcmd} set interfaces bridge \ member interface \ disable-learning + +**Disable MAC address learning for a specific member interface +within a bridge.** + +When learning is disabled, the bridge will not add source MAC addresses +observed on this port to its forwarding database (FDB). Frames destined +to MACs not present in the FDB are then flooded to all bridge ports +rather than unicast-forwarded. +``` + + +### Bridge options + +Configure how bridge interfaces maintain their {abbr}`FDB (Forwarding Database)` +, react to topology changes, and optimize multicast data streams. + +```{cfgcmd} set interfaces bridge \ aging \ + +**Configure the MAC address aging time for the bridge.** + +The duration in seconds that a MAC address remains in the bridge’s {abbr}`FDB +(Forwarding Database)` before removal if no traffic is received from that +address. + +The default value is 300 seconds. +``` + +```{cfgcmd} set interfaces bridge \ max-age \ + +**Configure the** {abbr}`STP (Spanning Tree Protocol)` **max age timer for +the bridge.** + +The duration in seconds that the bridge waits for a {abbr}`BPDU (Bridge +Protocol Data Unit)` from the root bridge. + +If the bridge does not receive a {abbr}`BPDU (Bridge Protocol Data Unit)` +within this period, it recalculates the path to the root bridge or initiates +a new root bridge election. +``` + +```{cfgcmd} set interfaces bridge \ igmp querier + +**Configure the bridge interface to act as the** {abbr}`IGMP (Internet Group +Management Protocol)`/{abbr}`MLD (Multicast Listener Discovery)` **Querier.** + +**When configured:** The bridge interface sends {abbr}`IGMP (Internet Group +Management Protocol)` (IPv4) and {abbr}`MLD (Multicast Listener Discovery)` +(IPv6) general queries to all connected hosts to identify active multicast +listeners. +``` + +```{cfgcmd} set interfaces bridge \ igmp snooping + +**Configure the bridge interface to perform** {abbr}`IGMP (Internet Group +Management Protocol)`/{abbr}`MLD (Multicast Listener Discovery)` +**snooping.** + +**When configured:** The bridge interface monitors {abbr}`IGMP (Internet Group +Management Protocol)` (IPv4) and {abbr}`MLD (Multicast Listener Discovery)` +(IPv6) join requests and restricts multicast traffic forwarding to only active +listeners. This prevents network flooding. +``` + +(stp)= + +#### STP configuration + +{abbr}`STP (Spanning Tree Protocol)` is a Layer 2 protocol that prevents loops +in Ethernet networks by ensuring only one logical path exists between any two +bridges. This creates a loop-free topology and prevents broadcast storms that +can crash the network. + +By default, {abbr}`STP (Spanning Tree Protocol)` is disabled on bridge interfaces. +To activate loop prevention, you must explicitly enable the protocol and +configure its parameters. + +```{cfgcmd} set interfaces bridge \ stp + +Enable {abbr}`STP (Spanning Tree Protocol)` on the bridge interface. +``` + +```{cfgcmd} set interfaces bridge \ forwarding-delay \ + +**Configure the** {abbr}`STP (Spanning Tree Protocol)` **delay, in seconds, +for the bridge interface.** + +This parameter defines how long the bridge interface remains in the listening +and learning states before forwarding traffic. The delay ensures that the +bridge has sufficient time to detect loops (in the listening state) and learn +the MAC addresses of connected devices (in the learning state). + +The default value is 15 seconds. The total time before forwarding begins is +twice this value. +``` + +```{cfgcmd} set interfaces bridge \ hello-time \ + +**Configure the** {abbr}`STP (Spanning Tree Protocol)` **Hello advertisement +interval, in seconds.** + +This parameter sets the frequency at which the bridge interface transmits +Hello packets ({abbr}`BPDUs (Bridge Protocol Data Units)`). These packets +originate from the root bridge and are propagated by designated bridges. If +neighbors stop receiving Hello packets, they assume a connection failure and +trigger a topology recalculation. + +The default value is 2 seconds. +``` + + +### VLAN + +#### VLAN-aware bridges + +```{cfgcmd} set interfaces bridge \ enable-vlan + +**Enable VLAN filtering (also known as VLAN awareness) on the bridge interface.** + +When enabled, the bridge strictly segregates traffic among VLANs configured +on its member interfaces. + +:::{note} +Do not configure **vif 1** on a VLAN-aware bridge. The main bridge +interface acts as VLAN 1 (the default native VLAN) and automatically +handles all untagged traffic. +::: +``` + +```{cfgcmd} set interfaces bridge \ protocol \<802.1ad | 802.1q\> + +**Configure the VLAN protocol (EtherType) for the bridge interface.** + +The following options are available: +* ``802.1q`` (default): Sets the EtherType to ``0x8100``. Used for standard +enterprise VLANs. +* ``802.1ad``: Sets the EtherType to ``0x88a8``. Used for QinQ (provider bridging). +``` + + +#### VLAN configuration + +```{cmdincludemd} /_include/interface-vlan-8021q.txt +:var0: bridge +:var1: br0 +``` + +```{cfgcmd} set interfaces bridge \ member interface \ native-vlan \ + +**Configure the native VLAN ID for a specific member interface within a +VLAN-aware bridge.** + +This assigns the specified ```` to untagged traffic entering the member +interface. The bridge strips the VLAN tag from outgoing traffic matching this +ID. + +**Example:** + +Set the native VLAN ID to 2 for the member interface ``eth0``: + +:::{code-block} none +set interfaces bridge br1 member interface eth0 native-vlan 2 +::: +``` + +```{cfgcmd} set interfaces bridge \ member interface \ allowed-vlan \ + +**Configure allowed VLAN IDs for a specific member interface within a +VLAN-aware bridge.** + +Enter a single VLAN ID or a range of VLAN IDs separated by a hyphen. + +**Example:** + +To allow VLAN ID 4 on member interface ``eth0``: + +:::{code-block} none +set interfaces bridge br1 member interface eth0 allowed-vlan 4 +::: +**Example:** + +To allow VLAN IDs 6 through 8 on member interface ``eth0``: + +:::{code-block} none +set interfaces bridge br1 member interface eth0 allowed-vlan 6-8 +::: +``` + + +### SPAN port mirroring + +```{cmdincludemd} ../../_include/interface-mirror.txt +:var0: bridge +:var1: br1 +:var2: eth3 +``` + + +## Examples + +### Configure a standard bridge + +The following example creates a bridge named br100 with {abbr}`STP (Spanning +Tree Protocol)` enabled. + +Configuration requirements: +- **Bridge name:** `br100` +- **Member interfaces:** Physical interface `eth1` and VLAN interface `eth2.10`. +- **STP:** Enabled. +- **Bridge IP addresses:** `192.0.2.1/24` (IPv4) and `2001:db8::ffff/64` (IPv6). + +```none +set interfaces bridge br100 address 192.0.2.1/24 +set interfaces bridge br100 address 2001:db8::ffff/64 +set interfaces bridge br100 member interface eth1 +set interfaces bridge br100 member interface eth2.10 +set interfaces bridge br100 stp +``` + +Verify the configuration: + +```none +vyos@vyos# show interfaces bridge br100 + address 192.0.2.1/24 + address 2001:db8::ffff/64 + member { + interface eth1 { + } + interface eth2.10 { + } + } + stp +``` + + +### Configure a VLAN-aware bridge + +The following example creates a VLAN-aware bridge named br100. In this setup, +one member interface is configured as a trunk port, and the other as an access +port. The VLAN interface is configured with IP addresses. + +**Configuration requirements:** +- **Bridge name:** `br100`. +- **Trunk port** (`eth1`): Handles **tagged** traffic for VLAN 10. +- **Access port** (`eth2`): Handles **untagged** traffic (assigned to native + VLAN 10). +- **STP:** Enabled. +- **VLAN IP addresses** (`vif 10`): `192.0.2.1/24` (IPv4) and + `2001:db8::ffff/64` (IPv6). + +```none +set interfaces bridge br100 enable-vlan +set interfaces bridge br100 member interface eth1 allowed-vlan 10 +set interfaces bridge br100 member interface eth2 native-vlan 10 +set interfaces bridge br100 vif 10 address 192.0.2.1/24 +set interfaces bridge br100 vif 10 address 2001:db8::ffff/64 +set interfaces bridge br100 stp +``` + +Verify the configuration: + +```none +vyos@vyos# show interfaces bridge br100 + enable-vlan + member { + interface eth1 { + allowed-vlan 10 + } + interface eth2 { + native-vlan 10 + } + } + stp + vif 10 { + address 192.0.2.1/24 + address 2001:db8::ffff/64 + } +``` + + +### Operation + +```{opcmd} show bridge + +Show the status of member interfaces for all configured bridges. + +:::{code-block} none +vyos@vyos:~$ show bridge +3: eth1: mtu 1500 master br0 state forwarding +priority 32 cost 100 +4: eth2: mtu 1500 master br0 state forwarding +priority 32 cost 100 +::: +``` + +```{opcmd} show bridge \ fdb + +Show the {abbr}`FDB (Forwarding Database)` for the specified bridge. + +:::{code-block} none +vyos@vyos:~$ show bridge br0 fdb +50:00:00:08:00:01 dev eth1 vlan 20 master br0 permanent +50:00:00:08:00:01 dev eth1 vlan 10 master br0 permanent +50:00:00:08:00:01 dev eth1 master br0 permanent +33:33:00:00:00:01 dev eth1 self permanent +33:33:00:00:00:02 dev eth1 self permanent +01:00:5e:00:00:01 dev eth1 self permanent +50:00:00:08:00:02 dev eth2 vlan 20 master br0 permanent +50:00:00:08:00:02 dev eth2 vlan 10 master br0 permanent +50:00:00:08:00:02 dev eth2 master br0 permanent +33:33:00:00:00:01 dev eth2 self permanent +33:33:00:00:00:02 dev eth2 self permanent +01:00:5e:00:00:01 dev eth2 self permanent +33:33:00:00:00:01 dev br0 self permanent +33:33:00:00:00:02 dev br0 self permanent +33:33:ff:08:00:01 dev br0 self permanent +01:00:5e:00:00:6a dev br0 self permanent +33:33:00:00:00:6a dev br0 self permanent +01:00:5e:00:00:01 dev br0 self permanent +33:33:ff:00:00:00 dev br0 self permanent +::: +``` + +```{opcmd} show bridge \ mdb + +Show the {abbr}`MDB (Multicast group Database)` for the specified bridge. + +The {abbr}`MDB (Multicast group Database)` is populated by {abbr}`IGMP +(Internet Group Management Protocol)`/{abbr}`MLD (Multicast Listener +Discovery)` snooping and lists the multicast groups currently active on the +bridge. + +:::{code-block} none +vyos@vyos:~$ show bridge br0 mdb +dev br0 port br0 grp ff02::1:ff00:0 temp vid 1 +dev br0 port br0 grp ff02::2 temp vid 1 +dev br0 port br0 grp ff02::1:ff08:1 temp vid 1 +dev br0 port br0 grp ff02::6a temp vid 1 +::: +``` + +```{opcmd} show bridge \ macs + +Show the learned {abbr}`MAC (Media Access Control)` address table for the +specified bridge. + +:::{code-block} none +vyos@vyos:~$ show bridge br100 macs +port no mac addr is local? ageing timer + 1 00:53:29:44:3b:19 yes 0.00 +::: +``` \ No newline at end of file diff --git a/docs/configuration/interfaces/md-dummy.md b/docs/configuration/interfaces/md-dummy.md new file mode 100644 index 00000000..d2d27c5d --- /dev/null +++ b/docs/configuration/interfaces/md-dummy.md @@ -0,0 +1,87 @@ +--- +lastproofread: '2026-01-23' +--- + +(dummy-interface)= + +# Dummy + +A dummy interface is a virtual network interface that operates like the +loopback interface, accepting traffic and routing it back to the local host. +Unlike the loopback interface, which is limited to one per system and reserved +for internal system use, multiple dummy interfaces can be created, removed, and +managed without impacting core operations. + +As a software-based interface, the dummy interface does not depend on physical +link state and remains active as long as the operating system is running. + +Dummy interfaces are commonly used in environments with multiple redundant +uplinks (e.g., a server connected to two different switches), where assigning a +management IP address to a specific physical interface is risky. If that +interface fails, the management IP address becomes unreachable. + +Assigning the management IP address to a dummy interface and advertising it +over all available physical links ensures the address remains reachable as long +as at least one physical path is active. + +Dummy interfaces are also used for testing and simulation purposes. + +## Configuration + +### Common interface configuration + +```{cmdincludemd} /_include/interface-address.txt +:var0: dummy +:var1: dum0 +``` + +```{cmdincludemd} /_include/interface-description.txt +:var0: dummy +:var1: dum0 +``` + +```{cmdincludemd} /_include/interface-disable.txt +:var0: dummy +:var1: dum0 +``` + +```{cmdincludemd} /_include/interface-vrf.txt +:var0: dummy +:var1: dum0 +``` + + +## Operation + +```{opcmd} show interfaces dummy + +Show brief interface information. + +:::{code-block} none +vyos@vyos:~$ show interfaces dummy +Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down +Interface IP Address S/L Description +--------- ---------- --- ----------- +dum0 172.18.254.201/32 u/u +::: +``` + +```{opcmd} show interfaces dummy \ + +Show detailed interface information. + +:::{code-block} none +vyos@vyos:~$ show interfaces dummy dum0 +dum0: mtu 1500 qdisc noqueue state UNKNOWN group default qlen 1000 + link/ether 26:7c:8e:bc:fc:f5 brd ff:ff:ff:ff:ff:ff + inet 172.18.254.201/32 scope global dum0 + valid_lft forever preferred_lft forever + inet6 fe80::247c:8eff:febc:fcf5/64 scope link + valid_lft forever preferred_lft forever + + RX: bytes packets errors dropped overrun mcast + 0 0 0 0 0 0 + TX: bytes packets errors dropped carrier collisions + 1369707 4267 0 0 0 0 +::: +``` \ No newline at end of file diff --git a/docs/configuration/interfaces/md-ethernet.md b/docs/configuration/interfaces/md-ethernet.md new file mode 100644 index 00000000..eac0b443 --- /dev/null +++ b/docs/configuration/interfaces/md-ethernet.md @@ -0,0 +1,515 @@ +--- +lastproofread: '2026-01-19' +--- + +(ethernet-interface)= + +# Ethernet + +Ethernet interfaces (e.g., `eth0`, `eth1`) represent the host's physical +or virtual network ports. + +They are the most common interface type, serving as the base layer upon which +IP addresses, VLANs, and tunnels are configured to carry traffic across both +LANs and WANs. + +## Configuration + +### Common interface configuration + +```{cmdincludemd} /_include/interface-common-with-dhcp.txt +:var0: ethernet +:var1: eth0 +``` + +```{cfgcmd} set interfaces ethernet \ switchdev + +**Enable** ``switchdev`` **mode for the interface.** + +In ``switchdev`` mode, the interface offloads traffic switching between ports +to the hardware, bypassing the host CPU. This increases the interface’s +traffic-handling capacity and reduces its forwarding delay. +``` + +:::{note} +`switchdev` mode is available only on certain physical network +interfaces and requires a switchdev-compatible driver. +::: + +### Ethernet options + +```{cfgcmd} set interfaces ethernet \ duplex \ + +**Configure duplex mode for the interface.** + +The following duplex modes are available: + +* ``auto``: The interface negotiates the duplex mode with the connected device. +* ``full``: The interface sends and receives data simultaneously. The + connected device must also be set to full-duplex to avoid a duplex mismatch. +* ``half``: The interface either sends or receives data, but not both at the + same time. + +The default duplex mode is ``auto``. +``` + +```{cfgcmd} set interfaces ethernet \ speed \ + +**Configure the interface's speed, in Mbit/s.** + +The following options are available: + +* ``auto``: The interface negotiates the speed with the connected device. +* ``10, 100, 1000 ...``: The interface operates at the selected speed. The + connected device must be set to the same speed to establish a connection. + +The default option is ``auto``. +``` + +```{cfgcmd} set interfaces ethernet \ ring-buffer rx \ + +**Configure the receive (RX) ring buffer size for the interface.** + +The RX ring buffer size defines the number of incoming packets the interface +can queue in hardware before the CPU processes them. + +Higher values reduce the risk of drops when the NIC receives network traffic +faster than the CPU can process it, though latency may increase. Lower values +reduce latency but increase the risk of packet drops during incoming traffic +bursts. + +To view supported values for a specific interface, use: +``` + +```none +ethtool -g +``` + +```{cfgcmd} set interfaces ethernet \ ring-buffer tx \ + +**Configure the transmit (TX) ring buffer size.** + +The TX ring buffer size defines the number of outgoing packets the interface +can queue in hardware before they are transmitted onto the network. + +Higher values reduce the risk of drops when the CPU generates traffic faster +than the NIC can handle, though latency may increase. Lower values reduce +latency but increase the risk of packet drops during outgoing traffic bursts. + +To view supported values for a specific interface, use: +``` + +```none +ethtool -g +``` + + +#### Interrupt Coalescing + +Interrupt coalescing is a mechanism that reduces CPU interrupt load by bundling +multiple packets into a single interrupt event instead of interrupting +the CPU for every packet arrival or transmission. + +:::{note} +Not all network drivers or virtual interfaces support all +coalescing parameters. Use `ethtool --show-coalesce ` +to verify which settings are supported by your hardware and driver. +::: + +**Basic adaptive coalescing** + +```{cfgcmd} set interfaces ethernet \ interrupt-coalescing adaptive-rx + +``` +```{cfgcmd} set interfaces ethernet \ interrupt-coalescing adaptive-tx + +Enable adaptive interrupt coalescing. The NIC automatically tunes RX/TX +interrupt pacing based on traffic patterns to reduce CPU utilization +during high throughput while preserving latency at low packet rates. +``` + +**Basic interrupt delay** + +```{cfgcmd} set interfaces ethernet \ interrupt-coalescing rx-usecs \<0-16384\> +``` + +```{cfgcmd} set interfaces ethernet \ interrupt-coalescing tx-usecs \<0-16384\> + +Set the delay in microseconds before generating an RX/TX interrupt after +receiving or transmitting a packet. Lower values reduce latency; higher +values reduce CPU load. +``` + +**Interrupt frame thresholds** + +```{cfgcmd} set interfaces ethernet \ interrupt-coalescing rx-frames \ +``` + +```{cfgcmd} set interfaces ethernet \ interrupt-coalescing tx-frames \ + +Generate an RX/TX interrupt only after the specified number of packets +have been received or transmitted. +``` + +**IRQ-specific coalescing** + +```{cfgcmd} set interfaces ethernet \ interrupt-coalescing rx-usecs-irq \ +``` + +```{cfgcmd} set interfaces ethernet \ interrupt-coalescing rx-frames-irq \ +``` + +```{cfgcmd} set interfaces ethernet \ interrupt-coalescing tx-usecs-irq \ +``` + +```{cfgcmd} set interfaces ethernet \ interrupt-coalescing tx-frames-irq \ + +Control interrupt coalescing parameters while the driver is already +servicing an interrupt (IRQ context). These settings allow finer tuning +of interrupt behavior under sustained load. +``` + +**Adaptive rate thresholds** + +```{cfgcmd} set interfaces ethernet \ interrupt-coalescing pkt-rate-low \ +``` + +```{cfgcmd} set interfaces ethernet \ interrupt-coalescing pkt-rate-high \ + +Define packet-rate thresholds (packets per second) used by adaptive +coalescing to switch between low-rate and high-rate interrupt coalescing +profiles. +``` + +**Low-rate adaptive parameters** + +```{cfgcmd} set interfaces ethernet \ interrupt-coalescing rx-usecs-low \ +``` + +```{cfgcmd} set interfaces ethernet \ interrupt-coalescing rx-frame-low \ +``` + +```{cfgcmd} set interfaces ethernet \ interrupt-coalescing tx-usecs-low \ +``` + +```{cfgcmd} set interfaces ethernet \ interrupt-coalescing tx-frame-low \ + +Interrupt coalescing parameters applied when the packet rate is below +``pkt-rate-low``. Typically optimized for lower latency. +``` + +**High-rate adaptive parameters** + +```{cfgcmd} set interfaces ethernet \ interrupt-coalescing rx-usecs-high \ +``` + +```{cfgcmd} set interfaces ethernet \ interrupt-coalescing rx-frame-high \ +``` + +```{cfgcmd} set interfaces ethernet \ interrupt-coalescing tx-usecs-high \ +``` + +```{cfgcmd} set interfaces ethernet \ interrupt-coalescing tx-frame-high \ + +Interrupt coalescing parameters applied when the packet rate exceeds +``pkt-rate-high``. Typically optimized for maximum throughput and +reduced CPU utilization. +``` + +**Statistics and sampling** + +```{cfgcmd} set interfaces ethernet \ interrupt-coalescing stats-block-usecs \ +``` + +```{cfgcmd} set interfaces ethernet \ interrupt-coalescing sample-interval \ + +Control how frequently coalescing statistics are updated and how often +the NIC samples traffic rates for adaptive coalescing decisions. +``` + +**Completion queue (CQE) mode** + +```{cfgcmd} set interfaces ethernet \ interrupt-coalescing cqe-mode-rx +``` + +```{cfgcmd} set interfaces ethernet \ interrupt-coalescing cqe-mode-tx + +Enable RX/TX Completion Queue Entry (CQE) mode, if supported by the +driver. CQE mode can improve performance on high-speed NICs by +optimizing completion handling. +``` + +**Transmit aggregation** + +```{cfgcmd} set interfaces ethernet \ interrupt-coalescing tx-aggr-max-bytes \ +``` + +```{cfgcmd} set interfaces ethernet \ interrupt-coalescing tx-aggr-max-frames \ +``` + +```{cfgcmd} set interfaces ethernet \ interrupt-coalescing tx-aggr-time-usecs \ + +Control transmit packet aggregation. Packets may be buffered and sent +together until one of the configured limits (bytes, frames, or time) +is reached, reducing interrupt and DMA overhead. +``` + +#### Offloading + +```{cfgcmd} set interfaces ethernet \ offload \ + +**Configure the offloading features for the interface.** + +The interface offloading features define whether specific packet-processing tasks +are performed by hardware (the NIC) or by software (the kernel). You can enable +multiple offloading features for a single interface. + + * ``lro`` **(Large Receive Offload):** Instructs the NIC to merge multiple + incoming packets into one larger packet before sending it to the CPU. + + :::{note} + {abbr}`LRO (Large Receive Offload)` hardware support is often limited + to TCP/IPv4 packets. For details on LRO limitations, see + https://lwn.net/Articles/358910/ + ::: + :::{warning} + {abbr}`LRO (Large Receive Offload)` irreversibly alters packet + headers during merging. This prevents the merged packet from being correctly + split back into the original packets, causing packet drops and forwarding + failures on routers and bridges. Use {abbr}`LRO (Large Receive Offload)` only + for end-hosts that do not forward traffic. + ::: + * ``tso`` **(TCP Segmentation Offload):** Instructs the NIC to split large TCP + packets into smaller ones before transmitting them to the network. + + **Important:** {abbr}`SG (Scatter-Gather/Scatter-Gather DMA)` must be enabled + for {abbr}`TSO (TCP Segmentation Offload)` to work. Additionally, {abbr}`GSO + (Generic Segmentation Offload)` should be enabled as a safety fallback; it + ensures that if traffic is rerouted to hardware without {abbr}`TSO (TCP + Segmentation Offload)` support, the kernel can still segment the packets, + preventing transmission failures. + + * ``gso`` **(Generic Segmentation Offload):** Instructs the kernel to split + large packets into smaller ones before sending them to the NIC. + + {abbr}`GSO (Generic Segmentation Offload)` serves as a software fallback for + hardware that does not support {abbr}`TSO (TCP Segmentation Offload)` or for + protocols (like UDP) that hardware cannot offload. + + **Important:** {abbr}`SG (Scatter-Gather/Scatter-Gather DMA)` must be enabled + for {abbr}`GSO (Generic Segmentation Offload)` to work. + + * ``gro`` **(Generic Receive Offload):** Instructs the kernel to merge multiple + incoming packets into one larger packet before passing it to upper protocol + layers. + + Unlike LRO, GRO preserves the necessary packet metadata so the merged packet + can be correctly split back into the original packets. This makes GRO safe for + use on routers and bridges. + + :::{note} +The exception is for IPv4 IDs. If the "Don't Fragment" (DF) bit is +set and IDs are not sequential, {abbr}`GSO (Generic Segmentation Offload)` +alters them to maintain a consistent sequence for {abbr}`GSO (Generic +Segmentation Offload)` compatibility. + ::: + * ``rps`` **(Receive Packet Steering):** Instructs the kernel to distribute + the processing of incoming packets across multiple CPU cores. + + The kernel calculates a hash from packet headers (IP addresses and ports) to + ensure packets from the same flow are processed by the same CPU core. + + :::{note} +{abbr}`RPS (Receive Packet Steering)` is a software version of +{abbr}`RSS (Receive Side Scaling)` and is useful for NICs without hardware +multi-queue support. + ::: + * ``sg`` **(Scatter-Gather/Scatter-Gather DMA):** Instructs the NIC to fetch + data fragments from various RAM locations and transmit them as a single packet + to the network, eliminating the need for the kernel to copy them into a + contiguous block first. +``` + +#### 802.1X (EAPOL) authentication + +```{cmdincludemd} /_include/interface-eapol.txt +:var0: ethernet +:var1: eth0 +``` + +#### EVPN Multihoming + +Uplink/core tracking. + +```{cmdincludemd} /_include/interface-evpn-uplink.txt +:var0: ethernet +:var1: eth0 +``` + +### VLAN +#### Regular VLANs (802.1q) + +```{cmdincludemd} /_include/interface-vlan-8021q.txt +:var0: ethernet +:var1: eth0 +``` + +#### 802.1ad (QinQ) + +```{cmdincludemd} /_include/interface-vlan-8021ad.txt +:var0: ethernet +:var1: eth0 +``` + +### SPAN port mirroring + +```{cmdincludemd} ../../_include/interface-mirror.txt +:var0: ethernet +:var1: eth1 +:var2: eth3 +``` + +## Operation + +```{opcmd} show interfaces ethernet + +Show brief interface information. + +:::{code-block} none +vyos@vyos:~$ show interfaces ethernet +Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down +Interface IP Address S/L Description +--------- ---------- --- ----------- +eth0 172.18.201.10/24 u/u LAN +eth1 172.18.202.11/24 u/u WAN +eth2 - u/D +::: +``` + +```{opcmd} show interfaces ethernet \ + +Show detailed interface information. + +:::{code-block} none +vyos@vyos:~$ show interfaces ethernet eth0 +eth0: mtu 1500 qdisc pfifo_fast state UP group default qlen 1000 + link/ether 00:50:44:00:f5:c9 brd ff:ff:ff:ff:ff:ff + inet6 fe80::250:44ff:fe00:f5c9/64 scope link + valid_lft forever preferred_lft forever + + RX: bytes packets errors dropped overrun mcast + 56735451 179841 0 0 0 142380 + TX: bytes packets errors dropped carrier collisions + 5601460 62595 0 0 0 0 +::: +``` + +```{opcmd} show interfaces ethernet \ physical + +Show interface hardware-level and driver details. + +:::{code-block} none +vyos@vyos:~$ show interfaces ethernet eth0 physical +Settings for eth0: + Supported ports: [ TP ] + Supported link modes: 1000baseT/Full + 10000baseT/Full + Supported pause frame use: No + Supports auto-negotiation: No + Supported FEC modes: Not reported + Advertised link modes: Not reported + Advertised pause frame use: No + Advertised auto-negotiation: No + Advertised FEC modes: Not reported + Speed: 10000Mb/s + Duplex: Full + Port: Twisted Pair + PHYAD: 0 + Transceiver: internal + Auto-negotiation: off + MDI-X: Unknown + Supports Wake-on: uag + Wake-on: d + Link detected: yes +driver: vmxnet3 +version: 1.4.16.0-k-NAPI +firmware-version: +expansion-rom-version: +bus-info: 0000:0b:00.0 +supports-statistics: yes +supports-test: no +supports-eeprom-access: no +supports-register-dump: yes +supports-priv-flags: no +::: +``` + +```{opcmd} show interfaces ethernet \ physical offload + +Show the status of the interface offloading features. + +:::{code-block} none +vyos@vyos:~$ show interfaces ethernet eth0 physical offload +rx-checksumming on +tx-checksumming on +tx-checksum-ip-generic on +scatter-gather off +tx-scatter-gather off +tcp-segmentation-offload off +tx-tcp-segmentation off +tx-tcp-mangleid-segmentation off +tx-tcp6-segmentation off +udp-fragmentation-offload off +generic-segmentation-offload off +generic-receive-offload off +large-receive-offload off +rx-vlan-offload on +tx-vlan-offload on +ntuple-filters off +receive-hashing on +tx-gre-segmentation on +tx-gre-csum-segmentation on +tx-udp_tnl-segmentation on +tx-udp_tnl-csum-segmentation on +tx-gso-partial on +tx-nocache-copy off +rx-all off +::: +``` + +```{opcmd} show interfaces ethernet \ transceiver + +Show information about the transceiver module plugged into the interface +(e.g., SFP+, QSFP). + +:::{code-block} none +vyos@vyos:~$ show interfaces ethernet eth5 transceiver + Identifier : 0x03 (SFP) + Extended identifier : 0x04 (GBIC/SFP defined by 2-wire interface ID) + Connector : 0x07 (LC) + Transceiver codes : 0x00 0x00 0x00 0x01 0x00 0x00 0x00 0x00 0x00 + Transceiver type : Ethernet: 1000BASE-SX + Encoding : 0x01 (8B/10B) + BR, Nominal : 1300MBd + Rate identifier : 0x00 (unspecified) + Length (SMF,km) : 0km + Length (SMF) : 0m + Length (50um) : 550m + Length (62.5um) : 270m + Length (Copper) : 0m + Length (OM3) : 0m + Laser wavelength : 850nm + Vendor name : CISCO-FINISAR + Vendor OUI : 00:90:65 + Vendor PN : FTRJ-8519-7D-CS4 + Vendor rev : A + Option values : 0x00 0x1a + Option : RX_LOS implemented + Option : TX_FAULT implemented + Option : TX_DISABLE implemented + BR margin, max : 0% + BR margin, min : 0% + Vendor SN : FNS092xxxxx + Date code : 0506xx +::: +``` \ No newline at end of file diff --git a/docs/configuration/interfaces/md-geneve.md b/docs/configuration/interfaces/md-geneve.md new file mode 100644 index 00000000..1fce1119 --- /dev/null +++ b/docs/configuration/interfaces/md-geneve.md @@ -0,0 +1,105 @@ +--- +lastproofread: '2026-02-02' +--- + +(geneve-interface)= + +# Geneve + +{abbr}`Geneve (Generic Network Virtualization Encapsulation)` interfaces +operate as virtual network ports. Administrators can apply standard network +configurations on them, such as IP addressing, bridging, or firewall rules, +just as they would on physical Ethernet ports. + +The Geneve protocol encapsulates Layer 2 Ethernet frames originating from +endpoints such as virtual machines, containers, or physical servers inside UDP +packets. It unifies the features of earlier encapsulation protocols, including +VXLAN, NVGRE, and STT, and addresses their limitations, such as fixed header +structures and a lack of metadata support. Because of its extensibility, Geneve +may eventually replace those older protocols. + +Geneve tunnels are used to connect virtual switches residing within +hypervisors, physical switches, middleboxes, and other network appliances. + +Geneve tunnels operate over any standard IP network. In larger deployments, +the underlying network (underlay) is often built using a **Clos** topology, +also known as a *leaf-and-spine* or *fat-tree* topology. + +Geneve header: + +```none ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +|Ver| Opt Len |O|C| Rsvd. | Protocol Type | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +| Virtual Network Identifier (VNI) | Reserved | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +| Variable Length Options | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +``` + + +## Configuration + +### Common interface configuration + +```{cmdincludemd} /_include/interface-address.txt +:var0: geneve +:var1: gnv0 +``` + +```{cmdincludemd} /_include/interface-description.txt +:var0: geneve +:var1: gnv0 +``` + +```{cmdincludemd} /_include/interface-disable.txt +:var0: geneve +:var1: gnv0 +``` + +```{cmdincludemd} /_include/interface-mac.txt +:var0: geneve +:var1: gnv0 +``` + +```{cmdincludemd} /_include/interface-mtu.txt +:var0: geneve +:var1: gnv0 +``` + +```{cmdincludemd} /_include/interface-ip.txt +:var0: geneve +:var1: gnv0 +``` + +```{cmdincludemd} /_include/interface-ipv6.txt +:var0: geneve +:var1: gnv0 +``` + + +### Geneve options + +```{cfgcmd} set interfaces geneve gnv0 remote \ + +Configure the remote endpoint IP address for the Geneve tunnel. +``` + +```{cfgcmd} set interfaces geneve gnv0 vni \ + +**Configure** {abbr}`VNI (Virtual Network Identifier)` **for the Geneve +interface.** + +The VNI is a virtual network identifier. It allows multiple virtual networks to +share the same physical infrastructure and remain isolated. + +The VNI is also used to distribute traffic after it leaves the tunnel, for +example, to map packets with overlapping IP addresses to specific routing +tables. +``` + +```{cfgcmd} set interfaces gnv0 \ port \ + +**Configure the destination UDP port for the remote Geneve tunnel endpoint.** +Ensure the remote peer is configured to listen on this specific port. +``` \ No newline at end of file diff --git a/docs/configuration/interfaces/md-index.md b/docs/configuration/interfaces/md-index.md new file mode 100644 index 00000000..9082cd80 --- /dev/null +++ b/docs/configuration/interfaces/md-index.md @@ -0,0 +1,26 @@ +# Interfaces + +```{toctree} +:includehidden: true +:maxdepth: 1 + +bonding +bridge +dummy +ethernet +geneve +l2tpv3 +loopback +macsec +openvpn +wireguard +pppoe +pseudo-ethernet +sstp-client +tunnel +virtual-ethernet +vti +vxlan +wireless +wwan +``` diff --git a/docs/configuration/interfaces/md-l2tpv3.md b/docs/configuration/interfaces/md-l2tpv3.md new file mode 100644 index 00000000..324840fa --- /dev/null +++ b/docs/configuration/interfaces/md-l2tpv3.md @@ -0,0 +1,170 @@ +--- +lastproofread: '2026-02-05' +--- + +(l2tpv3-interface)= + +# L2TPv3 + +{abbr}`L2TPv3 (Layer 2 Tunneling Protocol version 3)` interfaces let you +establish L2TPv3 tunnels to transport Layer 2 traffic over IP networks. + +The L2TPv3 protocol (defined in RFC 3931) wraps Layer 2 frames (e.g., Ethernet, +Frame Relay, HDLC) within IP packets, allowing them to traverse the underlying +IP infrastructure. + +Unlike L2TPv2, which strictly requires UDP encapsulation, the L2TPv3 protocol +is more flexible and supports two encapsulation types: + +> - **Direct IP:** Tunnel data is encapsulated directly inside IP packets +> (Protocol 115) for lower overhead. +> - **UDP:** Tunnel data is encapsulated inside a UDP datagram. This allows the +> tunnel to traverse NAT more easily. + +L2TPv3 tunnels connect geographically separated sites, serving as a simpler +alternative to {ref}`mpls` by operating over basic IP connectivity rather than +requiring a full MPLS infrastructure. + +L2TPv3 tunnels can be established over both IPv4 and IPv6 underlying networks. + +## Configuration + +### Common interface configuration + +```{cmdincludemd} /_include/interface-common-without-dhcp.txt +:var0: l2tpv3 +:var1: l2tpeth0 +``` + + +### L2TPv3 options + +Use the following commands to configure the L2TPv3 tunnel's specific parameters. + +```{cfgcmd} set interfaces l2tpv3 \ encapsulation \ + +**Configure the encapsulation type for the L2TPv3 tunnel.** + +Valid values are ``udp`` and ``ip``. + +The default encapsulation type is ``udp``. +``` + +:::{note} +The encapsulation type must match on both the local and remote peers +for the tunnel to establish. +::: + +```{cfgcmd} set interfaces l2tpv3 \ source-address \ + +**Configure the L2TPv3 tunnel source IP address.** + +The specified address must be a local interface IP address and can be either +IPv4 or IPv6. +``` + +```{cfgcmd} set interfaces l2tpv3 \ remote \ + +**Configure the L2TPv3 tunnel destination IP address.** + +The specified address must be a remote peer’s interface IP address and can be +either IPv4 or IPv6. +``` + +```{cfgcmd} set interfaces l2tpv3 \ session-id \ + +**Configure the local session ID within the L2TPv3 tunnel.** + +The ``session-id`` is a 32-bit value that identifies an incoming tunnel session +on the local peer. + +The ``peer-session-id`` that identifies this session on the remote peer must be +set to the same value. +``` + +```{cfgcmd} set interfaces l2tpv3 \ peer-session-id \ + +**Configure the peer session ID within the L2TPv3 tunnel.** + +The ``peer-session-id`` is a 32-bit value that identifies an outgoing tunnel +session from the local peer. + +The ``peer-session-id`` must match the ``session-id`` configured for this +session on the remote peer. +``` + +```{cfgcmd} set interfaces l2tpv3 \ tunnel-id \ + +**Configure the local identifier for the L2TPv3 tunnel.** + +The ``tunnel-id`` is a 32-bit value that identifies the L2TPv3 tunnel on the +local peer. + +The ``peer-tunnel-id`` that identifies this tunnel on the remote peer must be +set to the same value. +``` + +```{cfgcmd} set interfaces l2tpv3 \ peer-tunnel-id \ + +**Configure the peer identifier for the L2TPv3 tunnel.** + +The ``peer-tunnel-id`` is a 32-bit value that identifies the L2TPv3 tunnel on +the remote peer and must correspond to the ``tunnel-id`` configured for that +tunnel on that peer. + +The ``peer-tunnel-id`` must match the ``tunnel-id`` that identifies this tunnel +on the remote peer. +``` + + +## Example + +### L2TPv3 tunnel with IP encapsulation + +The following example shows the configuration of an L2TPv3 tunnel using direct +IP encapsulation: + +```none +# show interfaces l2tpv3 +l2tpv3 l2tpeth10 { + address 192.168.37.1/27 + encapsulation ip + source-address 192.0.2.1 + peer-session-id 100 + peer-tunnel-id 200 + remote 203.0.113.24 + session-id 100 + tunnel-id 200 +} +``` + +The inverse configuration must be applied to the remote peer. + +### L2TPv3 tunnel with UDP encapsulation + +The following example shows the configuration of an L2TPv3 tunnel using UDP +encapsulation. + +This setup is recommended when the tunnel traverses NAT devices. + +Configuration notes: +- Use a local LAN IP address as the `source-address`. +- Configure a forwarding rule to allow tunnel traffic on the specified UDP port + on the upstream NAT device. +- Use a distinct UDP port for each individual tunnel. + +```none +# show interfaces l2tpv3 +l2tpv3 l2tpeth10 { + address 192.168.37.1/27 + destination-port 9001 + encapsulation udp + source-address 192.0.2.1 + peer-session-id 100 + peer-tunnel-id 200 + remote 203.0.113.24 + session-id 100 + source-port 9000 + tunnel-id 200 +} +``` diff --git a/docs/configuration/interfaces/md-loopback.md b/docs/configuration/interfaces/md-loopback.md new file mode 100644 index 00000000..72f14c16 --- /dev/null +++ b/docs/configuration/interfaces/md-loopback.md @@ -0,0 +1,67 @@ +--- +lastproofread: '2026-01-23' +--- + +(loopback-interface)= + +# Loopback + +The loopback interface is a virtual, software-based network interface. All +traffic sent to it loops back and only targets services on the local host. + +:::{note} +Only one loopback `lo` interface is allowed per operating system. +If you require multiple virtual interfaces, use the {ref}`dummy-interface` +interface type. +::: + +## Configuration + +### Common interface configuration + +```{cmdincludemd} /_include/interface-address.txt +:var0: loopback +:var1: lo +``` + +```{cmdincludemd} /_include/interface-description.txt +:var0: loopback +:var1: lo +``` + + +## Operation + +```{opcmd} show interfaces loopback + +Show brief interface information. + +:::{code-block} none +vyos@vyos:~$ show interfaces loopback +Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down +Interface IP Address S/L Description +--------- ---------- --- ----------- +lo 127.0.0.1/8 u/u + ::1/128 +::: +``` + +```{opcmd} show interfaces loopback lo + +Show detailed interface information. + +:::{code-block} none +vyos@vyos:~$ show interfaces loopback lo +lo: mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1000 + link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00 + inet 127.0.0.1/8 scope host lo + valid_lft forever preferred_lft forever + inet6 ::1/128 scope host + valid_lft forever preferred_lft forever + + RX: bytes packets errors dropped overrun mcast + 300 6 0 0 0 0 + TX: bytes packets errors dropped carrier collisions + 300 6 0 0 0 0 +::: +``` \ No newline at end of file diff --git a/docs/configuration/interfaces/md-macsec.md b/docs/configuration/interfaces/md-macsec.md new file mode 100644 index 00000000..b3c70362 --- /dev/null +++ b/docs/configuration/interfaces/md-macsec.md @@ -0,0 +1,319 @@ +--- +lastproofread: '2026-02-13' +--- + +(macsec-interface)= + +# MACsec + +MACsec is an IEEE standard (IEEE 802.1AE) for MAC security, introduced in +2006\. It enables protocol-independent connectivity between two hosts, providing +data confidentiality, authenticity, and integrity using GCM-AES ciphers. MACsec +operates at the Ethernet layer as a Layer 2 protocol and secures traffic within +Layer 2 networks, including DHCP and ARP requests. It does not compete with +other security solutions, such as IPsec (Layer 3) or TLS (Layer 4), as each +addresses distinct use cases. + +## Configuration + +### Common interface configuration + +```{cmdincludemd} /_include/interface-common-with-dhcp.txt +:var0: macsec +:var1: macsec0 +``` + + +### MACsec options + +```{cfgcmd} set interfaces macsec \ security cipher \ + +**Configure the cipher suite for the MACsec interface.** + +This configuration parameter is mandatory. +``` + +```{cfgcmd} set interfaces macsec \ security encrypt + +**Enable encryption on the MACsec interface.** + +By default, MACsec interfaces only provide authentication; encryption is +optional. +When enabled, outgoing packets are encrypted using the configured cipher suite. +``` + +```{cfgcmd} set interfaces macsec \ source-interface \ + +**Configure a physical source interface for the MACsec interface.** + +Traffic transmitted through this interface is authenticated and, if configured, +encrypted. +``` + + +#### MACsec key management + +**Static** {abbr}`SAK (Secure Authentication Key)` **mode** + +In static SAK mode, administrators must manually configure and update SAKs on +each MACsec peer. {abbr}`MKA (MACsec Key Agreement protocol)` cannot be used in +this mode. + +```{cfgcmd} set interfaces macsec \ security static key \ + +**Configure the Transmit (TX) SAK for the MACsec interface.** + +The key must be a 16-byte (GCM-AES-128) or 64-byte (GCM-AES-256) hexadecimal +string. +``` + +```{cfgcmd} set interfaces macsec \ security static peer \ mac \ + +**Configure the MAC address associated with the MACsec peer.** +``` + +```{cfgcmd} set interfaces macsec \ security static peer \ key \ + +**Configure the RX SAK for traffic from the MACsec peer.** + +The key must be a 16-byte (GCM-AES-128) or 64-byte (GCM-AES-256) hexadecimal +string. +``` + +```{cfgcmd} set interfaces macsec \ security static peer \ disable +``` + +**Dynamic** {abbr}`MKA (MACsec Key Agreement protocol)` **mode** + +In this mode, the {abbr}`MKA (MACsec Key Agreement protocol)` protocol is used +to generate, distribute, and update {abbr}`CAKs (MACsec Connectivity +Association Keys)`, and to authenticate MACsec peers. + +```{cfgcmd} set interfaces macsec \ security mka cak \ + +**Configure the** {abbr}`CAK (MACsec Connectivity Association Key)` **for the +MACsec interface.** + +The {abbr}`CAK (MACsec Connectivity Association Key)` and its {abbr}`CKN +(MACsec Connectivity Association Key Name)` form the pre-shared master key pair +used to authenticate MACsec peers. +``` + +```{cfgcmd} set interfaces macsec \ security mka ckn \ + +Configure the {abbr}`CKN (MACsec Connectivity Association Key Name)` for the +MACsec interface. +``` + +```{cfgcmd} set interfaces macsec \ security mka priority \ + +Configure the MKA key server priority for the MACsec interface. +The peer with the lowest priority is elected as the key server. +``` + +#### Replay protection + +```{cfgcmd} set interfaces macsec \ security replay-window \ + +The replay protection window defines how many out-of-order frames can be +received before they are dropped as a potential replay attack. +The following values are valid: +- ``0``: Any out-of-order frame is immediately dropped. +- ``1-4294967295``: Allows the specified number of out-of-order frames. +``` + +## Operation + +```{opcmd} run generate macsec mka cak \ + +Generate a 128-bit (GCM-AES-128) or 256-bit (GCM-AES-256) {abbr}`MKA (MACsec +Key Agreement protocol)` {abbr}`CAK (MACsec Connectivity Association Key)`. + +:::{code-block} none +vyos@vyos:~$ generate macsec mka cak gcm-aes-128 +20693b6e08bfa482703a563898c9e3ad +::: +``` + +```{opcmd} run generate macsec mka ckn + +Generate an {abbr}`MKA (MACsec Key Agreement protocol)` {abbr}`CAK (MACsec +Connectivity Association Key)`. + +:::{code-block} none +vyos@vyos:~$ generate macsec mka ckn +88737efef314ee319b2cbf30210a5f164957d884672c143aefdc0f5f6bc49eb2 +::: +``` + +```{opcmd} show interfaces macsec + +Show all MACsec interfaces. + +:::{code-block} none +vyos@vyos:~$ show interfaces macsec +17: macsec1: protect on validate strict sc off sa off encrypt on send_sci on end_station off scb off replay off +cipher suite: GCM-AES-128, using ICV length 16 +TXSC: 005056bfefaa0001 on SA 0 +20: macsec0: protect on validate strict sc off sa off encrypt off send_sci on end_station off scb off replay off +cipher suite: GCM-AES-128, using ICV length 16 +TXSC: 005056bfefaa0001 on SA 0 +::: +``` + +```{opcmd} show interfaces macsec \ + +Show information for a specific MACsec interface. + +:::{code-block} none +vyos@vyos:~$ show interfaces macsec macsec1 +17: macsec1: protect on validate strict sc off sa off encrypt on send_sci on end_station off scb off replay off +cipher suite: GCM-AES-128, using ICV length 16 +TXSC: 005056bfefaa0001 on SA 0 +::: +``` + +## Examples + +**Site-to-site MACsec with dynamic MKA over an untrusted network** + +In the following example, two routers (R1 and R2) are connected via an +untrusted switch, using their `eth1` interfaces as the underlay. The MACsec +interface (`macsec1`) with dynamic MKA encrypts traffic between them. + +Topology details: +- R1 IP addresses: `192.0.2.1/24` and `2001:db8::1/64`. +- R2 IP addresses: `192.0.2.2/24` and `2001:db8::2/64`. + +**R1** + +```none +set interfaces macsec macsec1 address '192.0.2.1/24' +set interfaces macsec macsec1 address '2001:db8::1/64' +set interfaces macsec macsec1 security cipher 'gcm-aes-128' +set interfaces macsec macsec1 security encrypt +set interfaces macsec macsec1 security mka cak '232e44b7fda6f8e2d88a07bf78a7aff4' +set interfaces macsec macsec1 security mka ckn '40916f4b23e3d548ad27eedd2d10c6f98c2d21684699647d63d41b500dfe8836' +set interfaces macsec macsec1 source-interface 'eth1' +``` + +**R2** + +```none +set interfaces macsec macsec1 address '192.0.2.2/24' +set interfaces macsec macsec1 address '2001:db8::2/64' +set interfaces macsec macsec1 security cipher 'gcm-aes-128' +set interfaces macsec macsec1 security encrypt +set interfaces macsec macsec1 security mka cak '232e44b7fda6f8e2d88a07bf78a7aff4' +set interfaces macsec macsec1 security mka ckn '40916f4b23e3d548ad27eedd2d10c6f98c2d21684699647d63d41b500dfe8836' +set interfaces macsec macsec1 source-interface 'eth1' +``` + +Pinging (IPv6) the other host and intercepting traffic on `eth1` confirm that +the content is encrypted. + +```none +17:35:44.586668 00:50:56:bf:ef:aa > 00:50:56:b3:ad:d6, ethertype Unknown (0x88e5), length 150: + 0x0000: 2c00 0000 000a 0050 56bf efaa 0001 d9fb ,......PV....... + 0x0010: 920a 8b8d 68ed 9609 29dd e767 25a4 4466 ....h...)..g%.Df + 0x0020: 5293 487b 9990 8517 3b15 22c7 ea5c ac83 R.H{....;."..\.. + 0x0030: 4c6e 13cf 0743 f917 2c4e 694e 87d1 0f09 Ln...C..,NiN.... + 0x0040: 0f77 5d53 ed75 cfe1 54df 0e5a c766 93cb .w]S.u..T..Z.f.. + 0x0050: c4f2 6e23 f200 6dfe 3216 c858 dcaa a73b ..n#..m.2..X...; + 0x0060: 4dd1 9358 d9e4 ed0e 072f 1acc 31c4 f669 M..X...../..1..i + 0x0070: e93a 9f38 8a62 17c6 2857 6ac5 ec11 8b0e .:.8.b..(Wj..... + 0x0080: 6b30 92a5 7ccc 720b k0..|.r. +``` + +Disabling encryption on the MACsec interface by removing the `security +encrypt` option shows the unencrypted but authenticated content. + +```none +17:37:00.746155 00:50:56:bf:ef:aa > 00:50:56:b3:ad:d6, ethertype Unknown (0x88e5), length 150: + 0x0000: 2000 0000 0009 0050 56bf efaa 0001 86dd .......PV....... + 0x0010: 6009 86f3 0040 3a40 2001 0db8 0000 0000 `....@:@........ + 0x0020: 0000 0000 0000 0001 2001 0db8 0000 0000 ................ + 0x0030: 0000 0000 0000 0002 8100 d977 0f30 0003 ...........w.0.. + 0x0040: 1ca0 c65e 0000 0000 8d93 0b00 0000 0000 ...^............ + 0x0050: 1011 1213 1415 1617 1819 1a1b 1c1d 1e1f ................ + 0x0060: 2021 2223 2425 2627 2829 2a2b 2c2d 2e2f .!"#$%&'()*+,-./ + 0x0070: 3031 3233 3435 3637 87d5 eed3 3a39 d52b 01234567....:9.+ + 0x0080: a282 c842 5254 ef28 ...BRT.( +``` + +**Site-to-site MACsec with static SAK over an untrusted network** + +This example uses the same topology as above, but applies static SAK mode to +the MACsec interface configuration. + +**R1** + +```none +set interfaces macsec macsec1 address '192.0.2.1/24' +set interfaces macsec macsec1 address '2001:db8::1/64' +set interfaces macsec macsec1 security cipher 'gcm-aes-128' +set interfaces macsec macsec1 security encrypt +set interfaces macsec macsec1 security static key 'ddd6f4a7be4d8bbaf88b26f10e1c05f7' +set interfaces macsec macsec1 security static peer R2 mac 00:11:22:33:44:02 +set interfaces macsec macsec1 security static peer R2 key 'eadcc0aa9cf203f3ce651b332bd6e6c7' +set interfaces macsec macsec1 source-interface 'eth1' +``` + +**R2** + +```none +set interfaces macsec macsec1 address '192.0.2.2/24' +set interfaces macsec macsec1 address '2001:db8::2/64' +set interfaces macsec macsec1 security cipher 'gcm-aes-128' +set interfaces macsec macsec1 security encrypt +set interfaces macsec macsec1 security static key 'eadcc0aa9cf203f3ce651b332bd6e6c7' +set interfaces macsec macsec1 security static peer R1 mac 00:11:22:33:44:01 +set interfaces macsec macsec1 security static peer R1 key 'ddd6f4a7be4d8bbaf88b26f10e1c05f7' +set interfaces macsec macsec1 source-interface 'eth1' +``` + +## MACsec over WAN + +MACsec offers an alternative to traditional tunneling solutions by securing +Layer 2 with integrity, origin authentication, and optional encryption. + +While typically deployed between hosts and access switches, MACsec can also +secure traffic over a WAN. In the following example, we combine VXLAN (for +transport) and MACsec (for security) to create a secure tunnel between two +sites. + +**R1 MACsec01** + +```none +set interfaces macsec macsec1 address '192.0.2.1/24' +set interfaces macsec macsec1 address '2001:db8::1/64' +set interfaces macsec macsec1 security cipher 'gcm-aes-128' +set interfaces macsec macsec1 security encrypt +set interfaces macsec macsec1 security static key 'ddd6f4a7be4d8bbaf88b26f10e1c05f7' +set interfaces macsec macsec1 security static peer SEC02 key 'eadcc0aa9cf203f3ce651b332bd6e6c7' +set interfaces macsec macsec1 security static peer SEC02 mac '00:11:22:33:44:02' +set interfaces macsec macsec1 source-interface 'vxlan1' +set interfaces vxlan vxlan1 mac '00:11:22:33:44:01' +set interfaces vxlan vxlan1 remote '10.1.3.3' +set interfaces vxlan vxlan1 source-address '172.16.100.1' +set interfaces vxlan vxlan1 vni '10' +set protocols static route 10.1.3.3/32 next-hop 172.16.100.2 +``` + +**R2 MACsec02** + +```none +set interfaces macsec macsec1 address '192.0.2.2/24' +set interfaces macsec macsec1 address '2001:db8::2/64' +set interfaces macsec macsec1 security cipher 'gcm-aes-128' +set interfaces macsec macsec1 security encrypt +set interfaces macsec macsec1 security static key 'eadcc0aa9cf203f3ce651b332bd6e6c7' +set interfaces macsec macsec1 security static peer SEC01 key 'ddd6f4a7be4d8bbaf88b26f10e1c05f7' +set interfaces macsec macsec1 security static peer SEC01 mac '00:11:22:33:44:01' +set interfaces macsec macsec1 source-interface 'vxlan1' +set interfaces vxlan vxlan1 mac '00:11:22:33:44:02' +set interfaces vxlan vxlan1 remote '10.1.2.2' +set interfaces vxlan vxlan1 source-address '172.16.100.2' +set interfaces vxlan vxlan1 vni '10' +set protocols static route 10.1.2.2/32 next-hop 172.16.100.1 +``` diff --git a/docs/configuration/interfaces/md-openvpn-examples.md b/docs/configuration/interfaces/md-openvpn-examples.md new file mode 100644 index 00000000..817e6868 --- /dev/null +++ b/docs/configuration/interfaces/md-openvpn-examples.md @@ -0,0 +1,769 @@ +# Site-to-site + +:::{todo} +Convert raw command blocks in this file to cfgcmd/opcmd directives for command coverage tracking. +::: + +OpenVPN is popular for client-server setups, but its site-to-site mode is less common and often not supported by router appliances. Despite limited support, it is effective for quickly establishing tunnels between routers. + +As of VyOS 1.4, OpenVPN site-to-site mode can use either pre-shared keys or x.509 certificates. + +Pre-shared key mode is now deprecated and will be removed from future OpenVPN versions. VyOS will also discontinue support for this option because pre-shared keys are significantly less secure than TLS. + +We will configure OpenVPN with self-signed certificates, and then discuss the legacy pre-shared key mode. + +In both cases, we will use the following settings: + +- The public IP address of the local VPN endpoint is 198.51.100.10. +- The public IP address of the remote VPN endpoint is 203.0.113.11. +- The tunnel uses 10.255.1.1 for the local IP address and 10.255.1.2 for the remote IP address. +- The local site has a subnet of 10.0.0.0/16. +- The remote site has a subnet of 10.1.0.0/16. +- The official OpenVPN port 1194 is reserved for client VPN. For site-to-site VPN, port 1195 is used. +- The `persistent-tunnel` directive allows us to configure tunnel-related attributes, such as firewall policy, as we would on any standard network interface. +- If known, the remote router\'s IP address can be configured using the `remote-host` directive. If unknown, it can be omitted. We assume the remote router has a dynamic IP address. + +![](/_static/images/openvpn_site2site_diagram.webp) + +## Set up site-to-site certificates + +Deploying a complete Public Key Infrastructure (PKI) with a Certificate Authority (CA) would overcomplicate site-to-site OpenVPN setups, which are primarily designed for simplicity. To keep their configuration simple without compromising security, VyOS 1.4 and later lets you verify self-signed certificates using certificate fingerprints. + +Generate a self-signed certificate on each router, preferably using the Elliptic Curve (EC) type. In configuration mode, run the following command: `run generate pki certificate self-signed install `. This adds the certificate to the configuration session\'s `pki` subtree. Review and commit the changes. + +``` none +vyos@vyos# run generate pki certificate self-signed install openvpn-local +Enter private key type: [rsa, dsa, ec] (Default: rsa) ec +Enter private key bits: (Default: 256) +Enter country code: (Default: GB) +Enter state: (Default: Some-State) +Enter locality: (Default: Some-City) +Enter organization name: (Default: VyOS) +Enter common name: (Default: vyos.io) +Do you want to configure Subject Alternative Names? [y/N] +Enter how many days certificate will be valid: (Default: 365) +Enter certificate type: (client, server) (Default: server) +Note: If you plan to use the generated key on this router, do not encrypt the private key. +Do you want to encrypt the private key with a passphrase? [y/N] +2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. +[edit] + +vyos@vyos# compare +[pki] ++ certificate openvpn-local { ++ certificate "MIICJTCCAcugAwIBAgIUMXLfRNJ5iOjk/uAZqUe4phW8MdgwCgYIKoZIzj0EAwIwVzELMAkGA1UEBhMCR0IxEzARBgNVBAgMClNvbWUtU3RhdGUxEjAQBgNVBAcMCVNvbWUtQ2l0eTENMAsGA1UECgwEVnlPUzEQMA4GA1UEAwwHdnlvcy5pbzAeFw0yMzA5MDcyMTQzMTNaFw0yNDA5MDYyMTQzMTNaMFcxCzAJBgNVBAYTAkdCMRMwEQYDVQQIDApTb21lLVN0YXRlMRIwEAYDVQQHDAlTb21lLUNpdHkxDTALBgNVBAoMBFZ5T1MxEDAOBgNVBAMMB3Z5b3MuaW8wWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAASp7D0vE3SKSAWAzr/lw9Eq9Q89r247AJR6ec/GT26AIcVA1bsongV1YaWvRwzTPC/yi5pkzV/PcT/WU7JQIyMWo3UwczAMBgNVHRMBAf8EAjAAMA4GA1UdDwEB/wQEAwIHgDATBgNVHSUEDDAKBggrBgEFBQcDATAdBgNVHQ4EFgQUBrAxRdFppdG/UBRdo7qNyHutaTQwHwYDVR0jBBgwFoAUBrAxRdFppdG/UBRdo7qNyHutaTQwCgYIKoZIzj0EAwIDSAAwRQIhAI2+8C92z9wTcTWkQ/goRxs10EBC+h78O+vgo9k97z5iAiBSeqfaVr5taQTS31+McGTAK3cYWNTg0DlOBI8aKO2oRg==" ++ private { ++ key "MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQgtOeEb0dMb5P/2Exi09WWvk6Cvz0oOBoDuP68ZimS2LShRANCAASp7D0vE3SKSAWAzr/lw9Eq9Q89r247AJR6ec/GT26AIcVA1bsongV1YaWvRwzTPC/yi5pkzV/PcT/WU7JQIyMW" ++ } ++ } + +[edit] + +vyos@vyos# commit +``` + +You do **not** need to copy the certificate to the other router. Instead, retrieve its SHA-256 fingerprint. Since OpenVPN currently supports only SHA-256 fingerprints, use the following command: + +``` none +vyos@vyos# run show pki certificate openvpn-local fingerprint sha256 +5C:B8:09:64:8B:59:51:DC:F4:DF:2C:12:5C:B7:03:D1:68:94:D7:5B:62:C2:E1:83:79:F1:F0:68:B2:81:26:79 +``` + +::::{note} +Certificate names are arbitrary. While `openvpn-local` and `openvpn-remote` are used here, you may choose any names. +:::: + +Repeat the procedure on the other router. + +## Set up site-to-site OpenVPN + +Local configuration: + +``` none +Configure the tunnel: + +set interfaces openvpn vtun1 mode site-to-site +set interfaces openvpn vtun1 protocol udp +set interfaces openvpn vtun1 persistent-tunnel +set interfaces openvpn vtun1 remote-host '203.0.113.11' # Public IP of the other side +set interfaces openvpn vtun1 local-port '1195' +set interfaces openvpn vtun1 remote-port '1195' +set interfaces openvpn vtun1 local-address '10.255.1.1' # Local IP of vtun interface +set interfaces openvpn vtun1 remote-address '10.255.1.2' # Remote IP of vtun interface +set interfaces openvpn vtun1 tls certificate 'openvpn-local' # The self-signed certificate +set interfaces openvpn vtun1 tls peer-fingerprint # The output of 'run show pki certificate fingerprint sha256' on the remote router +set interfaces openvpn vtun1 tls role active +``` + +Remote configuration: + +``` none +set interfaces openvpn vtun1 mode site-to-site +set interfaces openvpn vtun1 protocol udp +set interfaces openvpn vtun1 persistent-tunnel +set interfaces openvpn vtun1 remote-host '198.51.100.10' # Pub IP of other site +set interfaces openvpn vtun1 local-port '1195' +set interfaces openvpn vtun1 remote-port '1195' +set interfaces openvpn vtun1 local-address '10.255.1.2' # Local IP of vtun interface +set interfaces openvpn vtun1 remote-address '10.255.1.1' # Remote IP of vtun interface +set interfaces openvpn vtun1 tls certificate 'openvpn-remote' # The self-signed certificate +set interfaces openvpn vtun1 tls peer-fingerprint # The output of 'run show pki certificate fingerprint sha256 on the local router +set interfaces openvpn vtun1 tls role passive +``` + + +## Set up pre-shared keys + +Before VyOS 1.4, site-to-site OpenVPN without PKI required pre-shared keys. This option is still available but is deprecated and will be removed in future releases. If you need to set up a tunnel to an older VyOS version or a system with older OpenVPN, you still need to use pre-shared keys. + +First, generate a key by running `run generate pki openvpn shared-secret install ` in configuration mode. You can use any name; in this example, we use `s2s`. + +``` none +vyos@local# run generate pki openvpn shared-secret install s2s +2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. +[edit] +vyos@local# compare +[pki openvpn shared-secret] ++ s2s { ++ key "7c73046a9da91e874d31c7ad894a32688cda054bde157c64270f28eceebc0bb2f44dbb70335fad45148b0456aaa78cb34a34c0958eeed4f75e75fd99ff519ef940f7029a316c436d2366a2b0fb8ea1d1c792a65f67d10a461af83ef4530adc25d1c872de6d9c7d5f338223d1f3b66dc3311bbbddc0e05228c47b91c817c721aadc7ed18f0662df52ad14f898904372679e3d9697d062b0869d12de47ceb2e626fa12e1926a3119be37dd29c9b0ad81997230f4038926900d5edb78522d2940cfe207f8e2b948e0d459fa137ebb18064ac5982b28dd1899020b4f2b082a20d5d4eb65710fbb1e62b5e061df39620267eab429d3eedd9a1ae85957457c8e4655f3" ++ version "1" ++ } + +[edit] + +vyos@local# commit +[edit] +``` + +Next, install the key on the remote router: + +``` none +vyos@remote# set pki openvpn shared-secret s2s key +``` + +Finally, configure the key in your OpenVPN interface settings: + +``` none +set interfaces openvpn vtun1 shared-secret-key s2s +``` + + +## Set up firewall exceptions + +To allow OpenVPN traffic to pass through the WAN interface, create a firewall exception: + +``` none +set firewall ipv4 name OUTSIDE_LOCAL rule 10 action 'accept' +set firewall ipv4 name OUTSIDE_LOCAL rule 10 description 'Allow established/related' +set firewall ipv4 name OUTSIDE_LOCAL rule 10 state 'established' +set firewall ipv4 name OUTSIDE_LOCAL rule 10 state 'related' +set firewall ipv4 name OUTSIDE_LOCAL rule 20 action 'accept' +set firewall ipv4 name OUTSIDE_LOCAL rule 20 description 'OpenVPN_IN' +set firewall ipv4 name OUTSIDE_LOCAL rule 20 destination port '1195' +set firewall ipv4 name OUTSIDE_LOCAL rule 20 log +set firewall ipv4 name OUTSIDE_LOCAL rule 20 protocol 'udp' +``` + +Apply the OUTSIDE_LOCAL firewall group to the WAN interface and to the input filter for traffic destined for the router itself: + +``` none +set firewall ipv4 input filter rule 10 action 'jump' +set firewall ipv4 input filter rule 10 inbound-interface name eth0 +set firewall ipv4 input filter rule 10 jump-target OUTSIDE_LOCAL +``` + +Static routing: + +Configure static routes by referencing the tunnel interface. For example, if the local router\'s network is `10.0.0.0/16` and the remote router\'s network is `10.1.0.0/16`, define the routes as follows: + +Local configuration: + +``` none +set protocols static route 10.1.0.0/16 interface vtun1 +``` + +Remote configuration: + +``` none +set protocols static route 10.0.0.0/16 interface vtun1 +``` + +As with standard Ethernet interfaces, you can apply firewall policies to the tunnel interface for input, output, and forward directions. + +If you use multiple tunnels, OpenVPN must distinguish between them beyond just the pre-shared key. To achieve this, assign either unique IP addresses or unique ports to each tunnel. + +Verify OpenVPN status using the show openvpn operational commands. + +``` none +vyos@vyos:~$ show openvpn site-to-site + +OpenVPN status on vtun1 + +Client CN Remote Host Tunnel IP Local Host TX bytes RX bytes Connected Since +----------- ----------------- ----------- ------------ ---------- ---------- ----------------- +N/A 10.110.12.54:1195 N/A N/A 504.0 B 656.0 B N/A +``` + + +### Server-client + +In OpenVPN's server-client mode, the server acts as a central hub, allowing multiple clients to connect and securely route their traffic or access a private network. Multi-client server is the most popular OpenVPN mode for routers. + +## Set up server-client certificates + +Server-client mode always uses x.509 authentication and therefore requires a PKI setup. The PKI utility now simplifies the creation of Certificate Authorities (CAs), server and client certificates, and Diffie-Hellman keys directly in VyOS using configuration or operational mode commands. + +On the server, generate all certificates by running the following commands in configuration mode. The certificates will be added to the configuration session\'s PKI subtree. + +Certificate Authority (CA): + +``` none +vyos@vyos# run generate pki ca install ca-1 +Enter private key type: [rsa, dsa, ec] (Default: rsa) +Enter private key bits: (Default: 2048) +Enter country code: (Default: GB) +Enter state: (Default: Some-State) +Enter locality: (Default: Some-City) +Enter organization name: (Default: VyOS) +Enter common name: (Default: vyos.io) ca-1 +Enter how many days certificate will be valid: (Default: 1825) +Note: If you plan to use the generated key on this router, do not encrypt the private key. +Do you want to encrypt the private key with a passphrase? [y/N] +2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. +[edit] +vyos@vyos# compare +[pki] ++ ca ca-1 { ++ certificate "MIIDlzCCAn+gAwIBAgIUQW7AtPu0Qzp7VzT0TyYx83/ME8swDQYJKoZIhvcNAQELBQAwVDELMAkGA1UEBhMCR0IxEzARBgNVBAgMClNvbWUtU3RhdGUxEjAQBgNVBAcMCVNvbWUtQ2l0eTENMAsGA1UECgwEVnlPUzENMAsGA1UEAwwEY2EtMTAeFw0yNTA2MTExMTIyMjJaFw0zMDA2MTAxMTIyMjJaMFQxCzAJBgNVBAYTAkdCMRMwEQYDVQQIDApTb21lLVN0YXRlMRIwEAYDVQQHDAlTb21lLUNpdHkxDTALBgNVBAoMBFZ5T1MxDTALBgNVBAMMBGNhLTEwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDi+v6i241T9ABxq1ngjWxDQITkqjV0nq2Jb3HSSuQpXRCu7DWdQZlbvnMHnkV/WTL0RNgkhS4iV/WYhE+bLihwiZ0GTeQnUd1QJSkusFROX46w6kKXYUR5IQtcBC+vdky8PESynPd+DXsJn5X9JTWqDeviUAQz/ZjDzWk+71MBCqa+Zps1zpIjK0ywn7pR/HnDrxJOQXlBMNgvbv8U3IAZ2jJp0jTB8TnuDtWSA+XZejMm/EN/AWUQyliX6OJFSCIhBL2BZ9lmVms4/HkRpbd50k3vvCoz+lAOEE6VsH0fEdLC3lZ+CtXZ7kjp2wdWWuSs5ggIJYZZkixsCisbtEmbAgMBAAGjYTBfMA8GA1UdEwEB/wQFMAMBAf8wDgYDVR0PAQH/BAQDAgGGMB0GA1UdJQQWMBQGCCsGAQUFBwMCBggrBgEFBQcDATAdBgNVHQ4EFgQUAG9lvr7AzJ/y4vY/XlWxXru+6m0wDQYJKoZIhvcNAQELBQADggEBAKsu4eZa8Fha9aKfuKqlGQHPpEFfVDaVJmebw0uMw+b5Y8EpBxzZrgbqbk3Mty8pBjNa9jkZzph04gHN4pR6kg3iQlUKGxZUfsB9ZUjKhkgNdUI9zq1323MKEvuIuYdt61DCfBHwY6Xax5Ge+BahR2bXdPaQH452/+xMTqkukkpLbioTeIDg6FCU2HYPY5emDF5DDZAZWXtTqi0zdT3Y6FqiTvs5VuWwXCcp+HM+Lwe1/VVJhwi4CHTq0CKWnQIH5blYjmyxzRBlrlZm4ntWlL5Mtepa1A3DJirY4kw/SqMAAh/Q9lh41JzBc8epf+OdnOzK55YmtmctGO2o+NBCFi0=" ++ private { ++ key "MIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQDi+v6i241T9ABxq1ngjWxDQITkqjV0nq2Jb3HSSuQpXRCu7DWdQZlbvnMHnkV/WTL0RNgkhS4iV/WYhE+bLihwiZ0GTeQnUd1QJSkusFROX46w6kKXYUR5IQtcBC+vdky8PESynPd+DXsJn5X9JTWqDeviUAQz/ZjDzWk+71MBCqa+Zps1zpIjK0ywn7pR/HnDrxJOQXlBMNgvbv8U3IAZ2jJp0jTB8TnuDtWSA+XZejMm/EN/AWUQyliX6OJFSCIhBL2BZ9lmVms4/HkRpbd50k3vvCoz+lAOEE6VsH0fEdLC3lZ+CtXZ7kjp2wdWWuSs5ggIJYZZkixsCisbtEmbAgMBAAECggEAZdykF6wV8Z4n8NsoG4j8E/ZJbWEhWjO3x1y3JNutJw735LhmmysMSsreToXtxGfgYRTgNwt5l7oHoqmGHCsLxO1NBb5A7JBllIkIwUYqn31syOJofg0NsJpuwZ2zVLfvWe5mGg4tV2lvVPNEWXWwbp+Ow2KLcFWXkA+H8tFuW6F2mH3ntYlIi/WiCNjsEotNx8Kk7OVwt43DbkN/rbF5lxquuLedaSspOHuhIAOfZB5ZySfqohQalSAaguVD66rGPMrerZ2Vc7B1iJ6Mn/KZrSaQeHwyWrwDDHdzVwG9waydevtGTVO0dvH4etWnRypDx8p1FPJJKD4XVcsl3rR6oQKBgQD497Ep2RJcbNnKVj+kNXGriSGmyRSp6CL61KotepzgucK0RtGMeFJge56/otMHMAxIOcDMX6vRn2MB2pqVqwqUBQy6JfLrSemdpIjMN9xlX6Dw3BWP39SdewZ896/Eo0Q1ythMj1ORp+u3PqOlSa14Cy9aPwDWmNy2deD68YDnsQKBgQDpZE/T84BMQ0FzL6NRijZRzR6Dc775hRfmmSTYI0KqpG0gXNSc5UgrWSLN5H7fnx36mT01P7UkgXCInV0AlJOfkt4a8QTqM1Fh/rZbLLWpQE55S6Fs28GDiFYl2kvZT/TtxhA/E0POf/YXl/8KITS7ZVAZxE8rxBe1hVUfDbnlCwKBgQDeWUguGaGeTdCMNk8MNnbYPdaCAB+mRp3G6ls51sF4qi5Lltva2jKn3H/AoohZaP3vGzUm0WLACdsAct2QQXtnCsN9FBtJK2+qzKEn0dPR7X/s3IGdRse6BX+b6BFgSnfGmuxmI7L86L1JoHXCTnTQOx0FOjNjdI3ZnplZRIpdYQKBgFJacASU9l9yl+SiGZnLEDG7FBpEPE3lVbKrtSGDB6IY1NzHhMo76URKdop6Jv6XMcfcTIm+ihdwiRnblRaAVrrG4xJUm2xcYUoXy5bOZudq5oXMVxCHVngoImXG6l6q5P0Fl3P6Q0HZSye2HWsgnm/FZwdAisMhtU/61TdY65BTAoGBAM4jKeImiXta5lz1RgNiW/TPhft3UbOLj3TbzchNCNAamqCv4Tmh9YKB2d/mz2hNxbnAGe2cYn4iRYKcjJLMZ0UfBL2WxlrgQYQPPGzSD0fH1pLIXPohpBZpsGqNR3Nc8Jd+Uw3IiIJ2oxPCOPTOJsklNB0Xf1AlUUagB16bhhZZ" ++ } ++ } + +[edit] +vyos@vyos# commit +``` + +Server certificate: + +``` none +vyos@vyos# run generate pki certificate sign ca-1 install srv-1 +Do you already have a certificate request? [y/N] N +Enter private key type: [rsa, dsa, ec] (Default: rsa) +Enter private key bits: (Default: 2048) +Enter country code: (Default: GB) +Enter state: (Default: Some-State) +Enter locality: (Default: Some-City) +Enter organization name: (Default: VyOS) +Enter common name: (Default: vyos.io) srv-1 +Do you want to configure Subject Alternative Names? [y/N] +Enter how many days certificate will be valid: (Default: 365) +Enter certificate type: (client, server) (Default: server) server +Note: If you plan to use the generated key on this router, do not encrypt the private key. +Do you want to encrypt the private key with a passphrase? [y/N] +2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. +[edit] +vyos@vyos# compare +[pki certificate] ++ srv-1 { ++ certificate "MIIDrDCCApSgAwIBAgIULpu+qZjfG01kUI58XNmqXbQC3qQwDQYJKoZIhvcNAQELBQAwVDELMAkGA1UEBhMCR0IxEzARBgNVBAgMClNvbWUtU3RhdGUxEjAQBgNVBAcMCVNvbWUtQ2l0eTENMAsGA1UECgwEVnlPUzENMAsGA1UEAwwEY2EtMTAeFw0yNTA2MTExMTMxMDJaFw0yNjA2MTExMTMxMDJaMFUxCzAJBgNVBAYTAkdCMRMwEQYDVQQIDApTb21lLVN0YXRlMRIwEAYDVQQHDAlTb21lLUNpdHkxDTALBgNVBAoMBFZ5T1MxDjAMBgNVBAMMBXNydi0xMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAysTrMfVH63aVidJT7bIf+zLwkLse07nGsv4aliGEbufr239RBHV4Jn8LbQ+nB/8mhYGjNY4OnZ7NYz3FU/iglo8qFtaZ26mWtPWpv2xW1F8JAEK7l5BAg42cBucxiIZFeRm+jkE6VN1bcNU0utnn3sbCwZMyH6pS9k08G1qrrFLA7ZFhv5AmgJcODmO8sigSAu7rRS/6O3eO6ICnVjvIfHLb+9DKKUEffHzFV8RrkqVCGmgisz9fF+j1Rvg9s+ylNc2lZJTbb1XnzixvSRro4t9I3uIWdpJ0iOu09YiTXGQgH9ER6V3rFiX00RdSiSXf+MJCV64hC1msg+8V3Nrw9QIDAQABo3UwczAMBgNVHRMBAf8EAjAAMA4GA1UdDwEB/wQEAwIHgDATBgNVHSUEDDAKBggrBgEFBQcDATAdBgNVHQ4EFgQUzH0h4vBxma89HF9rUQ+DW052c5swHwYDVR0jBBgwFoAUAG9lvr7AzJ/y4vY/XlWxXru+6m0wDQYJKoZIhvcNAQELBQADggEBAI/Cyd0y7AJ7wY3yRssCud2iJAl9/ZjgxzXOUo6ibawYIYOnSf9tS3eD4CIH4BgppDXoJZ/qEA4WvIsLx3yvnyOxiqyk3TQmKIZ27VJH+yQkgzPeiKrHn1pCXBKEb1/jlT8Ozu4Lmn/oFwDH6nk8toxI8DM+qsTxqUFlTA3ea9yaRtxeNPMWJdaxZSUYGVSZL0wVKw5ZuQ1Gn7vGVApWlYDKYbMozCuZUG1q8wMzFBRa7x0anvh5hM4bksLz+Y1ujCS8f8b4Xtb8KIdFrZtTvtl97crv62bN05VueAcbwtYbIBNWNoT/CvmqV7k3uPg95GYSNddFqEMbQHoyd8hdDCo=" ++ private { ++ key "MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQDKxOsx9UfrdpWJ0lPtsh/7MvCQux7Tucay/hqWIYRu5+vbf1EEdXgmfwttD6cH/yaFgaM1jg6dns1jPcVT+KCWjyoW1pnbqZa09am/bFbUXwkAQruXkECDjZwG5zGIhkV5Gb6OQTpU3Vtw1TS62efexsLBkzIfqlL2TTwbWqusUsDtkWG/kCaAlw4OY7yyKBIC7utFL/o7d47ogKdWO8h8ctv70MopQR98fMVXxGuSpUIaaCKzP18X6PVG+D2z7KU1zaVklNtvVefOLG9JGuji30je4hZ2knSI67T1iJNcZCAf0RHpXesWJfTRF1KJJd/4wkJXriELWayD7xXc2vD1AgMBAAECggEACsUk3PVzSX11+ekTDigM7NHK11UpEQPoGu/GR70mBKIK9BCyI/N9W0YaPEO9kn4p9KNrINgXzKV3sVLBnXEyTmzyRl5Fs9YxLBF0X7eIcSVPHBVvU2CVHKez5uX2ypKfNAx7A6FRUNqlFbwtXdNfLoUOKSwBWI86ctytWaKaRb/TTSGQkaP/z/cwIsXOLfG9m6iFkw98ShUzalrUWNo/4fJKlO1+DvXVYE9sv9rjD8J7DtAbr5KykQ5n0AAlZTCWQ7jwMybSnjjY9ypZUms0l17raJrfhrdbWayc6xMDvtrmNIDebkF+J7cHU06aEV+yQXV/7yjyZgUSM2ANcHMdzQKBgQDmTi5tUeaj1JUSl9lAP/XUzcElw2tcU1B8qpX69J4ofjTNgj5okLWQZVIy1UyAfLOI3LJbHTBUtSvedhH0VaMulq99NXs5qnbPGG3//RBAc0wKhJknB5Qv0D3FxMI14kMO6jzPly+aIGEk4dTtHvZuHbbVHbKSZ5MMouLyT+SS7wKBgQDhZETARZ0MazeWRaPJwdkjlfNcqqcsnDicdcppCkcDCjeLxkVPZc8ej37rshOvw2Pf1D0PddGyOhJoWCWA8QE2LQoDHLaDnQ0L6aQ3yjN5Gxx9RCDFi3Zuat/mPcv3tFO7uUmeYvRC5fGYrghq29NADmUefOopAc06Izd4A3iqWwKBgQC1uPrpR7a1jwgRo7/I8q8HO1MseQY903+u3ut5GYuyZ+NCRYL4/zZEua4ibivvNnZzh7E0M9PvAwWag4+nO+uG11+hbJHO7rLQtnYVh5lLQa6+neI66cAD+kzDwH1+BwriufFB3Amzk9kTQR7B+6x3NvsNLmG5JADj96Mbj+7MAQKBgFIevEXplyzdK6WevexWqoyip8aNjtdcG+w1pofa7MCYymAs3zfseihCVBYADdguModsxsqJPNvY+Lf31cJDDRP2GP3FSmJtqEE84U5KZ7KqRBkH54DSLVZRrj4vKc+YbiGpgr8ogqKVMQ9V6U81xKREGmefT5mdRG74Qc+CREadAoGAFtdsH5js1yFEeGFad4BZJ69grEavD3pNCfIe9oIPtXvvFdzxd+QbKgqFf3JMJp/HYi8A0iv/i4mzf00KXzF4JU7bIJYrUVlk/w8x77gzDRIphsPqpMBJkTI0jisQHZKWNEe7IbmM/dWW2S4jvCkrhB7F5Szf72Q+j/lPbfx2g/8=" ++ } ++ } + +[edit] +vyos@vyos# commit +``` + +Diffie-Hellman key: + +``` none +vyos@vyos# run generate pki dh install dh-1 +Enter DH parameters key size: (Default: 2048) +Generating parameters... +1 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. +[edit] +vyos@vyos# compare +[pki] ++ dh dh-1 { ++ parameters "MIIBCAKCAQEAp25kxwZeLZ7wcbRii5E5RD4uWCUOBxarzKEE0msa84omh5nZ9dv/4bfJw4gIXlA2+sGc2lLV/jajZminMryiSwJdisyVuUdOB7sJWZwrzHBAY0qFbNyaRMVJBar2xVm+XcKd3A2eNTEgn10G7rPPvf6CJ5isUKFaKT8ymUv+mI0upLneYdGs8/yS3sAojzeulCf49fa5SiaGCcZZkdOI3Nby1u/ZG4okqJ2wE2c2hRVLs1k5qrrono0OF4Dh0B91ihnywRfp1xPYeqpiln+OPh+PPgTuBxkz4VxwRDoQ+NhVr/LOCb3vbhnyFisxI0w4r3109cA3QiDmo1L14aKl1wIBAg==" ++ } + +[edit] +vyos@vyos# commit +``` + +Client certificate: + +``` none +vyos@vyos:~$ generate pki certificate sign ca-1 install client1 +Do you already have a certificate request? [y/N] N +Enter private key type: [rsa, dsa, ec] (Default: rsa) +Enter private key bits: (Default: 2048) +Enter country code: (Default: GB) +Enter state: (Default: Some-State) +Enter locality: (Default: Some-City) +Enter organization name: (Default: VyOS) +Enter common name: (Default: vyos.io) client1 +Do you want to configure Subject Alternative Names? [y/N] +Enter how many days certificate will be valid: (Default: 365) +Enter certificate type: (client, server) (Default: server) client +Note: If you plan to use the generated key on this router, do not encrypt the private key. +Do you want to encrypt the private key with a passphrase? [y/N] +You are not in configure mode, commands to install manually from configure mode: +set pki certificate client1 certificate 'MIIDrjCCApagAwIBAgIUPvtffeYTdoOiHxu++wdrjHwwVX4wDQYJKoZIhvcNAQELBQAwVDELMAkGA1UEBhMCR0IxEzARBgNVBAgMClNvbWUtU3RhdGUxEjAQBgNVBAcMCVNvbWUtQ2l0eTENMAsGA1UECgwEVnlPUzENMAsGA1UEAwwEY2EtMTAeFw0yNTA2MTExMTQxMDlaFw0yNjA2MTExMTQxMDlaMFcxCzAJBgNVBAYTAkdCMRMwEQYDVQQIDApTb21lLVN0YXRlMRIwEAYDVQQHDAlTb21lLUNpdHkxDTALBgNVBAoMBFZ5T1MxEDAOBgNVBAMMB2NsaWVudDEwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQC9H6E6gm0PfXO1n/WoA9xlg89/bnScLmfztVDn1uyNn8epE6zAi2GWBhtj4ixLllIwLdkJ7L2mF3yUZtA1Q0oYbGIqTbnaZ37JydCygVGnlLT7UX9zfRfS3KebCIvIte7OyCmnUfVfFzdIsp+4LI3S2wX/9Vyn4UBAR8QQNbezRB3XPMk9gzULnuLhmEDP6GVcPq7RzGXoXUMqsCxfEOJBjej0y4ANKH07HGVVrfVRiY+zlGkM4TFjVuZKnEA0BO6dhOA0E+7gsIXsC06UzzatkjsyWHpb2/DOECIifBoYej9DITu8VxyyZmgaINHEn2gGb0LRHO7rvQapc+XZ2z9DAgMBAAGjdTBzMAwGA1UdEwEB/wQCMAAwDgYDVR0PAQH/BAQDAgeAMBMGA1UdJQQMMAoGCCsGAQUFBwMCMB0GA1UdDgQWBBQnUyqEzG+AqZzsdSud5MDqsOxiXTAfBgNVHSMEGDAWgBQAb2W+vsDMn/Li9j9eVbFeu77qbTANBgkqhkiG9w0BAQsFAAOCAQEAplItvZpoX/joG3QREu9tHVKwDTmXB2lwUM5G8iKPgd6D6oOILZMe2KuvWt12dcdEzUCGfJwJJ8M8R2WD0OmcLdFqvM/8UM1hYzUP2BCnFCLtElVD+b4wMlQNpdHqNbdckw8J4MLQlhUgu9rZAZ0XjWCprr+U50bX++vYRw7Un3Ds6ETEvjflm5WAPb2e0V1hhISPl8K+VXO7RAwxy0DHcDuR+YaD+hnNgMsJV3/QwA17Iy8x86RpOgqmesbt0U7e9Rmo81aVgiy/V4OCV7u6bPX03fmZNS8UwwJuRUlxkjO+epHNYB2cnOcjSkUxaIJ9Hv3tMWHQEtbVZsNYSOZozw==' +set pki certificate client1 private key 'MIIEvAIBADANBgkqhkiG9w0BAQEFAASCBKYwggSiAgEAAoIBAQC9H6E6gm0PfXO1n/WoA9xlg89/bnScLmfztVDn1uyNn8epE6zAi2GWBhtj4ixLllIwLdkJ7L2mF3yUZtA1Q0oYbGIqTbnaZ37JydCygVGnlLT7UX9zfRfS3KebCIvIte7OyCmnUfVfFzdIsp+4LI3S2wX/9Vyn4UBAR8QQNbezRB3XPMk9gzULnuLhmEDP6GVcPq7RzGXoXUMqsCxfEOJBjej0y4ANKH07HGVVrfVRiY+zlGkM4TFjVuZKnEA0BO6dhOA0E+7gsIXsC06UzzatkjsyWHpb2/DOECIifBoYej9DITu8VxyyZmgaINHEn2gGb0LRHO7rvQapc+XZ2z9DAgMBAAECggEAPS/Fhtt5k2BgFivZW3FcVc+OS0keGwV8hkFsGoXTZIKEIzSFWIn/mX0CUY90C0Rn9MRwiqB4PwssOAsHY6QQjdRK8irRbVK8l2ZeydHC7DfVUdXtKR0YnxTaePML3nTV/TqPF14Rx6EINtHrkLeBbu2DhGsKfhoHIoTVbvUiKLHa2TkGJOkhvjsyMSPKzUXa1AzLmu+UBIhRYpEPHj0SQUUJJnKgIb7mTR2fhJScHcKwsrPq6S8OpChvsYZ6zatgrTFz9tuhD4IjL7NBiYP45BwGaLIaQjph8yAJwwHWoOP+TTj5WYflkW6Uu8F9gC0ve6dPGPNEi2TUdirvAe4LYQKBgQD0UfAPm6tQg8pdkvfMBvYc21fk8zqmgcA4OtvDi60aXuv5jI5+faISvOG2JLuFhKIDOb5ZerzGvkN+LvWgzr9H7YdGZNNtwKgpS/MGqcuuHncTxWBAwYgKhf26a/tqFZRNurJ6GowxDiAcQEc1mWnmdngRa+dvvCwNbXvGVqfVEQKBgQDGKi447TqD76QfvRPn/fRSjM+QE1duk+XorEJ0HHIha5HV9kCrZdV/olGRjDLwPJO6JW7iE2FUsS9SsIrccFE/9P2ZUqfYP2wL5vNO5kAmoLLUl0gwqg1WnBTPJfXeKReTj2uGmOdEuuMPXpL/49hDuPViiE2Q4MGe2Z+oEYN/EwKBgHfQMuTEl2e9qaDn8OM6SrluC5V4fjunh6dLnfgwaCx1fk1702lOnQuJWzsiml9o4raoO6PP4AGqzphz2PsKSJ2ya1NnIJRDFXRjDYQoAn2Z7RViBsja36chfINObxXgDUFtHBdrK3LnFXIlR4aOfHOLh2grvWx7IDNZjIiAeH+xAoGAJlmFZnjqiRv4bDgAQTZRcSRVCvHjSsAOj0++8I+MutEBgSHN9B2aCsBT/tHeDcX7ZNvXsKLFhElh+iO2S+DkqHb2GRT47I2hkFAaqBtBMPiKgz/ftaNDP46nLEuRYHQdXu4zhfHTV+a/CHtqAWGLuddyjaYJNM96SQ6eqjzxcMcCgYAzdxOF2e27hIgo2ttjsROMGqW0/0r/HsKGKPnao7xHQNCAswTnBT+QGugPCe0NXjuxbySP7V1GeWMWF+WV5khtteWerT1/ELAC48NSDpaMxVa4GP8Q/0w6+ZyJty3UGbCYQzZZue81dU+42LUIaVJ4NAc2tYj3jD780udasawS6w==' +``` + +Manually copy the CA, client certificate, and Diffie-Hellman key to the client device, then commit them before configuring the OpenVPN interface. + +For more options, refer to {ref}`configuration/pki/index:pki`. + +## Set up server-client OpenVPN + +The following example demonstrates the most complicated scenario: each client acts as a router with its own subnet (e.g., an HQ and multiple branch offices). Simpler setups are subsets of it. + +In this scenario, the 10.23.1.0/24 network is used for client tunnel endpoints, and all client subnets belong to 10.23.0.0/20. Each client needs access to the 192.168.0.0/16 network. + +Server configuration: + +``` none +set interfaces openvpn vtun10 encryption data-ciphers 'aes256' +set interfaces openvpn vtun10 hash 'sha512' +set interfaces openvpn vtun10 local-host '172.18.201.10' +set interfaces openvpn vtun10 local-port '1194' +set interfaces openvpn vtun10 mode 'server' +set interfaces openvpn vtun10 persistent-tunnel +set interfaces openvpn vtun10 protocol 'udp' +set interfaces openvpn vtun10 server client client1 ip '10.23.1.10' +set interfaces openvpn vtun10 server client client1 subnet '10.23.2.0/25' +set interfaces openvpn vtun10 server domain-name 'vyos.net' +set interfaces openvpn vtun10 server max-connections '250' +set interfaces openvpn vtun10 server name-server '172.16.254.30' +set interfaces openvpn vtun10 server subnet '10.23.1.0/24' +set interfaces openvpn vtun10 server topology 'subnet' +set interfaces openvpn vtun10 tls ca-certificate ca-1 +set interfaces openvpn vtun10 tls certificate srv-1 +set interfaces openvpn vtun10 tls dh-params dh-1 +``` + +The configuration above uses the default 1194/UDP port, 256-bit AES encryption, SHA-512 for HMAC authentication, and the persistent-tunnel option. Persistent-tunnel is recommended as it keeps the TUN/TAP device active during connection resets or daemon reloads. Clients are identified by the CN attribute in their SSL certificates. + +To grant clients access to a specific network behind the router, use the push-route option to automatically install the appropriate route on each client. + +``` none +set interfaces openvpn vtun10 server push-route 192.168.0.0/16 +``` + +OpenVPN does not automatically create kernel routes for client subnets when clients connect; it only uses client-subnet association internally. Therefore, you must manually create a route to the 10.23.0.0/20 network: + +``` none +set protocols static route 10.23.0.0/20 interface vtun10 +``` + + +## Set up OpenVPN client + +VyOS can operate not only as an OpenVPN site-to-site peer or a server for multiple clients, but also as an OpenVPN client. Any VyOS OpenVPN interface can be configured to connect to another VyOS or third-party OpenVPN server. + +Client configuration: + +``` none +set interfaces openvpn vtun10 encryption data-ciphers 'aes256' +set interfaces openvpn vtun10 hash 'sha512' +set interfaces openvpn vtun10 mode 'client' +set interfaces openvpn vtun10 persistent-tunnel +set interfaces openvpn vtun10 protocol 'udp' +set interfaces openvpn vtun10 remote-host '172.18.201.10' +set interfaces openvpn vtun10 remote-port '1194' +set interfaces openvpn vtun10 tls ca-certificate ca-1 +set interfaces openvpn vtun10 tls certificate client1 +``` + + +## Verification + +Check the tunnel status: + +``` none +vyos@vyos:~$ show openvpn server + +OpenVPN status on vtun10 + +Client CN Remote Host Tunnel IP Local Host TX bytes RX bytes Connected Since +----------- ------------------ ----------- ---------------- ---------- ---------- ------------------- +client1 172.16.12.54:33166 10.23.1.10 172.18.201.10:1194 3.4 KB 3.4 KB 2024-06-11 12:07:25 +``` + + +### Server bridge + +In Ethernet bridging configurations, an OpenVPN interface operating in server mode with the device type set to TAP can be added to a bridge. By encapsulating entire Ethernet frames (up to 1514 bytes) rather than just IP packets (up to 1500 bytes), this setup enables clients to transmit Layer 2 frames through the OpenVPN tunnel. + +The following is a basic configuration example: + +Server side: + +``` none +set interfaces bridge br10 member interface eth1.10 +set interfaces bridge br10 member interface vtun10 +set interfaces openvpn vtun10 device-type 'tap' +set interfaces openvpn vtun10 encryption data-ciphers 'aes192' +set interfaces openvpn vtun10 hash 'sha256' +set interfaces openvpn vtun10 local-host '172.18.201.10' +set interfaces openvpn vtun10 local-port '1194' +set interfaces openvpn vtun10 mode 'server' +set interfaces openvpn vtun10 server bridge gateway '10.10.0.1' +set interfaces openvpn vtun10 server bridge start '10.10.0.100' +set interfaces openvpn vtun10 server bridge stop '10.10.0.200' +set interfaces openvpn vtun10 server bridge subnet-mask '255.255.255.0' +set interfaces openvpn vtun10 server topology 'subnet' +set interfaces openvpn vtun10 tls ca-certificate 'ca-1' +set interfaces openvpn vtun10 tls certificate 'srv-1' +set interfaces openvpn vtun10 tls dh-params 'dh-1' +``` + +Client side: + +``` none +set interfaces openvpn vtun10 device-type 'tap' +set interfaces openvpn vtun10 encryption data-ciphers 'aes192' +set interfaces openvpn vtun10 hash 'sha256' +set interfaces openvpn vtun10 mode 'client' +set interfaces openvpn vtun10 protocol 'udp' +set interfaces openvpn vtun10 remote-host '172.18.201.10' +set interfaces openvpn vtun10 remote-port '1194' +set interfaces openvpn vtun10 tls ca-certificate 'ca-1' +set interfaces openvpn vtun10 tls certificate 'client-1' +``` + + +### Server LDAP authentication + +## LDAP + +Enterprise installations usually include a directory service to centralize employee password management. VyOS and OpenVPN support using LDAP and Active Directory as a single user backend. + +Authentication is performed by the `openvpn-auth-ldap.so` plugin, included with every VyOS installation. To use it, you must create a dedicated configuration file. +**Best practice:** Store the configuration file in the `/config` directory to ensure it is preserved after image updates. + +``` none +set interfaces openvpn vtun0 openvpn-option "--plugin /usr/lib/openvpn/openvpn-auth-ldap.so /config/auth/ldap-auth.config" +``` + +A sample configuration file is shown below: + +``` none + +# LDAP server URL +URL ldap://ldap.example.com +# Bind DN (If your LDAP server doesn't support anonymous binds) +BindDN cn=LDAPUser,dc=example,dc=com +# Bind Password password +Password S3cr3t +# Network timeout (in seconds) +Timeout 15 + + + +# Base DN +BaseDN "ou=people,dc=example,dc=com" +# User Search Filter +SearchFilter "(&(uid=%u)(objectClass=shadowAccount))" +# Require Group Membership - allow all users +RequireGroup false + +``` + + +### Active Directory + +A sample configuration file is shown below: + +``` none + + # LDAP server URL + URL ldap://dc01.example.com + # Bind DN (If your LDAP server doesn’t support anonymous binds) + BindDN CN=LDAPUser,DC=example,DC=com + # Bind Password + Password mysecretpassword + # Network timeout (in seconds) + Timeout 15 + # Enable Start TLS + TLSEnable no + # Follow LDAP Referrals (anonymously) + FollowReferrals no + + + + # Base DN + BaseDN "DC=example,DC=com" + # User Search Filter, user must be a member of the VPN AD group + SearchFilter "(&(sAMAccountName=%u)(memberOf=CN=VPN,OU=Groups,DC=example,DC=com))" + # Require Group Membership + RequireGroup false # already handled by SearchFilter + + BaseDN "OU=Groups,DC=example,DC=com" + SearchFilter "(|(cn=VPN))" + MemberAttribute memberOf + + +``` + +If you only want to check that the user account is enabled and can authenticate (against the primary group), the following snippet is sufficient: + +``` none + + URL ldap://dc01.example.com + BindDN CN=SA_OPENVPN,OU=ServiceAccounts,DC=example,DC=com + Password ThisIsTopSecret + Timeout 15 + TLSEnable no + FollowReferrals no + + + + BaseDN "DC=example,DC=com" + SearchFilter "sAMAccountName=%u" + RequireGroup false + +``` + +A complete example of an LDAP authentication configuration for OpenVPN is shown below: + +``` none +vyos@vyos# show interfaces openvpn + openvpn vtun0 { + mode server + openvpn-option "--tun-mtu 1500 --fragment 1300 --mssfix" + openvpn-option "--plugin /usr/lib/openvpn/openvpn-auth-ldap.so /config/auth/ldap-auth.config" + openvpn-option "--push redirect-gateway" + openvpn-option --duplicate-cn + openvpn-option "--verify-client-cert none" + openvpn-option --comp-lzo + openvpn-option --persist-key + openvpn-option --persist-tun + server { + domain-name example.com + max-connections 5 + name-server 203.0.113.0.10 + name-server 198.51.100.3 + subnet 172.18.100.128/29 + } + tls { + ca-certificate ca.crt + certificate server.crt + dh-params dh1024.pem + } + } +``` + +For a detailed example, refer to {doc}`OpenVPN with LDAP`. + +### Multi-factor authentication + +VyOS supports multi-factor authentication (MFA) or two-factor authentication using Time-based One-Time Passwords (TOTP). It is compatible with Google Authenticator and other software tokens. + +## Server side + +``` none +set interfaces openvpn vtun20 encryption cipher 'aes256' +set interfaces openvpn vtun20 hash 'sha512' +set interfaces openvpn vtun20 mode 'server' +set interfaces openvpn vtun20 persistent-tunnel +set interfaces openvpn vtun20 server client user1 +set interfaces openvpn vtun20 server mfa totp challenge 'disable' +set interfaces openvpn vtun20 server subnet '10.10.2.0/24' +set interfaces openvpn vtun20 server topology 'subnet' +set interfaces openvpn vtun20 tls ca-certificate 'openvpn_vtun20' +set interfaces openvpn vtun20 tls certificate 'openvpn_vtun20' +set interfaces openvpn vtun20 tls dh-params 'dh-pem' +``` + +A TOTP secret is created for each client in the OpenVPN server configuration. To display authentication information, use the following command: `show interfaces openvpn vtun20 user user1 mfa qrcode`. + +Example: + +``` none +vyos@vyos:~$ sh interfaces openvpn vtun20 user user1 mfa qrcode +█████████████████████████████████████ +█████████████████████████████████████ +████ ▄▄▄▄▄ █▀▄▀ ▀▀▄▀ ▀▀▄ █ ▄▄▄▄▄ ████ +████ █ █ █▀▀▄ █▀▀▀█▀██ █ █ █ ████ +████ █▄▄▄█ █▀█ ▄ █▀▀ █▄▄▄█ █▄▄▄█ ████ +████▄▄▄▄▄▄▄█▄█ █ █ ▀ █▄▀▄█▄▄▄▄▄▄▄████ +████▄▄ ▄ █▄▄ ▄▀▄█▄ ▄▀▄█ ▄▄▀ ▀▄█ ▀████ +████ ▀██▄▄▄█▄ ██ █▄▄▄▄ █▄▀█ █ █▀█████ +████ ▄█▀▀▄▄ ▄█▀ ▀▄ ▄▄▀▄█▀▀▀ ▄▄▀████ +████▄█ ▀▄▄▄▀ ▀ ▄█ ▄ █▄█▀ █▀ █▀█████ +████▀█▀ ▀ ▄█▀▄▀▀█▄██▄█▀▀ ▀ ▀ ▄█▀████ +████ ██▄▄▀▄▄█ ██ ▀█ ▄█ ▀▄█ █▀██▀████ +████▄███▄█▄█ ▀█▄ ██▄▄▄█▀ ▄▄▄ █ ▀ ████ +████ ▄▄▄▄▄ █▄█▀▄ ▀▄ ▀█▀ █▄█ ██▀█████ +████ █ █ █ ▄█▀█▀▀▄ ▄▀▀▄▄▄▄▄▄ ████ +████ █▄▄▄█ █ ▄ ▀ █▄▄▄██▄▀█▄▀▄█▄ █████ +████▄▄▄▄▄▄▄█▄██▄█▄▄▄▄▄█▄█▄█▄██▄██████ +█████████████████████████████████████ +█████████████████████████████████████ +``` + +Scan the QR code to add the user account to Google Authenticator. On the client side, use the generated OTP as the password. + +### Authentication with username/password + +An OpenVPN server can securely obtain a username and password from a connecting client and use this information for authentication. + +First, configure the server to use an authentication plugin or script. The server calls this plugin every time a client tries to connect, passing it the client\'s credentials. + +In the following example, the `--auth-user-pass-verify` directive is used with the via-env method and a specified script path to validate the client\'s username and password. + +## Server configuration + +``` none +set interfaces openvpn vtun10 local-port '1194' +set interfaces openvpn vtun10 mode 'server' +set interfaces openvpn vtun10 openvpn-option '--auth-user-pass-verify /config/auth/check_user.sh via-env' +set interfaces openvpn vtun10 openvpn-option '--script-security 3' +set interfaces openvpn vtun10 persistent-tunnel +set interfaces openvpn vtun10 protocol 'udp' +set interfaces openvpn vtun10 server client client-1 ip '10.10.10.55' +set interfaces openvpn vtun10 server push-route 192.0.2.0/24 +set interfaces openvpn vtun10 server subnet '10.10.10.0/24' +set interfaces openvpn vtun10 server topology 'subnet' +set interfaces openvpn vtun10 tls ca-certificate 'ca-1' +set interfaces openvpn vtun10 tls certificate 'srv-1' +set interfaces openvpn vtun10 tls dh-params 'dh-1' +``` + +The /config/auth/check_user.sh example includes two test users: + +``` none +#!/bin/bash +USERNAME="$username" +PASSWORD="$password" + +# Replace this with real user checking logic or use getent +if [[ "$USERNAME" == "client1" && "$PASSWORD" == "pass123" ]]; then + exit 0 +elif [[ "$USERNAME" == "peter" && "$PASSWORD" == "qwerty" ]]; then + exit 0 +else + exit 1 +fi +``` + + +## Client configuration + +Storing the client certificate locally lets you generate the OpenVPN client configuration file. Use the following command: + +``` none +vyos@vyos:~$ generate openvpn client-config interface vtun10 ca ca-1 certificate client1 +``` + +Copy the output and save it as a .ovpn file. Add the `auth-user-pass` directive to the file. This instructs the OpenVPN client to prompt the user for a username and password, which are then sent to the server over the TLS channel. You can now import this file into any OpenVPN client application. + +``` none +client +dev tun +proto udp +remote 192.168.77.10 1194 + +remote-cert-tls server +proto udp +dev tun +dev-type tun +persist-key +persist-tun +verb 3 +auth-user-pass + + + +-----BEGIN CERTIFICATE----- +MIIDlzCCAn+gAwIBAgIUQW7AtPu0Qzp7VzT0TyYx83/ME8swDQYJKoZIhvcNAQEL +BQAwVDELMAkGA1UEBhMCR0IxEzARBgNVBAgMClNvbWUtU3RhdGUxEjAQBgNVBAcM +CVNvbWUtQ2l0eTENMAsGA1UECgwEVnlPUzENMAsGA1UEAwwEY2EtMTAeFw0yNTA2 +MTExMTIyMjJaFw0zMDA2MTAxMTIyMjJaMFQxCzAJBgNVBAYTAkdCMRMwEQYDVQQI +DApTb21lLVN0YXRlMRIwEAYDVQQHDAlTb21lLUNpdHkxDTALBgNVBAoMBFZ5T1Mx +DTALBgNVBAMMBGNhLTEwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDi ++v6i241T9ABxq1ngjWxDQITkqjV0nq2Jb3HSSuQpXRCu7DWdQZlbvnMHnkV/WTL0 +RNgkhS4iV/WYhE+bLihwiZ0GTeQnUd1QJSkusFROX46w6kKXYUR5IQtcBC+vdky8 +PESynPd+DXsJn5X9JTWqDeviUAQz/ZjDzWk+71MBCqa+Zps1zpIjK0ywn7pR/HnD +rxJOQXlBMNgvbv8U3IAZ2jJp0jTB8TnuDtWSA+XZejMm/EN/AWUQyliX6OJFSCIh +BL2BZ9lmVms4/HkRpbd50k3vvCoz+lAOEE6VsH0fEdLC3lZ+CtXZ7kjp2wdWWuSs +5ggIJYZZkixsCisbtEmbAgMBAAGjYTBfMA8GA1UdEwEB/wQFMAMBAf8wDgYDVR0P +AQH/BAQDAgGGMB0GA1UdJQQWMBQGCCsGAQUFBwMCBggrBgEFBQcDATAdBgNVHQ4E +FgQUAG9lvr7AzJ/y4vY/XlWxXru+6m0wDQYJKoZIhvcNAQELBQADggEBAKsu4eZa +8Fha9aKfuKqlGQHPpEFfVDaVJmebw0uMw+b5Y8EpBxzZrgbqbk3Mty8pBjNa9jkZ +zph04gHN4pR6kg3iQlUKGxZUfsB9ZUjKhkgNdUI9zq1323MKEvuIuYdt61DCfBHw +Y6Xax5Ge+BahR2bXdPaQH452/+xMTqkukkpLbioTeIDg6FCU2HYPY5emDF5DDZAZ +WXtTqi0zdT3Y6FqiTvs5VuWwXCcp+HM+Lwe1/VVJhwi4CHTq0CKWnQIH5blYjmyx +zRBlrlZm4ntWlL5Mtepa1A3DJirY4kw/SqMAAh/Q9lh41JzBc8epf+OdnOzK55Ym +tmctGO2o+NBCFi0= +-----END CERTIFICATE----- + + + + +-----BEGIN CERTIFICATE----- +MIIDrjCCApagAwIBAgIUN6vPxDEW89cfbEFPa0tZlnsW1GkwDQYJKoZIhvcNAQEL +BQAwVDELMAkGA1UEBhMCR0IxEzARBgNVBAgMClNvbWUtU3RhdGUxEjAQBgNVBAcM +CVNvbWUtQ2l0eTENMAsGA1UECgwEVnlPUzENMAsGA1UEAwwEY2EtMTAeFw0yNTA2 +MTExMTQ0MjlaFw0yNjA2MTExMTQ0MjlaMFcxCzAJBgNVBAYTAkdCMRMwEQYDVQQI +DApTb21lLVN0YXRlMRIwEAYDVQQHDAlTb21lLUNpdHkxDTALBgNVBAoMBFZ5T1Mx +EDAOBgNVBAMMB2NsaWVudDEwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIB +AQCdOWq8vdO8CznGN83uAXCuN4PcdTJaRFEdJIEfqHjlcG0MZQuPIAlDbOU+IWmu +QBmeCj7SlbYtVYo1uQOMUaIrAvxLIQUaL1Y60oLVTF5eAPrGV+NSTQR5uMApcH9/ +RcZcW530pu/QpYinKTbGkEd54so6YRVPmYbIOPNUMbnZbccpinYi5t2dqubBb585 +A7L40043VtsVVbPjQq5V0HDursvqlaMqMRcffhR8H4B4ByU/EPRK4yTKm1hi19v3 +UtRHiq74CfGtJzYtplgrLJBON7TsbIi/fEux4q1yhbKA0S66L6e5DZldRxNZOXG6 +QjEL0RkYloMgkbv/2HLCu09hAgMBAAGjdTBzMAwGA1UdEwEB/wQCMAAwDgYDVR0P +AQH/BAQDAgeAMBMGA1UdJQQMMAoGCCsGAQUFBwMCMB0GA1UdDgQWBBQCkfdfq3hv +7UtqAxq/5VDRIdgJLTAfBgNVHSMEGDAWgBQAb2W+vsDMn/Li9j9eVbFeu77qbTAN +BgkqhkiG9w0BAQsFAAOCAQEAJ43+aDVRC+y2vsu6WRG2l6zYnLoIJZW4afdKMC1a +nhTWhj4AhAt8evhVbAxi/8qhQX3yXF2bUQKdS++8AVcvZFlSES32S5eBx83AwGLt +QkgvGx+QThKmoJwrelyuS2X0XX3P0WzohYI6HzSr6p9F8KhTvSW97E6SnldpdvEM +uG1C+61/Vys7WLmDBh1PZTGE03nRp3H4Q9ynyXEEf1MK3eZkzg5H3Evj66p82pD5 +8IauRfghMHJf3tOC+y0YIoXshF3lPq4nYso5Jc/HGCHlsboCODMCnY3CZsH7/O1n +/MI710KpzZTCLnv4Qtx9JpZxR7FTddl36OOuYUXU3Gcnsg== +-----END CERTIFICATE----- + + + + +-----BEGIN PRIVATE KEY----- +MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQCdOWq8vdO8CznG +N83uAXCuN4PcdTJaRFEdJIEfqHjlcG0MZQuPIAlDbOU+IWmuQBmeCj7SlbYtVYo1 +uQOMUaIrAvxLIQUaL1Y60oLVTF5eAPrGV+NSTQR5uMApcH9/RcZcW530pu/QpYin +KTbGkEd54so6YRVPmYbIOPNUMbnZbccpinYi5t2dqubBb585A7L40043VtsVVbPj +Qq5V0HDursvqlaMqMRcffhR8H4B4ByU/EPRK4yTKm1hi19v3UtRHiq74CfGtJzYt +plgrLJBON7TsbIi/fEux4q1yhbKA0S66L6e5DZldRxNZOXG6QjEL0RkYloMgkbv/ +2HLCu09hAgMBAAECggEAOR3xRVUO9Sr816JRSQwz486eNDpNSxazgwtOb3JUTUH9 +E7onq1y/kMOgOmSIEHoP9GaTcQxbbPe86IxomhLT/50ri52YzWzx/heY2SVPyQXB +FMo79putKw0vnj5UyydNiyLrbMQyrhFc5iFmWVdz5/c4cWHwjIThPp7V4znXYwHZ +OB/Xn1NNHDNy872oQn5wZWzuA4ml0OqjU5D+Ne9srODl3r4OTo3lb1N3JuH3aOSA +cACl1JnN/KElN8IotIdweeUFAdn2jsGjZnCpGaJvZQ+2iMn6doJXHgFiF5+GMF7o +aOatglElIuqgPtB/4nvnegSL0DSnB36ojqv2PAh24wKBgQDPBt4S4muqo8SqP2e0 +8X78MyK3tz1VmgPKn3O68Vdi1V7FPz0RHRGsw/kdgxXsJlfZTWgzcq2NNFu0yPBJ +A/h7qo16mv8GW7cJCd2exjb+/oq4r5iWeqLdSsMUXN87x02LRaMNd9wz1mls1Z73 +oQ5hJ7zTtlyYXnvKPQo8X1ImjwKBgQDCaptQxZ/a3tcUQQlXAFMAScviODZd0LCL +30ZalwpNs6nVVIPoZHD3tlzWN5Es74gndfkC7/Gm2cnsOW9QQaU56q+5LeNXItW8 +rc6yXq3vNQerqJxHNUmKWwLCQtSyLRjFqpGTl/PyX2bGXQ7/zjTL3W8VMD5otf4Y +SJJB+sKjDwKBgHSVX3WvAAamFtfwwMwKuwH3IfPnQqj0BHKUfK2nvxgvJCFbzV3X +yt5Jtf3ClhPYO9xpVOa0C7va4lHaXkYf8Exj7SxAIKFKALccUStaYBoU6bW7XOhQ +w2pu8ZCEBEo7oBVv77Rj7SNb+R6K5ex5TAm2QQXQSjCb9IYc/ail3TNNAoGBALu6 +GPMrgKnlFyV1j0E1DPBwUbDEuqpoArFtDRAYXFifLVTS4PQbWIG403f9++659Gy2 +G5ZcfqiwD6xL4VJLsPF1zewvhR/0gRJJehb+GVGrkRaOHykbKUGxk75kreDGbu8f +PqaXyXS17hWIch1Lzes0jDiXdwvA//QOzztqmVq9AoGAVMbmf04+QtzckLolAP4q +Uwr5svfy14A7V3IGkwlsHZdm37L26lfxW0kpOOE7g7D6gdinuALo6oopP7RN/IDq +PLaaHaGrIoLAEVFa0bRLGsrU2q87ytwfSgdra4jmsTn+xEabdI4IgmqWgwSRvGVf +KN18e19Ssw5x7Wq0Rsw/3VM= +-----END PRIVATE KEY----- + + +``` + +When prompted, log in with the username and password. diff --git a/docs/configuration/interfaces/md-openvpn.md b/docs/configuration/interfaces/md-openvpn.md new file mode 100644 index 00000000..170c585d --- /dev/null +++ b/docs/configuration/interfaces/md-openvpn.md @@ -0,0 +1,614 @@ +(openvpn)= + +# OpenVPN + +Traditionally, hardware routers use IPsec exclusively because it is easy to +implement in hardware, and their CPUs lack sufficient power for software-based +encryption. This limitation is less relevant for VyOS, as it is a software +router. + +OpenVPN has been widely used on UNIX platforms for a long time and is a popular +choice for remote-access VPNs. It also supports site-to-site connections. + +OpenVPN offers the following advantages: + +- It uses a single TCP or UDP connection and does not rely on packet source + addresses, so it works even through double NAT. This makes it well-suited for + public hotspots. +- It is easy to set up and offers very flexible split tunneling. +- A variety of client GUI frontends are available for any platform. + +Disadvantages include: + +- It is slower than IPsec due to higher protocol overhead and because it runs + in user mode, while IPsec on Linux runs in kernel mode. +- No operating system includes OpenVPN client software by default. + +In the VyOS CLI, OpenVPN is configured as a network interface using `set +interfaces openvpn` rather than `set vpn`, which is often overlooked. + +## Configuration + +```{cfgcmd} set interfaces openvpn \ authentication password \ + + **Configure the password for the** ``auth-user-pass`` **authentication method.** + + This option applies only to OpenVPN clients. +``` + + +```{cfgcmd} set interfaces openvpn \ authentication username \ + +**Configure the username for the** ``auth-user-pass`` **authentication method.** + +This option applies only to OpenVPN clients. +``` + + +```{cfgcmd} set interfaces openvpn \ description \ + +Configure the description for the OpenVPN interface. +``` + + +```{cfgcmd} set interfaces openvpn \ device-type \ + +**Configure the virtual network device type for the OpenVPN interface:** + +* ``tun`` **(default)**: Operates at Layer 3, encapsulating IPv4 or IPv6 packets. +* ``tap``: Operates at Layer 2, encapsulating Ethernet 802.3 frames. +``` + + +```{cfgcmd} set interfaces openvpn \ disable + +Disable the specific OpenVPN interface. +``` + + +```{cfgcmd} set interfaces openvpn \ encryption cipher \< 3des | aes128 | aes128gcm | aes192 | aes192gcm | aes256 | aes256gcm | none \> + +**Configure the static encryption cipher for the OpenVPN tunnel.** + +The ``cipher`` option maps to OpenVPN’s ``--cipher`` directive and specifies +the symmetric encryption algorithm for both control and data channels. + +This was previously the default encryption method in all OpenVPN modes. In +newer OpenVPN versions, the ``--cipher`` directive is considered **legacy** +and should be used only in compatibility scenarios. +``` + + +```{cfgcmd} set interfaces openvpn \ encryption data-ciphers \< 3des | aes128 | aes128gcm | aes192 | aes192gcm | aes256 | aes256gcm | none \> + +**Configure a prioritized list of negotiated ciphers for OpenVPN in** +``client`` **or** ``server`` **mode.** + +The ``data-ciphers`` option represents a list of supported encryption +algorithms. It corresponds to OpenVPN’s ``--data-ciphers`` directive and +enables cipher negotiation, where both peers automatically agree on a mutually +supported cipher during session startup. + +:::{note} +This option is not compatible with ``site-to-site`` mode. +::: +``` + + +```{cfgcmd} set interfaces openvpn \ encryption data-ciphers-fallback \< 3des | aes128 | aes128gcm | aes192 | aes192gcm | aes256 | aes256gcm | none \> + +**Configure the fallback cipher for** ``site-to-site`` **mode.** + +The ``data-ciphers-fallback`` option maps to OpenVPN’s ``--data-ciphers- +fallback`` directive. It defines the cipher to use if negotiation is **not +supported**. + +:::{note} +This option ensures consistent encryption between two static peers +without cipher negotiation capability. +::: +``` + + +```{cfgcmd} set interfaces openvpn \ hash \ + +Configure the hashing algorithm for the OpenVPN interface. +``` + + +```{cmdincludemd} /_include/interface-ip.txt +:var0: openvpn +:var1: vtun0 +``` + + +```{cmdincludemd} /_include/interface-ipv6.txt +:var0: openvpn +:var1: vtun0 +``` + + +```{cfgcmd} set interfaces openvpn \ keep-alive failure-count \ + +**Configure the number of tolerated keepalive packet failures.** + +Default: 60 consecutive failures. +``` + + +```{cfgcmd} set interfaces openvpn \ keep-alive interval \ + +**Configure the frequency, in seconds, at which keepalive packets are sent.** + +Default: 10 seconds. +``` + + +```{cfgcmd} set interfaces openvpn \ local-address \ + +Configure the local tunnel IP address for ``site-to-site`` mode. +``` + + +```{cfgcmd} set interfaces openvpn \ local-host \ + +**Configure the local IP address to accept connections.** + +If configured, OpenVPN binds to this IP address only. + +By default, OpenVPN binds to all interfaces. +``` + + +```{cfgcmd} set interfaces openvpn \ local-port \ + +Configure the local port to accept connections. +``` + + +```{cfgcmd} set interfaces openvpn \ mirror egress \ + +Configure mirroring of outgoing traffic from this OpenVPN interface to the +designated monitor interface. +``` + + +```{cfgcmd} set interfaces openvpn \ mirror ingress \ + +Configure mirroring of incoming traffic from this OpenVPN interface to the +designated monitor interface. +``` + + +```{cfgcmd} set interfaces openvpn \ mode \ + +**Configure OpenVPN operation mode:** + +* ``site-to-site``: Establishes a site-to-site VPN connection. +* ``client``: Operates as a client in server-client mode. +* ``server``: Operates as a server in server-client mode. +``` + +### OpenVPN Data Channel Offload (DCO) + +OpenVPN {abbr}`DCO (Data Channel Offload)` improves the performance of +encrypted OpenVPN data processing by keeping most data handling in the kernel +and avoiding frequent context switches between the kernel and user space. + +As a result, packet processing becomes more efficient and may utilize hardware +encryption offload support available in the kernel. + +:::{note} +- {abbr}`DCO (Data Channel Offload)` is an **experimental**, not fully supported + OpenVPN feature. Some OpenVPN features and deployment scenarios are **not + compatible** with {abbr}`DCO (Data Channel Offload)`. + + For a complete list of supported features, visit: + +- {abbr}`DCO (Data Channel Offload)` is configured per tunnel and disabled + by default. Existing tunnels operate without {abbr}`DCO (Data Channel + Offload)` unless it is explicitly enabled. +- Enabling {abbr}`DCO (Data Channel Offload)` resets the interface. +::: + +**Best practice:** Create a new tunnel with {abbr}`DCO (Data Channel Offload)` +enabled to avoid compatibility issues with existing clients. + +```{cfgcmd} set interfaces openvpn \ offload dco + + **Enable** {abbr}`DCO (Data Channel Offload)` **for the specified OpenVPN + interface.** + + Example: + + :::{code-block} none + set interfaces openvpn vtun0 offload dco + ::: + This command enables {abbr}`DCO (Data Channel Offload)` and loads the required + kernel module. +``` + + +```{cfgcmd} set interfaces openvpn \ openvpn-option \ + +**Add raw OpenVPN configuration options to the openvpn.conf file.** + +OpenVPN provides many configuration options, but not all are available in the +VyOS CLI. + +If a required option is missing, you may submit a feature request at +Phabricator so all users can benefit from it (see Contributing/Issues and Features). + +Alternatively, use ``openvpn-option`` to pass raw OpenVPN configuration options +to the openvpn.conf file. + +:::{warning} +Use this option only as a last resort. Invalid options or syntax +may prevent OpenVPN from starting. Check system logs for errors after applying +changes. +::: +Example: + +:::{code-block} none +set interfaces openvpn vtun0 openvpn-option 'persist-key' +::: +This command adds ``persist-key`` to the configuration file. This solves the +problem by persisting keys across resets, so they do not need to be re-read. + +:::{code-block} none +set interfaces openvpn vtun0 openvpn-option 'route-up "/config/auth/tun_up.sh arg1"' +::: +This command adds ``route-up "/config/auth/tun_up.sh arg1"`` to the +configuration file. This option is executed after connection authentication, +either immediately or after a short delay, as defined. + +Ensure the path and arguments are enclosed in single or double quotes. + +:::{note} +Some raw configuration options require quotes. To include them, use +the " statement. +::: +``` + + +```{cfgcmd} set interfaces openvpn \ persistent-tunnel + +**Enable always-active mode for the TUN/TAP device.** + +When enabled, the TUN/TAP device remains active upon connection resets or +daemon reloads. +``` + + +```{cfgcmd} set interfaces openvpn \ protocol \ + +**Configure the protocol for OpenVPN communication with a remote host:** + +* ``udp`` **(default)**: Uses the UDP protocol. +* ``tcp-passive``: Uses the TCP protocol and accepts connections passively. +* ``tcp-active``: Uses the TCP protocol and initiates connections actively. +``` + + +```{cfgcmd} set interfaces openvpn \ redirect \ + +Enable redirection of incoming packets to the specified interface. +``` + + +```{cfgcmd} set interfaces openvpn \ remote-address \ + +Configure the remote tunnel IP address for site-to-site mode. +``` + + +```{cfgcmd} set interfaces openvpn \ remote-host \
+ +**Configure the IPv4/IPv6 address or hostname for a server device if OpenVPN +runs in client mode.** + +This setting is not used in server mode. +``` + + +```{cfgcmd} set interfaces openvpn \ remote-port \ + +Configure the remote port to connect to the server. +``` + + +```{cfgcmd} set interfaces openvpn \ replace-default-route + +Configure the OpenVPN tunnel as the default route. +``` + + +```{cfgcmd} set interfaces openvpn \ server bridge disable + +Disable the given instance. +``` + + +```{cfgcmd} set interfaces openvpn \ server bridge gateway \ + +Configure the gateway IP address. +``` + + +```{cfgcmd} set interfaces openvpn \ server bridge start \ + +Configure the first IP address in the pool to allocate to connecting clients. +``` + + +```{cfgcmd} set interfaces openvpn \ server bridge stop \ + +Configure the last IP address in the pool to allocate to connecting clients. +``` + + +```{cfgcmd} set interfaces openvpn \ server bridge subnet-mask \ + +Configure the subnet mask pushed to dynamic clients. +``` + + +```{cfgcmd} set interfaces openvpn \ server client \ + +Configure the Common Name (CN) specified in the client certificate. +``` + + +```{cfgcmd} set interfaces openvpn \ server client \ disable + +Disable the client connection. +``` + + +```{cfgcmd} set interfaces openvpn \ server client \ ip \ + +Configure the IPv4/IPv6 address for the client. +``` + + +```{cfgcmd} set interfaces openvpn \ server client \ push-route \ + +Configure a route to be pushed to the specific client. +``` + + +```{cfgcmd} set interfaces openvpn \ server client \ subnet \ + +**Configure a fixed subnet to be routed from the server to the specified +client.** + +Used as OpenVPN’s ``iroute`` directive. +``` + + +```{cfgcmd} set interfaces openvpn \ server client-ip-pool start \ + +Configure the first IP address in the subnet's IPv4 pool to be dynamically +allocated to connecting clients. +``` + + +```{cfgcmd} set interfaces openvpn \ server client-ip-pool stop \ + +Configure the last IP address in the subnet's IPv4 pool to be dynamically +allocated to connecting clients. +``` + + +```{cfgcmd} set interfaces openvpn \ server client-ip-pool subnet \ + +**Configure the subnet mask pushed to dynamic clients.** + +Use this command only for the TAP device type. Do not use it for bridged +interfaces. +``` + + +```{cfgcmd} set interfaces openvpn \ server client-ipv6-pool base \ + +Configure the IPv6 address pool for dynamic assignment to clients. +``` + + +```{cfgcmd} set interfaces openvpn \ server domain-name \ + +Configure the DNS suffix to be pushed to all clients. +``` + + +```{cfgcmd} set interfaces openvpn \ server max-connections \<1-4096\> + +Configure the maximum number of client connections. +``` + + +```{cfgcmd} set interfaces openvpn \ server mfa totp challenge \ + +If enabled, openvpn-otp expects a password as a result of the challenge/ +response protocol. +``` + + +```{cfgcmd} set interfaces openvpn \ server mfa totp digits \<1-65535\> + +**Configure the number of digits to use for the** {abbr}`TOTP (Time-based +One-Time Password)` **hash.** + +Default: 6. +``` + + +```{cfgcmd} set interfaces openvpn \ server mfa totp drift \<1-65535\> + +**Configure the time drift in seconds.** + +Default: 0. +``` + + +```{cfgcmd} set interfaces openvpn \ server mfa totp slop \<1-65535\> + +**Configure the allowed clock slop in seconds.** + +Default: 180. +``` + + +```{cfgcmd} set interfaces openvpn \ server mfa totp step \<1-65535\> + +**Configure the step value for** {abbr}`TOTP (Time-based One-Time Password)` +**in seconds.** + +Default: 30. +``` + + +```{cfgcmd} set interfaces openvpn \ server name-server \ + +Define the client DNS configuration to be used with the connection. +``` + + +```{cfgcmd} set interfaces openvpn \ server push-route \ + +Configure the route to be pushed to all clients. +``` + + +```{cfgcmd} set interfaces openvpn \ server reject-unconfigured-client + +Reject connections from clients that are not explicitly configured. +``` + + +```{cfgcmd} set interfaces openvpn \ server subnet \ + +**Configure the IPv4 or IPv6 network.** + +This parameter is mandatory when operating in server mode. +``` + + +```{cfgcmd} set interfaces openvpn \ server topology \< net30 | point-to-point | subnet\> + +**Configure the virtual addressing topology for** ``tun`` **mode.** + +This command does not affect ``tap`` mode, which always uses the ``subnet`` +topology. + +* ``subnet`` **(default)**: Allocates a single IP address to each connecting client. +This is the recommended topology. +* ``net30``: Allocates a /30 subnet to each connecting client. This is a legacy +topology used to support Windows clients. It is now effectively deprecated. +* ``point-to-point``: Creates a point-to-point topology where the remote +endpoint of the client’s ``tun`` interface always points to the local endpoint +of the server’s ``tun`` interface. + +Like ``subnet``, this topology allocates a single IP address per client. Use it +only if no clients run Windows operating systems. +``` +```{cfgcmd} set interfaces openvpn \ shared-secret-key \ + +Configure the static secret key for a site-to-site OpenVPN connection. +``` +```{cfgcmd} set interfaces openvpn \ tls auth-key \ + +**Configure the TLS secret key for tls-auth.** + +This adds an HMAC signature to all SSL/TLS handshake packets to verify +integrity. + +Use ``run generate pki openvpn shared-secret install `` to generate +the key. +``` +```{cfgcmd} set interfaces openvpn \ tls ca-certificate \ + +Configure the Certificate Authority chain in the PKI configuration. +``` +```{cfgcmd} set interfaces openvpn \ tls certificate \ + +Configure the certificate name in the PKI configuration. +``` +```{cfgcmd} set interfaces openvpn \ tls crypt-key + +Configure a shared secret key to provide an additional level of security, +a variant similar to tls-auth. +``` +```{cfgcmd} set interfaces openvpn \ tls dh-params + +Configure Diffie-Hellman parameters for server mode. +``` +```{cfgcmd} set interfaces openvpn \ tls peer-fingerprint \ + +Configure the peer certificate SHA256 fingerprint for site-to-site mode. +``` +```{cfgcmd} set interfaces openvpn \ tls role \ + +**Configure the TLS negotiation role, preferably used in site-to-site mode:** +* ``active``: Initiates TLS negotiation actively. +* ``passive``: Waits for incoming TLS connections. +``` +```{cfgcmd} set interfaces openvpn \ tls tls-version-min \<1.0 | 1.1 | 1.2 | 1.3 \> + +Configure the minimum TLS version to be accepted from the peer. +``` +```{cfgcmd} set interfaces openvpn \ use-lzo-compression + +Configure fast LZO compression on this TUN/TAP interface. +``` +```{cfgcmd} set interfaces openvpn \ vrf \ + +Assign the interface to a specific VRF instance. +``` + +## Operation mode + +```{opcmd} show openvpn site-to-site + +Show tunnel status for OpenVPN site-to-site interfaces. +``` +```{opcmd} show openvpn server + +Show tunnel status for OpenVPN server interfaces. +``` +```{opcmd} show openvpn client + +Show tunnel status for OpenVPN client interfaces. +``` +```{opcmd} show log openvpn + +Show logs for all OpenVPN interfaces. +``` +```{opcmd} show log openvpn interface \ + +Show logs for the specific OpenVPN interface. +``` +```{opcmd} reset openvpn client \ + +Reset the specified OpenVPN client. +``` +```{opcmd} reset openvpn interface \ + +Reset the OpenVPN process on the specified interface. +``` +```{opcmd} generate openvpn client-config interface \ ca \ certificate \ + +Generate an OpenVPN client configuration file in the .ovpn format for client machines. +``` + +## Examples + +This section covers examples of OpenVPN configurations for various deployments. + +```{toctree} +:includehidden: true +:maxdepth: 1 + +openvpn-examples +``` + diff --git a/docs/configuration/interfaces/md-pppoe.md b/docs/configuration/interfaces/md-pppoe.md new file mode 100644 index 00000000..b79f41a2 --- /dev/null +++ b/docs/configuration/interfaces/md-pppoe.md @@ -0,0 +1,419 @@ +--- +lastproofread: '2026-03-03' +--- + +(pppoe-interface)= + +# PPPoE + +{abbr}`PPPoE (Point-to-Point Protocol over Ethernet)` is a network protocol +that encapsulates PPP frames within Ethernet frames. +It's often used for connecting ISP clients to a broadband access server. + +## Configuration + +### Common interface configuration + +```{cmdincludemd} /_include/interface-description.txt +:var0: pppoe +:var1: pppoe0 +``` + +```{cmdincludemd} /_include/interface-disable.txt +:var0: pppoe +:var1: pppoe0 +``` + +```{cmdincludemd} /_include/interface-mtu.txt +:var0: pppoe +:var1: pppoe0 +``` + +```{cmdincludemd} /_include/interface-vrf.txt +:var0: pppoe +:var1: pppoe0 +``` + + +### PPPoE options + +```{cfgcmd} set interfaces pppoe \ access-concentrator \ + +**Configure the name of the target access concentrator for the PPPoE session.** + +During the PPPoE discovery process, the client sends a PPPoE initiation packet. +Multiple access concentrators may respond with offer packets, and the client +selects one of them. + +This setting restricts the client to establishing sessions only with the +specified access concentrator. +``` + +```{cfgcmd} set interfaces pppoe \ authentication username \ + +**Configure the username for PPPoE session authentication.** + +Although authentication is optional in the interface configuration, most ISPs +require it to establish a connection. +``` + +```{cfgcmd} set interfaces pppoe \ authentication password \ + +**Configure the password for PPPoE session authentication.** + +Although authentication is optional in the interface configuration, most ISPs +require it to establish a connection. +``` + +```{cfgcmd} set interfaces pppoe \ connect-on-demand + +**Enable dial-on-demand on the PPPoE interface.** + +When enabled, the system establishes a PPPoE connection only when traffic +passes through the interface. If the connection fails, it is reestablished when +traffic resumes. + +For on-demand connections, you must also configure an ``idle-timeout`` period +to disconnect the session after inactivity. + +:::{note} +Setting the idle timeout to zero, or leaving it unconfigured, keeps +the connection active continuously once established. +::: + +By default, the PPPoE connection is established at boot and remains active +continuously; if the connection fails, it is reestablished immediately. +``` + +```{cfgcmd} set interfaces pppoe \ no-default-route + +Request an IP address from the PPPoE server without installing a default route. + +Example: + +:::{code-block} none +set interfaces pppoe pppoe0 no-default-route +::: + +:::{note} +Introduced in VyOS 1.4, this command inverts the logic of the former +``default-route`` CLI option. +::: +``` + +```{cfgcmd} set interfaces pppoe \ default-route-distance \ + +Configure the distance for the default gateway provided by the PPPoE server. + +Example: + +:::{code-block} none +set interfaces pppoe pppoe0 default-route-distance 220 +::: +``` + +```{cfgcmd} set interfaces pppoe \ mru \ + +**Configure the** {abbr}`MRU (Maximum Receive Unit)` **for the PPPoE +interface.** + +This setting instructs the pppd daemon to restrict the remote peer from sending +packets larger than the configured MRU. Allowed MRU values range from 128 to +16384 bytes. + +An MRU of 296 is suitable for very slow links (40 bytes for the TCP/IP header +and 256 bytes for data). + +The default MRU is 1492 bytes. + +:::{note} +When using the IPv6 protocol, the MRU must be at least 1280 bytes. +::: +``` + +```{cfgcmd} set interfaces pppoe \ idle-timeout \ + +**Configure the idle timeout for on-demand PPPoE sessions.** + +This setting defines how long the connection remains active without any traffic +before being disconnected. + +:::{note} +Setting the idle timeout to zero, or leaving it unconfigured, keeps +the connection active continuously once established. +::: +``` + +```{cfgcmd} set interfaces pppoe \ holdoff \ + +**Configure the redial delay for persistent PPPoE sessions.** + +If a persistent session (with ``connect-on-demand`` disabled) is terminated by +the remote peer or drops unexpectedly, the router waits the specified interval +before attempting to reconnect. + +The default redial delay is 30 seconds. +``` + +```{cfgcmd} set interfaces pppoe \ local-address \ + +**Configure the local endpoint IP address for PPPoE sessions.** + +By default, this IP address is negotiated. +``` + +```{cfgcmd} set interfaces pppoe \ no-peer-dns + +Disable the installation of advertised DNS nameservers on the local system. +``` + +```{cfgcmd} set interfaces pppoe \ remote-address \ + +**Configure the remote endpoint IP address for PPPoE sessions.** + +By default, this IP address is negotiated. +``` + +```{cfgcmd} set interfaces pppoe \ service-name \ + +**Configure the service name of the target access concentrator for the PPPoE +session.** + +By default, the PPPoE interface connects to any available access concentrator. +``` + +```{cfgcmd} set interfaces pppoe \ source-interface \ + +**Configure the underlying interface for the PPPoE connection.** + +Each PPPoE connection is established over an underlying interface, which can be +an Ethernet interface, a VIF, or a bonding interface. +``` + +```{cfgcmd} set interfaces pppoe \ ip adjust-mss \ + +**Configure the** {abbr}`MSS (Maximum Segment Size)` **advertised in outgoing +TCP SYN packets on the specified interface.** + +By clamping the MSS value in TCP SYN packets, you instruct the remote side not +to send packets larger than the specified size. This helps prevent connection +issues if {abbr}`PMTUD (Path MTU Discovery)` fails. + +The following options are available: + +* ``mss``: Sets the MSS to a specific value in bytes. +* ``clamp-mss-to-pmtu``: Sets the MSS to the interface’s MTU minus 40 bytes for + IPv4 traffic (20 bytes for the IPv4 header and 20 bytes for the TCP header). + This option is recommended to automatically set the proper value. + +:::{note} +Introduced in VyOS 1.4, this command replaces the older ``set firewall +options interface adjust-mss `` syntax. +::: +``` + +```{cfgcmd} set interfaces pppoe \ ip disable-forwarding + +**Configure the interface for host or router behavior.** + +If configured, the interface switches to host mode, and IPv4 forwarding is +disabled on it. +``` + +```{cfgcmd} set interfaces pppoe \ ip source-validation \ + +**Configure source IP address validation using** +{abbr}`RPF (Reverse Path Forwarding)` **on this interface, as specified in** +{rfc}`3704`. + +The following options are available: + +* ``strict``: Each incoming packet’s source IP address is checked against the + {abbr}`FIB (Forwarding Information Base)`. If the interface is not the best + route back to that source, validation fails, and the packet is dropped. +* ``loose``: Each incoming packet’s source IP address is checked against the + {abbr}`FIB (Forwarding Information Base)`. If the source IP address is + unreachable through any interface, validation fails. +* ``disable``: No source IP address validation is performed. All incoming + packets are accepted. + +{rfc}`3704` recommends enabling ``strict`` mode to prevent IP spoofing, such as +DDoS attacks. For asymmetric or other complex routing scenarios, use ``loose`` +mode. +``` + + +#### IPv6 + +```{cfgcmd} set interfaces pppoe \ ipv6 address autoconf + +Enable IPv6 address assignment via {abbr}`SLAAC (Stateless Address +Auto-Configuration)` on this interface. +``` + +```{cfgcmd} set interfaces pppoe \ ipv6 adjust-mss \ + +**Configure the** {abbr}`MSS (Maximum Segment Size)` **advertised in outgoing +TCP SYN packets on the specified interface.** + +By clamping the MSS value in TCP SYN packets, you instruct the remote side not +to send packets larger than the specified size. This helps prevent connection +issues if {abbr}`PMTUD (Path MTU Discovery)` fails. + +The following options are available: + +* ``mss``: Sets the MSS to a specific value in bytes. +* ``clamp-mss-to-pmtu``: Sets the MSS to the interface’s MTU minus 60 bytes for + IPv6 traffic (40 bytes for the IPv6 header and 20 bytes for the TCP header). + This option is recommended to automatically set the proper value. + +:::{note} +Introduced in VyOS 1.4, this command replaces the older ``set firewall +options interface adjust-mss `` syntax. +::: +``` + +```{cfgcmd} set interfaces pppoe \ ipv6 disable-forwarding + +**Configure the interface for host or router behavior.** + +If configured, the interface switches to host mode, and IPv6 forwarding is +disabled on it. +``` + +```{cmdincludemd} /_include/interface-dhcpv6-prefix-delegation.txt +:var0: pppoe +:var1: pppoe0 +``` + + +## Operation + +```{opcmd} show interfaces pppoe \ + +Show detailed information about a specific PPPoE interface. + +:::{code-block} none +vyos@vyos:~$ show interfaces pppoe pppoe0 +pppoe0: mtu 1492 qdisc pfifo_fast state UNKNOWN group default qlen 3 + link/ppp + inet 192.0.2.1 peer 192.0.2.255/32 scope global pppoe0 + valid_lft forever preferred_lft forever + + RX: bytes packets errors dropped overrun mcast + 7002658233 5064967 0 0 0 0 + TX: bytes packets errors dropped carrier collisions + 533822843 1620173 0 0 0 0 +::: +``` + +```{opcmd} show interfaces pppoe \ queue + +Show queue information for a specific PPPoE interface. + +:::{code-block} none +vyos@vyos:~$ show interfaces pppoe pppoe0 queue +qdisc pfifo_fast 0: root refcnt 2 bands 3 priomap 1 2 2 2 1 2 0 0 1 1 1 1 1 1 1 1 + Sent 534625359 bytes 1626761 pkt (dropped 62, overlimits 0 requeues 0) + backlog 0b 0p requeues 0 +::: +``` + + +### Connect/disconnect + +```{opcmd} disconnect interface \ + +Disconnect the specified interface. +``` + +```{opcmd} connect interface \ + +Initiate a session on the specified interface. +``` + + +## Example + +### PPPoE over DSL + +**Configuration scenario:** + +- Your ISP's DSL modem is connected to the `eth0` interface on your VyOS + router. +- Your ISP does not require VLAN tagging. +- PPPoE credentials are provided by your ISP. The typical username format is + `name@host.net`, though this may vary. + +**Configuration notes:** + +- The maximum MTU size for DSL is 1492 because of PPPoE overhead. If you are + switching from a DHCP-based ISP (e.g., a standard cable connection), ensure + VPN links have MTU sizes adjusted accordingly. +- To ignore ISP-provided nameservers and use only your statically configured + ones, set the `name-server` option to `none`. +- A default route is automatically installed once the interface is up. To + change this behavior, use the `no-default-route` CLI option. + +:::{note} +The PPPoE configuration syntax changed after VyOS 1.2 (Crux) and is +automatically migrated during an upgrade. +::: + +```none +set interfaces pppoe pppoe0 authentication username 'userid' +set interfaces pppoe pppoe0 authentication password 'secret' +set interfaces pppoe pppoe0 source-interface 'eth0' +``` + +Secure your setup by creating rules matching the `pppoe0` interface in the +firewall chains: + +```none +set firewall ipv4 input filter rule 10 inbound-interface name 'pppoe0' +set firewall ipv4 forward filter rule 10 inbound-interface name 'pppoe0' +``` + + +### PPPoE over VLAN + +Some ISPs require PPPoE connections to be +established over a VLAN interface. This specific topology is fully supported by +VyOS. + +The following configuration establishes the PPPoE connection through VLAN 7, +which is the default VLAN for Deutsche Telekom: + +```none +set interfaces pppoe pppoe0 authentication username 'userid' +set interfaces pppoe pppoe0 authentication password 'secret' +set interfaces pppoe pppoe0 source-interface 'eth0.7' +``` + + +#### IPv6 DHCPv6 prefix delegation + +**Configuration scenario:** + +The following configuration establishes a PPPoE session on the `eth1` +interface, requests a `/56` IPv6 prefix delegation from the ISP, and assigns +a `/64` subnet from that delegation to the `eth0` interface. + +**Configuration notes:** + +- The IPv6 address assigned to `eth0` is `::1/64`. +- If you do not know your delegated prefix size, begin with `sla-len 0`. +- To advertise the prefix on the `eth0` link, configure IPv6 Router + Advertisement. + +```none +set interfaces pppoe pppoe0 authentication username vyos +set interfaces pppoe pppoe0 authentication password vyos +set interfaces pppoe pppoe0 dhcpv6-options pd 0 interface eth0 address '1' +set interfaces pppoe pppoe0 dhcpv6-options pd 0 interface eth0 sla-id '0' +set interfaces pppoe pppoe0 dhcpv6-options pd 0 length '56' +set interfaces pppoe pppoe0 ipv6 address autoconf +set interfaces pppoe pppoe0 source-interface eth1 + +set service router-advert interface eth0 prefix ::/64 +``` diff --git a/docs/configuration/interfaces/md-pseudo-ethernet.md b/docs/configuration/interfaces/md-pseudo-ethernet.md new file mode 100644 index 00000000..fc8833eb --- /dev/null +++ b/docs/configuration/interfaces/md-pseudo-ethernet.md @@ -0,0 +1,52 @@ +--- +lastproofread: '2026-03-05' +--- + +(pseudo-ethernet-interface)= + +# MACVLAN (pseudo-Ethernet) + +MACVLAN, or pseudo-Ethernet interfaces, operate as logical subinterfaces of +standard Ethernet interfaces. Each subinterface has a unique MAC address but +shares a single physical Ethernet port. +That allows the user to send packets from different source IPv4 or IPv6 addresses +using a different MAC address. + +Pseudo-Ethernet interfaces behave like physical Ethernet interfaces. They +support IPv4 and IPv6 addressing, can obtain IP addresses through DHCP or +DHCPv6, and are mapped to a physical Ethernet port. They inherit +characteristics such as speed and duplex from their parent interface and can +be referenced like standard Ethernet interfaces once created. + +```{eval-rst} +Pseudo-Ethernet interfaces may not work in environments that require a + :abbr:`NIC (Network Interface Card)` to have only one MAC address. + This includes: + + * VMware machines with default settings. + * Network switches that permit only a single MAC address. + * xDSL modems that learn the NIC's MAC address. +``` + +## Configuration + +### Common interface configuration + +```{cmdincludemd} /_include/interface-common-with-dhcp.txt +:var0: pseudo-ethernet +:var1: peth0 +``` + +### MACVLAN (pseudo-Ethernet) options + +```{cfgcmd} set interfaces pseudo-ethernet \ source-interface \ + +Assign a physical Ethernet interface to the specified pseudo-Ethernet interface. +``` + +### VLAN + +```{cmdincludemd} /_include/interface-vlan-8021q.txt +:var0: pseudo-ethernet +:var1: peth0 +``` \ No newline at end of file diff --git a/docs/configuration/interfaces/md-sstp-client.md b/docs/configuration/interfaces/md-sstp-client.md new file mode 100644 index 00000000..da98aecd --- /dev/null +++ b/docs/configuration/interfaces/md-sstp-client.md @@ -0,0 +1,170 @@ +--- +lastproofread: '2026-03-16' +--- + +(sstp-client-interface)= + +# SSTP client + +{abbr}`SSTP (Secure Socket Tunneling Protocol)` transports PPP traffic over an +SSL/TLS channel, providing transport-level security through key negotiation, +encryption, and traffic integrity checking. The use of SSL/TLS over TCP port +443 (by default, the port can be changed) allows SSTP to pass through virtually +all firewalls and proxy servers, except for authenticated web proxies. + +:::{note} +VyOS includes a built-in SSTP server. For more information, see +{ref}`sstp`. +::: + +## Configuration + +### Common interface configuration + +```{cmdincludemd} /_include/interface-description.txt +:var0: sstpc +:var1: sstpc0 +``` + +```{cmdincludemd} /_include/interface-disable.txt +:var0: sstpc +:var1: sstpc0 +``` + +```{cmdincludemd} /_include/interface-mtu.txt +:var0: sstpc +:var1: sstpc0 +``` + +```{cmdincludemd} /_include/interface-vrf.txt +:var0: sstpc +:var1: sstpc0 +``` + + +### SSTP client options + +```{cfgcmd} set interfaces sstpc \ no-default-route + +Request an IP address from the SSTP server without installing a default route. + +Example: + +:::{code-block} none +set interfaces sstpc sstpc0 no-default-route +::: +:::{note} Introduced in VyOS 1.4, this command inverts the logic of the former +``default-route`` CLI option. +::: +``` + +```{cfgcmd} set interfaces sstpc \ default-route-distance \ + +Configure the distance for the default gateway provided by the SSTP server. + +Example: + +:::{code-block} none +set interfaces sstpc sstpc0 default-route-distance 220 +::: +``` + +```{cfgcmd} set interfaces sstpc \ no-peer-dns + +Disable the installation of advertised DNS nameservers on the local system. +``` + +```{cfgcmd} set interfaces sstpc \ server \ + +**Configure the remote SSTP server address for the client connection.** + +The address can be either an IP address or a {abbr}`FQDN (Fully Qualified +Domain Name)`. +``` + +```{cfgcmd} set interfaces sstpc \ ip adjust-mss \ + +**Configure the** {abbr}`MSS (Maximum Segment Size)` **advertised in outgoing +TCP SYN packets on the specified interface.** + +By clamping the MSS value in TCP SYN packets, you instruct the remote side not +to send packets larger than the specified size. This helps prevent connection +issues if {abbr}`PMTUD (Path MTU Discovery)` fails. + +The following options are available: + +* ``mss``: Sets the MSS to a specific value in bytes. +* ``clamp-mss-to-pmtu``: Sets the MSS to the interface’s MTU minus 40 bytes for +IPv4 traffic (20 bytes for the IPv4 header and 20 bytes for the TCP header). +This option is recommended to automatically set the proper value. + +:::{note} Introduced in VyOS 1.4, this command replaces the older ``set firewall +options interface adjust-mss `` syntax. +::: +``` + +```{cfgcmd} set interfaces sstpc \ ip disable-forwarding + +**Configure the interface for host or router behavior.** + +If configured, the interface switches to host mode, and IPv4 forwarding is +disabled on it. +``` + +```{cfgcmd} set interfaces sstpc \ ip source-validation \ + +**Configure source IP address validation using** +{abbr}`RPF (Reverse Path Forwarding)` **on this interface, as specified in** +{rfc}`3704`. + +The following options are available: + +* ``strict``: Each incoming packet’s source IP address is checked against the +{abbr}`FIB (Forwarding Information Base)`. If the interface is not the best +route back to that source, validation fails, and the packet is dropped. +* ``loose``: Each incoming packet’s source IP address is checked against the +{abbr}`FIB (Forwarding Information Base)`. If the source IP address is +unreachable through any interface, validation fails. +* ``disable``: No source IP address validation is performed. All incoming +packets are accepted. + +{rfc}`3704` recommends enabling ``strict`` mode to prevent IP spoofing, such as +DDoS attacks. For asymmetric or other complex routing scenarios, use ``loose`` +mode. +``` + + +## Operation + +```{opcmd} show interfaces sstpc \ + +Show detailed information about the specified interface. + +:::{code-block} none +vyos@vyos:~$ show interfaces sstpc sstpc10 +sstpc10: mtu 1500 qdisc pfifo_fast state UNKNOWN group default qlen 3 + link/ppp + inet 192.0.2.5 peer 192.0.2.254/32 scope global sstpc10 + valid_lft forever preferred_lft forever + inet6 fe80::fd53:c7ff:fe8b:144f/64 scope link + valid_lft forever preferred_lft forever + + RX: bytes packets errors dropped overrun mcast + 215 9 0 0 0 0 + TX: bytes packets errors dropped carrier collisions + 539 14 0 0 0 0 +::: +``` + + +### Connect/disconnect + +```{opcmd} disconnect interface \ + +Disconnect the specified interface. +``` + +```{opcmd} connect interface \ + +Initiate a session on the specified interface. +``` \ No newline at end of file diff --git a/docs/configuration/interfaces/md-tunnel.md b/docs/configuration/interfaces/md-tunnel.md new file mode 100644 index 00000000..9c9885d2 --- /dev/null +++ b/docs/configuration/interfaces/md-tunnel.md @@ -0,0 +1,309 @@ +--- +lastproofread: '2026-01-23' +--- + +(tunnel-interface)= + +# Tunnel + +Tunnel interfaces are virtual links that transmit encapsulated traffic between +private networks or hosts across public infrastructure, such as the Internet. +They operate using encapsulation protocols to wrap original traffic for +transport. The supported protocols include {abbr}`GRE (Generic Routing +Encapsulation)`, IPIP, IPIP6, IP6IP6, and 6in4 (SIT). + +While {abbr}`GRE (Generic Routing Encapsulation)` is often the preferred +one-size-fits-all solution due to its versatility, other encapsulation +protocols may be better suited for specific use cases. + +VyOS uses a single tunnel interface type for all of these protocols. There are +no separate {abbr}`GRE (Generic Routing Encapsulation)`, IPIP, or IP6IP6 +interface types; instead, the desired encapsulation protocol is selected within +the `set interfaces tunnel` configuration. + +Configuration options for each protocol are described below. + +:::{warning} +Do not change the encapsulation type for already configured tunnel +interfaces, as this may break their dependent configurations. +::: + +## Common interface configuration + +```{cmdincludemd} /_include/interface-address.txt +:var0: tunnel +:var1: tun0 +``` + +```{cmdincludemd} /_include/interface-common-without-mac.txt +:var0: tunnel +:var1: tun0 +``` + + +## IPIP + +IPIP is a straightforward encapsulation protocol defined in RFC 2003. It +encapsulates one IPv4 packet inside another IPv4 packet. + +Tunnels with IPIP encapsulation do not have protocol-specific configuration +options except for explicitly defining the encapsulation type as IPIP (see +the example below). + +Example: + +```none +set interfaces tunnel tun0 encapsulation ipip +set interfaces tunnel tun0 source-address 192.0.2.10 +set interfaces tunnel tun0 remote 203.0.113.20 +set interfaces tunnel tun0 address 192.168.100.200/24 +``` + + +## IP6IP6 + +IP6IP6 is the IPv6 counterpart to IPIP. It encapsulates one IPv6 packet inside +another IPv6 packet. + +Similar to their IPIP counterparts, tunnels with IP6IP6 encapsulation do not +have protocol-specific configuration options except for explicitly defining +the encapsulation type as IP6IP6. + +Example: + +```none +set interfaces tunnel tun0 encapsulation ip6ip6 +set interfaces tunnel tun0 source-address 2001:db8:aa::1 +set interfaces tunnel tun0 remote 2001:db8:aa::2 +set interfaces tunnel tun0 address 2001:db8:bb::1/64 +``` + + +## IPIP6 + +IPIP6 is an encapsulation protocol that wraps IPv4 packets inside IPv6 packets. + +Similar to IPIP and IP6IP6, protocol-specific configuration for tunnels with +IPIP6 encapsulation only requires defining the encapsulation type as IP6IP6. + +Example: + +```none +set interfaces tunnel tun0 encapsulation ipip6 +set interfaces tunnel tun0 source-address 2001:db8:aa::1 +set interfaces tunnel tun0 remote 2001:db8:aa::2 +set interfaces tunnel tun0 address 192.168.70.80/24 +``` + + +## 6in4 (SIT) + +6in4, also known as {abbr}`SIT (Simple Internet Transition)`, is an +encapsulation protocol defined in {rfc}`4213` that wraps IPv6 packets +inside IPv4 packets. The encapsulating IPv4 headers use IP protocol number 41, +which is reserved exclusively for IPv6 encapsulation. + +The encapsulation process adds a 20-byte IPv4 header to each IPv6 packet. +Consequently, 6in4 tunnel interfaces can transmit IPv6 packets up to 1480 bytes +over an underlying network with a standard MTU of 1500 bytes without +fragmentation. + +6in4 tunnel interfaces are frequently used by IPv6 tunnel brokers (such as +[Hurricane Electric]) to connect isolated IPv6 networks or individual hosts to +the IPv6 internet. + +Example: + +```none +set interfaces tunnel tun0 encapsulation sit +set interfaces tunnel tun0 source-address 192.0.2.10 +set interfaces tunnel tun0 remote 192.0.2.20 +set interfaces tunnel tun0 address 2001:db8:bb::1/64 +``` + +:::{seealso} +For a practical configuration example, see the +{ref}`Tunnelbroker.net (IPv6) ` section. +::: + +## Generic Routing Encapsulation (GRE) + +{abbr}`GRE (Generic Routing Encapsulation)` is a versatile encapsulation +protocol defined in RFC 2784. Unlike simpler protocols such as IPIP, it allows +both IPv4 and IPv6 to be transported through the same tunnel. + +{abbr}`GRE (Generic Routing Encapsulation)` encapsulates original data packets +by adding a {abbr}`GRE (Generic Routing Encapsulation)` header, followed by an +IP header (the delivery header). The delivery header uses IP protocol number 47 +to identify {abbr}`GRE (Generic Routing Encapsulation)`-encapsulated traffic. + +In VyOS, {abbr}`GRE (Generic Routing Encapsulation)` tunnels can be established +over both IPv4 (encapsulation `gre`) and IPv6 (encapsulation `ip6gre`) +transport networks. + +### Configuration + +To configure a {abbr}`GRE (Generic Routing Encapsulation)` tunnel, you need to +define a tunnel source IP address, a tunnel destination IP address, an +encapsulation type ({abbr}`GRE (Generic Routing Encapsulation)`), and a tunnel +interface IP address. + +Example: + +The following example shows how to configure an IPv4/IPv6-over-IPv6 {abbr}`GRE +(Generic Routing Encapsulation)` tunnel between a VyOS router and a Linux host +running `systemd-networkd`. + +**VyOS router:** + +```none +set interfaces tunnel tun101 address '2001:db8:feed:beef::1/126' +set interfaces tunnel tun101 address '192.168.5.1/30' +set interfaces tunnel tun101 encapsulation 'ip6gre' +set interfaces tunnel tun101 source-address '2001:db8:babe:face::3afe:3' +set interfaces tunnel tun101 remote '2001:db8:9bb:3ce::5' +``` + +**Linux** `systemd-networkd`: + +The `systemd-networkd` setup requires two configuration files: `xxx.netdev` +to create the {abbr}`GRE (Generic Routing Encapsulation)` tunnel interface, and +`xxx.network` to assign IP addresses to it. + +```none +# cat /etc/systemd/network/gre-example.netdev +[NetDev] +Name=gre-example +Kind=ip6gre +MTUBytes=14180 + +[Tunnel] +Remote=2001:db8:babe:face::3afe:3 + + +# cat /etc/systemd/network/gre-example.network +[Match] +Name=gre-example + +[Network] +Address=2001:db8:feed:beef::2/126 + +[Address] +Address=192.168.5.2/30 +``` + + +### GRE keys + +A GRE key is an optional 32-bit field in the GRE header that allows multiple +GRE tunnels to operate between the same source and destination endpoints. When +a packet arrives, the receiver checks the GRE key to determine which tunnel +interface should process it. + +Although it may sound security-related, the GRE key is only an identifier and +provides no encryption or data protection. + +Example: + +```none +set interfaces tunnel tun0 source-address 192.0.2.10 +set interfaces tunnel tun0 remote 192.0.2.20 +set interfaces tunnel tun0 address 10.40.50.60/24 +set interfaces tunnel tun0 parameters ip key 10 +``` + +```none +set interfaces tunnel tun1 source-address 192.0.2.10 +set interfaces tunnel tun1 remote 192.0.2.20 +set interfaces tunnel tun1 address 172.16.17.18/24 +set interfaces tunnel tun1 parameters ip key 20 +``` + + +### GRETAP + +Unlike GRE, which encapsulates only Layer 3 (IP) traffic, GRETAP encapsulates +Layer 2 (Ethernet) frames. + +That means that GRETAP tunnel interfaces can be members of a bridge interface. +This allows two geographically distant sites to connect as if they were on the +same LAN. + +GRETAP tunnels can be established over both IPv4 and IPv6 transport networks. + +Example: + +```none +set interfaces bridge br0 member interface eth0 +set interfaces bridge br0 member interface tun0 +set interfaces tunnel tun0 encapsulation gretap +set interfaces tunnel tun0 source-address 198.51.100.2 +set interfaces tunnel tun0 remote 203.0.113.10 +``` + + +### Troubleshooting + +GRE is a standardized tunneling protocol used in many network environments. + +Although the GRE tunnel setup is straightforward, connectivity failures +frequently occur because ACLs or firewall rules block IP protocol 47 or +prevent direct communication between the tunnel endpoints. + +If your GRE tunnel fails to establish, perform these diagnostic steps: + +1\. Verify that the remote peer is reachable from the configured +`source-address`. + +This ensures that the underlying physical path between the two endpoints is +functional. + +```none +vyos@vyos:~$ ping 203.0.113.10 interface 198.51.100.2 count 4 +PING 203.0.113.10 (203.0.113.10) from 198.51.100.2 : 56(84) bytes of data. +64 bytes from 203.0.113.10: icmp_seq=1 ttl=254 time=0.807 ms +64 bytes from 203.0.113.10: icmp_seq=2 ttl=254 time=1.50 ms +64 bytes from 203.0.113.10: icmp_seq=3 ttl=254 time=0.624 ms +64 bytes from 203.0.113.10: icmp_seq=4 ttl=254 time=1.41 ms + +--- 203.0.113.10 ping statistics --- +4 packets transmitted, 4 received, 0% packet loss, time 3007ms +rtt min/avg/max/mdev = 0.624/1.087/1.509/0.381 ms +``` + +2\. Verify that the tunnel interface is correctly configured (with the link type +set to GRE) and is actively processing traffic. + +```none +vyos@vyos:~$ show interfaces tunnel tun100 +tun100@NONE: mtu 1476 qdisc noqueue state UNKNOWN group default qlen 1000 + link/gre 198.51.100.2 peer 203.0.113.10 + inet 10.0.0.1/30 brd 10.0.0.3 scope global tun100 + valid_lft forever preferred_lft forever + inet6 fe80::5efe:c612:2/64 scope link + valid_lft forever preferred_lft forever + + RX: bytes packets errors dropped overrun mcast + 2183 27 0 0 0 0 + TX: bytes packets errors dropped carrier collisions + 836 9 0 0 0 0 +``` + +3\. Test the connection through the tunnel using the private IP addresses +assigned to each tunnel endpoint. + +```none +vyos@vyos:~$ ping 10.0.0.2 interface 10.0.0.1 count 4 +PING 10.0.0.2 (10.0.0.2) from 10.0.0.1 : 56(84) bytes of data. +64 bytes from 10.0.0.2: icmp_seq=1 ttl=255 time=1.05 ms +64 bytes from 10.0.0.2: icmp_seq=2 ttl=255 time=1.88 ms +64 bytes from 10.0.0.2: icmp_seq=3 ttl=255 time=1.98 ms +64 bytes from 10.0.0.2: icmp_seq=4 ttl=255 time=1.98 ms + +--- 10.0.0.2 ping statistics --- +4 packets transmitted, 4 received, 0% packet loss, time 3008ms +rtt min/avg/max/mdev = 1.055/1.729/1.989/0.395 ms +``` + +[hurricane electric]: https://tunnelbroker.net/ +[other proposals]: https://www.isc.org/othersoftware/ diff --git a/docs/configuration/interfaces/md-virtual-ethernet.md b/docs/configuration/interfaces/md-virtual-ethernet.md new file mode 100644 index 00000000..dee1b332 --- /dev/null +++ b/docs/configuration/interfaces/md-virtual-ethernet.md @@ -0,0 +1,119 @@ +--- +lastproofread: '2026-01-26' +--- + +(virtual-ethernet)= + +# Virtual Ethernet + +Virtual Ethernet (veth) interfaces are software-based interfaces that operate +in pairs, creating a tunnel between each other. Traffic transmitted into one +interface of the pair (e.g., `veth0`) is delivered directly to its peer +interface (e.g., `veth1`). + +Veth interfaces are commonly used to connect network namespaces or VRFs, but +they can also function as standalone virtual network interfaces. + +:::{note} +Veth interfaces must be created in pairs, where each interface acts +as the peer of the other. +::: + +## Configuration + +### Common interface configuration + +```{cmdincludemd} /_include/interface-address-with-dhcp.txt +:var0: virtual-ethernet +:var1: veth0 +``` + +```{cmdincludemd} /_include/interface-description.txt +:var0: virtual-ethernet +:var1: veth0 +``` + + +### VLAN + +#### Regular VLANs (802.1q) + +```{cmdincludemd} /_include/interface-vlan-8021q.txt +:var0: virtual-ethernet +:var1: veth0 +``` + + +#### 802.1ad (QinQ) + +```{cmdincludemd} /_include/interface-vlan-8021ad.txt +:var0: virtual-ethernet +:var1: veth0 +``` + +```{cmdincludemd} /_include/interface-disable.txt +:var0: virtual-ethernet +:var1: veth0 +``` + +```{cmdincludemd} /_include/interface-vrf.txt +:var0: virtual-ethernet +:var1: veth0 +``` + + +## Operation + +```{opcmd} show interfaces virtual-ethernet + +Show brief interface information. + +:::{code-block} none +vyos@vyos:~$ show interfaces virtual-ethernet +Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down +Interface IP Address S/L Description +--------- ---------- --- ----------- +veth10 100.64.0.0/31 u/u +veth11 100.64.0.1/31 u/u +::: +``` + +```{opcmd} show interfaces virtual-ethernet \ + +Show detailed interface information. + +:::{code-block} none +vyos@vyos:~$ show interfaces virtual-ethernet veth11 +10: veth11@veth10: mtu 1500 qdisc noqueue master red state UP group default qlen 1000 +link/ether b2:7b:df:47:e9:11 brd ff:ff:ff:ff:ff:ff +inet 100.64.0.1/31 scope global veth11 +valid_lft forever preferred_lft forever +inet6 fe80::b07b:dfff:fe47:e911/64 scope link +valid_lft forever preferred_lft forever + +RX: bytes packets errors dropped overrun mcast +0 0 0 0 0 0 +TX: bytes packets errors dropped carrier collisions +1369707 4267 0 0 0 0 +::: +``` + + +## Example + +The following example shows how to connect the global VRF to VRF ‘red ‘ using +the `veth10` and `veth11` veth pair. + +```none +set interfaces virtual-ethernet veth10 address '100.64.0.0/31' +set interfaces virtual-ethernet veth10 peer-name 'veth11' +set interfaces virtual-ethernet veth11 address '100.64.0.1/31' +set interfaces virtual-ethernet veth11 peer-name 'veth10' +set interfaces virtual-ethernet veth11 vrf 'red' +set vrf name red table '1000' + +vyos@vyos:~$ ping 100.64.0.1 +PING 100.64.0.1 (100.64.0.1) 56(84) bytes of data. +64 bytes from 100.64.0.1: icmp_seq=1 ttl=64 time=0.080 ms +64 bytes from 100.64.0.1: icmp_seq=2 ttl=64 time=0.119 ms +``` diff --git a/docs/configuration/interfaces/md-vti.md b/docs/configuration/interfaces/md-vti.md new file mode 100644 index 00000000..dbd2c88c --- /dev/null +++ b/docs/configuration/interfaces/md-vti.md @@ -0,0 +1,121 @@ +(vti-interface)= + +# VTI (virtual tunnel interface) + +{abbr}`VTIs (virtual tunnel interfaces)` let you create secure, encrypted +tunnels between private networks or hosts across public infrastructure, such as +the Internet. They operate alongside an underlying IPsec tunnel, which handles +encapsulation and encryption, while VTIs function exclusively as routing +interfaces. + +## Configuration + +### Common interface configuration + +```{cmdincludemd} /_include/interface-address.txt +:var0: vti +:var1: vti0 +``` + +```{cmdincludemd} /_include/interface-description.txt +:var0: vti +:var1: vti0 +``` + +```{cmdincludemd} /_include/interface-disable.txt +:var0: vti +:var1: vti0 +``` + +```{cmdincludemd} /_include/interface-ip.txt +:var0: vti +:var1: vti0 +``` + +```{cmdincludemd} /_include/interface-ipv6.txt +:var0: vti +:var1: vti0 +``` + +```{cmdincludemd} /_include/interface-mtu.txt +:var0: vti +:var1: vti0 +``` + +```{cfgcmd} set interfaces vti \ mirror egress \ + +Configure mirroring of outgoing traffic from the specified VTI to the +designated monitor interface. +``` + +```{cfgcmd} set interfaces vti \ mirror ingress \ + +Configure mirroring of incoming traffic from the specified VTI to the +designated monitor interface. +``` + +```{cfgcmd} set interfaces vti \ redirect \ + +Enable redirection of incoming packets to the specified interface. +``` + +```{cmdincludemd} /_include/interface-vrf.txt +:var0: vti +:var1: vti0 +``` + + +## Operation + +```{opcmd} show interfaces vti \ + +Show the operational status and traffic statistics for the specified VTI. +``` + +```{opcmd} show interfaces vti \ brief + +Show a brief operational status summary for the specified VTI. +``` + + +## Example + +**Configure a VTI** + +Assign IPv4 and IPv6 addresses to the VTI, along with a brief description: + +```none +set interfaces vti vti0 address 192.168.2.249/30 +set interfaces vti vti0 address 2001:db8:2::249/64 +set interfaces vti vti0 description "Description" +``` + +Resulting configuration: + +```none +vyos@vyos# show interfaces vti +vti vti0 { + address 192.168.2.249/30 + address 2001:db8:2::249/64 + description "Description" +} +``` + +:::{warning} +When configuring site-to-site IPsec with VTIs, ensure that route +autoinstall is disabled. +::: + +```none +set vpn ipsec options disable-route-autoinstall +``` + +For more information about the IPsec and VTI issue, as well as the +`disable-route-autoinstall` option, see: + + +The root cause of the problem is that VTI tunnels require their traffic +selectors to be set to `0.0.0.0/0` for traffic to match the tunnel, even +though routing decisions are based on netfilter marks. Unless route insertion +is explicitly disabled, strongSWAN incorrectly inserts a default route through +the VTI peer address, causing all traffic to be misrouted. diff --git a/docs/configuration/interfaces/md-vxlan.md b/docs/configuration/interfaces/md-vxlan.md new file mode 100644 index 00000000..8dae75ff --- /dev/null +++ b/docs/configuration/interfaces/md-vxlan.md @@ -0,0 +1,373 @@ +--- +lastproofread: '2026-03-16' +--- + +(vxlan-interface)= + +# VXLAN + +{abbr}`VXLAN (Virtual Extensible LAN)` is a network virtualization technology +that addresses scalability challenges in large cloud computing environments. +It encapsulates Ethernet frames (Layer 2) within UDP datagrams (Layer 4), which +are then transmitted via UDP port 4789, as assigned by IANA. VXLAN endpoints, +called {abbr}`VTEPs (VXLAN tunnel endpoints)`, terminate VXLAN tunnels and can +be either virtual or physical switch ports. + +VXLAN supports up to 16 million logical networks and enables Layer 2 adjacency +across Layer 3 IP networks. It uses multicast or unicast with head-end +replication (HER) to flood broadcast, unknown unicast, and multicast (BUM) +traffic. + +The VXLAN specification was initially developed by VMware, Arista Networks, and +Cisco. Other supporters include Huawei, Broadcom, Citrix, Pica8, Big Switch +Networks, Cumulus Networks, Dell EMC, Ericsson, Mellanox, FreeBSD, OpenBSD, Red +Hat, Joyent, and Juniper Networks. + +VXLAN is officially documented by the IETF in {rfc}`7348`. + +When configuring VXLAN in a VyOS virtual machine, ensure that MAC spoofing +(Hyper-V) or Forged Transmits (ESX) are permitted. Otherwise, the hypervisor +may block forwarded frames. + +:::{note} +Although the IANA-assigned VXLAN port is **4789**, VyOS uses the +Linux default UDP port **8472** for VXLAN interfaces. To ensure compatibility +with other vendors, set the port to the IANA standard **4789**. +::: + +## Configuration + +### Common interface configuration + +```{cmdincludemd} /_include/interface-common-without-dhcp.txt +:var0: vxlan +:var1: vxlan0 +``` + + +### VXLAN-specific options + +```{cfgcmd} set interfaces vxlan \ vni \ + +**Configure a** {abbr}`VNI (VXLAN Network Identifier)` **for the VXLAN +interface.** + +Each VXLAN segment is identified by this 24-bit VNI, allowing up to 16 million +segments to coexist within the same administrative domain. +``` + +```{cfgcmd} set interfaces vxlan \ port \ + +Configure the UDP port of the remote VXLAN endpoint. + +:::{note} +Although the IANA-assigned VXLAN port is **4789**, VyOS uses the +Linux default UDP port **8472** for VXLAN interfaces. +::: +``` + +```{cfgcmd} set interfaces vxlan \ source-address \ + +Configure the source IP address for the VXLAN underlay. + +:::{warning} +This setting is mandatory when deploying VXLAN via L2VPN/EVPN. +::: +``` + +```{cfgcmd} set interfaces vxlan \ gpe + +**Enable the** {abbr}`GPE (Generic Protocol Extension)` **for the VXLAN +interface.** + +To use this feature, you must configure the interface with the ``external`` +parameter. +``` + +```{cfgcmd} set interfaces vxlan \ parameters external + +**Configure the VXLAN interface to use an external control plane, such as BGP +L2VPN/EVPN, for remote endpoint discovery.** + +If not configured, the internal {abbr}`FDB (Forwarding Database)` is used. +``` + +```{cfgcmd} set interfaces vxlan \ parameters neighbor-suppress + +**Enable ARP and ND suppression on the VXLAN interface.** + +This reduces ARP and ND message flooding across the VXLAN network. As defined +in {rfc}`7432#section-10`, participating VTEPs use known MAC-to-IP bindings +to reply to local requests on behalf of remote hosts. +``` + +```{cfgcmd} set interfaces vxlan \ parameters nolearning + +Disable {abbr}`SLLA (Source Link-Layer Address)` and IP address learning on +the VXLAN interface. +``` + +```{cfgcmd} set interfaces vxlan \ parameters vni-filter + +**Enable** {abbr}`VNI (VXLAN Network Identifier)` **filtering on the VXLAN +interface.** + +When enabled, the interface only receives packets with VNIs configured in its +VNI filtering table. + +:::{note} +VNI filtering works only if the interface is configured with the +``external`` parameter. +::: +``` + + +#### Unicast + +```{cfgcmd} set interfaces vxlan \ remote \ + +**Configure the IPv4 or IPv6 address of the remote VTEP.** + +Unlike multicast setups, this command allows you to directly configure the +remote IPv4 or IPv6 address. +``` + + +#### Multicast + +```{cfgcmd} set interfaces vxlan \ source-interface \ + +**Configure the source interface for the VXLAN underlay.** + +All VXLAN traffic is sent and received through the specified interface. +This setting is mandatory when deploying VXLAN over a multicast network. +``` + +```{cfgcmd} set interfaces vxlan \ group \ + +**Configure the IPv4 or IPv6 multicast group address for the VXLAN interface.** + +VXLAN tunnels can be built using either multicast group or unicast IP addresses. +``` + + +## Multicast VXLAN + +Topology: PC4 - Leaf2 - Spine1 - Leaf3 - PC5 + +PC4 uses the IP address `10.0.0.4/24`, and PC5 uses the IP address +`10.0.0.5/24`. Both devices assume they reside within the same broadcast +domain. + +Assume PC4 on Leaf2 pings PC5 on Leaf3. Rather than manually specifying Leaf3 +as the remote endpoint, Leaf2 encapsulates the packet into a UDP datagram and +sends it to the designated multicast address via Spine1. Spine1 forwards the +packet to all leaves in the same multicast group, including Leaf3. Upon +receiving the datagram, Leaf3 forwards it to PC5 and learns that PC4 is +reachable through Leaf2 by inspecting the source IP in the encapsulated +datagram. + +PC5 receives the ping and responds with an echo reply. Leaf3, now aware of +PC4's location, forwards the reply directly to Leaf2's unicast address. Upon +receiving the echo reply, Leaf2 learns that PC5 is reachable through Leaf3. + +After this discovery, subsequent traffic between PC4 and PC5 will not use the +multicast address between the leaves, as both leaves have learned the PCs' +locations. This reduces multicast traffic and network load, improving +scalability as more leaves are added. + +## Single VXLAN device (SVD) + +In VyOS, you can configure multiple **VLAN-to-VNI mappings** for EVPN-VXLAN on +a single container interface, known as a single VXLAN device (SVD). This +enables significant VNI scaling because a separate VXLAN interface is not +required for each VNI. + +```{cfgcmd} set interfaces vxlan \ vlan-to-vni \ vni \ + +**Map a VLAN ID to a VNI on the specified VXLAN interface.** + +The VXLAN interface can be added to a bridge. + +The following example shows an SVD configuration with multiple VLAN-to-VNI +mappings. + +:::{code-block} none +set interfaces bridge br0 member interface vxlan0 +set interfaces vxlan vxlan0 parameters external +set interfaces vxlan vxlan0 source-interface 'dum0' +set interfaces vxlan vxlan0 vlan-to-vni 10 vni '10010' +set interfaces vxlan vxlan0 vlan-to-vni 11 vni '10011' +set interfaces vxlan vxlan0 vlan-to-vni 30 vni '10030' +set interfaces vxlan vxlan0 vlan-to-vni 31 vni '10031' +::: +``` + + +### Example + +The following example demonstrates a multicast VXLAN deployment. + +The setup includes three routers: Spine1, a Cisco IOS router, and Leaf2 and +Leaf3, which are VyOS routers. + +**Topology:** Leaf2 - Spine1 - Leaf3. + +The topology is built using GNS3. + +```none +Spine1: +fa0/2 towards Leaf2, IP-address: 10.1.2.1/24 +fa0/3 towards Leaf3, IP-address: 10.1.3.1/24 + +Leaf2: +Eth0 towards Spine1, IP-address: 10.1.2.2/24 +Eth1 towards a VLAN-aware switch + +Leaf3: +Eth0 towards Spine1, IP-address 10.1.3.3/24 +Eth1 towards a VLAN-aware switch +``` + +**Spine1 configuration:** + +```none +conf t +ip multicast-routing +! +interface fastethernet0/2 + ip address 10.1.2.1 255.255.255.0 + ip pim sparse-dense-mode +! +interface fastethernet0/3 + ip address 10.1.3.1 255.255.255.0 + ip pim sparse-dense-mode +! +router ospf 1 + network 10.0.0.0 0.255.255.255 area 0 +``` + +Multicast routing is required for scalable traffic forwarding between leaves. +{abbr}`PIM (Protocol Independent Multicast)` must be enabled towards the leaves +so the spine can learn from which multicast groups each leaf expects traffic. + +**Leaf2 configuration:** + +```none +set interfaces ethernet eth0 address '10.1.2.2/24' +set protocols ospf area 0 network '10.0.0.0/8' + +! First VXLAN interface +set interfaces bridge br241 address '172.16.241.1/24' +set interfaces bridge br241 member interface 'eth1.241' +set interfaces bridge br241 member interface 'vxlan241' + +set interfaces vxlan vxlan241 group '239.0.0.241' +set interfaces vxlan vxlan241 source-interface 'eth0' +set interfaces vxlan vxlan241 vni '241' + +! Second VXLAN interface +set interfaces bridge br242 address '172.16.242.1/24' +set interfaces bridge br242 member interface 'eth1.242' +set interfaces bridge br242 member interface 'vxlan242' + +set interfaces vxlan vxlan242 group '239.0.0.242' +set interfaces vxlan vxlan242 source-interface 'eth0' +set interfaces vxlan vxlan242 vni '242' +``` + +**Leaf3 configuration:** + +```none +set interfaces ethernet eth0 address '10.1.3.3/24' +set protocols ospf area 0 network '10.0.0.0/8' + +! First VXLAN interface +set interfaces bridge br241 address '172.16.241.1/24' +set interfaces bridge br241 member interface 'eth1.241' +set interfaces bridge br241 member interface 'vxlan241' + +set interfaces vxlan vxlan241 group '239.0.0.241' +set interfaces vxlan vxlan241 source-interface 'eth0' +set interfaces vxlan vxlan241 vni '241' + +! Second VXLAN interface +set interfaces bridge br242 address '172.16.242.1/24' +set interfaces bridge br242 member interface 'eth1.242' +set interfaces bridge br242 member interface 'vxlan242' + +set interfaces vxlan vxlan242 group '239.0.0.242' +set interfaces vxlan vxlan242 source-interface 'eth0' +set interfaces vxlan vxlan242 vni '242' +``` + +The configurations for Leaf2 and Leaf3 are nearly identical. Detailed +explanations for each command are provided below. + +```none +set interfaces bridge br241 address '172.16.241.1/24' +``` + +This command creates a bridge to bind traffic on `eth1` VLAN 241 with the +`vxlan241` interface. The IP address is optional. If configured, it can serve +as the default gateway for each leaf, allowing devices on the VLAN to reach +other subnets. Subnets must be redistributed by {abbr}`OSPF (Open Shortest Path +First)` so the spine can learn how to reach them. To advertise `172.16/12` +networks, change the {abbr}`OSPF (Open Shortest Path First)` network from +`10.0.0.0/8` to `0.0.0.0/0`. + +```none +set interfaces bridge br241 member interface 'eth1.241' +set interfaces bridge br241 member interface 'vxlan241' +``` + +These commands bind `eth1.241` and `vxlan241` as member interfaces of the +same bridge. + +```none +set interfaces vxlan vxlan241 group '239.0.0.241' +``` + +This command configures the multicast group used by all leaves for this VLAN +extension. It must be the same on all leaves that have this interface. + +```none +set interfaces vxlan vxlan241 source-interface 'eth0' +``` + +This command configures the interface that listens for multicast packets. It +can also be a loopback interface. + +```none +set interfaces vxlan vxlan241 vni '241' +``` + +This command configures the unique ID for the VXLAN interface. + +```none +set interfaces vxlan vxlan241 port 12345 +``` + +VyOS uses the Linux default UDP port **8472** for VXLAN interfaces. This +command allows you to configure a different UDP port. + +## Unicast VXLAN + +As an alternative to multicast, you can configure the VXLAN tunnel by +specifying the remote IPv4 address directly. The following updates the previous +multicast example: + +```none +# leaf2 and leaf3 +delete interfaces vxlan vxlan241 group '239.0.0.241' +delete interfaces vxlan vxlan241 source-interface 'eth0' + +# leaf2 +set interfaces vxlan vxlan241 remote 10.1.3.3 + +# leaf3 +set interfaces vxlan vxlan241 remote 10.1.2.2 +``` + +The default UDP port is 8472. To configure a different port, use `set +interfaces vxlan port `. diff --git a/docs/configuration/interfaces/md-wireguard.md b/docs/configuration/interfaces/md-wireguard.md new file mode 100644 index 00000000..121d1df0 --- /dev/null +++ b/docs/configuration/interfaces/md-wireguard.md @@ -0,0 +1,434 @@ +--- +lastproofread: '2026-03-02' +--- + +(wireguard)= + +# WireGuard + +WireGuard is an extremely simple, fast, and modern VPN that utilizes +state-of-the-art cryptography. See for more +information. + +## Site-to-site VPN + +The following diagram illustrates a site-to-site VPN setup. + +:::{figure} /_static/images/wireguard_site2site_diagram.webp +::: + +## Keypairs + +WireGuard requires a keypair, which includes a **private** key +to decrypt incoming traffic, and a **public** key for peer(s) to encrypt +outgoing traffic. + +### Generate keypair + +```{opcmd} generate pki wireguard key-pair + +Generate a keypair: a public and a private key. + +:::{note} +This command only outputs the keys to your console. It neither stores +them in the system nor applies them to the system configuration. +::: + +:::{code-block} none +vyos@vyos:~$ generate pki wireguard key-pair +Private key: iJJyEARGK52Ls1GYRCcFvPuTj7WyWYDo//BknoDU0XY= +Public key: EKY0dxRrSD98QHjfHOK13mZ5PJ7hnddRZt5woB3szyw= +::: +``` + + +```{opcmd} generate pki wireguard key-pair install interface \ + +Generate a keypair and output the private key assignment command for the +specified interface. + +:::{code-block} none +vyos@vyos:~$ generate pki wireguard key-pair install interface wg10 +"generate" CLI command executed from operational level. +Generated private key is not automatically added to the VyOS configuration, use the following configuration mode commands to install key: + +set interfaces wireguard wg10 private-key '4Krkv8h6NkAYMMaBWI957yYDJDMvj9URTHstdlOcDU0=' + +Corresponding public-key to use on peer system is: 'UxDsYT6EnpTIOKUzvMlw2p0sNOKQvFxEdSVrnNrX1Ro=' +::: + +:::{note} +If you invoke this command from configuration mode with the ``run`` +prefix, the generated private key is automatically assigned to the specified +interface. +::: + +:::{code-block} none +vyos@vyos# run generate pki wireguard key-pair install interface wg10 +"generate" CLI command executed from config session. +Generated private-key was imported to CLI! + +Use the following command to verify: show interfaces wireguard wg10 +Corresponding public-key to use on peer system is: '7d9KwabjLhHpJiEJeIGd0CBlao/eTwFOh6xyCovTfG8=' + +vyos@vyos# compare +[edit interfaces] ++wireguard wg10 { ++ private-key CJweb8FC6BU3Loj4PC2pn5V82cDjIPs7G1saW0ZfLWc= ++} +::: +``` + + +```{opcmd} show interfaces wireguard \ public-key + +Show the public key assigned to the interface. + +:::{code-block} none +vyos@vyos:~$ show interfaces wireguard wg01 public-key +EKY0dxRrSD98QHjfHOK13mZ5PJ7hnddRZt5woB3szyw= +::: +``` + +#### Optional + +```{opcmd} generate pki wireguard preshared-key + +Generate a pre-shared key. + +The pre-shared key is optional. It adds an additional layer of symmetric-key +cryptography on top of the asymmetric cryptography. + +:::{code-block} none +vyos@vyos:~$ generate pki wireguard preshared-key +Pre-shared key: OHH2EwZfMNK+1L6BXbYw3bKCtMrfjpR4mCAEeBlFnRs= +::: +``` + +```{opcmd} generate pki wireguard preshared-key install interface \ peer \ + +Generate a pre-shared key and output the key assignment command for the +specified peer. + +:::{code-block} none +vyos@vyos:~$ generate pki wireguard preshared-key install interface wg10 peer foo +"generate" CLI command executed from operational level. +Generated preshared-key is not stored to CLI, use configure mode commands to install key: + +set interfaces wireguard wg10 peer foo preshared-key '32vQ1w1yFKTna8n7Gu7EimubSe2Y63m8bafz55EG3Ro=' + +Pre-shared key: +LuaZ8W6DjsDFJFX3jJzoNqrsXHhvq08JztM9z8LHCs= +::: + +:::{note} +If you invoke this command from configuration mode with the run +prefix, the generated key is automatically assigned to the specified peer. +::: +``` + +## Interface configuration + +The next step is to configure your local WireGuard interface and define the +networks you want to tunnel (`allowed-ips`). + +If your system only initiates connections, specifying the listen port is +optional. If your system accepts incoming connections, you must define a port +for peers to connect to. Otherwise, WireGuard selects a random port at each +reboot, and that may break your peers' ability to connect if that port is not enabled in your firewall rules. + +To configure a WireGuard tunnel, you also need your peer's public key. + +:::{note} +The public key specified in the peer configuration block is always +the **remote** peer's public key, never your local one. +::: + +**Local side configuration** + +The local side is configured with the following parameters: +- Local WireGuard interface IP: `10.1.0.1/30` +- Local listen port: `51820` +- Remote peer name: `to-wg02` +- Remote peer endpoint: `192.0.2.1` on port `51820` +- Remote peer public key: `XMrlPykaxhdAAiSjhtPlvi30NVkvLQliQuKP7AI7CyI=` +- Allowed networks: `192.168.2.0/24` + +```none +set interfaces wireguard wg01 address '10.1.0.1/30' +set interfaces wireguard wg01 description 'VPN-to-wg02' +set interfaces wireguard wg01 peer to-wg02 allowed-ips '192.168.2.0/24' +set interfaces wireguard wg01 peer to-wg02 address '192.0.2.1' +set interfaces wireguard wg01 peer to-wg02 port '51820' +set interfaces wireguard wg01 peer to-wg02 public-key 'XMrlPykaxhdAAiSjhtPlvi30NVkvLQliQuKP7AI7CyI=' +set interfaces wireguard wg01 port '51820' + +set protocols static route 192.168.2.0/24 interface wg01 +``` + +To send traffic destined for `192.168.2.0/24` through the WireGuard interface +(`wg01`), configure a static route. Multiple IP addresses or networks can be +defined and routed. The final check is performed against `allowed-ips`, which +either permits or drops the traffic. + +:::{warning} +You cannot assign the same `allowed-ips` to multiple WireGuard +peers. This is a strict design restriction. For more information, check the +[WireGuard mailing list]. +::: + +```{cfgcmd} set interfaces wireguard \ private-key \ + +Assign a private key to the specified WireGuard interface. + +Example: + +:::{code-block} none +set interfaces wireguard wg01 private-key 'iJJyEARGK52Ls1GYRCcFvPuTj7WyWYDo//BknoDU0XY=' +::: + +To generate a private key, use the following command: +{opcmd}`generate pki wireguard key-pair`. + +To view the public key assigned to the interface so you can share it with a +peer, use the following command: +{opcmd}`show interfaces wireguard wg01 public-key`. +``` + + +```{cmdincludemd} /_include/interface-per-client-thread.txt +:var0: wireguard +:var1: wg01 +``` + +**Remote side configuration** + +```none +set interfaces wireguard wg01 address '10.1.0.2/30' +set interfaces wireguard wg01 description 'VPN-to-wg01' +set interfaces wireguard wg01 peer to-wg01 allowed-ips '192.168.1.0/24' +set interfaces wireguard wg01 peer to-wg01 address '192.0.2.2' +set interfaces wireguard wg01 peer to-wg01 port '51820' +set interfaces wireguard wg01 peer to-wg01 public-key 'EKY0dxRrSD98QHjfHOK13mZ5PJ7hnddRZt5woB3szyw=' +set interfaces wireguard wg01 port '51820' +set interfaces wireguard wg01 private-key 'OLTQY3HuK5qWDgVs6fJR093SwPgOmCKkDI1+vJLGoFU=' + +set protocols static route 192.168.1.0/24 interface wg01 +``` + +## Firewall exceptions + + +To allow WireGuard traffic through the WAN interface, create a firewall +exception: + +```none +set firewall ipv4 name OUTSIDE_LOCAL rule 10 action accept +set firewall ipv4 name OUTSIDE_LOCAL rule 10 description 'Allow established/related' +set firewall ipv4 name OUTSIDE_LOCAL rule 10 state established enable +set firewall ipv4 name OUTSIDE_LOCAL rule 10 state related enable +set firewall ipv4 name OUTSIDE_LOCAL rule 20 action accept +set firewall ipv4 name OUTSIDE_LOCAL rule 20 description WireGuard_IN +set firewall ipv4 name OUTSIDE_LOCAL rule 20 destination port 51820 +set firewall ipv4 name OUTSIDE_LOCAL rule 20 log enable +set firewall ipv4 name OUTSIDE_LOCAL rule 20 protocol udp +``` + +Ensure that the OUTSIDE_LOCAL firewall group is applied to the WAN interface +and in an input (local) direction. + +```none +set firewall ipv4 input filter rule 10 action jump +set firewall ipv4 input filter rule 10 jump-target 'OUTSIDE_LOCAL' +set firewall ipv4 input filter rule 10 inbound-interface name 'eth0' +``` + +Verify that your firewall rules permit traffic. If so, your WireGuard VPN +should be operational. + +```none +wg01# ping 192.168.1.1 +PING 192.168.1.1 (192.168.1.1) 56(84) bytes of data. +64 bytes from 192.168.1.1: icmp_seq=1 ttl=64 time=1.16 ms +64 bytes from 192.168.1.1: icmp_seq=2 ttl=64 time=1.77 ms + +wg02# ping 192.168.2.1 +PING 192.168.2.1 (192.168.2.1) 56(84) bytes of data. +64 bytes from 192.168.2.1: icmp_seq=1 ttl=64 time=4.40 ms +64 bytes from 192.168.2.1: icmp_seq=2 ttl=64 time=1.02 ms +``` + +An additional layer of symmetric-key cryptography can be used on top of the +asymmetric cryptography. This is optional. + +```none +vyos@vyos:~$ generate pki wireguard preshared-key +Pre-shared key: rvVDOoc2IYEnV+k5p7TNAmHBMEGTHbPU8Qqg8c/sUqc= +``` + +Copy the key, as it is not stored locally. Since it is a symmetric key, only +you and your peer should know its contents. Distribute the key securely. + +```none +wg01# set interfaces wireguard wg01 peer to-wg02 preshared-key 'rvVDOoc2IYEnV+k5p7TNAmHBMEGTHbPU8Qqg8c/sUqc=' +wg02# set interfaces wireguard wg01 peer to-wg01 preshared-key 'rvVDOoc2IYEnV+k5p7TNAmHBMEGTHbPU8Qqg8c/sUqc=' +``` + +## Remote access (road warrior) + + +With WireGuard, a road warrior VPN configuration is similar to a site-to-site +VPN. It just omits the `address` and `port` statements. + + +In the following example, the IP addresses for remote clients are defined +within each peer configuration. This allows peers to communicate with each +other. + + +Additionally, this setup uses a `persistent-keepalive` flag set to 15 seconds +to keep the connection alive. This setting is mainly relevant if a peer is +behind NAT and cannot be reached if the connection is lost. For effectiveness, +the value should be lower than the UDP timeout. + +```none +wireguard wg01 { + address 10.172.24.1/24 + address 2001:db8:470:22::1/64 + description RoadWarrior + peer MacBook { + allowed-ips 10.172.24.30/32 + allowed-ips 2001:db8:470:22::30/128 + persistent-keepalive 15 + pubkey F5MbW7ye7DsoxdOaixjdrudshjjxN5UdNV+pGFHqehc= + } + peer iPhone { + allowed-ips 10.172.24.20/32 + allowed-ips 2001:db8:470:22::20/128 + persistent-keepalive 15 + pubkey BknHcLFo8nOo8Dwq2CjaC/TedchKQ0ebxC7GYn7Al00= + } + port 2224 + private-key OLTQY3HuK5qWDgVs6fJR093SwPgOmCKkDI1+vJLGoFU= +} +``` + +Below is the configuration for the iPhone peer. The `AllowedIPs` wildcard +setting directs all IPv4 and IPv6 traffic through the VPN connection. + +```none +[Interface] +PrivateKey = ARAKLSDJsadlkfjasdfiowqeruriowqeuasdf= +Address = 10.172.24.20/24, 2001:db8:470:22::20/64 +DNS = 10.0.0.53, 10.0.0.54 + +[Peer] +PublicKey = RIbtUTCfgzNjnLNPQ/ulkGnnB2vMWHm7l2H/xUfbyjc= +AllowedIPs = 0.0.0.0/0, ::/0 +Endpoint = 192.0.2.1:2224 +PersistentKeepalive = 15 +``` + +To enable split tunneling, specify the remote subnets. This ensures that only +traffic destined for the remote site is sent through the tunnel, while all +other traffic remains unaffected. + +```none +[Interface] +PrivateKey = 8Iasdfweirousd1EVGUk5XsT+wYFZ9mhPnQhmjzaJE6Go= +Address = 10.172.24.30/24, 2001:db8:470:22::30/64 + +[Peer] +PublicKey = RIbtUTCfgzNjnLNPQ/ulkGnnB2vMWHm7l2H/xUfbyjc= +AllowedIPs = 10.172.24.30/24, 2001:db8:470:22::/64 +Endpoint = 192.0.2.1:2224 +PersistentKeepalive = 15 +``` + +## Operational commands + + +### Status + +```{opcmd} show interfaces wireguard wg01 summary + +Show information about the WireGuard service, including the latest handshake. + +:::{code-block} none +vyos@vyos:~$ show interfaces wireguard wg01 summary +interface: wg01 +public key: +private key: (hidden) +listening port: 51820 + +peer: +endpoint: +allowed ips: 10.69.69.2/32 +latest handshake: 23 hours, 45 minutes, 26 seconds ago +transfer: 1.26 MiB received, 6.47 MiB sent +::: +``` + + +```{opcmd} show interfaces wireguard + +Show a list of all WireGuard interfaces. + +:::{code-block} none +Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down +Interface IP Address S/L Description +--------- ---------- --- ----------- +wg01 10.0.0.1/24 u/u +::: +``` + +```{opcmd} show interfaces wireguard \ + +Show general information about a specific WireGuard interface. + +:::{code-block} none +vyos@vyos:~$ show interfaces wireguard wg01 +interface: wg01 +address: 10.0.0.1/24 +public key: h1HkYlSuHdJN6Qv4Hz4bBzjGg5WUty+U1L7DJsZy1iE= +private key: (hidden) +listening port: 41751 +RX: bytes packets errors dropped overrun mcast +0 0 0 0 0 0 +TX: bytes packets errors dropped carrier collisions +0 0 0 0 0 0 +::: +``` + +## Remote access (road warrior) clients + +Some users connect mobile devices to their VyOS router using WireGuard. To +simplify deployment, generate a per-mobile configuration from the VyOS CLI. + +:::{warning} +From a security perspective, it is not recommended to let a third +party create and share the private key for a secure connection. You should +create the private portion yourself and hand out only the public key. +::: + +```{opcmd} generate wireguard client-config \ interface \ server \ address \ + +**Generate a client configuration file that establishes a connection to the +specified interface.** + +The public key from the specified interface is automatically included in the +configuration file. + +The command also generates a configuration snippet that can be copied into the +VyOS CLI. The ```` you provide will be used as the peer name in the +snippet. + +You must also specify the IP address or FQDN of the server the client connects +to. The address parameter can be used twice to assign both an IPv4 (/32) and +an IPv6 (/128) address to the client. + +:::{figure} /_static/images/wireguard_qrcode.webp +:alt: WireGuard Client QR code +::: +``` + +[wireguard mailing list]: https://lists.zx2c4.com/pipermail/wireguard/2018-December/003704.html diff --git a/docs/configuration/interfaces/md-wireless.md b/docs/configuration/interfaces/md-wireless.md new file mode 100644 index 00000000..9e6b7c99 --- /dev/null +++ b/docs/configuration/interfaces/md-wireless.md @@ -0,0 +1,923 @@ +--- +lastproofread: '2026-03-23' +--- + +(wireless-interface)= + +# Wireless LAN / Wi-Fi + +{abbr}`WLAN (Wireless LAN)` interfaces provide 802.11 (a/b/g/n/ac) wireless +connectivity, referred to as Wi-Fi, and operate in one of the following +modes: + +- {abbr}`WAP (Wireless Access-Point)` mode provides network access to connecting + stations if the physical hardware supports acting as a WAP +- Station mode acts as a Wi-Fi client accessing the network through an available + WAP +- Monitor mode lets the system passively monitor wireless traffic + +If the system detects an unconfigured wireless device, it will be automatically +added to the configuration tree, specifying any detected settings (for example, +its MAC address) and configured to run in monitor mode. + +## Configuration + +### Common interface configuration + +```{cmdincludemd} /_include/interface-common-with-dhcp.txt +:var0: wireless +:var1: wlan0 +``` + + +### System-wide configuration + +```{cfgcmd} set system wireless country-code \ + +Country code (ISO/IEC 3166-1). Used to set regulatory domain. Set as needed +to indicate country in which device is operating. This can limit available +channels and transmit power. + +:::{note} +This option is mandatory in ``access-point`` mode. +::: +``` + + +### Wireless options + +```{cfgcmd} set interfaces wireless \ channel \ + +Configure the IEEE 802.11 wireless radio channel for the interface. +Channel allocation depends on the frequency band: +* **2.4 GHz** (802.11b/g/n/ax): Channels range from 1 to 14. +* **5 GHz** (802.11a/h/j/n/ac/ax): Channels range from 34 to 177. +* **6 GHz** (802.11ax): Channels range from 1 to 233. +* **Automatic channel selection:** 0. +``` + +```{cfgcmd} set interfaces wireless \ disable-broadcast-ssid + +Send empty SSID in beacons and ignore probe request frames that do not specify +full SSID, i.e., require stations to know the SSID. +``` + +```{cfgcmd} set interfaces wireless \ expunge-failing-stations + +Disassociate stations based on excessive transmission failures or other +indications of connection loss. + +This depends on the driver capabilities and may not be available with all +drivers. +``` + +```{cfgcmd} set interfaces wireless \ isolate-stations + +Client isolation can be used to prevent low-level bridging of frames between +associated stations in the BSS. + +By default, this bridging is allowed. +``` + +```{cfgcmd} set interfaces wireless \ max-stations \ + +Maximum number of stations allowed in station table. New stations will be +rejected after the station table is full. IEEE 802.11 has a limit of 2007 +different association IDs, so this number should not be larger than that. + +This defaults to 2007. +``` + +```{cfgcmd} set interfaces wireless \ mgmt-frame-protection + +Management Frame Protection (MFP) according to IEEE 802.11w + +:::{note} +{abbr}`MFP (Management Frame Protection)` is required for WPA3. +::: +``` + +```{cfgcmd} set interfaces wireless \ enable-bf-protection + +Beacon Protection: management frame protection for Beacon frames. + +:::{note} +This option requires {abbr}`MFP (Management Frame Protection)` +to be enabled. +::: +``` + +```{cfgcmd} set interfaces wireless \ mode \ + +Operation mode of wireless radio. +* ``a`` - 802.11a - 54 Mbits/sec +* ``b`` - 802.11b - 11 Mbits/sec +* ``g`` - 802.11g - 54 Mbits/sec (default) +* ``n`` - 802.11n - 600 Mbits/sec +* ``ac`` - 802.11ac - 1300 Mbits/sec +* ``ax`` - 802.11ax - exceeds 1GBit/sec + +:::{note} +In VyOS, 802.11ax is only implemented for 2.4GHz and 6GHz. +::: +``` + +```{cfgcmd} set interfaces wireless \ physical-device \ + +Wireless hardware device used as underlay radio. + +This defaults to phy0. +``` + +```{cfgcmd} set interfaces wireless \ reduce-transmit-power \ + +Adds the Power Constraint information element to Beacon and Probe Response +frames. + +This option adds the Power Constraint information element when applicable +and the Country information element is configured. The Power Constraint +element is required by Transmit Power Control. + +Valid values are 0..255. +``` + +```{cfgcmd} set interfaces wireless \ ssid \ + +SSID to be used in IEEE 802.11 management frames +``` + +```{cfgcmd} set interfaces wireless \ type \ + +Wireless device type for this interface +* ``access-point``: Forwards packets between other nodes. +* ``station``: Connects to another {abbr}`AP (Access Point)`. +* ``monitor``: Passively monitors all packets on the frequency/channel. +``` + +```{cmdincludemd} /_include/interface-per-client-thread.txt +:var0: wireless +:var1: wlan0 +``` + + +#### PPDU + +```{cfgcmd} set interfaces wireless \ capabilities require-ht + +``` +```{cfgcmd} set interfaces wireless \ capabilities require-vht +``` + +```{cfgcmd} set interfaces wireless \ capabilities require-he +``` + +##### HT (High Throughput) capabilities (802.11n) + +> Configuring HT mode options is required when using 802.11n or +> 802.11ax at 2.4GHz. + +```{cfgcmd} set interfaces wireless \ capabilities ht 40mhz-incapable + +Device is incapable of 40 MHz, do not advertise. This sets ``[40-INTOLERANT]`` +``` + +```{cfgcmd} set interfaces wireless \ capabilities ht auto-powersave + +WMM-PS Unscheduled Automatic Power Save Delivery [U-APSD] +``` + +```{cfgcmd} set interfaces wireless \ capabilities ht channel-set-width \ + +Supported channel width set. +* ``ht20`` - 20 MHz channel width +* ``ht40-`` - Both 20 MHz and 40 MHz with secondary channel below the primary +channel +* ``ht40+`` - Both 20 MHz and 40 MHz with secondary channel above the primary +channel + +:::{note} +Channel availability for HT40- and HT40+ is limited. The following +table lists channels permitted for HT40- and HT40+ according to IEEE +802.11n Annex J. Channel availability may vary by location. + + ::::{code-block} none + freq HT40- HT40+ + 2.4 GHz 5-13 1-7 (1-9 in Europe/Japan) + 5 GHz 40,48,56,64 36,44,52,60 + :::: +::: + +:::{note} +40 MHz channels may switch their primary and secondary channels if +needed or creation of 40 MHz channel may be rejected based on overlapping +BSSes. These changes are done automatically when hostapd is setting up the +40 MHz channel. +::: +``` + +```{cfgcmd} set interfaces wireless \ capabilities ht delayed-block-ack + +Enable HT-delayed Block Ack ``[DELAYED-BA]`` +``` + +```{cfgcmd} set interfaces wireless \ capabilities ht dsss-cck-40 + +DSSS/CCK Mode in 40 MHz, this sets ``[DSSS_CCK-40]`` +``` + +```{cfgcmd} set interfaces wireless \ capabilities ht greenfield + +This enables the greenfield option which sets the ``[GF]`` option +``` + +```{cfgcmd} set interfaces wireless \ capabilities ht ldpc + +Enable LDPC coding capability +``` + +```{cfgcmd} set interfaces wireless \ capabilities ht lsig-protection + +Enable L-SIG TXOP protection capability +``` + +```{cfgcmd} set interfaces wireless \ capabilities ht max-amsdu \<3839 | 7935\> + +Maximum A-MSDU length 3839 (default) or 7935 octets +``` + +```{cfgcmd} set interfaces wireless \ capabilities ht short-gi \<20 | 40\> + +Short GI capabilities for 20 and 40 MHz +``` + +```{cfgcmd} set interfaces wireless \ capabilities ht smps \ + +Spatial Multiplexing Power Save (SMPS) settings +``` + +```{cfgcmd} set interfaces wireless \ capabilities ht stbc rx \ + +Enable receiving PPDU using STBC (Space Time Block Coding) +``` + +```{cfgcmd} set interfaces wireless \ capabilities ht stbc tx + +Enable sending PPDU using STBC (Space Time Block Coding) +``` + +##### VHT (Very High Throughput) capabilities (802.11ac) + +```{cfgcmd} set interfaces wireless \ capabilities vht antenna-count \ +``` + +% +% Number of antennas on this card + +```{cfgcmd} set interfaces wireless \ capabilities vht antenna-pattern-fixed + +Set if antenna pattern does not change during the lifetime of an association +``` + +```{cfgcmd} set interfaces wireless \ capabilities vht beamform \ + +Beamforming capabilities: +* ``single-user-beamformer`` - Support for operation as +single user beamformer +* ``single-user-beamformee`` - Support for operation as +single user beamformee +* ``multi-user-beamformer`` - Support for operation as +multi user beamformer +* ``multi-user-beamformee`` - Support for operation as +multi user beamformee +``` + +```{cfgcmd} set interfaces wireless \ capabilities vht center-channel-freq \ \ + +VHT operating channel center frequency - center freq 1 +(for use with 80, 80+80 and 160 modes) + +VHT operating channel center frequency - center freq 2 +(for use with the 80+80 mode) + +\ must be from 34 - 173. For 80 MHz channels it should be channel + 6. +``` + +```{cfgcmd} set interfaces wireless \ capabilities vht channel-set-width \<0 | 1 | 2 | 3\> + +* ``0`` - 20 or 40 MHz channel width (default) +* ``1`` - 80 MHz channel width +* ``2`` - 160 MHz channel width +* ``3`` - 80+80 MHz channel width +``` + +```{cfgcmd} set interfaces wireless \ capabilities vht ldpc + +Enable LDPC (Low Density Parity Check) coding capability +``` + +```{cfgcmd} set interfaces wireless \ capabilities vht link-adaptation + +VHT link adaptation capabilities +``` + +```{cfgcmd} set interfaces wireless \ capabilities vht max-mpdu \ + +Increase Maximum MPDU length to 7991 or 11454 octets (default 3895 octets) +``` + +```{cfgcmd} set interfaces wireless \ capabilities vht max-mpdu-exp \ + +Set the maximum length of A-MPDU pre-EOF padding that the station can +receive +``` + +```{cfgcmd} set interfaces wireless \ capabilities vht short-gi \<80 | 160\> + +Short GI capabilities +``` + +```{cfgcmd} set interfaces wireless \ capabilities vht stbc rx \ + +Enable receiving PPDU using STBC (Space Time Block Coding) +``` + +```{cfgcmd} set interfaces wireless \ capabilities vht stbc tx + +Enable sending PPDU using STBC (Space Time Block Coding) +``` + +```{cfgcmd} set interfaces wireless \ capabilities vht tx-powersave + +Enable VHT TXOP Power Save Mode +``` + +```{cfgcmd} set interfaces wireless \ capabilities vht vht-cf + +Station supports receiving VHT variant HT Control field +``` + +##### HE (High Efficiency) capabilities (802.11ax) + +```{cfgcmd} set interfaces wireless \ capabilities he antenna-pattern-fixed + +Tell the AP that antenna positions are fixed and will not change +during the lifetime of an association. +``` + +```{cfgcmd} set interfaces wireless \ capabilities he beamform \ + +Beamforming capabilities: +* ``single-user-beamformer`` - Support for operation as +single user beamformer +* ``single-user-beamformee`` - Support for operation as +single user beamformee +* ``multi-user-beamformer`` - Support for operation as multi +user beamformer +``` + +```{cfgcmd} set interfaces wireless \ capabilities he bss-color \ + +BSS coloring helps to prevent channel jamming when multiple APs use +the same channels. + +Valid values are 1..63 +``` + +```{cfgcmd} set interfaces wireless \ capabilities he center-channel-freq \ \ + +HE operating channel center frequency - center freq 1 +(for use with 80, 80+80 and 160 modes) + +HE operating channel center frequency - center freq 2 +(for use with the 80+80 mode) + +\ must be within 1..233. For 80 MHz channels it should be +channel + 6 and for 160 MHz channels, it should be channel + 14. +``` + +```{cfgcmd} set interfaces wireless \ capabilities he channel-set-width \ + +\ must be one of: + +* ``81`` - 20 MHz channel width (2.4GHz) +* ``83`` - 40 MHz channel width, secondary 20MHz channel above primary +channel (2.4GHz) +* ``84`` - 40 MHz channel width, secondary 20MHz channel below primary +channel (2.4GHz) +* ``131`` - 20 MHz channel width (6GHz) +* ``132`` - 40 MHz channel width (6GHz) +* ``133`` - 80 MHz channel width (6GHz) +* ``134`` - 160 MHz channel width (6GHz) +* ``135`` - 80+80 MHz channel width (6GHz) +``` + +```{cfgcmd} set interfaces wireless \ capabilities he coding-scheme \ + +This setting configures Spatial Stream and Modulation Coding Scheme +settings for HE mode (HE-MCS). It is usually not needed to set this +explicitly, but it might help with some WiFi adapters. + +\ must be one of: +* ``0`` - HE-MCS 0-7 +* ``1`` - HE-MCS 0-9 +* ``2`` - HE-MCS 0-11 +* ``3`` - HE-MCS is not supported +``` + +### Wireless options (Station/Client) + +The example creates a wireless station (commonly referred to as Wi-Fi client) +that accesses the network through the WAP defined in the above example. The +default physical device (`phy0`) is used. + +```none +set system wireless country-code de +set interfaces wireless wlan0 type station +set interfaces wireless wlan0 address dhcp +set interfaces wireless wlan0 ssid 'TEST' +set interfaces wireless wlan0 security wpa passphrase '12345678' +``` + +Resulting configuration: + +```none +system { + wireless { + country-code de + } +} +interfaces { + wireless wlan0 { + address dhcp + security { + wpa { + passphrase "12345678" + } + } + ssid TEST + type station + } +``` + +### Security + +{abbr}`WPA (Wi-Fi Protected Access)`, WPA2 Enterprise and WPA3 Enterprise in +combination with 802.1X based authentication can be used to authenticate +users or computers in a domain. + +The wireless client (supplicant) authenticates against the RADIUS server +(authentication server) using an {abbr}`EAP (Extensible Authentication +Protocol)` method configured on the RADIUS server. The WAP (also referred +to as authenticator) role is to send all authentication messages between the +supplicant and the configured authentication server, thus the RADIUS server +is responsible for authenticating the users. + +The WAP in this example has the following characteristics: +- IP address `192.168.2.1/24` +- Network ID (SSID) `Enterprise-TEST` +- WPA passphrase `12345678` +- Use 802.11n protocol +- Wireless channel `1` +- RADIUS server at `192.168.3.10` with shared-secret `VyOSPassword` + +```none +set system wireless country-code de +set interfaces wireless wlan0 address '192.168.2.1/24' +set interfaces wireless wlan0 type access-point +set interfaces wireless wlan0 channel 1 +set interfaces wireless wlan0 mode n +set interfaces wireless wlan0 ssid 'Enterprise-TEST' +set interfaces wireless wlan0 security wpa mode wpa2 +set interfaces wireless wlan0 security wpa cipher CCMP +set interfaces wireless wlan0 security wpa radius server 192.168.3.10 key 'VyOSPassword' +set interfaces wireless wlan0 security wpa radius server 192.168.3.10 port 1812 +``` + +Resulting configuration: + +```none +system { + wireless { + country-code de + } +} +interfaces { + [...] + wireless wlan0 { + address 192.168.2.1/24 + channel 1 + mode n + security { + wpa { + cipher CCMP + mode wpa2 + radius { + server 192.168.3.10 { + key 'VyOSPassword' + port 1812 + } + } + } + } + ssid "Enterprise-TEST" + type access-point + } +} +``` + +### VLAN +#### Regular VLANs (802.1q) + +```{cmdincludemd} /_include/interface-vlan-8021q.txt +:var0: wireless +:var1: wlan0 +``` + +#### QinQ (802.1ad) + +```{cmdincludemd} /_include/interface-vlan-8021ad.txt +:var0: wireless +:var1: wlan0 +``` + +## Operation + +```{opcmd} show interfaces wireless info +``` + +Use this command to view operational status and wireless-specific information +about all wireless interfaces. + +```none +vyos@vyos:~$ show interfaces wireless info +Interface Type SSID Channel +wlan0 access-point VyOS-TEST-0 1 +``` + +```{opcmd} show interfaces wireless detail +``` + +Show the operational status and detailed wireless-specific +information about all wireless interfaces. + +```none +vyos@vyos:~$ show interfaces wireless detail +wlan0: mtu 1500 qdisc noqueue state UP group default qlen 1000 + link/ether XX:XX:XX:XX:XX:c3 brd XX:XX:XX:XX:XX:ff + inet xxx.xxx.99.254/24 scope global wlan0 + valid_lft forever preferred_lft forever + inet6 fe80::xxxx:xxxx:fe54:2fc3/64 scope link + valid_lft forever preferred_lft forever + + RX: bytes packets errors dropped overrun mcast + 66072 282 0 0 0 0 + TX: bytes packets errors dropped carrier collisions + 83413 430 0 0 0 0 + +wlan1: mtu 1500 qdisc noqueue state UP group default qlen 1000 + link/ether XX:XX:XX:XX:XX:c3 brd XX:XX:XX:XX:XX:ff + inet xxx.xxx.100.254/24 scope global wlan0 + valid_lft forever preferred_lft forever + inet6 fe80::xxxx:xxxx:ffff:2ed3/64 scope link + valid_lft forever preferred_lft forever + + RX: bytes packets errors dropped overrun mcast + 166072 5282 0 0 0 0 + TX: bytes packets errors dropped carrier collisions + 183413 5430 0 0 0 0 +``` + +```{opcmd} show interfaces wireless \ +``` + +This command shows both status and statistics on the specified wireless +interface. The wireless interface identifier can range from wlan0 to wlan999. + +```none +vyos@vyos:~$ show interfaces wireless wlan0 +wlan0: mtu 1500 qdisc noqueue state UP group default qlen 1000 + link/ether XX:XX:XX:XX:XX:c3 brd XX:XX:XX:XX:XX:ff + inet xxx.xxx.99.254/24 scope global wlan0 + valid_lft forever preferred_lft forever + inet6 fe80::xxxx:xxxx:fe54:2fc3/64 scope link + valid_lft forever preferred_lft forever + + RX: bytes packets errors dropped overrun mcast + 66072 282 0 0 0 0 + TX: bytes packets errors dropped carrier collisions + 83413 430 0 0 0 0 +``` + +```{opcmd} show interfaces wireless \ brief +``` + +This command gives a brief status overview of a specified wireless interface. +The wireless interface identifier can range from wlan0 to wlan999. + +```none +vyos@vyos:~$ show interfaces wireless wlan0 brief +Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down +Interface IP Address S/L Description +--------- ---------- --- ----------- +wlan0 192.168.2.254/24 u/u +``` + +```{opcmd} show interfaces wireless \ queue +``` + +Use this command to view wireless interface queue information. +The wireless interface identifier can range from wlan0 to wlan999. + +```none +vyos@vyos:~$ show interfaces wireless wlan0 queue +qdisc pfifo_fast 0: root bands 3 priomap 1 2 2 2 1 2 0 0 1 1 1 1 1 1 1 1 + Sent 810323 bytes 6016 pkt (dropped 0, overlimits 0 requeues 0) + rate 0bit 0pps backlog 0b 0p requeues 0 +``` + +```{opcmd} show interfaces wireless \ scan +``` + +This command is used to retrieve information about WAP within the range of your +wireless interface. This command is useful on wireless interfaces configured +in station mode. + +:::{note} +Scanning is not supported on all wireless drivers and wireless +hardware. Refer to your driver and wireless hardware documentation for +further details. +::: +```none +vyos@vyos:~$ show interfaces wireless wlan0 scan +Address SSID Channel Signal (dbm) +00:53:3b:88:6e:d8 WLAN-576405 1 -64.00 +00:53:3b:88:6e:da Telekom_FON 1 -64.00 +00:53:00:f2:c2:a4 BabyView_F2C2A4 6 -60.00 +00:53:3b:88:6e:d6 Telekom_FON 100 -72.00 +00:53:3b:88:6e:d4 WLAN-576405 100 -71.00 +00:53:44:a4:96:ec KabelBox-4DC8 56 -81.00 +00:53:d9:7a:67:c2 WLAN-741980 1 -75.00 +00:53:7c:99:ce:76 Vodafone Homespot 1 -86.00 +00:53:44:a4:97:21 KabelBox-4DC8 1 -78.00 +00:53:44:a4:97:21 Vodafone Hotspot 1 -79.00 +00:53:44:a4:97:21 Vodafone Homespot 1 -79.00 +00:53:86:40:30:da Telekom_FON 1 -86.00 +00:53:7c:99:ce:76 Vodafone Hotspot 1 -86.00 +00:53:44:46:d2:0b Vodafone Hotspot 1 -87.00 +``` + +## Examples + +The following example creates a WAP. When configuring multiple WAP interfaces, +you must specify unique IP addresses, channels, Network IDs commonly referred +to as {abbr}`SSID (Service Set Identifier)`, and MAC addresses. + +The WAP in this example has the following characteristics: +- IP address `192.168.2.1/24` +- Network ID (SSID) `TEST` +- WPA passphrase `12345678` +- Use 802.11n protocol +- Wireless channel `1` + +```none +set system wireless country-code de +set interfaces wireless wlan0 address '192.168.2.1/24' +set interfaces wireless wlan0 type access-point +set interfaces wireless wlan0 channel 1 +set interfaces wireless wlan0 mode n +set interfaces wireless wlan0 ssid 'TEST' +set interfaces wireless wlan0 security wpa mode wpa2 +set interfaces wireless wlan0 security wpa cipher CCMP +set interfaces wireless wlan0 security wpa passphrase '12345678' +``` + +Resulting configuration: + +```none +system { + wireless { + country-code de + } +} +interfaces { + [...] + wireless wlan0 { + address 192.168.2.1/24 + channel 1 + mode n + security { + wpa { + cipher CCMP + mode wpa2 + passphrase "12345678" + } + } + ssid "TEST" + type access-point + } +} +``` + +To enable access point functionality, configure a DHCP server for this +interface's network, or add the interface to an existing local bridge +(see {ref}`bridge-interface` for details). + +### Wi-Fi 6/6E (802.11ax) + +The following examples configure Wi-Fi 6 (2.4 GHz) and Wi-Fi 6E (6 GHz) +{abbr}`APs (Access Points)` with the following parameters: +- Network ID (SSID): `test.ax` +- WPA passphrase: `super-dooper-secure-passphrase` +- Protocol: 802.11ax +- Wireless channel for 2.4 GHz: `11` +- Wireless channel for 6 GHz: `5` + +#### Example configuration: Wi-Fi 6 at 2.4 GHz + +You may expect real throughput around 10 MB/s or higher in crowded areas. + +```none +set system wireless country-code de +set interfaces wireless wlan0 capabilities he antenna-pattern-fixed +set interfaces wireless wlan0 capabilities he beamform multi-user-beamformer +set interfaces wireless wlan0 capabilities he beamform single-user-beamformee +set interfaces wireless wlan0 capabilities he beamform single-user-beamformer +set interfaces wireless wlan0 capabilities he bss-color 13 +set interfaces wireless wlan0 capabilities he channel-set-width 81 +set interfaces wireless wlan0 capabilities ht 40mhz-incapable +set interfaces wireless wlan0 capabilities ht channel-set-width ht20 +set interfaces wireless wlan0 capabilities ht channel-set-width ht40+ +set interfaces wireless wlan0 capabilities ht channel-set-width ht40- +set interfaces wireless wlan0 capabilities ht short-gi 20 +set interfaces wireless wlan0 capabilities ht short-gi 40 +set interfaces wireless wlan0 capabilities ht stbc rx 2 +set interfaces wireless wlan0 capabilities ht stbc tx +set interfaces wireless wlan0 channel 11 +set interfaces wireless wlan0 description "802.11ax 2.4GHz" +set interfaces wireless wlan0 mode ax +set interfaces wireless wlan0 security wpa cipher CCMP +set interfaces wireless wlan0 security wpa cipher CCMP-256 +set interfaces wireless wlan0 security wpa cipher GCMP-256 +set interfaces wireless wlan0 security wpa cipher GCMP +set interfaces wireless wlan0 security wpa mode wpa2 +set interfaces wireless wlan0 security wpa passphrase super-dooper-secure-passphrase +set interfaces wireless wlan0 ssid test.ax +set interfaces wireless wlan0 type access-point +commit +``` + +Resulting configuration: + +```none +system { + wireless { + country-code de + } +} +interfaces { + [...] + wireless wlan0 { + capabilities { + he { + antenna-pattern-fixed + beamform { + multi-user-beamformer + single-user-beamformee + single-user-beamformer + } + bss-color 13 + channel-set-width 81 + } + ht { + 40mhz-incapable + channel-set-width ht20 + channel-set-width ht40+ + channel-set-width ht40- + short-gi 20 + short-gi 40 + stbc { + rx 2 + tx + } + } + } + channel 11 + description "802.11ax 2.4GHz" + hw-id [...] + mode ax + physical-device phy0 + security { + wpa { + cipher CCMP + cipher CCMP-256 + cipher GCMP-256 + cipher GCMP + mode wpa2 + passphrase super-dooper-secure-passphrase + } + } + ssid test.ax + type access-point + } +} +``` + +#### Example configuration: Wi-Fi 6E at 6 GHz + +You may expect real throughput between 50 MB/s and 150 MB/s, depending on +obstructions from walls, water, metal, or other materials +with high electromagnetic damping at 6 GHz. Best results are achieved +with the AP being in the same room and in line-of-sight. + +```none +set system wireless country-code de +set interfaces wireless wlan0 capabilities he antenna-pattern-fixed +set interfaces wireless wlan0 capabilities he beamform multi-user-beamformer +set interfaces wireless wlan0 capabilities he beamform single-user-beamformee +set interfaces wireless wlan0 capabilities he beamform single-user-beamformer +set interfaces wireless wlan0 capabilities he bss-color 13 +set interfaces wireless wlan0 capabilities he channel-set-width 134 +set interfaces wireless wlan0 capabilities he center-channel-freq freq-1 15 +set interfaces wireless wlan0 channel 5 +set interfaces wireless wlan0 description "802.11ax 6GHz" +set interfaces wireless wlan0 mode ax +set interfaces wireless wlan0 security wpa cipher CCMP +set interfaces wireless wlan0 security wpa cipher CCMP-256 +set interfaces wireless wlan0 security wpa cipher GCMP-256 +set interfaces wireless wlan0 security wpa cipher GCMP +set interfaces wireless wlan0 security wpa mode wpa3 +set interfaces wireless wlan0 security wpa passphrase super-dooper-secure-passphrase +set interfaces wireless wlan0 mgmt-frame-protection required +set interfaces wireless wlan0 enable-bf-protection +set interfaces wireless wlan0 ssid test.ax +set interfaces wireless wlan0 type access-point +set interfaces wireless wlan0 stationary-ap +commit +``` + +Resulting configuration: + +```none +system { + wireless { + country-code de + } +} +interfaces { + [...] + wireless wlan0 { + capabilities { + he { + antenna-pattern-fixed + beamform { + multi-user-beamformer + single-user-beamformee + single-user-beamformer + } + bss-color 13 + center-channel-freq { + freq-1 15 + } + channel-set-width 134 + } + } + channel 5 + description "802.11ax 6GHz" + enable-bf-protection + hw-id [...] + mgmt-frame-protection required + mode ax + physical-device phy0 + security { + wpa { + cipher CCMP + cipher CCMP-256 + cipher GCMP-256 + cipher GCMP + mode wpa3 + passphrase super-dooper-secure-passphrase + } + } + ssid test.ax + stationary-ap + type access-point + } +} +``` + +(wireless-interface-intel-ax200)= + +### Intel AX200 + +The Intel AX200 card does not work out of the box in AP mode. You can +still put this card into AP mode using the following configuration: + +```none +set system wireless country-code 'us' +set interfaces wireless wlan0 channel '1' +set interfaces wireless wlan0 mode 'n' +set interfaces wireless wlan0 physical-device 'phy0' +set interfaces wireless wlan0 ssid 'VyOS' +set interfaces wireless wlan0 type 'access-point' +``` + diff --git a/docs/configuration/interfaces/md-wwan.md b/docs/configuration/interfaces/md-wwan.md new file mode 100644 index 00000000..e8121f28 --- /dev/null +++ b/docs/configuration/interfaces/md-wwan.md @@ -0,0 +1,355 @@ +--- +lastproofread: '2026-03-30' +--- + +(wwan-interface)= + +# WWAN + +{abbr}`WWAN (Wireless Wide Area Network)` interfaces provide access to cellular +networks via a cellular modem or card. + +Configure these interfaces under the `interfaces wwan` node. + +## Configuration + +### Common interface configuration + +```{cmdincludemd} /_include/interface-address-with-dhcp.txt +:var0: wwan +:var1: wwan0 +``` + +```{cmdincludemd} /_include/interface-description.txt +:var0: wwan +:var1: wwan0 +``` + +```{cmdincludemd} /_include/interface-disable.txt +:var0: wwan +:var1: wwan0 +``` + +```{cmdincludemd} /_include/interface-disable-link-detect.txt +:var0: wwan +:var1: wwan0 +``` + +```{cmdincludemd} /_include/interface-mtu.txt +:var0: wwan +:var1: wwan0 +``` + +```{cmdincludemd} /_include/interface-ip.txt +:var0: wwan +:var1: wwan0 +``` + +```{cmdincludemd} /_include/interface-ipv6.txt +:var0: wwan +:var1: wwan0 +``` + +```{cmdincludemd} /_include/interface-vrf.txt +:var0: wwan +:var1: wwan0 +``` + +**DHCP(v6)** + +```{cmdincludemd} /_include/interface-dhcp-options.txt +:var0: wwan +:var1: wwan0 +``` + +```{cmdincludemd} /_include/interface-dhcpv6-options.txt +:var0: wwan +:var1: wwan0 +``` + +```{cmdincludemd} /_include/interface-dhcpv6-prefix-delegation.txt +:var0: wwan +:var1: wwan0 +``` + + +### WWAN options + +```{cfgcmd} set interfaces wwan \ apn \ + +**Configure the** {abbr}`APN (Access Point Name)` **for the WWAN connection.** + +Every WWAN connection requires an {abbr}`APN (Access Point Name)` to connect to +the cellular network. + +This parameter is mandatory. Contact your service provider for the correct +{abbr}`APN (Access Point Name)`. +``` + + +## Operation + +```{opcmd} show interfaces wwan \ + +Show the operational status and traffic statistics for the specified WWAN +interface. + +:::{code-block} none +vyos@vyos:~$ show interfaces wwan wwan0 +wwan0: mtu 1500 qdisc pfifo_fast state UNKNOWN group default qlen 1000 +link/ether 02:c2:f3:00:01:02 brd ff:ff:ff:ff:ff:ff +inet 10.155.144.12/30 brd 10.155.144.15 scope global dynamic wwan0 +valid_lft 7012sec preferred_lft 7012sec +inet6 fe80::c2:f3ff:fe00:0102/64 scope link +valid_lft forever preferred_lft forever + +RX: bytes packets errors dropped overrun mcast +640 2 0 0 0 0 +TX: bytes packets errors dropped carrier collisions +3229 16 0 0 0 0 +::: +``` + + +```{opcmd} show interfaces wwan \ summary + +Show WWAN module hardware characteristics and connection information. + +:::{code-block} none +vyos@vyos:~$ show interfaces wwan wwan0 summary +-------------------------------- +General | dbus path: /org/freedesktop/ModemManager1/Modem/0 +| device id: 79f4e9cc2e9fc8d4a3b8c8f6327c2e363170194d +-------------------------------- +Hardware | manufacturer: Sierra Wireless, Incorporated +| model: MC7710 +| revision: SWI9200X_03.05.29.03ap r6485 CNSHZ-ED-XP0031 2014/12/02 17:53:15 +| h/w revision: 1.0 +| supported: gsm-umts, lte +| current: gsm-umts, lte +| equipment id: 358xxxxxxxxxxxx +-------------------------------- +System | device: /sys/devices/pci0000:00/0000:00:13.0/usb3/3-1/3-1.3 +| drivers: qcserial, qmi_wwan +| plugin: Generic +| primary port: cdc-wdm0 +| ports: ttyUSB0 (qcdm), ttyUSB2 (at), cdc-wdm0 (qmi), wwan0 (net) +-------------------------------- +Numbers | own: 4917xxxxxxxx +-------------------------------- +Status | lock: sim-pin2 +| unlock retries: sim-pin (3), sim-pin2 (3), sim-puk (10), sim-puk2 (10) +| state: connected +| power state: on +| access tech: lte +| signal quality: 63% (recent) +-------------------------------- +Modes | supported: allowed: 2g; preferred: none +| allowed: 3g; preferred: none +| allowed: 4g; preferred: none +| allowed: 2g, 3g; preferred: 3g +| allowed: 2g, 3g; preferred: 2g +| allowed: 2g, 4g; preferred: 4g +| allowed: 2g, 4g; preferred: 2g +| allowed: 3g, 4g; preferred: 3g +| allowed: 3g, 4g; preferred: 4g +| allowed: 2g, 3g, 4g; preferred: 4g +| allowed: 2g, 3g, 4g; preferred: 3g +| allowed: 2g, 3g, 4g; preferred: 2g +| current: allowed: 2g, 3g, 4g; preferred: 2g +-------------------------------- +Bands | supported: egsm, dcs, pcs, utran-1, utran-8, eutran-1, eutran-3, +| eutran-7, eutran-8, eutran-20 +| current: egsm, dcs, pcs, utran-1, utran-8, eutran-1, eutran-3, +| eutran-7, eutran-8, eutran-20 +-------------------------------- +IP | supported: ipv4, ipv6, ipv4v6 +-------------------------------- +3GPP | imei: 358xxxxxxxxxxxx +| operator id: 26201 +| operator name: Telekom.de +| registration: home +-------------------------------- +3GPP EPS | ue mode of operation: ps-1 +-------------------------------- +SIM | dbus path: /org/freedesktop/ModemManager1/SIM/0 +-------------------------------- +Bearer | dbus path: /org/freedesktop/ModemManager1/Bearer/0 +::: +``` + +```{opcmd} show interfaces wwan \ capabilities + +Show WWAN module radio capabilities. + +:::{code-block} none +vyos@vyos:~$ show interfaces wwan wwan0 capabilities +Max TX channel rate: '50000000' +Max RX channel rate: '100000000' +Data Service: 'simultaneous-cs-ps' +SIM: 'supported' +Networks: 'gsm, umts, lte' +Bands: 'gsm-dcs-1800, gsm-900-extended, gsm-900-primary, gsm-pcs-1900, wcdma-2100, wcdma-900' +LTE bands: '1, 3, 7, 8, 20' +::: +``` + + +```{opcmd} show interfaces wwan \ firmware + +Show WWAN module firmware information. + +:::{code-block} none +vyos@vyos:~$ show interfaces wwan wwan0 firmware +Model: MC7710 +Boot version: SWI9200X_03.05.29.03bt r6485 CNSHZ-ED-XP0031 2014/12/02 17:33:08 +AMSS version: SWI9200X_03.05.29.03ap r6485 CNSHZ-ED-XP0031 2014/12/02 17:53:15 +SKU ID: unknown +Package ID: unknown +Carrier ID: 0 +Config version: unknown +::: +``` + +```{opcmd} show interfaces wwan \ imei + +Show WWAN module IMEI. + +:::{code-block} none +vyos@vyos:~$ show interfaces wwan wwan0 imei +ESN: '0' +IMEI: '358xxxxxxxxxxxx' +MEID: 'unknown' +::: +``` + +```{opcmd} show interfaces wwan \ imsi + +Show the IMSI of the associated SIM card. + +:::{code-block} none +vyos@vyos:~$ show interfaces wwan wwan0 imsi +IMSI: '262xxxxxxxxxxxx' +::: +``` + +```{opcmd} show interfaces wwan \ model + +Show WWAN module model. + +:::{code-block} none +vyos@vyos:~$ show interfaces wwan wwan0 model +Model: 'MC7710' +::: +``` + +```{opcmd} show interfaces wwan \ msisdn + +Show the MSISDN of the associated SIM card. + +:::{code-block} none +vyos@vyos:~$ show interfaces wwan wwan0 msisdn +MSISDN: '4917xxxxxxxx' +::: +``` + +```{opcmd} show interfaces wwan \ revision + +Show WWAN module hardware revision. + +:::{code-block} none +vyos@vyos:~$ show interfaces wwan wwan0 revision +Revision: 'SWI9200X_03.05.29.03ap r6485 CNSHZ-ED-XP0031 2014/12/02 17:53:15' +::: +``` + +```{opcmd} show interfaces wwan \ signal + +Show signal information for the cellular connection. + +:::{code-block} none +vyos@vyos:~$ show interfaces wwan wwan0 signal +LTE: +RSSI: '-74 dBm' +RSRQ: '-7 dB' +RSRP: '-100 dBm' +SNR: '13.0 dB' +Radio Interface: 'lte' +Active Band Class: 'eutran-3' +Active Channel: '1300' +::: +``` + +```{opcmd} show interfaces wwan \ sim + +Show WWAN module SIM card information. + +:::{code-block} none +vyos@vyos:~$ show interfaces wwan wwan0 sim +Provisioning applications: +Primary GW: slot '1', application '1' +Primary 1X: session doesn't exist +Secondary GW: session doesn't exist +Secondary 1X: session doesn't exist +Slot [1]: +Card state: 'present' +UPIN state: 'not-initialized' +UPIN retries: '0' +UPUK retries: '0' +Application [1]: +Application type: 'usim (2)' +Application state: 'ready' +Application ID: +A0:00:00:00:87:10:02:FF:49:94:20:89:03:10:00:00 +Personalization state: 'ready' +UPIN replaces PIN1: 'no' +PIN1 state: 'disabled' +PIN1 retries: '3' +PUK1 retries: '10' +PIN2 state: 'enabled-not-verified' +PIN2 retries: '3' +PUK2 retries: '10' +::: +``` + + +## Example + +The following example shows how to configure a cellular connection using a +Sierra Wireless MC7710 miniPCIe card that operates over USB despite its form +factor. The card is installed in a {ref}`pc-engines-apu4`. + +```none +set interfaces wwan wwan0 apn 'internet.telekom' +set interfaces wwan wwan0 address 'dhcp' +``` + + +## Supported hardware + +The following WWAN modules have been successfully tested with a +{ref}`pc-engines-apu4` board: +- Sierra Wireless AirPrime MC7304 miniPCIe card (LTE) +- Sierra Wireless AirPrime MC7430 miniPCIe card (LTE) +- Sierra Wireless AirPrime MC7455 miniPCIe card (LTE) +- Sierra Wireless AirPrime MC7710 miniPCIe card (LTE) +- Huawei ME909u-521 miniPCIe card (LTE) +- Huawei ME909s-120 miniPCIe card (LTE) +- HP LT4120 Snapdragon X5 LTE + +## Firmware update + +WWAN modules include reprogrammable firmware, and most vendors regularly +provide updates for it. + +Since VyOS communicates with these devices via the QMI interface, you can +update firmware directly within the system using the `qmi-firmware-update` +utility. + +The following example shows how to update the firmware for a Sierra Wireless +MC7710 module using the provided .cwe file. + +```bash +$ sudo qmi-firmware-update --update -d 1199:68a2 \ + 9999999_9999999_9200_03.05.14.00_00_generic_000.000_001_SPKG_MC.cwe +``` diff --git a/docs/configuration/loadbalancing/md-haproxy.md b/docs/configuration/loadbalancing/md-haproxy.md new file mode 100644 index 00000000..d60c5248 --- /dev/null +++ b/docs/configuration/loadbalancing/md-haproxy.md @@ -0,0 +1,510 @@ +--- +lastproofread: '2026-04-06' +--- + +# HAproxy + +```{include} /_include/need_improvement.txt +``` + +HAProxy is a load balancer and proxy server that provides +high-availability, load balancing, and proxying for TCP (level 4) and +HTTP-based (level 7) applications. + +## Configuration + +Service configuration specifies the port to bind to. Backend +configuration defines the load balancing method and specifies the backend +servers. + +### Service + +```{cfgcmd} set load-balancing haproxy service \ listen-address \ + +Set the IP address for the service to bind to. By default, the service +listens on all IPv4 and IPv6 addresses. +``` + +```{cfgcmd} set load-balancing haproxy service \ port \ + +Create service ** to listen on \ +``` + +```{cfgcmd} set load-balancing haproxy service \ mode \ + +Configure service ** mode TCP or HTTP +``` + +```{cfgcmd} set load-balancing haproxy service \ backend \ + +Configure service ** to use the backend \ +``` + +```{cfgcmd} set load-balancing haproxy service \ ssl certificate \ + +Set the SSL certificate \ for service \. You can define +multiple certificates. +``` + +```{cfgcmd} set load-balancing haproxy service \ http-response-headers \ value \ + +Set custom HTTP headers to include in all responses. +``` + +```{cfgcmd} set load-balancing haproxy service \ logging facility \ level \ + +Specify facility and level for logging. +For an explanation on {ref}`syslog_facilities` and +{ref}`syslog_severity_level`, +see tables in the syslog configuration section. +``` + +```{cfgcmd} set load-balancing haproxy service \ timeout client \ + +Set the maximum inactivity time on the client side for this service. +Value range 1-3600 seconds. +``` + +```{cfgcmd} set load-balancing haproxy service \ http-compression algorithm \ + +Set the compression algorithm to be used when compressing HTTP responses. +``` + +```{cfgcmd} set load-balancing haproxy service \ http-compression mime-type \ + +Set the list of HTTP response MIME types which haproxy will attempt to +compress, if received uncompressed from backend server. +``` + +#### Rules + +Rules control and route incoming traffic to specific backends based on +predefined conditions. Rules define matching criteria and specify actions +to perform. + +```{cfgcmd} set load-balancing haproxy service \ rule \ domain-name \ + +Match domain name +``` + +````{cfgcmd} set load-balancing haproxy service \ rule \ ssl \ + +```{eval-rst} +SSL match Server Name Indication (SNI) option: + * ``req-ssl-sni`` SSL Server Name Indication (SNI) request match + * ``ssl-fc-sni`` SSL frontend connection Server Name Indication match + * ``ssl-fc-sni-end`` SSL frontend match end of connection Server Name + + Indication +``` +```` + +````{cfgcmd} set load-balancing haproxy service \ rule \ url-path \ \ + +Define URL path matching rules for a specific service. Use this command +to specify how to match the URL path against incoming requests. + +```{eval-rst} +The available options for are: + * ``begin`` Matches the beginning of the URL path + * ``end`` Matches the end of the URL path. + * ``exact`` Matches the URL path exactly. +``` +```` + +```{cfgcmd} set load-balancing haproxy service \ rule \ set backend \ + +Assign a specific backend to a rule +``` + +```{cfgcmd} set load-balancing haproxy service \ rule \ redirect-location \ + +Redirect URL to a new location. +``` + +### Backend + +````{cfgcmd} set load-balancing haproxy backend \ balance \ + +Specify the load balancing algorithm for distributing requests among +available servers. + +```{eval-rst} +Balance algorithms: + * ``source-address`` Distributes requests based on the source IP address + of the client. + * ``round-robin`` Distributes requests in a circular manner, + sequentially sending each request to the next server in line. + * ``least-connection`` Distributes requests to the server with the fewest + active connections. +``` +```` + +```{cfgcmd} set load-balancing haproxy backend \ mode \ + +Configure backend ** mode TCP or HTTP. +``` + +```{cfgcmd} set load-balancing haproxy backend \ server \ address \ + +Set the address of the backend server that receives incoming traffic. +``` + +```{cfgcmd} set load-balancing haproxy backend \ server \ port \ + +Set the address of the backend port. +``` + +```{cfgcmd} set load-balancing haproxy backend \ server \ check + +Active health check backend server. +``` + +```{cfgcmd} set load-balancing haproxy backend \ server \ check port \ + +Set an alternative port number for health checks. +Overrides the default server port used for TCP/HTTP checks. +``` + +```{cfgcmd} set load-balancing haproxy backend \ server \ send-proxy + +Send a Proxy Protocol version 1 header (text format). +``` + +```{cfgcmd} set load-balancing haproxy backend \ server \ send-proxy-v2 + +Send a Proxy Protocol version 2 header (binary format). +``` + +```{cfgcmd} set load-balancing haproxy backend \ ssl ca-certificate \ + +Use SSL encryption for backend requests and authenticate the backend +against ````. +``` + +```{cfgcmd} set load-balancing haproxy backend \ ssl no-verify + +Use SSL encryption for backend requests without validating the server +certificate. +``` + +```{cfgcmd} set load-balancing haproxy backend \ http-response-headers \ value \ + +Set custom HTTP headers to include in all responses from the backend. +``` + +```{cfgcmd} set load-balancing haproxy backend \ logging facility \ level \ + +Specify facility and level for logging. +For an explanation on {ref}`syslog_facilities` and +{ref}`syslog_severity_level`, +see tables in the syslog configuration section. +``` + +```{cfgcmd} set load-balancing haproxy backend \ timeout check \ + +Set the timeout in seconds for established connections. +Value range 1-3600 seconds. +``` +```{cfgcmd} set load-balancing haproxy backend \ timeout connect \ + +Set the maximum time to wait for a connection attempt to a server to succeed. +Value range 1-3600 seconds. +``` + + +```{cfgcmd} set load-balancing haproxy backend \ timeout server \ + +Set the maximum inactivity time on the server side. +Value range 1-3600 seconds. +``` + +### Global + +Global configuration parameters: + +```{cfgcmd} set load-balancing haproxy global-parameters max-connections \ + +Limit maximum number of connections +``` + + +```{cfgcmd} set load-balancing haproxy global-parameters ssl-bind-ciphers \ + +Limit the cipher algorithms allowed during SSL/TLS handshake. +``` + + +```{cfgcmd} set load-balancing haproxy global-parameters tls-version-min \ + +Specify the minimum required TLS version 1.2 or 1.3 +``` + + +```{cfgcmd} set load-balancing haproxy global-parameters logging facility \ level \ + +Specify facility and level for logging. +For an explanation on {ref}`syslog_facilities` and +{ref}`syslog_severity_level`, +see tables in the syslog configuration section. +``` + + +```{cfgcmd} set load-balancing haproxy timeout check \ + +Set the timeout in seconds for established connections. +Value range 1-3600 seconds. Default is 5 seconds. +``` + + +```{cfgcmd} set load-balancing haproxy timeout client \ + +Set the maximum inactivity time on the client side. +Value range 1-3600 seconds. Default is 50 seconds. +``` + + +```{cfgcmd} set load-balancing haproxy timeout connect \ + +Set the maximum time to wait for a connection attempt to a server to succeed. +Value range 1-3600 seconds. Default is 10 seconds. +``` + + +```{cfgcmd} set load-balancing haproxy timeout server \ + +Set the maximum inactivity time on the server side. +Value range 1-3600 seconds. Default is 50 seconds. +``` + +## Health checks + + +### HTTP checks + + +Use HTTP health checks to monitor web applications that provide health status +information and determine their availability. + +```{cfgcmd} set load-balancing haproxy backend \ http-check + +Enables HTTP health checks using OPTION HTTP requests against '/' and +expecting a successful response code in the 200-399 range. +``` + + +```{cfgcmd} set load-balancing haproxy backend \ http-check method \ + +Set the HTTP method: ``OPTION``, ``GET``, ``POST``, or ``PUT``. +``` + + +```{cfgcmd} set load-balancing haproxy backend \ http-check uri \ + +Set the endpoint to use for health checks. +``` + + +````{cfgcmd} set load-balancing haproxy backend \ http-check expect \ + +Set the expected result condition for a server to be considered healthy. + +```{eval-rst} +Some possible examples are: + * ``status 200`` Expecting a 200 response code + * ``status 200-399`` Expecting a non-failure response code + * ``string success`` Expecting the string success in the response body +``` +```` + +### TCP checks + +Configure health checks for TCP mode backends. You can configure protocol-aware +checks for a range of Layer 7 protocols: + +````{cfgcmd} set load-balancing haproxy backend \ health-check \ + +```{eval-rst} +Available health check protocols: + * ``ldap`` LDAP protocol check. + * ``redis`` Redis protocol check. + * ``mysql`` MySQL protocol check. + * ``pgsql`` PostgreSQL protocol check. + * ``smtp`` SMTP protocol check. +``` +```` + +:::{note} +If you specify a server to check but do not configure a +protocol, HAProxy performs a basic TCP health check. A server is online if +it responds to a connection attempt with a valid `SYN/ACK` packet. +::: +## Redirect HTTP to HTTPS + +Configure a HAProxy service for HTTP that listens on port 80 and redirects +incoming requests to HTTPS: + +```none +set load-balancing haproxy service http port '80' +set load-balancing haproxy service http redirect-http-to-https +``` + +You can use a different service name; in this example, `http` is just for +convenience. + +## Examples +### Level 4 balancing + +This configuration enables the TCP reverse proxy for the `my-tcp-api` +service. Incoming TCP connections on port 8888 are load balanced across the +backend servers (srv01 and srv02) using the round-robin load balancing +algorithm. + +```none +set load-balancing haproxy service my-tcp-api backend 'bk-01' +set load-balancing haproxy service my-tcp-api mode 'tcp' +set load-balancing haproxy service my-tcp-api port '8888' + +set load-balancing haproxy backend bk-01 balance 'round-robin' +set load-balancing haproxy backend bk-01 mode 'tcp' + +set load-balancing haproxy backend bk-01 server srv01 address '192.0.2.11' +set load-balancing haproxy backend bk-01 server srv01 port '8881' +set load-balancing haproxy backend bk-01 server srv02 address '192.0.2.12' +set load-balancing haproxy backend bk-01 server srv02 port '8882' +``` + +### Balancing based on domain name + +The following configuration demonstrates how to use VyOS +to achieve load balancing based on the domain name: + +The HTTP service listens on TCP port 80. + +Rule 10 matches requests with the domain name `node1.example.com` and +forwards them to the backend `bk-api-01`. + +Rule 20 matches requests with the domain name `node2.example.com` and +forwards them to the backend `bk-api-02`. + +```none +set load-balancing haproxy service http description 'bind app listen on 443 port' +set load-balancing haproxy service http mode 'tcp' +set load-balancing haproxy service http port '80' + +set load-balancing haproxy service http rule 10 domain-name 'node1.example.com' +set load-balancing haproxy service http rule 10 set backend 'bk-api-01' +set load-balancing haproxy service http rule 20 domain-name 'node2.example.com' +set load-balancing haproxy service http rule 20 set backend 'bk-api-02' + +set load-balancing haproxy backend bk-api-01 description 'My API-1' +set load-balancing haproxy backend bk-api-01 mode 'tcp' +set load-balancing haproxy backend bk-api-01 server api01 address '127.0.0.1' +set load-balancing haproxy backend bk-api-01 server api01 port '4431' +set load-balancing haproxy backend bk-api-02 description 'My API-2' +set load-balancing haproxy backend bk-api-02 mode 'tcp' +set load-balancing haproxy backend bk-api-02 server api01 address '127.0.0.2' +set load-balancing haproxy backend bk-api-02 server api01 port '4432' +``` + +### Terminate SSL + +The following configuration terminates SSL on the router. + +The `http` service listens on port 80 and redirects HTTP requests to +HTTPS. + +The `https` service listens on port 443 with the `bk-default` backend +and handles HTTPS traffic using the `cert` certificate for SSL termination. +The HSTS header is set with a 1-year expiry to tell browsers to always use +SSL for the site. + +Rule 10 matches requests with the exact URL path `/.well-known/xxx` and +redirects them to `/certs/`. + +Rule 20 matches requests with URL paths ending in `/mail` or the exact +path `/email/bar` and redirects them to `/postfix/`. + +Global parameters include a maximum connection limit of 4000 and a minimum +TLS version of 1.3. + +```none +set load-balancing haproxy service http description 'Force redirect to HTTPS' +set load-balancing haproxy service http port '80' +set load-balancing haproxy service http redirect-http-to-https + +set load-balancing haproxy service https backend 'bk-default' +set load-balancing haproxy service https description 'listen on 443 port' +set load-balancing haproxy service https mode 'http' +set load-balancing haproxy service https port '443' +set load-balancing haproxy service https ssl certificate 'cert' +set load-balancing haproxy service https http-response-headers Strict-Transport-Security value 'max-age=31536000' + +set load-balancing haproxy service https rule 10 url-path exact '/.well-known/xxx' +set load-balancing haproxy service https rule 10 set redirect-location '/certs/' +set load-balancing haproxy service https rule 20 url-path end '/mail' +set load-balancing haproxy service https rule 20 url-path exact '/email/bar' +set load-balancing haproxy service https rule 20 set redirect-location '/postfix/' + +set load-balancing haproxy backend bk-default description 'Default backend' +set load-balancing haproxy backend bk-default mode 'http' +set load-balancing haproxy backend bk-default server sr01 address '192.0.2.23' +set load-balancing haproxy backend bk-default server sr01 port '80' + +set load-balancing haproxy global-parameters max-connections '4000' +set load-balancing haproxy global-parameters tls-version-min '1.3' +``` + +### SSL Bridging + +The following configuration terminates incoming HTTPS traffic on the router, +then re-encrypts the traffic and sends it to the backend server via HTTPS. +Use this when encryption is required for both paths but you do not want to +install publicly trusted certificates on each backend server. + +Backend service certificates are checked against the certificate authority +specified in the configuration, which could be an internal CA. + +The `https` service listens on port 443 with backend `bk-bridge-ssl` to +handle HTTPS traffic. It uses certificate named `cert` for SSL termination. + +The `bk-bridge-ssl` backend connects to `sr01` server on port 443 via HTTPS +and checks backend server has a valid certificate trusted by CA `cacert` + +```none +set load-balancing haproxy service https backend 'bk-bridge-ssl' +set load-balancing haproxy service https description 'listen on 443 port' +set load-balancing haproxy service https mode 'http' +set load-balancing haproxy service https port '443' +set load-balancing haproxy service https ssl certificate 'cert' + +set load-balancing haproxy backend bk-bridge-ssl description 'SSL backend' +set load-balancing haproxy backend bk-bridge-ssl mode 'http' +set load-balancing haproxy backend bk-bridge-ssl ssl ca-certificate 'cacert' +set load-balancing haproxy backend bk-bridge-ssl server sr01 address '192.0.2.23' +set load-balancing haproxy backend bk-bridge-ssl server sr01 port '443' +``` + +### Balancing with HTTP health checks + +This configuration enables HTTP health checks for backend servers. + +```none +set load-balancing haproxy service my-tcp-api backend 'bk-01' +set load-balancing haproxy service my-tcp-api mode 'tcp' +set load-balancing haproxy service my-tcp-api port '8888' + +set load-balancing haproxy backend bk-01 balance 'round-robin' +set load-balancing haproxy backend bk-01 mode 'tcp' + +set load-balancing haproxy backend bk-01 http-check method 'get' +set load-balancing haproxy backend bk-01 http-check uri '/health' +set load-balancing haproxy backend bk-01 http-check expect 'status 200' + +set load-balancing haproxy backend bk-01 server srv01 address '192.0.2.11' +set load-balancing haproxy backend bk-01 server srv01 port '8881' +set load-balancing haproxy backend bk-01 server srv01 check +set load-balancing haproxy backend bk-01 server srv02 address '192.0.2.12' +set load-balancing haproxy backend bk-01 server srv02 port '8882' +set load-balancing haproxy backend bk-01 server srv02 check port '8892' +``` diff --git a/docs/configuration/loadbalancing/md-index.md b/docs/configuration/loadbalancing/md-index.md new file mode 100644 index 00000000..3241edb7 --- /dev/null +++ b/docs/configuration/loadbalancing/md-index.md @@ -0,0 +1,15 @@ +--- +lastproofread: '2026-04-06' +--- + +(load-balancing)= + +# Load-balancing + +```{toctree} +:includehidden: true +:maxdepth: 1 + +wan +haproxy +``` diff --git a/docs/configuration/loadbalancing/md-wan.md b/docs/configuration/loadbalancing/md-wan.md new file mode 100644 index 00000000..a19bbfae --- /dev/null +++ b/docs/configuration/loadbalancing/md-wan.md @@ -0,0 +1,306 @@ +--- +lastproofread: '2026-04-06' +--- + +# WAN load balancing + +```{todo} +Convert raw command blocks in this file to cfgcmd/opcmd +directives for command coverage tracking. +``` + +The load balancer distributes outbound traffic across two or more +interfaces. If a path fails, the load balancer balances traffic across the +remaining healthy paths. When a path recovers, it is automatically added back +to the routing table. The load balancer adds routes for each path and +distributes traffic based on interface health and weight. + +In a minimal configuration, the following must be provided: +> - An interface with a `nexthop`. +> - One rule with a LAN (inbound-interface) and the WAN (interface). + +The following examples uses two DHCP WAN interfaces and one LAN (`eth2`): + +```none +set load-balancing wan interface-health eth0 nexthop 'dhcp' +set load-balancing wan interface-health eth1 nexthop 'dhcp' +set load-balancing wan rule 1 inbound-interface 'eth2' +set load-balancing wan rule 1 interface eth0 +set load-balancing wan rule 1 interface eth1 +``` + +:::{note} +Do not use WAN load balancing with dynamic routing protocols. This +feature creates customized routing tables and firewall rules that are +incompatible with routing protocols. +::: + +## Load balancing rules + +You define interfaces, their weight, and the traffic type to balance in +numbered rule sets. The load balancer executes rules in numerical order +against outgoing packets. When a packet matches a rule, it is sent through the +specified interface. Packets that do not match any rule use the system routing +table. You cannot change rule numbers. + +Create a load balancing rule, it can be a number between 1 and 9999: + +```none +vyos@vyos# set load-balancing wan rule 1 +Possible completions: +description Description for this rule +> destination Destination +exclude Exclude packets matching this rule from wan load balance +failover Enable failover for packets matching this rule from wan load balance +inbound-interface Inbound interface name (e.g., "eth0") [REQUIRED] ++> interface Interface name [REQUIRED] +> limit Enable packet limit for this rule +per-packet-balancing Option to match traffic per-packet instead of the default, per-flow +protocol Protocol to match +> source Source information +``` + + +### Interface weight + +By default, the load balancer distributes outbound +traffic randomly across available interfaces. You can assign weights to +interfaces to influence the distribution. If `eth0` has more bandwidth +than `eth1`, you can assign a higher weight to `eth0` to send more +traffic through it: + +```none +set load-balancing wan rule 1 interface eth0 weight 2 +set load-balancing wan rule 1 interface eth1 weight 1 +``` + +In this example,\`\`eth0\`\` receives 66% of traffic, and `eth1` receives +33% of traffic. + +### Rate limit + +Set a packet rate limit for a rule to apply it to traffic above or below a +specified threshold. To configure rate limiting, use: + +```none +set load-balancing wan rule limit +``` + +- `burst`: Number of packets allowed to overshoot the limit within `period`. + Default 5. +- `period`: Time window for rate calculation. Possible values: + `second` (one second), `minute` (one minute), `hour` (one hour). + Default is `second`. +- `rate`: Number of packets. Default: `5`. +- `threshold`: `below` or `above` the specified rate limit. + +### Flow and packet-based balancing + +The load balancer balances outgoing traffic by flow. A connection tracking +table tracks flows by source address, destination address, and port. Each +flow is assigned to an interface based on the balancing rules, and subsequent +packets use the same interface. This ensures packets arrive in order when links +have different speeds. + +Packet-based balancing can improve balance across interfaces when packet +order is not critical. Enable per-packet balancing for a rule with: + +```none +set load-balancing wan rule per-packet-balancing +``` + + +### Exclude traffic + +To exclude traffic from load balancing, traffic matching an exclude rule +bypasses load balancing and uses the system routing table instead: + +```none +set load-balancing wan rule exclude +``` + + +## Health checks + +The load balancer periodically checks the health of interfaces and paths by +sending ICMP packets (ping) to remote destinations, performing TTL tests, or +executing a user-defined script. If an interface fails the health check, the +load balancer removes it from its interface pool. +To enable health checking for an interface: + +```none +vyos@vyos# set load-balancing wan interface-health +Possible completions: +failure-count Failure count +nexthop Outbound interface nexthop address. Can be 'dhcp or ip address' [REQUIRED] +success-count Success count ++> test Rule number +``` + +Specify the nexthop on the path to the destination. You can set +`ipv4-address` to `dhcp`. + +```none +set load-balancing wan interface-health nexthop +``` + +Set the number of health check failures before the load balancer marks an +interface as unavailable (range 1-10, default 1). Or set the number of +successful health checks before adding an interface back to the pool +(range 1-10, default 1). + +```none +set load-balancing wan interface-health failure-count +set load-balancing wan interface-health success-count +``` + +Configure each health check in its own test. Tests are numbered and processed +in numeric order. You can define multiple tests for multi-target health +checking: + +```none +vyos@vyos# set load-balancing wan interface-health eth1 test 0 +Possible completions: +resp-time Ping response time (seconds) +target Health target address +test-script Path to user defined script +ttl-limit Ttl limit (hop count) +type WLB test type +``` + +- `resp-time`: The maximum response time for ping in seconds. Range + 1-30, default `5`. +- `target`: The target to receive ICMP packets. The address can be an IPv4 + address or hostname. +- `test-script`: A user-defined script must return 0 to succeed and + non-zero to fail. Scripts reside in `/config/scripts`. For other locations, + provide the full path. +- `ttl-limit`: For the UDP TTL limit test, specify the hop count limit. + The limit must be shorter than the path length. The test succeeds when an + ICMP time-expired message is returned. Default `1`. +- `type`: Specify the test type: `ping`, `ttl`, or a user-defined + script. + +## Source NAT rules + +By default, interfaces in a load balancing pool replace the source IP of +each outgoing packet with their own address to ensure replies arrive on the +same interface. The load balancer handles this through automatically generated +Source NAT (SNAT) rules applied only to balanced traffic. To disable the +automatic generation of SNAT rules when this behavior is not desired, use: + +```none +set load-balancing wan disable-source-nat +``` + + +## Sticky connections + +Inbound connections to a WAN interface can be improperly handled when +replies are sent back to the client. + +```{image} /_static/images/sticky-connections.webp +:align: center +:width: 80% +``` + +When responding to an incoming packet, you may want to ensure the response +leaves from the same interface as the incoming packet. Enable sticky +connections in the load balancer to do this: + +```none +set load-balancing wan sticky-connections inbound +``` + + +## Failover + +In failover mode, one interface is primary and other interfaces are +secondary or spare. The load balancer uses only the primary interface. If it +fails, a secondary interface from the available pool takes over. The load +balancer selects the primary interface based on its weight and health. Other +interfaces become secondary. Secondary interfaces are chosen based on their +weight and health. You can also select interface roles based on rule order by +including interfaces in balancing rules and ordering those rules accordingly. +To enable failover mode, create a failover rule: + +```none +set load-balancing wan rule failover +``` + +Existing sessions do not automatically fail over to a new path. Flush the +session table on each connection state change to enable failover: + +```none +set load-balancing wan flush-connections +``` + +:::{warning} +Flushing the session table causes other connections to revert from +flow-based to packet-based balancing until each flow is reestablished. +::: + +## Script execution + +Run a script when an interface state changes. Scripts run from the +`/config/scripts` directory. To use a script in another location, +specify the full path: + +```none +set load-balancing wan hook script-name +``` + +Two environment variables are available: +- `WLB_INTERFACE_NAME=[interfacename]`: Interface to be monitored +- `WLB_INTERFACE_STATE=[ACTIVE|FAILED]`: Interface state + +:::{warning} +Blocking call with no timeout: VyOS becomes unresponsive if the +script does not return. +::: + +## Handling and monitoring + +The following command shows WAN load balancer information including test +types and targets. The character at the start of each line indicates the test +state: +- `+` successful. +- `-` failed. +- A blank indicates that no test has been carried out. + +```none +vyos@vyos:~$ show wan-load-balance +Interface: eth0 +Status: failed +Last Status Change: Tue Jun 11 20:12:19 2019 +-Test: ping Target: + Last Interface Success: 55s + Last Interface Failure: 0s + # Interface Failure(s): 5 + +Interface: eth1 +Status: active +Last Status Change: Tue Jun 11 20:06:42 2019 ++Test: ping Target: + Last Interface Success: 0s + Last Interface Failure: 6m26s + # Interface Failure(s): 0 +``` + +Show connection data of load balanced traffic: + +```none +vyos@vyos:~$ show wan-load-balance connection +conntrack v1.4.2 (conntrack-tools): 3 flow entries have been shown. +Type State Src Dst Packets Bytes +tcp TIME_WAIT 10.1.1.13:38040 203.0.113.2:80 203.0.113.2 192.168.188.71 +udp 10.1.1.13:41891 198.51.100.3:53 198.51.100.3 192.168.188.71 +udp 10.1.1.13:55437 198.51.100.3:53 198.51.100.3 192.168.188.71 +``` + + +### Restart + +```none +restart wan-load-balance +``` diff --git a/docs/configuration/md-index.md b/docs/configuration/md-index.md new file mode 100644 index 00000000..3e215502 --- /dev/null +++ b/docs/configuration/md-index.md @@ -0,0 +1,23 @@ +# Configuration Guide + +The following structure represents the CLI structure. + +```{toctree} +:includehidden: true +:maxdepth: 1 + +container/index +firewall/index +highavailability/index +interfaces/index +loadbalancing/index +nat/index +policy/index +pki/index +protocols/index +service/index +system/index +trafficpolicy/index +vpn/index +vrf/index +``` diff --git a/docs/configuration/nat/md-cgnat.md b/docs/configuration/nat/md-cgnat.md new file mode 100644 index 00000000..914a466b --- /dev/null +++ b/docs/configuration/nat/md-cgnat.md @@ -0,0 +1,200 @@ +(cgnat)= + +# CGNAT + +{abbr}`CGNAT (Carrier-Grade Network Address Translation)` , also known as +Large-Scale NAT (LSN), is a type of network address translation used by +Internet Service Providers (ISPs) to enable multiple private IP addresses to +share a single public IP address. This technique helps to conserve the limited +IPv4 address space. +The 100.64.0.0/10 address block is reserved for use in carrier-grade NAT + +## Overview + +CGNAT works by placing a NAT device within the ISP's network. This device +translates private IP addresses from customer networks to a limited pool of +public IP addresses assigned to the ISP. This allows many customers to share a +smaller number of public IP addresses. + +Not all {rfc}`6888` requirements are implemented in CGNAT. + +Implemented the following {rfc}`6888` requirements: + +- REQ 2: A CGN must have a default "IP address pooling" behavior of "Paired". + CGN must use the same external IP address mapping for all sessions associated + with the same internal IP address, be they TCP, UDP, ICMP, something else, + or a mix of different protocols. +- REQ 3: The CGN function should not have any limitations on the size or the + contiguity of the external address pool. +- REQ 4: A CGN must support limiting the number of external ports (or, + equivalently, "identifiers" for ICMP) that are assigned per subscriber + +### Advantages of CGNAT + +- **IPv4 Address Conservation**: CGNAT helps mitigate the exhaustion of IPv4 addresses by allowing multiple customers to share a single public IP address. +- **Scalability**: ISPs can support more customers without needing a proportional increase in public IP addresses. +- **Cost-Effective**: Reduces the cost associated with acquiring additional public IPv4 addresses. + +### Considerations + +- **Traceability Issues**: Since multiple users share the same public IP address, tracking individual users for security and legal purposes can be challenging. +- **Performance Overheads**: The translation process can introduce latency and potential performance bottlenecks, especially under high load. +- **Application Compatibility**: Some applications and protocols may not work well with CGNAT due to their reliance on unique public IP addresses. +- **Port Allocation Limits**: Each public IP address has a limited number of ports, which can be exhausted, affecting the ability to establish new connections. +- **Port Control Protocol**: PCP is not implemented. + +## Port calculation + +When implementing CGNAT, ensuring that there are enough ports allocated per subscriber is critical. Below is a summary based on RFC 6888. + +1. **Total Ports Available**: + + - Total Ports: 65536 (0 to 65535) + - Reserved Ports: Assume 1024 ports are reserved for well-known services and administrative purposes. + - Usable Ports: 65536 - 1024 = 64512 + +2. **Estimate Ports Needed per Subscriber**: + + - Example: A household might need 1000 ports to ensure smooth operation for multiple devices and applications. + +3. **Calculate the Number of Subscribers per Public IP**: + + - Usable Ports / Ports per Subscriber + - 64512 / 1000 ≈ 64 subscribers per public IP + +## Configuration + +```{cfgcmd} set nat cgnat pool external \ external-port-range \ + +Set an external port-range for the external pool, the default range is +1024-65535. Multiple entries can be added to the same pool. +``` + + +```{cfgcmd} set nat cgnat pool external \ per-user-limit port \ + +Set external source port limits that will be allocated to each subscriber +individually. The default value is 2000. +``` + + +```{cfgcmd} set nat cgnat pool external \ range [address | address range | network] [seq] + +Set the range of external IP addresses for the CGNAT pool. +The sequence is optional; if set, a lower value means higher priority. +``` + + +```{cfgcmd} set nat cgnat pool internal \ range [address range | network] + +Set the range of internal IP addresses for the CGNAT pool. +``` + + +```{cfgcmd} set nat cgnat rule \ source pool \ + +Set the rule for the source pool. +``` + + +```{cfgcmd} set nat cgnat rule \ translation pool \ + +Set the rule for the translation pool. +``` + + +```{cfgcmd} set nat cgnat log-allocation + +Enable logging of IP address and ports allocations. +``` + + +## Configuration Examples + +### Single external address + +Example of setting up a basic CGNAT configuration: +In the following example, we define an external pool named `ext-1` with one +external IP address. + +Each subscriber will be allocated a maximum of 2000 ports from the external pool. + +```none +set nat cgnat pool external ext1 external-port-range '1024-65535' +set nat cgnat pool external ext1 per-user-limit port '2000' +set nat cgnat pool external ext1 range '192.0.2.222/32' +set nat cgnat pool internal int1 range '100.64.0.0/28' +set nat cgnat rule 10 source pool 'int1' +set nat cgnat rule 10 translation pool 'ext1' +``` + + +### Multiple external addresses + +```none +set nat cgnat pool external ext1 external-port-range '1024-65535' +set nat cgnat pool external ext1 per-user-limit port '8000' +set nat cgnat pool external ext1 range '192.0.2.1-192.0.2.2' +set nat cgnat pool external ext1 range '203.0.113.253-203.0.113.254' +set nat cgnat pool internal int1 range '100.64.0.1-100.64.0.32' +set nat cgnat rule 10 source pool 'int1' +set nat cgnat rule 10 translation pool 'ext1' +``` + + +### External address sequences + +```none +set nat cgnat pool external ext-01 per-user-limit port '16000' +set nat cgnat pool external ext-01 range 203.0.113.1/32 seq '10' +set nat cgnat pool external ext-01 range 192.0.2.1/32 seq '20' +set nat cgnat pool internal int-01 range '100.64.0.0/29' +set nat cgnat rule 10 source pool 'int-01' +set nat cgnat rule 10 translation pool 'ext-01' +``` + + +## Operation commands + +```{opcmd} show nat cgnat allocation + +Show address and port allocations +``` + +```{opcmd} show nat cgnat allocation external-address \ + +Show all allocations for an external IP address +``` + +```{opcmd} show nat cgnat allocation internal-address \ + +Show all allocations for an internal IP address +``` + + +### Show CGNAT allocations + +```none +vyos@vyos:~$ show nat cgnat allocation +Internal IP External IP Port range +------------- ------------- ------------ +100.64.0.0 203.0.113.1 1024-17023 +100.64.0.1 203.0.113.1 17024-33023 +100.64.0.2 203.0.113.1 33024-49023 +100.64.0.3 203.0.113.1 49024-65023 +100.64.0.4 192.0.2.1 1024-17023 +100.64.0.5 192.0.2.1 17024-33023 +100.64.0.6 192.0.2.1 33024-49023 +100.64.0.7 192.0.2.1 49024-65023 + +vyos@vyos:~$ show nat cgnat allocation internal-address 100.64.0.4 +Internal IP External IP Port range +------------- ------------- ------------ +100.64.0.4 192.0.2.1 1024-17023 +``` + + +## Further Reading + +- {rfc}`6598` - IANA-Reserved IPv4 Prefix for Shared Address Space +- {rfc}`6888` - Requirements for CGNAT diff --git a/docs/configuration/nat/md-index.md b/docs/configuration/nat/md-index.md new file mode 100644 index 00000000..35e5d32b --- /dev/null +++ b/docs/configuration/nat/md-index.md @@ -0,0 +1,13 @@ +(nat)= + +# NAT + +```{toctree} +:includehidden: true +:maxdepth: 1 + +nat44 +nat64 +nat66 +cgnat +``` diff --git a/docs/configuration/nat/md-nat44.md b/docs/configuration/nat/md-nat44.md new file mode 100644 index 00000000..8b02477e --- /dev/null +++ b/docs/configuration/nat/md-nat44.md @@ -0,0 +1,788 @@ +(nat44)= + +# NAT44 + +{abbr}`NAT (Network Address Translation)` is a common method of +remapping one IP address space into another by modifying network address +information in the IP header of packets while they are in transit across +a traffic routing device. The technique was originally used as a +shortcut to avoid the need to readdress every host when a network was +moved. It has become a popular and essential tool in conserving global +address space in the face of IPv4 address exhaustion. One +Internet-routable IP address of a NAT gateway can be used for an entire +private network. + +IP masquerading is a technique that hides an entire IP address space, +usually consisting of private IP addresses, behind a single IP address +in another, usually public address space. The hidden addresses are +changed into a single (public) IP address as the source address of the +outgoing IP packets so they appear as originating not from the hidden +host but from the routing device itself. Because of the popularity of +this technique to conserve IPv4 address space, the term NAT has become +virtually synonymous with IP masquerading. + +As network address translation modifies the IP address information in +packets, NAT implementations may vary in their specific behavior in +various addressing cases and their effect on network traffic. The +specifics of NAT behavior are not commonly documented by vendors of +equipment containing NAT implementations. + +The computers on an internal network can use any of the addresses set +aside by the {abbr}`IANA (Internet Assigned Numbers Authority)` for +private addressing (see {rfc}`1918`). These reserved IP addresses are +not in use on the Internet, so an external machine will not directly +route to them. The following addresses are reserved for private use: + +- 10.0.0.0 to 10.255.255.255 (CIDR: 10.0.0.0/8) +- 172.16.0.0 to 172.31.255.255 (CIDR: 172.16.0.0/12) +- 192.168.0.0 to 192.168.255.255 (CIDR: 192.168.0.0/16) + +If an ISP deploys a {abbr}`CGN (Carrier-grade NAT)`, and uses +{rfc}`1918` address space to number customer gateways, the risk of +address collision, and therefore routing failures, arises when the +customer network already uses an {rfc}`1918` address space. + +This prompted some ISPs to develop a policy within the {abbr}`ARIN +(American Registry for Internet Numbers)` to allocate new private +address space for CGNs, but ARIN deferred to the IETF before +implementing the policy indicating that the matter was not a typical +allocation issue but a reservation of addresses for technical purposes +(per {rfc}`2860`). + +IETF published {rfc}`6598`, detailing a shared address space for use in +ISP CGN deployments that can handle the same network prefixes occurring +both on inbound and outbound interfaces. ARIN returned address space to +the {abbr}`IANA (Internet Assigned Numbers Authority)` for this +allocation. + +The allocated address block is 100.64.0.0/10. + +Devices evaluating whether an IPv4 address is public must be updated to +recognize the new address space. Allocating more private IPv4 address +space for NAT devices might prolong the transition to IPv6. + +## Overview + +### Different NAT Types + +(source-nat)= + +#### SNAT + +{abbr}`SNAT (Source Network Address Translation)` is the most common +form of {abbr}`NAT (Network Address Translation)` and is typically +referred to simply as NAT. To be more correct, what most people refer +to as {abbr}`NAT (Network Address Translation)` is actually the process +of {abbr}`PAT (Port Address Translation)`, or NAT overload. SNAT is +typically used by internal users/private hosts to access the Internet +\- the source address is translated and thus kept private. + +(destination-nat)= + +#### DNAT + +{abbr}`DNAT (Destination Network Address Translation)` changes the +destination address of packets passing through the router, while +{ref}`source-nat` changes the source address of packets. DNAT is +typically used when an external (public) host needs to initiate a +session with an internal (private) host. A customer needs to access a +private service behind the routers public IP. A connection is +established with the routers public IP address on a well known port and +thus all traffic for this port is rewritten to address the internal +(private) host. + +(bidirectional-nat)= + +#### Bidirectional NAT + +This is a common scenario where both {ref}`source-nat` and +{ref}`destination-nat` are configured at the same time. It's commonly +used when internal (private) hosts need to establish a connection with +external resources and external systems need to access internal +(private) resources. + +### NAT, Routing, Firewall Interaction + +There is a very nice picture/explanation in the Vyatta documentation +which should be rewritten here. + +### NAT Ruleset + +{abbr}`NAT (Network Address Translation)` is configured entirely on a +series of so called *rules*. Rules are numbered and evaluated by the +underlying OS in numerical order! The rule numbers can be changes by +utilizing the {cfgcmd}`rename` and {cfgcmd}`copy` commands. + +:::{note} +Changes to the NAT system only affect newly established +connections. Already established connections are not affected. +::: + +:::{hint} +When designing your NAT ruleset leave some space between +consecutive rules for later extension. Your ruleset could start with +numbers 10, 20, 30. You thus can later extend the ruleset and place +new rules between existing ones. +::: + +Rules will be created for both {ref}`source-nat` and +{ref}`destination-nat`. + +For {ref}`bidirectional-nat` a rule for both {ref}`source-nat` and +{ref}`destination-nat` needs to be created. + +(traffic-filters)= + +### Traffic Filters + +Traffic Filters are used to control which packets will have the defined +NAT rules applied. Five different filters can be applied within a NAT +rule. + +- **outbound-interface** - applicable only to {ref}`source-nat`. It + configures the interface which is used for the outside traffic that + this translation rule applies to. Interface groups, inverted + selection and wildcard, are also supported. + + Examples: + + ```none + set nat source rule 20 outbound-interface name eth0 + set nat source rule 30 outbound-interface name bond1* + set nat source rule 20 outbound-interface name !vtun2 + set nat source rule 20 outbound-interface group GROUP1 + set nat source rule 20 outbound-interface group !GROUP2 + ``` + +- **inbound-interface** - applicable only to {ref}`destination-nat`. It + configures the interface which is used for the inside traffic the + translation rule applies to. Interface groups, inverted + selection and wildcard, are also supported. + + Example: + + ```none + set nat destination rule 20 inbound-interface name eth0 + set nat destination rule 30 inbound-interface name bond1* + set nat destination rule 20 inbound-interface name !vtun2 + set nat destination rule 20 inbound-interface group GROUP1 + set nat destination rule 20 inbound-interface group !GROUP2 + ``` + +- **protocol** - specify which types of protocols this translation rule + applies to. Only packets matching the specified protocol are NATed. + By default this applies to *all* protocols. + + Example: + + - Set SNAT rule 20 to only NAT TCP and UDP packets + - Set DNAT rule 20 to only NAT UDP packets + + ```none + set nat source rule 20 protocol tcp_udp + set nat destination rule 20 protocol udp + ``` + +- **source** - specifies which packets the NAT translation rule applies + to based on the packets source IP address and/or source port. Only + matching packets are considered for NAT. + + Example: + + - Set SNAT rule 20 to only NAT packets arriving from the 192.0.2.0/24 + network + - Set SNAT rule 30 to only NAT packets arriving from the 203.0.113.0/24 + network with a source port of 80 and 443 + + ```none + set nat source rule 20 source address 192.0.2.0/24 + set nat source rule 30 source address 203.0.113.0/24 + set nat source rule 30 source port 80,443 + ``` + +- **destination** - specify which packets the translation will be + applied to, only based on the destination address and/or port number + configured. + + :::{note} + If no destination is specified the rule will match on any + destination address and port. + ::: + + Example: + + - Configure SNAT rule (40) to only NAT packets with a destination + address of 192.0.2.1. + + ```none + set nat source rule 40 destination address 192.0.2.1 + ``` + +### Address Conversion + +Every NAT rule has a translation command defined. The address defined +for the translation is the address used when the address information in +a packet is replaced. + +#### Source Address + +For {ref}`source-nat` rules the packets source address will be replaced +with the address specified in the translation command. A port +translation can also be specified and is part of the translation +address. + +:::{note} +The translation address must be set to one of the available +addresses on the configured *outbound-interface* or it must be set to +*masquerade* which will use the primary IP address of the +*outbound-interface* as its translation address. +::: + +:::{note} +When using NAT for a large number of host systems it +recommended that a minimum of 1 IP address is used to NAT every 256 +private host systems. This is due to the limit of 65,000 port numbers +available for unique translations and a reserving an average of +200-300 sessions per host system. +::: + +Example: + +- Define a discrete source IP address of 100.64.0.1 for SNAT rule 20 +- Use address *masquerade* (the interfaces primary address) on rule 30 +- For a large amount of private machines behind the NAT your address + pool might to be bigger. Use any address in the range 100.64.0.10 - + 100.64.0.20 on SNAT rule 40 when doing the translation + +```none +set nat source rule 20 translation address 100.64.0.1 +set nat source rule 30 translation address 'masquerade' +set nat source rule 40 translation address 100.64.0.10-100.64.0.20 +``` + +#### Destination Address + +For {ref}`destination-nat` rules the packets destination address will be +replaced by the specified address in the *translation address* command. + +Example: + +- DNAT rule 10 replaces the destination address of an inbound packet + with 192.0.2.10 + +```none +set nat destination rule 10 translation address 192.0.2.10 +``` + +Also, in {ref}`destination-nat`, redirection to localhost is supported. +The redirect statement is a special form of dnat which always translates +the destination address to the local host’s one. + +Example of redirection: + +```none +set nat destination rule 10 translation redirect port 22 +``` + +### NAT Load Balance + +Advanced configuration can be used in order to apply source or destination NAT, +and within a single rule, be able to define multiple translated addresses, +so NAT balances the translations among them. + +NAT Load Balance uses an algorithm that generates a hash and based on it, then +it applies corresponding translation. This hash can be generated randomly, or +can use data from the ip header: source-address, destination-address, +source-port and/or destination-port. By default, it will generate the hash +randomly. + +When defining the translated address, called `backends`, a `weight` must +be configured. This lets the user define load balance distribution according +to their needs. Them sum of all the weights defined for the backends should +be equal to 100. In oder words, the weight defined for the backend is the +percentage of the connections that will receive such backend. + +```{cfgcmd} set nat [source | destination] rule \ load-balance hash [source-address | destination-address | source-port | destination-port | random] +``` + +```{cfgcmd} set nat [source | destination] rule \ load-balance backend \ weight \<1-100\> +``` + +## Configuration Examples + +To setup SNAT, we need to know: +- The internal IP addresses we want to translate +- The outgoing interface to perform the translation on +- The external IP address to translate to + +In the example used for the Quick Start configuration above, we +demonstrate the following configuration: + +```none +set nat source rule 100 outbound-interface name 'eth0' +set nat source rule 100 source address '192.168.0.0/24' +set nat source rule 100 translation address 'masquerade' +``` + +Which generates the following configuration: + +```none +rule 100 { + outbound-interface { + name eth0 + } + source { + address 192.168.0.0/24 + } + translation { + address masquerade + } +} +``` + +In this example, we use **masquerade** as the translation address +instead of an IP address. The **masquerade** target is effectively an +alias to say "use whatever IP address is on the outgoing interface", +rather than a statically configured IP address. This is useful if you +use DHCP for your outgoing interface and do not know what the external +address will be. + +When using NAT for a large number of host systems it recommended that a +minimum of 1 IP address is used to NAT every 256 host systems. This is +due to the limit of 65,000 port numbers available for unique +translations and a reserving an average of 200-300 sessions per host +system. + +Example: For an ~8,000 host network a source NAT pool of 32 IP addresses +is recommended. + +A pool of addresses can be defined by using a hyphen between two IP +addresses: + +```none +set nat source rule 100 translation address '203.0.113.32-203.0.113.63' +``` + +(avoidng-leaky-nat)= + +### Avoiding "leaky" NAT + +Linux netfilter will not NAT traffic marked as INVALID. This often +confuses people into thinking that Linux (or specifically VyOS) has a +broken NAT implementation because non-NATed traffic is seen leaving an +external interface. This is actually working as intended, and a packet +capture of the "leaky" traffic should reveal that the traffic is either +an additional TCP "RST", "FIN,ACK", or "RST,ACK" sent by client systems +after Linux netfilter considers the connection closed. The most common +is the additional TCP RST some host implementations send after +terminating a connection (which is implementation-specific). + +In other words, connection tracking has already observed the connection +be closed and has transition the flow to INVALID to prevent attacks from +attempting to reuse the connection. + +You can avoid the "leaky" behavior by using a firewall policy that drops +"invalid" state packets. + +Having control over the matching of INVALID state traffic, e.g. the +ability to selectively log, is an important troubleshooting tool for +observing broken protocol behavior. For this reason, VyOS does not +globally drop invalid state traffic, instead allowing the operator to +make the determination on how the traffic is handled. + +(hairpin-nat-reflection)= + +### Hairpin NAT/NAT Reflection + +A typical problem with using NAT and hosting public servers is the +ability for internal systems to reach an internal server using it's +external IP address. The solution to this is usually the use of +split-DNS to correctly point host systems to the internal address when +requests are made internally. Because many smaller networks lack DNS +infrastructure, a work-around is commonly deployed to facilitate the +traffic by NATing the request from internal hosts to the source address +of the internal interface on the firewall. + +This technique is commonly referred to as NAT Reflection or Hairpin NAT. + +Example: + +- Redirect Microsoft RDP traffic from the outside (WAN, external) world + via {ref}`destination-nat` in rule 100 to the internal, private host + 192.0.2.40. +- Redirect Microsoft RDP traffic from the internal (LAN, private) + network via {ref}`destination-nat` in rule 110 to the internal, + private host 192.0.2.40. We also need a {ref}`source-nat` rule 110 for + the reverse path of the traffic. The internal network 192.0.2.0/24 is + reachable via interface *eth0.10*. + +```none +set nat destination rule 100 description 'Regular destination NAT from external' +set nat destination rule 100 destination port '3389' +set nat destination rule 100 inbound-interface name 'pppoe0' +set nat destination rule 100 protocol 'tcp' +set nat destination rule 100 translation address '192.0.2.40' + +set nat destination rule 110 description 'NAT Reflection: INSIDE' +set nat destination rule 110 destination port '3389' +set nat destination rule 110 inbound-interface name 'eth0.10' +set nat destination rule 110 protocol 'tcp' +set nat destination rule 110 translation address '192.0.2.40' + +set nat source rule 110 description 'NAT Reflection: INSIDE' +set nat source rule 110 destination address '192.0.2.0/24' +set nat source rule 110 outbound-interface name 'eth0.10' +set nat source rule 110 protocol 'tcp' +set nat source rule 110 source address '192.0.2.0/24' +set nat source rule 110 translation address 'masquerade' +``` + +Which results in a configuration of: + +```none +vyos@vyos# show nat + destination { + rule 100 { + description "Regular destination NAT from external" + destination { + port 3389 + } + inbound-interface { + name pppoe0 + } + protocol tcp + translation { + address 192.0.2.40 + } + } + rule 110 { + description "NAT Reflection: INSIDE" + destination { + port 3389 + } + inbound-interface { + name eth0.10 + } + protocol tcp + translation { + address 192.0.2.40 + } + } + } + source { + rule 110 { + description "NAT Reflection: INSIDE" + destination { + address 192.0.2.0/24 + } + outbound-interface { + name eth0.10 + } + protocol tcp + source { + address 192.0.2.0/24 + } + translation { + address masquerade + } + } + } +``` + +### Destination NAT + +DNAT is typically referred to as a **Port Forward**. When using VyOS as +a NAT router and firewall, a common configuration task is to redirect +incoming traffic to a system behind the firewall. + +In this example, we will be using the example Quick Start configuration +above as a starting point. + +To setup a destination NAT rule we need to gather: +- The interface traffic will be coming in on; +- The protocol and port we wish to forward; +- The IP address of the internal system we wish to forward traffic to. + +In our example, we will be forwarding web server traffic to an internal +web server on 192.168.0.100. HTTP traffic makes use of the TCP protocol +on port 80. For other common port numbers, see: + + +Our configuration commands would be: + +```none +set nat destination rule 10 description 'Port Forward: HTTP to 192.168.0.100' +set nat destination rule 10 destination port '80' +set nat destination rule 10 inbound-interface name 'eth0' +set nat destination rule 10 protocol 'tcp' +set nat destination rule 10 translation address '192.168.0.100' +``` + +Which would generate the following NAT destination configuration: + +```none +nat { + destination { + rule 10 { + description "Port Forward: HTTP to 192.168.0.100" + destination { + port 80 + } + inbound-interface { + name eth0 + } + protocol tcp + translation { + address 192.168.0.100 + } + } + } +} +``` +:::{note} +If forwarding traffic to a different port than it is arriving +on, you may also configure the translation port using +*set nat destination rule [n] translation port*. +::: + +This establishes our Port Forward rule, but if we created a firewall +policy it will likely block the traffic. + +#### Firewall rules for Destination NAT + +It is important to note that when creating firewall rules, the DNAT +translation occurs **before** traffic traverses the firewall. In other +words, the destination address has already been translated to +192.168.0.100. + +So in our firewall ruleset, we want to allow traffic which previously matched +a destination nat rule. In order to avoid creating many rules, one for each +destination nat rule, we can accept all **'dnat'** connections with one simple +rule, using `connection-status` matcher: + +```none +set firewall ipv4 forward filter rule 10 action accept +set firewall ipv4 forward filter rule 10 connection-status nat destination +set firewall ipv4 forward filter rule 10 state new +``` + +This would generate the following configuration: + +```none +ipv4 { + forward { + filter { + rule 10 { + action accept + connection-status { + nat destination + } + state new + } + } + } +} +``` + +### 1-to-1 NAT + +Another term often used for DNAT is **1-to-1 NAT**. For a 1-to-1 NAT +configuration, both DNAT and SNAT are used to NAT all traffic from an +external IP address to an internal IP address and vice-versa. + +Typically, a 1-to-1 NAT rule omits the destination port (all ports) and +replaces the protocol with either **all** or **ip**. + +Then a corresponding SNAT rule is created to NAT outgoing traffic for +the internal IP to a reserved external IP. This dedicates an external IP +address to an internal IP address and is useful for protocols which +don't have the notion of ports, such as GRE. + +Here's an extract of a simple 1-to-1 NAT configuration with one internal +and one external interface: + +```none +set interfaces ethernet eth0 address '192.168.1.1/24' +set interfaces ethernet eth0 description 'Inside interface' +set interfaces ethernet eth1 address '192.0.2.30/24' +set interfaces ethernet eth1 description 'Outside interface' +set nat destination rule 2000 description '1-to-1 NAT example' +set nat destination rule 2000 destination address '192.0.2.30' +set nat destination rule 2000 inbound-interface name 'eth1' +set nat destination rule 2000 translation address '192.168.1.10' +set nat source rule 2000 description '1-to-1 NAT example' +set nat source rule 2000 outbound-interface name 'eth1' +set nat source rule 2000 source address '192.168.1.10' +set nat source rule 2000 translation address '192.0.2.30' +``` + +Firewall rules are written as normal, using the internal IP address as +the source of outbound rules and the destination of inbound rules. + +### NAT before VPN + +Some application service providers (ASPs) operate a VPN gateway to +provide access to their internal resources, and require that a +connecting organisation translate all traffic to the service provider +network to a source address provided by the ASP. + +### Load Balance + +Here we provide two examples on how to apply NAT Load Balance. + +First scenario: apply destination NAT for all HTTP traffic coming through +interface eth0, and user 4 backends. First backend should received 30% of +the request, second backend should get 20%, third 15% and the fourth 35% +We will use source and destination address for hash generation. + +```none +set nat destination rule 10 inbound-interface name eth0 +set nat destination rule 10 protocol tcp +set nat destination rule 10 destination port 80 +set nat destination rule 10 load-balance hash source-address +set nat destination rule 10 load-balance hash destination-address +set nat destination rule 10 load-balance backend 198.51.100.101 weight 30 +set nat destination rule 10 load-balance backend 198.51.100.102 weight 20 +set nat destination rule 10 load-balance backend 198.51.100.103 weight 15 +set nat destination rule 10 load-balance backend 198.51.100.104 weight 35 +``` + +Second scenario: apply source NAT for all outgoing connections from +LAN 10.0.0.0/8, using 3 public addresses and equal distribution. +We will generate the hash randomly. + +```none +set nat source rule 10 outbound-interface name eth0 +set nat source rule 10 source address 10.0.0.0/8 +set nat source rule 10 load-balance hash random +set nat source rule 10 load-balance backend 192.0.2.251 weight 33 +set nat source rule 10 load-balance backend 192.0.2.252 weight 33 +set nat source rule 10 load-balance backend 192.0.2.253 weight 34 +``` + +#### Example Network + +Here's one example of a network environment for an ASP. +The ASP requests that all connections from this company should come from +172.29.41.89 - an address that is assigned by the ASP and not in use at +the customer site. + +```{eval-rst} +.. figure:: /_static/images/nat_before_vpn_topology.webp + :scale: 100 % + :alt: NAT before VPN Topology + + NAT before VPN Topology +``` +#### Configuration + +The required configuration can be broken down into 4 major pieces: +- A dummy interface for the provider-assigned IP; +- NAT (specifically, Source NAT); +- IPSec IKE and ESP Groups; +- IPSec VPN tunnels. + +##### Dummy interface + +The dummy interface allows us to have an equivalent of the Cisco IOS +Loopback interface - a router-internal interface we can use for IP +addresses the router must know about, but which are not actually +assigned to a real network. + +We only need a single step for this interface: + +```none +set interfaces dummy dum0 address '172.29.41.89/32' +``` + +##### NAT Configuration + +```none +set nat source rule 110 description 'Internal to ASP' +set nat source rule 110 destination address '172.27.1.0/24' +set nat source rule 110 source address '192.168.43.0/24' +set nat source rule 110 translation address '172.29.41.89' +set nat source rule 120 description 'Internal to ASP' +set nat source rule 120 destination address '10.125.0.0/16' +set nat source rule 120 source address '192.168.43.0/24' +set nat source rule 120 translation address '172.29.41.89' +``` + +##### IPSec IKE and ESP + +The ASP has documented their IPSec requirements: +- IKE Phase: + - aes256 Encryption + - sha256 Hashes +- ESP Phase: + - aes256 Encryption + - sha256 Hashes + - DH Group 14 + +Additionally, we want to use VPNs only on our eth1 interface (the +external interface in the image above) + +```none +set vpn ipsec ike-group my-ike key-exchange 'ikev1' +set vpn ipsec ike-group my-ike lifetime '7800' +set vpn ipsec ike-group my-ike proposal 1 dh-group '14' +set vpn ipsec ike-group my-ike proposal 1 encryption 'aes256' +set vpn ipsec ike-group my-ike proposal 1 hash 'sha256' + +set vpn ipsec esp-group my-esp lifetime '3600' +set vpn ipsec esp-group my-esp mode 'tunnel' +set vpn ipsec esp-group my-esp pfs 'disable' +set vpn ipsec esp-group my-esp proposal 1 encryption 'aes256' +set vpn ipsec esp-group my-esp proposal 1 hash 'sha256' + +set vpn ipsec interface 'eth1' +``` + +##### IPSec VPN Tunnels + +We'll use the IKE and ESP groups created above for this VPN. Because we +need access to 2 different subnets on the far side, we will need two +different tunnels. If you changed the names of the ESP group and IKE +group in the previous step, make sure you use the correct names here +too. + +```none +set vpn ipsec authentication psk vyos id '203.0.113.46' +set vpn ipsec authentication psk vyos id '198.51.100.243' +set vpn ipsec authentication psk vyos secret 'MYSECRETPASSWORD' +set vpn ipsec site-to-site peer branch authentication local-id '203.0.113.46' +set vpn ipsec site-to-site peer branch authentication mode 'pre-shared-secret' +set vpn ipsec site-to-site peer branch authentication remote-id '198.51.100.243' +set vpn ipsec site-to-site peer branch connection-type 'initiate' +set vpn ipsec site-to-site peer branch default-esp-group 'my-esp' +set vpn ipsec site-to-site peer branch ike-group 'my-ike' +set vpn ipsec site-to-site peer branch ikev2-reauth 'inherit' +set vpn ipsec site-to-site peer branch local-address '203.0.113.46' +set vpn ipsec site-to-site peer branch remote-address '198.51.100.243' +set vpn ipsec site-to-site peer branch tunnel 0 local prefix '172.29.41.89/32' +set vpn ipsec site-to-site peer branch tunnel 0 remote prefix '172.27.1.0/24' +set vpn ipsec site-to-site peer branch tunnel 1 local prefix '172.29.41.89/32' +set vpn ipsec site-to-site peer branch tunnel 1 remote prefix '10.125.0.0/16' +``` + +##### Testing and Validation + +If you've completed all the above steps you no doubt want to see if it's +all working. + +Start by checking for IPSec SAs (Security Associations) with: + +```none +$ show vpn ipsec sa + +Peer ID / IP Local ID / IP +------------ ------------- +198.51.100.243 203.0.113.46 + + Tunnel State Bytes Out/In Encrypt Hash NAT-T A-Time L-Time Proto + ------ ----- ------------- ------- ---- ----- ------ ------ ----- + 0 up 0.0/0.0 aes256 sha256 no 1647 3600 all + 1 up 0.0/0.0 aes256 sha256 no 865 3600 all +``` + +That looks good - we defined 2 tunnels and they're both up and running. diff --git a/docs/configuration/nat/md-nat64.md b/docs/configuration/nat/md-nat64.md new file mode 100644 index 00000000..c1b1c994 --- /dev/null +++ b/docs/configuration/nat/md-nat64.md @@ -0,0 +1,73 @@ +(nat64)= + +# NAT64 + +{abbr}`NAT64 (IPv6-to-IPv4 Prefix Translation)` is a critical component in +modern networking, facilitating communication between IPv6 and IPv4 networks. +This documentation outlines the setup, configuration, and usage of the NAT64 +feature in your project. Whether you are transitioning to IPv6 or need to +seamlessly connect IPv4 and IPv6 devices. +NAT64 is a stateful translation mechanism that translates IPv6 addresses to +IPv4 addresses and IPv4 addresses to IPv6 addresses. NAT64 is used to enable +IPv6-only clients to contact IPv4 servers using unicast UDP, TCP, or ICMP. + +## Overview + +### Different NAT Types + +(source-nat64)= + +#### SNAT64 + +{abbr}`SNAT64 (IPv6-to-IPv4 Source Address Translation)` is a stateful +translation mechanism that translates IPv6 addresses to IPv4 addresses. + +`64:ff9b::/96` is the well-known prefix for IPv4-embedded IPv6 addresses. +The prefix is used to represent IPv4 addresses in an IPv6 address format. +The IPv4 address is encoded in the low-order 32 bits of the IPv6 address. +The high-order 32 bits are set to the well-known prefix 64:ff9b::/96. + +## Configuration Examples + +The following examples show how to configure NAT64 on a VyOS router. +The 192.0.2.10 address is used as the IPv4 address for the translation pool. + +NAT64 server configuration: + +```none +set interfaces ethernet eth0 address '192.0.2.1/24' +set interfaces ethernet eth0 address '192.0.2.10/24' +set interfaces ethernet eth0 description 'WAN' +set interfaces ethernet eth1 address '2001:db8::1/64' +set interfaces ethernet eth1 description 'LAN' + +set service dns forwarding allow-from '2001:db8::/64' +set service dns forwarding dns64-prefix '64:ff9b::/96' +set service dns forwarding listen-address '2001:db8::1' + +set nat64 source rule 100 source prefix '64:ff9b::/96' +set nat64 source rule 100 translation pool 10 address '192.0.2.10' +set nat64 source rule 100 translation pool 10 port '1-65535' +``` + +NAT64 client configuration: + +```none +set interfaces ethernet eth1 address '2001:db8::2/64' +set protocols static route6 64:ff9b::/96 next-hop 2001:db8::1 +set system name-server '2001:db8::1' +``` + +Test from the IPv6 only client: + +```none +vyos@r1:~$ ping 64:ff9b::192.0.2.1 count 2 +PING 64:ff9b::192.0.2.1(64:ff9b::c000:201) 56 data bytes +64 bytes from 64:ff9b::c000:201: icmp_seq=1 ttl=63 time=0.351 ms +64 bytes from 64:ff9b::c000:201: icmp_seq=2 ttl=63 time=0.373 ms + +--- 64:ff9b::192.0.2.1 ping statistics --- +2 packets transmitted, 2 received, 0% packet loss, time 1023ms +rtt min/avg/max/mdev = 0.351/0.362/0.373/0.011 ms +``` + diff --git a/docs/configuration/nat/md-nat66.md b/docs/configuration/nat/md-nat66.md new file mode 100644 index 00000000..1cbe3317 --- /dev/null +++ b/docs/configuration/nat/md-nat66.md @@ -0,0 +1,243 @@ +(nat66)= + +# NAT66(NPTv6) + +```{todo} +Convert raw command blocks in this file to cfgcmd/opcmd +directives for command coverage tracking. +``` + +{abbr}`NPTv6 (IPv6-to-IPv6 Network Prefix Translation)` is an address +translation technology based on IPv6 networks, used to convert an IPv6 +address prefix in an IPv6 message into another IPv6 address prefix. +We call this address translation method NAT66. Devices that support the NAT66 +function are called NAT66 devices, which can provide NAT66 source +and destination address translation functions. + +## Overview + +### Different NAT Types + +(source-nat66)= + +#### SNAT66 + +{abbr}`SNPTv6 (Source IPv6-to-IPv6 Network Prefix Translation)` The conversion +function is mainly used in the following scenarios: +- A single internal network and external network. Use the NAT66 device to + connect a single internal network and public network, and the hosts in + the internal network use IPv6 address prefixes that only support + routing within the local range. When a host in the internal network + accesses the external network, the source IPv6 address prefix in + the message will be converted into a global unicast IPv6 address + prefix by the NAT66 device. +- Redundancy and load sharing. There are multiple NAT66 devices at the edge + of an IPv6 network to another IPv6 network. The path through the NAT66 + device to another IPv6 network forms an equivalent route, and traffic + can be load-shared on these NAT66 devices. In this case, you + can configure the same source address translation rules on these + NAT66 devices, so that any NAT66 device can handle IPv6 traffic between + different sites. +- Multi-homed. In a multi-homed network environment, the NAT66 device + connects to an internal network and simultaneously connects to + different external networks. Address translation can be configured + on each external network side interface of the NAT66 device to + convert the same internal network address into different external + network addresses, and realize the mapping of the same internal + address to multiple external addresses. +(destination-nat66)= + +#### DNAT66 + +The {abbr}`DNPTv6 (Destination IPv6-to-IPv6 Network Prefix Translation)` +destination address translation function is used in scenarios where the +server in the internal network provides services to the external network, +such as providing Web services or FTP services to the external network. +By configuring the mapping relationship between the internal server +address and the external network address on the external network +side interface of the NAT66 device, external network users can +access the internal network server through the designated +external network address. + +### Prefix Conversion + +#### Source Prefix + +Every SNAT66 rule has a translation command defined. The prefix defined +for the translation is the prefix used when the address information in +a packet is replaced.、 + +The {ref}`source-nat66` rule replaces the source address of the packet +and calculates the converted address using the prefix specified in the rule. + +Example: +- Convert the address prefix of a single `fc01::/64` network to `fc00::/64` +- Output from `eth0` network interface + +```none +set nat66 source rule 1 outbound-interface name 'eth0' +set nat66 source rule 1 source prefix 'fc01::/64' +set nat66 source rule 1 translation address 'fc00::/64' +``` + + +#### Destination Prefix + +For the {ref}`destination-nat66` rule, the destination address of +the packet isreplaced by the address calculated from the specified +address or prefix in the `translation address` command + +Example: +- Convert the address prefix of a single `fc00::/64` network + to `fc01::/64` +- Input from `eth0` network interface + +```none +set nat66 destination rule 1 inbound-interface name 'eth0' +set nat66 destination rule 1 destination address 'fc00::/64' +set nat66 destination rule 1 translation address 'fc01::/64' +``` + +For the destination, groups can also be used instead of an address. + +Example: + +```none +set firewall group ipv6-address-group ADR-INSIDE-v6 address fc00::1 + +set nat66 destination rule 1 inbound-interface name 'eth0' +set nat66 destination rule 1 destination group address-group ADR-INSIDE-v6 +set nat66 destination rule 1 translation address 'fc01::/64' +``` + + +## Configuration Examples + +Use the following topology to build a nat66 based isolated +network between internal and external networks (dynamic prefix is +not supported): + +:::{figure} /_static/images/vyos_1_4_nat66_simple.webp +:alt: VyOS NAT66 Simple Configure +::: + +R1: + +```none +set interfaces ethernet eth0 ipv6 address autoconf +set interfaces ethernet eth1 address 'fc01::1/64' +set nat66 destination rule 1 destination address 'fc00:470:f1cd:101::/64' +set nat66 destination rule 1 inbound-interface name 'eth0' +set nat66 destination rule 1 translation address 'fc01::/64' +set nat66 source rule 1 outbound-interface name 'eth0' +set nat66 source rule 1 source prefix 'fc01::/64' +set nat66 source rule 1 translation address 'fc00:470:f1cd:101::/64' +``` + +R2: + +```none +set interfaces bridge br1 address 'fc01::2/64' +set interfaces bridge br1 member interface eth0 +set interfaces bridge br1 member interface eth1 +set protocols static route6 ::/0 next-hop fc01::1 +set service router-advert interface br1 prefix ::/0 +``` + +Use the following topology to translate internal user local addresses +(`fc::/7`) to DHCPv6-PD provided prefixes from an ISP connected to +a VyOS HA pair. + +:::{figure} /_static/images/vyos_1_5_nat66_dhcpv6_wdummy.webp +:alt: VyOS NAT66 DHCPv6 using a dummy interface +::: + +Configure both routers (a and b) for DHCPv6-PD via dummy interface: + +```none +set interfaces dummy dum1 description 'DHCPv6-PD NPT dummy' +set interfaces bonding bond0 vif 20 dhcpv6-options pd 0 interface dum1 address '0' +set interfaces bonding bond0 vif 20 dhcpv6-options pd 1 interface dum1 address '0' +set interfaces bonding bond0 vif 20 dhcpv6-options pd 2 interface dum1 address '0' +set interfaces bonding bond0 vif 20 dhcpv6-options pd 3 interface dum1 address '0' +set interfaces bonding bond0 vif 20 dhcpv6-options rapid-commit +commit +``` + +Get the DHCPv6-PD prefixes from both routers: + +```none +trae@cr01a-vyos# run show interfaces dummy dum1 br +Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down +Interface IP Address S/L Description +--------- ---------- --- ----------- +dum1 2001:db8:123:b008::/64 u/u DHCPv6-PD NPT dummy + 2001:db8:123:b00a::/64 + 2001:db8:123:b00b::/64 + 2001:db8:123:b009::/64 + +trae@cr01b-vyos# run show int dummy dum1 brief +Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down +Interface IP Address S/L Description +--------- ---------- --- ----------- +dum1 2001:db8:123:b00d::/64 u/u DHCPv6-PD NPT dummy + 2001:db8:123:b00c::/64 + 2001:db8:123:b00e::/64 + 2001:db8:123:b00f::/64 +``` + +Configure the A-side router for NPTv6 using the prefixes above: + +```none +set nat66 source rule 10 description 'NPT to VLAN 10' +set nat66 source rule 10 outbound-interface name 'bond0.20' +set nat66 source rule 10 source prefix 'fd52:d62e:8011:a::/64' +set nat66 source rule 10 translation address '2001:db8:123:b008::/64' +set nat66 source rule 20 description 'NPT to VLAN 70' +set nat66 source rule 20 outbound-interface name 'bond0.20' +set nat66 source rule 20 source prefix 'fd52:d62e:8011:46::/64' +set nat66 source rule 20 translation address '2001:db8:123:b009::/64' +set nat66 source rule 30 description 'NPT to VLAN 200' +set nat66 source rule 30 outbound-interface name 'bond0.20' +set nat66 source rule 30 source prefix 'fd52:d62e:8011:c8::/64' +set nat66 source rule 30 translation address '2001:db8:123:b00a::/64' +set nat66 source rule 40 description 'NPT to VLAN 240' +set nat66 source rule 40 outbound-interface name 'bond0.20' +set nat66 source rule 40 source prefix 'fd52:d62e:8011:f0::/64' +set nat66 source rule 40 translation address '2001:db8:123:b00b::/64' +commit +``` + +Configure the B-side router for NPTv6 using the prefixes above: + +```none +set nat66 source rule 10 description 'NPT to VLAN 10' +set nat66 source rule 10 outbound-interface name 'bond0.20' +set nat66 source rule 10 source prefix 'fd52:d62e:8011:a::/64' +set nat66 source rule 10 translation address '2001:db8:123:b00c::/64' +set nat66 source rule 20 description 'NPT to VLAN 70' +set nat66 source rule 20 outbound-interface name 'bond0.20' +set nat66 source rule 20 source prefix 'fd52:d62e:8011:46::/64' +set nat66 source rule 20 translation address '2001:db8:123:b00d::/64' +set nat66 source rule 30 description 'NPT to VLAN 200' +set nat66 source rule 30 outbound-interface name 'bond0.20' +set nat66 source rule 30 source prefix 'fd52:d62e:8011:c8::/64' +set nat66 source rule 30 translation address '2001:db8:123:b00e::/64' +set nat66 source rule 40 description 'NPT to VLAN 240' +set nat66 source rule 40 outbound-interface name 'bond0.20' +set nat66 source rule 40 source prefix 'fd52:d62e:8011:f0::/64' +set nat66 source rule 40 translation address '2001:db8:123:b00f::/64' +commit +``` + +Verify that connections are hitting the rule on both sides: + +```none +trae@cr01a-vyos# run show nat66 source statistics +Rule Packets Bytes Interface +------ --------- ------- ----------- +10 1 104 bond0.20 +20 1 104 bond0.20 +30 8093 669445 bond0.20 +40 2446 216912 bond0.20 +``` diff --git a/docs/configuration/pki/md-index.md b/docs/configuration/pki/md-index.md new file mode 100644 index 00000000..e7d793de --- /dev/null +++ b/docs/configuration/pki/md-index.md @@ -0,0 +1,583 @@ +--- +lastproofread: '2024-01-05' +--- + +```{include} /_include/need_improvement.txt +``` + +(pki)= + +# PKI + +VyOS 1.4 changed the way in how encryption keys or certificates are stored on the +system. In the pre VyOS 1.4 era, certificates got stored under /config and every +service referenced a file. That made copying a running configuration from system +A to system B a bit harder, as you had to copy the files and their permissions +by hand. + +{vytask}`T3642` describes a new CLI subsystem that serves as a "certstore" to +all services requiring any kind of encryption key(s). In short, public and +private certificates are now stored in PKCS#8 format in the regular VyOS CLI. +Keys can now be added, edited, and deleted using the regular set/edit/delete +CLI commands. + +VyOS not only can now manage certificates issued by 3rd party Certificate +Authorities, it can also act as a CA on its own. You can create your own root +CA and sign keys with it by making use of some simple op-mode commands. + +Don't be afraid that you need to re-do your configuration. Key transformation is +handled, as always, by our migration scripts, so this will be a smooth transition +for you! + +## Key Generation + +### Certificate Authority (CA) + +VyOS now also has the ability to create CAs, keys, Diffie-Hellman and other +keypairs from an easy to access operational level command. + +```{opcmd} generate pki ca + +Create a new {abbr}`CA (Certificate Authority)` and output the CAs public and +private key on the console. +``` + +```{opcmd} generate pki ca install \ + +Create a new {abbr}`CA (Certificate Authority)` and output the CAs public and +private key on the console. + +:::{note} +In addition to the command above, the output is in a format which can be used +to directly import the key into the VyOS CLI by simply copy-pasting the output +from op-mode into configuration mode. + +``name`` is used for the VyOS CLI command to identify this key. This +key ``name`` is then used in the CLI configuration to reference the key +instance. +::: +``` + +```{opcmd} generate pki ca sign \ + +Create a new subordinate {abbr}`CA (Certificate Authority)` and sign it using +the private key referenced by ca-name. +``` + +```{opcmd} generate pki ca sign \ install \ + +Create a new subordinate {abbr}`CA (Certificate Authority)` and sign it using +the private key referenced by `name`. + +:::{note} +In addition to the command above, the output is in a format which can be used +to directly import the key into the VyOS CLI by simply copy-pasting the output +from op-mode into configuration mode. + +``name`` is used for the VyOS CLI command to identify this key. This +key ``name`` is then used in the CLI configuration to reference the key +instance. +::: +``` + +### Certificates + +```{opcmd} generate pki certificate + +Create a new public/private keypair and output the certificate on the console. +``` + +```{opcmd} generate pki certificate install \ + +Create a new public/private keypair and output the certificate on the console. + +:::{note} +In addition to the command above, the output is in a format which can be used +to directly import the key into the VyOS CLI by simply copy-pasting the output +from op-mode into configuration mode. + +``name`` is used for the VyOS CLI command to identify this key. This +key ``name`` is then used in the CLI configuration to reference the key +instance. +::: +``` + +```{opcmd} generate pki certificate self-signed + +Create a new self-signed certificate. The public/private is then shown on the +console. +``` + +```{opcmd} generate pki certificate self-signed install \ + +Create a new self-signed certificate. The public/private is then shown on the +console. + +:::{note} +In addition to the command above, the output is in a format which can be used +to directly import the key into the VyOS CLI by simply copy-pasting the output +from op-mode into configuration mode. + +``name`` is used for the VyOS CLI command to identify this key. This +key ``name`` is then used in the CLI configuration to reference the key +instance. +::: +``` + +```{opcmd} generate pki certificate sign \ + +Create a new public/private keypair which is signed by the CA referenced by +ca-name. The signed certificate is then output to the console. +``` + +```{opcmd} generate pki certificate sign \ install \ + +Create a new public/private keypair which is signed by the CA referenced by +ca-name. The signed certificate is then output to the console. + +:::{note} +In addition to the command above, the output is in a format which can be used +to directly import the key into the VyOS CLI by simply copy-pasting the output +from op-mode into configuration mode. + +``name`` is used for the VyOS CLI command to identify this key. This +key ``name`` is then used in the CLI configuration to reference the key +instance. +::: +``` + +### Diffie-Hellman parameters + +```{opcmd} generate pki dh + +Generate a new set of {abbr}`DH (Diffie-Hellman)` parameters. The key size +is requested by the CLI and defaults to 2048 bit. + +The generated parameters are then output to the console. +``` + +```{opcmd} generate pki dh install \ + +Generate a new set of {abbr}`DH (Diffie-Hellman)` parameters. The key size +is requested by the CLI and defaults to 2048 bit. + +:::{note} +In addition to the command above, the output is in a format which can be used +to directly import the key into the VyOS CLI by simply copy-pasting the output +from op-mode into configuration mode. + +``name`` is used for the VyOS CLI command to identify this key. This +key ``name`` is then used in the CLI configuration to reference the key +instance. +::: +``` + +### OpenVPN + +```{opcmd} generate pki openvpn shared-secret + +Generate a new OpenVPN shared secret. The generated secret is the output to +the console. +``` + +```{opcmd} generate pki openvpn shared-secret install \ + +Generate a new OpenVPN shared secret. The generated secret is the output to +the console. + +:::{note} +In addition to the command above, the output is in a format which can be used +to directly import the key into the VyOS CLI by simply copy-pasting the output +from op-mode into configuration mode. + +``name`` is used for the VyOS CLI command to identify this key. This +key ``name`` is then used in the CLI configuration to reference the key +instance. +::: +``` + +### WireGuard + +```{opcmd} generate pki wireguard key-pair + +Generate a new WireGuard public/private key portion and output the result to +the console. +``` + +```{opcmd} generate pki wireguard key-pair install \ + +Generate a new WireGuard public/private key portion and output the result to +the console. + +:::{note} +In addition to the command above, the output is in a format which can +be used to directly import the key into the VyOS CLI by simply copy-pasting +the output from op-mode into configuration mode. + +``interface`` is used for the VyOS CLI command to identify the WireGuard +interface where this private key is to be used. +::: +``` + +```{opcmd} generate pki wireguard preshared-key + +Generate a WireGuard pre-shared secret used for peers to communicate. +``` + +```{opcmd} generate pki wireguard preshared-key install \ + +Generate a WireGuard pre-shared secret used for peers to communicate. + +:::{note} +In addition to the command above, the output is in a format which can +be used to directly import the key into the VyOS CLI by simply copy-pasting +the output from op-mode into configuration mode. + +``peer`` is used for the VyOS CLI command to identify the WireGuard peer where +this secret is to be used. +::: +``` + +## Key usage (CLI) +### CA (Certificate Authority) + +```{cfgcmd} set pki ca \ certificate + +Add the public CA certificate for the CA named `name` to the VyOS CLI. + +:::{note} +When loading the certificate you need to manually strip the +``-----BEGIN CERTIFICATE-----`` and ``-----END CERTIFICATE-----`` tags. +Also, the certificate/key needs to be presented in a single line without +line breaks (``\n``), this can be done using the following shell command: + +``$ tail -n +2 ca.pem | head -n -1 | tr -d '\n'`` +::: +``` + +```{cfgcmd} set pki ca \ crl + +Certificate revocation list in PEM format. +``` + +```{cfgcmd} set pki ca \ description + +A human readable description what this CA is about. +``` + +```{cfgcmd} set pki ca \ private key + +Add the CAs private key to the VyOS CLI. This should never leave the system, +and is only required if you use VyOS as your certificate generator as +mentioned above. + +:::{note} +When loading the certificate you need to manually strip the +``-----BEGIN KEY-----`` and ``-----END KEY-----`` tags. Also, the +certificate/key needs to be presented in a single line without line +breaks (``\n``), this can be done using the following shell command: + +``$ tail -n +2 ca.key | head -n -1 | tr -d '\n'`` +::: +``` + +```{cfgcmd} set pki ca \ private password-protected + +Mark the CAs private key as password protected. User is asked for the password +when the key is referenced. +``` + +### Server Certificate + +After we have imported the CA certificate(s) we can now import and add +certificates used by services on this router. + +```{cfgcmd} set pki certificate \ certificate + +Add public key portion for the certificate named `name` to the VyOS CLI. + +:::{note} +When loading the certificate you need to manually strip the +``-----BEGIN CERTIFICATE-----`` and ``-----END CERTIFICATE-----`` tags. +Also, the certificate/key needs to be presented in a single line without +line breaks (``\n``), this can be done using the following shell command: + +``$ tail -n +2 cert.pem | head -n -1 | tr -d '\n'`` +::: +``` + +```{cfgcmd} set pki certificate \ description + +A human readable description what this certificate is about. +``` + +```{cfgcmd} set pki certificate \ private key + +Add the private key portion of this certificate to the CLI. This should never +leave the system as it is used to decrypt the data. + +:::{note} +When loading the certificate you need to manually strip the +``-----BEGIN KEY-----`` and ``-----END KEY-----`` tags. Also, the +certificate/key needs to be presented in a single line without line +breaks (``\n``), this can be done using the following shell command: + +``$ tail -n +2 cert.key | head -n -1 | tr -d '\n'`` +::: +``` + +```{cfgcmd} set pki certificate \ private password-protected + +Mark the private key as password protected. User is asked for the password +when the key is referenced. +``` + +```{cfgcmd} set pki certificate \ revoke + +If CA is present, this certificate will be included in generated CRLs +``` + +### Import files to PKI format + +VyOS provides this utility to import existing certificates/key files directly +into PKI from op-mode. Previous to VyOS 1.4, certificates were stored under the +/config folder permanently and will be retained post upgrade. + +```{opcmd} import pki ca \ file \ + +Import the public CA certificate from the defined file to VyOS CLI. +``` + +```{opcmd} import pki ca \ key-file \ + +Import the CAs private key portion to the CLI. This should never leave the +system as it is used to decrypt the data. The key is required if you use +VyOS as your certificate generator. +``` + +```{opcmd} import pki certificate \ file \ + +Import the certificate from the file to VyOS CLI. +``` + +```{opcmd} import pki certificate \ key-file \ + +Import the private key of the certificate to the VyOS CLI. This should never +leave the system as it is used to decrypt the data. +``` + +```{opcmd} import pki openvpn shared-secret \ file \ + +Import the OpenVPN shared secret stored in file to the VyOS CLI. +``` + +#### ACME + +The VyOS PKI subsystem can also be used to automatically retrieve Certificates +using the {abbr}`ACME (Automatic Certificate Management Environment)` protocol. + +```{cfgcmd} set pki certificate \ acme domain-name \ + +Domain names to apply, multiple domain-names can be specified. + +This is a mandatory option +``` + +```{cfgcmd} set pki certificate \ acme email \ + +Email used for registration and recovery contact. + +This is a mandatory option +``` + +```{cfgcmd} set pki certificate \ acme listen-address \ + +The address the server listens to during http-01 challenge +``` + +```{cfgcmd} set pki certificate \ acme rsa-key-size \<2048 | 3072 | 4096\> + +Size of the RSA key. + +This options defaults to 2048 +``` + +```{cfgcmd} set pki certificate \ acme url \ + +ACME Directory Resource URI. + +This defaults to https://acme-v02.api.letsencrypt.org/directory + +:::{note} +During initial deployment we recommend using the staging API +of LetsEncrypt to prevent and blacklisting of your system. The API +endpoint is https://acme-staging-v02.api.letsencrypt.org/directory +::: +``` + +## Operation + +VyOS operational mode commands are not only available for generating keys but +also to display them. + +```{opcmd} show pki ca + +Show a list of installed {abbr}`CA (Certificate Authority)` certificates. + +:::{code-block} none +vyos@vyos:~$ show pki ca +Certificate Authorities: +Name Subject Issuer CN Issued Expiry Private Key Parent +-------------- ------------------------------------------------------- ----------------- ------------------- ------------------- ------------- -------------- +DST_Root_CA_X3 CN=ISRG Root X1,O=Internet Security Research Group,C=US CN=DST Root CA X3 2021-01-20 19:14:03 2024-09-30 18:14:03 No N/A +R3 CN=R3,O=Let's Encrypt,C=US CN=ISRG Root X1 2020-09-04 00:00:00 2025-09-15 16:00:00 No DST_Root_CA_X3 +vyos_rw CN=VyOS RW CA,O=VyOS,L=Some-City,ST=Some-State,C=GB CN=VyOS RW CA 2021-07-05 13:46:03 2026-07-04 13:46:03 Yes N/A +::: +``` + +```{opcmd} show pki ca \ + +Show only information for specified Certificate Authority. +``` + +```{opcmd} show pki certificate + +Show a list of installed certificates + +:::{code-block} none +vyos@vyos:~$ show pki certificate +Certificates: +Name Type Subject CN Issuer CN Issued Expiry Revoked Private Key CA Present +--------- ------ --------------------- ------------- ------------------- ------------------- --------- ------------- ------------- +ac2 Server CN=ac2.vyos.net CN=R3 2021-07-05 07:29:59 2021-10-03 07:29:58 No Yes Yes (R3) +rw_server Server CN=VyOS RW CN=VyOS RW CA 2021-07-05 13:48:02 2022-07-05 13:48:02 No Yes Yes (vyos_rw) +::: +``` + +```{opcmd} show pki certificate \ + +Show only information for specified certificate. +``` + +```{opcmd} show pki crl + +Show a list of installed {abbr}`CRLs (Certificate Revocation List)`. +``` + +```{opcmd} renew certbot + +Manually trigger certificate renewal. This will be done twice a day. +``` + +## Examples + +### Create a CA chain and leaf certificates + +This configuration generates & installs into the VyOS PKI system a root +certificate authority, alongside two intermediary certificate authorities for +client & server certificates. These CAs are then used to generate a server +certificate for the router, and a client certificate for a user. +- `vyos_root_ca` is the root certificate authority. +- `vyos_client_ca` and `vyos_server_ca` are intermediary certificate authorities, + which are signed by the root CA. +- `vyos_cert` is a leaf server certificate used to identify the VyOS router, + signed by the server intermediary CA. +- `vyos_example_user` is a leaf client certificate used to identify a user, + signed by client intermediary CA. + +First, we create the root certificate authority. + +```none +[edit] +vyos@vyos# run generate pki ca install vyos_root_ca +Enter private key type: [rsa, dsa, ec] (Default: rsa) rsa +Enter private key bits: (Default: 2048) 2048 +Enter country code: (Default: GB) GB +Enter state: (Default: Some-State) Some-State +Enter locality: (Default: Some-City) Some-City +Enter organization name: (Default: VyOS) VyOS +Enter common name: (Default: vyos.io) VyOS Root CA +Enter how many days certificate will be valid: (Default: 1825) 1825 +Note: If you plan to use the generated key on this router, do not encrypt the private key. +Do you want to encrypt the private key with a passphrase? [y/N] n +2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. +``` + +Secondly, we create the intermediary certificate authorities, which are used to +sign the leaf certificates. + +```none +[edit] +vyos@vyos# run generate pki ca sign vyos_root_ca install vyos_server_ca +Do you already have a certificate request? [y/N] n +Enter private key type: [rsa, dsa, ec] (Default: rsa) rsa +Enter private key bits: (Default: 2048) 2048 +Enter country code: (Default: GB) GB +Enter state: (Default: Some-State) Some-State +Enter locality: (Default: Some-City) Some-City +Enter organization name: (Default: VyOS) VyOS +Enter common name: (Default: vyos.io) VyOS Intermediary Server CA +Enter how many days certificate will be valid: (Default: 1825) 1095 +Note: If you plan to use the generated key on this router, do not encrypt the private key. +Do you want to encrypt the private key with a passphrase? [y/N] n +2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. + + +[edit] +vyos@vyos# run generate pki ca sign vyos_root_ca install vyos_client_ca +Do you already have a certificate request? [y/N] n +Enter private key type: [rsa, dsa, ec] (Default: rsa) rsa +Enter private key bits: (Default: 2048) 2048 +Enter country code: (Default: GB) GB +Enter state: (Default: Some-State) Some-State +Enter locality: (Default: Some-City) Some-City +Enter organization name: (Default: VyOS) VyOS +Enter common name: (Default: vyos.io) VyOS Intermediary Client CA +Enter how many days certificate will be valid: (Default: 1825) 1095 +Note: If you plan to use the generated key on this router, do not encrypt the private key. +Do you want to encrypt the private key with a passphrase? [y/N] n +2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. +``` + +Lastly, we can create the leaf certificates that devices and users will utilise. + +```none +[edit] +vyos@vyos# run generate pki certificate sign vyos_server_ca install vyos_cert +Do you already have a certificate request? [y/N] n +Enter private key type: [rsa, dsa, ec] (Default: rsa) rsa +Enter private key bits: (Default: 2048) 2048 +Enter country code: (Default: GB) GB +Enter state: (Default: Some-State) Some-State +Enter locality: (Default: Some-City) Some-City +Enter organization name: (Default: VyOS) VyOS +Enter common name: (Default: vyos.io) vyos.net +Do you want to configure Subject Alternative Names? [y/N] y +Enter alternative names in a comma separate list, example: ipv4:1.1.1.1,ipv6:fe80::1,dns:vyos.net +Enter Subject Alternative Names: dns:vyos.net,dns:www.vyos.net +Enter how many days certificate will be valid: (Default: 365) 365 +Enter certificate type: (client, server) (Default: server) server +Note: If you plan to use the generated key on this router, do not encrypt the private key. +Do you want to encrypt the private key with a passphrase? [y/N] n +2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. + + +[edit] +vyos@vyos# run generate pki certificate sign vyos_client_ca install vyos_example_user +Do you already have a certificate request? [y/N] n +Enter private key type: [rsa, dsa, ec] (Default: rsa) rsa +Enter private key bits: (Default: 2048) 2048 +Enter country code: (Default: GB) GB +Enter state: (Default: Some-State) Some-State +Enter locality: (Default: Some-City) Some-City +Enter organization name: (Default: VyOS) VyOS +Enter common name: (Default: vyos.io) Example User +Do you want to configure Subject Alternative Names? [y/N] y +Enter alternative names in a comma separate list, example: ipv4:1.1.1.1,ipv6:fe80::1,dns:vyos.net,rfc822:user@vyos.net +Enter Subject Alternative Names: rfc822:example.user@vyos.net +Enter how many days certificate will be valid: (Default: 365) 365 +Enter certificate type: (client, server) (Default: server) client +Note: If you plan to use the generated key on this router, do not encrypt the private key. +Do you want to encrypt the private key with a passphrase? [y/N] n +2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. +``` diff --git a/docs/configuration/policy/md-access-list.md b/docs/configuration/policy/md-access-list.md new file mode 100644 index 00000000..c3a92e56 --- /dev/null +++ b/docs/configuration/policy/md-access-list.md @@ -0,0 +1,70 @@ +# Access List Policy + +Filtering is used for both input and output of the routing information. Once +filtering is defined, it can be applied in any direction. VyOS makes filtering +possible using acls and prefix lists. + +Basic filtering can be done using access-list and access-list6. + +## Configuration + +### Access Lists + +```{cfgcmd} set policy access-list \ + +This command creates the new access list policy, where `` must be +a number from 1 to 2699. +``` + +```{cfgcmd} set policy access-list \ description \ + +Set description for the access list. +``` + +```{cfgcmd} set policy access-list \ rule \<1-65535\> action \ + +This command creates a new rule in the access list and defines an action. +``` + +```{cfgcmd} set policy access-list \ rule \<1-65535\> \ \ + +This command defines matching parameters for access list rule. Matching +criteria could be applied to destination or source parameters: + +* any: any IP address to match. +* host: single host IP address to match. +* inverse-match: network/netmask to match (requires network be defined). +* network: network/netmask to match (requires inverse-match be defined). +``` + + +### IPv6 Access List + +Basic filtering could also be applied to IPv6 traffic. + +```{cfgcmd} set policy access-list6 \ + +This command creates the new IPv6 access list, identified by `` +``` + +```{cfgcmd} set policy access-list6 \ description \ + +Set description for the IPv6 access list. +``` + +```{cfgcmd} set policy access-list6 \ rule \<1-65535\> action \ + +This command creates a new rule in the IPv6 access list and defines an +action. +``` + +```{cfgcmd} set policy access-list6 \ rule \<1-65535\> source \ + +This command defines matching parameters for IPv6 access list rule. Matching +criteria could be applied to source parameters: + +* any: any IPv6 address to match. +* exact-match: exact match of the network prefixes. +* network: network/netmask to match (requires inverse-match be defined) BUG, +NO invert-match option in access-list6 +``` \ No newline at end of file diff --git a/docs/configuration/policy/md-as-path-list.md b/docs/configuration/policy/md-as-path-list.md new file mode 100644 index 00000000..1fcece91 --- /dev/null +++ b/docs/configuration/policy/md-as-path-list.md @@ -0,0 +1,29 @@ +# BGP - AS Path Policy + +VyOS provides policies commands exclusively for BGP traffic filtering and +manipulation: **as-path-list** is one of them. + +## Configuration + +### policy as-path-list + +```{cfgcmd} set policy as-path-list \ + +Create as-path-policy identified by name ``. +``` +```{cfgcmd} set policy as-path-list \ description \ + +Set description for as-path-list policy. +``` +```{cfgcmd} set policy as-path-list \ rule \<1-65535\> action \ + +Set action to take on entries matching this rule. +``` +```{cfgcmd} set policy as-path-list \ rule \<1-65535\> description \ + +Set description for rule. +``` +```{cfgcmd} set policy as-path-list \ rule \<1-65535\> regex \ + +Regular expression to match against an AS path. For example "64501 64502". +``` \ No newline at end of file diff --git a/docs/configuration/policy/md-community-list.md b/docs/configuration/policy/md-community-list.md new file mode 100644 index 00000000..bdcf4140 --- /dev/null +++ b/docs/configuration/policy/md-community-list.md @@ -0,0 +1,29 @@ +# BGP - Community List + +VyOS provides policies commands exclusively for BGP traffic filtering and +manipulation: **community-list** is one of them. + +## Configuration + +### policy community-list + +```{cfgcmd} set policy community-list \ + +Creat community-list policy identified by name ``. +``` +```{cfgcmd} set policy community-list \ description \ + +Set description for community-list policy. +``` +```{cfgcmd} set policy community-list \ rule \<1-65535\> action \ + +Set action to take on entries matching this rule. +``` +```{cfgcmd} set policy community-list \ rule \<1-65535\> description \ + +Set description for rule. +``` +```{cfgcmd} set policy community-list \ rule \<1-65535\> regex \ + +Regular expression to match against a community-list. +``` \ No newline at end of file diff --git a/docs/configuration/policy/md-examples.md b/docs/configuration/policy/md-examples.md new file mode 100644 index 00000000..4dc3f3b0 --- /dev/null +++ b/docs/configuration/policy/md-examples.md @@ -0,0 +1,205 @@ +# BGP Example + +**Policy definition:** + +```none +# Create policy +set policy route-map setmet rule 2 action 'permit' +set policy route-map setmet rule 2 set as-path prepend '2 2 2' + +# Apply policy to BGP +set protocols bgp system-as 1 +set protocols bgp neighbor 203.0.113.2 address-family ipv4-unicast route-map import 'setmet' +set protocols bgp neighbor 203.0.113.2 address-family ipv4-unicast soft-reconfiguration 'inbound' +``` + +Using 'soft-reconfiguration' we get the policy update without bouncing the +neighbor. + +**Routes learned before routing policy applied:** + +```none +vyos@vos1:~$ show ip bgp +BGP table version is 0, local router ID is 192.168.56.101 +Status codes: s suppressed, d damped, h history, * valid, > best, i - internal, + r RIB-failure, S Stale, R Removed +Origin codes: i - IGP, e - EGP, ? - incomplete + + Network Next Hop Metric LocPrf Weight Path +*> 198.51.100.3/32 203.0.113.2 1 0 2 i < Path + +Total number of prefixes 1 +``` + +**Routes learned after routing policy applied:** + +```none +vyos@vos1:~$ show ip bgp +BGP table version is 0, local router ID is 192.168.56.101 +Status codes: s suppressed, d damped, h history, * valid, > best, i - internal, + r RIB-failure, S Stale, R Removed +Origin codes: i - IGP, e - EGP, ? - incomplete + + Network Next Hop Metric LocPrf Weight Path +*> 198.51.100.3/32 203.0.113.2 1 0 2 2 2 2 i + +Total number of prefixes 1 +vyos@vos1:~$ +``` + +You now see the longer AS path. + +# Transparent Proxy + +The following example will show how VyOS can be used to redirect web +traffic to an external transparent proxy: + +```none +set policy route FILTER-WEB rule 1000 destination port 80 +set policy route FILTER-WEB rule 1000 protocol tcp +set policy route FILTER-WEB rule 1000 set table 100 +``` + +This creates a route policy called FILTER-WEB with one rule to set the +routing table for matching traffic (TCP port 80) to table ID 100 +instead of the default routing table. + +To create routing table 100 and add a new default gateway to be used by +traffic matching our route policy: + +```none +set protocols static table 100 route 0.0.0.0/0 next-hop 10.255.0.2 +``` + +This can be confirmed using the `show ip route table 100` operational +command. + +Finally, to apply the policy route to ingress traffic on our LAN +interface, we use: + +```none +set policy route FILTER-WEB interface eth1 +``` + + +# Multiple Uplinks + +VyOS Policy-Based Routing (PBR) works by matching source IP address +ranges and forwarding the traffic using different routing tables. + +Routing tables that will be used in this example are: + +- `table 10` Routing table used for VLAN 10 (192.168.188.0/24) +- `table 11` Routing table used for VLAN 11 (192.168.189.0/24) +- `main` Routing table used by VyOS and other interfaces not + participating in PBR + +:::{figure} /_static/images/pbr_example_1.webp +:alt: PBR multiple uplinks +:scale: 80 % + +Policy-Based Routing with multiple ISP uplinks +(source ./draw.io/pbr_example_1.drawio) +::: + +Add default routes for routing `table 10` and `table 11` + +```none +set protocols static table 10 route 0.0.0.0/0 next-hop 192.0.2.1 +set protocols static table 11 route 0.0.0.0/0 next-hop 192.0.2.2 +``` + +Add policy route matching VLAN source addresses + +```none +set policy route PBR rule 20 set table '10' +set policy route PBR rule 20 description 'Route VLAN10 traffic to table 10' +set policy route PBR rule 20 source address '192.168.188.0/24' + +set policy route PBR rule 30 set table '11' +set policy route PBR rule 30 description 'Route VLAN11 traffic to table 11' +set policy route PBR rule 30 source address '192.168.189.0/24' +``` + +Apply routing policy to **inbound** direction of out VLAN interfaces + +```none +set policy route 'PBR' interface eth0.10 +set policy route 'PBR' interface eth0.11 +``` + +**OPTIONAL:** Exclude Inter-VLAN traffic (between VLAN10 and VLAN11) +from PBR + +```none +set firewall group network-group VLANS-GR description 'VLANs networks' +set firewall group network-group VLANS-GR network '192.168.188.0/24' +set firewall group network-group VLANS-GR network '192.168.189.0/24' + +set policy route PBR rule 10 description 'VLAN10 <-> VLAN11 shortcut' +set policy route PBR rule 10 destination group network-group 'VLANS-GR' +set policy route PBR rule 10 set table 'main' +``` + +These commands allow the VLAN10 and VLAN11 hosts to communicate with +each other using the main routing table. + +## Local route + +The following example allows VyOS to use {abbr}`PBR (Policy-Based Routing)` +for traffic, which originated from the router itself. That solution for multiple +ISP's and VyOS router will respond from the same interface that the packet was +received. Also, it used, if we want that one VPN tunnel to be through one +provider, and the second through another. + +- `203.0.113.254` IP address on VyOS eth1 from ISP1 +- `192.168.2.254` IP address on VyOS eth2 from ISP2 +- `table 10` Routing table used for ISP1 +- `table 11` Routing table used for ISP2 + +```none +set policy local-route rule 101 set table '10' +set policy local-route rule 101 source address '203.0.113.254' +set policy local-route rule 102 set table '11' +set policy local-route rule 102 source address '192.0.2.254' +set protocols static table 10 route 0.0.0.0/0 next-hop '203.0.113.1' +set protocols static table 11 route 0.0.0.0/0 next-hop '192.0.2.2' +``` + +Add multiple source IP in one rule with same priority + +```none +set policy local-route rule 101 set table '10' +set policy local-route rule 101 source address '203.0.113.254' +set policy local-route rule 101 source address '203.0.113.253' +set policy local-route rule 101 source address '198.51.100.0/24' +``` + + +# Clamp MSS for a specific IP + +This example shows how to target an MSS clamp (in our example to 1360 bytes) +to a specific destination IP. + +```none +set policy route IP-MSS-CLAMP rule 10 description 'Clamp TCP session MSS to 1360 for 198.51.100.30' +set policy route IP-MSS-CLAMP rule 10 destination address '198.51.100.30/32' +set policy route IP-MSS-CLAMP rule 10 protocol 'tcp' +set policy route IP-MSS-CLAMP rule 10 set tcp-mss '1360' +set policy route IP-MSS-CLAMP rule 10 tcp flags 'SYN' +``` + +To apply this policy to the correct interface, configure it on the +interface the inbound local host will send through to reach our +destined target host (in our example eth1). + +```none +set policy route IP-MSS-CLAMP interface eth1 +``` + +You can view that the policy is being correctly (or incorrectly) utilised +with the following command: + +```none +show policy route statistics +``` diff --git a/docs/configuration/policy/md-extcommunity-list.md b/docs/configuration/policy/md-extcommunity-list.md new file mode 100644 index 00000000..5247c13c --- /dev/null +++ b/docs/configuration/policy/md-extcommunity-list.md @@ -0,0 +1,33 @@ +# BGP - Extended Community List + +VyOS provides policies commands exclusively for BGP traffic filtering and +manipulation: **extcommunity-list** is one of them. + +## Configuration + +### policy extcommunity-list + +```{cfgcmd} set policy extcommunity-list \ + +Creat extcommunity-list policy identified by name \. +``` +```{cfgcmd} set policy extcommunity-list \ description \ + +Set description for extcommunity-list policy. +``` +```{cfgcmd} set policy extcommunity-list \ rule \<1-65535\> action \ + +Set action to take on entries matching this rule. +``` +```{cfgcmd} set policy extcommunity-list \ rule \<1-65535\> description \ + +Set description for rule. +``` +```{cfgcmd} set policy extcommunity-list \ rule \<1-65535\> regex \ + +Regular expression to match against an extended community list, where text +could be: +* \: Extended community list regular expression. +* \: Route Target regular expression. +* \: Site of Origin regular expression. +``` \ No newline at end of file diff --git a/docs/configuration/policy/md-index.md b/docs/configuration/policy/md-index.md new file mode 100644 index 00000000..f919e70a --- /dev/null +++ b/docs/configuration/policy/md-index.md @@ -0,0 +1,53 @@ +--- +lastproofread: '2021-07-12' +--- + +```{include} /_include/need_improvement.txt +``` + + +# Policy + +Policies are used for filtering and traffic management. With policies, network +administrators could filter and treat traffic +according to their needs. + +There could be a wide range of routing policies. Some examples are listed +below: +- Filter traffic based on source/destination address. +- Set some metric to routes learned from a particular neighbor. +- Set some attributes (like AS PATH or Community value) to advertised routes + to neighbors. +- Prefer a specific routing protocol routes over another routing protocol + running on the same router. + +Policies, in VyOS, are implemented using FRR filtering and route maps. Detailed +information of FRR could be found in + +## Policy Sections + +```{toctree} +:includehidden: true +:maxdepth: 1 + +access-list +prefix-list +route +route-map +local-route +as-path-list +community-list +extcommunity-list +large-community-list +``` + +## Examples + +Examples of policies usage: + +```{toctree} +:includehidden: true +:maxdepth: 1 + +examples +``` diff --git a/docs/configuration/policy/md-large-community-list.md b/docs/configuration/policy/md-large-community-list.md new file mode 100644 index 00000000..23b9a85a --- /dev/null +++ b/docs/configuration/policy/md-large-community-list.md @@ -0,0 +1,29 @@ +# BGP - Large Community List + +VyOS provides policies commands exclusively for BGP traffic filtering and +manipulation: **large-community-list** is one of them. + +## Configuration + +### policy large-community-list + +```{cfgcmd} set policy large-community-list \ + +Create large-community-list policy identified by name ``. +``` +```{cfgcmd} set policy large-community-list \ description \ + +Set description for large-community-list policy. +``` +```{cfgcmd} set policy large-community-list \ rule \<1-65535\> action \ + +Set action to take on entries matching this rule. +``` +```{cfgcmd} set policy large-community-list \ rule \<1-65535\> description \ + +Set description for rule. +``` +```{cfgcmd} set policy large-community-list \ rule \<1-65535\> regex \ + +Regular expression to match against a large community list. +``` \ No newline at end of file diff --git a/docs/configuration/policy/md-local-route.md b/docs/configuration/policy/md-local-route.md new file mode 100644 index 00000000..527a2380 --- /dev/null +++ b/docs/configuration/policy/md-local-route.md @@ -0,0 +1,100 @@ +# Local Route Policy + +Policies for local traffic are defined in this section. + +## Configuration + +### Local Route IPv4 + +```{cfgcmd} set policy local-route rule \<1-32765\> set table \<1-200|main\> + +Set the routing table to use for forwarding matching packets. +``` + +```{cfgcmd} set policy local-route rule \<1-32765\> set vrf \ + +Set the VRF to use for forwarding matching packets. +``` + +```{cfgcmd} set policy local-route rule \<1-32765\> protocol \ + +Match specified protocol (name or number). +``` + +```{cfgcmd} set policy local-route rule \<1-32765\> fwmark \<1-2147483647\> + +Match specified firewall mark (fwmark). +``` + +```{cfgcmd} set policy local-route rule \<1-32765\> source address \ + +Match specified source address or prefix. +``` + +```{cfgcmd} set policy local-route rule \<1-32765\> source port \<1-65535\> + +Match specified source port. +``` + +```{cfgcmd} set policy local-route rule \<1-32765\> destination address \ + +Match specified destination address or prefix. +``` + +```{cfgcmd} set policy local-route rule \<1-32765\> destination port \<1-65535\> + +Match specified destination port. +``` + +```{cfgcmd} set policy local-route rule \<1-32765\> inbound-interface \ + +Match specified inbound interface. +``` + + +### Local Route IPv6 + +```{cfgcmd} set policy local-route6 rule \<1-32765\> set table \<1-200|main\> + +Set the routing table to use for forwarding matching packets. +``` + +```{cfgcmd} set policy local-route6 rule \<1-32765\> set vrf \ + +Set the VRF to use for forwarding matching packets. +``` + +```{cfgcmd} set policy local-route6 rule \<1-32765\> protocol \ + +Match specified protocol (name or number). +``` + +```{cfgcmd} set policy local-route6 rule \<1-32765\> fwmark \<1-2147483647\> + +Match specified firewall mark (fwmark). +``` + +```{cfgcmd} set policy local-route6 rule \<1-32765\> source address \ + +Match specified source address or prefix. +``` + +```{cfgcmd} set policy local-route6 rule \<1-32765\> source port \<1-65535\> + +Match specified source port. +``` + +```{cfgcmd} set policy local-route6 rule \<1-32765\> destination address \ + +Match specified destination address or prefix. +``` + +```{cfgcmd} set policy local-route6 rule \<1-32765\> destination port \<1-65535\> + +Match specified destination port. +``` + +```{cfgcmd} set policy local-route6 rule \<1-32765\> inbound-interface \ + +Match specified inbound interface. +``` \ No newline at end of file diff --git a/docs/configuration/policy/md-prefix-list.md b/docs/configuration/policy/md-prefix-list.md new file mode 100644 index 00000000..eb827c77 --- /dev/null +++ b/docs/configuration/policy/md-prefix-list.md @@ -0,0 +1,152 @@ +# Prefix List Policy + +Prefix lists provides the most powerful prefix based filtering mechanism. In +addition to access-list functionality, ip prefix-list has prefix length range +specification. + +If no ip prefix list is specified, it acts as permit. If ip prefix list is +defined, and no match is found, default deny is applied. + +Prefix filtering can be done using prefix-list and prefix-list6. + +## Configuration + +### IPv4 Prefix Lists (prefix-list) + +```{cfgcmd} set policy prefix-list \ + +This command creates the new prefix-list policy, identified by ``. +``` + +```{cfgcmd} set policy prefix-list \ description \ + +Set description for the prefix-list policy. +``` + +```{cfgcmd} set policy prefix-list \ rule \<1-65535\> action \ + +This command creates a new rule in the prefix-list and defines an action. +``` + +```{cfgcmd} set policy prefix-list \ rule \<1-65535\> description \ + +Set description for rule in the prefix-list. +``` + +```{cfgcmd} set policy prefix-list \ rule \<1-65535\> prefix \ + +Prefix to match against. +``` + +```{cfgcmd} set policy prefix-list \ rule \<1-65535\> ge \<0-32\> + +Netmask greater than length. +``` + +```{cfgcmd} set policy prefix-list \ rule \<1-65535\> le \<0-32\> + +Netmask less than length +``` + + +### Example: IPv4 Prefix Lists (prefix-list) + +This example creates an IPv4 prefix-list named PL4-EXAMPLE-NAME, defines 3 +rules each with 1 prefix, and matches le (less than/equal to) /32. + +```{cfgcmd} set policy prefix-list PL4-EXAMPLE-NAME rule 10 action 'permit' + +``` +```{cfgcmd} set policy prefix-list PL4-EXAMPLE-NAME rule 10 le '32' +``` + +```{cfgcmd} set policy prefix-list PL4-EXAMPLE-NAME rule 10 prefix '192.0.2.0/24' +``` + +```{cfgcmd} set policy prefix-list PL4-EXAMPLE-NAME rule 20 action 'permit' +``` + +```{cfgcmd} set policy prefix-list PL4-EXAMPLE-NAME rule 20 le '32' +``` + +```{cfgcmd} set policy prefix-list PL4-EXAMPLE-NAME rule 20 prefix '198.51.100.0/24' +``` + +```{cfgcmd} set policy prefix-list PL4-EXAMPLE-NAME rule 30 action 'permit' +``` + +```{cfgcmd} set policy prefix-list PL4-EXAMPLE-NAME rule 30 le '32' +``` + +```{cfgcmd} set policy prefix-list PL4-EXAMPLE-NAME rule 30 prefix '203.0.113.0/24' +``` + +### IPv6 Prefix Lists (prefix-list6) + +```{cfgcmd} set policy prefix-list6 \ + +This command creates the new IPv6 prefix-list policy, identified by ``. +``` + +```{cfgcmd} set policy prefix-list6 \ description \ + +Set description for the IPv6 prefix-list policy. +``` + +```{cfgcmd} set policy prefix-list6 \ rule \<1-65535\> action \ + +This command creates a new rule in the IPv6 prefix-list and defines an +action. +``` + +```{cfgcmd} set policy prefix-list6 \ rule \<1-65535\> description \ + +Set description for rule in IPv6 prefix-list. +``` + +```{cfgcmd} set policy prefix-list6 \ rule \<1-65535\> prefix \ + +IPv6 prefix. +``` + +```{cfgcmd} set policy prefix-list6 \ rule \<1-65535\> ge \<0-128\> + +Netmask greater than length. +``` + +```{cfgcmd} set policy prefix-list6 \ rule \<1-65535\> le \<0-128\> + +Netmask less than length +``` + +### Example: IPv6 Prefix Lists (prefix-list6) + +This example creates an IPv6 prefix-list6 named PL6-EXAMPLE-NAME, defines 3 +rules each with 1 prefix, and matches le (less than/equal to) /128. + +```{cfgcmd} set policy prefix-list6 PL6-EXAMPLE-NAME rule 10 action 'permit' +``` + +```{cfgcmd} set policy prefix-list6 PL6-EXAMPLE-NAME rule 10 le '128' +``` + +```{cfgcmd} set policy prefix-list6 PL6-EXAMPLE-NAME rule 10 prefix '2001:db8:0:0::/64' +``` + +```{cfgcmd} set policy prefix-list6 PL6-EXAMPLE-NAME rule 20 action 'permit' +``` + +```{cfgcmd} set policy prefix-list6 PL6-EXAMPLE-NAME rule 20 le '128' +``` + +```{cfgcmd} set policy prefix-list6 PL6-EXAMPLE-NAME rule 20 prefix '2001:db8:0:1::/64' +``` + +```{cfgcmd} set policy prefix-list6 PL6-EXAMPLE-NAME rule 30 action 'permit' +``` + +```{cfgcmd} set policy prefix-list6 PL6-EXAMPLE-NAME rule 30 le '128' +``` + +```{cfgcmd} set policy prefix-list6 PL6-EXAMPLE-NAME rule 30 prefix '2001:db8:0:2::/64' +``` \ No newline at end of file diff --git a/docs/configuration/policy/md-route-map.md b/docs/configuration/policy/md-route-map.md new file mode 100644 index 00000000..cf419a48 --- /dev/null +++ b/docs/configuration/policy/md-route-map.md @@ -0,0 +1,439 @@ +# Route Map Policy + +Route map is a powerful command, that gives network administrators a very +useful and flexible tool for traffic manipulation. + +## Configuration + +### Route Map + +```{cfgcmd} set policy route-map \ + + This command creates a new route-map policy, identified by \. +``` + + +```{cfgcmd} set policy route-map \ description \ + +Set description for the route-map policy. +``` + + +```{cfgcmd} set policy route-map \ rule \<1-65535\> action \ + +Set action for the route-map policy. +``` + + +```{cfgcmd} set policy route-map \ rule \<1-65535\> call \ + +Call another route-map policy on match. +``` + + +```{cfgcmd} set policy route-map \ rule \<1-65535\> continue \<1-65535\> + +Jump to a different rule in this route-map on a match. +``` + + +```{cfgcmd} set policy route-map \ rule \<1-65535\> description \ + +Set description for the rule in the route-map policy. +``` + + +```{cfgcmd} set policy route-map \ rule \<1-65535\> match as-path \ + +BGP as-path list to match. +``` + + +```{cfgcmd} set policy route-map \ rule \<1-65535\> match community community-list \ + +BGP community-list to match. +``` + + +```{cfgcmd} set policy route-map \ rule \<1-65535\> match community exact-match + +Set BGP community-list to exactly match. +``` + + +```{cfgcmd} set policy route-map \ rule \<1-65535\> match extcommunity \ + +BGP extended community to match. +``` + + +```{cfgcmd} set policy route-map \ rule \<1-65535\> match interface \ + +First hop interface of a route to match. +``` + + +```{cfgcmd} set policy route-map \ rule \<1-65535\> match ip address access-list \<1-2699\> + +IP address of route to match, based on access-list. +``` + + +```{cfgcmd} set policy route-map \ rule \<1-65535\> match ip address prefix-list \ + +IP address of route to match, based on prefix-list. +``` + + +```{cfgcmd} set policy route-map \ rule \<1-65535\> match ip address prefix-len \<0-32\> + +IP address of route to match, based on specified prefix-length. +Note that this can be used for kernel routes only. +Do not apply to the routes of dynamic routing protocols (e.g. BGP, +RIP, OSFP), as this can lead to unexpected results.. +``` + + +```{cfgcmd} set policy route-map \ rule \<1-65535\> match ip nexthop access-list \<1-2699\> + +IP next-hop of route to match, based on access-list. +``` + + +```{cfgcmd} set policy route-map \ rule \<1-65535\> match ip nexthop address \ + +IP next-hop of route to match, based on ip address. +``` + + +```{cfgcmd} set policy route-map \ rule \<1-65535\> match ip nexthop prefix-len \<0-32\> + +IP next-hop of route to match, based on prefix length. +``` + + +```{cfgcmd} set policy route-map \ rule \<1-65535\> match ip nexthop prefix-list \ + +IP next-hop of route to match, based on prefix-list. +``` + + +```{cfgcmd} set policy route-map \ rule \<1-65535\> match ip nexthop type \ + +IP next-hop of route to match, based on type. +``` + + +```{cfgcmd} set policy route-map \ rule \<1-65535\> match ip route-source access-list \<1-2699\> + +IP route source of route to match, based on access-list. +``` + + +```{cfgcmd} set policy route-map \ rule \<1-65535\> match ip route-source prefix-list \ + +IP route source of route to match, based on prefix-list. +``` + + +```{cfgcmd} set policy route-map \ rule \<1-65535\> match ipv6 address access-list \ + +IPv6 address of route to match, based on IPv6 access-list. +``` + + +```{cfgcmd} set policy route-map \ rule \<1-65535\> match ipv6 address prefix-list \ + +IPv6 address of route to match, based on IPv6 prefix-list. +``` + + +```{cfgcmd} set policy route-map \ rule \<1-65535\> match ipv6 address prefix-len \<0-128\> + +IPv6 address of route to match, based on specified prefix-length. +Note that this can be used for kernel routes only. +Do not apply to the routes of dynamic routing protocols (e.g. BGP, +RIP, OSFP), as this can lead to unexpected results.. +``` + + +```{cfgcmd} set policy route-map \ rule \<1-65535\> match ipv6 nexthop \ + +Nexthop IPv6 address to match. +``` + + +```{cfgcmd} set policy route-map \ rule \<1-65535\> match large-community large-community-list \ + +Match BGP large communities. +``` + + +```{cfgcmd} set policy route-map \ rule \<1-65535\> match local-preference \<0-4294967295\> + +Match local preference. +``` + + +```{cfgcmd} set policy route-map \ rule \<1-65535\> match metric \<1-65535\> + +Match route metric. +``` + + +```{cfgcmd} set policy route-map \ rule \<1-65535\> match origin \ + +Boarder Gateway Protocol (BGP) origin code to match. +``` + + +```{cfgcmd} set policy route-map \ rule \<1-65535\> match peer \ + +Peer IP address to match. +``` + + +````{cfgcmd} set policy route-map \ rule \<1-65535\> match protocol \ + +```{eval-rst} +Source protocol to match. + * ``babel`` - Babel routing protocol (Babel) + * ``bgp`` - Border Gateway Protocol (BGP) + * ``connected`` - Connected routes (directly attached subnet or host) + * ``isis`` - Intermediate System to Intermediate System (IS-IS) + * ``kernel`` - Kernel routes + * ``ospf`` - Open Shortest Path First (OSPFv2) + * ``ospfv3`` - Open Shortest Path First (IPv6) (OSPFv3) + * ``rip`` - Routing Information Protocol (RIP) + * ``ripng`` - Routing Information Protocol next-generation (IPv6) (RIPng) + * ``static`` - Statically configured routes + * ``table`` - Non-main Kernel Routing Table + * ``vnc`` - Virtual Network Control (VNC) +``` +```` + + +```{cfgcmd} set policy route-map \ rule \<1-65535\> match rpki \ + +Match RPKI validation result. +``` + + +```{cfgcmd} set policy route-map \ rule \<1-65535\> match source-vrf \ + +Source VRF to match. +``` + + +```{cfgcmd} set policy route-map \ rule \<1-65535\> match tag \<1-65535\> + +Route tag to match. +``` + + +```{cfgcmd} set policy route-map \ rule \<1-65535\> on-match goto \<1-65535\> + +Exit policy on match: go to rule <1-65535> +``` + + +```{cfgcmd} set policy route-map \ rule \<1-65535\> on-match next + +Exit policy on match: go to next sequence number. +``` + + +```{cfgcmd} set policy route-map \ rule \<1-65535\> set aggregator \ \<1-4294967295|x.x.x.x\> + +BGP aggregator attribute: AS number or IP address of an aggregation. +``` + + +```{cfgcmd} set policy route-map \ rule \<1-65535\> set as-path exclude \<1-4294967295 | all\> + +Drop AS-NUMBER from the BGP AS path. + +If ``all`` is specified, remove all AS numbers from the AS_PATH of the BGP +path's NLRI. +``` + + +```{cfgcmd} set policy route-map \ rule \<1-65535\> set as-path prepend \<1-4294967295\> + +Prepend the given string of AS numbers to the AS_PATH of the BGP path's NLRI. +``` + + +```{cfgcmd} set policy route-map \ rule \<1-65535\> set as-path prepend-last-as \ + +Prepend the existing last AS number (the leftmost ASN) to the AS_PATH. +``` + + +```{cfgcmd} set policy route-map \ rule \<1-65535\> set atomic-aggregate + +BGP atomic aggregate attribute. +``` + + +```{cfgcmd} set policy route-map \ rule \<1-65535\> set community \ \ + +Add or replace BGP community attribute in format ``<0-65535:0-65535>`` +or from well-known community list +``` + + +```{cfgcmd} set policy route-map \ rule \<1-65535\> set community none + +Delete all BGP communities +``` + + +```{cfgcmd} set policy route-map \ rule \<1-65535\> set community delete \ + +Delete BGP communities matching the community-list. +``` + + +```{cfgcmd} set policy route-map \ rule \<1-65535\> set large-community \ \ + +Add or replace BGP large-community attribute in format +``<0-4294967295:0-4294967295:0-4294967295>`` +``` + + +```{cfgcmd} set policy route-map \ rule \<1-65535\> set large-community none + +Delete all BGP large-communities +``` + + +```{cfgcmd} set policy route-map \ rule \<1-65535\> set large-community delete \ + +Delete BGP communities matching the large-community-list. +``` + + +```{cfgcmd} set policy route-map \ rule \<1-65535\> set extcommunity bandwidth \<1-25600|cumulative|num-multipaths\> + +Set extcommunity bandwidth +``` + + +```{cfgcmd} set policy route-map \ rule \<1-65535\> set extcommunity bandwidth-non-transitive + +The link bandwidth extended community is encoded as non-transitive +``` + + +```{cfgcmd} set policy route-map \ rule \<1-65535\> set extcommunity rt \ + +Set route target value in format ``<0-65535:0-4294967295>`` or ````. +``` + + +```{cfgcmd} set policy route-map \ rule \<1-65535\> set extcommunity soo \ + +Set site of origin value in format ``<0-65535:0-4294967295>`` or ````. +``` + + +```{cfgcmd} set policy route-map \ rule \<1-65535\> set extcommunity none + +Clear all BGP extcommunities. +``` + + +```{cfgcmd} set policy route-map \ rule \<1-65535\> set distance \<0-255\> + +Locally significant administrative distance. +``` +```{cfgcmd} set policy route-map \ rule \<1-65535\> set ip-next-hop \ + +Nexthop IP address. +``` +```{cfgcmd} set policy route-map \ rule \<1-65535\> set ip-next-hop unchanged + +Set the next-hop as unchanged. Pass through the route-map without +changing its value +``` +```{cfgcmd} set policy route-map \ rule \<1-65535\> set ip-next-hop peer-address + +Set the BGP nexthop address to the address of the peer. For an incoming +route-map this means the ip address of our peer is used. For an +outgoing route-map this means the ip address of our self is used to +establish the peering with our neighbor. +``` +```{cfgcmd} set policy route-map \ rule \<1-65535\> set ipv6-next-hop \ \ + +Nexthop IPv6 address. +``` +```{cfgcmd} set policy route-map \ rule \<1-65535\> set ipv6-next-hop peer-address + +Set the BGP nexthop address to the address of the peer. For an incoming +route-map this means the ip address of our peer is used. For an +outgoing route-map this means the ip address of our self is used to +establish the peering with our neighbor. +``` +```{cfgcmd} set policy route-map \ rule \<1-65535\> set ipv6-next-hop prefer-global + +For Incoming and Import Route-maps if we receive a v6 global and v6 LL +address for the route, then prefer to use the global address as the +nexthop. +``` +```{cfgcmd} set policy route-map \ rule \<1-65535\> set local-preference \<0-4294967295\> + +Set BGP local preference attribute. +``` +```{cfgcmd} set policy route-map \ rule \<1-65535\> set metric \<+/-metric|0-4294967295|rtt|+rtt|-rtt\> + +Set the route metric. When used with BGP, set the BGP attribute MED +to a specific value. Use ``+/-`` to add or subtract the specified value +to/from the existing/MED. Use ``rtt`` to set the MED to the round trip +time or ``+rtt/-rtt`` to add/subtract the round trip time to/from the MED. +``` +```{cfgcmd} set policy route-map \ rule \<1-65535\> set metric-type \ + +Set OSPF external metric-type. +``` +```{cfgcmd} set policy route-map \ rule \<1-65535\> set origin \ + +Set BGP origin code. +``` +```{cfgcmd} set policy route-map \ rule \<1-65535\> set originator-id \ + +Set BGP originator ID attribute. +``` +```{cfgcmd} set policy route-map \ rule \<1-65535\> set src \ + +Set source IP/IPv6 address for route. +``` +```{cfgcmd} set policy route-map \ rule \<1-65535\> set table \<1-200\> + +Set prefixes to table. +``` +```{cfgcmd} set policy route-map \ rule \<1-65535\> set tag \<1-65535\> + +Set tag value for routing protocol. +``` +```{cfgcmd} set policy route-map \ rule \<1-65535\> set weight \<0-4294967295\> + +Set BGP weight attribute +``` + +### List of well-known communities + +> - `local-as` - Well-known communities value NO_EXPORT_SUBCONFED 0xFFFFFF03 +> - `no-advertise` - Well-known communities value NO_ADVERTISE 0xFFFFFF02 +> - `no-export` - Well-known communities value NO_EXPORT 0xFFFFFF01 +> - `graceful-shutdown` - Well-known communities value GRACEFUL_SHUTDOWN 0xFFFF0000 +> - `accept-own` - Well-known communities value ACCEPT_OWN 0xFFFF0001 +> - `route-filter-translated-v4` - Well-known communities value ROUTE_FILTER_TRANSLATED_v4 0xFFFF0002 +> - `route-filter-v4` - Well-known communities value ROUTE_FILTER_v4 0xFFFF0003 +> - `route-filter-translated-v6` - Well-known communities value ROUTE_FILTER_TRANSLATED_v6 0xFFFF0004 +> - `route-filter-v6` - Well-known communities value ROUTE_FILTER_v6 0xFFFF0005 +> - `llgr-stale` - Well-known communities value LLGR_STALE 0xFFFF0006 +> - `no-llgr` - Well-known communities value NO_LLGR 0xFFFF0007 +> - `accept-own-nexthop` - Well-known communities value accept-own-nexthop 0xFFFF0008 +> - `blackhole` - Well-known communities value BLACKHOLE 0xFFFF029A +> - `no-peer` - Well-known communities value NOPEER 0xFFFFFF04 diff --git a/docs/configuration/policy/md-route.md b/docs/configuration/policy/md-route.md new file mode 100644 index 00000000..b3ef6540 --- /dev/null +++ b/docs/configuration/policy/md-route.md @@ -0,0 +1,424 @@ +# Route and Route6 Policy + +IPv4 route and IPv6 route policies are defined in this section. These route +policies can then be associated to interfaces. + +## Rule-Sets + +A rule-set is a named collection of rules that can be applied to an interface. +Each rule is numbered, has an action to apply if the rule is matched, and the +ability to specify the criteria to match. Data packets go through the rules +from 1 - 999999, at the first match the action of the rule will be executed. + +```{cfgcmd} set policy route \ description \ + +``` +```{cfgcmd} set policy route6 \ description \ + +Provide a rule-set description. +``` + +```{cfgcmd} set policy route \ default-log +``` + +```{cfgcmd} set policy route6 \ default-log + +Option to log packets hitting default-action. +``` + +```{cfgcmd} set policy route \ interface \ +``` + +```{cfgcmd} set policy route6 \ interface \ + +Apply routing policy to interface +``` + +```{cfgcmd} set policy route \ rule \ description \ +``` + +```{cfgcmd} set policy route6 \ rule \ description \ + +Provide a description for each rule. +``` + +```{cfgcmd} set policy route \ rule \ log \ +``` + +```{cfgcmd} set policy route6 \ rule \ log \ + +Option to enable or disable log matching rule. +``` + +### Matching criteria + +There are a lot of matching criteria options available, both for +`policy route` and `policy route6`. These options are listed +in this section. + +```{cfgcmd} set policy route \ rule \ connection-mark \<1-2147483647\> +``` + +```{cfgcmd} set policy route6 \ rule \ connection-mark \<1-2147483647\> + +Set match criteria based on connection mark. +``` + +```{cfgcmd} set policy route \ rule \ mark \ +``` + +```{cfgcmd} set policy route6 \ rule \ mark \ + +Match based on the firewall mark (fwmark), where \ can be: + * \<0-2147483647\> a single fwmark + * !\<0-2147483647\> everything except a single fwmark + * <start-end> a range of marks + * !<start-end> everything except the range of marks + +:::{note} +When using the ``set table`` or ``set vrf`` commands the mark +settings are ignored and overwritten with a table-specific mark that +is set to 0x7FFFFFFF - the id of the table/VRF. +::: +``` + +```{cfgcmd} set policy route \ rule \ source address \ +``` + +```{cfgcmd} set policy route \ rule \ destination address \ +``` + +```{cfgcmd} set policy route6 \ rule \ source address \ +``` + +```{cfgcmd} set policy route6 \ rule \ destination address \ + +Set match criteria based on source or destination ipv4|ipv6 address, where +<match_criteria> could be: +``` + +For ipv4: +: - \: IP address to match. + - \: Subnet to match. + - \-\: IP range to match. + - !\: Match everything except the specified address. + - !\: Match everything except the specified subnet. + - !\-\: Match everything except the specified range. + +And for ipv6: +: - \: IPv6 address to match. + - \: IPv6 prefix to match. + - \-\: IPv6 range to match. + - !\: Match everything except the specified address. + - !\: Match everything except the specified prefix. + - !\-\: Match everything except the + specified range. + +```{cfgcmd} set policy route \ rule \ source group \ \ +``` + +```{cfgcmd} set policy route \ rule \ destination group \ \ +``` + +```{cfgcmd} set policy route6 \ rule \ source group \ \ +``` + +```{cfgcmd} set policy route6 \ rule \ destination group \ \ + +Set match criteria based on source or destination groups, where <text> +would be the group name/identifier. Prepend character '!' for inverted +matching criteria. +``` + +```{cfgcmd} set policy route \ rule \ destination port \ +``` + +```{cfgcmd} set policy route6 \ rule \ destination port \ + +Set match criteria based on destination port, where \ could +be: +* <port name>: Named port (any name in /etc/services, e.g., http). +* \<1-65535\>: Numbered port. +* <start>-<end>: Numbered port range (e.g., 1001-1005). + +Multiple destination ports can be specified as a comma-separated list. The +whole list can also be "negated" using '!'. For example: +'!22,telnet,http,123,1001-1005' +``` + +```{cfgcmd} set policy route \ rule \ disable +``` + +```{cfgcmd} set policy route6 \ rule \ disable + +Option to disable rule. +``` + +```{cfgcmd} set policy route \ rule \ dscp \ +``` + +```{cfgcmd} set policy route6 \ rule \ dscp \ +``` + +```{cfgcmd} set policy route \ rule \ dscp-exclude \ +``` + +```{cfgcmd} set policy route6 \ rule \ dscp-exclude \ + +Match based on dscp value criteria. Multiple values from 0 to 63 +and ranges are supported. +``` + +```{cfgcmd} set policy route \ rule \ fragment \ +``` + +```{cfgcmd} set policy route6 \ rule \ fragment \ + +Set IP fragment match, where: +* match-frag: Second and further fragments of fragmented packets. +* match-non-frag: Head fragments or unfragmented packets. +``` + +```{cfgcmd} set policy route \ rule \ icmp \ +``` + +```{cfgcmd} set policy route6 \ rule \ icmpv6 \ + +Match based on icmp|icmpv6 code and type. +``` + +```{cfgcmd} set policy route \ rule \ icmp type-name \ +``` + +```{cfgcmd} set policy route6 \ rule \ icmpv6 type-name \ + +Match based on icmp|icmpv6 type-name criteria. Use tab for information +about what type-name criteria are supported. +``` + +```{cfgcmd} set policy route \ rule \ ipsec \ +``` + +```{cfgcmd} set policy route6 \ rule \ ipsec \ + +Set IPSec inbound match criterias, where: +* match-ipsec: match inbound IPsec packets. +* match-none: match inbound non-IPsec packets. +``` + +```{cfgcmd} set policy route \ rule \ limit burst \<0-4294967295\> +``` + +```{cfgcmd} set policy route6 \ rule \ limit burst \<0-4294967295\> + +Set maximum number of packets to allow 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 matching all patterns defined in a rule, then different actions can +be made. This includes dropping the packet, modifying certain data, or +setting a different routing table. + +```{cfgcmd} set policy route \ 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 new file mode 100644 index 00000000..7d9bf4f9 --- /dev/null +++ b/docs/configuration/protocols/md-arp.md @@ -0,0 +1,72 @@ +```{eval-rst} +.. meta:: + :description: The Address Resolution Protocol (ARP) resolves + network-layer addresses to link-layer MAC addresses. + :keywords: arp, network, protocol, mac, address, ipv4, static +``` + +(routing_static_arp)= + +# ARP + +The {abbr}`ARP (Address Resolution Protocol)` resolves IPv4 network layer addresses +to link layer MAC addresses. +addresses. This mapping is essential for communication within the Internet +Protocol suite. ARP was standardized in 1982 by {rfc}`826` (STD 37). + +:::{note} +In Internet Protocol version 6 (IPv6) networks, address resolution is +performed by the Neighbor Discovery Protocol (NDP). +::: + +Use the following commands to configure or view ARP table entries. + +## Configuration + +```{eval-rst} +.. cfgcmd:: set protocols static arp interface address mac + + **Configure a static ARP entry on the specified interface.** + + This creates a permanent mapping between an IP address and a MAC address + on the specified interface. + + Example: + + .. code-block:: none + + set protocols static arp interface eth0 address 192.0.2.1 mac 01:23:45:67:89:01 +``` + +## Operation + +```{eval-rst} +.. opcmd:: show protocols static arp + + Show all ARP table entries across all interfaces. + + .. code-block:: none + + vyos@vyos:~$ show protocols static arp + Address HWtype HWaddress Flags Mask Iface + 10.1.1.1 ether 00:53:00:de:23:2e C eth1 + 10.1.1.100 ether 00:53:00:de:23:aa CM eth1 +``` + +```{eval-rst} +.. opcmd:: show protocols static arp interface + + Show all ARP table entries for the specific interface. + + Example for ``eth1``: + + .. code-block:: none + + vyos@vyos:~$ show protocols static arp interface eth1 + Address HWtype HWaddress Flags Mask Iface + 10.1.1.1 ether 00:53:00:de:23:2e C eth1 + 10.1.1.100 ether 00:53:00:de:23:aa CM eth1 +``` + +[arp]: https://en.wikipedia.org/wiki/Address_Resolution_Protocol + diff --git a/docs/configuration/protocols/md-babel.md b/docs/configuration/protocols/md-babel.md new file mode 100644 index 00000000..b03e9fa4 --- /dev/null +++ b/docs/configuration/protocols/md-babel.md @@ -0,0 +1,296 @@ +```{eval-rst} +.. meta:: + :description: The Babel routing protocol provides robust and efficient + routing for wired and wireless mesh networks. + :keywords: babel, routing, protocol, wireless, mesh, network, metric, + ipv4, ipv6 +``` + +(babel)= + +# Babel + +The Babel protocol provides robust and efficient routing for both wired and +wireless mesh networks. By default, Babel uses hop-count metrics on wired links +and a variant of Expected Transmission Count (ETX) on wireless links. +Administrators can configure Babel to account for radio diversity, +automatically compute link latency, and include that latency in the routing +metric. {rfc}`8966` defines the Babel protocol. + +Babel is a dual-stack protocol. A single Babel instance routes both IPv4 and +IPv6 traffic simultaneously. + +## General configuration + +VyOS does not require a specific command to start the Babel process. The system +automatically starts the routing process when you configure the first +Babel-enabled interface. + +```{cfgcmd} set protocols babel interface \ + +**Enable Babel routing on the specified interface.** + +The system immediately begins sending and receiving Babel packets on this +interface. +``` + +## Optional configuration + +```{cfgcmd} set protocols babel parameters diversity + +**Enable radio-frequency diversity routing for the Babel process.** + +Enabling this feature is highly recommended for networks with many +wireless nodes. + +:::{note} +When you enable diversity routing, you should also configure the +``diversity-factor`` and ``channel`` parameters. +::: +``` + +```{cfgcmd} set protocols babel parameters diversity-factor \<1-256\> + +**Configure the multiplicative factor for diversity routing, in units of +1/256.** + +Lower multiplicative factors give greater weight to diversity in route +selection. The default value is 256, which disables diversity routing. +On nodes with multiple independent radios, configure a value of 128 or less. +``` + +```{cfgcmd} set protocols babel parameters resend-delay \<20-655340\> + +**Configure the delay in milliseconds before the system resends an +important request or update.** + +The default value is 2000 ms. +``` + +```{cfgcmd} set protocols babel parameters smoothing-half-life \<0-65534\> + +**Configure the time constant, in seconds, for the smoothing algorithm used +to implement hysteresis.** + +Higher values reduce route oscillation but slightly increase convergence +time. A value of 0 disables hysteresis and is suitable for wired networks. +The default is 4 seconds. +``` + +## Interfaces configuration + +```{cfgcmd} set protocols babel interface \ type \ + +**Configure the network type for the Babel-enabled interface.** + +Choose from the following: + +* ``auto``: Babel automatically detects if an interface is wired or + wireless. +* ``wired``: Babel enables optimizations for wired interfaces. +* ``wireless``: Babel disables optimizations suitable only for wired + interfaces. Specifying wireless is always correct, but may cause slower + convergence and increased routing traffic. +``` + +```{cfgcmd} set protocols babel interface \ split-horizon \ + +**Configure the split-horizon routing behavior for the specified +interface.** + +Use one of the following options: + +* ``default``: Babel automatically enables split-horizon on wired + interfaces and disables it on wireless interfaces. +* ``enable``: Babel enables split-horizon on the interface. This + optimization should be used only on symmetric, transitive (wired) + networks. +* ``disable``: Babel disables split-horizon on the interface. Disabling + split-horizon is always safe and correct. +``` + +```{cfgcmd} set protocols babel interface \ hello-interval \<20-655340\> + +**Configure the interval, in milliseconds, between scheduled hello messages +on the specified interface.** + +On wired links, Babel detects link failures within two hello intervals. +On wireless links, link quality is reestimated at each interval. The +default is 4000 ms. +``` + +```{cfgcmd} set protocols babel interface \ update-interval \<20-655340\> + +**Configure the interval, in milliseconds, between scheduled routing +updates on the specified interface.** + +Because Babel uses triggered updates extensively, you can increase this +value on reliable links with minimal packet loss. The default is 20000 ms. +``` + +```{cfgcmd} set protocols babel interface \ rxcost \<1-65534\> + +**Configure the base receive cost for the specified interface.** + +Babel applies this value based on the configured network type: + +* ``wired``: The value is the routing cost advertised to neighboring + routers. +* ``wireless``: The value is a multiplier used to compute the ETX + (Expected Transmission Count) reception cost. + +The default value is 256. +``` + +```{cfgcmd} set protocols babel interface \ rtt-decay \<1-256\> + +**Configure the decay factor for the exponential moving average of RTT +samples, in units of 1/256.** + +Higher values discard older samples faster. The default value is 42. +``` + +```{cfgcmd} set protocols babel interface \ rtt-min \<1-65535\> + +**Configure the minimum RTT, in milliseconds, at which the cost to a +neighbor begins to increase.** + +The additional cost is linear in (rtt - rtt-min). The default value is 10 ms. +``` + +```{cfgcmd} set protocols babel interface \ rtt-max \<1-65535\> + +**Configure the maximum RTT, in milliseconds, above which the cost to a +neighbor stops increasing.** + +The default value is 120 ms. +``` + +```{cfgcmd} set protocols babel interface \ max-rtt-penalty \<0-65535\> + +**Configure the maximum cost added to a neighbor when RTT meets or exceeds +rtt-max.** + +Setting this value to 0 disables RTT-based costs. The default value is 150. +``` + +```{cfgcmd} set protocols babel interface \ enable-timestamps + +**Configure adding timestamps to each Hello and IHU message to calculate +RTT values.** + +Enabling timestamps is recommended for tunnel interfaces. +``` + +```{cfgcmd} set protocols babel interface \ channel \<1-254|interfering|noninterfering\> + +**Configure the channel identifier that diversity routing uses for the +specified interface.** + +Interfaces interfere with each other based on the assigned channel +identifier: + +* ``1–254``: The interface interferes with interfaces sharing the same + channel number and with interfaces configured as ``interfering``. +* ``interfering``: The interface interferes with all others except those + configured as ``noninterfering``. +* ``noninterfering``: The interface interferes only with itself. +``` + +## Redistribution configuration + +```{cfgcmd} set protocols babel redistribute \ \ + +**Configure the redistribution of routing information from the specified +route source into the Babel process.** + +The following route sources are available: + +* **ipv4:** ``bgp``, ``connected``, ``eigrp``, ``isis``, ``kernel``, + ``nhrp``, ``ospf``, ``rip``, ``static`` +* **ipv6:** ``bgp``, ``connected``, ``eigrp``, ``isis``, ``kernel``, + ``nhrp``, ``ospfv3``, ``ripng``, ``static`` +``` + +```{cfgcmd} set protocols babel distribute-list \ access-list \ \ + +**Configure global Babel route filtering using an access list.** + +Specify the direction in which the access list is applied: + +* ``in``: Filters incoming routes. +* ``out``: Filters outgoing routes. +``` + +```{cfgcmd} set protocols babel distribute-list \ interface \ access-list \ \ + +**Configure Babel route filtering on the specified interface using an +access list.** + +Specify the direction in which the access list is applied: + +* ``in``: Filters incoming routes. +* ``out``: Filters outgoing routes. +``` + +```{cfgcmd} set protocols babel distribute-list \ prefix-list \ \ + +**Configure global Babel route filtering using a prefix list.** + +Specify the direction in which the prefix list is applied: + +* ``in``: Filters incoming routes. +* ``out``: Filters outgoing routes. +``` + +```{cfgcmd} set protocols babel distribute-list \ interface \ prefix-list \ \ + +**Configure Babel route filtering on the specified interface using a +prefix list.** + +Specify the direction in which the prefix list is applied: + +* ``in``: Filters incoming routes. +* ``out``: Filters outgoing routes. +``` + +## Configuration example + +### Basic two-node babel network + +**Goal:** The following example connects two routers (Node 1 and Node 2) via +their eth0 interfaces and uses the Babel routing protocol to advertise +(redistribute) each router's locally configured networks (represented by +loopback addresses) to one another. + +**Node 1:** + +```none +# Configure the loopback (local networks) and physical (eth0) addresses +set interfaces loopback lo address 10.1.1.1/32 +set interfaces loopback lo address fd12:3456:dead:beef::1/128 +set interfaces ethernet eth0 address 192.168.1.1/24 + +# Enable Babel on the physical link +set protocols babel interface eth0 type wired + +# Instruct Babel to advertise (redistribute) the locally configured networks +set protocols babel redistribute ipv4 connected +set protocols babel redistribute ipv6 connected +``` + +**Node 2:** + +```none +# Configure the loopback (local networks) and physical (eth0) addresses +set interfaces loopback lo address 10.2.2.2/32 +set interfaces loopback lo address fd12:3456:beef:dead::2/128 +set interfaces ethernet eth0 address 192.168.1.2/24 + +# Enable Babel on the physical link +set protocols babel interface eth0 type wired + +# Tell Babel to advertise (redistribute) the locally configured networks +set protocols babel redistribute ipv4 connected +set protocols babel redistribute ipv6 connected +``` diff --git a/docs/configuration/protocols/md-bfd.md b/docs/configuration/protocols/md-bfd.md new file mode 100644 index 00000000..13623e03 --- /dev/null +++ b/docs/configuration/protocols/md-bfd.md @@ -0,0 +1,205 @@ +--- +lastproofread: '2023-01-27' +--- + +```{include} /_include/need_improvement.txt +``` + +(routing-bfd)= + +# BFD + +{abbr}`BFD (Bidirectional Forwarding Detection)` is described and extended by +the following RFCs: {rfc}`5880`, {rfc}`5881` and {rfc}`5883`. + +In the age of very fast networks, a second of unreachability may equal millions of lost packets. +The idea behind BFD is to detect very quickly when a peer is down and take action extremely fast. + +BFD sends lots of small UDP packets very quickly to ensures that the peer is still alive. + +This allows avoiding the timers defined in BGP and OSPF protocol to expires. + +## Configure BFD + +```{cfgcmd} set protocols bfd peer \ + +Set BFD peer IPv4 address or IPv6 address +``` + +```{cfgcmd} set protocols bfd peer \ echo-mode + +Enables the echo transmission mode +``` + +```{cfgcmd} set protocols bfd peer \ multihop + +Allow this BFD peer to not be directly connected +``` + +```{cfgcmd} set protocols bfd peer \ source [address \ | interface \] + +Bind listener to specific interface/address, mandatory for IPv6 +``` + +```{cfgcmd} set protocols bfd peer \ interval echo-interval \<10-60000\> + +The minimal echo receive transmission interval that this system is +capable of handling +``` + +```{cfgcmd} set protocols bfd peer \ interval multiplier \<2-255\> + +Remote transmission interval will be multiplied by this value +``` + +```{cfgcmd} set protocols bfd peer \ interval [receive | transmit] \<10-60000\> + +Interval in milliseconds +``` + +```{cfgcmd} set protocols bfd peer \ shutdown + +Disable a BFD peer +``` + +```{cfgcmd} set protocols bfd peer \ minimum-ttl \<1-254\> + +For multi hop sessions only. Configure the minimum expected TTL for an +incoming BFD control packet. + +This feature serves the purpose of thightening the packet validation +requirements to avoid receiving BFD control packets from other sessions. +``` + +### Enable BFD in BGP + +```{cfgcmd} set protocols bgp neighbor \ bfd + +Enable BFD on a single BGP neighbor +``` + +```{cfgcmd} set protocols bgp peer-group \ bfd + +Enable BFD on a BGP peer group +``` + +### Enable BFD in OSPF + +```{cfgcmd} set protocols ospf interface \ bfd + + Enable BFD for OSPF on an interface + +``` + +```{cfgcmd} set protocols ospfv3 interface \ bfd + +Enable BFD for OSPFv3 on an interface +``` + +### Enable BFD in ISIS + +```{cfgcmd} set protocols isis \ interface \ bfd + +Enable BFD for ISIS on an interface + +``` + +## Operational Commands + +```{opcmd} show bfd peers + + Show all BFD peers + + :::{code-block} none + BFD Peers: + peer 198.51.100.33 vrf default interface eth4.100 + ID: 4182341893 + Remote ID: 12678929647 + Status: up + Uptime: 1 month(s), 16 hour(s), 29 minute(s), 38 second(s) + Diagnostics: ok + Remote diagnostics: ok + Local timers: + Receive interval: 300ms + Transmission interval: 300ms + Echo transmission interval: 50ms + Remote timers: + Receive interval: 300ms + Transmission interval: 300ms + Echo transmission interval: 0ms + + peer 198.51.100.55 vrf default interface eth4.101 + ID: 4618932327 + Remote ID: 3312345688 + Status: up + Uptime: 20 hour(s), 16 minute(s), 19 second(s) + Diagnostics: ok + Remote diagnostics: ok + Local timers: + Receive interval: 300ms + Transmission interval: 300ms + Echo transmission interval: 50ms + Remote timers: + Receive interval: 300ms + Transmission interval: 300ms + Echo transmission interval: 0ms + ::: +``` + +## BFD Static Route Monitoring + + +A monitored static route conditions the installation to the RIB on the BFD +session running state: when BFD session is up the route is installed to RIB, +but when the BFD session is down it is removed from the RIB. + + +### Configuration + +```{cfgcmd} set protocols static route \ next-hop \ bfd profile \ + +Configure a static route for \ using gateway \ +and use the gateway address as BFD peer destination address. +``` + +```{cfgcmd} set protocols static route \ next-hop \ bfd multi-hop source \ profile \ + +Configure a static route for \ using gateway \, +use source address to identify 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 identify the peer when is multi-hop session +and the gateway address as BFD peer destination address. +``` + +(bfd-operational-commands)= + +## Operational Commands + +```{opcmd} show bfd static routes + +Showing BFD monitored static routes + +:::{code-block} none +Showing BFD monitored static routes: + + Next hops: + VRF default IPv4 Unicast: + 10.10.13.3/32 peer 192.168.2.3 (status: installed) + 172.16.10.3/32 peer 192.168.10.1 (status: uninstalled) + + VRF default IPv4 Multicast: + + VRF default IPv6 Unicast: +::: +``` \ No newline at end of file diff --git a/docs/configuration/protocols/md-bgp.md b/docs/configuration/protocols/md-bgp.md new file mode 100644 index 00000000..702a2b1f --- /dev/null +++ b/docs/configuration/protocols/md-bgp.md @@ -0,0 +1,1414 @@ +(routing-bgp)= + +# BGP + +{abbr}`BGP (Border Gateway Protocol)` is one of the Exterior Gateway Protocols +and the de facto standard interdomain routing protocol. The latest BGP version +is 4. BGP-4 is described in {rfc}`1771` and updated by {rfc}`4271`. {rfc}`2858` +adds multiprotocol support to BGP. + +VyOS makes use of {abbr}`FRR (Free Range Routing)` and we would like to thank +them for their effort! + +## Basic Concepts + +(bgp-autonomous-systems)= + +### Autonomous Systems + +From {rfc}`1930`: + +> An AS is a connected group of one or more IP prefixes run by one or more +> network operators which has a SINGLE and CLEARLY DEFINED routing policy. + +Each {abbr}`AS (Autonomous System)` has an identifying number associated with it +called an {abbr}`ASN (Autonomous System Number)`. This is a two octet value +ranging in value from 1 to 65535. The AS numbers 64512 through 65535 are defined +as private AS numbers. Private AS numbers must not be advertised on the global +Internet. The 2-byte AS number range has been exhausted. 4-byte AS numbers are +specified in {rfc}`6793`, and provide a pool of 4294967296 AS numbers. + +The {abbr}`ASN (Autonomous System Number)` is one of the essential elements of +BGP. BGP is a distance vector routing protocol, and the AS-Path framework +provides distance vector metric and loop detection to BGP. + +```{cfgcmd} set protocols bgp system-as \ + +Set local {abbr}`ASN (Autonomous System Number)` that this router represents. +This is a a mandatory option! +``` + +(bgp-address-families)= + + +### Address Families + + +Multiprotocol extensions enable BGP to carry routing information for multiple +network layer protocols. BGP supports an Address Family Identifier (AFI) for +IPv4 and IPv6. + + +(bgp-route-selection)= + + +### Route Selection + + +The route selection process used by FRR's BGP implementation uses the following +decision criterion, starting at the top of the list and going towards the +bottom until one of the factors can be used. + + +01. **Weight check** + + + Prefer higher local weight routes to lower routes. + + +02. **Local preference check** + + + Prefer higher local preference routes to lower. + + +03. **Local route check** + + + Prefer local routes (statics, aggregates, redistributed) to received routes. + + +04. **AS path length check** + + + Prefer shortest hop-count AS_PATHs. + + +05. **Origin check** + + + Prefer the lowest origin type route. That is, prefer IGP origin routes to + EGP, to Incomplete routes. + + +06. **MED check** + + + Where routes with a MED were received from the same AS, prefer the route + with the lowest MED. + + +07. **External check** + + + Prefer the route received from an external, eBGP peer over routes received + from other types of peers. + + +08. **IGP cost check** + + + Prefer the route with the lower IGP cost. + + +09. **Multi-path check** + + + If multi-pathing is enabled, then check whether the routes not yet + distinguished in preference may be considered equal. If + {cfgcmd}`bgp bestpath as-path multipath-relax` is set, all such routes are + considered equal, otherwise routes received via iBGP with identical AS_PATHs + or routes received from eBGP neighbours in the same AS are considered equal. + + +10. **Already-selected external check** + + + Where both routes were received from eBGP peers, then prefer the route + which is already selected. Note that this check is not applied if + {cfgcmd}`bgp bestpath compare-routerid` is configured. This check can + prevent some cases of oscillation. + + +11. **Router-ID check** + + + Prefer the route with the lowest router-ID. If the route has an + ORIGINATOR_ID attribute, through iBGP reflection, then that router ID is + used, otherwise the router-ID of the peer the route was received from is + used. + + +12. **Cluster-List length check** + + + The route with the shortest cluster-list length is used. The cluster-list + reflects the iBGP reflection path the route has taken. + + +13. **Peer address** + + + Prefer the route received from the peer with the higher transport layer + address, as a last-resort tie-breaker. + + +(bgp-capability-negotiation)= + + +### Capability Negotiation + + +When adding IPv6 routing information exchange feature to BGP. There were some +proposals. {abbr}`IETF (Internet Engineering Task Force)` +{abbr}`IDR (Inter Domain Routing)` adopted a proposal called Multiprotocol +Extension for BGP. The specification is described in {rfc}`2283`. The protocol +does not define new protocols. It defines new attributes to existing BGP. When +it is used exchanging IPv6 routing information it is called BGP-4+. When it is +used for exchanging multicast routing information it is called MBGP. + + +*bgpd* supports Multiprotocol Extension for BGP. So if a remote peer supports +the protocol, *bgpd* can exchange IPv6 and/or multicast routing information. + + +Traditional BGP did not have the feature to detect a remote peer's +capabilities, e.g. whether it can handle prefix types other than IPv4 unicast +routes. This was a big problem using Multiprotocol Extension for BGP in an +operational network. {rfc}`2842` adopted a feature called Capability +Negotiation. *bgpd* use this Capability Negotiation to detect the remote peer's +capabilities. If a peer is only configured as an IPv4 unicast neighbor, *bgpd* +does not send these Capability Negotiation packets (at least not unless other +optional BGP features require capability negotiation). + + +By default, FRR will bring up peering with minimal common capability for the +both sides. For example, if the local router has unicast and multicast +capabilities and the remote router only has unicast capability the local router +will establish the connection with unicast only capability. When there are no +common capabilities, FRR sends Unsupported Capability error and then resets the +connection. + + +## Configuration + + +(bgp-router-configuration)= + + +### BGP Router Configuration + + +First of all you must configure BGP router with the {abbr}`ASN (Autonomous +System Number)`. The AS number is an identifier for the autonomous system. +The BGP protocol uses the AS number for detecting whether the BGP connection +is internal or external. VyOS does not have a special command to start the BGP +process. The BGP process starts when the first neighbor is configured. + +```{cfgcmd} set protocols bgp system-as \ + +Set local autonomous system number that this router represents. This is a +mandatory option! +``` + +#### Peers Configuration + + +##### Defining Peers + +```{cfgcmd} set protocols bgp neighbor \ remote-as \ + +This command creates a new neighbor whose remote-as is \. The neighbor +address can be an IPv4 address or an IPv6 address or an interface to use +for the connection. The command is applicable for peer and peer group. +``` + + +```{cfgcmd} set protocols bgp neighbor \ remote-as internal + +Create a peer as you would when you specify an ASN, except that if the +peers ASN is different than mine as specified under the {cfgcmd}`protocols +bgp ` command the connection will be denied. +``` + + +```{cfgcmd} set protocols bgp neighbor \ remote-as external + +Create a peer as you would when you specify an ASN, except that if the +peers ASN is the same as mine as specified under the {cfgcmd}`protocols +bgp ` command the connection will be denied. +``` + + +```{cfgcmd} set protocols bgp neighbor \ remote-as auto + +Create a peer as you would when you specify an ASN, except that the peers +remote ASN is detected automatically from the OPEN message. +``` + + +```{cfgcmd} set protocols bgp neighbor \ local-role \ [strict] + +BGP roles are defined in RFC {rfc}`9234` and provide an easy way to +add route leak prevention, detection and mitigation. The local Role +value is negotiated with the new BGP Role capability which has a +built-in check of the corresponding value. In case of a mismatch the +new OPEN Roles Mismatch Notification <2, 11> would be sent. +The correct Role pairs are: + +Provider - Customer + +Peer - Peer + +RS-Server - RS-Client + +If {cfgcmd}`strict` is set the BGP session won’t become established +until the BGP neighbor sets local Role on its side. This +configuration parameter is defined in RFC {rfc}`9234` and is used to +enforce the corresponding configuration at your counter-parts side. + +Routes that are sent from provider, rs-server, or the peer local-role +(or if received by customer, rs-client, or the peer local-role) will +be marked with a new Only to Customer (OTC) attribute. + +Routes with this attribute can only be sent to your neighbor if your +local-role is provider or rs-server. Routes with this attribute can +be received only if your local-role is customer or rs-client. + +In case of peer-peer relationship routes can be received only if OTC +value is equal to your neighbor AS number. + +All these rules with OTC will help to detect and mitigate route leaks +and happen automatically if local-role is set. +``` + + +```{cfgcmd} set protocols bgp neighbor \ shutdown + +This command disable the peer or peer group. To reenable the peer use +the delete form of this command. +``` + + +```{cfgcmd} set protocols bgp neighbor \ description \ + +Set description of the peer or peer group. +``` + + +```{cfgcmd} set protocols bgp neighbor \ update-source \ + +Specify the IPv4 source address to use for the BGP session to this neighbor, +may be specified as either an IPv4 address directly or as an interface name. +``` + +(bgp-capability-negotiation-1)= + + +##### Capability Negotiation + +```{cfgcmd} set protocols bgp neighbor \ capability dynamic + +This command would allow the dynamic update of capabilities over an +established BGP session. +``` + + +```{cfgcmd} set protocols bgp neighbor \ capability extended-nexthop + +Allow bgp to negotiate the extended-nexthop capability with it’s peer. +If you are peering over a IPv6 Link-Local address then this capability +is turned on automatically. If you are peering over a IPv6 Global Address +then turning on this command will allow BGP to install IPv4 routes with +IPv6 nexthops if you do not have IPv4 configured on interfaces. +``` + + +```{cfgcmd} set protocols bgp neighbor \ disable-capability-negotiation + +Suppress sending Capability Negotiation as OPEN message optional +parameter to the peer. This command only affects the peer is +configured other than IPv4 unicast configuration. + +When remote peer does not have capability negotiation feature, +remote peer will not send any capabilities at all. In that case, +bgp configures the peer with configured capabilities. + +You may prefer locally configured capabilities more than the negotiated +capabilities even though remote peer sends capabilities. If the peer is +configured by {cfgcmd}`override-capability`, VyOS ignores received +capabilities then override negotiated capabilities with configured values. + +Additionally you should keep in mind that this feature fundamentally +disables the ability to use widely deployed BGP features. BGP unnumbered, +hostname support, AS4, Addpath, Route Refresh, ORF, Dynamic Capabilities, +and graceful restart. +``` + + +```{cfgcmd} set protocols bgp neighbor \ override-capability + +This command allow override the result of Capability Negotiation with +local configuration. Ignore remote peer’s capability value. +``` + + +```{cfgcmd} set protocols bgp neighbor \ strict-capability-match + +This command forces strictly compare remote capabilities and local +capabilities. If capabilities are different, send Unsupported Capability +error then reset connection. + +You may want to disable sending Capability Negotiation OPEN message +optional parameter to the peer when remote peer does not implement +Capability Negotiation. Please use {cfgcmd}`disable-capability-negotiation` +command to disable the feature. +``` + +##### Peer Parameters + +```{cfgcmd} set protocols bgp neighbor \ address-family \ allowas-in number \ + +This command accept incoming routes with AS path containing AS +number with the same value as the current system AS. This is +used when you want to use the same AS number in your sites, +but you can’t connect them directly. + + The number parameter (1-10) configures the amount of accepted + occurrences of the system AS number in AS path. + + This command is only allowed for eBGP peers. It is not applicable + for peer groups. +``` + + +```{cfgcmd} set protocols bgp neighbor \ address-family \ as-override + +This command override AS number of the originating router with +the local AS number. + +Usually this configuration is used in PEs (Provider Edge) to +replace the incoming customer AS number so the connected CE ( +Customer Edge) can use the same AS number as the other customer +sites. This allows customers of the provider network to use the +same AS number across their sites. + +This command is only allowed for eBGP peers. +``` + + +```{cfgcmd} set protocols bgp neighbor \ address-family \ attribute-unchanged \ + +This command specifies attributes to be left unchanged for +advertisements sent to a peer or peer group. +``` + + +```{cfgcmd} set protocols bgp neighbor \ address-family \ maximum-prefix \ + +This command specifies a maximum number of prefixes we can receive +from a given peer. If this number is exceeded, the BGP session +will be destroyed. The number range is 1 to 4294967295. +``` + + +```{cfgcmd} set protocols bgp neighbor \ address-family \ nexthop-self + +This command forces the BGP speaker to report itself as the +next hop for an advertised route it advertised to a neighbor. +``` + + +```{cfgcmd} set protocols bgp neighbor \ address-family \ remove-private-as + +This command removes the private ASN of routes that are advertised +to the configured peer. It removes only private ASNs on routes +advertised to EBGP peers. + +If the AS-Path for the route has only private ASNs, the private +ASNs are removed. + +If the AS-Path for the route has a private ASN between public +ASNs, it is assumed that this is a design choice, and the +private ASN is not removed. +``` + + +```{cfgcmd} set protocols bgp neighbor \ address-family \ soft-reconfiguration inbound + +Changes in BGP policies require the BGP session to be cleared. Clearing has a +large negative impact on network operations. Soft reconfiguration enables you +to generate inbound updates from a neighbor, change and activate BGP policies +without clearing the BGP session. + +This command specifies that route updates received from this neighbor will be +stored unmodified, regardless of the inbound policy. When inbound soft +reconfiguration is enabled, the stored updates are processed by the new +policy configuration to create new inbound updates. + +:::{note} +Storage of route updates uses memory. If you enable soft +reconfiguration inbound for multiple neighbors, the amount of memory used +can become significant. +::: +``` + + +```{cfgcmd} set protocols bgp neighbor \ address-family \ weight \ + +This command specifies a default weight value for the neighbor’s +routes. The number range is 1 to 65535. +``` + + +```{cfgcmd} set protocols bgp neighbor \ advertisement-interval \ + +This command specifies the minimum route advertisement interval for +the peer. The interval value is 0 to 600 seconds, with the default +advertisement interval being 0. +``` + + +```{cfgcmd} set protocols bgp neighbor \ disable-connected-check + +This command allows peerings between directly connected eBGP peers +using loopback addresses without adjusting the default TTL of 1. +``` + + +```{cfgcmd} set protocols bgp neighbor \ disable-send-community \ + +This command specifies that the community attribute should not be sent +in route updates to a peer. By default community attribute is sent. +``` + + +```{cfgcmd} set protocols bgp neighbor \ ebgp-multihop \ + +This command allows sessions to be established with eBGP neighbors +when they are multiple hops away. When the neighbor is not directly +connected and this knob is not enabled, the session will not establish. +The number of hops range is 1 to 255. This command is mutually +exclusive with {cfgcmd}`ttl-security hops`. +``` + + +```{cfgcmd} set protocols bgp neighbor \ local-as \ [no-prepend] [replace-as] + +Specify an alternate AS for this BGP process when interacting with +the specified peer or peer group. With no modifiers, the specified +local-as is prepended to the received AS_PATH when receiving routing +updates from the peer, and prepended to the outgoing AS_PATH (after +the process local AS) when transmitting local routes to the peer. + +If the {cfgcmd}`no-prepend` attribute is specified, then the supplied +local-as is not prepended to the received AS_PATH. + +If the {cfgcmd}`replace-as` attribute is specified, then only the supplied +local-as is prepended to the AS_PATH when transmitting local-route +updates to this peer. + +:::{note} +This command is only allowed for eBGP peers. +::: +``` + + +```{cfgcmd} set protocols bgp neighbor \ passive + +Configures the BGP speaker so that it only accepts inbound connections +from, but does not initiate outbound connections to the peer or peer group. +``` + + +```{cfgcmd} set protocols bgp neighbor \ password \ + +This command specifies a MD5 password to be used with the tcp socket that +is being used to connect to the remote peer. +``` + + +```{cfgcmd} set protocols bgp neighbor \ ttl-security hops \ + +This command enforces Generalized TTL Security Mechanism (GTSM), +as specified in {rfc}`5082`. With this command, only neighbors +that are specified number of hops away will be allowed to +become neighbors. The number of hops range is 1 to 254. This +command is mutually exclusive with {cfgcmd}`ebgp-multihop`. +``` + +##### Peer Groups + +Peer groups are used to help improve scaling by generating the same update +information to all members of a peer group. Note that this means that the +routes generated by a member of a peer group will be sent back to that +originating peer with the originator identifier attribute set to indicated +the originating peer. All peers not associated with a specific peer group +are treated as belonging to a default peer group, and will share updates. + +```{cfgcmd} set protocols bgp peer-group \ + + This command defines a new peer group. You can specify to the group the same + parameters that you can specify for specific neighbors. + + :::{note} + If you apply a parameter to an individual neighbor IP address, you + override the action defined for a peer group that includes that IP + address. + ::: +``` + + +```{cfgcmd} set protocols bgp neighbor \ peer-group \ + +This command bind specific peer to peer group with a given name. +``` + +#### Network Advertisement Configuration + +```{cfgcmd} set protocols bgp address-family \ network \ + +This command is used for advertising IPv4 or IPv6 networks. + + :::{note} + By default, the BGP prefix is advertised even if it's not present + in the routing table. This behaviour differs from the implementation of + some vendors. + ::: +``` + + +```{cfgcmd} set protocols bgp parameters network-import-check + +This configuration modifies the behavior of the network statement. If you +have this configured the underlying network must exist in the routing table. +``` + + +```{cfgcmd} set protocols bgp neighbor \ address-family \ default-originate [route-map \] + +By default, VyOS does not advertise a default route (0.0.0.0/0) even if it is +in routing table. When you want to announce default routes to the peer, use +this command. Using optional argument {cfgcmd}`route-map` you can inject the +default route to given neighbor only if the conditions in the route map are +met. +``` + +#### Route Aggregation Configuration + +```{cfgcmd} set protocols bgp address-family \ aggregate-address \ + +This command specifies an aggregate address. The router will also +announce longer-prefixes inside of the aggregate address. +``` + + +```{cfgcmd} set protocols bgp address-family \ aggregate-address \ as-set + +This command specifies an aggregate address with a mathematical set of +autonomous systems. This command summarizes the AS_PATH attributes of +all the individual routes. +``` + + +```{cfgcmd} set protocols bgp address-family \ aggregate-address \ summary-only + +This command specifies an aggregate address and provides that +longer-prefixes inside of the aggregate address are suppressed +before sending BGP updates out to peers. +``` + + +```{cfgcmd} set protocols bgp neighbor \ address-family \ unsuppress-map \ + +This command applies route-map to selectively unsuppress prefixes +suppressed by summarisation. +``` + +#### Redistribution Configuration + +```{cfgcmd} set protocols bgp address-family \ redistribute + +This command redistributes routing information from the given route source +to the BGP process. There are six modes available for route source: +connected, kernel, ospf, rip, static, table. +``` + + +```{cfgcmd} set protocols bgp address-family \ redistribute metric \ + +This command specifies metric (MED) for redistributed routes. The +metric range is 0 to 4294967295. There are six modes available for +route source: connected, kernel, ospf, rip, static, table. +``` + + +```{cfgcmd} set protocols bgp address-family \ redistribute route-map \ + +This command allows to use route map to filter redistributed routes. +There are six modes available for route source: connected, kernel, +ospf, rip, static, table. +``` + +#### General Configuration +##### Common parameters + +```{cfgcmd} set protocols bgp parameters allow-martian-nexthop + + When a peer receives a martian nexthop as part of the NLRI for a route + permit the nexthop to be used as such, instead of rejecting and resetting + the connection. +``` + + +```{cfgcmd} set protocols bgp parameters router-id \ + +This command specifies the router-ID. If router ID is not specified it will +use the highest interface IP address. +``` + + +```{cfgcmd} set protocols bgp address-family \ maximum-paths \ \ + +This command defines the maximum number of parallel routes that +the BGP can support. In order for BGP to use the second path, the +following attributes have to match: Weight, Local Preference, AS +Path (both AS number and AS path length), Origin code, MED, IGP +metric. Also, the next hop address for each path must be different. +``` + + +```{cfgcmd} set protocols bgp parameters no-hard-administrative-reset + +Do not send Hard Reset CEASE Notification for "Administrative Reset" +events. When set and Graceful Restart Notification capability is exchanged +between the peers, Graceful Restart procedures apply, and routes will be retained. +``` + + +```{cfgcmd} set protocols bgp parameters log-neighbor-changes + +This command enable logging neighbor up/down changes and reset reason. +``` + + +```{cfgcmd} set protocols bgp parameters no-client-to-client-reflection + +This command disables route reflection between route reflector clients. +By default, the clients of a route reflector are not required to be +fully meshed and the routes from a client are reflected to other clients. +However, if the clients are fully meshed, route reflection is not required. +In this case, use the {cfgcmd}`no-client-to-client-reflection` command +to disable client-to-client reflection. +``` + + +```{cfgcmd} set protocols bgp parameters no-fast-external-failover + +Disable immediate session reset if peer's connected link goes down. +``` + + +```{cfgcmd} set protocols bgp parameters no-ipv6-auto-ra + +By default, FRR sends router advertisement packets when Extended Next Hop is +on or when a connection is established directly using the device name (Unnumbered BGP). +Setting this option prevents FRR from sending router advertisement packets, but could break Unnumbered BGP. +``` + + +```{cfgcmd} set protocols bgp listen range \ peer-group \ + +This command is useful if one desires to loosen the requirement for BGP +to have strictly defined neighbors. Specifically what is allowed is for +the local router to listen to a range of IPv4 or IPv6 addresses defined +by a prefix and to accept BGP open messages. When a TCP connection +(and subsequently a BGP open message) from within this range tries to +connect the local router then the local router will respond and connect +with the parameters that are defined within the peer group. One must define +a peer-group for each range that is listed. If no peer-group is defined +then an error will keep you from committing the configuration. +``` + + +```{cfgcmd} set protocols bgp listen limit \ + +This command goes hand in hand with the listen range command to limit the +amount of BGP neighbors that are allowed to connect to the local router. +The limit range is 1 to 5000. +``` + + +```{cfgcmd} set protocols bgp parameters ebgp-requires-policy + +This command changes the eBGP behavior of FRR. By default FRR enables +{rfc}`8212` functionality which affects how eBGP routes are advertised, +namely no routes are advertised across eBGP sessions without some +sort of egress route-map/policy in place. In VyOS however we have this +RFC functionality disabled by default so that we can preserve backwards +compatibility with older versions of VyOS. With this option one can +enable {rfc}`8212` functionality to operate. +``` + + +```{cfgcmd} set protocols bgp parameters labeled-unicast \ + +By default, locally advertised prefixes use the implicit-null label to +encode in the outgoing NLRI. + +The following command uses the explicit-null label value for all the +BGP instances. +``` + +##### Administrative Distance + +```{cfgcmd} set protocols bgp parameters distance global \ \ + +This command change distance value of BGP. The arguments are the distance +values for external routes, internal routes and local routes respectively. +The distance range is 1 to 255. +``` + + +```{cfgcmd} set protocols bgp parameters distance prefix \ distance \ + +This command sets the administrative distance for a particular route. The +distance range is 1 to 255. + +:::{note} +Routes with a distance of 255 are effectively disabled and not +installed into the kernel. +::: +``` + +##### Timers + +```{cfgcmd} set protocols bgp timers holdtime \ + + This command specifies hold-time in seconds. The timer range is + 4 to 65535. The default value is 180 second. If you set value to 0 + VyOS will not hold routes. +``` + + +```{cfgcmd} set protocols bgp timers keepalive \ + +This command specifies keep-alive time in seconds. The timer +can range from 4 to 65535. The default value is 60 second. +``` + +##### Route Dampening + +When a route fails, a routing update is sent to withdraw the route from the +network's routing tables. When the route is re-enabled, the change in +availability is also advertised. A route that continually fails and returns +requires a great deal of network traffic to update the network about the +route's status. + +Route dampening wich described in {rfc}`2439` enables you to identify routes +that repeatedly fail and return. If route dampening is enabled, an unstable +route accumulates penalties each time the route fails and returns. If the +accumulated penalties exceed a threshold, the route is no longer advertised. +This is route suppression. Routes that have been suppressed are re-entered +into the routing table only when the amount of their penalty falls below a +threshold. + +A penalty of 1000 is assessed each time the route fails. When the penalties +reach a predefined threshold (suppress-value), the router stops advertising +the route. + +Once a route is assessed a penalty, the penalty is decreased by half each time +a predefined amount of time elapses (half-life-time). When the accumulated +penalties fall below a predefined threshold (reuse-value), the route is +unsuppressed and added back into the BGP routing table. + +No route is suppressed indefinitely. Maximum-suppress-time defines the maximum +time a route can be suppressed before it is re-advertised. + +```{cfgcmd} set protocols bgp parameters dampening half-life \ + +This command defines the amount of time in minutes after +which a penalty is reduced by half. The timer range is +10 to 45 minutes. +``` + + +```{cfgcmd} set protocols bgp parameters dampening re-use \ + +This command defines the accumulated penalty amount at which the +route is re-advertised. The penalty range is 1 to 20000. +``` + + +```{cfgcmd} set protocols bgp parameters dampening start-suppress-time \ + +This command defines the accumulated penalty amount at which the +route is suppressed. The penalty range is 1 to 20000. +``` + + +```{cfgcmd} set protocols bgp parameters dampening max-suppress-time \ + +This command defines the maximum time in minutes that a route is +suppressed. The timer range is 1 to 255 minutes. +``` + +#### Route Selection Configuration + +```{cfgcmd} set protocols bgp parameters always-compare-med + + This command provides to compare the MED on routes, even when they were + received from different neighbouring ASes. Setting this option makes the + order of preference of routes more defined, and should eliminate MED + induced oscillations. +``` + + +```{cfgcmd} set protocols bgp parameters bestpath as-path confed + +This command specifies that the length of confederation path sets and +sequences should be taken into account during the BGP best path +decision process. +``` + + +```{cfgcmd} set protocols bgp parameters bestpath as-path multipath-relax + +This command specifies that BGP decision process should consider paths +of equal AS_PATH length candidates for multipath computation. Without +the knob, the entire AS_PATH must match for multipath computation. +``` + + +```{cfgcmd} set protocols bgp parameters bestpath as-path ignore + +Ignore AS_PATH length when selecting a route +``` + + +```{cfgcmd} set protocols bgp parameters bestpath compare-routerid + +Ensure that when comparing routes where both are equal on most metrics, +including local-pref, AS_PATH length, IGP cost, MED, that the tie is +broken based on router-ID. + +If this option is enabled, then the already-selected check, where +already selected eBGP routes are preferred, is skipped. + +If a route has an ORIGINATOR_ID attribute because it has been reflected, +that ORIGINATOR_ID will be used. Otherwise, the router-ID of the peer +the route was received from will be used. + +The advantage of this is that the route-selection (at this point) will +be more deterministic. The disadvantage is that a few or even one lowest-ID +router may attract all traffic to otherwise-equal paths because of this +check. It may increase the possibility of MED or IGP oscillation, unless +other measures were taken to avoid these. The exact behaviour will be +sensitive to the iBGP and reflection topology. +``` + + +```{cfgcmd} set protocols bgp parameters bestpath med confed + +This command specifies that BGP considers the MED when comparing routes +originated from different sub-ASs within the confederation to which this +BGP speaker belongs. The default state, where the MED attribute is not +considered. +``` + + +```{cfgcmd} set protocols bgp parameters bestpath med missing-as-worst + +This command specifies that a route with a MED is always considered to be +better than a route without a MED by causing the missing MED attribute to +have a value of infinity. The default state, where the missing MED +attribute is considered to have a value of zero. +``` + + +```{cfgcmd} set protocols bgp parameters default local-pref + +This command specifies the default local preference value. The local +preference range is 0 to 4294967295. +``` + + +```{cfgcmd} set protocols bgp parameters deterministic-med + +This command provides to compare different MED values that advertised by +neighbours in the same AS for routes selection. When this command is +enabled, routes from the same autonomous system are grouped together, and +the best entries of each group are compared. +``` + + +```{cfgcmd} set protocols bgp address-family ipv4-unicast network \ backdoor + +This command allows the router to prefer route to specified prefix learned +via IGP through backdoor link instead of a route to the same prefix learned +via EBGP. +``` + +#### Route Filtering Configuration + +In order to control and modify routing information that is exchanged between +peers you can use route-map, filter-list, prefix-list, distribute-list. + +For inbound updates the order of preference is: + +> - route-map +> - filter-list +> - prefix-list, distribute-list + +For outbound updates the order of preference is: +> - prefix-list, distribute-list +> - filter-list +> - route-map +> +> :::{note} +> The attributes {cfgcmd}`prefix-list` and {cfgcmd}`distribute-list` +> are mutually exclusive, and only one command (distribute-list or +> prefix-list) can be applied to each inbound or outbound direction for a +> particular neighbor. +> ::: + +```{cfgcmd} set protocols bgp neighbor \ address-family \ distribute-list \ \ + +This command applies the access list filters named in \ to the +specified BGP neighbor to restrict the routing information that BGP learns +and/or advertises. The arguments {cfgcmd}`export` and {cfgcmd}`import` +specify the direction in which the access list are applied. +``` + + +```{cfgcmd} set protocols bgp neighbor \ address-family \ prefix-list \ \ + +This command applies the prfefix list filters named in \ to the +specified BGP neighbor to restrict the routing information that BGP learns +and/or advertises. The arguments {cfgcmd}`export` and {cfgcmd}`import` +specify the direction in which the prefix list are applied. +``` + + +```{cfgcmd} set protocols bgp neighbor \ address-family \ route-map \ \ + +This command applies the route map named in \ to the specified BGP +neighbor to control and modify routing information that is exchanged +between peers. The arguments {cfgcmd}`export` and {cfgcmd}`import` +specify the direction in which the route map are applied. +``` + + +```{cfgcmd} set protocols bgp neighbor \ address-family \ filter-list \ \ + +This command applies the AS path access list filters named in \ to the +specified BGP neighbor to restrict the routing information that BGP learns +and/or advertises. The arguments {cfgcmd}`export` and {cfgcmd}`import` +specify the direction in which the AS path access list are applied. +``` + + +```{cfgcmd} set protocols bgp neighbor \ address-family \ capability orf \ + +This command enables the ORF capability (described in {rfc}`5291`) on the +local router, and enables ORF capability advertisement to the specified BGP +peer. The {cfgcmd}`receive` keyword configures a router to advertise ORF +receive capabilities. The {cfgcmd}`send` keyword configures a router to +advertise ORF send capabilities. To advertise a filter from a sender, you +must create an IP prefix list for the specified BGP peer applied in inbound +derection. +``` + + +```{cfgcmd} set protocols bgp neighbor \ solo + +This command prevents from sending back prefixes learned from the neighbor. +``` + +#### BGP Scaling Configuration + + +BGP routers connected inside the same AS through BGP belong to an internal BGP +session, or IBGP. In order to prevent routing table loops, IBGP speaker does +not advertise IBGP-learned routes to other IBGP speaker (Split Horizon +mechanism). As such, IBGP requires a full mesh of all peers. For large +networks, this quickly becomes unscalable. + + +There are two ways that help us to mitigate the BGPs full-mesh requirement in +a network: + + +> - Using BGP route-reflectors +> - Using BGP confederation + + +##### Route Reflector Configuration + + +Introducing route reflectors removes the need for the full-mesh. When you +configure a route reflector you have to tell the router whether the other IBGP +router is a client or non-client. A client is an IBGP router that the route +reflector will “reflect” routes to, the non-client is just a regular IBGP +neighbor. Route reflectors mechanism is described in {rfc}`4456` and updated +by {rfc}`7606`. + +```{cfgcmd} set protocols bgp neighbor \ address-family \ route-reflector-client + +This command specifies the given neighbor as route reflector client. +``` + + +```{cfgcmd} set protocols bgp parameters cluster-id \ + +This command specifies cluster ID which identifies a collection of route +reflectors and their clients, and is used by route reflectors to avoid +looping. By default cluster ID is set to the BGP router id value, but can be +set to an arbitrary 32-bit value. +``` + +##### Confederation Configuration + +A BGP confederation divides our AS into sub-ASes to reduce the number of +required IBGP peerings. Within a sub-AS we still require full-mesh IBGP but +between these sub-ASes we use something that looks like EBGP but behaves like +IBGP (called confederation BGP). Confederation mechanism is described in +{rfc}`5065` + +```{cfgcmd} set protocols bgp parameters confederation identifier \ + +This command specifies a BGP confederation identifier. \ is the number +of the autonomous system that internally includes multiple sub-autonomous +systems (a confederation). +``` + + +```{cfgcmd} set protocols bgp parameters confederation peers \ + +This command sets other confederations \ as members of autonomous +system specified by {cfgcmd}`confederation identifier `. +``` + +## Operational Mode Commands +### Show + +```{opcmd} show bgp \ + + This command displays all entries in BGP routing table. +``` + + +```none +BGP table version is 10, local router ID is 10.0.35.3, vrf id 0 +Default local pref 100, local AS 65000 +Status codes: s suppressed, d damped, h history, * valid, > best, = multipath, + i internal, r RIB-failure, S Stale, R Removed +Nexthop codes: @NNN nexthop's vrf id, < announce-nh-self +Origin codes: i - IGP, e - EGP, ? - incomplete +RPKI validation codes: V valid, I invalid, N Not found + + Network Next Hop Metric LocPrf Weight Path +*> 198.51.100.0/24 10.0.34.4 0 0 65004 i +*> 203.0.113.0/24 10.0.35.5 0 0 65005 i + +Displayed 2 routes and 2 total paths +``` + + +```{opcmd} show bgp \ \ + +This command displays information about the particular entry in the BGP +routing table. +``` + + +```none +BGP routing table entry for 198.51.100.0/24 +Paths: (1 available, best #1, table default) + Advertised to non peer-group peers: + 10.0.13.1 10.0.23.2 10.0.34.4 10.0.35.5 + 65004 + 10.0.34.4 from 10.0.34.4 (10.0.34.4) + Origin IGP, metric 0, valid, external, best (First path received) + Last update: Wed Jan 6 12:18:53 2021 +``` + + +```{opcmd} show bgp cidr-only + +This command displays routes with classless interdomain routing (CIDR). +``` + + +```{opcmd} show bgp \ community \ + +This command displays routes that belong to specified BGP communities. +Valid value is a community number in the range from 1 to 4294967200, +or AA:NN (autonomous system-community number/2-byte number), no-export, +local-as, or no-advertise. +``` + + +```{opcmd} show bgp \ community-list \ + +This command displays routes that are permitted by the BGP +community list. +``` + + +```{opcmd} show bgp \ dampening dampened-paths + +This command displays BGP dampened routes. +``` + + +```{opcmd} show bgp \ dampening flap-statistics + +This command displays information about flapping BGP routes. +``` + + +```{opcmd} show bgp \ filter-list \ + +This command displays BGP routes allowed by the specified AS Path +access list. +``` + + +```{opcmd} show bgp \ neighbors \ advertised-routes + +This command displays BGP routes advertised to a neighbor. +``` + + +```{opcmd} show bgp \ neighbors \ received-routes + +This command displays BGP routes originating from the specified BGP +neighbor before inbound policy is applied. To use this command inbound +soft reconfiguration must be enabled. +``` + + +```{opcmd} show bgp \ neighbors \ routes + +This command displays BGP received-routes that are accepted after filtering. +``` + + +```{opcmd} show bgp \ neighbors \ dampened-routes + +This command displays dampened routes received from BGP neighbor. +``` + + +```{opcmd} show bgp \ regexp \ + +This command displays information about BGP routes whose AS path +matches the specified regular expression. +``` + + +```{opcmd} show bgp \ summary + +This command displays the status of all BGP connections. +``` + + +```none +IPv4 Unicast Summary: +BGP router identifier 10.0.35.3, local AS number 65000 vrf-id 0 +BGP table version 11 +RIB entries 5, using 920 bytes of memory +Peers 4, using 82 KiB of memory + +Neighbor V AS MsgRcvd MsgSent TblVer InQ OutQ Up/Down State/PfxRcd +10.0.13.1 4 65000 148 159 0 0 0 02:16:01 0 +10.0.23.2 4 65000 136 143 0 0 0 02:13:21 0 +10.0.34.4 4 65004 161 163 0 0 0 02:16:01 1 +10.0.35.5 4 65005 162 166 0 0 0 02:16:01 1 + +Total number of neighbors 4 +``` + +### Reset + +```{opcmd} reset bgp \ \ [soft [in|out]] + +This command resets BGP connections to the specified neighbor IP address. +With argument {cfgcmd}`soft` this command initiates a soft reset. If +you do not specify the {cfgcmd}`in` or {cfgcmd}`out` options, both +inbound and outbound soft reconfiguration are triggered. +``` + + +```{opcmd} reset bgp all + +This command resets all BGP connections of given router. +``` + + +```{opcmd} reset bgp \ external + +This command resets all external BGP peers of given router. +``` + + +```{opcmd} reset bgp \ peer-group \ [soft [in|out]] + +This command resets BGP connections to the specified peer group. +With argument {cfgcmd}`soft` this command initiates a soft reset. If +you do not specify the {cfgcmd}`in` or {cfgcmd}`out` options, both +inbound and outbound soft reconfiguration are triggered. +``` + +## Examples +### IPv4 peering + +A simple eBGP configuration: + +**Node 1:** + +```none +set protocols bgp system-as 65534 +set protocols bgp neighbor 192.168.0.2 ebgp-multihop '2' +set protocols bgp neighbor 192.168.0.2 remote-as '65535' +set protocols bgp neighbor 192.168.0.2 update-source '192.168.0.1' +set protocols bgp neighbor 192.168.0.2 address-family ipv4-unicast +set protocols bgp address-family ipv4-unicast network '172.16.0.0/16' +set protocols bgp parameters router-id '192.168.0.1' +``` + +**Node 2:** + +```none +set protocols bgp system-as 65535 +set protocols bgp neighbor 192.168.0.1 ebgp-multihop '2' +set protocols bgp neighbor 192.168.0.1 remote-as '65534' +set protocols bgp neighbor 192.168.0.1 update-source '192.168.0.2' +set protocols bgp neighbor 192.168.0.1 address-family ipv4-unicast +set protocols bgp address-family ipv4-unicast network '172.17.0.0/16' +set protocols bgp parameters router-id '192.168.0.2' +``` + +Don't forget, the CIDR declared in the network statement MUST **exist in your +routing table (dynamic or static), the best way to make sure that is true is +creating a static route:** + +**Node 1:** + +```none +set protocols static route 172.16.0.0/16 blackhole distance '254' +``` + +**Node 2:** + +```none +set protocols static route 172.17.0.0/16 blackhole distance '254' +``` + +### IPv6 peering + +A simple BGP configuration via IPv6. + +**Node 1:** + +```none +set protocols bgp system-as 65534 +set protocols bgp neighbor 2001:db8::2 ebgp-multihop '2' +set protocols bgp neighbor 2001:db8::2 remote-as '65535' +set protocols bgp neighbor 2001:db8::2 update-source '2001:db8::1' +set protocols bgp neighbor 2001:db8::2 address-family ipv6-unicast +set protocols bgp address-family ipv6-unicast network '2001:db8:1::/48' +set protocols bgp parameters router-id '10.1.1.1' +``` + +**Node 2:** + +```none +set protocols bgp system-as 65535 +set protocols bgp neighbor 2001:db8::1 ebgp-multihop '2' +set protocols bgp neighbor 2001:db8::1 remote-as '65534' +set protocols bgp neighbor 2001:db8::1 update-source '2001:db8::2' +set protocols bgp neighbor 2001:db8::1 address-family ipv6-unicast +set protocols bgp address-family ipv6-unicast network '2001:db8:2::/48' +set protocols bgp parameters router-id '10.1.1.2' +``` + +Don't forget, the CIDR declared in the network statement **MUST exist in your +routing table (dynamic or static), the best way to make sure that is true is +creating a static route:** + +**Node 1:** + +```none +set protocols static route6 2001:db8:1::/48 blackhole distance '254' +``` + +**Node 2:** + +```none +set protocols static route6 2001:db8:2::/48 blackhole distance '254' +``` + +### Route Filtering + +Route filter can be applied using a route-map: + +**Node1:** + +```none +set policy prefix-list AS65535-IN rule 10 action 'permit' +set policy prefix-list AS65535-IN rule 10 prefix '172.16.0.0/16' +set policy prefix-list AS65535-OUT rule 10 action 'deny' +set policy prefix-list AS65535-OUT rule 10 prefix '172.16.0.0/16' +set policy prefix-list6 AS65535-IN rule 10 action 'permit' +set policy prefix-list6 AS65535-IN rule 10 prefix '2001:db8:2::/48' +set policy prefix-list6 AS65535-OUT rule 10 action 'deny' +set policy prefix-list6 AS65535-OUT rule 10 prefix '2001:db8:2::/48' + +set policy route-map AS65535-IN rule 10 action 'permit' +set policy route-map AS65535-IN rule 10 match ip address prefix-list 'AS65535-IN' +set policy route-map AS65535-IN rule 10 match ipv6 address prefix-list 'AS65535-IN' +set policy route-map AS65535-IN rule 20 action 'deny' +set policy route-map AS65535-OUT rule 10 action 'deny' +set policy route-map AS65535-OUT rule 10 match ip address prefix-list 'AS65535-OUT' +set policy route-map AS65535-OUT rule 10 match ipv6 address prefix-list 'AS65535-OUT' +set policy route-map AS65535-OUT rule 20 action 'permit' + +set protocols bgp system-as 65534 +set protocols bgp neighbor 2001:db8::2 address-family ipv4-unicast route-map export 'AS65535-OUT' +set protocols bgp neighbor 2001:db8::2 address-family ipv4-unicast route-map import 'AS65535-IN' +set protocols bgp neighbor 2001:db8::2 address-family ipv6-unicast route-map export 'AS65535-OUT' +set protocols bgp neighbor 2001:db8::2 address-family ipv6-unicast route-map import 'AS65535-IN' +``` + +**Node2:** + +```none +set policy prefix-list AS65534-IN rule 10 action 'permit' +set policy prefix-list AS65534-IN rule 10 prefix '172.17.0.0/16' +set policy prefix-list AS65534-OUT rule 10 action 'deny' +set policy prefix-list AS65534-OUT rule 10 prefix '172.17.0.0/16' +set policy prefix-list6 AS65534-IN rule 10 action 'permit' +set policy prefix-list6 AS65534-IN rule 10 prefix '2001:db8:1::/48' +set policy prefix-list6 AS65534-OUT rule 10 action 'deny' +set policy prefix-list6 AS65534-OUT rule 10 prefix '2001:db8:1::/48' + +set policy route-map AS65534-IN rule 10 action 'permit' +set policy route-map AS65534-IN rule 10 match ip address prefix-list 'AS65534-IN' +set policy route-map AS65534-IN rule 10 match ipv6 address prefix-list 'AS65534-IN' +set policy route-map AS65534-IN rule 20 action 'deny' +set policy route-map AS65534-OUT rule 10 action 'deny' +set policy route-map AS65534-OUT rule 10 match ip address prefix-list 'AS65534-OUT' +set policy route-map AS65534-OUT rule 10 match ipv6 address prefix-list 'AS65534-OUT' +set policy route-map AS65534-OUT rule 20 action 'permit' + +set protocols bgp system-as 65535 +set protocols bgp neighbor 2001:db8::1 address-family ipv4-unicast route-map export 'AS65534-OUT' +set protocols bgp neighbor 2001:db8::1 address-family ipv4-unicast route-map import 'AS65534-IN' +set protocols bgp neighbor 2001:db8::1 address-family ipv6-unicast route-map export 'AS65534-OUT' +set protocols bgp neighbor 2001:db8::1 address-family ipv6-unicast route-map import 'AS65534-IN' +``` + +We could expand on this and also deny link local and multicast in the rule 20 +action deny. diff --git a/docs/configuration/protocols/md-failover.md b/docs/configuration/protocols/md-failover.md new file mode 100644 index 00000000..96374d11 --- /dev/null +++ b/docs/configuration/protocols/md-failover.md @@ -0,0 +1,237 @@ +--- +description: |- + Failover routes are static routes that are installed in the routing + table only while a configured health-check target responds. VyOS uses them + to switch traffic to a backup path when the primary next hop becomes + unreachable, and to restore the primary path automatically once it recovers. +keywords: |- + failover, failover route, static route, health check, icmp probe, + next hop, route metric +--- + +# Failover + +Failover routes are manually configured network paths used only while their +health-check targets are reachable. If the target stops responding, VyOS +removes the route from the routing table and reinstalls it once the target +recovers. + +## Configuration + +Use the following commands to configure failover routes for a specific remote +`` reachable via next-hop `
`. + +```{eval-rst} +.. cfgcmd:: set protocols failover route next-hop
check target + + **Configure the health check target IP address.** + + This is typically a highly available host, either within the destination + subnet or on the public internet. + + Example: + + .. code-block:: none + + set protocols failover route 203.0.113.1/32 next-hop 10.217.37.254 check target 8.8.8.8 +``` + +```{eval-rst} +.. cfgcmd:: set protocols failover route next-hop
check timeout + + **Configure the timeout interval, in seconds, between target health checks.** + + The valid range is 1 to 300 seconds. The default is 10 seconds. + + Example: + + .. code-block:: none + + set protocols failover route 203.0.113.1/32 next-hop 10.217.37.254 check timeout 2 +``` + +```{eval-rst} +.. cfgcmd:: set protocols failover route next-hop
check type + + **Configure the protocol to use for health checks.** + + The following protocols are available: + + * ``icmp``: VyOS sends two ICMP echo request packets with a 1-second + response timeout. The health check is successful if at least one response + is received. + * ``arp``: VyOS sends two ARP requests with a 1-second response timeout. + The health check is successful if at least one response is received. + * ``tcp``: VyOS verifies whether the destination TCP port is open. The + health check is successful if a TCP connection is successfully + established with the target port. + + The default protocol is ``icmp``. + + .. note:: + + When the check type is set to ``tcp``, you must also define the target + TCP port. + + Example: + + .. code-block:: none + + set protocols failover route 203.0.113.1/32 next-hop 10.217.37.254 check type tcp +``` + +```{eval-rst} +.. cfgcmd:: set protocols failover route next-hop
check port + + **Configure the destination TCP port on the health check target.** + + This parameter applies only when the check type is configured as ``tcp``. + + The valid port range is 1 to 65535. + + Example: + + .. code-block:: none + + set protocols failover route 203.0.113.1/32 next-hop 10.217.37.254 check port 443 +``` + +```{eval-rst} +.. cfgcmd:: set protocols failover route next-hop
check policy + + **Configure the health check success policy for multiple targets.** + + The following policies are available: + + * ``any-available``: The health check succeeds if at least one of the + configured targets responds successfully. + * ``all-available``: The health check succeeds only if every configured + target responds successfully. + + The default policy is ``any-available``. + + Example: + + .. code-block:: none + + set protocols failover route 203.0.113.1/32 next-hop 10.217.37.254 check policy all-available +``` + +```{eval-rst} +.. cfgcmd:: set protocols failover route next-hop
interface + + **Configure the local interface used to reach the next-hop address.** + + This parameter is mandatory. + + Example: + + .. code-block:: none + + set protocols failover route 203.0.113.1/32 next-hop 10.217.37.254 interface eth0 +``` + +```{eval-rst} +.. cfgcmd:: set protocols failover route next-hop
metric <1-255> + + **Configure the metric (cost) for the failover route.** + + The metric defines the route priority. A lower metric value indicates a + more preferred route. + + The default value is 1. + + Example: + + .. code-block:: none + + set protocols failover route 203.0.113.1/32 next-hop 10.217.37.254 metric 50 +``` + +```{eval-rst} +.. cfgcmd:: set protocols failover route next-hop
onlink + + Configure the next-hop to be reachable via the assigned interface, even + when ``
`` is outside any subnet configured on that interface. + + Example: + + .. code-block:: none + + set protocols failover route 203.0.113.1/32 next-hop 10.217.37.254 onlink +``` + +## Examples + +### Failover route with a single next-hop and ICMP health check + +The following example configures a failover route to `203.0.113.1/32` +through next-hop `192.0.2.1` on `eth0`. The next-hop is monitored with +ICMP probes to `192.0.2.1` every 5 seconds, and the route is installed with +a metric of 10. + +```none +set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 check target '192.0.2.1' +set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 check timeout '5' +set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 check type 'icmp' +set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 interface 'eth0' +set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 metric '10' +``` + +Verify the route: + +```none +vyos@vyos:~$ show ip route 203.0.113.1 +Routing entry for 203.0.113.1/32 + Known via "kernel", distance 0, metric 10, best + Last update 00:00:39 ago + Flags: Selected + Status: Installed + * 192.0.2.1, via eth0, weight 1 +``` + +### Two failover routes with different metrics + +The following example configures two failover routes to `203.0.113.1/32`, +each through a different next-hop. The primary next-hop `192.0.2.1` is +reached on `eth0` with metric 10, and the backup next-hop `198.51.100.1` +is reached on `eth2` with metric 20. Both next-hops are monitored with ICMP +probes every 5 seconds. + +While both health checks succeed, the lower-metric route through `eth0` is +preferred. If the primary target stops responding, its route is removed from +the routing table, and traffic falls over to `198.51.100.1` via `eth2`. + +```none +set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 check target '192.0.2.1' +set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 check timeout '5' +set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 check type 'icmp' +set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 interface 'eth0' +set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 metric '10' + +set protocols failover route 203.0.113.1/32 next-hop 198.51.100.1 check target '198.51.100.99' +set protocols failover route 203.0.113.1/32 next-hop 198.51.100.1 check timeout '5' +set protocols failover route 203.0.113.1/32 next-hop 198.51.100.1 check type 'icmp' +set protocols failover route 203.0.113.1/32 next-hop 198.51.100.1 interface 'eth2' +set protocols failover route 203.0.113.1/32 next-hop 198.51.100.1 metric '20' +``` + +Verify routes: + +```none +vyos@vyos:~$ show ip route 203.0.113.1 +Routing entry for 203.0.113.1/32 + Known via "kernel", distance 0, metric 10, best + Last update 00:08:06 ago + Flags: Selected + Status: Installed + * 192.0.2.1, via eth0, weight 1 + +Routing entry for 203.0.113.1/32 + Known via "kernel", distance 0, metric 20 + Last update 00:08:14 ago + Flags: None + Status: Installed + * 198.51.100.1, via eth2, weight 1 +``` + diff --git a/docs/configuration/protocols/md-igmp-proxy.md b/docs/configuration/protocols/md-igmp-proxy.md new file mode 100644 index 00000000..961f921b --- /dev/null +++ b/docs/configuration/protocols/md-igmp-proxy.md @@ -0,0 +1,79 @@ +--- +lastproofread: '2023-11-13' +--- + +(igmp-proxy)= + +# IGMP Proxy + +{abbr}`IGMP (Internet Group Management Protocol)` proxy sends IGMP host messages +on behalf of a connected client. The configuration must define one, and only one +upstream interface, and one or more downstream interfaces. + +## Configuration + +```{cfgcmd} set protocols igmp-proxy interface \ role \ + +* **upstream:** The upstream network interface is the outgoing interface +which is responsible for communicating to available multicast data sources. +There can only be one upstream interface. + +* **downstream:** Downstream network interfaces are the distribution +interfaces to the destination networks, where multicast clients can join +groups and receive multicast data. One or more downstream interfaces must +be configured. +``` + +```{cfgcmd} set protocols igmp-proxy interface \ alt-subnet \ + +Defines alternate sources for multicasting and IGMP data. The network address +must be on the following format 'a.b.c.d/n'. By default, the router will +accept data from sources on the same network as configured on an interface. +If the multicast source lies on a remote network, one must define from where +traffic should be accepted. + +This is especially useful for the upstream interface, since the source for +multicast traffic is often from a remote location. + +This option can be supplied multiple times. +``` + +```{cfgcmd} set protocols igmp-proxy disable-quickleave + +Disables quickleave mode. In this mode the daemon will not send a Leave IGMP +message upstream as soon as it receives a Leave message for any downstream +interface. The daemon will not ask for Membership reports on the downstream +interfaces, and if a report is received the group is not joined again the +upstream. + +If it's vital that the daemon should act exactly like a real multicast client +on the upstream interface, this function should be enabled. + +Enabling this function increases the risk of bandwidth saturation. +``` + +```{cfgcmd} set protocols igmp-proxy disable + +Disable this service. +``` + +(igmp-proxy-example)= + +### Example + +Interface eth1 LAN is behind NAT. In order to subscribe 10.0.0.0/23 subnet +multicast which is in eth0 WAN we need to configure igmp-proxy. + +```none +set protocols igmp-proxy interface eth0 role upstream +set protocols igmp-proxy interface eth0 alt-subnet 10.0.0.0/23 +set protocols igmp-proxy interface eth1 role downstream +``` + + +## Operation + +```{opcmd} restart igmp-proxy + +Restart the IGMP proxy process. +``` \ No newline at end of file diff --git a/docs/configuration/protocols/md-index.md b/docs/configuration/protocols/md-index.md new file mode 100644 index 00000000..5f190ce1 --- /dev/null +++ b/docs/configuration/protocols/md-index.md @@ -0,0 +1,25 @@ +# Protocols + +```{toctree} +:includehidden: true +:maxdepth: 1 + +arp +babel +bfd +bgp +failover +igmp-proxy +isis +mpls +multicast +segment-routing +traffic-engineering +openfabric +ospf +pim +pim6 +rip +rpki +static +``` diff --git a/docs/configuration/protocols/md-isis.md b/docs/configuration/protocols/md-isis.md new file mode 100644 index 00000000..ac6db346 --- /dev/null +++ b/docs/configuration/protocols/md-isis.md @@ -0,0 +1,746 @@ +```{include} /_include/need_improvement.txt +``` + +(routing-isis)= + +# IS-IS + +{abbr}`IS-IS (Intermediate System to Intermediate System)` is a link-state +interior gateway protocol (IGP) which is described in ISO10589, +{rfc}`1195`, {rfc}`5308`. IS-IS runs the Dijkstra shortest-path first (SPF) +algorithm to create a database of the network’s topology, and +from that database to determine the best (that is, lowest cost) path to a +destination. The intermediate systems (the name for routers) exchange topology +information with their directly connected neighbors. IS-IS runs directly on +the data link layer (Layer 2). IS-IS addresses are called +{abbr}`NETs (Network Entity Titles)` and can be 8 to 20 bytes long, but are +generally 10 bytes long. The tree database that is created with IS-IS is +similar to the one that is created with OSPF in that the paths chosen should +be similar. Comparisons to OSPF are inevitable and often are reasonable ones +to make in regards to the way a network will respond with either IGP. + +## General + +### Configuration + +#### Mandatory Settings + +For IS-IS top operate correctly, one must do the equivalent of a Router ID in +CLNS. This Router ID is called the {abbr}`NET (Network Entity Title)`. This +must be unique for each and every router that is operating in IS-IS. It also +must not be duplicated otherwise the same issues that occur within OSPF will +occur within IS-IS when it comes to said duplication. + +```{cfgcmd} set protocols isis net \ + +This command sets network entity title (NET) provided in ISO format. + +Here is an example {abbr}`NET (Network Entity Title)` value: + +:::{code-block} none +49.0001.1921.6800.1002.00 +::: +The CLNS address consists of the following parts: + +* {abbr}`AFI (Address family authority identifier)` - ``49`` The AFI value + 49 is what IS-IS uses for private addressing. + +* Area identifier: ``0001`` IS-IS area number (numerical area ``1``) + +* System identifier: ``1921.6800.1002`` - for system identifiers we recommend + to use IP address or MAC address of the router itself. The way to construct + this is to keep all of the zeroes of the router IP address, and then change + the periods from being every three numbers to every four numbers. The + address that is listed here is ``192.168.1.2``, which if expanded will turn + into ``192.168.001.002``. Then all one has to do is move the dots to have + four numbers instead of three. This gives us ``1921.6800.1002``. + +* {abbr}`NET (Network Entity Title)` selector: ``00`` Must always be 00. This + setting indicates "this system" or "local system." + +``` + +```{cfgcmd} set protocols isis interface \ + +This command enables IS-IS on this interface, and allows for +adjacency to occur. Note that the name of IS-IS instance must be +the same as the one used to configure the IS-IS process. +``` + +#### IS-IS Global Configuration + +```{cfgcmd} set protocols isis dynamic-hostname + +This command enables support for dynamic hostname TLV. Dynamic hostname +mapping determined as described in {rfc}`2763`, Dynamic Hostname +Exchange Mechanism for IS-IS. +``` + +```{cfgcmd} set protocols isis level \ + +This command defines the IS-IS router behavior: + +* **level-1** - Act as a station (Level 1) router only. +* **level-1-2** - Act as a station (Level 1) router and area (Level 2) router. +* **level-2-only** - Act as an area (Level 2) router only. +``` + +```{cfgcmd} set protocols isis lsp-mtu \ + +This command configures the maximum size of generated +{abbr}`LSPs (Link State PDUs)`, in bytes. The size range is 128 to 4352. +``` + +```{cfgcmd} set protocols isis metric-style \ + +This command sets old-style (ISO 10589) or new style packet formats: + +* **narrow** - Use old style of TLVs with narrow metric. +* **transition** - Send and accept both styles of TLVs during transition. +* **wide** - Use new style of TLVs to carry wider metric. +``` + +```{cfgcmd} set protocols isis purge-originator + +This command enables {rfc}`6232` purge originator identification. Enable +purge originator identification (POI) by adding the type, length and value +(TLV) with the Intermediate System (IS) identification to the LSPs that do +not contain POI information. If an IS generates a purge, VyOS adds this TLV +with the system ID of the IS to the purge. +``` + +```{cfgcmd} set protocols isis set-attached-bit + +This command sets ATT bit to 1 in Level1 LSPs. It is described in {rfc}`3787`. +``` + +```{cfgcmd} set protocols isis set-overload-bit + +This command sets overload bit to avoid any transit traffic through this +router. It is described in {rfc}`3787`. +``` + +```{cfgcmd} set protocols isis default-information originate \ level-1 + +This command will generate a default-route in L1 database. +``` + +```{cfgcmd} set protocols isis default-information originate \ level-2 + +This command will generate a default-route in L2 database. +``` + +```{cfgcmd} set protocols isis ldp-sync + +This command will enable IGP-LDP synchronization globally for ISIS. This +requires for LDP to be functional. This is described in {rfc}`5443`. By +default all interfaces operational in IS-IS are enabled for synchronization. +Loopbacks are exempt. + +``` + +```{cfgcmd} set protocols isis ldp-sync holddown \ + +This command will change the hold down value globally for IGP-LDP +synchronization during convergence/interface flap events. +``` + +#### Interface Configuration + +```{cfgcmd} set protocols isis interface \ circuit-type \ + +This command specifies circuit type for interface: + +* **level-1** - Level-1 only adjacencies are formed. +* **level-1-2** - Level-1-2 adjacencies are formed +* **level-2-only** - Level-2 only adjacencies are formed + +``` + +```{cfgcmd} set protocols isis interface \ hello-interval \ + +This command sets hello interval in seconds on a given interface. +The range is 1 to 600. +``` + +```{cfgcmd} set protocols isis interface \ hello-multiplier \ + +This command sets multiplier for hello holding time on a given +interface. The range is 2 to 100. +``` + +```{cfgcmd} set protocols isis interface \ hello-padding + +This command configures padding on hello packets to accommodate asymmetrical +maximum transfer units (MTUs) from different hosts as described in +{rfc}`3719`. This helps to prevent a premature adjacency Up state when one +routing devices MTU does not meet the requirements to establish the adjacency. +``` + +```{cfgcmd} set protocols isis interface \ metric \ + +This command set default metric for circuit. + +The metric range is 1 to 16777215 (Max value depend if metric support narrow +or wide value). +``` + +```{cfgcmd} set protocols isis interface \ network point-to-point + +This command specifies network type to Point-to-Point. The default +network type is broadcast. +``` + +```{cfgcmd} set protocols isis interface \ passive + +This command configures the passive mode for this interface. +``` + +```{cfgcmd} set protocols isis interface \ password plaintext-password \ + +This command configures the authentication password for the interface. +``` + +```{cfgcmd} set protocols isis interface \ priority \ + +This command sets priority for the interface for +{abbr}`DIS (Designated Intermediate System)` election. The priority +range is 0 to 127. +``` + +```{cfgcmd} set protocols isis interface \ psnp-interval \ + +This command sets PSNP interval in seconds. The interval range is 0 +to 127. +``` + +```{cfgcmd} set protocols isis interface \ no-three-way-handshake + +This command disables Three-Way Handshake for P2P adjacencies which +described in {rfc}`5303`. Three-Way Handshake is enabled by default. +``` + +```{cfgcmd} set protocols isis interface \ ldp-sync disable + +This command disables IGP-LDP sync for this specific interface. +``` + +```{cfgcmd} set protocols isis interface \ ldp-sync holddown \ + +This command will change the hold down value for IGP-LDP synchronization +during convergence/interface flap events, but for this interface only. +``` + +```{cfgcmd} set protocols isis interface \ fast-reroute lfa [level-1 | level-2] enable + +This command enables per-prefix local LFA fast reroute link protection. +``` + +```{cfgcmd} set protocols isis interface \ fast-reroute lfa [level-1 | level-2] exclude + +This command excludes an interface from the local LFA backup nexthop computation. +``` + +```{cfgcmd} set protocols isis interface \ fast-reroute remote-lfa [level-1 | level-2] tunnel mpls-ldp + +This command enables per-prefix Remote LFA fast reroute link protection. +Note that other routers in the network need to be configured to accept LDP +targeted hello messages in order for RLFA to work. +``` + +```{cfgcmd} set protocols isis interface \ fast-reroute remote-lfa [level-1 | level-2] maximum-metric \ + +This command limits Remote LFA PQ node selection within the specified metric. Metric value range (1-16777215). +``` + +```{cfgcmd} set protocols isis interface \ fast-reroute ti-lfa [level-1|level-2] [node-protection [link-fallback]] + +This command enables per-prefix TI-LFA fast reroute link or node protection. +When node protection is used, option link-fallback enables the computation +and use of link-protecting LFAs for destinations unprotected by node +protection. +``` + +#### Route Redistribution + +```{cfgcmd} set protocols isis redistribute ipv4 \ level-1 + +This command redistributes routing information from the given route source +into the ISIS database as Level-1. There are six modes available for route +source: bgp, connected, kernel, ospf, rip, static. +``` + +```{cfgcmd} set protocols isis redistribute ipv4 \ level-2 + +This command redistributes routing information from the given route source +into the ISIS database as Level-2. There are six modes available for route +source: bgp, connected, kernel, ospf, rip, static. +``` + +```{cfgcmd} set protocols isis redistribute ipv4 \ \ metric \ + +This command specifies metric for redistributed routes from the given route +source. There are six modes available for route source: bgp, connected, +kernel, ospf, rip, static. The metric range is 1 to 16777215. +``` + +```{cfgcmd} set protocols isis redistribute ipv4 \ \ route-map \ + +This command allows to use route map to filter redistributed routes from +the given route source. There are six modes available for route source: +bgp, connected, kernel, ospf, rip, static. +``` + +#### Timers + +```{cfgcmd} set protocols isis lsp-gen-interval \ + +This command sets minimum interval in seconds between regenerating same +LSP. The interval range is 1 to 120. +``` + +```{cfgcmd} set protocols isis lsp-refresh-interval \ + +This command sets LSP refresh interval in seconds. IS-IS generates LSPs +when the state of a link changes. However, to ensure that routing +databases on all routers remain converged, LSPs in stable networks are +generated on a regular basis even though there has been no change to +the state of the links. The interval range is 1 to 65235. The default +value is 900 seconds. +``` + +```{cfgcmd} set protocols isis max-lsp-lifetime \ + +This command sets LSP maximum LSP lifetime in seconds. The interval range +is 350 to 65535. LSPs remain in a database for 1200 seconds by default. +If they are not refreshed by that time, they are deleted. You can change +the LSP refresh interval or the LSP lifetime. The LSP refresh interval +should be less than the LSP lifetime or else LSPs will time out before +they are refreshed. +``` + +```{cfgcmd} set protocols isis spf-interval \ + +This command sets minimum interval between consecutive SPF calculations in +seconds.The interval range is 1 to 120. +``` + +```{cfgcmd} set protocols isis spf-delay-ietf holddown \ +``` + +```{cfgcmd} set protocols isis spf-delay-ietf init-delay \ +``` + +```{cfgcmd} set protocols isis spf-delay-ietf long-delay \ +``` + +```{cfgcmd} set protocols isis spf-delay-ietf short-delay \ +``` + +```{cfgcmd} set protocols isis spf-delay-ietf time-to-learn \ + +This commands specifies the Finite State Machine (FSM) intended to +control the timing of the execution of SPF calculations in response +to IGP events. The process described in {rfc}`8405`. +``` + +#### Loop Free Alternate (LFA) + +```{cfgcmd} set protocols isis fast-reroute lfa remote prefix-list \ \ + +This command enables IP fast re-routing that is part of {rfc}`5286`. +Specifically this is a prefix list which references a prefix in which +will select eligible PQ nodes for remote LFA backups. +``` + +```{cfgcmd} set protocols isis fast-reroute lfa local load-sharing disable \ + +This command disables the load sharing across multiple LFA backups. +``` + +```{cfgcmd} set protocols isis fast-reroute lfa local tiebreaker \ index \ \ + +This command will configure a tie-breaker for multiple local LFA backups. +The lower index numbers will be processed first. +``` + +```{cfgcmd} set protocols isis fast-reroute lfa local priority-limit \ \ + +This command will limit LFA backup computation up to the specified +prefix priority. +``` + +#### Segment Routing over IPv6 (SRv6) + +```{cfgcmd} set protocols isis segment-routing srv6 interface \ + +The dummy interface used +to install SRv6 SIDs into the Linux data plane. The interface must exist and +must be present when configuring IS-IS with +SRv6. +``` + +```{cfgcmd} set protocols isis segment-routing srv6 locator \ + +Specifies the SRv6 locator to use for IS-IS. IS-IS automatically allocates +prefix and adjacency SIDs, creates local SID entries and advertises them +into the IGP domain. +``` + +```{cfgcmd} set protocols isis segment-routing srv6 node-msd max-end-d \<0-255\> + +The Maximum End D MSD Type specifies the maximum number of SIDs present in an +SRH when performing decapsulation. As specified in {rfc}`8986`, the permitted +SID types include, but are not limited to, End.DX6, End.DT4, End.DT46, End +with USD, and End.X with USD. + +If the advertised value is zero or no value is advertised, then the router +cannot apply any behavior that results in decapsulation and forwarding of the +inner packet if the outer IPv6 header contains an SRH. + +Reference: {rfc}`9352` +``` + +```{cfgcmd} set protocols isis segment-routing srv6 node-msd max-end-pop \<0-255\> + +The Maximum End Pop MSD Type signals the maximum number of SIDs in the SRH to +which the router can apply "Penultimate Segment Pop (PSP) of the SRH" or +"Ultimate Segment Pop (USP) of the SRH" behavior, as defined in "Flavors" +(Section 4.16 of {rfc}`8986`). + +If the advertised value is zero or no value is advertised, then the router +cannot apply PSP or USP flavors. + +Reference: {rfc}`9352` +``` + +```{cfgcmd} set protocols isis segment-routing srv6 node-msd max-h-encaps \<0-255\> + +The Maximum H.Encaps MSD Type signals the maximum number of SIDs that can be +added to the segment list of an SRH as part of the "H.Encaps" behavior, as +defined in {rfc}`8986`. + +If the advertised value is zero or no value is advertised, then the headend +can apply an SR Policy that only contains one segment without inserting any +SRH header. A non-zero SRH Max H.encaps MSD indicates that the headend can +insert an SRH up to the advertised number of SIDs. + +Reference: {rfc}`9352` +``` + +```{cfgcmd} set protocols isis segment-routing srv6 node-msd max-segs-left \<0-255\> + +The Maximum Segments Left MSD Type signals the maximum value of the +"Segments Left" field ({rfc}`8754`) in the SRH of a received packet before +applying the Endpoint behavior associated with a SID. + +If no value is advertised, the supported value is 0. + +Reference: {rfc}`9352` +``` + +## Examples + +### Enable IS-IS + +**Node 1:** + +```none +set interfaces loopback lo address '192.168.255.255/32' +set interfaces ethernet eth1 address '192.0.2.1/24' + +set protocols isis interface eth1 +set protocols isis interface lo +set protocols isis net '49.0001.1921.6825.5255.00' +``` + +**Node 2:** + +```none +set interfaces ethernet eth1 address '192.0.2.2/24' + +set interfaces loopback lo address '192.168.255.254/32' +set interfaces ethernet eth1 address '192.0.2.2/24' + +set protocols isis interface eth1 +set protocols isis interface lo +set protocols isis net '49.0001.1921.6825.5254.00' +``` + +This gives us the following neighborships, Level 1 and Level 2: + +```none +Node-1@vyos:~$ show isis neighbor +Area VyOS: + System Id Interface L State Holdtime SNPA + vyos eth1 1 Up 28 0c87.6c09.0001 + vyos eth1 2 Up 28 0c87.6c09.0001 + +Node-2@vyos:~$ show isis neighbor +Area VyOS: + System Id Interface L State Holdtime SNPA + vyos eth1 1 Up 29 0c33.0280.0001 + vyos eth1 2 Up 28 0c33.0280.0001 +``` + +Here's the IP routes that are populated. Just the loopback: + +```none +Node-1@vyos:~$ show ip route isis +Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, + f - OpenFabric, + > - selected route, * - FIB route, q - queued, r - rejected, b - backup + t - trapped, o - offload failure + +I 192.0.2.0/24 [115/20] via 192.0.2.2, eth1 inactive, weight 1, 00:02:22 +I>* 192.168.255.254/32 [115/20] via 192.0.2.2, eth1, weight 1, 00:02:22 + +Node-2@vyos:~$ show ip route isis +Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, + f - OpenFabric, + > - selected route, * - FIB route, q - queued, r - rejected, b - backup + t - trapped, o - offload failure + +I 192.0.2.0/24 [115/20] via 192.0.2.1, eth1 inactive, weight 1, 00:02:21 +I>* 192.168.255.255/32 [115/20] via 192.0.2.1, eth1, weight 1, 00:02:21 +``` + +### Enable IS-IS and redistribute routes not natively in IS-IS + +**Node 1:** + +```none +set interfaces dummy dum0 address '203.0.113.1/24' +set interfaces ethernet eth1 address '192.0.2.1/24' + +set policy prefix-list EXPORT-ISIS rule 10 action 'permit' +set policy prefix-list EXPORT-ISIS rule 10 prefix '203.0.113.0/24' +set policy route-map EXPORT-ISIS rule 10 action 'permit' +set policy route-map EXPORT-ISIS rule 10 match ip address prefix-list 'EXPORT-ISIS' + +set protocols isis interface eth1 +set protocols isis net '49.0001.1921.6800.1002.00' +set protocols isis redistribute ipv4 connected level-2 route-map 'EXPORT-ISIS' +``` + +**Node 2:** + +```none +set interfaces ethernet eth1 address '192.0.2.2/24' + +set protocols isis interface eth1 +set protocols isis net '49.0001.1921.6800.2002.00' +``` + +Routes on Node 2: + +```none +Node-2@r2:~$ show ip route isis +Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, D - SHARP, + F - PBR, f - OpenFabric, + > - selected route, * - FIB route, q - queued route, r - rejected route + +I 203.0.113.0/24 [115/10] via 192.0.2.1, eth1, 00:03:42 +``` + +### Enable IS-IS and IGP-LDP synchronization + +**Node 1:** + +```none +set interfaces loopback lo address 192.168.255.255/32 +set interfaces ethernet eth0 address 192.0.2.1/24 + +set protocols isis interface eth0 +set protocols isis interface lo passive +set protocols isis ldp-sync +set protocols isis net 49.0001.1921.6825.5255.00 + +set protocols mpls interface eth0 +set protocols mpls ldp discovery transport-ipv4-address 192.168.255.255 +set protocols mpls ldp interface lo +set protocols mpls ldp interface eth0 +set protocols mpls ldp parameters transport-prefer-ipv4 +set protocols mpls ldp router-id 192.168.255.255 +``` + +This gives us IGP-LDP synchronization for all non-loopback interfaces with +a holddown timer of zero seconds: + +```none +Node-1@vyos:~$ show isis mpls ldp-sync +eth0 + LDP-IGP Synchronization enabled: yes + holddown timer in seconds: 0 + State: Sync achieved +``` + +### Enable IS-IS with Segment Routing (Experimental) + +**Node 1:** + +```none +set interfaces loopback lo address '192.168.255.255/32' +set interfaces ethernet eth1 address '192.0.2.1/24' + +set protocols isis interface eth1 +set protocols isis interface lo +set protocols isis net '49.0001.1921.6825.5255.00' +set protocols isis segment-routing global-block high-label-value '599' +set protocols isis segment-routing global-block low-label-value '550' +set protocols isis segment-routing prefix 192.168.255.255/32 index value '1' +set protocols isis segment-routing prefix 192.168.255.255/32 index explicit-null +set protocols mpls interface 'eth1' +``` + +**Node 2:** + +```none +set interfaces loopback lo address '192.168.255.254/32' +set interfaces ethernet eth1 address '192.0.2.2/24' + +set protocols isis interface eth1 +set protocols isis interface lo +set protocols isis net '49.0001.1921.6825.5254.00' +set protocols isis segment-routing global-block high-label-value '599' +set protocols isis segment-routing global-block low-label-value '550' +set protocols isis segment-routing prefix 192.168.255.254/32 index value '2' +set protocols isis segment-routing prefix 192.168.255.254/32 index explicit-null +set protocols mpls interface 'eth1' +``` + +This gives us MPLS segment routing enabled and labels for far end loopbacks: + +```none +Node-1@vyos:~$ show mpls table + Inbound Label Type Nexthop Outbound Label + ---------------------------------------------------------------------- + 552 SR (IS-IS) 192.0.2.2 IPv4 Explicit Null <-- Node-2 loopback learned on Node-1 + 15000 SR (IS-IS) 192.0.2.2 implicit-null + 15001 SR (IS-IS) fe80::e87:6cff:fe09:1 implicit-null + 15002 SR (IS-IS) 192.0.2.2 implicit-null + 15003 SR (IS-IS) fe80::e87:6cff:fe09:1 implicit-null + +Node-2@vyos:~$ show mpls table + Inbound Label Type Nexthop Outbound Label + --------------------------------------------------------------------- + 551 SR (IS-IS) 192.0.2.1 IPv4 Explicit Null <-- Node-1 loopback learned on Node-2 + 15000 SR (IS-IS) 192.0.2.1 implicit-null + 15001 SR (IS-IS) fe80::e33:2ff:fe80:1 implicit-null + 15002 SR (IS-IS) 192.0.2.1 implicit-null + 15003 SR (IS-IS) fe80::e33:2ff:fe80:1 implicit-null +``` + +Here is the routing tables showing the MPLS segment routing label operations: + +```none +Node-1@vyos:~$ show ip route isis +Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, + f - OpenFabric, + > - selected route, * - FIB route, q - queued, r - rejected, b - backup + t - trapped, o - offload failure + +I 192.0.2.0/24 [115/20] via 192.0.2.2, eth1 inactive, weight 1, 00:07:48 +I>* 192.168.255.254/32 [115/20] via 192.0.2.2, eth1, label IPv4 Explicit Null, weight 1, 00:03:39 + +Node-2@vyos:~$ show ip route isis +Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, + f - OpenFabric, + > - selected route, * - FIB route, q - queued, r - rejected, b - backup + t - trapped, o - offload failure + +I 192.0.2.0/24 [115/20] via 192.0.2.1, eth1 inactive, weight 1, 00:07:46 +I>* 192.168.255.255/32 [115/20] via 192.0.2.1, eth1, label IPv4 Explicit Null, weight 1, 00:03:43 +``` + +### Enable IS-IS with Segment Routing over IPv6 (Experimental) + +**Node 1:** + +```none +set interfaces dummy dum6 description "SRv6 IS-IS" +set interfaces ethernet eth1 address '192.0.2.1/24' +set interfaces loopback lo address '192.168.255.255/32' + +set protocols segment-routing srv6 locator MAIN prefix 2001:db8:1::/64 +set protocols segment-routing interface eth1 + +set protocols isis interface eth1 +set protocols isis interface lo +set protocols isis net '49.0001.1921.6825.5255.00' +set protocols isis segment-routing srv6 locator MAIN +set protocols isis segment-routing srv6 interface dum6 +``` + +**Node 2:** + +```none +set interfaces dummy dum6 description "SRv6 IS-IS" +set interfaces ethernet eth1 address '192.0.2.2/24' +set interfaces loopback lo address '192.168.255.254/32' + +set protocols segment-routing srv6 locator MAIN prefix 2001:db8:2::/64 +set protocols segment-routing interface eth1 + +set protocols isis interface eth1 +set protocols isis interface lo +set protocols isis net '49.0001.1921.6825.5254.00' +set protocols isis segment-routing srv6 locator MAIN +set protocols isis segment-routing srv6 interface dum6 +``` + +### Enable IS-IS with Segment Routing over IPv6 (uSID) (Experimental) + +**Node 1:** + +```none +set interfaces dummy dum6 description "SRv6 IS-IS" +set interfaces ethernet eth1 address '192.0.2.1/24' +set interfaces loopback lo address '192.168.255.255/32' + +set protocols segment-routing interface eth1 +set protocols segment-routing srv6 locator MAIN prefix 2001:db8:1::/48 +set protocols segment-routing srv6 locator MAIN behavior-usid +set protocols segment-routing srv6 locator MAIN block-len 32 +set protocols segment-routing srv6 locator MAIN format usid-f3216 +set protocols segment-routing srv6 locator MAIN func-bits 16 +set protocols segment-routing srv6 locator MAIN node-len 16 + +set protocols isis interface eth1 +set protocols isis interface lo +set protocols isis net '49.0001.1921.6825.5255.00' +set protocols isis segment-routing srv6 interface dum6 +set protocols isis segment-routing srv6 locator MAIN +``` + +**Node 2:** + +```none +set interfaces dummy dum6 description "SRv6 IS-IS" +set interfaces ethernet eth1 address '192.0.2.2/24' +set interfaces loopback lo address '192.168.255.254/32' + +set protocols segment-routing interface eth1 +set protocols segment-routing srv6 locator MAIN prefix 2001:db8:2::/48 +set protocols segment-routing srv6 locator MAIN behavior-usid +set protocols segment-routing srv6 locator MAIN block-len 32 +set protocols segment-routing srv6 locator MAIN format usid-f3216 +set protocols segment-routing srv6 locator MAIN func-bits 16 +set protocols segment-routing srv6 locator MAIN node-len 16 + +set protocols isis interface eth1 +set protocols isis interface lo +set protocols isis net '49.0001.1921.6825.5254.00' +set protocols isis segment-routing srv6 interface dum6 +set protocols isis segment-routing srv6 locator MAIN +``` diff --git a/docs/configuration/protocols/md-mpls.md b/docs/configuration/protocols/md-mpls.md new file mode 100644 index 00000000..71b14be2 --- /dev/null +++ b/docs/configuration/protocols/md-mpls.md @@ -0,0 +1,285 @@ +(mpls)= + +# MPLS + +{abbr}`MPLS (Multi-Protocol Label Switching)` is a packet forwarding paradigm +which differs from regular IP forwarding. Instead of IP addresses being used to +make the decision on finding the exit interface, a router will instead use an +exact match on a 32 bit/4 byte header called the MPLS label. This label is +inserted between the ethernet (layer 2) header and the IP (layer 3) header. +One can statically or dynamically assign label allocations, but we will focus +on dynamic allocation of labels using some sort of label distribution protocol +(such as the aptly named Label Distribution Protocol / LDP, Resource Reservation +Protocol / RSVP, or Segment Routing through OSPF/ISIS). These protocols allow +for the creation of a unidirectional/unicast path called a labeled switched +path (initialized as LSP) throughout the network that operates very much like +a tunnel through the network. An easy way of thinking about how an MPLS LSP +actually forwards traffic throughout a network is to think of a GRE tunnel. +They are not the same in how they operate, but they are the same in how they +handle the tunneled packet. It would be good to think of MPLS as a tunneling +technology that can be used to transport many different types of packets, to +aid in traffic engineering by allowing one to specify paths throughout the +network (using RSVP or SR), and to generally allow for easier intra/inter +network transport of data packets. + +For more information on how MPLS label switching works, please go visit +[Wikipedia (MPLS)]. + +:::{note} +MPLS support in VyOS is not finished yet, and therefore its +functionality is limited. Currently there is no support for MPLS enabled VPN +services such as L2VPNs and mVPNs. RSVP support is also not present as the +underlying routing stack (FRR) does not implement it. Currently VyOS +implements LDP as described in RFC 5036; other LDP standard are the +following ones: RFC 6720, RFC 6667, RFC 5919, RFC 5561, RFC 7552, RFC 4447. +Because MPLS is already available (FRR also supports RFC 3031). +::: + +## Label Distribution Protocol + +The {abbr}`MPLS (Multi-Protocol Label Switching)` architecture does not assume +a single protocol to create MPLS paths. VyOS supports the Label Distribution +Protocol (LDP) as implemented by FRR, based on {rfc}`5036`. + +{abbr}`LDP (Label Distribution Protocol)` is a TCP based MPLS signaling protocol +that distributes labels creating MPLS label switched paths in a dynamic manner. +LDP is not a routing protocol, as it relies on other routing protocols for +forwarding decisions. LDP cannot bootstrap itself, and therefore relies on said +routing protocols for communication with other routers that use LDP. + +In order to allow for LDP on the local router to exchange label advertisements +with other routers, a TCP session will be established between automatically +discovered and statically assigned routers. LDP will try to establish a TCP +session to the **transport address** of other routers. Therefore for LDP to +function properly please make sure the transport address is shown in the +routing table and reachable to traffic at all times. + +It is highly recommended to use the same address for both the LDP router-id and +the discovery transport address, but for VyOS MPLS LDP to work both parameters +must be explicitly set in the configuration. + +Another thing to keep in mind with LDP is that much like BGP, it is a protocol +that runs on top of TCP. It however does not have an ability to do something +like a refresh capability like BGPs route refresh capability. Therefore one +might have to reset the neighbor for a capability change or a configuration +change to work. + +## Configuration Options + +```{cfgcmd} set protocols mpls interface \ + +Use this command to enable MPLS processing on the interface you define. +``` + + +```{cfgcmd} set protocols mpls ldp interface \ + +Use this command to enable LDP on the interface you define. +``` + + +```{cfgcmd} set protocols mpls ldp router-id \ + +Use this command to configure the IP address used as the LDP router-id of the +local device. +``` + + +```{cfgcmd} set protocols mpls ldp discovery transport-ipv4-address \ + +``` +```{cfgcmd} set protocols mpls ldp discovery transport-ipv6-address \ + +Use this command to set the IPv4 or IPv6 transport-address used by LDP. +``` + +```{cfgcmd} set protocols mpls ldp neighbor \ password \ + +Use this command to configure authentication for LDP peers. Set the +IP address of the LDP peer and a password that should be shared in +order to become neighbors. +``` + +```{cfgcmd} set protocols mpls ldp neighbor \ session-holdtime \ + +Use this command to configure a specific session hold time for LDP peers. +Set the IP address of the LDP peer and a session hold time that should be +configured for it. You may have to reset the neighbor for this to work. +``` + +```{cfgcmd} set protocols mpls ldp neighbor \ ttl-security \ + +Use this command to enable, disable, or specify hop count for TTL security +for LDP peers. By default the value is set to 255 (or max TTL). +``` + +```{eval-rst} +.. cfgcmd:: set protocols mpls ldp discovery hello-ipv4-interval +.. cfgcmd:: set protocols mpls ldp discovery hello-ipv4-holdtime +.. cfgcmd:: set protocols mpls ldp discovery hello-ipv6-interval +.. cfgcmd:: set protocols mpls ldp discovery hello-ipv6-holdtime + + Use these commands if you would like to set the discovery hello and hold time + parameters. +``` + +```{eval-rst} +.. cfgcmd:: set protocols mpls ldp discovery session-ipv4-holdtime +.. cfgcmd:: set protocols mpls ldp discovery session-ipv6-holdtime + + Use this command if you would like to set the TCP session hold time intervals. +``` + +```{eval-rst} +.. cfgcmd:: set protocols mpls ldp import ipv4 import-filter filter-access-list + +.. cfgcmd:: set protocols mpls ldp import ipv6 import-filter filter-access-list6 + + + Use these commands to control the importing of forwarding equivalence classes + (FECs) for LDP from neighbors. This would be useful for example on only + accepting the labeled routes that are needed and not ones that are not + needed, such as accepting loopback interfaces and rejecting all others. +``` + +```{eval-rst} +.. cfgcmd:: set protocols mpls ldp export ipv4 export-filter filter-access-list + +.. cfgcmd:: set protocols mpls ldp export ipv6 export-filter filter-access-list6 + + + Use these commands to control the exporting of forwarding equivalence classes + (FECs) for LDP to neighbors. This would be useful for example on only + announcing the labeled routes that are needed and not ones that are not + needed, such as announcing loopback interfaces and no others. +``` + +```{eval-rst} +.. cfgcmd:: set protocols mpls ldp export ipv4 explicit-null +.. cfgcmd:: set protocols mpls ldp export ipv6 explicit-null + + Use this command if you would like for the router to advertise FECs with a + label of 0 for explicit null operations. +``` + +```{eval-rst} +.. cfgcmd:: set protocols mpls ldp allocation ipv4 access-list +.. cfgcmd:: set protocols mpls ldp allocation ipv6 access-list6 + + Use this command if you would like to control the local FEC allocations for + LDP. A good example would be for your local router to not allocate a label for + everything. Just a label for what it's useful. A good example would be just a + loopback label. +``` + +```{cfgcmd} set protocols mpls ldp parameters cisco-interop-tlv + +Use this command to use a Cisco non-compliant format to send and interpret +the Dual-Stack capability TLV for IPv6 LDP communications. This is related to +{rfc}`7552`. +``` + +```{cfgcmd} set protocols mpls ldp parameters ordered-control + +Use this command to use ordered label distribution control mode. FRR +by default uses independent label distribution control mode for label +distribution. This is related to {rfc}`5036`. +``` + +```{cfgcmd} set protocols mpls ldp parameters transport-prefer-ipv4 + +Use this command to prefer IPv4 for TCP peer transport connection for LDP +when both an IPv4 and IPv6 LDP address are configured on the same interface. +``` + +```{cfgcmd} set protocols mpls ldp targeted-neighbor ipv4 enable +``` + +```{cfgcmd} set protocols mpls ldp targeted-neighbor ipv6 enable + +Use this command to enable targeted LDP sessions to the local router. The +router will then respond to any sessions that are trying to connect to it that +are not a link local type of TCP connection. +``` + +```{cfgcmd} set protocols mpls ldp targeted-neighbor ipv4 address \ +``` + +```{cfgcmd} set protocols mpls ldp targeted-neighbor ipv6 address \ + +Use this command to enable the local router to try and connect with a targeted +LDP session to another router. +``` + +```{cfgcmd} set protocols mpls ldp targeted-neighbor ipv4 hello-holdtime \ +``` + +```{cfgcmd} set protocols mpls ldp targeted-neighbor ipv4 hello-interval \ +``` + +```{cfgcmd} set protocols mpls ldp targeted-neighbor ipv6 hello-holdtime \ +``` + +```{cfgcmd} set protocols mpls ldp targeted-neighbor ipv6 hello-interval \ + +Use these commands if you would like to set the discovery hello and hold time +parameters for the targeted LDP neighbors. +``` + +### Sample configuration to setup LDP on VyOS + +```none +set protocols ospf area 0 network '192.168.255.252/32' <--- Routing for loopback +set protocols ospf area 0 network '192.168.0.5/32' <--- Routing for an interface connecting to the network +set protocols ospf parameters router-id '192.168.255.252' <--- Router ID setting for OSPF +set protocols mpls interface 'eth1' <--- Enable MPLS for an interface connecting to network +set protocols mpls ldp discovery transport-ipv4-address '192.168.255.252' <--- Transport address for LDP for TCP sessions to connect to +set protocols mpls ldp interface 'eth1' <--- Enable LDP for an interface connecting to network +set protocols mpls ldp interface 'lo' <--- Enable LDP on loopback for future services connectivity +set protocols mpls ldp router-id '192.168.255.252' <--- Router ID setting for LDP +set interfaces ethernet eth1 address '192.168.0.5/31' <--- Interface IP for connecting to network +set interfaces loopback lo address '192.168.255.252/32' <--- Interface loopback IP for router ID and other uses +``` + +## Operational Mode Commands + +When LDP is working, you will be able to see label information in the outcome +of `show ip route`. Besides that information, there are also specific *show* +commands for LDP: + +### Show + +```{opcmd} show mpls ldp binding + +Use this command to see the Label Information Base. + +``` + +```{opcmd} show mpls ldp discovery + +Use this command to see discovery hello information +``` + +```{opcmd} show mpls ldp interface + +Use this command to see LDP interface information +``` + +```{opcmd} show mpls ldp neighbor + +Use this command to see LDP neighbor information +``` + +```{opcmd} show mpls ldp neighbor detail + +Use this command to see detailed LDP neighbor information +``` + +### Reset + +```{opcmd} reset mpls ldp neighbor \ + +Use this command to reset an LDP neighbor/TCP session that is established +``` + +[wikipedia (mpls)]: diff --git a/docs/configuration/protocols/md-multicast.md b/docs/configuration/protocols/md-multicast.md new file mode 100644 index 00000000..27150a29 --- /dev/null +++ b/docs/configuration/protocols/md-multicast.md @@ -0,0 +1,31 @@ +(routing-static)= + +# Multicast + +In order to influence Multicast {abbr}`RPF (Reverse Path Forwarding)` lookup, +it is possible to insert into zebra routes for the Multicast +{abbr}`RIB (Routing Information Base)`. These routes are only used for RPF +lookup and will not be used by ZEBRA for insertion into the kernel or for +normal RIB processing. As such it is possible to create weird states with +these commands. + +Use with caution. Most of the time this will not be necessary. + +```{cfgcmd} set protocols static mroute \ next-hop \ [distance \] + +Insert into the Multicast RIB Route `` with specified next-hop. +The distance can be specified as well if desired. +``` +```{cfgcmd} set protocols static mroute \ next-hop \ disable + +Do not install route for `` into the Multicast RIB. +``` +```{cfgcmd} set protocols static mroute \ interface \ [distance \] + +Insert into the Multicast RIB Route `` with specified ``. +The distance can be specified as well if desired. +``` +```{cfgcmd} set protocols static mroute \ interface \ disable + +Do not install route for `` into the Multicast RIB. +``` \ No newline at end of file diff --git a/docs/configuration/protocols/md-openfabric.md b/docs/configuration/protocols/md-openfabric.md new file mode 100644 index 00000000..09ff5900 --- /dev/null +++ b/docs/configuration/protocols/md-openfabric.md @@ -0,0 +1,242 @@ +(openfabric)= + +# OpenFabric + +OpenFabric, specified in [draft-white-openfabric-06.txt](https://datatracker.ietf.org/doc/html/draft-white-openfabric-06), is +a routing protocol derived from IS-IS, providing link-state routing with +efficient flooding for topologies like spine-leaf networks. + +OpenFabric a dual stack protocol. +A single OpenFabric instance is able to perform routing for both IPv4 and IPv6. + +## General + +### Configuration + +#### Mandatory Settings + +For OpenFabric to operate correctly, one must do the equivalent of a Router ID +in Connectionless Network Service (CLNS). This Router ID is called the +{abbr}`NET (Network Entity Title)`. The system identifier must be unique within +the network + +```{cfgcmd} set protocols openfabric net \ + +This command sets network entity title (NET) provided in ISO format. + +Here is an example {abbr}`NET (Network Entity Title)` value: + +:::{code-block} none +49.0001.1921.6800.1002.00 +::: +The CLNS address consists of the following parts: + +* {abbr}`AFI (Address family authority identifier)` - ``49`` The AFI value + 49 is what OpenFabric uses for private addressing. + +* Area identifier: ``0001`` OpenFabric area number (numerical area ``1``) + +* System identifier: ``1921.6800.1002`` - for system identifiers we recommend + to use IP address or MAC address of the router itself. The way to construct + this is to keep all of the zeroes of the router IP address, and then change + the periods from being every three numbers to every four numbers. The + address that is listed here is ``192.168.1.2``, which if expanded will turn + into ``192.168.001.002``. Then all one has to do is move the dots to have + four numbers instead of three. This gives us ``1921.6800.1002``. + +* {abbr}`NET (Network Entity Title)` selector: ``00`` Must always be 00. This + setting indicates "this system" or "local system." +``` + + +```{cfgcmd} set protocols openfabric domain \ interface \ address-family \ + +This command enables OpenFabric instance with \ on this interface, and +allows for adjacency to occur for address family (IPv4 or IPv6 or both). +``` + +#### OpenFabric Global Configuration + +```{cfgcmd} set protocols openfabric domain-password \ \ + +This command configures the authentication password for a routing domain, +as clear text or md5 one. +``` + + +```{cfgcmd} set protocols openfabric domain \ purge-originator + +This command enables {rfc}`6232` purge originator identification. +``` + + +```{cfgcmd} set protocols openfabric domain \ set-overload-bit + +This command sets overload bit to avoid any transit traffic through this +router. +``` + + +```{cfgcmd} set protocols openfabric domain \ log-adjacency-changes + +Log changes in adjacency state. +``` + + +```{cfgcmd} set protocols openfabric domain \ fabric-tier \ + +This command sets a static tier number to advertise as location +in the fabric. +``` + +#### Interface Configuration + +```{cfgcmd} set protocols openfabric interface \ hello-interval \ + +This command sets hello interval in seconds on a given interface. +The range is 1 to 600. Hello packets are used to establish and maintain +adjacency between OpenFabric neighbors. +``` + + +```{cfgcmd} set protocols openfabric domain \ interface \ hello-multiplier \ + +This command sets multiplier for hello holding time on a given +interface. The range is 2 to 100. +``` + + +```{cfgcmd} set protocols openfabric domain \ interface \ metric \ + +This command sets default metric for circuit. +The metric range is 1 to 16777215. +``` + + +```{cfgcmd} set protocols openfabric interface \ passive + +This command enables the passive mode for this interface. +``` + + +```{cfgcmd} set protocols openfabric domain \ interface \ password plaintext-password \ + +This command sets the authentication password for the interface. +``` + + +```{cfgcmd} set protocols openfabric domain \ interface \ csnp-interval \ + +This command sets Complete Sequence Number Packets (CSNP) interval in seconds. +The interval range is 1 to 600. +``` + + +```{cfgcmd} set protocols openfabric domain \ interface \ psnp-interval \ + +This command sets Partial Sequence Number Packets (PSNP) interval in seconds. +The interval range is 1 to 120. +``` + +#### Timers + +```{cfgcmd} set protocols openfabric domain \ lsp-gen-interval \ + +This command sets minimum interval at which link-state packets (LSPs) are +generated. The interval range is 1 to 120. +``` + + +```{cfgcmd} set protocols openfabric domain \ lsp-refresh-interval \ + +This command sets LSP refresh interval in seconds. The interval range +is 1 to 65235. +``` + + +```{cfgcmd} set protocols openfabric domain \ max-lsp-lifetime \ + +This command sets LSP maximum LSP lifetime in seconds. The interval range +is 360 to 65535. LSPs remain in a database for 1200 seconds by default. +If they are not refreshed by that time, they are deleted. You can change +the LSP refresh interval or the LSP lifetime. The LSP refresh interval +should be less than the LSP lifetime or else LSPs will time out before +they are refreshed. +``` + + +```{cfgcmd} set protocols openfabric domain \ spf-interval \ + +This command sets minimum interval between consecutive shortest path first +(SPF) calculations in seconds.The interval range is 1 to 120. +``` + +## Examples +### Enable OpenFabric + +**Node 1:** + +```none +set interfaces loopback lo address '192.168.255.255/32' +set interfaces ethernet eth1 address '192.0.2.1/24' + +set protocols openfabric domain VyOS interface eth1 address-family ipv4 +set protocols openfabric domain VyOS interface lo address-family ipv4 +set protocols openfabric net '49.0001.1921.6825.5255.00' +``` + +**Node 2:** + +```none +set interfaces loopback lo address '192.168.255.254/32' +set interfaces ethernet eth1 address '192.0.2.2/24' + +set protocols openfabric domain VyOS interface eth1 address-family ipv4 +set protocols openfabric domain VyOS interface lo address-family ipv4 +set protocols openfabric net '49.0001.1921.6825.5254.00' +``` + +This gives us the following neighborships: + +```none +Node-1@vyos:~$ show openfabric neighbor +show openfabric neighbor +Area VyOS: + System Id Interface L State Holdtime SNPA + vyos eth1 2 Up 27 2020.2020.2020 + + +Node-2@vyos:~$ show openfabric neighbor +show openfabric neighbor +Area VyOS: + System Id Interface L State Holdtime SNPA + vyos eth1 2 Up 30 2020.2020.2020 +``` + +Here's the IP routes that are populated: + +```none +Node-1@vyos:~$ show ip route openfabric +show ip route openfabric +Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, + f - OpenFabric, + > - selected route, * - FIB route, q - queued, r - rejected, b - backup + t - trapped, o - offload failure + +f 192.0.2.0/24 [115/20] via 192.0.2.2, eth1 onlink, weight 1, 00:00:10 +f>* 192.168.255.254/32 [115/20] via 192.0.2.2, eth1 onlink, weight 1, 00:00:10 + +Node-2@vyos:~$ show ip route openfabric +show ip route openfabric +Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, + f - OpenFabric, + > - selected route, * - FIB route, q - queued, r - rejected, b - backup + t - trapped, o - offload failure + +f 192.0.2.0/24 [115/20] via 192.0.2.1, eth1 onlink, weight 1, 00:00:48 +f>* 192.168.255.255/32 [115/20] via 192.0.2.1, eth1 onlink, weight 1, 00:00:48 +``` diff --git a/docs/configuration/protocols/md-ospf.md b/docs/configuration/protocols/md-ospf.md new file mode 100644 index 00000000..72fefb84 --- /dev/null +++ b/docs/configuration/protocols/md-ospf.md @@ -0,0 +1,1504 @@ +(routing-ospf)= + +# OSPF + +{abbr}`OSPF (Open Shortest Path First)` is a routing protocol for Internet +Protocol (IP) networks. It uses a link state routing (LSR) algorithm and falls +into the group of interior gateway protocols (IGPs), operating within a single +autonomous system (AS). It is defined as OSPF Version 2 in {rfc}`2328` (1998) +for IPv4. Updates for IPv6 are specified as OSPF Version 3 in {rfc}`5340` +(2008). OSPF supports the {abbr}`CIDR (Classless Inter-Domain Routing)` +addressing model. + +OSPF is a widely used IGP in large enterprise networks. + +## OSPFv2 (IPv4) + +### Configuration + +#### General + +VyOS does not have a special command to start the OSPF process. The OSPF process +starts when the first ospf enabled interface is configured. + +```{cfgcmd} set protocols ospf area \ network \ + + This command specifies the OSPF enabled interface(s). If the interface has + an address from defined range then the command enables OSPF on this + interface so router can provide network information to the other ospf + routers via this interface. + + This command is also used to enable the OSPF process. The area number can be + specified in decimal notation in the range from 0 to 4294967295. Or it + can be specified in dotted decimal notation similar to ip address. + + Prefix length in interface must be equal or bigger (i.e. smaller network) + than prefix length in network statement. For example statement above doesn't + enable ospf on interface with address 192.168.1.1/23, but it does on + interface with address 192.168.1.129/25. + + In some cases it may be more convenient to enable OSPF on a per + interface/subnet + basis {cfgcmd}`set protocols ospf interface area ` +``` + + +```{cfgcmd} set protocols ospf auto-cost reference-bandwidth \ + +This command sets the reference bandwidth for cost calculations, where +bandwidth can be in range from 1 to 4294967, specified in Mbits/s. The +default is 100Mbit/s (i.e. a link of bandwidth 100Mbit/s or higher will +have a cost of 1. Cost of lower bandwidth links will be scaled with +reference to this cost). +``` + + +```{cfgcmd} set protocols ospf parameters router-id \ + +This command sets the router-ID of the OSPF process. The router-ID may be an +IP address of the router, but need not be – it can be any arbitrary 32bit +number. However it MUST be unique within the entire OSPF domain to the OSPF +speaker – bad things will happen if multiple OSPF speakers are configured +with the same router-ID! +``` + +#### Optional + +```{cfgcmd} set protocols ospf default-information originate [always] [metric \] [metric-type \<1|2\>] [route-map \] + +Originate an AS-External (type-5) LSA describing a default route into all +external-routing capable areas, of the specified metric and metric type. +If the {cfgcmd}`always` keyword is given then the default is always +advertised, even when there is no default present in the routing table. +The argument {cfgcmd}`route-map` specifies to advertise the default route +if the route map is satisfied. +``` + + +```{cfgcmd} set protocols ospf distance global \ + +This command change distance value of OSPF globally. +The distance range is 1 to 255. +``` + + +```{cfgcmd} set protocols ospf distance ospf \ \ + +This command change distance value of OSPF. The arguments are the distance +values for external routes, inter-area routes and intra-area routes +respectively. The distance range is 1 to 255. + +:::{note} +Routes with a distance of 255 are effectively disabled and not +installed into the kernel. +::: +``` + + +```{cfgcmd} set protocols ospf log-adjacency-changes [detail] + +This command allows to log changes in adjacency. With the optional +{cfgcmd}`detail` argument, all changes in adjacency status are shown. +Without {cfgcmd}`detail`, only changes to full or regressions are shown. +``` + + +```{cfgcmd} set protocols ospf max-metric router-lsa \|on-startup \> + +This enables {rfc}`3137` support, where the OSPF process describes its +transit links in its router-LSA as having infinite distance so that other +routers will avoid calculating transit paths through the router while +still being able to reach networks through the router. + +This support may be enabled administratively (and indefinitely) with the +{cfgcmd}`administrative` command. It may also be enabled conditionally. +Conditional enabling of max-metric router-lsas can be for a period of +seconds after startup with the {cfgcmd}`on-startup ` command +and/or for a period of seconds prior to shutdown with the +{cfgcmd}`on-shutdown ` command. The time range is 5 to 86400. +``` + + +```{cfgcmd} set protocols ospf parameters abr-type \ + +This command selects ABR model. OSPF router supports four ABR models: + +**cisco** – a router will be considered as ABR if it has several configured +links to the networks in different areas one of which is a backbone area. +Moreover, the link to the backbone area should be active (working). +**ibm** – identical to "cisco" model but in this case a backbone area link +may not be active. +**standard** – router has several active links to different areas. +**shortcut** – identical to "standard" but in this model a router is +allowed to use a connected areas topology without involving a backbone +area for inter-area connections. + +Detailed information about "cisco" and "ibm" models differences can be +found in {rfc}`3509`. A "shortcut" model allows ABR to create routes +between areas based on the topology of the areas connected to this router +but not using a backbone area in case if non-backbone route will be +cheaper. For more information about "shortcut" model, +see ospf-shortcut-abr-02.txt +``` + + +```{cfgcmd} set protocols ospf parameters rfc1583-compatibility + +{rfc}`2328`, the successor to {rfc}`1583`, suggests according to section +G.2 (changes) in section 16.4.1 a change to the path preference algorithm +that prevents possible routing loops that were possible in the old version +of OSPFv2. More specifically it demands that inter-area paths and +intra-area backbone path are now of equal preference but still both +preferred to external paths. + +This command should NOT be set normally. +``` + + +```{cfgcmd} set protocols ospf interface \ passive [disable] + +This command specifies interface as passive. Passive interface advertises +its address, but does not run the OSPF protocol (adjacencies are not formed +and hello packets are not generated). + +The optional disable option allows to exclude interface from passive state. +This command is used if the command {cfgcmd}`passive-interface default` was +configured. +``` + + +```{cfgcmd} set protocols ospf passive-interface default + +This command specifies all interfaces as passive by default. Because this +command changes the configuration logic to a default passive; therefore, +interfaces where router adjacencies are expected need to be configured +with the {cfgcmd}`passive-interface-exclude` command. +``` + + +```{cfgcmd} set protocols ospf maximum-paths \<1-64\> + +Use this command to control the maximum number of equal cost paths to reach +a specific destination. The upper limit may differ if you change the value +of MULTIPATH_NUM during compilation. The default is MULTIPATH_NUM (64). +``` + + +```{cfgcmd} set protocols ospf refresh timers \ + +The router automatically updates link-state information with its neighbors. +Only an obsolete information is updated which age has exceeded a specific +threshold. This parameter changes a threshold value, which by default is +1800 seconds (half an hour). The value is applied to the whole OSPF router. +The timer range is 10 to 1800. +``` + + +```{cfgcmd} set protocols ospf timers throttle spf \ \ + +This command sets the initial delay, the initial-holdtime and the +maximum-holdtime between when SPF is calculated and the event which +triggered the calculation. The times are specified in milliseconds and must +be in the range of 0 to 600000 milliseconds. {cfgcmd}`delay` sets the +initial SPF schedule delay in milliseconds. The default value is 200 ms. +{cfgcmd}`initial-holdtime` sets the minimum hold time between two +consecutive SPF calculations. The default value is 1000 ms. +{cfgcmd}`max-holdtime` sets the maximum wait time between two +consecutive SPF calculations. The default value is 10000 ms. +``` + + +```{cfgcmd} set protocols ospf ldp-sync + +This command will enable IGP-LDP synchronization globally for OSPF. This +requires for LDP to be functional. This is described in {rfc}`5443`. By +default all interfaces operational in OSPF are enabled for synchronization. +Loopbacks are exempt. +``` + + +```{cfgcmd} set protocols ospf ldp-sync holddown \ + +This command will change the hold down value globally for IGP-LDP +synchronization during convergence/interface flap events. +``` + + +```{cfgcmd} set protocols ospf capability opaque + +ospfd supports Opaque LSA {rfc}`2370` as partial support for MPLS Traffic +Engineering LSAs. The opaque-lsa capability must be enabled in the +configuration. + +An alternate command could be "mpls-te on" (Traffic Engineering) + +:::{note} +FRR offers only partial support for some of the routing +protocol extensions that are used with MPLS-TE; it does not +support a complete RSVP-TE solution. +::: +``` + +#### Area Configuration + +```{cfgcmd} set protocols ospf area \ area-type stub + +This command specifies the area to be a Stub Area. That is, an area where +no router originates routes external to OSPF and hence an area where all +external routes are via the ABR(s). Hence, ABRs for such an area do not +need to pass AS-External LSAs (type-5) or ASBR-Summary LSAs (type-4) into +the area. They need only pass Network-Summary (type-3) LSAs into such an +area, along with a default-route summary. +``` + + +```{cfgcmd} set protocols ospf area \ area-type stub no-summary + +This command specifies the area to be a Totally Stub Area. In addition to +stub area limitations this area type prevents an ABR from injecting +Network-Summary (type-3) LSAs into the specified stub area. Only default +summary route is allowed. +``` + + +```{cfgcmd} set protocols ospf area \ area-type stub default-cost \ + +This command sets the cost of default-summary LSAs announced to stubby +areas. The cost range is 0 to 16777215. +``` + + +```{cfgcmd} set protocols ospf area \ area-type nssa + +This command specifies the area to be a Not So Stubby Area. External +routing information is imported into an NSSA in Type-7 LSAs. Type-7 LSAs +are similar to Type-5 AS-external LSAs, except that they can only be +flooded into the NSSA. In order to further propagate the NSSA external +information, the Type-7 LSA must be translated to a Type-5 AS-external-LSA +by the NSSA ABR. +``` + + +```{cfgcmd} set protocols ospf area \ area-type nssa no-summary + +This command specifies the area to be a NSSA Totally Stub Area. ABRs for +such an area do not need to pass Network-Summary (type-3) LSAs (except the +default summary route), ASBR-Summary LSAs (type-4) and AS-External LSAs +(type-5) into the area. But Type-7 LSAs that convert to Type-5 at the NSSA +ABR are allowed. +``` + + +```{cfgcmd} set protocols ospf area \ area-type nssa default-cost \ + +This command sets the default cost of LSAs announced to NSSA areas. +The cost range is 0 to 16777215. +``` + + +```{cfgcmd} set protocols ospf area \ area-type nssa translate \ + +Specifies whether this NSSA border router will unconditionally translate +Type-7 LSAs into Type-5 LSAs. When role is Always, Type-7 LSAs are +translated into Type-5 LSAs regardless of the translator state of other +NSSA border routers. When role is Candidate, this router participates in +the translator election to determine if it will perform the translations +duties. When role is Never, this router will never translate Type-7 LSAs +into Type-5 LSAs. +``` + + +```{cfgcmd} set protocols ospf area \ authentication plaintext-password + +This command specifies that simple password authentication should be used +for the given area. The password must also be configured on a per-interface +basis. +``` + + +```{cfgcmd} set protocols ospf area \ authentication md5 + +This command specify that OSPF packets must be authenticated with MD5 HMACs +within the given area. Keying material must also be configured on a +per-interface basis. +``` + + +```{cfgcmd} set protocols ospf area \ range \ [cost \] + +This command summarizes intra area paths from specified area into one +summary-LSA (Type-3) announced to other areas. This command can be used +only in ABR and ONLY router-LSAs (Type-1) and network-LSAs (Type-2) +(i.e. LSAs with scope area) can be summarized. AS-external-LSAs (Type-5) +can’t be summarized - their scope is AS. The optional argument +{cfgcmd}`cost` specifies the aggregated link metric. The metric range is 0 +to 16777215. +``` + + +```{cfgcmd} set protocols ospf area \ range \ not-advertise + +This command instead of summarizing intra area paths filter them - i.e. +intra area paths from this range are not advertised into other areas. +This command makes sense in ABR only. +``` + + +```{cfgcmd} set protocols ospf area \ export-list \ + +Filter Type-3 summary-LSAs announced to other areas originated from +intra- area paths from specified area. +This command makes sense in ABR only. +``` + + +```{cfgcmd} set protocols ospf area \ import-list \ + +Same as export-list, but it applies to paths announced into specified +area as Type-3 summary-LSAs. +This command makes sense in ABR only. +``` + + +```{cfgcmd} set protocols ospf area \ range \ substitute \ + +One Type-3 summary-LSA with routing info is announced into +backbone area if defined area contains at least one intra-area network +(i.e. described with router-LSA or network-LSA) from range . +This command makes sense in ABR only. +``` + + +```{cfgcmd} set protocols ospf area \ shortcut \ + +This parameter allows to "shortcut" routes (non-backbone) for inter-area +routes. There are three modes available for routes shortcutting: + +**default** – this area will be used for shortcutting only if ABR does not +have a link to the backbone area or this link was lost. +**enable** – the area will be used for shortcutting every time the route +that goes through it is cheaper. +**disable** – this area is never used by ABR for routes shortcutting. +``` + + +```{cfgcmd} set protocols ospf area \ virtual-link \ + +Provides a backbone area coherence by virtual link establishment. + +In general, OSPF protocol requires a backbone area (area 0) to be coherent +and fully connected. I.e. any backbone area router must have a route to any +other backbone area router. Moreover, every ABR must have a link to +backbone area. However, it is not always possible to have a physical link +to a backbone area. In this case between two ABR (one of them has a link to +the backbone area) in the area (not stub area) a virtual link is organized. + +\ – area identifier through which a virtual link goes. +\ – ABR router-id with which a virtual link is established. Virtual +link must be configured on both routers. + +Formally, a virtual link looks like a point-to-point network connecting two +ABR from one area one of which physically connected to a backbone area. +This pseudo-network is considered to belong to a backbone area. +``` + +#### Interface Configuration + +```{cfgcmd} set protocols ospf interface \ area \ + + Enable ospf on an interface and set associated area. + + If you have a lot of interfaces, and/or a lot of subnets, then enabling + OSPF via this command may result in a slight performance improvement. +``` + + +```{cfgcmd} set protocols ospf interface \ authentication plaintext-password \ + +This command sets OSPF authentication key to a simple password. After +setting, all OSPF packets are authenticated. Key has length up to 8 chars. + +Simple text password authentication is insecure and deprecated in favour of +MD5 HMAC authentication. +``` + + +```{cfgcmd} set protocols ospf interface \ authentication md5 key-id \ md5-key \ + +This command specifys that MD5 HMAC authentication must be used on this +interface. It sets OSPF authentication key to a cryptographic password. +Key-id identifies secret key used to create the message digest. This ID +is part of the protocol and must be consistent across routers on a link. +The key can be long up to 16 chars (larger strings will be truncated), +and is associated with the given key-id. +``` + + +```{cfgcmd} set protocols ospf interface \ bandwidth \ + +This command sets the interface bandwidth for cost calculations, where +bandwidth can be in range from 1 to 100000, specified in Mbits/s. +``` + + +```{cfgcmd} set protocols ospf interface \ cost \ + +This command sets link cost for the specified interface. The cost value is +set to router-LSA’s metric field and used for SPF calculation. The cost +range is 1 to 65535. +``` + + +```{cfgcmd} set protocols ospf interface \ dead-interval \ + +Set number of seconds for router Dead Interval timer value used for Wait +Timer and Inactivity Timer. This value must be the same for all routers +attached to a common network. The default value is 40 seconds. The +interval range is 1 to 65535. +``` + + +```{cfgcmd} set protocols ospf interface \ hello-multiplier \ + +The hello-multiplier specifies how many Hellos to send per second, from 1 +(every second) to 10 (every 100ms). Thus one can have 1s convergence time +for OSPF. If this form is specified, then the hello-interval advertised in +Hello packets is set to 0 and the hello-interval on received Hello packets +is not checked, thus the hello-multiplier need NOT be the same across +multiple routers on a common link. +``` + + +```{cfgcmd} set protocols ospf interface \ hello-interval \ + +Set number of seconds for Hello Interval timer value. Setting this value, +Hello packet will be sent every timer value seconds on the specified +interface. This value must be the same for all routers attached to a +common network. The default value is 10 seconds. The interval range is 1 +to 65535. +``` + + +```{cfgcmd} set protocols ospf interface \ bfd + +This command enables {abbr}`BFD (Bidirectional Forwarding Detection)` on +this OSPF link interface. +``` + + +```{cfgcmd} set protocols ospf interface \ mtu-ignore + +This command disables check of the MTU value in the OSPF DBD packets. Thus, +use of this command allows the OSPF adjacency to reach the FULL state even +though there is an interface MTU mismatch between two OSPF routers. +``` + + +```{cfgcmd} set protocols ospf interface \ network \ + +This command allows to specify the distribution type for the network +connected to this interface: + +**broadcast** – broadcast IP addresses distribution. +**non-broadcast** – address distribution in NBMA networks topology. +**point-to-multipoint** – address distribution in point-to-multipoint +networks. +**point-to-point** – address distribution in point-to-point networks. +``` + + +```{cfgcmd} set protocols ospf interface \ priority \ + +This command sets Router Priority integer value. The router with the +highest priority will be more eligible to become Designated Router. +Setting the value to 0, makes the router ineligible to become +Designated Router. The default value is 1. The interval range is 0 to 255. +``` + + +```{cfgcmd} set protocols ospf interface \ retransmit-interval \ + +This command sets number of seconds for RxmtInterval timer value. This +value is used when retransmitting Database Description and Link State +Request packets if acknowledge was not received. The default value is 5 +seconds. The interval range is 3 to 65535. +``` + + +```{cfgcmd} set protocols ospf interface \ transmit-delay \ + +This command sets number of seconds for InfTransDelay value. It allows to +set and adjust for each interface the delay interval before starting the +synchronizing process of the router's database with all neighbors. The +default value is 1 seconds. The interval range is 3 to 65535. +``` + + +```{cfgcmd} set protocols ospf interface \ ldp-sync disable + +This command disables IGP-LDP sync for this specific interface. +``` + + +```{cfgcmd} set protocols ospf interface \ ldp-sync holddown \ + +This command will change the hold down value for IGP-LDP synchronization +during convergence/interface flap events, but for this interface only. +``` + +#### External Route Summarisation + + +This feature summarises originated external LSAs (Type-5 and Type-7). Summary +Route will be originated on-behalf of all matched external LSAs. + +```{cfgcmd} set protocols ospf aggregation timer \ + +Configure aggregation delay timer interval. + +Summarisation starts only after this delay timer expiry. +``` + + +```{cfgcmd} set protocols ospf summary-address x.x.x.x/y [tag (1-4294967295)] + +This command enable/disables summarisation for the configured address range. + +Tag is the optional parameter. If tag configured Summary route will be +originated with the configured tag. +``` + + +```{cfgcmd} set protocols ospf summary-address x.x.x.x/y no-advertise + +This command to ensure not advertise the summary lsa for the matched +external LSAs. +``` + +#### Graceful Restart + +```{cfgcmd} set protocols ospf graceful-restart [grace-period (1-1800)] + +Configure Graceful Restart {rfc}`3623` restarting support. When enabled, +the default grace period is 120 seconds. + +To perform a graceful shutdown, the FRR ``graceful-restart prepare ip +ospf`` EXEC-level command needs to be issued before restarting the +ospfd daemon. +``` + + +```{cfgcmd} set protocols ospf graceful-restart helper enable [router-id A.B.C.D] + +Configure Graceful Restart {rfc}`3623` helper support. By default, helper support +is disabled for all neighbours. This config enables/disables helper support +on this router for all neighbours. + +To enable/disable helper support for a specific neighbour, the router-id +(A.B.C.D) has to be specified. +``` + + +```{cfgcmd} set protocols ospf graceful-restart helper no-strict-lsa-checking + +By default strict-lsa-checking is configured then the helper will abort +the Graceful Restart when a LSA change occurs which affects the restarting +router. + +This command disables it. +``` + + +```{cfgcmd} set protocols ospf graceful-restart helper supported-grace-time + +Supports as HELPER for configured grace period. +``` + + +```{cfgcmd} set protocols ospf graceful-restart helper planned-only + +It helps to support as HELPER only for planned restarts. + +By default, it supports both planned and unplanned outages. +``` + +#### Manual Neighbor Configuration + + +OSPF routing devices normally discover their neighbors dynamically by +listening to the broadcast or multicast hello packets on the network. +Because an NBMA network does not support broadcast (or multicast), the +device cannot discover its neighbors dynamically, so you must configure all +the neighbors statically. + +```{cfgcmd} set protocols ospf neighbor \ + +This command specifies the IP address of the neighboring device. +``` + + +```{cfgcmd} set protocols ospf neighbor \ poll-interval \ + +This command specifies the length of time, in seconds, before the routing +device sends hello packets out of the interface before it establishes +adjacency with a neighbor. The range is 1 to 65535 seconds. The default +value is 60 seconds. +``` + + +```{cfgcmd} set protocols ospf neighbor \ priority \ + +This command specifies the router priority value of the nonbroadcast +neighbor associated with the IP address specified. The default is 0. +This keyword does not apply to point-to-multipoint interfaces. +``` + +#### Redistribution Configuration + +```{cfgcmd} set protocols ospf redistribute \ + + This command redistributes routing information from the given route source + to the OSPF process. There are five modes available for route source: bgp, + connected, kernel, rip, static. +``` + + +```{cfgcmd} set protocols ospf default-metric \ + +This command specifies the default metric value of redistributed routes. +The metric range is 0 to 16777214. +``` + + +```{cfgcmd} set protocols ospf redistribute \ metric \ + +This command specifies metric for redistributed routes from the given +route source. There are five modes available for route source: bgp, +connected, kernel, rip, static. The metric range is 1 to 16777214. +``` + + +```{cfgcmd} set protocols ospf redistribute \ metric-type \<1|2\> + +This command specifies metric type for redistributed routes. Difference +between two metric types that metric type 1 is a metric which is +"commensurable" with inner OSPF links. When calculating a metric to the +external destination, the full path metric is calculated as a metric sum +path of a router which had advertised this link plus the link metric. +Thus, a route with the least summary metric will be selected. If external +link is advertised with metric type 2 the path is selected which lies +through the router which advertised this link with the least metric +despite of the fact that internal path to this router is longer (with more +cost). However, if two routers advertised an external link and with metric +type 2 the preference is given to the path which lies through the router +with a shorter internal path. If two different routers advertised two +links to the same external destimation but with different metric type, +metric type 1 is preferred. If type of a metric left undefined the router +will consider these external links to have a default metric type 2. +``` + + +```{cfgcmd} set protocols ospf redistribute \ route-map \ + +This command allows to use route map to filter redistributed routes from +the given route source. There are five modes available for route source: +bgp, connected, kernel, rip, static. +``` + +#### Operational Mode Commands + +```{opcmd} show ip ospf neighbor + + This command displays the neighbors status. +``` + + +```none +Neighbor ID Pri State Dead Time Address Interface RXmtL RqstL DBsmL +10.0.13.1 1 Full/DR 38.365s 10.0.13.1 eth0:10.0.13.3 0 0 0 +10.0.23.2 1 Full/Backup 39.175s 10.0.23.2 eth1:10.0.23.3 0 0 0 +``` + + +```{opcmd} show ip ospf neighbor detail + +This command displays the neighbors information in a detailed form, not +just a summary table. +``` + + +```none + Neighbor 10.0.13.1, interface address 10.0.13.1 + + In the area 0.0.0.0 via interface eth0 + + Neighbor priority is 1, State is Full, 5 state changes + + Most recent state change statistics: + + Progressive change 11m55s ago + + DR is 10.0.13.1, BDR is 10.0.13.3 + + Options 2 *|-|-|-|-|-|E|- + + Dead timer due in 34.854s + + Database Summary List 0 + + Link State Request List 0 + + Link State Retransmission List 0 + + Thread Inactivity Timer on + + Thread Database Description Retransmision off + + Thread Link State Request Retransmission on + + Thread Link State Update Retransmission on + + +Neighbor 10.0.23.2, interface address 10.0.23.2 + + In the area 0.0.0.1 via interface eth1 + + Neighbor priority is 1, State is Full, 4 state changes + + Most recent state change statistics: + + Progressive change 41.193s ago + + DR is 10.0.23.3, BDR is 10.0.23.2 + + Options 2 *|-|-|-|-|-|E|- + + Dead timer due in 35.661s + + Database Summary List 0 + + Link State Request List 0 + + Link State Retransmission List 0 + + Thread Inactivity Timer on + + Thread Database Description Retransmision off + + Thread Link State Request Retransmission on + + Thread Link State Update Retransmission on +``` + + +```{opcmd} show ip ospf neighbor \ + +This command displays the neighbors information in a detailed form for a +neighbor whose IP address is specified. +``` + + +```{opcmd} show ip ospf neighbor \ + +This command displays the neighbors status for a neighbor on the specified +interface. +``` + + +```{opcmd} show ip ospf interface [\] + +This command displays state and configuration of OSPF the specified +interface, or all interfaces if no interface is given. +``` + + +```none +eth0 is up + ifindex 2, MTU 1500 bytes, BW 4294967295 Mbit + Internet Address 10.0.13.3/24, Broadcast 10.0.13.255, Area 0.0.0.0 + MTU mismatch detection: enabled + Router ID 10.0.23.3, Network Type BROADCAST, Cost: 1 + Transmit Delay is 1 sec, State Backup, Priority 1 + Backup Designated Router (ID) 10.0.23.3, Interface Address 10.0.13.3 + Multicast group memberships: OSPFAllRouters OSPFDesignatedRouters + Timer intervals configured, Hello 10s, Dead 40s, Wait 40s, Retransmit 5 + Hello due in 4.470s + Neighbor Count is 1, Adjacent neighbor count is 1 +eth1 is up + ifindex 3, MTU 1500 bytes, BW 4294967295 Mbit + Internet Address 10.0.23.3/24, Broadcast 10.0.23.255, Area 0.0.0.1 + MTU mismatch detection: enabled + Router ID 10.0.23.3, Network Type BROADCAST, Cost: 1 + Transmit Delay is 1 sec, State DR, Priority 1 + Backup Designated Router (ID) 10.0.23.2, Interface Address 10.0.23.2 + Saved Network-LSA sequence number 0x80000002 + Multicast group memberships: OSPFAllRouters OSPFDesignatedRouters + Timer intervals configured, Hello 10s, Dead 40s, Wait 40s, Retransmit 5 + Hello due in 4.563s + Neighbor Count is 1, Adjacent neighbor count is 1 +``` + + +```{opcmd} show ip ospf route [detail] + +This command displays the OSPF routing table, as determined by the most +recent SPF calculation. With the optional {cfgcmd}`detail` argument, +each route item's advertiser router and network attribute will be shown. +``` + + +```none +============ OSPF network routing table ============ +N IA 10.0.12.0/24 [3] area: 0.0.0.0 + via 10.0.13.3, eth0 +N 10.0.13.0/24 [1] area: 0.0.0.0 + directly attached to eth0 +N IA 10.0.23.0/24 [2] area: 0.0.0.0 + via 10.0.13.3, eth0 +N 10.0.34.0/24 [2] area: 0.0.0.0 + via 10.0.13.3, eth0 + +============ OSPF router routing table ============= +R 10.0.23.3 [1] area: 0.0.0.0, ABR + via 10.0.13.3, eth0 +R 10.0.34.4 [2] area: 0.0.0.0, ASBR + via 10.0.13.3, eth0 + +============ OSPF external routing table =========== +N E2 172.16.0.0/24 [2/20] tag: 0 + via 10.0.13.3, eth0 +``` + +The table consists of following data: + + +**OSPF network routing table** – includes a list of acquired routes for all +accessible networks (or aggregated area ranges) of OSPF system. "IA" flag +means that route destination is in the area to which the router is not +connected, i.e. it’s an inter-area path. In square brackets a summary metric +for all links through which a path lies to this network is specified. "via" +prefix defines a router-gateway, i.e. the first router on the way to the +destination (next hop). +**OSPF router routing table** – includes a list of acquired routes to all +accessible ABRs and ASBRs. +**OSPF external routing table** – includes a list of acquired routes that are +external to the OSPF process. "E" flag points to the external link metric type +(E1 – metric type 1, E2 – metric type 2). External link metric is printed in +the "\/\" format. + +```{opcmd} show ip ospf border-routers + +This command displays a table of paths to area boundary and autonomous +system boundary routers. +``` + + +```{opcmd} show ip ospf database + +This command displays a summary table with a database contents (LSA). +``` + + +```none + OSPF Router with ID (10.0.13.1) + + Router Link States (Area 0.0.0.0) + +Link ID ADV Router Age Seq# CkSum Link count +10.0.13.1 10.0.13.1 984 0x80000005 0xd915 1 +10.0.23.3 10.0.23.3 1186 0x80000008 0xfe62 2 +10.0.34.4 10.0.34.4 1063 0x80000004 0x4e3f 1 + + Net Link States (Area 0.0.0.0) + +Link ID ADV Router Age Seq# CkSum +10.0.13.1 10.0.13.1 994 0x80000003 0x30bb +10.0.34.4 10.0.34.4 1188 0x80000001 0x9411 + + Summary Link States (Area 0.0.0.0) + +Link ID ADV Router Age Seq# CkSum Route +10.0.12.0 10.0.23.3 1608 0x80000001 0x6ab6 10.0.12.0/24 +10.0.23.0 10.0.23.3 981 0x80000003 0xe232 10.0.23.0/24 + + AS External Link States + +Link ID ADV Router Age Seq# CkSum Route +172.16.0.0 10.0.34.4 1063 0x80000001 0xc40d E2 172.16.0.0/24 [0x0] +``` + + +```{opcmd} show ip ospf database \ [A.B.C.D] [adv-router \|self-originate] + + This command displays a database contents for a specific link advertisement + type. + + The type can be the following: + asbr-summary, external, network, nssa-external, opaque-area, opaque-as, + opaque-link, router, summary. + + [A.B.C.D] – link-state-id. With this specified the command displays portion + of the network environment that is being described by the advertisement. + The value entered depends on the advertisement’s LS type. It must be + entered in the form of an IP address. + + {cfgcmd}`adv-router ` – router id, which link advertisements need + to be reviewed. + + {cfgcmd}`self-originate` displays only self-originated LSAs from the local + router. +``` + + +```none + OSPF Router with ID (10.0.13.1) + + Router Link States (Area 0.0.0.0) + +LS age: 1213 +Options: 0x2 : *|-|-|-|-|-|E|- +LS Flags: 0x3 +Flags: 0x0 +LS Type: router-LSA +Link State ID: 10.0.13.1 +Advertising Router: 10.0.13.1 +LS Seq Number: 80000009 +Checksum: 0xd119 +Length: 36 + + Number of Links: 1 + + Link connected to: a Transit Network + (Link ID) Designated Router address: 10.0.13.1 + (Link Data) Router Interface address: 10.0.13.1 + Number of TOS metrics: 0 + TOS 0 Metric: 1 +``` + + +```{opcmd} show ip ospf database max-age + +This command displays LSAs in MaxAge list. +``` + +#### Examples +### Enable OSPF + +**Node 1** + +```none +set interfaces loopback lo address 10.1.1.1/32 +set interfaces ethernet eth0 address 192.168.0.1/24 +set protocols ospf area 0 network 192.168.0.0/24 +set protocols ospf area 0 network 10.1.1.1/32 +set protocols ospf parameters router-id 10.1.1.1 +``` + +**Node 2** + +```none +set interfaces loopback lo address 10.1.1.2/32 +set interfaces ethernet eth0 address 192.168.0.2/24 +set protocols ospf area 0 network 192.168.0.0/24 +set protocols ospf area 0 network 10.1.1.2/32 +set protocols ospf parameters router-id 10.1.1.2 +``` + +Here's the neighbors up: + +```none +Node-1@vyos:~$ show ip ospf neighbor + +Neighbor ID Pri State Up Time Dead Time Address Interface RXmtL RqstL DBsmL +10.1.1.2 1 Full/DR 3m43s 36.094s 192.168.0.2 eth0:192.168.0.1 0 0 0 + + +Node-2@vyos:~$ show ip ospf neighbor + +Neighbor ID Pri State Up Time Dead Time Address Interface RXmtL RqstL DBsmL +10.1.1.1 1 Full/Backup 3m47s 31.736s 192.168.0.1 eth0:192.168.0.2 0 0 0 +``` + +Here's the routes: + +```none +Node-1@vyos:~$ show ip route ospf +Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, + f - OpenFabric, + > - selected route, * - FIB route, q - queued, r - rejected, b - backup + t - trapped, o - offload failure + +O 10.1.1.1/32 [110/0] is directly connected, lo, weight 1, 00:00:14 +O>* 10.1.1.2/32 [110/1] via 192.168.0.2, eth0, weight 1, 00:00:07 +O 192.168.0.0/24 [110/1] is directly connected, eth0, weight 1, 00:03:32 + +Node-2@vyos:~$ show ip route ospf +Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, + f - OpenFabric, + > - selected route, * - FIB route, q - queued, r - rejected, b - backup + t - trapped, o - offload failure + +O>* 10.1.1.1/32 [110/1] via 192.168.0.1, eth0, weight 1, 00:00:11 +O 10.1.1.2/32 [110/0] is directly connected, lo, weight 1, 00:00:04 +O 192.168.0.0/24 [110/1] is directly connected, eth0, weight 1, 00:03:18 +``` + +### Enable OSPF with route redistribution of the loopback and default originate: + +**Node 1** + +```none +set interfaces loopback lo address 10.1.1.1/32 +set protocols ospf area 0 network 192.168.0.0/24 +set protocols ospf default-information originate always +set protocols ospf default-information originate metric 10 +set protocols ospf default-information originate metric-type 2 +set protocols ospf log-adjacency-changes +set protocols ospf parameters router-id 10.1.1.1 +set protocols ospf redistribute connected metric-type 2 +set protocols ospf redistribute connected route-map CONNECT + +set policy route-map CONNECT rule 10 action permit +set policy route-map CONNECT rule 10 match interface lo +``` + +**Node 2** + +```none +set interfaces loopback lo address 10.2.2.2/32 +set protocols ospf area 0 network 192.168.0.0/24 +set protocols ospf log-adjacency-changes +set protocols ospf parameters router-id 10.2.2.2 +set protocols ospf redistribute connected metric-type 2 +set protocols ospf redistribute connected route-map CONNECT + +set policy route-map CONNECT rule 10 action permit +set policy route-map CONNECT rule 10 match interface lo +``` + +### Enable OSPF and IGP-LDP synchronization: + +**Node 1:** + +```none +set interfaces loopback lo address 10.1.1.1/32 +set interfaces ethernet eth0 address 192.168.0.1/24 + +set protocols ospf area 0 network '192.168.0.0/24' +set protocols ospf area 0 network '10.1.1.1/32' +set protocols ospf parameters router-id '10.1.1.1' +set protocols ospf ldp-sync + +set protocols mpls interface eth0 +set protocols mpls ldp discovery transport-ipv4-address 10.1.1.1 +set protocols mpls ldp interface lo +set protocols mpls ldp interface eth0 +set protocols mpls ldp parameters transport-prefer-ipv4 +set protocols mpls ldp router-id 10.1.1.1 +``` + +This gives us IGP-LDP synchronization for all non-loopback interfaces with +a holddown timer of zero seconds: + +```none +Node-1@vyos:~$ show ip ospf mpls ldp-sync + eth0 + LDP-IGP Synchronization enabled: yes + Holddown timer in seconds: 0 + State: Sync achieved +``` + +### Enable OSPF with Segment Routing (Experimental): + +**Node 1** + +```none +set interfaces loopback lo address 10.1.1.1/32 +set interfaces ethernet eth0 address 192.168.0.1/24 + +set protocols ospf area 0 network '192.168.0.0/24' +set protocols ospf area 0 network '10.1.1.1/32' +set protocols ospf parameters opaque-lsa +set protocols ospf parameters router-id '10.1.1.1' +set protocols ospf segment-routing global-block high-label-value '1100' +set protocols ospf segment-routing global-block low-label-value '1000' +set protocols ospf segment-routing prefix 10.1.1.1/32 index explicit-null +set protocols ospf segment-routing prefix 10.1.1.1/32 index value '1' +``` + +**Node 2** + +```none +set interfaces loopback lo address 10.1.1.2/32 +set interfaces ethernet eth0 address 192.168.0.2/24 + +set protocols ospf area 0 network '192.168.0.0/24' +set protocols ospf area 0 network '10.1.1.2/32' +set protocols ospf parameters opaque-lsa +set protocols ospf parameters router-id '10.1.1.2' +set protocols ospf segment-routing global-block high-label-value '1100' +set protocols ospf segment-routing global-block low-label-value '1000' +set protocols ospf segment-routing prefix 10.1.1.2/32 index explicit-null +set protocols ospf segment-routing prefix 10.1.1.2/32 index value '2' +``` + +This gives us MPLS segment routing enabled and labels for far end loopbacks: + +```none +Node-1@vyos:~$ show mpls table + Inbound Label Type Nexthop Outbound Label + ----------------------------------------------------------- + 1002 SR (OSPF) 192.168.0.2 IPv4 Explicit Null <-- Node-2 loopback learned on Node-1 + 15000 SR (OSPF) 192.168.0.2 implicit-null + 15001 SR (OSPF) 192.168.0.2 implicit-null + +Node-2@vyos:~$ show mpls table + Inbound Label Type Nexthop Outbound Label + ----------------------------------------------------------- + 1001 SR (OSPF) 192.168.0.1 IPv4 Explicit Null <-- Node-1 loopback learned on Node-2 + 15000 SR (OSPF) 192.168.0.1 implicit-null + 15001 SR (OSPF) 192.168.0.1 implicit-null +``` + +Here is the routing tables showing the MPLS segment routing label operations: + +```none +Node-1@vyos:~$ show ip route ospf +Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, + f - OpenFabric, + > - selected route, * - FIB route, q - queued, r - rejected, b - backup + t - trapped, o - offload failure + +O 10.1.1.1/32 [110/0] is directly connected, lo, weight 1, 00:03:43 +O>* 10.1.1.2/32 [110/1] via 192.168.0.2, eth0, label IPv4 Explicit Null, weight 1, 00:03:32 +O 192.168.0.0/24 [110/1] is directly connected, eth0, weight 1, 00:03:43 + +Node-2@vyos:~$ show ip route ospf +Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, + f - OpenFabric, + > - selected route, * - FIB route, q - queued, r - rejected, b - backup + t - trapped, o - offload failure + +O>* 10.1.1.1/32 [110/1] via 192.168.0.1, eth0, label IPv4 Explicit Null, weight 1, 00:03:36 +O 10.1.1.2/32 [110/0] is directly connected, lo, weight 1, 00:03:51 +O 192.168.0.0/24 [110/1] is directly connected, eth0, weight 1, 00:03:51 +``` + +(routing-ospfv3)= + +## OSPFv3 (IPv6) + +(ospf-v3-configuration)= + +### Configuration + +(ospf-v3-general)= + +#### General + +VyOS does not have a special command to start the OSPFv3 process. The OSPFv3 +process starts when the first ospf enabled interface is configured. + +```{cfgcmd} set protocols ospfv3 interface \ area \ + + This command specifies the OSPFv3 enabled interface. This command is also + used to enable the OSPF process. The area number can be specified in + decimal notation in the range from 0 to 4294967295. Or it can be specified + in dotted decimal notation similar to ip address. +``` + + +```{cfgcmd} set protocols ospfv3 parameters router-id \ + +This command sets the router-ID of the OSPFv3 process. The router-ID may be +an IP address of the router, but need not be – it can be any arbitrary +32bit number. However it MUST be unique within the entire OSPFv3 domain to +the OSPFv3 speaker – bad things will happen if multiple OSPFv3 speakers are +configured with the same router-ID! +``` + +(ospf-v3-optional)= + +#### Optional + +```{cfgcmd} set protocols ospfv3 distance global \ + +This command change distance value of OSPFv3 globally. +The distance range is 1 to 255. +``` +```{cfgcmd} set protocols ospfv3 distance ospfv3 \ \ + +This command change distance value of OSPFv3. The arguments are the +distance values for external routes, inter-area routes and intra-area +routes respectively. The distance range is 1 to 255. +``` + +(ospf-v3-area-configuration)= + +#### Area Configuration + +```{cfgcmd} set protocols ospfv3 area \ range \ + +This command summarizes intra area paths from specified area into one +Type-3 Inter-Area Prefix LSA announced to other areas. This command can be +used only in ABR. +``` +```{cfgcmd} set protocols ospfv3 area \ range \ not-advertise + +This command instead of summarizing intra area paths filter them - i.e. +intra area paths from this range are not advertised into other areas. This +command makes sense in ABR only. +``` + +(ospf-v3-interface-config)= + +#### Interface Configuration + +```{cfgcmd} set protocols ospfv3 interface \ ipv6 cost \ + +This command sets link cost for the specified interface. The cost value is +set to router-LSA’s metric field and used for SPF calculation. The cost +range is 1 to 65535. +``` +```{cfgcmd} set protocols ospfv3 interface \ dead-interval \ + +Set number of seconds for router Dead Interval timer value used for Wait +Timer and Inactivity Timer. This value must be the same for all routers +attached to a common network. The default value is 40 seconds. The +interval range is 1 to 65535. +``` +```{cfgcmd} set protocols ospfv3 interface \ hello-interval \ + +Set number of seconds for Hello Interval timer value. Setting this value, +Hello packet will be sent every timer value seconds on the specified +interface. This value must be the same for all routers attached to a +common network. The default value is 10 seconds. The interval range is 1 +to 65535. +``` +```{cfgcmd} set protocols ospfv3 interface \ mtu-ignore + +This command disables check of the MTU value in the OSPF DBD packets. +Thus, use of this command allows the OSPF adjacency to reach the FULL +state even though there is an interface MTU mismatch between two OSPF +routers. +``` +```{cfgcmd} set protocols ospfv3 interface \ network \ + +This command allows to specify the distribution type for the network +connected to this interface: + +**broadcast** – broadcast IP addresses distribution. +**point-to-point** – address distribution in point-to-point networks. +``` +```{cfgcmd} set protocols ospfv3 interface \ priority \ + +This command sets Router Priority integer value. The router with the +highest priority will be more eligible to become Designated Router. +Setting the value to 0, makes the router ineligible to become Designated +Router. The default value is 1. The interval range is 0 to 255. +``` +```{cfgcmd} set protocols ospfv3 interface \ passive + +This command specifies interface as passive. Passive interface advertises +its address, but does not run the OSPF protocol (adjacencies are not formed +and hello packets are not generated). +``` +```{cfgcmd} set protocols ospfv3 interface \ retransmit-interval \ + +This command sets number of seconds for RxmtInterval timer value. This +value is used when retransmitting Database Description and Link State +Request packets if acknowledge was not received. The default value is 5 +seconds. The interval range is 3 to 65535. +``` +```{cfgcmd} set protocols ospfv3 interface \ transmit-delay \ + +This command sets number of seconds for InfTransDelay value. It allows to +set and adjust for each interface the delay interval before starting the +synchronizing process of the router's database with all neighbors. The +default value is 1 seconds. The interval range is 3 to 65535. +``` + +(ospf-v3-graceful-restart)= + +#### Graceful Restart + +```{cfgcmd} set protocols ospfv3 graceful-restart [grace-period (1-1800)] + +Configure Graceful Restart {rfc}`3623` restarting support. When enabled, +the default grace period is 120 seconds. + +To perform a graceful shutdown, the FRR ``graceful-restart prepare ip +ospf`` EXEC-level command needs to be issued before restarting the +ospfd daemon. +``` +```{cfgcmd} set protocols ospfv3 graceful-restart helper enable [router-id A.B.C.D] + +Configure Graceful Restart {rfc}`3623` helper support. By default, helper support +is disabled for all neighbours. This config enables/disables helper support +on this router for all neighbours. + +To enable/disable helper support for a specific neighbour, the router-id +(A.B.C.D) has to be specified. +``` +```{cfgcmd} set protocols ospfv3 graceful-restart helper lsa-check-disable + +By default strict-lsa-checking is configured then the helper will abort +the Graceful Restart when a LSA change occurs which affects the restarting +router. + +This command disables it. +``` +```{cfgcmd} set protocols ospfv3 graceful-restart helper supported-grace-time + +Supports as HELPER for configured grace period. +``` +```{cfgcmd} set protocols ospfv3 graceful-restart helper planned-only + +It helps to support as HELPER only for planned restarts. +By default, it supports both planned and unplanned outages. +``` + +(ospf-v3-redistribution-config)= + +#### Redistribution Configuration + +```{cfgcmd} set protocols ospfv3 redistribute \ + +This command redistributes routing information from the given route source +to the OSPFv3 process. There are five modes available for route source: +bgp, connected, kernel, ripng, static. +``` +```{cfgcmd} set protocols ospf redistribute \ route-map \ + +This command allows to use route map to filter redistributed routes from +given route source. There are five modes available for route source: bgp, +connected, kernel, ripng, static. +``` + +(ospf-v3-op-cmd)= + +#### Operational Mode Commands + +```{opcmd} show ipv6 ospfv3 neighbor + +This command displays the neighbors status. +``` +```{opcmd} show ipv6 ospfv3 neighbor detail + +This command displays the neighbors information in a detailed form, not +just a summary table. +``` +```{opcmd} show ipv6 ospfv3 neighbor drchoice + +This command displays the neighbor DR choice information. +``` +```{opcmd} show ipv6 ospfv3 interface [prefix]|[\ [prefix]] + +This command displays state and configuration of OSPF the specified +interface, or all interfaces if no interface is given. Whith the argument +{cfgcmd}`prefix` this command shows connected prefixes to advertise. +``` +```{opcmd} show ipv6 ospfv3 route + +This command displays the OSPF routing table, as determined by the most +recent SPF calculation. +``` +```{opcmd} show ipv6 ospfv3 border-routers + +This command displays a table of paths to area boundary and autonomous +system boundary routers. +``` +```{opcmd} show ipv6 ospfv3 database + +This command displays a summary table with a database contents (LSA). +``` +```{opcmd} show ipv6 ospfv3 database \ [A.B.C.D] [adv-router \|self-originate] + +This command displays a database contents for a specific link +advertisement type. +``` +```{opcmd} show ipv6 ospfv3 redistribute + +This command displays external information redistributed into OSPFv3 +``` + +(ospf-v3-config-example)= + +#### Configuration Example + +A typical configuration using 2 nodes. + +**Node 1:** + +```none +set protocols ospfv3 interface eth1 area 0.0.0.0 +set protocols ospfv3 area 0.0.0.0 range 2001:db8:1::/64 +set protocols ospfv3 parameters router-id 192.168.1.1 +set protocols ospfv3 redistribute connected +``` + +**Node 2:** + +```none +set protocols ospfv3 interface eth1 area 0.0.0.0 +set protocols ospfv3 area 0.0.0.0 range 2001:db8:2::/64 +set protocols ospfv3 parameters router-id 192.168.2.1 +set protocols ospfv3 redistribute connected +``` + +**To see the redistributed routes:** + +```none +show ipv6 ospfv3 redistribute +``` + +Cost calculation wireguard interfaces is unreliable as ospfv3 uses the link speed to calculate the link cost. +You might therefore want to set the link cost to a fixed value on WireGuard tunnels. + +Example configuration for WireGuard interfaces: + +**Node 1** + +```none +set interfaces wireguard wg01 peer ospf02 allowed-ips '::/0' +set interfaces wireguard wg01 peer ospf02 endpoint '10.1.1.101:12345' +set interfaces wireguard wg01 peer ospf02 pubkey 'ie3...=' +set interfaces wireguard wg01 port '12345' +set protocols ospfv3 parameters router-id 192.168.1.1 +set protocols ospfv3 interface 'wg01' area 0.0.0.0 +set protocols ospfv3 interface 'wg01' cost 10 +set protocols ospfv3 interface 'lo' area 0.0.0.0 +``` + +**Node 2** + +```none +set interfaces wireguard wg01 peer ospf01 allowed-ips '::/0' +set interfaces wireguard wg01 peer ospf01 endpoint '10.1.1.100:12345' +set interfaces wireguard wg01 peer ospf01 pubkey 'NHI...=' +set interfaces wireguard wg01 port '12345' +set protocols ospfv3 parameters router-id 192.168.1.2 +set protocols ospfv3 interface 'wg01' area 0.0.0.0 +set protocols ospfv3 interface 'wg01' cost 10 +set protocols ospfv3 interface 'lo' area 0.0.0.0 +``` + +**Status** + +```none +vyos@ospf01:~$ sh ipv6 ospfv3 neighbor +Neighbor ID Pri DeadTime State/IfState Duration I/F[State] +192.168.0.2 1 00:00:37 Full/PointToPoint 00:18:03 wg01[PointToPoint] + +vyos@ospf02# run sh ipv6 ospfv3 neighbor +Neighbor ID Pri DeadTime State/IfState Duration I/F[State] +192.168.0.1 1 00:00:39 Full/PointToPoint 00:19:44 wg01[PointToPoint] +``` diff --git a/docs/configuration/protocols/md-pim.md b/docs/configuration/protocols/md-pim.md new file mode 100644 index 00000000..db8c9fb7 --- /dev/null +++ b/docs/configuration/protocols/md-pim.md @@ -0,0 +1,282 @@ +--- +lastproofread: '2023-11-13' +--- + +(pim)= + +# PIM – Protocol Independent Multicast + +VyOS supports {abbr}`PIM-SM (PIM Sparse Mode)` as well as +{abbr}`IGMP (Internet Group Management Protocol)` v2 and v3 + +{abbr}`PIM (Protocol Independent Multicast)` must be configured in every +interface of every participating router. Every router must also have the +location of the Rendevouz Point manually configured. Then, unidirectional +shared trees rooted at the Rendevouz Point will automatically be built +for multicast distribution. + +Traffic from multicast sources will go to the Rendezvous Point, and +receivers will pull it from a shared tree using {abbr}`IGMP (Internet +Group Management Protocol)`. + +Multicast receivers will talk IGMP to their local router, so, besides +having PIM configured in every router, IGMP must also be configured in +any router where there could be a multicast receiver locally connected. + +VyOS supports both IGMP version 2 and version 3 (which allows +source-specific multicast). + +## PIM-SM - PIM Sparse Mode + +```{cfgcmd} set protocols pim ecmp + +If PIM has the a choice of ECMP nexthops for a particular +{abbr}`RPF (Reverse Path Forwarding)`, PIM will cause S,G flows to be +spread out amongst the nexthops. If this command is not specified then +the first nexthop found will be used. +``` + +```{cfgcmd} set protocols pim ecmp rebalance + +If PIM is using ECMP and an interface goes down, cause PIM to rebalance all +S,G flows across the remaining nexthops. If this command is not configured +PIM only modifies those S,G flows that were using the interface that went +down. +``` + +```{cfgcmd} set protocols pim join-prune-interval \ + +Modify the join/prune interval that PIM uses to the new value. Time is +specified in seconds. + +The default time is 60 seconds. + +If you enter a value smaller than 60 seconds be aware that this can and +will affect convergence at scale. +``` + +```{cfgcmd} set protocols pim keep-alive-timer \ + +Modify the time out value for a S,G flow from 1-65535 seconds. If choosing +a value below 31 seconds be aware that some hardware platforms cannot see +data flowing in better than 30 second chunks. +``` + +```{cfgcmd} set protocols pim packets \ + +When processing packets from a neighbor process the number of packets +incoming at one time before moving on to the next task. + +The default value is 3 packets. + +This command is only useful at scale when you can possibly have a large +number of PIM control packets flowing. +``` + +```{cfgcmd} set protocols pim register-accept-list \ + +When PIM receives a register packet the source of the packet will be compared +to the prefix-list specified, and if a permit is received normal processing +continues. If a deny is returned for the source address of the register packet +a register stop message is sent to the source. +``` + +```{cfgcmd} set protocols pim register-suppress-time \ + +Modify the time that pim will register suppress a FHR will send register +notifications to the kernel. +``` + +```{cfgcmd} set protocols pim rp \ group \ + +In order to use PIM, it is necessary to configure a {abbr}`RP (Rendezvous Point)` +for join messages to be sent to. Currently the only methodology to do this is +via static rendezvous point commands. + +All routers in the PIM network must agree on these values. + +The first ip address is the RP's address and the second value is the matching +prefix of group ranges covered. +``` + +```{cfgcmd} set protocols pim rp keep-alive-timer \ + +Modify the time out value for a S,G flow from 1-65535 seconds at +{abbr}`RP (Rendezvous Point)`. The normal keepalive period for the KAT(S,G) +defaults to 210 seconds. However, at the {abbr}`RP (Rendezvous Point)`, the +keepalive period must be at least the Register_Suppression_Time, or the RP +may time out the (S,G) state before the next Null-Register arrives. +Thus, the KAT(S,G) is set to max(Keepalive_Period, RP_Keepalive_Period) +when a Register-Stop is sent. + +If choosing a value below 31 seconds be aware that some hardware platforms +cannot see data flowing in better than 30 second chunks. + +See {rfc}`7761#section-4.1` for details. +``` + +```{cfgcmd} set protocols pim no-v6-secondary + +When sending PIM hello packets tell PIM to not send any v6 secondary +addresses on the interface. This information is used to allow PIM to use v6 +nexthops in it's decision for {abbr}`RPF (Reverse Path Forwarding)` lookup +if this option is not set (default). +``` + +```{cfgcmd} set protocols pim spt-switchover infinity-and-beyond [prefix-list \] + +On the last hop router if it is desired to not switch over to the SPT tree +configure this command. + +Optional parameter prefix-list can be use to control which groups to switch or +not switch. If a group is PERMIT as per the prefix-list, then the SPT switchover +does not happen for it and if it is DENY, then the SPT switchover happens. +``` + +```{cfgcmd} set protocols pim ssm prefix-list \ + +Specify a range of group addresses via a prefix-list that forces PIM to never +do {abbr}`SSM (Source-Specific Multicast)` over. +``` + + +### Interface specific commands + +```{cfgcmd} set protocols pim interface \ bfd [profile \] + +Automatically create BFD session for each RIP peer discovered in this +interface. When the BFD session monitor signalize that the link is down +the RIP peer is removed and all the learned routes associated with that +peer are removed. + +If optional profile parameter is used, select a BFD profile for the BFD +sessions created via this interface. +``` + +```{cfgcmd} set protocols pim interface \ dr-priority \ + +Set the {abbr}`DR (Designated Router)` Priority for the interface. +This command is useful to allow the user to influence what node becomes +the DR for a LAN segment. +``` + +```{cfgcmd} set protocols pim interface \ hello \ + +Set the PIM hello and hold interval for a interface. +``` + +```{cfgcmd} set protocols pim interface \ no-bsm + +Tell PIM that we would not like to use this interface to process +bootstrap messages. +``` + +```{cfgcmd} set protocols pim interface \ no-unicast-bsm + +Tell PIM that we would not like to use this interface to process +unicast bootstrap messages. +``` + +```{cfgcmd} set protocols pim interface \ passive + +Disable sending and receiving PIM control packets on the interface. +``` + +```{cfgcmd} set protocols pim interface \ source-address \ + +If you have multiple addresses configured on a particular interface and would +like PIM to use a specific source address associated with that interface. +``` + + +## IGMP - Internet Group Management Protocol) + +```{cfgcmd} set protocols pim igmp watermark-warning \ + +Configure watermark warning generation for an IGMP group limit. Generates +warning once the configured group limit is reached while adding new groups. +``` + +(pim-igmp-interface-commands)= + +### Interface specific commands + +```{cfgcmd} set protocols pim interface \ igmp join \ source-address \ + +Use this command to allow the selected interface to join a multicast +group defining the multicast address you want to join and the source +IP address too. +``` + +```{cfgcmd} set protocols pim interface \ igmp query-interval \ + +Use this command to configure in the selected interface the IGMP +host query interval (1-1800) in seconds that PIM will use. +``` + +```{cfgcmd} set protocols pim interface \ igmp query-max-response-time \ + +Use this command to configure in the selected interface the IGMP +query response timeout value (10-250) in deciseconds. If a report is +not returned in the specified time, it will be assumed the (S,G) or +(\*,G) state {rfc}`7761#section-4.1` has timed out. +``` + +```{cfgcmd} set protocols pim interface \ igmp version \ + +Use this command to define in the selected interface whether you +choose IGMP version 2 or 3. + +The default value is 3. +``` + + +#### Example + +In the following example we can see a basic multicast setup: + +```{image} /_static/images/multicast-basic.webp +:align: center +:alt: Network Topology Diagram +:width: 90% +``` + +**Router 1** + +```none +set interfaces ethernet eth2 address '172.16.0.2/24' +set interfaces ethernet eth1 address '100.64.0.1/24' +set protocols ospf area 0 network '172.16.0.0/24' +set protocols ospf area 0 network '100.64.0.0/24' +set protocols igmp interface eth1 +set protocols pim interface eth1 +set protocols pim interface eth2 +set protocols pim rp address 172.16.255.1 group '224.0.0.0/4' +``` + +**Router 3** + +```none +set interfaces dummy dum0 address '172.16.255.1/24' +set interfaces ethernet eth0 address '172.16.0.1/24' +set interfaces ethernet eth1 address '172.16.1.1/24' +set protocols ospf area 0 network '172.16.0.0/24' +set protocols ospf area 0 network '172.16.255.0/24' +set protocols ospf area 0 network '172.16.1.0/24' +set protocols pim interface dum0 +set protocols pim interface eth0 +set protocols pim interface eth1 +set protocols pim rp address 172.16.255.1 group '224.0.0.0/4' +``` + +**Router 2** + +```none +set interfaces ethernet eth1 address '10.0.0.1/24' +set interfaces ethernet eth2 address '172.16.1.2/24' +set protocols ospf area 0 network '10.0.0.0/24' +set protocols ospf area 0 network '172.16.1.0/24' +set protocols pim interface eth1 +set protocols pim interface eth2 +set protocols pim rp address 172.16.255.1 group '224.0.0.0/4' +``` diff --git a/docs/configuration/protocols/md-pim6.md b/docs/configuration/protocols/md-pim6.md new file mode 100644 index 00000000..707ae606 --- /dev/null +++ b/docs/configuration/protocols/md-pim6.md @@ -0,0 +1,100 @@ +(pim6)= + +# PIM6 - Protocol Independent Multicast for IPv6 + +VyOS facilitates IPv6 Multicast by supporting **PIMv6** and **MLD**. + +PIMv6 (Protocol Independent Multicast for IPv6) must be configured in every +interface of every participating router. Every router must also have the +location of the Rendevouz Point manually configured. +Then, unidirectional shared trees rooted at the Rendevouz Point will +automatically be built for multicast distribution. + +Traffic from multicast sources will go to the Rendezvous Point, and receivers +will pull it from a shared tree using MLD (Multicast Listener Discovery). + +Multicast receivers will talk MLD to their local router, so, besides having +PIMv6 configured in every router, MLD must also be configured in any router +where there could be a multicast receiver locally connected. + +VyOS supports both MLD version 1 and version 2 +(which allows source-specific multicast). + +## Basic commands + +These are the commands for a basic setup. + +```{cfgcmd} set protocols pim6 interface \ + + Use this command to enable PIMv6 in the selected interface so that it + can communicate with PIMv6 neighbors. This command also enables MLD reports + and query on the interface unless {cfgcmd}`mld disable` is configured. +``` + + +```{cfgcmd} set protocols pim6 interface \ mld disable + +Disable MLD reports and query on the interface. +``` + + +## Tuning commands + +You can also tune multicast with the following commands. + +```{cfgcmd} set protocols pim6 interface \ mld interval \ + +Use this command to configure in the selected interface the MLD +host query interval (1-65535) in seconds that PIM will use. +The default value is 125 seconds. +``` + +```{cfgcmd} set protocols pim6 interface \ mld join \ + +Use this command to allow the selected interface to join a multicast group. +``` + +```{cfgcmd} set protocols pim6 interface \ mld join \ source \ + +Use this command to allow the selected interface to join a source-specific multicast +group. +``` + +```{cfgcmd} set protocols pim6 interface \ mld last-member-query-count \ + +Set the MLD last member query count. The default value is 2. +``` + +```{cfgcmd} set protocols pim6 interface \ mld last-member-query-interval \ + +Set the MLD last member query interval in milliseconds (100-6553500). The default value is 1000 milliseconds. +``` + +```{cfgcmd} set protocols pim6 interface \ mld max-response-time \ + +Set the MLD query response timeout in milliseconds (100-6553500). The default value is 10000 milliseconds. +``` + +```{cfgcmd} set protocols pim6 interface \ mld version \ + +Set the MLD version used on this interface. The default value is 2. +``` + + +### Configuration Example + +To enable MLD reports and query on interfaces `eth0` and `eth1`: + +```none +set protocols pim6 interface eth0 +set protocols pim6 interface eth1 +``` + +The following configuration explicitly joins multicast group `ff15::1234` on interface `eth1` +and source-specific multicast group `ff15::5678` with source address `2001:db8::1` on interface +`eth1`: + +```none +set protocols pim6 interface eth0 mld join ff15::1234 +set protocols pim6 interface eth1 mld join ff15::5678 source 2001:db8::1 +``` diff --git a/docs/configuration/protocols/md-rip.md b/docs/configuration/protocols/md-rip.md new file mode 100644 index 00000000..684337d6 --- /dev/null +++ b/docs/configuration/protocols/md-rip.md @@ -0,0 +1,294 @@ +--- +lastproofread: '2021-10-04' +--- + +(rip)= + +# RIP + +{abbr}`RIP (Routing Information Protocol)` is a widely deployed interior gateway +protocol. RIP was developed in the 1970s at Xerox Labs as part of the XNS +routing protocol. RIP is a distance-vector protocol and is based on the +Bellman-Ford algorithms. As a distance-vector protocol, RIP router send updates +to its neighbors periodically, thus allowing the convergence to a known +topology. In each update, the distance to any given network will be broadcast +to its neighboring router. + +Supported versions of RIP are: + +> - RIPv1 as described in {rfc}`1058` +> - RIPv2 as described in {rfc}`2453` + +## General Configuration + +```{cfgcmd} set protocols rip network \ + +This command enables RIP and sets the RIP enable interface by NETWORK. +The interfaces which have addresses matching with NETWORK are enabled. +``` + + +```{cfgcmd} set protocols rip interface \ + +This command specifies a RIP enabled interface by interface name. Both +the sending and receiving of RIP packets will be enabled on the port +specified in this command. +``` + + +```{cfgcmd} set protocols rip neighbor \ + +This command specifies a RIP neighbor. When a neighbor doesn’t understand +multicast, this command is used to specify neighbors. In some cases, not +all routers will be able to understand multicasting, where packets are +sent to a network or a group of addresses. In a situation where a neighbor +cannot process multicast packets, it is necessary to establish a direct +link between routers. +``` + + +```{cfgcmd} set protocols rip passive-interface interface \ + +This command sets the specified interface to passive mode. On passive mode +interface, all receiving packets are processed as normal and VyOS does not +send either multicast or unicast RIP packets except to RIP neighbors +specified with neighbor command. +``` + + +```{cfgcmd} set protocols rip passive-interface interface default + +This command specifies all interfaces to passive mode. +``` + +## Optional Configuration + +```{cfgcmd} set protocols rip default-distance \ + +This command change the distance value of RIP. The distance range is 1 to 255. + +> :::{note} +> Routes with a distance of 255 are effectively disabled and not +> installed into the kernel. +> ::: +``` + + +```{cfgcmd} set protocols rip network-distance \ distance \ + +This command sets default RIP distance to a specified value when the routes +source IP address matches the specified prefix. +``` + + +```{cfgcmd} set protocols rip network-distance \ access-list \ + +This command can be used with previous command to sets default RIP distance +to specified value when the route source IP address matches the specified +prefix and the specified access-list. +``` + + +```{cfgcmd} set protocols rip default-information originate + +This command generate a default route into the RIP. +``` + + +```{cfgcmd} set protocols rip distribute-list access-list \ \ + +This command can be used to filter the RIP path using access lists. +{cfgcmd}`in` and {cfgcmd}`out` this is the direction in which the access +lists are applied. +``` + + +```{cfgcmd} set protocols rip distribute-list interface \ access-list \ \ + +This command allows you apply access lists to a chosen interface to +filter the RIP path. +``` + + +```{cfgcmd} set protocols rip distribute-list prefix-list \ \ + +This command can be used to filter the RIP path using prefix lists. +{cfgcmd}`in` and {cfgcmd}`out` this is the direction in which the prefix +lists are applied. +``` + + +```{cfgcmd} set protocols rip distribute-list interface \ prefix-list \ \ + +This command allows you apply prefix lists to a chosen interface to +filter the RIP path. +``` + + +```{cfgcmd} set protocols rip route \ + +This command is specific to FRR and VyOS. The route command makes a static +route only inside RIP. This command should be used only by advanced users +who are particularly knowledgeable about the RIP protocol. In most cases, +we recommend creating a static route in VyOS and redistributing it in RIP +using {cfgcmd}`redistribute static`. +``` + + +```{cfgcmd} set protocols rip timers update \ + +This command specifies the update timer. Every update timer seconds, the +RIP process is awakened to send an unsolicited response message containing +the complete routing table to all neighboring RIP routers. The time range +is 5 to 2147483647. The default value is 30 seconds. +``` + + +```{cfgcmd} set protocols rip timers timeout \ + +This command specifies the timeout timer. Upon expiration of the timeout, +the route is no longer valid; however, it is retained in the routing table +for a short time so that neighbors can be notified that the route has been +dropped. The time range is 5 to 2147483647. The default value is 180 +seconds. +``` + + +```{cfgcmd} set protocols rip timers garbage-collection \ + +This command specifies the garbage-collection timer. Upon expiration of +the garbage-collection timer, the route is finally removed from the +routing table. The time range is 5 to 2147483647. The default value is 120 +seconds. +``` + +## Redistribution Configuration + +```{cfgcmd} set protocols rip redistribute \ + +This command redistributes routing information from the given route source +into the RIP tables. There are five modes available for route source: bgp, +connected, kernel, ospf, static. +``` + + +```{cfgcmd} set protocols rip redistribute \ metric \ + +This command specifies metric for redistributed routes from the given route +source. There are five modes available for route source: bgp, connected, +kernel, ospf, static. The metric range is 1 to 16. +``` + + +```{cfgcmd} set protocols rip redistribute \ route-map \ + +This command allows to use route map to filter redistributed routes from +the given route source. There are five modes available for route source: +bgp, connected, kernel, ospf, static. +``` + + +```{cfgcmd} set protocols rip default-metric \ + +This command modifies the default metric (hop count) value for redistributed +routes. The metric range is 1 to 16. The default value is 1. This command +does not affect connected route even if it is redistributed by +{cfgcmd}`redistribute connected`. To modify connected routes metric +value, please use {cfgcmd}`redistribute connected metric`. +``` + +## Interfaces Configuration + +```{cfgcmd} set interfaces \ \ ip rip authentication plaintext-password \ + +This command sets the interface with RIP simple password authentication. +This command also sets authentication string. The string must be shorter +than 16 characters. +``` + + +```{cfgcmd} set interfaces \ \ ip rip authentication md5 \ password \ + +This command sets the interface with RIP MD5 authentication. This command +also sets MD5 Key. The key must be shorter than 16 characters. +``` + + +```{cfgcmd} set interfaces \ \ ip rip split-horizon disable + +This command disables split-horizon on the interface. By default, VyOS does +not advertise RIP routes out the interface over which they were learned +(split horizon).3 +``` + + +```{cfgcmd} set interfaces \ \ ip rip split-horizon poison-reverse + +This command enables poison-reverse on the interface. If both poison reverse +and split horizon are enabled, then VyOS advertises the learned routes +as unreachable over the interface on which the route was learned. +``` + +## Operational Mode Commands + +```{opcmd} show ip rip + +This command displays RIP routes. +``` +```none +Codes: R - RIP, C - connected, S - Static, O - OSPF, B - BGP +Sub-codes: + (n) - normal, (s) - static, (d) - default, (r) - redistribute, + (i) - interface + + Network Next Hop Metric From Tag Time +C(i) 10.0.12.0/24 0.0.0.0 1 self 0 +C(i) 10.0.13.0/24 0.0.0.0 1 self 0 +R(n) 10.0.23.0/24 10.0.12.2 2 10.0.12.2 0 02:53 +``` + +```{opcmd} show ip rip status + +The command displays current RIP status. It includes RIP timer, filtering, +version, RIP enabled interface and RIP peer information. +``` +```none +Routing Protocol is "rip" + Sending updates every 30 seconds with +/-50%, next due in 11 seconds + Timeout after 180 seconds, garbage collect after 120 seconds + Outgoing update filter list for all interface is not set + Incoming update filter list for all interface is not set + Default redistribution metric is 1 + Redistributing: + Default version control: send version 2, receive any version + Interface Send Recv Key-chain + eth0 2 1 2 + eth2 2 1 2 + Routing for Networks: + 10.0.12.0/24 + eth0 + Routing Information Sources: + Gateway BadPackets BadRoutes Distance Last Update + 10.0.12.2 0 0 120 00:00:11 + Distance: (default is 120) +``` + +## Configuration Example + +Simple RIP configuration using 2 nodes and redistributing connected interfaces. + +**Node 1:** + +```none +set interfaces loopback address 10.1.1.1/32 +set protocols rip network 192.168.0.0/24 +set protocols rip redistribute connected +``` + +**Node 2:** + +```none +set interfaces loopback address 10.2.2.2/32 +set protocols rip network 192.168.0.0/24 +set protocols rip redistribute connected +``` diff --git a/docs/configuration/protocols/md-rpki.md b/docs/configuration/protocols/md-rpki.md new file mode 100644 index 00000000..1f4cf5bf --- /dev/null +++ b/docs/configuration/protocols/md-rpki.md @@ -0,0 +1,210 @@ +(rpki)= + +# RPKI + +:::{pull-quote} + +There are two types of Network Admins who deal with BGP, those who have +created an international incident and/or outage, and those who are lying + +-- [tweet by EvilMog](https://twitter.com/Evil_Mog/status/1230924170508169216), 2020-02-21 +::: + +{abbr}`RPKI (Resource Public Key Infrastructure)` is a framework designed to +secure the Internet routing infrastructure. It associates BGP route +announcements with the correct originating {abbr}`ASN (Autonomus System +Number)` which BGP routers can then use to check each route against the +corresponding {abbr}`ROA (Route Origin Authorisation)` for validity. RPKI is +described in {rfc}`6480`. + +A BGP-speaking router like VyOS can retrieve ROA information from RPKI +"Relying Party software" (often just called an "RPKI server" or "RPKI +validator") by using {abbr}`RTR (RPKI to Router)` protocol. There are several +open source implementations to choose from, such as NLNetLabs' [Routinator] +(written in Rust), OpenBSD's [rpki-client] (written in C), and [StayRTR] (written +in Go). The RTR protocol is described in {rfc}`8210`. + +:::{tip} +If you are new to these routing security technologies then there is an +[excellent guide to RPKI] by NLnet Labs which will get you up to speed +very quickly. Their documentation explains everything from what RPKI is to +deploying it in production. It also has some +[help and operational guidance] including "What can I do about my route +having an Invalid state?" +::: + +## Getting started + +First you will need to deploy an RPKI validator for your routers to use. NLnet +Labs provides a collection of [software] you can compare and settle on one. +Once your server is running you can start validating announcements. + +Imported prefixes during the validation may have values: + +> valid +> +> : The prefix and ASN that originated it match a signed ROA. These are +> probably trustworthy route announcements. +> +> invalid +> +> : The prefix or prefix length and ASN that originated it doesn't +> match any existing ROA. This could be the result of a prefix hijack, or +> merely a misconfiguration, but should probably be treated as +> untrustworthy route announcements. +> +> notfound +> +> : No ROA exists which covers that prefix. Unfortunately this is the case for +> about 40%-50% of the prefixes which were announced to the {abbr}`DFZ +> (default-free zone)` at the start of 2024. + +:::{note} +If you are responsible for the global addresses assigned to your +network, please make sure that your prefixes have ROAs associated with them +to avoid being `notfound` by RPKI. For most ASNs this will involve +publishing ROAs via your {abbr}`RIR (Regional Internet Registry)` (RIPE +NCC, APNIC, ARIN, LACNIC, or AFRINIC), and is something you are encouraged +to do whenever you plan to announce addresses into the DFZ. + +Particularly large networks may wish to run their own RPKI certificate +authority and publication server instead of publishing ROAs via their RIR. +This is a subject far beyond the scope of VyOS' documentation. Consider +reading about [Krill] if this is a rabbit hole you need or especially want +to dive down. +::: + +### Features of the Current Implementation + +In a nutshell, the current implementation provides the following features: + +- The BGP router can connect to one or more RPKI cache servers to receive + validated prefix to origin AS mappings. Advanced failover can be implemented + by server sockets with different preference values. +- If no connection to an RPKI cache server can be established after a + pre-defined timeout, the router will process routes without prefix origin + validation. It still will try to establish a connection to an RPKI cache + server in the background. +- By default, enabling RPKI does not change best path selection. In particular, + invalid prefixes will still be considered during best path selection. However, + the router can be configured to ignore all invalid prefixes. +- Route maps can be configured to match a specific RPKI validation state. This + allows the creation of local policies, which handle BGP routes based on the + outcome of the Prefix Origin Validation. +- Updates from the RPKI cache servers are directly applied and path selection is + updated accordingly. (Soft reconfiguration must be enabled for this to work). + +## Configuration + +```{cfgcmd} set protocols rpki polling-period \<1-86400\> + +Define the time interval to update the local cache + +The default value is 300 seconds. +``` + +```{cfgcmd} set protocols rpki expire-interval \<600-172800\> + +Set the number of seconds the router waits until the router +expires the cache. + +The default value is 7200 seconds. +``` + +```{cfgcmd} set protocols rpki retry-interval \<1-7200\> + +Set the number of seconds the router waits until retrying to connect +to the cache server. + +The default value is 600 seconds. +``` + +```{cfgcmd} set protocols rpki cache \ port \ + +Defined the IPv4, IPv6 or FQDN and port number of the caching RPKI caching +instance which is used. + +This is a mandatory setting. +``` + +```{cfgcmd} set protocols rpki cache \ preference \ + +Multiple RPKI caching instances can be supplied and they need a preference in +which their result sets are used. + +This is a mandatory setting. +``` + + +### SSH + +Connections to the RPKI caching server can not only be established by TCP using +the RTR protocol but you can also rely on a secure SSH session to the server. +This provides transport integrity and confidentiality and it is a good idea if +your validation software supports it. To enable SSH, first you need to create +an SSH client keypair using `generate ssh client-key +/config/auth/id_rsa_rpki`. Once your key is created you can setup the +connection. + +```{cfgcmd} set protocols rpki cache \ ssh username \ + +SSH username to establish an SSH connection to the cache server. +``` + +```{cfgcmd} set protocols rpki cache \ ssh private-key-file \ + +Local path that includes the private key file of the router. +``` + +```{cfgcmd} set protocols rpki cache \ ssh public-key-file \ + +Local path that includes the public key file of the router. +``` + +:::{note} +When using SSH, private-key-file and public-key-file +are mandatory options. +::: + +## Example + +We can build route-maps for import based on these states. Here is a simple +RPKI configuration, where `routinator` is the RPKI-validating "cache" +server with ip `192.0.2.1`: + +```none +set protocols rpki cache 192.0.2.1 port '3323' +set protocols rpki cache 192.0.2.1 preference '1' +``` + +Here is an example route-map to apply to routes learned at import. In this +filter we reject prefixes with the state `invalid`, and set a higher +`local-preference` if the prefix is RPKI `valid` rather than merely +`notfound`. + +```none +set policy route-map ROUTES-IN rule 10 action 'permit' +set policy route-map ROUTES-IN rule 10 match rpki 'valid' +set policy route-map ROUTES-IN rule 10 set local-preference '300' +set policy route-map ROUTES-IN rule 20 action 'permit' +set policy route-map ROUTES-IN rule 20 match rpki 'notfound' +set policy route-map ROUTES-IN rule 20 set local-preference '125' +set policy route-map ROUTES-IN rule 30 action 'deny' +set policy route-map ROUTES-IN rule 30 match rpki 'invalid' +``` + +Once your routers are configured to reject RPKI-invalid prefixes, you can +test whether the configuration is working correctly using Cloudflare's [test] +website. Keep in mind that in order for this to work, you need to have no +default routes or anything else that would still send traffic to RPKI-invalid +destinations. + +[excellent guide to rpki]: https://rpki.readthedocs.io/ +[help and operational guidance]: https://rpki.readthedocs.io/en/latest/about/help.html +[krill]: https://www.nlnetlabs.nl/projects/rpki/krill/ +[routinator]: https://www.nlnetlabs.nl/projects/rpki/routinator/ +[rpki-client]: https://www.rpki-client.org/ +[software]: https://rpki.readthedocs.io/en/latest/ops/tools.html#relying-party-software +[stayrtr]: https://github.com/bgp/stayrtr/ +[test]: https://isbgpsafeyet.com/ +[tweet by evilmog]: diff --git a/docs/configuration/protocols/md-segment-routing.md b/docs/configuration/protocols/md-segment-routing.md new file mode 100644 index 00000000..af47d343 --- /dev/null +++ b/docs/configuration/protocols/md-segment-routing.md @@ -0,0 +1,359 @@ +(segment-routing)= + +# Segment Routing + +Segment Routing (SR) is a network architecture that is similar to source-routing +. In this architecture, the ingress router adds a list of segments, known as +SIDs, to the packet as it enters the network. These segments represent different +portions of the network path that the packet will take. + +The SR segments are portions of the network path taken by the packet, and are +called SIDs. At each node, the first SID of the list is read, executed as a +forwarding function, and may be popped to let the next node read the next SID of +the list. The SID list completely determines the path where the packet is +forwarded. + +Segment Routing can be applied to an existing MPLS-based data plane and defines +a control plane network architecture. In MPLS networks, segments are encoded as +MPLS labels and are added at the ingress router. These MPLS labels are then +exchanged and populated by Interior Gateway Protocols (IGPs) like IS-IS or OSPF +which are running on most ISPs. + +:::{note} +Segment routing defines a control plane network architecture and +can be applied to an existing MPLS based dataplane. In the MPLS networks, +segments are encoded as MPLS labels and are imposed at the ingress router. +MPLS labels are exchanged and populated by IGPs like IS-IS.Segment Routing +as per RFC8667 for MPLS dataplane. It supports IPv4, IPv6 and ECMP and has +been tested against Cisco & Juniper routers.however,this deployment is still +EXPERIMENTAL for FRR. +::: + +## IS-IS SR Configuration + +Segment routing (SR) is used by the IGP protocols to interconnect network +devices, below configuration shows how to enable SR on IS-IS: + +:::{note} +``Known limitations:`` + +No support for level redistribution (L1 to L2 or L2 to L1) + +No support for binding SID + +No support for SRLB + +Only one SRGB and default SPF Algorithm is supported +::: + +```{cfgcmd} set protocols isis segment-routing global-block high-label-value \ + +Set the Segment Routing Global Block i.e. the label range used by MPLS to +store label in the MPLS FIB for Prefix SID. Note that the block size may +not exceed 65535. +``` + + +```{cfgcmd} set protocols isis segment-routing global-block low-label-value \ + +Set the Segment Routing Global Block i.e. the low label range used by MPLS to +store label in the MPLS FIB for Prefix SID. Note that the block size may +not exceed 65535. +``` + + +```{cfgcmd} set protocols isis segment-routing local-block high-label-value \ + +Set the Segment Routing Local Block i.e. the label range used by MPLS to +store label in the MPLS FIB for Prefix SID. Note that the block size may +not exceed 65535.Segment Routing Local Block, The negative command always +unsets both. +``` + + +```{cfgcmd} set protocols isis segment-routing local-block \ + +Set the Segment Routing Local Block i.e. the low label range used by MPLS to +store label in the MPLS FIB for Prefix SID. Note that the block size may +not exceed 65535.Segment Routing Local Block, The negative command always +unsets both. +``` + + +```{cfgcmd} set protocols isis segment-routing maximum-label-depth \<1-16\> + +Set the Maximum Stack Depth supported by the router. The value depend of +the MPLS dataplane. +``` + + +```{cfgcmd} set protocols isis segment-routing prefix \ index value \<0-65535\> + +A segment ID that contains an IP address prefix calculated by an IGP in the +service provider core network. Prefix SIDs are globally unique, this value +identify 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 +identify it +``` + +```{cfgcmd} set protocols ospf segment-routing prefix \ index \ + +this option allows to configure prefix-sid on SR. The ‘no-php-flag’ means NO +Penultimate Hop Popping that allows SR node to request to its neighbor to +not pop the label. The ‘explicit-null’ flag allows SR node to request to its +neighbor to send IP packet with the EXPLICIT-NULL label. The ‘n-flag-clear’ +option can be used to explicitly clear the Node flag that is set by default +for Prefix-SIDs associated to loopback addresses. This option is necessary +to configure Anycast-SIDs. +``` + +:::{note} +more information related IGP - {ref}`routing-ospf` +::: + +## Configuration Example + +we described the configuration SR ISIS / SR OSPF using 2 connected with them to +share label information. + +### Enable IS-IS with Segment Routing (Experimental) + +**Node 1:** + +```none +set interfaces loopback lo address '192.168.255.255/32' +set interfaces ethernet eth1 address '192.0.2.1/24' + +set protocols isis interface eth1 +set protocols isis interface lo +set protocols isis net '49.0001.1921.6825.5255.00' +set protocols isis segment-routing global-block high-label-value '599' +set protocols isis segment-routing global-block low-label-value '550' +set protocols isis segment-routing prefix 192.168.255.255/32 index value '1' +set protocols isis segment-routing prefix 192.168.255.255/32 index explicit-null +set protocols mpls interface 'eth1' +``` + +**Node 2:** + +```none +set interfaces loopback lo address '192.168.255.254/32' +set interfaces ethernet eth1 address '192.0.2.2/24' + +set protocols isis interface eth1 +set protocols isis interface lo +set protocols isis net '49.0001.1921.6825.5254.00' +set protocols isis segment-routing global-block high-label-value '599' +set protocols isis segment-routing global-block low-label-value '550' +set protocols isis segment-routing prefix 192.168.255.254/32 index value '2' +set protocols isis segment-routing prefix 192.168.255.254/32 index explicit-null +set protocols mpls interface 'eth1' +``` + +This gives us MPLS segment routing enabled and labels for far end loopbacks: + +```none +Node-1@vyos:~$ show mpls table + Inbound Label Type Nexthop Outbound Label + ---------------------------------------------------------------------- + 552 SR (IS-IS) 192.0.2.2 IPv4 Explicit Null <-- Node-2 loopback learned on Node-1 + 15000 SR (IS-IS) 192.0.2.2 implicit-null + 15001 SR (IS-IS) fe80::e87:6cff:fe09:1 implicit-null + 15002 SR (IS-IS) 192.0.2.2 implicit-null + 15003 SR (IS-IS) fe80::e87:6cff:fe09:1 implicit-null + +Node-2@vyos:~$ show mpls table + Inbound Label Type Nexthop Outbound Label + --------------------------------------------------------------------- + 551 SR (IS-IS) 192.0.2.1 IPv4 Explicit Null <-- Node-1 loopback learned on Node-2 + 15000 SR (IS-IS) 192.0.2.1 implicit-null + 15001 SR (IS-IS) fe80::e33:2ff:fe80:1 implicit-null + 15002 SR (IS-IS) 192.0.2.1 implicit-null + 15003 SR (IS-IS) fe80::e33:2ff:fe80:1 implicit-null +``` + +Here is the routing tables showing the MPLS segment routing label operations: + +```none +Node-1@vyos:~$ show ip route isis +Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, + f - OpenFabric, + > - selected route, * - FIB route, q - queued, r - rejected, b - backup + t - trapped, o - offload failure + +I 192.0.2.0/24 [115/20] via 192.0.2.2, eth1 inactive, weight 1, 00:07:48 +I>* 192.168.255.254/32 [115/20] via 192.0.2.2, eth1, label IPv4 Explicit Null, weight 1, 00:03:39 + +Node-2@vyos:~$ show ip route isis +Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, + f - OpenFabric, + > - selected route, * - FIB route, q - queued, r - rejected, b - backup + t - trapped, o - offload failure + +I 192.0.2.0/24 [115/20] via 192.0.2.1, eth1 inactive, weight 1, 00:07:46 +I>* 192.168.255.255/32 [115/20] via 192.0.2.1, eth1, label IPv4 Explicit Null, weight 1, 00:03:43 +``` + + +### Enable OSPF with Segment Routing (Experimental): + +**Node 1** + +```none +set interfaces loopback lo address 10.1.1.1/32 +set interfaces ethernet eth0 address 192.168.0.1/24 +set protocols ospf area 0 network '192.168.0.0/24' +set protocols ospf area 0 network '10.1.1.1/32' +set protocols ospf parameters opaque-lsa +set protocols ospf parameters router-id '10.1.1.1' +set protocols ospf segment-routing global-block high-label-value '1100' +set protocols ospf segment-routing global-block low-label-value '1000' +set protocols ospf segment-routing prefix 10.1.1.1/32 index explicit-null +set protocols ospf segment-routing prefix 10.1.1.1/32 index value '1' +``` + +**Node 2** + +```none +set interfaces loopback lo address 10.1.1.2/32 +set interfaces ethernet eth0 address 192.168.0.2/24 +set protocols ospf area 0 network '192.168.0.0/24' +set protocols ospf area 0 network '10.1.1.2/32' +set protocols ospf parameters opaque-lsa +set protocols ospf parameters router-id '10.1.1.2' +set protocols ospf segment-routing global-block high-label-value '1100' +set protocols ospf segment-routing global-block low-label-value '1000' +set protocols ospf segment-routing prefix 10.1.1.2/32 index explicit-null +set protocols ospf segment-routing prefix 10.1.1.2/32 index value '2' +``` + +This gives us MPLS segment routing enabled and labels for far end loopbacks: + +```none +Node-1@vyos:~$ show mpls table + Inbound Label Type Nexthop Outbound Label + ----------------------------------------------------------- + 1002 SR (OSPF) 192.168.0.2 IPv4 Explicit Null <-- Node-2 loopback learned on Node-1 + 15000 SR (OSPF) 192.168.0.2 implicit-null + 15001 SR (OSPF) 192.168.0.2 implicit-null + +Node-2@vyos:~$ show mpls table + Inbound Label Type Nexthop Outbound Label + ----------------------------------------------------------- + 1001 SR (OSPF) 192.168.0.1 IPv4 Explicit Null <-- Node-1 loopback learned on Node-2 + 15000 SR (OSPF) 192.168.0.1 implicit-null + 15001 SR (OSPF) 192.168.0.1 implicit-null +``` + +Here is the routing tables showing the MPLS segment routing label operations: + +```none +Node-1@vyos:~$ show ip route ospf +Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, + f - OpenFabric, + > - selected route, * - FIB route, q - queued, r - rejected, b - backup + t - trapped, o - offload failure + +O 10.1.1.1/32 [110/0] is directly connected, lo, weight 1, 00:03:43 +O>* 10.1.1.2/32 [110/1] via 192.168.0.2, eth0, label IPv4 Explicit Null, weight 1, 00:03:32 +O 192.168.0.0/24 [110/1] is directly connected, eth0, weight 1, 00:03:43 + +Node-2@vyos:~$ show ip route ospf +Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, + f - OpenFabric, + > - selected route, * - FIB route, q - queued, r - rejected, b - backup + t - trapped, o - offload failure + +O>* 10.1.1.1/32 [110/1] via 192.168.0.1, eth0, label IPv4 Explicit Null, weight 1, 00:03:36 +O 10.1.1.2/32 [110/0] is directly connected, lo, weight 1, 00:03:51 +O 192.168.0.0/24 [110/1] is directly connected, eth0, weight 1, 00:03:51 +``` diff --git a/docs/configuration/protocols/md-static.md b/docs/configuration/protocols/md-static.md new file mode 100644 index 00000000..357f7076 --- /dev/null +++ b/docs/configuration/protocols/md-static.md @@ -0,0 +1,298 @@ +(routing-static)= + +# Static + +Static routes are manually configured routes, which, in general, cannot be +updated dynamically from information VyOS learns about the network topology from +other routing protocols. However, if a link fails, the router will remove +routes, including static routes, from the {abbr}`RIPB (Routing Information +Base)` that used this interface to reach the next hop. In general, static +routes should only be used for very simple network topologies, or to override +the behavior of a dynamic routing protocol for a small number of routes. The +collection of all routes the router has learned from its configuration or from +its dynamic routing protocols is stored in the RIB. Unicast routes are directly +used to determine the forwarding table used for unicast packet forwarding. + +## IPv4 Unicast Routes + +```{cfgcmd} set protocols static route \ next-hop \ + +Configure next-hop *\* for an IPv4 static route. Multiple static +routes can be created. +``` + +```{cfgcmd} set protocols static route \ next-hop \ disable + +Disable this IPv4 static route entry. +``` + +```{cfgcmd} set protocols static route \ next-hop \ distance \ + +Defines next-hop distance for this route, routes with smaller administrative +distance are elected prior to those with a higher distance. + +Range is 1 to 255, default is 1. + +:::{note} +Routes with a distance of 255 are effectively disabled and not +installed into the kernel. +::: +``` + + +### IPv4 Interface Routes + +```{cfgcmd} set protocols static route \ interface \ + +Allows you to configure the next-hop interface for an interface-based IPv4 +static route. *\* will be the next-hop interface where traffic is +routed for the given *\*. +``` + +```{cfgcmd} set protocols static route \ interface \ disable + +Disables interface-based IPv4 static route. +``` + +```{cfgcmd} set protocols static route \ interface \ distance \ + +Defines next-hop distance for this route, routes with smaller administrative +distance are elected prior to those with a higher distance. + +Range is 1 to 255, default is 1. +``` + + +### IPv4 BFD + +```{cfgcmd} set protocols static route \ next-hop \ bfd + +Configure a static route for *\* using gateway *\* and use the +gateway address as BFD peer destination address. +``` + +```{cfgcmd} set protocols static route \ next-hop \ bfd profile \ + +Configure a static route for *\* using gateway *\* and use the +gateway address as BFD peer destination address with BFD profile *\*. +``` + +```{cfgcmd} set protocols static route \ next-hop \ bfd multi-hop source-address \ + +Configure a static route for *\* using gateway *\* and use the +gateway address as BFD peer destination address with source address +*\* but initiate a multi-hop session. +``` + + +### DHCP Interface Routes + +```{cfgcmd} set protocols static route \ dhcp-interface \ + +Defines route with DHCP interface supplying next-hop IP address. +``` + + +### IPv4 Reject Routes + +```{cfgcmd} set protocol static route \ reject + +Defines route which emits an ICMP unreachable when matched. +``` + +```{cfgcmd} set protocols static route \ reject distance \ + +Defines distance for this route, routes with smaller administrative +distance are elected prior to those with a higher distance. +``` + +```{cfgcmd} set protocols static route \ reject tag \ + +Sets a tag for this route. +``` + +```{cfgcmd} set protocol static route6 \ reject + +Defines route which emits an ICMP unreachable when matched. +``` + + +### IPv4 Blackhole Routes + +```{cfgcmd} set protocols static route \ blackhole + +Use this command to configure a "black-hole" route on the router. A +black-hole route is a route for which the system silently discard packets +that are matched. This prevents networks leaking out public interfaces, but +it does not prevent them from being used as a more specific route inside your +network. +``` + +```{cfgcmd} set protocols static route \ blackhole distance \ + +Defines blackhole distance for this route, routes with smaller administrative +distance are elected prior to those with a higher distance. +``` + +```{cfgcmd} set protocols static route \ blackhole tag \ + +Sets a tag for this route. +``` + + +## IPv6 Unicast Routes + +```{cfgcmd} set protocols static route6 \ next-hop \ + +Configure next-hop *\* for an IPv6 static route. Multiple static +routes can be created. +``` + +```{cfgcmd} set protocols static route6 \ next-hop \ disable + +Disable this IPv6 static route entry. +``` + +```{cfgcmd} set protocols static route6 \ next-hop \ distance \ + +Defines next-hop distance for this route, routes with smaller administrative +distance are elected prior to those with a higher distance. + +Range is 1 to 255, default is 1. + +:::{note} +Routes with a distance of 255 are effectively disabled and not +installed into the kernel. +::: +``` + +```{cfgcmd} set protocols static route6 \ next-hop \ segments \ + +It is possible to specify a static route for ipv6 prefixes using an +SRv6 segments instruction. The ``/`` separator can be used to specify +multiple segment instructions. + +Example: + +:::{code-block} none +set protocols static route6 2001:db8:1000::/36 next-hop 2001:db8:201::ffff segments '2001:db8:aaaa::7/2002::4/2002::3/2002::2' +::: + +:::{code-block} none +vyos@vyos:~$ show ipv6 route +Codes: K - kernel route, C - connected, S - static, R - RIPng, + O - OSPFv3, I - IS-IS, B - BGP, N - NHRP, T - Table, + v - VNC, V - VNC-Direct, A - Babel, F - PBR, + f - OpenFabric, + > - selected route, * - FIB route, q - queued, r - rejected, b - backup + t - trapped, o - offload failure +C>* 2001:db8:201::/64 is directly connected, eth0.201, 00:00:46 +S>* 2001:db8:1000::/36 [1/0] via 2001:db8:201::ffff, eth0.201, seg6 2001:db8:aaaa::7,2002::4,2002::3,2002::2, weight 1, 00:00:08 +::: +``` + + +### IPv6 Interface Routes + +```{cfgcmd} set protocols static route6 \ interface \ + +Allows you to configure the next-hop interface for an interface-based IPv6 +static route. *\* will be the next-hop interface where traffic is +routed for the given *\*. +``` + +```{cfgcmd} set protocols static route6 \ interface \ disable + +Disables interface-based IPv6 static route. +``` + +```{cfgcmd} set protocols static route6 \ interface \ distance \ + +Defines next-hop distance for this route, routes with smaller administrative +distance are elected prior to those with a higher distance. + +Range is 1 to 255, default is 1. +``` + +```{cfgcmd} set protocols static route6 \ interface \ segments \ + +It is possible to specify a static route for ipv6 prefixes using an +SRv6 segments instruction. The ``/`` separator can be used to specify +multiple segment instructions. + +Example: + +:::{code-block} none +set protocols static route6 2001:db8:1000::/36 interface eth0 segments '2001:db8:aaaa::7/2002::4/2002::3/2002::2' +::: +``` + + +### IPv6 BFD + +```{cfgcmd} set protocols static route6 \ next-hop \ bfd + +Configure a static route for *\* using gateway *\* and use the +gateway address as BFD peer destination address. +``` + +```{cfgcmd} set protocols static route6 \ next-hop \ bfd profile \ + +Configure a static route for *\* using gateway *\* and use the +gateway address as BFD peer destination address with BFD profile *\*. +``` + +```{cfgcmd} set protocols static route6 \ next-hop \ bfd multi-hop source-address \ + +Configure a static route for *\* using gateway *\* and use the +gateway address as BFD peer destination address with source address +*\* but initiate a multi-hop session. +``` + + +### IPv6 Reject Routes + +```{cfgcmd} set protocol static route6 \ reject + +Defines route which emits an ICMP unreachable when matched. +``` + +```{cfgcmd} set protocols static route6 \ reject distance \ + +Defines distance for this route, routes with smaller administrative +distance are elected prior to those with a higher distance. +``` + +```{cfgcmd} set protocols static route6 \ reject tag \ + +Sets a tag for this route. +``` + + +### IPv6 Blackhole Routes + +```{cfgcmd} set protocols static route6 \ blackhole + +Use this command to configure a "black-hole" route on the router. A +black-hole route is a route for which the system silently discard packets +that are matched. This prevents networks leaking out public interfaces, but +it does not prevent them from being used as a more specific route inside your +network. +``` + +```{cfgcmd} set protocols static route6 \ blackhole distance \ + +Defines blackhole distance for this route, routes with smaller administrative +distance are elected prior to those with a higher distance. +``` + +```{cfgcmd} set protocols static route6 \ blackhole tag \ + +Sets a tag for this route. +``` + + +## Alternate Routing Tables + +Alternate routing tables are used with policy based routing by utilizing +{ref}`vrf`. diff --git a/docs/configuration/protocols/md-traffic-engineering.md b/docs/configuration/protocols/md-traffic-engineering.md new file mode 100644 index 00000000..832023a7 --- /dev/null +++ b/docs/configuration/protocols/md-traffic-engineering.md @@ -0,0 +1,54 @@ +(traffic-engineering)= + +# Traffic Engineering + +Traffic Engineering (TE) is possibility to send traffic from node to node using +alternative path. + +## Common link parameters + +Traffic Engineering parameters are used for both IS-IS and OSPF (not supported yet). + +```{cfgcmd} set protocols traffic-engineering admin-group \ bit-position \ + +Create Administrative group and assosiate bit position with it. These groups can be +used in the following commands. + +\ can have value 0-31. There cannot be two groups with same bit position. +``` + + +```{cfgcmd} set protocols traffic-engineering interface \ admin-group \ + +Set administrative group for interface \. Multiple values can be provided. +``` + + +```{cfgcmd} set protocols traffic-engineering interface \ max-bandwidth \ + +Set maximum bandwidth for interface \. Value given in Mbits per second. +``` + + +```{cfgcmd} set protocols traffic-engineering interface \ max-reservable-bandwidth \ + +Set maximum reservable bandwidth for interface \. Value given in Mbits per second. +``` + +## IS-IS TE Configuration + +Traffic Engineering (TE) can be enabled and exported for IS-IS +using the following commands: + +```{cfgcmd} set protocols isis traffic-engineering enable + +Enable Traffic Engineering for IS-IS. +``` +```{cfgcmd} set protocols isis traffic-engineering export + +Export Traffic Engineering data to neighbors. +``` +```{cfgcmd} set protocols isis traffic-engineering address \ + +Configure IPv4 address for MPLS-TE. +``` \ No newline at end of file diff --git a/docs/configuration/service/md-broadcast-relay.md b/docs/configuration/service/md-broadcast-relay.md new file mode 100644 index 00000000..4202ad6b --- /dev/null +++ b/docs/configuration/service/md-broadcast-relay.md @@ -0,0 +1,70 @@ +(udp-broadcast-relay)= + +# UDP Broadcast Relay + +Certain vendors use broadcasts to identify their equipment within one ethernet +segment. Unfortunately if you split your network with multiple VLANs you loose +the ability of identifying your equipment. + +This is where "UDP broadcast relay" comes into play! It will forward received +broadcasts to other configured networks. + +Every UDP port which will be forward requires one unique ID. Currently we +support 99 IDs! + +## Configuration + +```{cfgcmd} set service broadcast-relay id \ 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 new file mode 100644 index 00000000..a575f947 --- /dev/null +++ b/docs/configuration/service/md-config-sync.md @@ -0,0 +1,164 @@ +(config-sync)= + +# Config Sync + +Configuration synchronization (config sync) is a feature of VyOS that +permits synchronization of the configuration of one VyOS router to +another in a network. + +The main benefit to configuration synchronization is that it eliminates having +to manually replicate configuration changes made on the primary router to the +secondary (replica) router. + +The writing of the configuration to the secondary router is performed through +the VyOS HTTP API. The user can specify which portion(s) of the configuration will +be synchronized and the mode to use - whether to replace or add. + +To prevent issues with divergent configurations between the pair of routers, +synchronization is strictly unidirectional from primary to replica. Both +routers should be online and run the same version of VyOS. + +## Configuration + +```{cfgcmd} set service config-sync secondary \ + +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 new file mode 100644 index 00000000..4aad6283 --- /dev/null +++ b/docs/configuration/service/md-conntrack-sync.md @@ -0,0 +1,321 @@ +(conntrack-sync)= + +# Conntrack Sync + +One of the important features built on top of the Netfilter framework is +connection tracking. Connection tracking allows the kernel to keep track of all +logical network connections or sessions, and thereby relate all of the packets +which may make up that connection. NAT relies on this information to translate +all related packets in the same way, and iptables can use this information to +act as a stateful firewall. + +The connection state however is completely independent of any upper-level +state, such as TCP's or SCTP's state. Part of the reason for this is that when +merely forwarding packets, i.e. no local delivery, the TCP engine may not +necessarily be invoked at all. Even connectionless-mode transmissions such as +UDP, IPsec (AH/ESP), GRE and other tunneling protocols have, at least, a pseudo +connection state. The heuristic for such protocols is often based upon a preset +timeout value for inactivity, after whose expiration a Netfilter connection is +dropped. + +Each Netfilter connection is uniquely identified by a (layer-3 protocol, source +address, destination address, layer-4 protocol, layer-4 key) tuple. The layer-4 +key depends on the transport protocol; for TCP/UDP it is the port numbers, for +tunnels it can be their tunnel ID, but otherwise is just zero, as if it were +not part of the tuple. To be able to inspect the TCP port in all cases, packets +will be mandatorily defragmented. + +It is possible to use either Multicast or Unicast to sync conntrack traffic. +Most examples below show Multicast, but unicast can be specified by using the +"peer" keyword after the specified interface, as in the following example: + +{cfgcmd}`set service conntrack-sync interface eth0 peer 192.168.0.250` + +## Configuration + +```{cfgcmd} set service conntrack-sync accept-protocol + +Accept only certain protocols: You may want to replicate the state of flows +depending on their layer 4 protocol. + +Protocols are: tcp, sctp, dccp, udp, icmp and ipv6-icmp. +``` + + +```{cfgcmd} set service conntrack-sync event-listen-queue-size \ + +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 entries to, if not using Multicast +configuration from 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 disables the external cache and directly injects the flow-states into the +in-kernel Connection Tracking System of the backup firewall. +``` + + +```{cfgcmd} set service conntrack-sync purge-timeout \ + +Timeout (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 new file mode 100644 index 00000000..f0556652 --- /dev/null +++ b/docs/configuration/service/md-console-server.md @@ -0,0 +1,139 @@ +(console-server)= + +# Console Server + +Starting of with VyOS 1.3 (equuleus) we added support for running VyOS as an +Out-of-Band Management device which provides remote access by means of SSH to +directly attached serial interfaces. + +Serial interfaces can be any interface which is directly connected to the CPU +or chipset (mostly known as a ttyS interface in Linux) or any other USB to +serial converter (Prolific PL2303 or FTDI FT232/FT4232 based chips). + +If you happened to use a Cisco NM-16A - Sixteen Port Async Network Module or +NM-32A - Thirty-two Port Async Network Module - this is your VyOS replacement. + +For USB port information please refor to: {ref}`hardware_usb`. + +## Configuration + +Between computers, the most common configuration used was "8N1": eight bit +characters, with one start bit, one stop bit, and no parity bit. Thus 10 Baud +times are used to send a single character, and so dividing the signalling +bit-rate by ten results in the overall transmission speed in characters per +second. This is also the default setting if none of those options are defined. + +```{cfgcmd} set service console-server device \ 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 successful authentication the user will be directly dropped to +the connected serial device. + +:::{hint} +Multiple users can connect to the same serial device but only +one is allowed to write to the console port. +::: +``` + +## Operation + +```{opcmd} show console-server ports + +Show configured serial ports and their respective interface configuration. + +:::{code-block} none +vyos@vyos:~$ show console-server ports +usb0b2.4p1.0 on /dev/serial/by-bus/usb0b2.4p1.0@ at 9600n +::: +``` + + +```{opcmd} show console-server user + +Show currently connected users. + +:::{code-block} none +vyos@vyos:~$ show console-server user +usb0b2.4p1.0 up vyos@localhost +::: +``` +```{opcmd} connect console \ + +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 new file mode 100644 index 00000000..a4a10109 --- /dev/null +++ b/docs/configuration/service/md-dhcp-relay.md @@ -0,0 +1,205 @@ +(dhcp-relay)= + +# DHCP Relay + +If you want your router to forward DHCP requests to an external DHCP server +you can configure the system to act as a DHCP relay agent. The DHCP relay +agent works with IPv4 and IPv6 addresses. + +All interfaces used for the DHCP relay must be configured. This includes the +uplink to the DHCP server. + +## IPv4 relay + +### Configuration + +```{cfgcmd} set service dhcp-relay interface \ + +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 new file mode 100644 index 00000000..721d6d4a --- /dev/null +++ b/docs/configuration/service/md-dhcp-server.md @@ -0,0 +1,1178 @@ +(dhcp-server)= + +# DHCP Server + +VyOS uses Kea DHCP server for both IPv4 and IPv6 address assignment. + +## IPv4 server + +The network topology is declared by shared-network-name and the subnet +declarations. The DHCP service can serve multiple shared networks, with each +shared network having 1 or more subnets. Each subnet must be present on an +interface. A range can be declared inside a subnet to define a pool of dynamic +addresses. Multiple ranges can be defined and can contain holes. Static +mappings can be set to assign "static" addresses to clients based on their MAC +address. + +### Configuration + +```{cfgcmd} set service dhcp-server hostfile-update + + Create DNS record per client lease, by adding clients to /etc/hosts file. + Entry will have format: `_.` +``` + + +```{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 `