From 038b3a3a2ad91f67f074ba05a35d800c3dac2c07 Mon Sep 17 00:00:00 2001 From: Yuriy Andamasov Date: Sat, 2 May 2026 21:13:13 +0300 Subject: feat(swap-circinus): add incremental RST-to-MyST swap mechanism MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Backport of the swap mechanism from feat/incremental-myst-swap onto the circinus release branch. Built directly on top of origin/circinus, so the underlying RST tree is circinus's (not current's). Mechanism: - scripts/import_myst.py — import md from myst/* with md- prefix - scripts/swap_sources.py — rename md-{name}.md → {name}.md before Sphinx builds, restore after; writes _build/_swap_state.json and _build/_swap_exclude.txt - docs/Makefile — html/dirhtml/pdf/livehtml all run swap → build → trap restore; explicit `swap` and `restore` targets too - docs/conf.py — MyST extensions enabled; swap exclude_patterns loader; _prefer_webp builder hook so html prefers webp over png Content (all from origin/myst/circinus): - 253 md-prefixed pages alongside each {name}.rst counterpart - 1 plain MyST-only page kept at canonical name (docs/copyright.md, no .rst counterpart) - 182 .webp images added (circinus release previously had only PNG/JPG; this PR brings webp into circinus alongside the originals) - docs/_swap.txt populated with all 253 stems → MyST is served by default; revert a page by removing its stem from _swap.txt 🤖 Generated by [robots](https://vyos.io) --- docs/Makefile | 40 +- docs/_static/images/1u_vyos_back.webp | Bin 0 -> 274242 bytes docs/_static/images/1u_vyos_front.webp | Bin 0 -> 179238 bytes docs/_static/images/1u_vyos_front_10ge_open_1.webp | Bin 0 -> 753068 bytes docs/_static/images/1u_vyos_front_10ge_open_2.webp | Bin 0 -> 927384 bytes docs/_static/images/1u_vyos_front_10ge_open_3.webp | Bin 0 -> 728730 bytes docs/_static/images/1u_vyos_front_10ge_open_4.webp | Bin 0 -> 1029796 bytes docs/_static/images/1u_vyos_front_open_1.webp | Bin 0 -> 609946 bytes docs/_static/images/1u_vyos_front_open_2.webp | Bin 0 -> 816692 bytes docs/_static/images/1u_vyos_front_open_3.webp | Bin 0 -> 865004 bytes .../images/480px-Acrosser_ANDJ190N1_Back.webp | Bin 0 -> 7182 bytes .../images/480px-Acrosser_ANDJ190N1_Front.webp | Bin 0 -> 7064 bytes docs/_static/images/600px-Partaker-i5.webp | Bin 0 -> 22500 bytes docs/_static/images/ESP_AH.webp | Bin 0 -> 22368 bytes .../images/IPSec_close_action_settings.webp | Bin 0 -> 16040 bytes docs/_static/images/L3VPN_hub_and_spoke.webp | Bin 0 -> 49718 bytes docs/_static/images/PA-ESP-group.webp | Bin 0 -> 11374 bytes docs/_static/images/PA-IKE-GW-1.webp | Bin 0 -> 13074 bytes docs/_static/images/PA-IKE-GW-2.webp | Bin 0 -> 8956 bytes docs/_static/images/PA-IKE-group.webp | Bin 0 -> 12356 bytes docs/_static/images/PA-IPsec-tunnel.webp | Bin 0 -> 13830 bytes docs/_static/images/PA-tunnel-1.webp | Bin 0 -> 6454 bytes docs/_static/images/PA-tunnel-2.webp | Bin 0 -> 7788 bytes docs/_static/images/PA-tunnel-3.webp | Bin 0 -> 6096 bytes docs/_static/images/VyOS_Dual-Hub_DMVPN.webp | Bin 0 -> 38696 bytes docs/_static/images/Wan_load_balancing1.webp | Bin 0 -> 80134 bytes .../images/Wan_load_balancing_exclude1.webp | Bin 0 -> 81692 bytes docs/_static/images/ansible.webp | Bin 0 -> 35842 bytes docs/_static/images/apu4_desk_1.webp | Bin 0 -> 188746 bytes docs/_static/images/apu4_desk_2.webp | Bin 0 -> 101176 bytes docs/_static/images/apu4_desk_3.webp | Bin 0 -> 506950 bytes docs/_static/images/apu4_desk_4.webp | Bin 0 -> 502830 bytes docs/_static/images/apu4_rack_1.webp | Bin 0 -> 163172 bytes docs/_static/images/apu4_rack_2.webp | Bin 0 -> 383592 bytes docs/_static/images/apu4_rack_3.webp | Bin 0 -> 704064 bytes docs/_static/images/apu4_rack_4.webp | Bin 0 -> 1176470 bytes docs/_static/images/apu4_rack_5.webp | Bin 0 -> 948240 bytes docs/_static/images/apu4_rack_vyos_print.webp | Bin 0 -> 354582 bytes docs/_static/images/aws.webp | Bin 0 -> 22146 bytes docs/_static/images/blueprint-dmvpn.webp | Bin 0 -> 20178 bytes docs/_static/images/boot-options.webp | Bin 0 -> 24560 bytes docs/_static/images/cisco-vpn-ipsec.webp | Bin 0 -> 17008 bytes docs/_static/images/cloud-aws-01.webp | Bin 0 -> 17216 bytes docs/_static/images/cloud-aws-02.webp | Bin 0 -> 31212 bytes docs/_static/images/cloud-aws-03.webp | Bin 0 -> 17688 bytes docs/_static/images/cloud-aws-04.webp | Bin 0 -> 47288 bytes docs/_static/images/cloud-aws-05.webp | Bin 0 -> 40486 bytes docs/_static/images/cloud-aws-06.webp | Bin 0 -> 45608 bytes docs/_static/images/cloud-aws-07.webp | Bin 0 -> 29012 bytes docs/_static/images/cloud-aws-08.webp | Bin 0 -> 7400 bytes docs/_static/images/cloud-azure-01.webp | Bin 0 -> 34472 bytes docs/_static/images/cloud-azure-02.webp | Bin 0 -> 20216 bytes docs/_static/images/cloud-azure-03.webp | Bin 0 -> 17942 bytes docs/_static/images/cloud-azure-04.webp | Bin 0 -> 34348 bytes docs/_static/images/cloud-azure-05.webp | Bin 0 -> 26358 bytes docs/_static/images/cloud-azure-06.webp | Bin 0 -> 18790 bytes docs/_static/images/cloud-gcp-01.webp | Bin 0 -> 1900 bytes docs/_static/images/cloud-gcp-02.webp | Bin 0 -> 19684 bytes docs/_static/images/cloud-gcp-03.webp | Bin 0 -> 39188 bytes docs/_static/images/cloud-gcp-04.webp | Bin 0 -> 6756 bytes docs/_static/images/cloud-gcp-05.webp | Bin 0 -> 9378 bytes .../images/dhcp-relay-through-gre-bridge.webp | Bin 0 -> 12810 bytes docs/_static/images/dual-hub-DMVPN.webp | Bin 0 -> 36020 bytes docs/_static/images/eve-ng-vyos.webp | Bin 0 -> 956 bytes .../images/firewall-and-vrf-blueprints.webp | Bin 0 -> 28402 bytes docs/_static/images/firewall-bridge-forward.webp | Bin 0 -> 8986 bytes docs/_static/images/firewall-bridge-input.webp | Bin 0 -> 13910 bytes docs/_static/images/firewall-bridge-output.webp | Bin 0 -> 12086 bytes .../images/firewall-flowtable-packet-flow.webp | Bin 0 -> 15128 bytes docs/_static/images/firewall-fwd-packet-flow.webp | Bin 0 -> 10202 bytes docs/_static/images/firewall-gral-packet-flow.webp | Bin 0 -> 18066 bytes .../_static/images/firewall-input-packet-flow.webp | Bin 0 -> 13918 bytes docs/_static/images/firewall-netfilter.webp | Bin 0 -> 10638 bytes docs/_static/images/firewall-traditional.webp | Bin 0 -> 4404 bytes docs/_static/images/firewall-zonebased.webp | Bin 0 -> 6012 bytes docs/_static/images/gns3-01.webp | Bin 0 -> 10250 bytes docs/_static/images/gns3-02.webp | Bin 0 -> 67826 bytes docs/_static/images/gns3-03.webp | Bin 0 -> 7798 bytes docs/_static/images/gns3-04.webp | Bin 0 -> 12946 bytes docs/_static/images/gns3-05.webp | Bin 0 -> 12544 bytes docs/_static/images/gns3-06.webp | Bin 0 -> 9376 bytes docs/_static/images/gns3-07.webp | Bin 0 -> 9940 bytes docs/_static/images/gns3-08.webp | Bin 0 -> 9724 bytes docs/_static/images/gns3-09.webp | Bin 0 -> 7428 bytes docs/_static/images/gns3-10.webp | Bin 0 -> 10530 bytes docs/_static/images/gns3-11.webp | Bin 0 -> 63708 bytes docs/_static/images/gns3-12.webp | Bin 0 -> 21712 bytes docs/_static/images/gns3-13.webp | Bin 0 -> 18354 bytes docs/_static/images/gns3-14.webp | Bin 0 -> 9784 bytes docs/_static/images/gns3-15.webp | Bin 0 -> 16520 bytes docs/_static/images/gns3-16.webp | Bin 0 -> 17928 bytes docs/_static/images/gns3-17.webp | Bin 0 -> 62974 bytes docs/_static/images/gns3-20.webp | Bin 0 -> 19712 bytes docs/_static/images/gns3-21.webp | Bin 0 -> 7950 bytes docs/_static/images/gns3-215.webp | Bin 0 -> 16012 bytes docs/_static/images/gns3-22.webp | Bin 0 -> 17222 bytes docs/_static/images/gowin-01.webp | Bin 0 -> 24732 bytes docs/_static/images/gowin-02.webp | Bin 0 -> 224350 bytes docs/_static/images/gowin-03.webp | Bin 0 -> 255730 bytes docs/_static/images/gowin-04.webp | Bin 0 -> 223808 bytes .../_static/images/inter-vrf-routing-vrf-lite.webp | Bin 0 -> 36860 bytes docs/_static/images/ipsec-vyos-pa.webp | Bin 0 -> 22972 bytes docs/_static/images/json.webp | Bin 0 -> 34856 bytes docs/_static/images/key.webp | Bin 0 -> 88726 bytes docs/_static/images/keypairs.webp | Bin 0 -> 28220 bytes docs/_static/images/lac-lns-diagram.webp | Bin 0 -> 11148 bytes docs/_static/images/lac-lns-winclient.webp | Bin 0 -> 20246 bytes docs/_static/images/ldapone.webp | Bin 0 -> 51782 bytes docs/_static/images/ldaptwo.webp | Bin 0 -> 34450 bytes docs/_static/images/mainschema.webp | Bin 0 -> 25286 bytes docs/_static/images/multicast-basic.webp | Bin 0 -> 15932 bytes docs/_static/images/nat_before_vpn_topology.webp | Bin 0 -> 16422 bytes docs/_static/images/nmp1.webp | Bin 0 -> 30280 bytes docs/_static/images/nmp2.webp | Bin 0 -> 23324 bytes docs/_static/images/nmp3.webp | Bin 0 -> 60334 bytes docs/_static/images/nmp4.webp | Bin 0 -> 40784 bytes docs/_static/images/nmp5.webp | Bin 0 -> 63412 bytes docs/_static/images/nmp6.webp | Bin 0 -> 73202 bytes docs/_static/images/nmp7.webp | Bin 0 -> 35884 bytes docs/_static/images/openvpn_site2site_diagram.webp | Bin 0 -> 9624 bytes docs/_static/images/pbr_example_1.webp | Bin 0 -> 17460 bytes .../images/policy-based-ipsec-and-firewall.webp | Bin 0 -> 25992 bytes docs/_static/images/pppoe-ipv6-pd-diagram.webp | Bin 0 -> 5368 bytes docs/_static/images/project.webp | Bin 0 -> 8396 bytes docs/_static/images/qos1.webp | Bin 0 -> 71136 bytes docs/_static/images/qos10.webp | Bin 0 -> 187728 bytes docs/_static/images/qos2.webp | Bin 0 -> 74934 bytes docs/_static/images/qos3.webp | Bin 0 -> 30634 bytes docs/_static/images/qos4.webp | Bin 0 -> 30498 bytes docs/_static/images/qos5.webp | Bin 0 -> 8820 bytes docs/_static/images/qos6.webp | Bin 0 -> 80314 bytes docs/_static/images/qos7.webp | Bin 0 -> 32416 bytes docs/_static/images/qos8.webp | Bin 0 -> 32812 bytes docs/_static/images/qos9.webp | Bin 0 -> 30238 bytes docs/_static/images/reset-password-step-1.webp | Bin 0 -> 11746 bytes docs/_static/images/reset-password-step-2.webp | Bin 0 -> 13622 bytes docs/_static/images/reset-password-step-3.webp | Bin 0 -> 11670 bytes docs/_static/images/reset-password-step-4.webp | Bin 0 -> 10236 bytes docs/_static/images/reset-password-step-5.webp | Bin 0 -> 51232 bytes docs/_static/images/service.webp | Bin 0 -> 83530 bytes .../images/service_conntrack_sync-schema.webp | Bin 0 -> 16600 bytes docs/_static/images/service_dhcp-relay01.webp | Bin 0 -> 27266 bytes docs/_static/images/service_dhcpv6-relay01.webp | Bin 0 -> 25882 bytes ...vice_snmp_communication_principles_diagram.webp | Bin 0 -> 53888 bytes docs/_static/images/sg.webp | Bin 0 -> 19282 bytes docs/_static/images/sticky-connections.webp | Bin 0 -> 12094 bytes docs/_static/images/traffic.webp | Bin 0 -> 21794 bytes docs/_static/images/uefi_secureboot_01.webp | Bin 0 -> 22238 bytes docs/_static/images/uefi_secureboot_02.webp | Bin 0 -> 6232 bytes docs/_static/images/uefi_secureboot_03.webp | Bin 0 -> 6568 bytes docs/_static/images/uefi_secureboot_04.webp | Bin 0 -> 3682 bytes docs/_static/images/uefi_secureboot_05.webp | Bin 0 -> 3308 bytes docs/_static/images/uefi_secureboot_06.webp | Bin 0 -> 3406 bytes docs/_static/images/uefi_secureboot_07.webp | Bin 0 -> 5726 bytes docs/_static/images/virt-libvirt-01.webp | Bin 0 -> 13058 bytes docs/_static/images/virt-libvirt-02.webp | Bin 0 -> 14020 bytes docs/_static/images/virt-libvirt-03.webp | Bin 0 -> 9180 bytes docs/_static/images/virt-libvirt-04.webp | Bin 0 -> 12254 bytes docs/_static/images/virt-libvirt-05.webp | Bin 0 -> 14698 bytes docs/_static/images/virt-libvirt-06.webp | Bin 0 -> 46772 bytes docs/_static/images/virt-libvirt-qc-01.webp | Bin 0 -> 13206 bytes docs/_static/images/virt-libvirt-qc-02.webp | Bin 0 -> 10610 bytes docs/_static/images/virt-libvirt-qc-03.webp | Bin 0 -> 41558 bytes docs/_static/images/vpn_dmvpn_topology01.webp | Bin 0 -> 35722 bytes docs/_static/images/vpn_s2s_ikev2.webp | Bin 0 -> 26994 bytes docs/_static/images/vpn_s2s_ikev2_c.webp | Bin 0 -> 30564 bytes docs/_static/images/vrf-example-topology-01.webp | Bin 0 -> 19256 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.webp | Bin 0 -> 20016 bytes docs/_static/images/vyos_1_4_nat66_simple.webp | Bin 0 -> 5488 bytes .../images/vyos_1_5_nat66_dhcpv6_wdummy.webp | Bin 0 -> 82130 bytes docs/_static/images/vyos_arista_bond_lacp.webp | Bin 0 -> 24962 bytes docs/_static/images/vyosnew-downloads.webp | Bin 0 -> 37012 bytes docs/_static/images/wireguard_qrcode.webp | Bin 0 -> 57382 bytes .../images/wireguard_site2site_diagram.webp | Bin 0 -> 9020 bytes docs/_static/images/zone-policy-diagram.webp | Bin 0 -> 54546 bytes docs/_swap.txt | 261 +++ docs/automation/md-cloud-init.md | 383 ++++ docs/automation/md-command-scripting.md | 225 ++ docs/automation/md-index.md | 16 + docs/automation/md-vyos-ansible.md | 89 + docs/automation/md-vyos-api.md | 571 ++++++ docs/automation/md-vyos-govyos.md | 191 ++ docs/automation/md-vyos-napalm.md | 142 ++ docs/automation/md-vyos-netmiko.md | 72 + docs/automation/md-vyos-pyvyos.md | 138 ++ docs/automation/md-vyos-salt.md | 218 ++ docs/automation/terraform/md-index.md | 31 + docs/automation/terraform/md-terraformAWS.md | 537 +++++ docs/automation/terraform/md-terraformAZ.md | 487 +++++ docs/automation/terraform/md-terraformGoogle.md | 698 +++++++ docs/automation/terraform/md-terraformvSphere.md | 385 ++++ docs/conf.py | 24 +- .../DHCPRelay_through_GRE/_include/topology.webp | Bin 0 -> 20146 bytes .../md-DHCPRelay_through_GRE.md | 96 + .../autotest/L3VPN_EVPN/_include/topology.webp | Bin 0 -> 49416 bytes .../autotest/L3VPN_EVPN/md-L3VPN_EVPN.md | 250 +++ .../OpenVPN_with_LDAP/_include/topology.webp | Bin 0 -> 11392 bytes .../OpenVPN_with_LDAP/md-OpenVPN_with_LDAP.md | 235 +++ .../autotest/Wireguard/_include/topology.webp | Bin 0 -> 31422 bytes .../autotest/Wireguard/md-Wireguard.md | 113 ++ .../autotest/tunnelbroker/_include/topology.webp | Bin 0 -> 8464 bytes .../autotest/tunnelbroker/md-tunnelbroker.md | 209 ++ docs/configexamples/md-ansible.md | 196 ++ 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 | 538 +++++ docs/configexamples/md-firewall.md | 17 + docs/configexamples/md-fwall-and-bridge.md | 488 +++++ docs/configexamples/md-fwall-and-vrf.md | 119 ++ docs/configexamples/md-ha.md | 556 +++++ docs/configexamples/md-index.md | 63 + .../md-inter-vrf-routing-vrf-lite.md | 793 ++++++++ docs/configexamples/md-ipsec-cisco-policy-based.md | 357 ++++ docs/configexamples/md-ipsec-cisco-route-based.md | 402 ++++ docs/configexamples/md-ipsec-pa-route-based.md | 420 ++++ docs/configexamples/md-l3vpn-hub-and-spoke.md | 1096 ++++++++++ docs/configexamples/md-lac-lns.md | 178 ++ docs/configexamples/md-nmp.md | 44 + docs/configexamples/md-ospf-unnumbered.md | 118 ++ .../md-policy-based-ipsec-and-firewall.md | 268 +++ docs/configexamples/md-pppoe-ipv6-basic.md | 111 + docs/configexamples/md-qos.md | 203 ++ docs/configexamples/md-segment-routing-isis.md | 277 +++ docs/configexamples/md-site-2-site-cisco.md | 167 ++ docs/configexamples/md-wan-load-balancing.md | 179 ++ docs/configexamples/md-zone-policy.md | 415 ++++ docs/configuration/container/md-index.md | 479 +++++ docs/configuration/firewall/md-bridge.md | 868 ++++++++ docs/configuration/firewall/md-flowtables.md | 189 ++ docs/configuration/firewall/md-global-options.md | 259 +++ docs/configuration/firewall/md-groups.md | 526 +++++ docs/configuration/firewall/md-index.md | 236 +++ docs/configuration/firewall/md-ipv4.md | 2142 ++++++++++++++++++++ docs/configuration/firewall/md-ipv6.md | 2131 +++++++++++++++++++ docs/configuration/firewall/md-zone.md | 221 ++ docs/configuration/highavailability/md-index.md | 527 +++++ docs/configuration/interfaces/md-bonding.md | 753 +++++++ 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 | 855 ++++++++ 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 | 304 +++ .../interfaces/md-virtual-ethernet.md | 119 ++ docs/configuration/interfaces/md-vti.md | 53 + docs/configuration/interfaces/md-vxlan.md | 373 ++++ docs/configuration/interfaces/md-wireguard.md | 441 ++++ docs/configuration/interfaces/md-wireless.md | 1012 +++++++++ docs/configuration/interfaces/md-wwan.md | 355 ++++ docs/configuration/loadbalancing/md-haproxy.md | 574 ++++++ docs/configuration/loadbalancing/md-index.md | 16 + docs/configuration/loadbalancing/md-wan.md | 303 +++ docs/configuration/md-index.md | 24 + docs/configuration/nat/md-cgnat.md | 200 ++ docs/configuration/nat/md-index.md | 13 + docs/configuration/nat/md-nat44.md | 800 ++++++++ docs/configuration/nat/md-nat64.md | 75 + docs/configuration/nat/md-nat66.md | 241 +++ 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 | 208 ++ docs/configuration/policy/md-extcommunity-list.md | 33 + docs/configuration/policy/md-index.md | 55 + .../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 | 55 + docs/configuration/protocols/md-babel.md | 214 ++ docs/configuration/protocols/md-bfd.md | 205 ++ docs/configuration/protocols/md-bgp.md | 1414 +++++++++++++ docs/configuration/protocols/md-failover.md | 123 ++ docs/configuration/protocols/md-igmp-proxy.md | 79 + docs/configuration/protocols/md-index.md | 25 + docs/configuration/protocols/md-isis.md | 822 ++++++++ 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 | 304 +++ 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 | 419 ++++ .../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 | 380 ++++ docs/configuration/service/md-console-server.md | 139 ++ docs/configuration/service/md-dhcp-relay.md | 225 ++ 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 | 27 + docs/configuration/service/md-ipoe-server.md | 512 +++++ docs/configuration/service/md-lldp.md | 154 ++ docs/configuration/service/md-mdns.md | 138 ++ 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 | 259 +++ 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 | 270 +++ 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 | 46 + 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 | 26 + 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 | 1403 +++++++++++++ docs/configuration/vpn/ipsec/md-index.md | 10 + docs/configuration/vpn/ipsec/md-ipsec_general.md | 442 ++++ .../vpn/ipsec/md-remoteaccess_ipsec.md | 184 ++ docs/configuration/vpn/ipsec/md-site2site_ipsec.md | 829 ++++++++ .../vpn/ipsec/md-troubleshooting_ipsec.md | 310 +++ docs/configuration/vpn/md-dmvpn.md | 446 ++++ docs/configuration/vpn/md-index.md | 13 + docs/configuration/vpn/md-l2tp.md | 624 ++++++ docs/configuration/vpn/md-openconnect.md | 363 ++++ docs/configuration/vpn/md-pptp.md | 594 ++++++ docs/configuration/vpn/md-rsa-keys.md | 116 ++ docs/configuration/vpn/md-sstp.md | 698 +++++++ docs/configuration/vrf/md-index.md | 621 ++++++ 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 | 174 ++ docs/installation/cloud/md-azure.md | 88 + docs/installation/cloud/md-gcp.md | 60 + docs/installation/cloud/md-index.md | 10 + docs/installation/cloud/md-oracle.md | 23 + docs/installation/md-bare-metal.md | 626 ++++++ docs/installation/md-image.md | 113 ++ docs/installation/md-index.md | 30 + docs/installation/md-install.md | 464 +++++ docs/installation/md-secure-boot.md | 193 ++ docs/installation/md-update.md | 104 + docs/installation/virtual/md-docker.md | 70 + docs/installation/virtual/md-eve-ng.md | 22 + 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 | 62 + docs/installation/virtual/md-vmware.md | 38 + docs/introducing/md-about.md | 21 + docs/introducing/md-history.md | 127 ++ docs/md-404.md | 13 + docs/md-cli.md | 1187 +++++++++++ docs/md-coverage.md | 59 + docs/md-documentation.md | 442 ++++ docs/md-index.md | 116 ++ docs/md-quick-start.md | 381 ++++ docs/operation/md-boot-options.md | 56 + docs/operation/md-index.md | 12 + docs/operation/md-information.md | 163 ++ 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 | 45 + 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 +++++ 438 files changed, 67689 insertions(+), 11 deletions(-) create mode 100644 docs/_static/images/1u_vyos_back.webp create mode 100644 docs/_static/images/1u_vyos_front.webp create mode 100644 docs/_static/images/1u_vyos_front_10ge_open_1.webp create mode 100644 docs/_static/images/1u_vyos_front_10ge_open_2.webp create mode 100644 docs/_static/images/1u_vyos_front_10ge_open_3.webp create mode 100644 docs/_static/images/1u_vyos_front_10ge_open_4.webp create mode 100644 docs/_static/images/1u_vyos_front_open_1.webp create mode 100644 docs/_static/images/1u_vyos_front_open_2.webp create mode 100644 docs/_static/images/1u_vyos_front_open_3.webp create mode 100644 docs/_static/images/480px-Acrosser_ANDJ190N1_Back.webp create mode 100644 docs/_static/images/480px-Acrosser_ANDJ190N1_Front.webp create mode 100644 docs/_static/images/600px-Partaker-i5.webp create mode 100644 docs/_static/images/ESP_AH.webp create mode 100644 docs/_static/images/IPSec_close_action_settings.webp create mode 100644 docs/_static/images/L3VPN_hub_and_spoke.webp create mode 100644 docs/_static/images/PA-ESP-group.webp create mode 100644 docs/_static/images/PA-IKE-GW-1.webp create mode 100644 docs/_static/images/PA-IKE-GW-2.webp create mode 100644 docs/_static/images/PA-IKE-group.webp create mode 100644 docs/_static/images/PA-IPsec-tunnel.webp create mode 100644 docs/_static/images/PA-tunnel-1.webp create mode 100644 docs/_static/images/PA-tunnel-2.webp create mode 100644 docs/_static/images/PA-tunnel-3.webp create mode 100644 docs/_static/images/VyOS_Dual-Hub_DMVPN.webp create mode 100644 docs/_static/images/Wan_load_balancing1.webp create mode 100644 docs/_static/images/Wan_load_balancing_exclude1.webp create mode 100644 docs/_static/images/ansible.webp create mode 100644 docs/_static/images/apu4_desk_1.webp create mode 100644 docs/_static/images/apu4_desk_2.webp create mode 100644 docs/_static/images/apu4_desk_3.webp create mode 100644 docs/_static/images/apu4_desk_4.webp create mode 100644 docs/_static/images/apu4_rack_1.webp create mode 100644 docs/_static/images/apu4_rack_2.webp create mode 100644 docs/_static/images/apu4_rack_3.webp create mode 100644 docs/_static/images/apu4_rack_4.webp create mode 100644 docs/_static/images/apu4_rack_5.webp create mode 100644 docs/_static/images/apu4_rack_vyos_print.webp create mode 100644 docs/_static/images/aws.webp create mode 100644 docs/_static/images/blueprint-dmvpn.webp create mode 100644 docs/_static/images/boot-options.webp create mode 100644 docs/_static/images/cisco-vpn-ipsec.webp create mode 100644 docs/_static/images/cloud-aws-01.webp create mode 100644 docs/_static/images/cloud-aws-02.webp create mode 100644 docs/_static/images/cloud-aws-03.webp create mode 100644 docs/_static/images/cloud-aws-04.webp create mode 100644 docs/_static/images/cloud-aws-05.webp create mode 100644 docs/_static/images/cloud-aws-06.webp create mode 100644 docs/_static/images/cloud-aws-07.webp create mode 100644 docs/_static/images/cloud-aws-08.webp create mode 100644 docs/_static/images/cloud-azure-01.webp create mode 100644 docs/_static/images/cloud-azure-02.webp create mode 100644 docs/_static/images/cloud-azure-03.webp create mode 100644 docs/_static/images/cloud-azure-04.webp create mode 100644 docs/_static/images/cloud-azure-05.webp create mode 100644 docs/_static/images/cloud-azure-06.webp create mode 100644 docs/_static/images/cloud-gcp-01.webp create mode 100644 docs/_static/images/cloud-gcp-02.webp create mode 100644 docs/_static/images/cloud-gcp-03.webp create mode 100644 docs/_static/images/cloud-gcp-04.webp create mode 100644 docs/_static/images/cloud-gcp-05.webp create mode 100644 docs/_static/images/dhcp-relay-through-gre-bridge.webp create mode 100644 docs/_static/images/dual-hub-DMVPN.webp create mode 100644 docs/_static/images/eve-ng-vyos.webp create mode 100644 docs/_static/images/firewall-and-vrf-blueprints.webp create mode 100644 docs/_static/images/firewall-bridge-forward.webp create mode 100644 docs/_static/images/firewall-bridge-input.webp create mode 100644 docs/_static/images/firewall-bridge-output.webp create mode 100644 docs/_static/images/firewall-flowtable-packet-flow.webp create mode 100644 docs/_static/images/firewall-fwd-packet-flow.webp create mode 100644 docs/_static/images/firewall-gral-packet-flow.webp create mode 100644 docs/_static/images/firewall-input-packet-flow.webp create mode 100644 docs/_static/images/firewall-netfilter.webp create mode 100644 docs/_static/images/firewall-traditional.webp create mode 100644 docs/_static/images/firewall-zonebased.webp create mode 100644 docs/_static/images/gns3-01.webp create mode 100644 docs/_static/images/gns3-02.webp create mode 100644 docs/_static/images/gns3-03.webp create mode 100644 docs/_static/images/gns3-04.webp create mode 100644 docs/_static/images/gns3-05.webp create mode 100644 docs/_static/images/gns3-06.webp create mode 100644 docs/_static/images/gns3-07.webp create mode 100644 docs/_static/images/gns3-08.webp create mode 100644 docs/_static/images/gns3-09.webp create mode 100644 docs/_static/images/gns3-10.webp create mode 100644 docs/_static/images/gns3-11.webp create mode 100644 docs/_static/images/gns3-12.webp create mode 100644 docs/_static/images/gns3-13.webp create mode 100644 docs/_static/images/gns3-14.webp create mode 100644 docs/_static/images/gns3-15.webp create mode 100644 docs/_static/images/gns3-16.webp create mode 100644 docs/_static/images/gns3-17.webp create mode 100644 docs/_static/images/gns3-20.webp create mode 100644 docs/_static/images/gns3-21.webp create mode 100644 docs/_static/images/gns3-215.webp create mode 100644 docs/_static/images/gns3-22.webp create mode 100644 docs/_static/images/gowin-01.webp create mode 100644 docs/_static/images/gowin-02.webp create mode 100644 docs/_static/images/gowin-03.webp create mode 100644 docs/_static/images/gowin-04.webp create mode 100644 docs/_static/images/inter-vrf-routing-vrf-lite.webp create mode 100644 docs/_static/images/ipsec-vyos-pa.webp create mode 100644 docs/_static/images/json.webp create mode 100644 docs/_static/images/key.webp create mode 100644 docs/_static/images/keypairs.webp create mode 100644 docs/_static/images/lac-lns-diagram.webp create mode 100644 docs/_static/images/lac-lns-winclient.webp create mode 100644 docs/_static/images/ldapone.webp create mode 100644 docs/_static/images/ldaptwo.webp create mode 100644 docs/_static/images/mainschema.webp create mode 100644 docs/_static/images/multicast-basic.webp create mode 100644 docs/_static/images/nat_before_vpn_topology.webp create mode 100644 docs/_static/images/nmp1.webp create mode 100644 docs/_static/images/nmp2.webp create mode 100644 docs/_static/images/nmp3.webp create mode 100644 docs/_static/images/nmp4.webp create mode 100644 docs/_static/images/nmp5.webp create mode 100644 docs/_static/images/nmp6.webp create mode 100644 docs/_static/images/nmp7.webp create mode 100644 docs/_static/images/openvpn_site2site_diagram.webp create mode 100644 docs/_static/images/pbr_example_1.webp create mode 100644 docs/_static/images/policy-based-ipsec-and-firewall.webp create mode 100644 docs/_static/images/pppoe-ipv6-pd-diagram.webp create mode 100644 docs/_static/images/project.webp create mode 100644 docs/_static/images/qos1.webp create mode 100644 docs/_static/images/qos10.webp create mode 100644 docs/_static/images/qos2.webp create mode 100644 docs/_static/images/qos3.webp create mode 100644 docs/_static/images/qos4.webp create mode 100644 docs/_static/images/qos5.webp create mode 100644 docs/_static/images/qos6.webp create mode 100644 docs/_static/images/qos7.webp create mode 100644 docs/_static/images/qos8.webp create mode 100644 docs/_static/images/qos9.webp create mode 100644 docs/_static/images/reset-password-step-1.webp create mode 100644 docs/_static/images/reset-password-step-2.webp create mode 100644 docs/_static/images/reset-password-step-3.webp create mode 100644 docs/_static/images/reset-password-step-4.webp create mode 100644 docs/_static/images/reset-password-step-5.webp create mode 100644 docs/_static/images/service.webp create mode 100644 docs/_static/images/service_conntrack_sync-schema.webp create mode 100644 docs/_static/images/service_dhcp-relay01.webp create mode 100644 docs/_static/images/service_dhcpv6-relay01.webp create mode 100644 docs/_static/images/service_snmp_communication_principles_diagram.webp create mode 100644 docs/_static/images/sg.webp create mode 100644 docs/_static/images/sticky-connections.webp create mode 100644 docs/_static/images/traffic.webp create mode 100644 docs/_static/images/uefi_secureboot_01.webp create mode 100644 docs/_static/images/uefi_secureboot_02.webp create mode 100644 docs/_static/images/uefi_secureboot_03.webp create mode 100644 docs/_static/images/uefi_secureboot_04.webp create mode 100644 docs/_static/images/uefi_secureboot_05.webp create mode 100644 docs/_static/images/uefi_secureboot_06.webp create mode 100644 docs/_static/images/uefi_secureboot_07.webp create mode 100644 docs/_static/images/virt-libvirt-01.webp create mode 100644 docs/_static/images/virt-libvirt-02.webp create mode 100644 docs/_static/images/virt-libvirt-03.webp create mode 100644 docs/_static/images/virt-libvirt-04.webp create mode 100644 docs/_static/images/virt-libvirt-05.webp create mode 100644 docs/_static/images/virt-libvirt-06.webp create mode 100644 docs/_static/images/virt-libvirt-qc-01.webp create mode 100644 docs/_static/images/virt-libvirt-qc-02.webp create mode 100644 docs/_static/images/virt-libvirt-qc-03.webp create mode 100644 docs/_static/images/vpn_dmvpn_topology01.webp create mode 100644 docs/_static/images/vpn_s2s_ikev2.webp create mode 100644 docs/_static/images/vpn_s2s_ikev2_c.webp create mode 100644 docs/_static/images/vrf-example-topology-01.webp 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 create mode 100644 docs/_static/images/vyos-sr-isis.webp create mode 100644 docs/_static/images/vyos_1_4_nat66_simple.webp create mode 100644 docs/_static/images/vyos_1_5_nat66_dhcpv6_wdummy.webp create mode 100644 docs/_static/images/vyos_arista_bond_lacp.webp create mode 100644 docs/_static/images/vyosnew-downloads.webp create mode 100644 docs/_static/images/wireguard_qrcode.webp create mode 100644 docs/_static/images/wireguard_site2site_diagram.webp 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..29ef3906 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -12,22 +12,42 @@ 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)/**' \ + "$(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/_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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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..d957688e --- /dev/null +++ b/docs/automation/md-cloud-init.md @@ -0,0 +1,383 @@ +--- +lastproofread: '2024-07-03' +--- + +(cloud-init)= + +# VyOS cloud-init + +Cloud and virtualized instances of VyOS are initialized using the +industry-standard cloud-init. Via cloud-init, the system performs tasks such as +injecting SSH keys and configuring the network. In addition, the user can +supply a custom configuration at the time of instance launch. + +## Config Sources + +VyOS support three types of config sources. + +- Metadata - Metadata is sourced by the cloud platform or hypervisor. + In some clouds, there is implemented as an HTTP endpoint at + `http://169.254.169.254`. +- Network configuration - This config source informs the system about the + network settings like IP addresses, routes, DNS. Available only in several + cloud and virtualization platforms. +- User-data - User-data is specified by the user. This config source offers + the ability to insert any CLI configuration commands into the configuration + before the first boot. + +## User-data + +Major cloud providers offer a means of providing user-data at the time of +instance launch. It can be provided as plain text or as base64-encoded text, +depending on cloud provider. Also, it can be compressed using gzip, which makes +sense with a long configuration commands list, because of the hard limit to +\~16384 bytes for the whole user-data. + +The easiest way to configure the system via user-data is the Cloud-config +syntax described below. + +## Cloud-config modules + +In VyOS, by default, enables only two modules: + +- `write_files` - this module allows to insert any files into the filesystem + before the first boot, for example, pre-generated encryption keys, + certificates, or even a whole `config.boot` file. The format is described + in the cloudinit documentation [Cloud-init-write_files]. +- `vyos_userdata` - the module accepts a list of CLI configuration commands + in a `vyos_config_commands` section, which gives an easy way to configure + the system during deployment. + +## cloud-config file format + +A cloud-config document is written in YAML. The file must begin +with `#cloud-config` line. The only supported top-level keys are +`vyos_config_commands` and `write_files`. The use of these keys is +described in the following two sections. + +## Initial Configuration + +The key used to designate a VyOS configuration is `vyos_config_commands`. +What follows is VyOS configuration using the "set-style" syntax. Both "set" +and "delete" commands are supported. + +Commands requirements: + +- One command per line. +- If command ends in a value, it must be inside single quotes. +- A single-quote symbol is not allowed inside command or value. + +The commands list produced by the `show configuration commands` command +on a VyOS router should comply with all the requirements, so it is easy +to get a proper commands list by copying it from another router. + +The configuration specified in the cloud-config document overwrites default +configuration values and values configured via Metadata. + +After the `vyos_config_commands` are executed, cloud-init will +automatically perform a `commit` and `save` operation. + +Here is an example cloud-config that appends configuration at the time of +first boot. + +```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' +``` + +### System Defaults/Fallbacks + +These are the VyOS defaults and fallbacks. + +- SSH is configured on port 22. +- `vyos`/`vyos` credentials if no others specified by data source. +- DHCP on first Ethernet interface if no network configuration is provided. + +All of these can be overridden using the configuration in user-data. + +## Command Execution at Initial Boot + +VyOS supports the execution of operational commands and linux commands at +initial boot. This is accomplished using `write_files` to certain +files in the /opt/vyatta/etc/config/scripts directory. Commands specified +in opt/vyatta/etc/config/scripts/vyos-preconfig-bootup.script are executed +prior to configuration. The +/opt/vyatta/etc/config/scripts/vyos-postconfig-bootup.script file contains +commands to be executed after configuration. In both cases, commands are +executed as the root user. + +Note that the /opt/vyatta/etc/config is used instead of the /config/scripts +directory referenced in the {ref}`command-scripting` section of the +documentation because the /config/script directory isn't mounted when the +`write_files` module executes. + +The following example shows how to execute commands after the initial +configuration. + +```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 +``` + +If you need to gather information from linux commands to configure VyOS, you +can execute commands and then configure VyOS in the same script. + +The following example sets the hostname based on the instance identifier +obtained from the EC2 metadata service. + +```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. Users can +employ the NoCloud data source to inject user-data and meta-data on +virtualization platforms such as VMware, Hyper-V and KVM. + +While other methods exist, the most straightforward method for using the +NoCloud data source is creating a seed ISO and attaching 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, +the mkisofs utility can be used to create the seed ISO. The following +syntax will add these files to the ISO 9660 file system. + +```none +mkisofs -joliet -rock -volid "cidata" -output seed.iso meta-data user-data +``` + +The seed.iso file can be attached to the virtual machine. As an example, +the method with KVM to attach the ISO as a CD drive follows. + +```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 its +page [nocloud] in the cloud-init documentation. + +## Troubleshooting + +If you encounter problems, verify that the cloud-config document contains +valid YAML. Online resources such as provide +a simple tool for validating YAML. + +cloud-init logs to /var/log/cloud-init.log. This file can be helpful in +determining why the configuration varies from what you expect. You can fetch +the most important data filtering output for `vyos` keyword: + +```none +sudo grep vyos /var/log/cloud-init.log +``` + +## Cloud-init on Proxmox + +Before starting, please refer to cloud-init [network-config-docs] in order to +know how to import user and network configurations. + +Most important keys that needs to be considered: + +- VyOS configuration commands are defined in user-data file. + +- Networking configurations shouldn't be passed in user-data file. + +- If no networking configuration is provided, then dhcp client is going to be + enabled on first interface. Bear in mind that this configuration will be + injected at an OS level, so don't expect to find dhcp client configuration + on vyos cli. Because of this behavior, in next example lab we will disable + dhcp-client configuration on eth0. + + Also, this lab considers: + +- Proxmox IP address: **192.168.0.253/24** + +- Storaged used: volume local, which is mounted on directory **/var/lib/vz**, + and contains all type of content, including snippets. + +- Remove default dhcp client on first interface, and load other + configuration during first boot, using cloud-init. + +### Generate qcow image + +A VyOS qcow image with cloud-init options is needed. This can be obtained +using [vyos-vm-images] repo. After cloning the repo, edit the file +**qemu.yml** and comment the **download-iso** role. + +In this lab, we are using 1.3.0 VyOS version and setting a disk of 10G. +Download VyOS .iso file and save it as `/tmp/vyos.iso`. Command used for +generating qcow image: + +```sh +sudo ansible-playbook qemu.yml -e disk_size=10 \ + -e iso_local=/tmp/vyos.iso -e grub_console=serial -e vyos_version=1.3.0 \ + -e cloud_init=true -e cloud_init_ds=NoCloud +``` + +File generated with previous command: +`/tmp/vyos-1.3.0-cloud-init-10G-qemu.qcow2` + +Now, that file needs to be copied to proxmox server: + +```sh +sudo scp /tmp/vyos-1.3.0-cloud-init-10G-qemu.qcow2 root@192.168.0.253:/tmp/ +``` + +### Prepare cloud-init files + +In Proxmox server three files are going to be used for this setup: + +- **network-config**: file that will indicate to avoid dhcp client on first + interface. +- **user-data**: includes vyos-commands. +- **meta-data**: empty file (required). + +In this lab, all files are located in `/tmp/`. So, before going on, lets +move to that directory: + +```sh +cd /tmp/ +``` + +**user-data** file must start with `#cloud-config` and contains +vyos-commands. For example: + +```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 'Comming through VLAN 25' + - set interfaces ethernet eth2 address '192.168.26.1/24' + - set interfaces ethernet eth2 description 'Comming through VLAN 26' + - set protocols static route 0.0.0.0/0 next-hop '198.51.100.1' +``` + +**network-config** file only has configuration that disables the automatic +dhcp client on first interface. + +Content of network-config file: + +```none +version: 2 +ethernets: + eth0: + dhcp4: false + dhcp6: false +``` + +Finally, file **meta-data** has no content, but it's required. + +### Create seed.iso + +Once the three files were created, it's time to generate the `seed.iso` +image, which needs to be mounted to the new VM as a cd. + +Command for generating `seed.iso` + +```sh +mkisofs -joliet -rock -volid "cidata" -output seed.iso meta-data \ +user-data network-config +``` + +**NOTE**: be careful while copying and pasting previous commands. Double +quotes may need to be corrected. + +### Creating the VM + +Notes for this particular example, that may need to be modified in other +setups: + +- VM ID: in this example, VM ID used is 555. +- VM Storage: `local` volume is used. +- ISO files storage: `local` volume is used for `.iso` file storage. In + this scenario `local` volume type is set to **directory**, abd attached to + `/var/lib/vz`. +- VM Resources: these parameters can be modified as needed. + +`seed.iso` was previously created in directory `/tmp/`. It's necessary to +move it to `/var/lib/vz/template/iso` + +```sh +mv /tmp/seed.iso /var/lib/vz/template/iso/ +``` + +On proxmox server: + +```none +## Create VM, import disk and define boot order +qm create 555 --name vyos-1.3.0-cloudinit --memory 1024 --net0 virtio,bridge=vmbr0 +qm importdisk 555 vyos-1.3.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 VM and verifications + +From cli or GUI, power on VM, and after it boots, verify configuration + +### References + +- VyOS [cloud-init-docs]. +- Cloud-init [network-config-docs]. +- Proxmox [Cloud-init-Support]. + + + +[cloud-init-docs]: https://docs.vyos.io/en/equuleus/automation/cloud-init.html?highlight=cloud-init#vyos-cloud-init +[cloud-init-support]: https://pve.proxmox.com/pve-docs/pve-admin-guide.html#qm_cloud_init +[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' < 0. An example follows, in the alternative JSON format, for brevity, +although the standard form-data format is fine: + +```none +curl -k -X POST -d '{"key": "MY-HTTPS-API-PLAINTEXT-KEY", "op": "merge", "string": "interfaces {\nethernet eth1 {\naddress '192.168.137.1/24'\ndescription 'internal'\n}\n}\n", "confirm_time": 1}' https://vyos/config-file + +response: +{ + "success": true, + "data": "Initialized commit-confirm; 1 minutes to confirm before reload\n", + "error": null +} +``` + +The committed changes will be reverted at the timeout unless confirmed. +To confirm and keep the changes: + +```none +curl -k -X POST -d '{"key": "MY-HTTPS-API-PLAINTEXT-KEY", "op": "confirm"}' https://vyos/config-file + +response: +{ + "success": true, + "data": "Reload timer stopped\n", + "error": null +} +``` + +If allowed to revert to the previous configuration, the manner in which +changes are reverted is governed by: + +```none +vyos@vyos# set system config-management commit-confirm action +Possible completions: + reload Reload previous configuration if not confirmed + reboot Reboot to saved configuration if not confirmed (default) +``` diff --git a/docs/automation/md-vyos-govyos.md b/docs/automation/md-vyos-govyos.md new file mode 100644 index 00000000..2d09ac47 --- /dev/null +++ b/docs/automation/md-vyos-govyos.md @@ -0,0 +1,191 @@ +--- +lastproofread: '2024-03-10' +--- + +(vyos-govyos)= + +# go-vyos + +go-vyos is a Go library designed for interacting with VyOS devices through +their REST API. This documentation is intended to guide you in using go-vyos for +programmatic management of your VyOS devices. + +- [go-vyos Documentation & Source Code on GitHub](https://github.com/ganawaj/go-vyos) + allows you to access and contribute to the library's code. +- [go-vyos on pkg.go.dev](https://pkg.go.dev/github.com/ganawaj/go-vyos@v0.1.0/vyos) + for detailed instructions on the installation, configuration, and + operation of the go-vyos library. + +## Installation + +You can install go-vyos: + +```bash +go install "github.com/ganawaj/go-vyos/vyos" +``` + +## Getting Started + +## Importing and Disabling TLS Verification + + +```none +import "github.com/ganawaj/go-vyos/vyos" +client := vyos.NewClient(nil).WithToken("AUTH_KEY").WithURL("https://192.168.0.1").Insecure() +``` + + +## Initializing a VyDevice Object + +```none +import ( + "github.com/ganawaj/go-vyos/vyos" + "os" +) + +hostname := os.Getenv('VYDEVICE_HOSTNAME') +port := os.Getenv('VYDEVICE_PORT') +url := fmt.Sprintf("https://%s:%s", hostname, port) + +apikey := os.Getenv('VYDEVICE_APIKEY') +verify_ssl := os.Getenv('VYDEVICE_VERIFY_SSL') + +client := vyos.NewClient(nil).WithToken(apikey).WithURL(url) + +if verify_ssl == "false" { + client = client.Insecure() +} +``` + +## Using go-vyos + +### Configure, then Set + + +```none +out, resp, err := c.Conf.Set(ctx, "interfaces ethernet eth0 address 192.168.1.1/24") +if err != nil { + panic("Error: %v", err) +} + +fmt.Println(out.Success) +``` + + +### Show a Single Object Value + +```none +out, resp, err := c.Show.Do(ctx, "interfaces dummy dum1 address") +if err != nil { + panic("Error: %v", err) +} + +fmt.Println(out.Success) +fmt.Printf("Data: %v\n", out.Data) +``` + +### Configure, then Show Object + +```none +out, resp, err := c.Conf.Get(ctx, "interfaces dummy dum1", nil) +if err != nil { + panic("Error: %v", err) +} + +fmt.Println(out.Success) +fmt.Printf("Data: %v\n", out.Data) +``` + +### Configure, then Show Multivalue Object + +```none +options := RetrieveOptions{ + Multivalue: true, +} + +out, resp, err := c.Conf.Get(ctx, "interfaces dummy dum1", options) +if err != nil { + panic("Error: %v", err) +} + +fmt.Println(out.Success) +``` + +### Configure, then Delete Object + +```none +out, resp, err := c.Conf.Delete(ctx, "interfaces dummy dum1") +if err != nil { + panic("Error: %v", err) +} + +fmt.Println(out.Success) +``` + +### Configure, then Save + +```none +out, resp, err := c.Conf.Save(ctx, "") + +if err != nil { + panic("Error: %v", err) +} + +fmt.Println(out.Success) +``` + +## Configure, then Save File + +```none +out, resp, err := c.Conf.Save(ctx, "/config/test300.config") + +if err != nil { + panic("Error: %v", err) +} + +fmt.Println(out.Success) +``` + +### Show Object + +```none +out, resp, err := c.Show.Do(ctx, "system image") +if err != nil { + panic("Error: %v", err) +} + +fmt.Println(out.Success) +fmt.Printf("Data: %v\n", out.Data) +``` + +### Generate Object + +```none +out, resp, err := c.Generate.Do(ctx, "pki wireguard key-pair") +if err != nil { + panic("Error: %v", err) +} + +fmt.Println(out.Success) +fmt.Printf("Data: %v\n", out.Data) +``` + +### Reset Object + +```none +out, resp, err := c.Reset.Do(ctx, "ip bgp 192.0.2.11") +if err != nil { + panic("Error: %v", err) +} + +fmt.Println(out.Success) +fmt.Printf("Data: %v\n", out.Data) +``` + +### Configure, then Load File + +```none +out, resp, err := c.ConfigFile.Load(ctx, "/config/test300.config") +``` + +[go-vyos]: https://github.com/ganawaj/go-vyos diff --git a/docs/automation/md-vyos-napalm.md b/docs/automation/md-vyos-napalm.md new file mode 100644 index 00000000..8ca78813 --- /dev/null +++ b/docs/automation/md-vyos-napalm.md @@ -0,0 +1,142 @@ +--- +lastproofread: '2023-01-16' +--- + +(vyos-napalm)= + +# Napalm + +VyOS supports some [napalm] functions for configuration and op-mode. +It requires more tests. + +Install `napalm-vyos` module + +```none +apt install python3-pip +pip3 install napalm +pip3 install napalm-vyos +``` + +## Op-mode + +```none +#!/usr/bin/env python3 + +import json +from napalm import get_network_driver + +driver = get_network_driver('vyos') + +vyos_router = driver( + hostname="192.0.2.1", + username="vyos", + password="vyospass", + optional_args={"port": 22}, +) + +vyos_router.open() +output = vyos_router.get_facts() +print(json.dumps(output, indent=4)) + +output = vyos_router.get_arp_table() +print(json.dumps(output, indent=4)) + +vyos_router.close() +``` + +Output op-mode + +```none +$ ./vyos-napalm.py +{ + "uptime": 7185, + "vendor": "VyOS", + "os_version": "1.3.0-rc5", + "serial_number": "", + "model": "Standard PC (Q35 + ICH9, 2009)", + "hostname": "r4-1.3", + "fqdn": "vyos.local", + "interface_list": [ + "eth0", + "eth1", + "eth2", + "lo", + "vtun10" + ] +} +[ + { + "interface": "eth1", + "mac": "52:54:00:b2:38:2c", + "ip": "192.0.2.2", + "age": 0.0 + }, + { + "interface": "eth0", + "mac": "52:54:00:a2:b9:5b", + "ip": "203.0.113.11", + "age": 0.0 + } +] +``` + +## Configuration + +We need 2 files, commands.conf and script itself. + +Content of commands.conf + +```none +set service ssh disable-host-validation +set service ssh port '2222' +set system name-server '192.0.2.8' +set system name-server '203.0.113.8' +set interfaces ethernet eth1 description 'FOO' +``` + +Script vyos-napalm.py + +```none +#!/usr/bin/env python3 + +from napalm import get_network_driver + +driver = get_network_driver('vyos') + +vyos_router = driver( + hostname="192.0.2.1", + username="vyos", + password="vyospass", + optional_args={"port": 22}, +) + +vyos_router.open() +vyos_router.load_merge_candidate(filename='commands.conf') +diffs = vyos_router.compare_config() + +if bool(diffs) == True: + print(diffs) + vyos_router.commit_config() +else: + print('No configuration changes to commit') + vyos_router.discard_config() + +vyos_router.close() +``` + +Output + +```none +$./vyos-napalm.py +[edit interfaces ethernet eth1] ++description FOO +[edit service ssh] ++disable-host-validation ++port 2222 +[edit system] ++name-server 192.0.2.8 ++name-server 203.0.113.8 +[edit] +``` + +[napalm]: https://napalm.readthedocs.io/en/latest/base.html diff --git a/docs/automation/md-vyos-netmiko.md b/docs/automation/md-vyos-netmiko.md new file mode 100644 index 00000000..da042b6c --- /dev/null +++ b/docs/automation/md-vyos-netmiko.md @@ -0,0 +1,72 @@ +--- +lastproofread: '2023-01-16' +--- + +(vyos-netmiko)= + +# Netmiko + +VyOS supports configuration via [netmiko]. +It requires to install `python3-netmiko` module. + +## Example + +```none +#!/usr/bin/env python3 + +from netmiko import ConnectHandler + +vyos_router = { + "device_type": "vyos", + "host": "192.0.2.1", + "username": "vyos", + "password": "vyospass", + "port": 22, + } + +net_connect = ConnectHandler(**vyos_router) + +config_commands = [ + 'set interfaces ethernet eth0 description WAN', + 'set interfaces ethernet eth1 description LAN', + ] + +# set configuration +output = net_connect.send_config_set(config_commands, exit_config_mode=False) +print(output) + +# commit configuration +output = net_connect.commit() +print(output) + +# op-mode commands +output = net_connect.send_command("run show interfaces") +print(output) +``` + +Output + +```none +$ ./vyos-netmiko.py +configure +set interfaces ethernet eth0 description WAN +[edit] +vyos@r4-1.3# set interfaces ethernet eth1 description LAN +[edit] +vyos@r4-1.3# +commit +[edit] +vyos@r4-1.3# +Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down +Interface IP Address S/L Description +--------- ---------- --- ----------- +eth0 203.0.113.1/24 u/u WAN +eth1 192.0.2.1/30 u/u LAN +eth2 - u/u +lo 127.0.0.1/8 u/u + ::1/128 +vtun10 10.10.0.1/24 u/u +[edit] +``` + +[netmiko]: https://github.com/ktbyers/netmiko diff --git a/docs/automation/md-vyos-pyvyos.md b/docs/automation/md-vyos-pyvyos.md new file mode 100644 index 00000000..462ee63e --- /dev/null +++ b/docs/automation/md-vyos-pyvyos.md @@ -0,0 +1,138 @@ +--- +lastproofread: '2024-03-10' +--- + +(vyos-pyvyos)= + +# pyvyos + +pyvyos is a Python library designed for interacting with VyOS devices through +their API. This documentation is intended to guide you in using pyvyos for +programmatic management of your VyOS devices. + +- [pyvyos Documentation on Read the Docs](https://pyvyos.readthedocs.io/en/latest/) provides detailed instructions + on the installation, configuration, and operation of the pyvyos library. +- [pyvyos Source Code on GitHub](https://github.com/robertoberto/pyvyos) + allows you to access and contribute to the library's code. +- [pyvyos on PyPI](https://pypi.org/project/pyvyos/) for easy installation + via pip, the Python package installer. Execute `pip install pyvyos` in your + terminal to install. + +## Installation + +You can install pyvyos using pip: + +```bash +pip install pyvyos +``` + +## Getting Started + +## Importing and Disabling Warnings for verify=False + +```none +import urllib3 +urllib3.disable_warnings() +``` + +## Using API Response Class + +```none +@dataclass +class ApiResponse: + status: int + request: dict + result: dict + error: str +``` + +## Initializing a VyDevice Object + +```none +from dotenv import load_dotenv +load_dotenv() + +hostname = os.getenv('VYDEVICE_HOSTNAME') +apikey = os.getenv('VYDEVICE_APIKEY') +port = os.getenv('VYDEVICE_PORT') +protocol = os.getenv('VYDEVICE_PROTOCOL') +verify_ssl = os.getenv('VYDEVICE_VERIFY_SSL') + +verify = verify_ssl.lower() == "true" if verify_ssl else True + +device = VyDevice(hostname=hostname, apikey=apikey, port=port, protocol=protocol, verify=verify) +``` + +## Using pyvyos + +### Configure, then Set + +```none +response = device.configure_set(path=["interfaces", "ethernet", "eth0", "address", "192.168.1.1/24"]) +if not response.error: + print(response.result) +``` + +### Configure, then Show a Single Object Value + +```none +response = device.retrieve_return_values(path=["interfaces", "dummy", "dum1", "address"]) +print(response.result) +``` + +### Configure, then Show Object + +```none +response = device.retrieve_show_config(path=[]) +if not response.error: + print(response.result) +``` + +### Configure, then Delete Object + +```none +response = device.configure_delete(path=["interfaces", "dummy", "dum1"]) +``` + +### Configure, then Save + +```none +response = device.config_file_save() +``` + +## Configure, then Save File + +```none +response = device.config_file_save(file="/config/test300.config") +``` + +### Show Object + +```none +response = device.show(path=["system", "image"]) +print(response.result) +``` + +### Generate Object + +```none +randstring = ''.join(random.choice(string.ascii_letters + string.digits) for _ in range(20)) +keyrand = f'/tmp/key_{randstring}' +response = device.generate(path=["ssh", "client-key", keyrand]) +``` + +### Reset Object + +```none +response = device.reset(path=["conntrack-sync", "internal-cache"]) +if not response.error: + print(response.result) +``` + +### Configure, then Load File + +```none +response = device.config_file_load(file="/config/test300.config") +``` + +[pyvyos]: https://github.com/robertoberto/pyvyos diff --git a/docs/automation/md-vyos-salt.md b/docs/automation/md-vyos-salt.md new file mode 100644 index 00000000..fe18bd41 --- /dev/null +++ b/docs/automation/md-vyos-salt.md @@ -0,0 +1,218 @@ +--- +lastproofread: '2023-01-16' +--- + +(vyos-salt)= + +```{include} /_include/need_improvement.txt +``` + +# Salt + +VyOS supports op-mode and configuration via [salt]. + +Without proxy it requires VyOS minion configuration +and supports op-mode data: + +```none +set service salt-minion id 'r14' +set service salt-minion master '192.0.2.250' +``` + +Check salt-keys on the salt master + +```none +/ # salt-key --list-all +Accepted Keys: +r11 +Denied Keys: +Unaccepted Keys: +r14 +Rejected Keys: +``` + +Accept minion key + +```none +/ # salt-key --accept r14 +The following keys are going to be accepted: +Unaccepted Keys: +r14 +Proceed? [n/Y] y +Key for minion r14 accepted. +``` + +Check that salt master can communicate with minions + +```none +/ # salt '*' test.ping +r14: + True +r11: + True +``` + +At this step we can get some op-mode information from VyOS nodes: + +```none +/ # salt '*' network.interface eth0 +r11: + |_ + ---------- + address: + 192.0.2.11 + broadcast: + 192.0.2.255 + label: + eth0 + netmask: + 255.255.255.0 +r14: + |_ + ---------- + address: + 192.0.2.14 + broadcast: + 192.0.2.255 + label: + eth0 + netmask: + 255.255.255.0 + + +/ # salt r14 network.arp +r14: + ---------- + aa:bb:cc:dd:f3:db: + 192.0.2.1 + aa:bb:cc:dd:2e:80: + 203.0.113.1 +``` + +## Netmiko-proxy + +It is possible to configure VyOS via [netmiko] proxy module. +It requires a minion with installed packet `python3-netmiko` module +who has a connection to VyOS nodes. Salt-minion have to communicate +with salt master + +### Configuration + +Salt master configuration: + +```none +/ # cat /etc/salt/master +file_roots: + base: + - /srv/salt/states + +pillar_roots: + base: + - /srv/salt/pillars +``` + +Structure of /srv/salt: + +```none +/ # tree /srv/salt/ +/srv/salt/ +|___ pillars +| |__ r11-proxy.sls +| |__ top.sls +|___ states + |__ commands.txt +``` + +top.sls + +```none +/ # cat /srv/salt/pillars/top.sls +base: + r11-proxy: + - r11-proxy +``` + +r11-proxy.sls Includes parameters for connecting to salt-proxy minion + +```none +/ # cat /srv/salt/pillars/r11-proxy.sls +proxy: + proxytype: netmiko # how to connect to proxy minion, change it + device_type: vyos # + host: 192.0.2.250 + username: user + password: secret_passwd +``` + +commands.txt + +```none +/ # cat /srv/salt/states/commands.txt +set interfaces ethernet eth0 description 'WAN' +set interfaces ethernet eth1 description 'LAN' +``` + +Check that proxy minion is alive: + +```none +/ # salt r11-proxy test.ping +r11-proxy: + True +/ # +``` + +### Examples + +Example of op-mode: + + +```none +/ # salt r11-proxy netmiko.send_command 'show interfaces ethernet eth0 brief' host=192.0.2.14 device_type=vyos username=vyos password=vyos +r11-proxy: + Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down + Interface IP Address S/L Description + --------- ---------- --- ----------- + eth0 192.0.2.14/24 u/u Upstream +/ # +``` + + +Example of configuration: + + +```none +/ # salt r11-proxy netmiko.send_config config_commands=['set interfaces ethernet eth0 description Link_to_WAN'] commit=True host=192.0.2.14 device_type=vyos username=vyos password=vyos +r11-proxy: + configure + set interfaces ethernet eth0 description Link_to_WAN + [edit] + vyos@r14# commit + [edit] + vyos@r14# +/ # +``` + + +Example of configuration commands from the file +"/srv/salt/states/commands.txt" + + +```none +/ # salt r11-proxy netmiko.send_config config_file=salt://commands.txt commit=True host=192.0.2.11 device_type=vyos username=vyos password=vyos +r11-proxy: + configure + set interfaces ethernet eth0 description 'WAN' + [edit] + vyos@r1# set interfaces ethernet eth1 description 'LAN' + [edit] + vyos@r1# commit + [edit] + vyos@r1# +/ # +``` + + + + +[netmiko]: https://docs.saltproject.io/en/latest/ref/modules/all/salt.modules.netmiko_mod.html#module-salt.modules.netmiko_mod +[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..102c06e7 --- /dev/null +++ b/docs/automation/terraform/md-index.md @@ -0,0 +1,31 @@ +--- +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]. + +```{eval-rst} +.. toctree:: + :maxdepth: 1 + :caption: Guides + + 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..013a24e5 --- /dev/null +++ b/docs/automation/terraform/md-terraformAWS.md @@ -0,0 +1,537 @@ +--- +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. + +```{image} /_static/images/aws.webp +:align: center +:alt: Network Topology Diagram +:width: 50% +``` + +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. + +```{image} /_static/images/keypairs.webp +:align: center +:alt: Network Topology Diagram +:width: 50% +``` + +3. Create a security [group] for the new VyOS instance and open all traffic. + +```{image} /_static/images/sg.webp +:align: center +:alt: Network Topology Diagram +:width: 50% +``` + +```{image} /_static/images/traffic.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 a folder, for example `/root/awsterraform`: + +```none +mkdir /root/awsterraform +``` + + +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. + + +5. Run the following commands: + +```none +cd / +terraform init +``` + +### Ansible + +1. Create a UNIX instance whenever you need. +2. Download and install Ansible +3. Create a folder, for example `/root/aws/`. + + +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. + +```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 +[image]: https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/AMIs.html +[install]: https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli +[link]: https://developer.hashicorp.com/terraform/intro +[pair]: https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/create-key-pairs.html +[vyos-automation]: https://github.com/vyos/vyos-automation/tree/main/TerraformCloud/AWS_terraform_ansible_single_vyos_instance-main diff --git a/docs/automation/terraform/md-terraformAZ.md b/docs/automation/terraform/md-terraformAZ.md new file mode 100644 index 00000000..686e6e10 --- /dev/null +++ b/docs/automation/terraform/md-terraformAZ.md @@ -0,0 +1,487 @@ +--- +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 + +1. Create an [Azure account](https://azure.microsoft.com/). + +### 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/azvyos/`. + +```none +mkdir /root/azvyos +``` + + +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). + + +5. Log in to Azure using the command: + +```none +az login +``` + +6. Run the following commands to initialize Terraform: + +```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] + +### 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" + default = "Vyos0!" +} + +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: Vyos0! +``` + +## 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]: https://github.com/vyos/vyos-automation/tree/main/TerraformCloud/Azure_terraform_ansible_single_vyos_instance-main diff --git a/docs/automation/terraform/md-terraformGoogle.md b/docs/automation/terraform/md-terraformGoogle.md new file mode 100644 index 00000000..e0f28ebc --- /dev/null +++ b/docs/automation/terraform/md-terraformGoogle.md @@ -0,0 +1,698 @@ +--- +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] + +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 + +1. 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. +2. 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]: https://github.com/vyos/vyos-automation/tree/main/TerraformCloud/Google_terraform_ansible_single_vyos_instance-main diff --git a/docs/automation/terraform/md-terraformvSphere.md b/docs/automation/terraform/md-terraformvSphere.md new file mode 100644 index 00000000..6a4dd2ca --- /dev/null +++ b/docs/automation/terraform/md-terraformvSphere.md @@ -0,0 +1,385 @@ +lastproofread +2024-03-03 + +# Deploying VyOS in the vSphere infrastructure + +With the help of Terraform, you can quickly deploy VyOS-based +infrastructure in the vSphere. +Also we will make provisioning using Ansible. + +In this case, we'll create the necessary files for Terraform and +Ansible next using Terraform we'll create a single instance on the +vSphere cloud and make provisioning using Ansible. + +## Preparation steps for deploying VyOS on vSphere + +How to create a single instance and install your configuration using +Terraform+Ansible+vSphere +Step by step: + +vSphere + +> 1 Collect all data in to file "terraform.tfvars" and create +> resources for example "terraform" + +Terraform + +> 1 Create an UNIX or Windows instance +> +> 2 Download and install Terraform +> +> 3 Create the folder for example /root/vsphereterraform + +``` none +mkdir /root/vsphereterraform + + + 4 Copy all files into your Terraform project + "/root/vsphereterraform" (vyos.tf, var.tf, terraform.tfvars, + version.tf), more detailed see + `Structure of files Terraform for vSphere`_ + + 5 Type the commands : +``` + +``` none +cd / +terraform init +``` + +Ansible + +> 1 Create an UNIX instance whenever you want (local, cloud, and so on) +> +> 2 Download and install Ansible +> +> 3 Create the folder for example /root/vsphereterraform/ +> +> 4 Copy all files into your Ansible project +> "/root/vsphereterraform/" (ansible.cfg, instance.yml, "all"), +> more detailed see [Structure of files Ansible for vSphere](#structure-of-files-ansible-for-vsphere) + +Start + +Type the commands on your Terraform instance: + +``` none +cd / +terraform plan +terraform apply +yes +``` + +After executing all the commands you will have your VyOS instance on +the vSphere with your configuration, it's a very convenient decision. +If you need to delete the instance please type the command: + +``` none +terraform destroy +``` + +Structure of files Terraform for vSphere +--------------------------------------- + +``` none +. +├── vyos.tf # The main script +├── versions.tf # File for the changing version of Terraform. +├── var.tf # File for the changing version of Terraform. +└── terraform.tfvars # The value of all variables +``` + +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 if yor host" + type = string +} + +variable "remotename" { + description = "the name of you VM" + type = string +} + +variable "url_ova" { + description = "the URL to .OVA file or cloude store" + 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 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 cammans 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 +``` + +## Sourse files for vSphere from GIT + +All files about the article can be found [here](https://github.com/vyos/vyos-automation/tree/main/TerraformCloud/Vsphere_terraform_ansible_single_vyos_instance-main) diff --git a/docs/conf.py b/docs/conf.py index 3e84a34a..612ae577 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -85,6 +85,19 @@ gettext_uuid = False # This pattern also affects html_static_path and html_extra_path . exclude_patterns = [u'_build', 'Thumbs.db', '.DS_Store', '_include/vyos-1x'] +# MyST-Parser configuration +myst_enable_extensions = ["colon_fence", "deflist", "fieldlist", "substitution"] +myst_fence_as_directive = ["cfgcmd", "opcmd", "cmdincludemd"] + +# Incremental RST→MyST swap: extend exclude_patterns with the RST paths that +# swap_sources.py just hid behind their md-prefixed counterparts. +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' @@ -213,5 +226,14 @@ texinfo_documents = [ ] +def _prefer_webp(app): + """Prepend WebP to supported image types for HTML builders so MyST pages + can use webp without falling back to PDF/PNG fallbacks.""" + 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 setup(app): - pass \ No newline at end of file + app.connect('builder-inited', _prefer_webp) \ No newline at end of file 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..6581cfb3 --- /dev/null +++ b/docs/configexamples/autotest/DHCPRelay_through_GRE/md-DHCPRelay_through_GRE.md @@ -0,0 +1,96 @@ +# DHCP Relay trough GRE-Bridge + +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: + +```{eval-rst} +.. literalinclude:: _include/transport.conf + :language: none + +``` + +DHCP-Server + +```{eval-rst} +.. literalinclude:: _include/dhcp-server.conf + :language: none + :lines: 1-8 + +``` + +DHCP-Relay + +```{eval-rst} +.. 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 + +```{eval-rst} +.. literalinclude:: _include/dhcp-server.conf + :language: none + :lines: 9-13 + +``` + +DHCP-Relay + +```{eval-rst} +.. 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..91dee302 --- /dev/null +++ b/docs/configexamples/autotest/L3VPN_EVPN/md-L3VPN_EVPN.md @@ -0,0 +1,250 @@ +# L3VPN EVPN with VyOS + +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. + +```{eval-rst} +.. 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 + +```{eval-rst} +.. literalinclude:: _include/PE1.conf + :language: none + :lines: 8-38 +``` + +PE2 + +```{eval-rst} +.. literalinclude:: _include/PE2.conf + :language: none + :lines: 8-38 +``` + +PE3 + +```{eval-rst} +.. 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 + +```{eval-rst} +.. literalinclude:: _include/PE1.conf + :language: none + :lines: 40-96 +``` + +PE2 + +```{eval-rst} +.. literalinclude:: _include/PE2.conf + :language: none + :lines: 40-89 +``` + +PE3 + +```{eval-rst} +.. 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..38e09b9d --- /dev/null +++ b/docs/configexamples/autotest/OpenVPN_with_LDAP/md-OpenVPN_with_LDAP.md @@ -0,0 +1,235 @@ +(examples-openvpn-with-ldap)= + +# OpenVPN with LDAP + +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. + +Add the LDAP plugin configuration file + +`/config/auth/ldap-auth.config` + +Check all possible settings + +[here](https://github.com/threerings/openvpn-auth-ldap/blob/master/auth-ldap.conf) + +```{eval-rst} +.. 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. + +```{eval-rst} +.. 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..e33d74cd --- /dev/null +++ b/docs/configexamples/autotest/Wireguard/md-Wireguard.md @@ -0,0 +1,113 @@ +# Wireguard + +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 + +```{eval-rst} +.. literalinclude:: _include/central.conf + :language: none + :lines: 1-2 +``` + +Branch + +```{eval-rst} +.. 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 + +```{eval-rst} +.. literalinclude:: _include/central.conf + :language: none + :lines: 4-12 +``` + +Branch + +```{eval-rst} +.. 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 + +```{eval-rst} +.. literalinclude:: _include/central.conf + :language: none + :lines: 14 +``` + +Branch + +```{eval-rst} +.. 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..388a459d --- /dev/null +++ b/docs/configexamples/autotest/tunnelbroker/md-tunnelbroker.md @@ -0,0 +1,209 @@ +(examples-tunnelbroker-ipv6)= + +# Tunnelbroker.net (IPv6) + +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 on 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. + +```{eval-rst} +.. literalinclude:: _include/vyos-wan.conf + :language: none + +``` + +Now we are able to setup the tunnel interface. + +```{eval-rst} +.. 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 + +```{eval-rst} +.. 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: + +```{eval-rst} +.. 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: + +```{eval-rst} +.. 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. + +```{eval-rst} +.. 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 for +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..f28faec9 --- /dev/null +++ b/docs/configexamples/md-ansible.md @@ -0,0 +1,196 @@ +lastproofread +2024-04-09 + +# 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: + +Network Topology Diagram + +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 8.8.8.8 + - 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 8.8.8.8 +set system name-server '8.8.8.8' +``` + +## 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 8.8.8.8 + - 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..8020aca0 --- /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 azure 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 azure 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..aa526366 --- /dev/null +++ b/docs/configexamples/md-dmvpn-dualhub-dualcloud.md @@ -0,0 +1,538 @@ +--- +lastproofread: '2024-02-21' +--- + +(examples-dmvpn-dualhub-dualcloud)= + +# DMVPN Dual HUB Dual Cloud + +This document is to describe a basic setup to build DVMPN 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 + +```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 + +```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 + +```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 + +```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..c6c944a5 --- /dev/null +++ b/docs/configexamples/md-firewall.md @@ -0,0 +1,17 @@ +--- +lastproofread: '2024-09-11' +--- + +# Firewall Examples + +This section contains examples of firewall configurations for various +deployments. + +```{eval-rst} +.. 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..802346ff --- /dev/null +++ b/docs/configexamples/md-fwall-and-bridge.md @@ -0,0 +1,488 @@ +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 whithin the bridge. + +- Bridge br1: + - Drop all DHCP discover packets. + - Accept all ARP packets. + - Within the bridge, accept only new IPv4 connections from host 10.1.1.102 + - Drop all other IPv4 connections. + - Drop all IPv6 connections. + - Accept access to router itself. + - Allow connections to internet + - Drop connections to other LANs. + +- Bridge br2: + - Accept all DHCP discover packets. + - Accept only DHCP offers from valid server and|or trusted bridge port. + - Accept all ARP packets. + - Accept all IPv4 connections. + - Drop all IPv6 connections. + - Deny access to the router. + - Allow connections to internet. + - Allow connections to bridge br1. + +## Configuration + +### Bridges and interfaces configuration + +First, we need to configure the interfaces and bridges: + +``` none +# Brige br0 +set interfaces bridge br0 description 'Isolated L2 bridge' +set interfaces bridge br0 member interface eth1 +set interfaces bridge br0 member interface eth2 +set interfaces ethernet eth1 description 'br0' +set interfaces ethernet eth2 description 'br0' + +# Bridge br1: +set interfaces bridge br1 address '10.1.1.1/24' +set interfaces bridge br1 description 'L3 bridge br1' +set interfaces bridge br1 member interface eth3 +set interfaces bridge br1 member interface eth4 +set interfaces ethernet eth3 description 'br1' +set interfaces ethernet eth4 description 'br1' + +# Bridge br2: +set interfaces bridge br2 address '10.2.2.1/24' +set interfaces bridge br2 description 'L3 bridge br2' +set interfaces bridge br2 member interface eth5 +set interfaces bridge br2 member interface eth6 +set interfaces bridge br2 member interface eth7 +set interfaces ethernet eth5 description 'br2 - Host' +set interfaces ethernet eth6 description 'br2 - Trusted DHCP Server' +set interfaces ethernet eth7 description 'br2' +``` + +### Bridge firewall configuration + +In this section, we are going to configure the firewall rules that will be used +in bridge firewall, and will control the traffic within each bridge. + +We are going to use custom firewall rulesets, one for each bridge that will +be used in `prerouting`, and one for each bridge that will be used in the +`forward` chain. + +Also, we are going to use firewall interface groups in order to simplify the +firewall configuration. + +So first, let's create the required firewall interface groups: + +``` none +# Bridge br0 interface-group: +set firewall group interface-group br0-ifaces interface 'br0' +set firewall group interface-group br0-ifaces interface 'eth1' +set firewall group interface-group br0-ifaces interface 'eth2' + +# Bridge br1 interface-group: +set firewall group interface-group br1-ifaces interface 'br1' +set firewall group interface-group br1-ifaces interface 'eth3' +set firewall group interface-group br1-ifaces interface 'eth4' + +# Bridge br2 interface-group: +set firewall group interface-group br2-ifaces interface 'br2' +set firewall group interface-group br2-ifaces interface 'eth5' +set firewall group interface-group br2-ifaces interface 'eth6' +set firewall group interface-group br2-ifaces interface 'eth7' +``` + +As said before, we are going to create custom firewall rulesets for each +bridge, that will be used in the `prerouting` chain, in order to drop as much +unwanted traffic as early as possible. So, custom rulesets used in +`prerouting` chain are going to be `br0-pre`, `br1-pre`, and `br2-pre`: + +``` none +# Prerouting - Catch all traffic for br0 +set firewall bridge prerouting filter rule 10 action 'jump' +set firewall bridge prerouting filter rule 10 description 'br0 traffic' +set firewall bridge prerouting filter rule 10 inbound-interface group 'br0-ifaces' +set firewall bridge prerouting filter rule 10 jump-target 'br0-pre' + +# Prerouting - Catch all traffic for br1 +set firewall bridge prerouting filter rule 20 action 'jump' +set firewall bridge prerouting filter rule 20 description 'br1 traffic' +set firewall bridge prerouting filter rule 20 inbound-interface group 'br1-ifaces' +set firewall bridge prerouting filter rule 20 jump-target 'br1-pre' + +# Prerouting - Catch all traffic for br2 +set firewall bridge prerouting filter rule 30 action 'jump' +set firewall bridge prerouting filter rule 30 description 'br2 traffic' +set firewall bridge prerouting filter rule 30 inbound-interface group 'br2-ifaces' +set firewall bridge prerouting filter rule 30 jump-target 'br2-pre' +``` + +And then create the custom rulesets: + +``` none +### br0 - br0-pre + # Requirements: accept only IPv6 communication within the bridge +set firewall bridge name br0-pre rule 10 description 'Accept IPv6 traffic' +set firewall bridge name br0-pre rule 10 action 'accept' +set firewall bridge name br0-pre rule 10 ethernet-type 'ipv6' + # And drop everything else +set firewall bridge name br0-pre default-action 'drop' + +### br1 - br1-pre + # Requirements: drop all DHCP discover packets +set firewall bridge name br1-pre rule 10 description 'Drop DHCP discover' +set firewall bridge name br1-pre rule 10 action 'drop' +set firewall bridge name br1-pre rule 10 protocol 'udp' +set firewall bridge name br1-pre rule 10 source port '68' +set firewall bridge name br1-pre rule 10 destination port '67' +set firewall bridge name br1-pre rule 10 destination mac-address 'ff:ff:ff:ff:ff:ff' +set firewall bridge name br1-pre rule 10 log + # Requirement: drop all IPv6 connections +set firewall bridge name br1-pre rule 20 description 'Drop IPv6 traffic' +set firewall bridge name br1-pre rule 20 action 'drop' +set firewall bridge name br1-pre rule 20 ethernet-type 'ipv6' + # Accept everything else so it can be parsed later +set firewall bridge name br1-pre default-action 'accept' + +### br2 - br2-pre + # Requirements: drop all IPv6 connections +set firewall bridge name br2-pre rule 10 description 'Drop IPv6 traffic' +set firewall bridge name br2-pre rule 10 action 'drop' +set firewall bridge name br2-pre rule 10 ethernet-type 'ipv6' + # Accept everything else so it can be parsed later +set firewall bridge name br2-pre default-action 'accept' +``` + +Now, in the `forward` chain, we are going to define state policies, and +custom rulesets for each bridge that would be used in the `forward` chain. +These rulesets are `br0-fwd`, `br1-fwd`, and `br2-fwd`: + +``` none +# Forward - State policies if not defined globally +set firewall bridge forward filter rule 5 action 'accept' +set firewall bridge forward filter rule 5 state 'established' +set firewall bridge forward filter rule 5 state 'related' +set firewall bridge forward filter rule 10 action 'drop' +set firewall bridge forward filter rule 10 state 'invalid' + +# Forward - Catch all traffic for br0 +set firewall bridge forward filter rule 110 description 'br0 traffic' +set firewall bridge forward filter rule 110 action 'jump' +set firewall bridge forward filter rule 110 inbound-interface group 'br0-ifaces' +set firewall bridge forward filter rule 110 jump-target 'br0-fwd' + +# Forward - Catch all traffic for br1 +set firewall bridge forward filter rule 120 description 'br1 traffic' +set firewall bridge forward filter rule 120 action 'jump' +set firewall bridge forward filter rule 120 inbound-interface group 'br1-ifaces' +set firewall bridge forward filter rule 120 jump-target 'br1-fwd' + +# Forward - Catch all traffic for br2 +set firewall bridge forward filter rule 130 description 'br2 traffic' +set firewall bridge forward filter rule 130 action 'jump' +set firewall bridge forward filter rule 130 inbound-interface group 'br2-ifaces' +set firewall bridge forward filter rule 130 jump-target 'br2-fwd' + +# Forward - Default action drop: +set firewall bridge forward filter default-action 'drop' +``` + +And the content of the custom rulesets: + +``` none +### br0 - br0-fwd + # Accept everything that wasn't dropped in prerouting +set firewall bridge name br0-fwd default-action 'accept' + +### br1 - br1-fwd + # Requirement: Accept all ARP packets +set firewall bridge name br1-fwd rule 10 description 'Accept ARP' +set firewall bridge name br1-fwd rule 10 action 'accept' +set firewall bridge name br1-fwd rule 10 ethernet-type 'arp' + # Requirement: Accept only new IPv4 connections from host 10.1.1.102 +set firewall bridge name br1-fwd rule 20 description 'Accept ipv4 from host' +set firewall bridge name br1-fwd rule 20 action 'accept' +set firewall bridge name br1-fwd rule 20 source address '10.1.1.102' +set firewall bridge name br1-fwd rule 20 state 'new' + # Drop everythin 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 `firewall documentation +`, where you can find more information about +the packet flow for traffic that comes from bridge layer and should be analized +by the IP firewall. + +Access to the router itself is controlled by the base chain `input`, and +rules to accomplish all the requirements are: + +``` none +# First of all, if not using global state policies, we need to define them: +set firewall ipv4 input filter rule 10 state 'established' +set firewall ipv4 input filter rule 10 state 'related' +set firewall ipv4 input filter rule 10 action 'accept' +set firewall ipv4 input filter rule 20 state 'invalid' +set firewall ipv4 input filter rule 20 action 'drop' + +# Input - br1 - Accept access to router itself +set firewall ipv4 input filter rule 110 description "Accept access from br1" +set firewall ipv4 input filter rule 110 action 'accept' +set firewall ipv4 input filter rule 110 inbound-interface group 'br1-ifaces' + +# Input - br2 - Deny access to the router +set firewall ipv4 input filter rule 120 description "Deny access from br2" +set firewall ipv4 input filter rule 120 action 'drop' +set firewall ipv4 input filter rule 120 inbound-interface group 'br2-ifaces' +``` + +And for traffic that is going to other local networks, and to he Internet, we +need to use the base chain `forward`. As in the bridge firewall, we are +going to use custom rulesets for each bridge, that would be used in the +`forward` chain. Those rulesets are `ip-br1-fwd` and `ip-br2-fwd`: + +``` none +# First of all, if not using global state policies, we need to define them: +set firewall ipv4 forward filter rule 5 action 'accept' +set firewall ipv4 forward filter rule 5 state 'established' +set firewall ipv4 forward filter rule 5 state 'related' +set firewall ipv4 forward filter rule 10 action 'drop' +set firewall ipv4 forward filter rule 10 state 'invalid' + +# Forward - Catch all traffic for br1 +set firewall ipv4 forward filter rule 110 description 'br1 traffic' +set firewall ipv4 forward filter rule 110 action 'jump' +set firewall ipv4 forward filter rule 110 inbound-interface group 'br1-ifaces' +set firewall ipv4 forward filter rule 110 jump-target 'ip-br1-fwd' + +# Forward - Catch all traffic for br2 +set firewall ipv4 forward filter rule 120 description 'br2 traffic' +set firewall ipv4 forward filter rule 120 action 'jump' +set firewall ipv4 forward filter rule 120 inbound-interface group 'br2-ifaces' +set firewall ipv4 forward filter rule 120 jump-target 'ip-br2-fwd' + +# Forward - Default action drop: +set firewall ipv4 forward filter default-action 'drop' +``` + +And the content of the custom rulesets: + +``` none +### br1 - ip-br1-fwd + # Requirement: Allow connections to internet +set firewall ipv4 name ip-br1-fwd rule 10 description 'br1 - allow internet access' +set firewall ipv4 name ip-br1-fwd rule 10 action 'accept' +set firewall ipv4 name ip-br1-fwd rule 10 outbound-interface name 'eth0' + # Requirement: Drop all other connections +set firewall ipv4 name ip-br1-fwd default-action 'drop' + +### br2 - ip-br2-fwd + # Requirement: Allow connections to internet +set firewall ipv4 name ip-br2-fwd rule 10 description 'br2 - allow internet access' +set firewall ipv4 name ip-br2-fwd rule 10 action 'accept' +set firewall ipv4 name ip-br2-fwd rule 10 outbound-interface name 'eth0' + # Requirement: Allow connections to br1 +set firewall ipv4 name ip-br2-fwd rule 20 description 'br2 - allow access to br1' +set firewall ipv4 name ip-br2-fwd rule 20 action 'accept' +set firewall ipv4 name ip-br2-fwd rule 20 outbound-interface group 'br1-ifaces' + # Requirement: Drop all other connections +set firewall ipv4 name ip-br2-fwd default-action 'drop' +``` + +## Validation + +While testing the configuration, we can check logs in order to ensure that +we are accepting and/or blocking the correct traffic. + +For example, while a host tries to get an IP address from a DHCP server in +br1 all DHCP discover are dropped, and in br2, we can see that DHCP offers from +untrusted servers are dropped: + +``` none +vyos@bridge:~$ show log firewall bridge +Sep 17 14:22:35 kernel: [bri-NAM-br2-fwd-22-D]IN=eth7 OUT=eth5 MAC=50:00:00:09:00:00:50:00:00:04:00:00:08:00 SRC=10.2.2.199 DST=10.2.2.92 LEN=322 TOS=0x10 PREC=0x00 TTL=128 ID=0 DF PROTO=UDP SPT=67 DPT=68 LEN=302 +Sep 17 14:28:18 kernel: [bri-NAM-br1-pre-10-D]IN=eth3 OUT= MAC=ff:ff:ff:ff:ff:ff:00:50:79:66:68:0c:08:00 SRC=0.0.0.0 DST=255.255.255.255 LEN=392 TOS=0x10 PREC=0x00 TTL=16 ID=0 PROTO=UDP SPT=68 DPT=67 LEN=372 +Sep 17 14:28:19 kernel: [bri-NAM-br1-pre-10-D]IN=eth3 OUT= MAC=ff:ff:ff:ff:ff:ff:00:50:79:66:68:0c:08:00 SRC=0.0.0.0 DST=255.255.255.255 LEN=392 TOS=0x10 PREC=0x00 TTL=16 ID=0 PROTO=UDP SPT=68 DPT=67 LEN=372 +``` + +And with operational mode commands, we can check rules matchers, actions, and +counters. + +Bridge firewall rulset: + +``` 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 rulset: + +``` 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..6ae38c5f --- /dev/null +++ b/docs/configexamples/md-fwall-and-vrf.md @@ -0,0 +1,119 @@ +# 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: + +- 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..b272f38e --- /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 amdifferent /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..8bec766a --- /dev/null +++ b/docs/configexamples/md-index.md @@ -0,0 +1,63 @@ +(examples)= + +# Configuration Blueprints + +This chapter contains various configuration examples: + +```{eval-rst} +.. 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 contains automatic full tested configuration examples. + +Each lab will build an test from an external script. +The page content will generate, so changes will not take an effect. + +A host `vyos-oobm` will use as a ssh proxy. This host is just +necessary for the Lab test. + +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 + +```{eval-rst} +.. 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..c35fb1f9 --- /dev/null +++ b/docs/configexamples/md-inter-vrf-routing-vrf-lite.md @@ -0,0 +1,793 @@ +# Inter-VRF Routing over VRF Lite + +**Virtual Routing and Forwarding** is a technology that allow multiple instance +of a routing table to exist within a single device. One of the key aspect of +**VRFs** is that do not share the same routes or interfaces, therefore packets +are forwarded between interfaces that belong to the same VRF only. + +Any information related to a VRF is not exchanged between devices -or in the +same device- by default, this is a technique called **VRF-Lite**. + +Keep networks isolated is -in general- a good principle, but there are cases +where you might need that some network can access other in a different VRF. + +The scope of this document is to cover such cases in a dynamic way without the +use of MPLS-LDP. + +General information about L3VPNs can be found in the {ref}`configuration/vrf/index:L3VPN VRFs` chapter. + +## Overview + +Let’s say we have a requirement to have multiple networks. + +- LAN 1 +- LAN 2 +- Management +- Internet + +Both LANs have to be able to route between each other, both will have managed +devices through a dedicated management network and both will need Internet +access yet the LAN2 will need access to some set of outside networks, not all. +The management network will need access to both LANs but cannot have access +to/from the outside. + +This scenario could be a nightmare applying regular routing and might need +filtering in multiple interfaces. + +A simple solution could be using different routing tables, or VRFs +for all the networks so we can keep the routing restrictions. +But for us to route between the different VRFs we would need a cable or a +logical connection between each other: + +- One cable/logical connection between LAN1 and LAN2 +- One cable/logical connection between LAN1 and Internet +- One cable/logical connection between LAN2 and Internet +- One cable/logical connection between LAN1 and Management +- One cable/logical connection between LAN2 and Management + +As we can see this is unpractical. + +To address this scenario we will use to our advantage an extension of the BGP +routing protocol that will help us in the “Export” between VRFs without the +need for MPLS. + +MP-BGP or MultiProtocol BGP introduces two main concepts to solve this +limitation: +\- Route Distinguisher (RD): Is used to distinguish between different VRFs +–called VPNs- inside the BGP Process. The RD is appended to each IPv4 Network +that is advertised into BGP for that VPN making it a unique VPNv4 route. +\- Route Target (RT): This is an extended BGP community append to the VPNv4 route +in the Import/Export process. When a route passes from the VRF routing table +into the BGP process it will add the configured export extended community(ies) +for that VPN. When that route needs to go from BGP into the VRF routing table +will only pass if that given VPN import policy matches any of the appended +community(ies) into that prefix. + +## Topology + +```{image} /_static/images/inter-vrf-routing-vrf-lite.webp +:align: center +:alt: Network Topology Diagram +:width: 70% +``` + +### IP Schema + +```{eval-rst} ++----------+------------+----------------+------------------+ +| Device-A | Device-B | IPv4 Network | IPv6 Network | ++----------+------------+----------------+------------------+ +| Core | LAN1 | 10.1.1.0/30 | 2001:db8::/127 | ++----------+------------+----------------+------------------+ +| Core | LAN2 | 172.16.2.0/30 | 2001:db8::2/127 | ++----------+------------+----------------+------------------+ +| Core | Management | 192.168.3.0/30 | 2001:db8::4/127 | ++----------+------------+----------------+------------------+ +| Core | ISP | 10.2.2.0/30 | 2001:db8::6/127 | ++----------+------------+----------------+------------------+ +``` + +### RD & RT Schema + +```{eval-rst} ++------------+-----------+-----------+ +| VRF | RD | RT | ++------------+-----------+-----------+ +| LAN1 | 64496:1 | 64496:1 | ++------------+-----------+-----------+ +| LAN2 | 64496:2 | 64496:2 | ++------------+-----------+-----------+ +| Management | 64496:50 | 64496:50 | ++------------+-----------+-----------+ +| Internet | 64496:100 | 64496:100 | ++------------+-----------+-----------+ +``` + +## Configurations + +:::{note} +We use a static route configuration in between the Core and each +LAN and Management router, and BGP between the Core router and the ISP router +but any dynamic routing protocol can be used. +::: + +### Remote Networks + +The following template configuration can be used in each remote router based +in our topology. + +```none +# Interface Configuration +set interface eth eth address + +# Static default route back to Core +set procotols static route 0.0.0.0/0 next-hop +``` + +### Core Router + +#### Step 1: VRF and Configurations to remote networks + +- Configuration + +Set the VRF name and Table ID, set interface address and bind it to the VRF. +Last add the static route to the remote network. + +```none +# VRF name and table ID (MANDATORY) +set vrf name table + +# Interface Configuration +set interface eth eth address + +# Assign interface to VRF +set interface eth eth vrf + +# Static route to remote Network +set vrf name protocols static route next-hop +``` + +- Verification + +Checking the routing table of the VRF should reveal both static and connected +entries active. A PING test between the Core and remote router is a way to +validate connectivity within the VRF. + +```none +# show ip route vrf +# show ipv6 route vrf + +vyos@Core:~$ show ip route vrf LAN1 +Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, + f - OpenFabric, + > - selected route, * - FIB route, q - queued, r - rejected, b - backup + t - trapped, o - offload failure + +VRF LAN1: +S>* 10.0.0.0/24 [1/0] via 10.1.1.2, eth0, weight 1, 00:05:41 +C>* 10.1.1.0/30 is directly connected, eth0, 00:05:44 + +vyos@Core:~$ show ipv6 route vrf LAN1 +Codes: K - kernel route, C - connected, S - static, R - RIPng, + O - OSPFv3, I - IS-IS, B - BGP, N - NHRP, T - Table, + v - VNC, V - VNC-Direct, A - Babel, F - PBR, + f - OpenFabric, + > - selected route, * - FIB route, q - queued, r - rejected, b - backup + t - trapped, o - offload failure + +VRF LAN1: +C>* 2001:db8::/127 is directly connected, eth0, 00:18:43 +S>* 2001:db8:0:1::/64 [1/0] via 2001:db8::1, eth0, weight 1, 00:16:03 +C>* fe80::/64 is directly connected, eth0, 00:18:43 + +# ping vrf + +vyos@Core:~$ ping 10.1.1.2 vrf LAN1 +PING 10.1.1.2 (10.1.1.2) 56(84) bytes of data. +64 bytes from 10.1.1.2: icmp_seq=1 ttl=64 time=1.52 ms +64 bytes from 10.1.1.2: icmp_seq=2 ttl=64 time=0.830 ms +^C +--- 10.1.1.2 ping statistics --- +2 packets transmitted, 2 received, 0% packet loss, time 1002ms +rtt min/avg/max/mdev = 0.830/1.174/1.518/0.344 ms +vyos@Core:~$ ping 10.0.0.1 vrf LAN1 +PING 10.0.0.1 (10.0.0.1) 56(84) bytes of data. +64 bytes from 10.0.0.1: icmp_seq=1 ttl=64 time=0.785 ms +64 bytes from 10.0.0.1: icmp_seq=2 ttl=64 time=0.948 ms +^C +--- 10.0.0.1 ping statistics --- +2 packets transmitted, 2 received, 0% packet loss, time 1002ms +rtt min/avg/max/mdev = 0.785/0.866/0.948/0.081 ms + +vyos@Core:~$ ping 2001:db8:0:1::1 vrf LAN1 +PING 2001:db8:0:1::1(2001:db8:0:1::1) 56 data bytes +64 bytes from 2001:db8:0:1::1: icmp_seq=1 ttl=64 time=3.04 ms +64 bytes from 2001:db8:0:1::1: icmp_seq=2 ttl=64 time=1.04 ms +64 bytes from 2001:db8:0:1::1: icmp_seq=3 ttl=64 time=0.925 ms +^C +--- 2001:db8:0:1::1 ping statistics --- +3 packets transmitted, 3 received, 0% packet loss, time 2004ms +rtt min/avg/max/mdev = 0.925/1.665/3.035/0.969 ms +``` + +#### Step 2: BGP Configuration for VRF-Lite + +- Configuration + +Setting BGP global local-as as well inside the VRF. Redistribute static routes +to inject configured networks into the BGP process but still inside the VRF. + +```none +# set BGP global local-as +set protocols bgp system-as + +# set BGP VRF local-as and redistribution +set vrf name protocols bgp address-family redistribute static +``` + +- Verification + +Check the BGP VRF table and verify if the static routes are injected showing +the correct next-hop information. + +```none +# show ip bgp vrf +# show bgp vrf ipv6 + +vyos@Core:~$ show ip bgp vrf LAN1 +BGP table version is 3, local router ID is 10.1.1.1, vrf id 8 +Default local pref 100, local AS 64496 +Status codes: s suppressed, d damped, h history, * valid, > best, = multipath, + i internal, r RIB-failure, S Stale, R Removed +Nexthop codes: @NNN nexthop's vrf id, < announce-nh-self +Origin codes: i - IGP, e - EGP, ? - incomplete +RPKI validation codes: V valid, I invalid, N Not found + + Network Next Hop Metric LocPrf Weight Path +*> 10.0.0.0/24 10.1.1.2 0 32768 ? + +vyos@Core# run show bgp vrf LAN1 ipv6 +BGP table version is 13, local router ID is 10.1.1.1, vrf id 8 +Default local pref 100, local AS 64496 +Status codes: s suppressed, d damped, h history, * valid, > best, = multipath, + i internal, r RIB-failure, S Stale, R Removed +Nexthop codes: @NNN nexthop's vrf id, < announce-nh-self +Origin codes: i - IGP, e - EGP, ? - incomplete +RPKI validation codes: V valid, I invalid, N Not found + + Network Next Hop Metric LocPrf Weight Path +*> 2001:db8:0:1::/64 + 2001:db8::1 0 32768 ? +``` + +#### Step 3: VPN Configuration + +- Configuration + +Within the VRF we set the Route-Distinguisher (RD) and Route-Targets (RT), then +we enable the export/import VPN. + +```none +# set Route-distinguisher +set vrf name protocols bgp address-family rd vpn export '' + +# set route-target for import/export +# Note: RT are a list that can be more than one community between apostrophe +# and separated by blank space. Ex: ' ' +set vrf name protocols bgp address-family route-target vpn export '' +set vrf name protocols bgp address-family route-target vpn import '' + +# Enable VPN export/import under this VRF +set vrf name protocols bgp address-family export vpn +set vrf name protocols bgp address-family import vpn +``` + +A key point to understand is that if we need two VRFs to communicate between +each other EXPORT rt from VRF1 has to be in the IMPORT rt list from VRF2. But +this is only in ONE direction, to complete the communication the EXPORT rt from +VRF2 has to be in the IMPORT rt list from VRF1. + +There are some cases where this is not needed -for example, in some +DDoS appliance- but most inter-vrf routing designs use the above configurations. + +- Verification + +After configured all the VRFs involved in this topology we take a deeper look +at both BGP and Routing table for the VRF LAN1 + +```none +# show ip bgp vrf +# show bgp vrf ipv6 + +vyos@Core# run show ip bgp vrf LAN1 +BGP table version is 53, local router ID is 10.1.1.1, vrf id 8 +Default local pref 100, local AS 64496 +Status codes: s suppressed, d damped, h history, * valid, > best, = multipath, + i internal, r RIB-failure, S Stale, R Removed +Nexthop codes: @NNN nexthop's vrf id, < announce-nh-self +Origin codes: i - IGP, e - EGP, ? - incomplete +RPKI validation codes: V valid, I invalid, N Not found + + Network Next Hop Metric LocPrf Weight Path +*> 0.0.0.0/0 10.2.2.2@7< 0 64497 i +*> 10.0.0.0/24 10.1.1.2 0 32768 ? +*> 10.2.2.0/30 10.2.2.2@7< 0 0 64497 ? +*> 192.0.2.0/24 10.2.2.2@7< 0 0 64497 ? +*> 192.168.0.0/24 192.168.3.2@11< 0 32768 ? +*> 198.51.100.0/24 10.2.2.2@7< 0 0 64497 ? +*> 203.0.113.0/24 10.2.2.2@7< 0 0 64497 ? + +vyos@Core# run show bgp vrf LAN1 ipv6 +BGP table version is 13, local router ID is 10.1.1.1, vrf id 8 +Default local pref 100, local AS 64496 +Status codes: s suppressed, d damped, h history, * valid, > best, = multipath, + i internal, r RIB-failure, S Stale, R Removed +Nexthop codes: @NNN nexthop's vrf id, < announce-nh-self +Origin codes: i - IGP, e - EGP, ? - incomplete +RPKI validation codes: V valid, I invalid, N Not found + +Network Next Hop Metric LocPrf Weight Path +*> ::/0 fe80::5200:ff:fe02:3@7< + 0 64497 i +*> 2001:db8::6/127 fe80::5200:ff:fe02:3@7< + 0 0 64497 ? +*> 2001:db8:0:1::/64 + 2001:db8::1 0 32768 ? +*> 2001:db8:0:3::/64 + 2001:db8::5@11< 0 32768 ? +*> 2001:db8:1::/48 fe80::5200:ff:fe02:3@7< + 0 0 64497 ? +*> 2001:db8:2::/48 fe80::5200:ff:fe02:3@7< + 0 0 64497 ? +*> 2001:db8:3::/48 fe80::5200:ff:fe02:3@7< + 0 0 64497 ? + + +# show ip route vrf +# show ipv6 route vrf + +vyos@Core:~$ show ip route vrf LAN1 +Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, + f - OpenFabric, + > - selected route, * - FIB route, q - queued, r - rejected, b - backup + t - trapped, o - offload failure + +VRF LAN1: +B>* 0.0.0.0/0 [20/0] via 10.2.2.2, eth3 (vrf Internet), weight 1, 00:00:38 +S>* 10.0.0.0/24 [1/0] via 10.1.1.2, eth0, weight 1, 00:29:57 +C>* 10.1.1.0/30 is directly connected, eth0, 00:29:59 +B 10.2.2.0/30 [20/0] via 10.2.2.2 (vrf Internet) inactive, weight 1, 00:00:38 +B>* 172.16.0.0/24 [20/0] via 172.16.2.2, eth1 (vrf LAN2), weight 1, 00:00:38 +B>* 192.0.2.0/24 [20/0] via 10.2.2.2, eth3 (vrf Internet), weight 1, 00:00:38 +B>* 198.51.100.0/24 [20/0] via 10.2.2.2, eth3 (vrf Internet), weight 1, 00:00:38 +B>* 203.0.113.0/24 [20/0] via 10.2.2.2, eth3 (vrf Internet), weight 1, 00:00:38 + +vyos@Core# run show ipv6 route vrf LAN1 +Codes: K - kernel route, C - connected, S - static, R - RIPng, + O - OSPFv3, I - IS-IS, B - BGP, N - NHRP, T - Table, + v - VNC, V - VNC-Direct, A - Babel, F - PBR, + f - OpenFabric, + > - selected route, * - FIB route, q - queued, r - rejected, b - backup + t - trapped, o - offload failure + +VRF LAN1: +B>* ::/0 [20/0] via fe80::5200:ff:fe02:3, eth3 (vrf Internet), weight 1, 00:07:50 +C>* 2001:db8::/127 is directly connected, eth0, 05:33:43 +B>* 2001:db8::6/127 [20/0] via fe80::5200:ff:fe02:3, eth3 (vrf Internet), weight 1, 00:07:50 +S>* 2001:db8:0:1::/64 [1/0] via 2001:db8::1, eth0, weight 1, 05:31:03 +B>* 2001:db8:0:3::/64 [20/0] via 2001:db8::5, eth2 (vrf Management), weight 1, 00:07:50 +B>* 2001:db8:1::/48 [20/0] via fe80::5200:ff:fe02:3, eth3 (vrf Internet), weight 1, 00:07:50 +B>* 2001:db8:2::/48 [20/0] via fe80::5200:ff:fe02:3, eth3 (vrf Internet), weight 1, 00:07:50 +B>* 2001:db8:3::/48 [20/0] via fe80::5200:ff:fe02:3, eth3 (vrf Internet), weight 1, 00:07:50 +C>* fe80::/64 is directly connected, eth0, 05:33:43 +``` + +As we can see in the BGP table any imported route has been injected with a "@" +followed by the VPN id; In the routing table of the VRF, if the route was +installed, we can see -between round brackets- the exported VRF table. + +#### Step 4: End to End verification + +Now we perform some end-to-end testing + +- From Management to LAN1/LAN2 + +```none +vyos@Management:~$ ping 10.0.0.1 source-address 192.168.0.1 +PING 10.0.0.1 (10.0.0.1) from 192.168.0.1 : 56(84) bytes of data. +64 bytes from 10.0.0.1: icmp_seq=1 ttl=63 time=1.93 ms +64 bytes from 10.0.0.1: icmp_seq=2 ttl=63 time=2.12 ms +64 bytes from 10.0.0.1: icmp_seq=3 ttl=63 time=2.12 ms +^C +--- 10.0.0.1 ping statistics --- +3 packets transmitted, 3 received, 0% packet loss, time 2005ms +rtt min/avg/max/mdev = 1.931/2.056/2.123/0.088 ms +vyos@Management:~$ ping 172.16.0.1 source-address 192.168.0.1 +PING 172.16.0.1 (172.16.0.1) from 192.168.0.1 : 56(84) bytes of data. +64 bytes from 172.16.0.1: icmp_seq=1 ttl=63 time=1.62 ms +64 bytes from 172.16.0.1: icmp_seq=2 ttl=63 time=1.75 ms +^C +--- 172.16.0.1 ping statistics --- +2 packets transmitted, 2 received, 0% packet loss, time 1001ms +rtt min/avg/max/mdev = 1.621/1.686/1.752/0.065 ms +vyos@Management:~$ ping 2001:db8:0:1::1 source-address 2001:db8:0:3::1 +PING 2001:db8:0:1::1(2001:db8:0:1::1) from 2001:db8:0:3::1 : 56 data bytes +64 bytes from 2001:db8:0:1::1: icmp_seq=1 ttl=63 time=2.44 ms +64 bytes from 2001:db8:0:1::1: icmp_seq=2 ttl=63 time=2.40 ms +64 bytes from 2001:db8:0:1::1: icmp_seq=3 ttl=63 time=2.41 ms +^C +--- 2001:db8:0:1::1 ping statistics --- +3 packets transmitted, 3 received, 0% packet loss, time 2003ms +rtt min/avg/max/mdev = 2.399/2.418/2.442/0.017 ms +vyos@Management:~$ ping 2001:db8:0:2::1 source-address 2001:db8:0:3::1 +PING 2001:db8:0:2::1(2001:db8:0:2::1) from 2001:db8:0:3::1 : 56 data bytes +64 bytes from 2001:db8:0:2::1: icmp_seq=1 ttl=63 time=1.66 ms +64 bytes from 2001:db8:0:2::1: icmp_seq=2 ttl=63 time=1.99 ms +64 bytes from 2001:db8:0:2::1: icmp_seq=3 ttl=63 time=1.88 ms +64 bytes from 2001:db8:0:2::1: icmp_seq=4 ttl=63 time=2.32 ms +^C +--- 2001:db8:0:2::1 ping statistics --- +4 packets transmitted, 4 received, 0% packet loss, time 3005ms +rtt min/avg/max/mdev = 1.660/1.960/2.315/0.236 ms +``` + +- From Management to Outside (fails as intended) + +```none +vyos@Management:~$ show ip route +Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, + f - OpenFabric, + > - selected route, * - FIB route, q - queued, r - rejected, b - backup + t - trapped, o - offload failure + +S>* 0.0.0.0/0 [1/0] via 192.168.3.1, eth2, weight 1, 00:01:58 +C>* 192.168.0.0/24 is directly connected, dum0, 00:02:05 +C>* 192.168.3.0/30 is directly connected, eth2, 00:02:03 +vyos@Management:~$ ping 192.0.2.1 +PING 192.0.2.1 (192.0.2.1) 56(84) bytes of data. +From 192.168.3.1 icmp_seq=1 Destination Net Unreachable +From 192.168.3.1 icmp_seq=2 Destination Net Unreachable +^C +--- 192.0.2.1 ping statistics --- +2 packets transmitted, 0 received, +2 errors, 100% packet loss, time 1002ms + +vyos@Management:~$ ping 195.51.100.1 +PING 195.51.100.1 (195.51.100.1) 56(84) bytes of data. +From 192.168.3.1 icmp_seq=1 Destination Net Unreachable +From 192.168.3.1 icmp_seq=2 Destination Net Unreachable +From 192.168.3.1 icmp_seq=3 Destination Net Unreachable +^C +--- 195.51.100.1 ping statistics --- +3 packets transmitted, 0 received, +3 errors, 100% packet loss, time 2003ms + +vyos@Management:~$ ping 2001:db8:1::1 +PING 2001:db8:1::1(2001:db8:1::1) 56 data bytes +From 2001:db8::4 icmp_seq=1 Destination unreachable: No route +From 2001:db8::4 icmp_seq=2 Destination unreachable: No route +^C +--- 2001:db8:1::1 ping statistics --- +2 packets transmitted, 0 received, +2 errors, 100% packet loss, time 1002ms + +vyos@Management:~$ ping 2001:db8:2::1 +PING 2001:db8:2::1(2001:db8:2::1) 56 data bytes +From 2001:db8::4 icmp_seq=1 Destination unreachable: No route +From 2001:db8::4 icmp_seq=2 Destination unreachable: No route +^C +--- 2001:db8:2::1 ping statistics --- +2 packets transmitted, 0 received, +2 errors, 100% packet loss, time 1002ms +``` + +- LAN1 to Outside + +```none +vyos@LAN1:~$ ping 192.0.2.1 source-address 10.0.0.1 +PING 192.0.2.1 (192.0.2.1) from 10.0.0.1 : 56(84) bytes of data. +64 bytes from 192.0.2.1: icmp_seq=1 ttl=63 time=1.47 ms +64 bytes from 192.0.2.1: icmp_seq=2 ttl=63 time=1.41 ms +64 bytes from 192.0.2.1: icmp_seq=3 ttl=63 time=1.80 ms +^C +--- 192.0.2.1 ping statistics --- +3 packets transmitted, 3 received, 0% packet loss, time 2004ms +rtt min/avg/max/mdev = 1.414/1.563/1.803/0.171 ms +vyos@LAN1:~$ ping 198.51.100.1 source-address 10.0.0.1 +PING 198.51.100.1 (198.51.100.1) from 10.0.0.1 : 56(84) bytes of data. +64 bytes from 198.51.100.1: icmp_seq=1 ttl=63 time=1.71 ms +64 bytes from 198.51.100.1: icmp_seq=2 ttl=63 time=1.83 ms +^C +--- 198.51.100.1 ping statistics --- +2 packets transmitted, 2 received, 0% packet loss, time 1002ms +rtt min/avg/max/mdev = 1.705/1.766/1.828/0.061 ms +vyos@LAN1:~$ ping 203.0.113.1 source-address 10.0.0.1 +PING 203.0.113.1 (203.0.113.1) from 10.0.0.1 : 56(84) bytes of data. +64 bytes from 203.0.113.1: icmp_seq=1 ttl=63 time=1.25 ms +64 bytes from 203.0.113.1: icmp_seq=2 ttl=63 time=1.88 ms +^C +--- 203.0.113.1 ping statistics --- +2 packets transmitted, 2 received, 0% packet loss, time 1003ms +rtt min/avg/max/mdev = 1.249/1.566/1.884/0.317 ms +vyos@LAN1:~$ ping 2001:db8:1::1 source-address 2001:db8:0:1::1 +PING 2001:db8:1::1(2001:db8:1::1) from 2001:db8:0:1::1 : 56 data bytes +64 bytes from 2001:db8:1::1: icmp_seq=1 ttl=63 time=2.35 ms +64 bytes from 2001:db8:1::1: icmp_seq=2 ttl=63 time=2.29 ms +64 bytes from 2001:db8:1::1: icmp_seq=3 ttl=63 time=2.22 ms +^C +--- 2001:db8:1::1 ping statistics --- +3 packets transmitted, 3 received, 0% packet loss, time 2004ms +rtt min/avg/max/mdev = 2.215/2.285/2.352/0.055 ms +vyos@LAN1:~$ ping 2001:db8:2::1 source-address 2001:db8:0:1::1 +PING 2001:db8:2::1(2001:db8:2::1) from 2001:db8:0:1::1 : 56 data bytes +64 bytes from 2001:db8:2::1: icmp_seq=1 ttl=63 time=1.37 ms +64 bytes from 2001:db8:2::1: icmp_seq=2 ttl=63 time=2.68 ms +64 bytes from 2001:db8:2::1: icmp_seq=3 ttl=63 time=2.00 ms +^C +--- 2001:db8:2::1 ping statistics --- +3 packets transmitted, 3 received, 0% packet loss, time 2003ms +rtt min/avg/max/mdev = 1.367/2.015/2.679/0.535 ms +``` + +:::{note} +we are using "source-address" option cause we are not redistributing +connected interfaces into BGP on the Core router hence there is no comeback +route and ping will fail. +::: + +- LAN1 to LAN2 + +```none +vyos@LAN1:~$ ping 172.16.0.1 source-address 10.0.0.1 +PING 172.16.0.1 (172.16.0.1) from 10.0.0.1 : 56(84) bytes of data. +64 bytes from 172.16.0.1: icmp_seq=1 ttl=63 time=3.00 ms +64 bytes from 172.16.0.1: icmp_seq=2 ttl=63 time=2.20 ms +^C +--- 172.16.0.1 ping statistics --- +2 packets transmitted, 2 received, 0% packet loss, time 1002ms +rtt min/avg/max/mdev = 2.199/2.600/3.001/0.401 ms +vyos@LAN1:~$ ping 2001:db8:0:2::1 source 2001:db8:0:1::1 +PING 2001:db8:0:2::1(2001:db8:0:2::1) from 2001:db8:0:1::1 : 56 data bytes +64 bytes from 2001:db8:0:2::1: icmp_seq=1 ttl=63 time=4.82 ms +64 bytes from 2001:db8:0:2::1: icmp_seq=2 ttl=63 time=1.95 ms +64 bytes from 2001:db8:0:2::1: icmp_seq=3 ttl=63 time=1.98 ms +^C +--- 2001:db8:0:2::1 ping statistics --- +3 packets transmitted, 3 received, 0% packet loss, time 2003ms +rtt min/avg/max/mdev = 1.949/2.915/4.815/1.343 ms +``` + +## Conclusions + +Inter-VRF routing is a well-known solution to address complex routing scenarios +that enable -in a dynamic way- to leak routes between VRFs. Is recommended to +take special consideration while designing route-targets and its application as +it can minimize future interventions while creating a new VRF will automatically +take the desired effect in its propagation. + +## Appendix-A + +### Full configuration from all devices + +- Core + +```none +set interfaces ethernet eth0 address '10.1.1.1/30' +set interfaces ethernet eth0 address '2001:db8::/127' +set interfaces ethernet eth0 vrf 'LAN1' +set interfaces ethernet eth1 address '172.16.2.1/30' +set interfaces ethernet eth1 address '2001:db8::2/127' +set interfaces ethernet eth1 vrf 'LAN2' +set interfaces ethernet eth2 address '192.168.3.1/30' +set interfaces ethernet eth2 address '2001:db8::4/127' +set interfaces ethernet eth2 vrf 'Management' +set interfaces ethernet eth3 address '10.2.2.1/30' +set interfaces ethernet eth3 address '2001:db8::6/127' +set interfaces ethernet eth3 vrf 'Internet' +set protocols bgp address-family ipv4-unicast +set protocols bgp system-as '64496' +set vrf name Internet protocols bgp address-family ipv4-unicast export vpn +set vrf name Internet protocols bgp address-family ipv4-unicast import vpn +set vrf name Internet protocols bgp address-family ipv4-unicast rd vpn export '64496:100' +set vrf name Internet protocols bgp address-family ipv4-unicast route-target vpn export '64496:100' +set vrf name Internet protocols bgp address-family ipv4-unicast route-target vpn import '64496:1 64496:2' +set vrf name Internet protocols bgp address-family ipv6-unicast export vpn +set vrf name Internet protocols bgp address-family ipv6-unicast import vpn +set vrf name Internet protocols bgp address-family ipv6-unicast rd vpn export '64496:100' +set vrf name Internet protocols bgp address-family ipv6-unicast route-target vpn export '64496:100' +set vrf name Internet protocols bgp address-family ipv6-unicast route-target vpn import '64496:1 64496:2' +set vrf name Internet protocols bgp neighbor 10.2.2.2 address-family ipv4-unicast +set vrf name Internet protocols bgp neighbor 10.2.2.2 remote-as '64497' +set vrf name Internet protocols bgp neighbor 2001:db8::7 address-family ipv6-unicast +set vrf name Internet protocols bgp neighbor 2001:db8::7 remote-as '64497' +set vrf name Internet table '104' +set vrf name LAN1 protocols bgp address-family ipv4-unicast export vpn +set vrf name LAN1 protocols bgp address-family ipv4-unicast import vpn +set vrf name LAN1 protocols bgp address-family ipv4-unicast rd vpn export '64496:1' +set vrf name LAN1 protocols bgp address-family ipv4-unicast redistribute static +set vrf name LAN1 protocols bgp address-family ipv4-unicast route-target vpn export '64496:1' +set vrf name LAN1 protocols bgp address-family ipv4-unicast route-target vpn import '64496:100 64496:50 64496:2' +set vrf name LAN1 protocols bgp address-family ipv6-unicast export vpn +set vrf name LAN1 protocols bgp address-family ipv6-unicast import vpn +set vrf name LAN1 protocols bgp address-family ipv6-unicast rd vpn export '64496:1' +set vrf name LAN1 protocols bgp address-family ipv6-unicast redistribute static +set vrf name LAN1 protocols bgp address-family ipv6-unicast route-target vpn export '64496:1' +set vrf name LAN1 protocols bgp address-family ipv6-unicast route-target vpn import '64496:100 64496:50 64496:2' +set vrf name LAN1 protocols static route 10.0.0.0/24 next-hop 10.1.1.2 +set vrf name LAN1 protocols static route6 2001:db8:0:1::/64 next-hop 2001:db8::1 +set vrf name LAN1 table '101' +set vrf name LAN2 protocols bgp address-family ipv4-unicast export vpn +set vrf name LAN2 protocols bgp address-family ipv4-unicast import vpn +set vrf name LAN2 protocols bgp address-family ipv4-unicast rd vpn export '64496:2' +set vrf name LAN2 protocols bgp address-family ipv4-unicast redistribute static +set vrf name LAN2 protocols bgp address-family ipv4-unicast route-target vpn export '64496:2' +set vrf name LAN2 protocols bgp address-family ipv4-unicast route-target vpn import '64496:100 64496:50 64496:1' +set vrf name LAN2 protocols bgp address-family ipv6-unicast export vpn +set vrf name LAN2 protocols bgp address-family ipv6-unicast import vpn +set vrf name LAN2 protocols bgp address-family ipv6-unicast rd vpn export '64496:2' +set vrf name LAN2 protocols bgp address-family ipv6-unicast redistribute static +set vrf name LAN2 protocols bgp address-family ipv6-unicast route-target vpn export '64496:2' +set vrf name LAN2 protocols bgp address-family ipv6-unicast route-target vpn import '64496:100 64496:50 64496:1' +set vrf name LAN2 protocols static route 172.16.0.0/24 next-hop 172.16.2.2 +set vrf name LAN2 protocols static route6 2001:db8:0:2::/64 next-hop 2001:db8::3 +set vrf name LAN2 table '102' +set vrf name Management protocols bgp address-family ipv4-unicast export vpn +set vrf name Management protocols bgp address-family ipv4-unicast import vpn +set vrf name Management protocols bgp address-family ipv4-unicast rd vpn export '64496:50' +set vrf name Management protocols bgp address-family ipv4-unicast redistribute static +set vrf name Management protocols bgp address-family ipv4-unicast route-target vpn export '64496:50' +set vrf name Management protocols bgp address-family ipv4-unicast route-target vpn import '64496:1 64496:2' +set vrf name Management protocols bgp address-family ipv6-unicast export vpn +set vrf name Management protocols bgp address-family ipv6-unicast import vpn +set vrf name Management protocols bgp address-family ipv6-unicast rd vpn export '64496:50' +set vrf name Management protocols bgp address-family ipv6-unicast redistribute static +set vrf name Management protocols bgp address-family ipv6-unicast route-target vpn export '64496:50' +set vrf name Management protocols bgp address-family ipv6-unicast route-target vpn import '64496:1 64496:2' +set vrf name Management protocols static route 192.168.0.0/24 next-hop 192.168.3.2 +set vrf name Management protocols static route6 2001:db8:0:3::/64 next-hop 2001:db8::5 +set vrf name Management table '103' +``` + +- LAN1 + +```none +set interfaces dummy dum0 address '10.0.0.1/24' +set interfaces dummy dum0 address '2001:db8:0:1::1/64' +set interfaces ethernet eth0 address '10.1.1.2/30' +set interfaces ethernet eth0 address '2001:db8::1/127' +set protocols static route 0.0.0.0/0 next-hop 10.1.1.1 +set protocols static route6 ::/0 next-hop 2001:db8::1 +``` + +- LAN2 + +```none +set interfaces dummy dum0 address '172.16.0.1/24' +set interfaces dummy dum0 address '2001:db8:0:2::1/64' +set interfaces ethernet eth0 hw-id '50:00:00:03:00:00' +set interfaces ethernet eth1 address '172.16.2.2/30' +set interfaces ethernet eth1 address '2001:db8::3/127' +set protocols static route 0.0.0.0/0 next-hop 172.16.2.1 +set protocols static route6 ::/0 next-hop 2001:db8::2 +``` + +- Management + +```none +set interfaces dummy dum0 address '192.168.0.1/24' +set interfaces dummy dum0 address '2001:db8:0:3::1/64' +set interfaces ethernet eth2 address '192.168.3.2/30' +set interfaces ethernet eth2 address '2001:db8::5/127' +set protocols static route 0.0.0.0/0 next-hop 192.168.3.1 +set protocols static route6 ::/0 next-hop 2001:db8::4 +``` + +- ISP + +```none +set interfaces dummy dum0 address '192.0.2.1/24' +set interfaces dummy dum0 address '2001:db8:1::1/48' +set interfaces dummy dum1 address '198.51.100.1/24' +set interfaces dummy dum1 address '2001:db8:2::1/48' +set interfaces dummy dum2 address '203.0.113.1/24' +set interfaces dummy dum2 address '2001:db8:3::1/48' +set interfaces ethernet eth3 address '10.2.2.2/30' +set interfaces ethernet eth3 address '2001:db8::7/127' +set protocols bgp address-family ipv4-unicast redistribute connected +set protocols bgp address-family ipv6-unicast redistribute connected +set protocols bgp system-as '64497' +set protocols bgp neighbor 10.2.2.1 address-family ipv4-unicast default-originate +set protocols bgp neighbor 10.2.2.1 remote-as '64496' +set protocols bgp neighbor 2001:db8::6 address-family ipv6-unicast default-originate +set protocols bgp neighbor 2001:db8::6 remote-as '64496' +set protocols static route 0.0.0.0/0 next-hop 10.2.2.1 +set protocols static route6 ::/0 next-hop 2001:db8::6 +``` + +## Appendix-B + +### Route-Filtering + +When importing routes using MP-BGP it is possible to filter a subset of them +before are injected in the BGP table. One of the most common case is to use a +route-map with an prefix-list. + +- Configuration + +We create a prefix-list first and add all the routes we need to. + +```none +# set both ipv4 and ipv6 policies + +set policy prefix-list LAN2-Internet rule 1 action 'permit' +set policy prefix-list LAN2-Internet rule 1 le '24' +set policy prefix-list LAN2-Internet rule 1 prefix '198.51.0.0/16' +set policy prefix-list LAN2-Internet rule 2 action 'permit' +set policy prefix-list LAN2-Internet rule 2 prefix '192.0.2.0/24' +set policy prefix-list LAN2-Internet rule 3 action 'permit' +set policy prefix-list LAN2-Internet rule 3 prefix '192.168.0.0/24' +set policy prefix-list LAN2-Internet rule 4 action 'permit' +set policy prefix-list LAN2-Internet rule 4 prefix '10.0.0.0/24' + +set policy prefix-list6 LAN2-Internet-v6 rule 1 action 'permit' +set policy prefix-list6 LAN2-Internet-v6 rule 1 prefix '2001:db8:1::/48' +set policy prefix-list6 LAN2-Internet-v6 rule 2 action 'permit' +set policy prefix-list6 LAN2-Internet-v6 rule 2 prefix '2001:db8:2::/48' +set policy prefix-list6 LAN2-Internet-v6 rule 3 action 'permit' +set policy prefix-list6 LAN2-Internet-v6 rule 3 prefix '2001:db8:0:3::/64' +set policy prefix-list6 LAN2-Internet-v6 rule 4 action 'permit' +set policy prefix-list6 LAN2-Internet-v6 rule 4 prefix '2001:db8:0:1::/64' +``` + +Then add a route-map and reference to above prefix. Consider that the actions +taken inside the prefix will MATCH the routes that will be affected by the +actions inside the rules of the route-map. + +```none +set policy route-map LAN2-Internet rule 1 action 'permit' +set policy route-map LAN2-Internet rule 1 match ip address prefix-list 'LAN2-Internet' + +set policy route-map LAN2-Internet-v6 rule 1 action 'permit' +set policy route-map LAN2-Internet-v6 rule 1 match ipv6 address prefix-list 'LAN2-Internet-v6' +``` + +We are using a "white list" approach by allowing only what is necessary. In case +that need to implement a "black list" approach then you will need to change the +action in the route-map for a deny BUT you need to add a rule that permits the +rest due to the implicit deny in the route-map. + +Then we need to attach the policy to the BGP process. This needs to be under +the import statement in the vrf we need to filter. + +```none +set vrf name LAN2 protocols bgp address-family ipv4-unicast route-map vpn import 'LAN2-Internet' +set vrf name LAN2 protocols bgp address-family ipv6-unicast route-map vpn import 'LAN2-Internet-v6' +``` + +- Verification + +```none +# show ip route vrf LAN2 + +B>* 10.0.0.0/24 [20/0] via 10.1.1.2, eth0 (vrf LAN1), weight 1, 00:45:28 +S>* 172.16.0.0/24 [1/0] via 172.16.2.2, eth1, weight 1, 00:45:32 +C>* 172.16.2.0/30 is directly connected, eth1, 00:45:39 +B>* 192.0.2.0/24 [20/0] via 10.2.2.2, eth3 (vrf Internet), weight 1, 00:45:24 +B>* 192.168.0.0/24 [20/0] via 192.168.3.2, eth2 (vrf Managment), weight 1, 00:45:27 +B>* 198.51.100.0/24 [20/0] via 10.2.2.2, eth3 (vrf Internet), weight 1, 00:45:24 + +# show ipv6 route vrf LAN2 + +C>* 2001:db8::2/127 is directly connected, eth1, 00:46:26 +B>* 2001:db8:0:1::/64 [20/0] via 2001:db8::1, eth0 (vrf LAN1), weight 1, 00:46:17 +S>* 2001:db8:0:2::/64 [1/0] via 2001:db8::3, eth1, weight 1, 00:46:21 +B>* 2001:db8:0:3::/64 [20/0] via 2001:db8::5, eth2 (vrf Managment), weight 1, 00:46:16 +B>* 2001:db8:1::/48 [20/0] via fe80::5200:ff:fe02:3, eth3 (vrf Internet), weight 1, 00:46:13 +B>* 2001:db8:2::/48 [20/0] via fe80::5200:ff:fe02:3, eth3 (vrf Internet), weight 1, 00:46:13 +C>* fe80::/64 is directly connected, eth1, 00:46:27 +``` + +As we can see even if both VRF LAN1 and LAN2 has the same import RTs we are able +to select which routes are effectively imported and installed. diff --git a/docs/configexamples/md-ipsec-cisco-policy-based.md b/docs/configexamples/md-ipsec-cisco-policy-based.md new file mode 100644 index 00000000..4ac4b7e7 --- /dev/null +++ b/docs/configexamples/md-ipsec-cisco-policy-based.md @@ -0,0 +1,357 @@ +--- +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 | ++------------+---------+ +``` + +**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..9cad654b --- /dev/null +++ b/docs/configexamples/md-ipsec-cisco-route-based.md @@ -0,0 +1,402 @@ +--- +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 + +```{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..27d97f8f --- /dev/null +++ b/docs/configexamples/md-ipsec-pa-route-based.md @@ -0,0 +1,420 @@ +--- +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 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' +``` + +### Palo Alto + +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..97ce2e2a --- /dev/null +++ b/docs/configexamples/md-l3vpn-hub-and-spoke.md @@ -0,0 +1,1096 @@ +# 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..e05ee2be --- /dev/null +++ b/docs/configexamples/md-lac-lns.md @@ -0,0 +1,178 @@ +--- +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..b30476ae --- /dev/null +++ b/docs/configexamples/md-nmp.md @@ -0,0 +1,44 @@ +lastproofread +2023-03-26 + +# 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 just should follow the pictures: + +Network Topology Diagram + +Network Topology Diagram + +Network Topology Diagram + +Network Topology Diagram + +Network Topology Diagram + +Network Topology Diagram + +Network Topology Diagram + +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..13b990f6 --- /dev/null +++ b/docs/configexamples/md-policy-based-ipsec-and-firewall.md @@ -0,0 +1,268 @@ +(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: accepd 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..1314fcf1 --- /dev/null +++ b/docs/configexamples/md-pppoe-ipv6-basic.md @@ -0,0 +1,111 @@ +--- +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 user +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..0405b534 --- /dev/null +++ b/docs/configexamples/md-qos.md @@ -0,0 +1,203 @@ +--- +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..6b1930e9 --- /dev/null +++ b/docs/configexamples/md-site-2-site-cisco.md @@ -0,0 +1,167 @@ +# 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..6dcf88c1 --- /dev/null +++ b/docs/configexamples/md-wan-load-balancing.md @@ -0,0 +1,179 @@ +--- +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..be80ee55 --- /dev/null +++ b/docs/configexamples/md-zone-policy.md @@ -0,0 +1,415 @@ +--- +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..6cb64225 --- /dev/null +++ b/docs/configuration/container/md-index.md @@ -0,0 +1,479 @@ +--- +lastproofread: '2024-07-03' +--- + +# Container + +The VyOS container implementation is based on [Podman](https://podman.io/) as +a deamonless container engine. + +## Configuration + +```{cfgcmd} set container name \ image + +Sets the image name in the hub registry + +:::{code-block} none +set container name mysql-server image mysql:8.0 +::: + +If a registry is not specified, Docker.io will be used as the container +registry unless an alternative registry is specified using +`set container registry ` or the registry is included +in the image name + +:::{code-block} none +set container name mysql-server image quay.io/mysql:8.0 +::: +``` + + +```{cfgcmd} set container name \ entrypoint \ + +Override the default entrypoint from the image for a container. +``` + + +```{cfgcmd} set container name \ command \ + +Override the default command from the image for a container. +``` + + +```{cfgcmd} set container name \ arguments \ + +Set the command arguments for a container. +``` + + +```{cfgcmd} set container name \ host-name \ + +Set the host name for a container. +``` + + +```{cfgcmd} set container name \ allow-host-pid + +The container and the host share the same process namespace. +This means that processes running on the host are visible inside the +container, and processes inside the container are visible on the host. + +The command translates to "--pid host" when the container is created. +``` + + +```{cfgcmd} set container name \ allow-host-networks + +Allow host networking in a container. The network stack of the container is +not isolated from the host and will use the host IP. + +The command translates to "--net host" when the container is created. + +:::{note} +**allow-host-networks** cannot be used with **network** +::: +``` + + +```{cfgcmd} set container name \ network \ + +Attaches user-defined network to a container. +Only one network must be specified and must already exist. +``` + + +```{cfgcmd} set container name \ network \ address \ + +Optionally set a specific static IPv4 or IPv6 address for the container. +This address must be within the named network prefix. + +:::{note} +The first IP in the container network is reserved by the +engine and cannot be used +::: +``` + + +```{cfgcmd} set container name \ name-server \ + +Optionally set a custom name server. +If a container network is used with DNS enabled, +this setting will not have any effect. +``` + + +```{cfgcmd} set container name \ description \ + +Set a container description +``` + + +```{cfgcmd} set container name \ environment \ value \ + +Add custom environment variables. +Multiple environment variables are allowed. +The following commands translate to "-e key=value" when the container +is created. + +:::{code-block} none +set container name mysql-server environment MYSQL_DATABASE value 'zabbix' +set container name mysql-server environment MYSQL_USER value 'zabbix' +set container name mysql-server environment MYSQL_PASSWORD value 'zabbix_pwd' +set container name mysql-server environment MYSQL_ROOT_PASSWORD value 'root_pwd' +::: +``` + + +```{cfgcmd} set container name \ port \ source \ + +``` +```{cfgcmd} set container name \ port \ destination \ +``` + +```{cfgcmd} set container name \ port \ protocol \ + +Publish a port for the container. + +:::{code-block} none +set container name zabbix-web-nginx-mysql port http source 80 +set container name zabbix-web-nginx-mysql port http destination 8080 +set container name zabbix-web-nginx-mysql port http protocol tcp +::: +``` +:::{note} +Port publishing cannot be used with **network**. For this purpose, a workaround +using destination NAT and static IP assignment for the container is available. +::: +```{cfgcmd} set container name \ volume \ source \ +``` + +```{cfgcmd} set container name \ volume \ destination \ + +Mount a volume into the container + +:::{code-block} none +set container name coredns volume 'corefile' source /config/coredns/Corefile +set container name coredns volume 'corefile' destination /etc/Corefile +::: +``` + +```{cfgcmd} set container name \ volume \ mode \ + +Volume is either mounted as rw (read-write - default) or ro (read-only) +``` + +```{cfgcmd} set container name \ tmpfs \ destination \ + +Mount a tmpfs *(ramdisk)* filesystem to the given path within the container. +``` + +```{cfgcmd} set container name \ tmpfs \ size \ + +Size in MB for tmpfs filesystem, maximum size is 64GB or 50% of the +systems total available memory. +``` + +```{cfgcmd} set container name \ uid \ +``` + +```{cfgcmd} set container name \ gid \ + +Set the User ID or Group ID of the container +``` + +```{cfgcmd} set container name \ restart [no | on-failure | always] + +Set the restart behavior of the container. + +- **no**: Do not restart containers on exit +- **on-failure**: Restart containers when they exit with a non-zero +exit code, retrying indefinitely (default) +- **always**: Restart containers when they exit, regardless of status, +retrying indefinitely +``` + +```{cfgcmd} set container name \ cpu-quota \ + +This specifies the number of CPU resources the container can use. + +Default is 0 for unlimited. +For example, 1.25 limits the container to use up to 1.25 cores +worth of CPU time. +This can be a decimal number with up to three decimal places. + +The command translates to "--cpus=\" when the container is created. +``` + +```{cfgcmd} set container name \ memory \ + +Constrain the memory available to the container. + +Default is 512 MB. Use 0 MB for unlimited memory. +``` + +```{cfgcmd} set container name \ device \ source \ +``` + +```{cfgcmd} set container name \ device \ destination \ + +Add a host device to the container. +``` + +```{cfgcmd} set container name \ capability \ + +Set container capabilities or permissions. + +- **net-admin**: Network operations (interface, firewall, routing tables) +- **net-bind-service**: Bind a socket to privileged ports +(port numbers less than 1024) +- **net-raw**: Permission to create raw network sockets +- **setpcap**: Capability sets (from bounded or inherited set) +- **sys-admin**: Administration operations (quotactl, mount, sethostname, +setdomainame) +- **sys-time**: Permission to set system clock +``` + +```{cfgcmd} set container name \ sysctl parameter \ value \ + +Set container sysctl values. + +The subset of possible parameters are: + +- Kernel Parameters: kernel.msgmax, kernel.msgmnb, kernel.msgmni, kernel.sem, +kernel.shmall, kernel.shmmax, kernel.shmmni, kernel.shm_rmid_forced +- Parameters beginning with fs.mqueue.* +- Parameters beginning with net.* (only if user-defined network is used) +``` + +```{cfgcmd} set container name \ label \ value \ + +Add metadata label for this container. +``` + +```{cfgcmd} set container name \ disable + +Disable a container. +``` + +### Container Health checks + + +By default, no health checks are run, even when defined by the image. + +```{cfgcmd} set container name \ health-check + +Default health check is run for the container if defined by the image. +``` + +```{cfgcmd} set container name \ health-check command \ + +Override the default health check command from the image for a container. +``` + +```{cfgcmd} set container name \ health check interval \ + +Override the default health-check interval. For example: `60` +``` + +```{cfgcmd} set container name \ health check timeout \ + +Override the default health-check timeout. For example: `10` +``` + +```{cfgcmd} set container name \ health check retries \ + +Number of health check retries before container is considered unhealthy. For example: `1` +``` + +### Container Networks + +```{cfgcmd} set container network \ + +Creates a named container network +``` + +```{cfgcmd} set container network \ description + +A brief description what this network is all about. +``` + +```{cfgcmd} set container network \ prefix \ + +Define IPv4 and/or IPv6 prefix for a given network name. +Both IPv4 and IPv6 can be used in parallel. +``` + +```{cfgcmd} set container network \ mtu \ + +Configure {abbr}`MTU (Maximum Transmission Unit)` for a given network. It +is the size (in bytes) of the largest ethernet frame sent on this link. +``` + +```{cfgcmd} set container network \ no-name-server + +Disable Domain Name System (DNS) plugin for this network. +``` + +```{cfgcmd} set container network \ vrf \ + +Bind container network to a given VRF instance. +``` + +### Container Registry + +```{cfgcmd} set container registry \ + +Adds registry to list of unqualified-search-registries. By default, for any +image that does not include the registry in the image name, VyOS will use +docker.io and quay.io as the container registry. +``` + +```{cfgcmd} set container registry \ disable + +Disable a given container registry +``` + +```{cfgcmd} set container registry \ authentication username +``` + +```{cfgcmd} set container registry \ authentication password + +Some container registries require credentials to be used. + +Credentials can be defined here and will only be used when adding a +container image to the system. +``` + +```{cfgcmd} set container registry \ insecure + +Allow registry access over unencrypted HTTP or TLS connections with +untrusted certificates. +``` + +```{cfgcmd} set container registry \ mirror address \ +``` + +```{cfgcmd} set container registry \ mirror host-name \ +``` + +```{cfgcmd} set container registry \ mirror port \ +``` + +```{cfgcmd} set container registry \ mirror path \ + +Registry mirror, use ``(host-name|address)[:port][/path]``. + +If you have mirror http://192.168.1.1:8080 for docker.io, you can use ``docker.io/some/repo`` or run ``podman pull docker.io/some/repo`` + +:::{code-block} none +set container registry docker.io mirror address 192.168.1.1 +set container registry docker.io mirror port 8080 +set container registry docker.io insecure +::: +If http://192.168.1.1:8080 is your own registry, you can use ``192.168.1.1:8080/some/repo`` or run ``podman pull 192.168.1.1:8080/some/repo`` + +:::{code-block} none +set container registry 192.168.1.1:8080 insecure +::: +``` + +### Log Configuration + +```{cfgcmd} set container name \ log-driver [k8s-file | journald | none] + +Set the default log driver for containers. + +- **k8s-file**: Log to a plain text file in Kubernetes-style format. +- **journald**: Log to the system journal +- **none**: Disable logging for the container + +Current default is journald. + +``` + +## Operation Commands + +```{opcmd} add container image \ + +Pull a new image for container +``` +```{opcmd} show container + +Show the list of all active containers. +``` +```{opcmd} show container image + +Show the local container images. +``` +```{opcmd} show container log \ + +Show logs from a given container +``` +```{opcmd} show container network + +Show a list available container networks +``` +```{opcmd} restart container \ + +Restart a given container +``` +```{opcmd} update container image \ + +Update container image +``` +```{opcmd} delete container image \ [force] + +Delete a particular container image based on it's image ID. +You can also delete all container images at once. + +You can not delete a container image if it has more then one tag +assigned, this is why there is a `force` option to pass down to +the container image to also remove those images. +``` + +## Example Configuration + +For the sake of demonstration, [example #1 in the official documentation](https://www.zabbix.com/documentation/current/manual/installation/containers) +to the declarative VyOS CLI syntax. + +```none +set container network zabbix prefix 172.20.0.0/16 +set container network zabbix description 'Network for Zabbix component containers' + +set container name mysql-server image mysql:8.0 +set container name mysql-server network zabbix + +set container name mysql-server environment 'MYSQL_DATABASE' value 'zabbix' +set container name mysql-server environment 'MYSQL_USER' value 'zabbix' +set container name mysql-server environment 'MYSQL_PASSWORD' value 'zabbix_pwd' +set container name mysql-server environment 'MYSQL_ROOT_PASSWORD' value 'root_pwd' + +set container name zabbix-java-gateway image zabbix/zabbix-java-gateway:alpine-5.2-latest +set container name zabbix-java-gateway network zabbix + +set container name zabbix-server-mysql image zabbix/zabbix-server-mysql:alpine-5.2-latest +set container name zabbix-server-mysql network zabbix + +set container name zabbix-server-mysql environment 'DB_SERVER_HOST' value 'mysql-server' +set container name zabbix-server-mysql environment 'MYSQL_DATABASE' value 'zabbix' +set container name zabbix-server-mysql environment 'MYSQL_USER' value 'zabbix' +set container name zabbix-server-mysql environment 'MYSQL_PASSWORD' value 'zabbix_pwd' +set container name zabbix-server-mysql environment 'MYSQL_ROOT_PASSWORD' value 'root_pwd' +set container name zabbix-server-mysql environment 'ZBX_JAVAGATEWAY' value 'zabbix-java-gateway' + +set container name zabbix-server-mysql port zabbix source 10051 +set container name zabbix-server-mysql port zabbix destination 10051 + +set container name zabbix-web-nginx-mysql image zabbix/zabbix-web-nginx-mysql:alpine-5.2-latest +set container name zabbix-web-nginx-mysql network zabbix + +set container name zabbix-web-nginx-mysql environment 'MYSQL_DATABASE' value 'zabbix' +set container name zabbix-web-nginx-mysql environment 'ZBX_SERVER_HOST' value 'zabbix-server-mysql' +set container name zabbix-web-nginx-mysql environment 'DB_SERVER_HOST' value 'mysql-server' +set container name zabbix-web-nginx-mysql environment 'MYSQL_USER' value 'zabbix' +set container name zabbix-web-nginx-mysql environment 'MYSQL_PASSWORD' value 'zabbix_pwd' +set container name zabbix-web-nginx-mysql environment 'MYSQL_ROOT_PASSWORD' value 'root_pwd' + +set container name zabbix-web-nginx-mysql port http source 80 +set container name zabbix-web-nginx-mysql port http destination 8080 +``` diff --git a/docs/configuration/firewall/md-bridge.md b/docs/configuration/firewall/md-bridge.md new file mode 100644 index 00000000..8062e226 --- /dev/null +++ b/docs/configuration/firewall/md-bridge.md @@ -0,0 +1,868 @@ +--- +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: + +```{eval-rst} +.. 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. + +```{eval-rst} +.. cfgcmd:: set firewall bridge forward filter rule <1-999999> action + [accept | continue | drop | jump | queue | return] +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge input filter rule <1-999999> action + [accept | continue | drop | jump | queue | return] +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge output filter rule <1-999999> action + [accept | continue | drop | jump | queue | return] +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge prerouting filter rule <1-999999> action + [accept | continue | drop | jump | notrack | queue | return] +``` + +```{eval-rst} +.. 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. +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge forward filter rule <1-999999> + jump-target +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge input filter rule <1-999999> + jump-target +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge output filter rule <1-999999> + jump-target +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge prerouting filter rule <1-999999> + jump-target +``` + +```{eval-rst} +.. 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: +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge forward filter rule <1-999999> + queue <0-65535> +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge input filter rule <1-999999> + queue <0-65535> +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge output filter rule <1-999999> + queue <0-65535> +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge prerouting filter rule <1-999999> + queue <0-65535> +``` + +```{eval-rst} +.. 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``: +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge forward filter rule <1-999999> + queue-options bypass +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge input filter rule <1-999999> + queue-options bypass +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge output filter rule <1-999999> + queue-options bypass +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge prerouting filter rule <1-999999> + queue-options bypass +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge name rule <1-999999> + queue-options bypass +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge forward filter rule <1-999999> + queue-options fanout +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge input filter rule <1-999999> + queue-options fanout +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge output filter rule <1-999999> + queue-options fanout +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge prerouting filter rule <1-999999> + queue-options fanout +``` + +```{eval-rst} +.. 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**. + +```{eval-rst} +.. cfgcmd:: set firewall bridge forward filter default-action + [accept | drop] +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge input filter default-action + [accept | drop] +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge output filter default-action + [accept | drop] +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge prerouting filter default-action + [accept | drop] +``` + +```{eval-rst} +.. 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. +``` + +```{eval-rst} +.. 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. + +```{eval-rst} +.. cfgcmd:: set firewall bridge forward filter rule <1-999999> log +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge input filter rule <1-999999> log +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge output filter rule <1-999999> log +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge prerouting filter rule <1-999999> log +``` + +```{eval-rst} +.. 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. +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge forward filter default-log +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge input filter default-log +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge output filter default-log +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge prerouting filter default-log +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge name default-log + + Use this command to enable the logging of the default action on + the specified chain. +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge forward filter rule <1-999999> + log-options level [emerg | alert | crit | err | warn | notice + | info | debug] +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge input filter rule <1-999999> + log-options level [emerg | alert | crit | err | warn | notice + | info | debug] +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge output filter rule <1-999999> + log-options level [emerg | alert | crit | err | warn | notice + | info | debug] +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge prerouting filter rule <1-999999> + log-options level [emerg | alert | crit | err | warn | notice + | info | debug] +``` + +```{eval-rst} +.. 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. +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge forward filter rule <1-999999> + log-options group <0-65535> +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge input filter rule <1-999999> + log-options group <0-65535> +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge output filter rule <1-999999> + log-options group <0-65535> +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge prerouting filter rule <1-999999> + log-options group <0-65535> +``` + +```{eval-rst} +.. 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. +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge forward filter rule <1-999999> + log-options snapshot-length <0-9000> +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge input filter rule <1-999999> + log-options snapshot-length <0-9000> +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge output filter rule <1-999999> + log-options snapshot-length <0-9000> +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge prerouting filter rule <1-999999> + log-options snapshot-length <0-9000> +``` + +```{eval-rst} +.. 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. +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge forward filter rule <1-999999> + log-options queue-threshold <0-65535> +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge input filter rule <1-999999> + log-options queue-threshold <0-65535> +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge output filter rule <1-999999> + log-options queue-threshold <0-65535> +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge prerouting filter rule <1-999999> + log-options queue-threshold <0-65535> +``` + +```{eval-rst} +.. 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. + +```{eval-rst} +.. cfgcmd:: set firewall bridge name description + + Provide a rule-set description to a custom firewall chain. +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge forward filter rule <1-999999> + description +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge input filter rule <1-999999> + description +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge output filter rule <1-999999> + description +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge prerouting filter rule <1-999999> + description +``` + +```{eval-rst} +.. 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. + +```{eval-rst} +.. cfgcmd:: set firewall bridge forward filter rule <1-999999> disable +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge input filter rule <1-999999> disable +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge output filter rule <1-999999> disable +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge prerouting filter rule <1-999999> disable +``` + +```{eval-rst} +.. 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: + +```{eval-rst} +.. cfgcmd:: set firewall bridge forward filter rule <1-999999> ethernet-type + [802.1q | 802.1ad | arp | ipv4 | ipv6] +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge input filter rule <1-999999> ethernet-type + [802.1q | 802.1ad | arp | ipv4 | ipv6] +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge output filter rule <1-999999> ethernet-type + [802.1q | 802.1ad | arp | ipv4 | ipv6] +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge prerouting filter rule <1-999999> ethernet-type + [802.1q | 802.1ad | arp | ipv4 | ipv6] +``` + +```{eval-rst} +.. 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. +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge forward filter rule <1-999999> vlan + ethernet-type [802.1q | 802.1ad | arp | ipv4 | ipv6] +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge input filter rule <1-999999> vlan + ethernet-type [802.1q | 802.1ad | arp | ipv4 | ipv6] +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge output filter rule <1-999999> vlan + ethernet-type [802.1q | 802.1ad | arp | ipv4 | ipv6] +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge prerouting filter rule <1-999999> vlan + ethernet-type [802.1q | 802.1ad | arp | ipv4 | ipv6] +``` + +```{eval-rst} +.. 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. +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge forward filter rule <1-999999> vlan id + <0-4096> +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge input filter rule <1-999999> vlan id + <0-4096> +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge output filter rule <1-999999> vlan id + <0-4096> +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge prerouting filter rule <1-999999> vlan id + <0-4096> +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge name rule <1-999999> vlan id + <0-4096> + + Match based on VLAN identifier. Range is also supported. +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge forward filter rule <1-999999> vlan priority + <0-7> +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge input filter rule <1-999999> vlan priority + <0-7> +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge output filter rule <1-999999> vlan priority + <0-7> +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge prerouting filter rule <1-999999> vlan priority + <0-7> +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge name rule <1-999999> vlan priority + <0-7> + + Match based on VLAN priority (Priority Code Point - PCP). Range is also + supported. +``` + +### Packet Modifications + +Starting from **VyOS-1.5-rolling-202410060007**, the firewall can modify +packets before they are sent out. This feaure provides more flexibility in +packet handling. + +```{eval-rst} +.. cfgcmd:: set firewall bridge [prerouting | forward | output] filter + rule <1-999999> set dscp <0-63> + + Set a specific value of Differentiated Services Codepoint (DSCP). +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge [prerouting | forward | output] filter + rule <1-999999> set mark <1-2147483647> + + Set a specific packet mark value. +``` + +```{eval-rst} +.. 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. +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge [prerouting | forward | output] filter + rule <1-999999> set ttl <0-255> + + Set the TTL (Time to Live) value. +``` + +```{eval-rst} +.. cfgcmd:: set firewall bridge [prerouting | forward | output] filter + rule <1-999999> set hop-limit <0-255> + + Set hop limit value. +``` + +```{eval-rst} +.. 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: + +```{eval-rst} +.. 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 + ...`` +``` + +```{eval-rst} +.. 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: + +```{eval-rst} +.. opcmd:: show firewall +``` + +```{eval-rst} +.. opcmd:: show firewall summary +``` + +```{eval-rst} +.. opcmd:: show firewall statistics +``` + +And, to print only bridge firewall information: + +```{eval-rst} +.. opcmd:: show firewall bridge +``` + +```{eval-rst} +.. opcmd:: show firewall bridge forward filter +``` + +```{eval-rst} +.. opcmd:: show firewall bridge forward filter rule +``` + +```{eval-rst} +.. opcmd:: show firewall bridge name +``` + +```{eval-rst} +.. opcmd:: show firewall bridge name rule +``` + +### Show Firewall log + +```{eval-rst} +.. opcmd:: show log firewall +``` + +```{eval-rst} +.. opcmd:: show log firewall bridge +``` + +```{eval-rst} +.. opcmd:: show log firewall bridge forward +``` + +```{eval-rst} +.. opcmd:: show log firewall bridge forward filter +``` + +```{eval-rst} +.. opcmd:: show log firewall bridge name +``` + +```{eval-rst} +.. opcmd:: show log firewall bridge forward filter rule +``` + +```{eval-rst} +.. 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..e43dbd30 --- /dev/null +++ b/docs/configuration/firewall/md-flowtables.md @@ -0,0 +1,189 @@ +--- +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. + +```{eval-rst} +.. 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: + +```{eval-rst} +.. cfgcmd:: set firewall flowtable interface + + Specify interfaces to use in the flowtable. +``` + +```{eval-rst} +.. cfgcmd:: set firewall flowtable description +``` + +Provide a description for the flow table. + +```{eval-rst} +.. 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: + +```{eval-rst} +.. 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``. +``` + +```{eval-rst} +.. 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..5a74266c --- /dev/null +++ b/docs/configuration/firewall/md-global-options.md @@ -0,0 +1,259 @@ +--- +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: + +```{eval-rst} +.. cfgcmd:: set firewall global-options ... +``` + +## Configuration + +```{eval-rst} +.. 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. +``` + +```{eval-rst} +.. cfgcmd:: set firewall global-options apply-to-bridged-traffic [ipv4 | ipv6] + + Apply IPv4 or IPv6 firewall rules to bridged traffic. +``` + +```{eval-rst} +.. 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`` +``` + +```{eval-rst} +.. cfgcmd:: set firewall global-options ip-src-route [enable | disable] +``` + +```{eval-rst} +.. 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`` +``` + +```{eval-rst} +.. cfgcmd:: set firewall global-options receive-redirects [enable | disable] +``` + +```{eval-rst} +.. 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`` +``` + +```{eval-rst} +.. 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`` +``` + +```{eval-rst} +.. 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`` +``` + +```{eval-rst} +.. 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`` +``` + +```{eval-rst} +.. 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`` +``` + +```{eval-rst} +.. 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`` +``` + +```{eval-rst} +.. cfgcmd:: set firewall global-options state-policy established action + [accept | drop | reject] +``` + +```{eval-rst} +.. cfgcmd:: set firewall global-options state-policy established log +``` + +```{eval-rst} +.. 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. +``` + +```{eval-rst} +.. cfgcmd:: set firewall global-options state-policy invalid action + [accept | drop | reject] +``` + +```{eval-rst} +.. cfgcmd:: set firewall global-options state-policy invalid log +``` + +```{eval-rst} +.. 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. +``` + +```{eval-rst} +.. cfgcmd:: set firewall global-options state-policy related action + [accept | drop | reject] +``` + +```{eval-rst} +.. cfgcmd:: set firewall global-options state-policy related log +``` + +```{eval-rst} +.. 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: +``` + +```{eval-rst} +.. cfgcmd:: set firewall global-options timeout other <1-21474836> + :defaultvalue: +``` + +```{eval-rst} +.. cfgcmd:: set firewall global-options timeout tcp close <1-21474836> + :defaultvalue: +``` + +```{eval-rst} +.. cfgcmd:: set firewall global-options timeout tcp close-wait <1-21474836> + :defaultvalue: +``` + +```{eval-rst} +.. cfgcmd:: set firewall global-options timeout tcp established <1-21474836> + :defaultvalue: +``` + +```{eval-rst} +.. cfgcmd:: set firewall global-options timeout tcp fin-wait <1-21474836> + :defaultvalue: +``` + +```{eval-rst} +.. cfgcmd:: set firewall global-options timeout tcp last-ack <1-21474836> + :defaultvalue: +``` + +```{eval-rst} +.. cfgcmd:: set firewall global-options timeout tcp syn-recv <1-21474836> + :defaultvalue: +``` + +```{eval-rst} +.. cfgcmd:: set firewall global-options timeout tcp syn-sent <1-21474836> + :defaultvalue: +``` + +```{eval-rst} +.. cfgcmd:: set firewall global-options timeout tcp time-wait <1-21474836> + :defaultvalue: +``` + +```{eval-rst} +.. cfgcmd:: set firewall global-options timeout udp other <1-21474836> + :defaultvalue: +``` + +```{eval-rst} +.. cfgcmd:: set firewall global-options timeout udp stream <1-21474836> + :defaultvalue: + + Set the timeout in seconds for a protocol or state. +``` diff --git a/docs/configuration/firewall/md-groups.md b/docs/configuration/firewall/md-groups.md new file mode 100644 index 00000000..ed02d249 --- /dev/null +++ b/docs/configuration/firewall/md-groups.md @@ -0,0 +1,526 @@ +--- +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. + +```{eval-rst} +.. cfgcmd:: set firewall group address-group address [address | + address range] +``` + +```{eval-rst} +.. 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 +``` + +```{eval-rst} +.. cfgcmd:: set firewall group address-group description +``` + +```{eval-rst} +.. 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. + +```{eval-rst} +.. cfgcmd:: set firewall group remote-group url + + Specify a remote list of IPv4 and/or IPv6 addresses, ranges, and CIDRs + to fetch. +``` + +```{eval-rst} +.. 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. + +```{eval-rst} +.. cfgcmd:: set firewall group network-group network +``` + +```{eval-rst} +.. 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 +``` + +```{eval-rst} +.. cfgcmd:: set firewall group network-group description +``` + +```{eval-rst} +.. 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. + +```{eval-rst} +.. 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* +``` + +```{eval-rst} +.. 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 `-`. + +```{eval-rst} +.. 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 +``` + +```{eval-rst} +.. cfgcmd:: set firewall group port-group description + + Provide a port group description. +``` + +### MAC Groups + +A **mac group** represents a collection of mac addresses. + +```{eval-rst} +.. 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 +``` + +```{eval-rst} +.. cfgcmd:: set firewall group mac-group description + + Provide a MAC group description. +``` + +### Domain Groups + +A **domain group** represents a collection of domains. + +```{eval-rst} +.. cfgcmd:: set firewall group domain-group address + + Define a domain group. +``` + +```none +set firewall group domain-group DOM address example.com +``` + +```{eval-rst} +.. 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: + +```{eval-rst} +.. cfgcmd:: set firewall group dynamic-group address-group +``` + +```{eval-rst} +.. cfgcmd:: set firewall group dynamic-group ipv6-address-group +``` + +Add description to firewall groups: + +```{eval-rst} +.. cfgcmd:: set firewall group dynamic-group address-group + description +``` + +```{eval-rst} +.. 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: + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 [forward | input | output] filter rule + <1-999999> add-address-to-group destination-address address-group +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name rule <1-999999> add-address-to-group + destination-address address-group +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 [forward | input | output] filter rule + <1-999999> add-address-to-group destination-address address-group +``` + +```{eval-rst} +.. 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: + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 [forward | input | output] filter rule + <1-999999> add-address-to-group source-address address-group +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name rule <1-999999> add-address-to-group + source-address address-group +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 [forward | input | output] filter rule + <1-999999> add-address-to-group source-address address-group +``` + +```{eval-rst} +.. 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. + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 [forward | input | output] filter rule + <1-999999> add-address-to-group [destination-address | source-address] + timeout +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name rule <1-999999> add-address-to-group + [destination-address | source-address] timeout +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 [forward | input | output] filter rule + <1-999999> add-address-to-group [destination-address | source-address] + timeout +``` + +```{eval-rst} +.. 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: + +```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: + +```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: + +```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 + +```{eval-rst} +.. opcmd:: show firewall group +``` + +```{eval-rst} +.. 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..fb7803ce --- /dev/null +++ b/docs/configuration/firewall/md-index.md @@ -0,0 +1,236 @@ +lastproofread +2024-08-05 + +# Firewall + +
+ +Convert raw command blocks in this file to cfgcmd/opcmd +directives for command coverage tracking. + +
+ +
+ +
+ +Warning + +
+ +Due to a race condition that can lead to a failure during boot +process, all interfaces are initialized before firewall is configured. This +leads to a situation where the system is open to all traffic, and can be +considered as a security risk. + +
+ +As VyOS is based on Linux it leverages its firewall. The Netfilter project +created iptables and its successor nftables for the Linux kernel to +work directly on packet data flows. This now extends the concept of +zone-based security to allow for manipulating the data at multiple stages once +accepted by the network interface and the driver before being handed off to +the destination (e.g., a web server OR another device). + +A simplified traffic flow diagram, based on Netfilter packet flow, is shown +next, in order to have a full view and understanding of how packets are +processed, and what possible paths traffic can take. + +
+ +
+ +The main points regarding this packet flow and terminology used in VyOS +firewall are covered below: + +> - **Bridge Port?**: choose appropriate path based on whether interface +> where the packet was received is part of a bridge, or not. + +If the interface where the packet was received isn't part of a bridge, then +packet is processed at the **IP Layer**: + +> - **Prerouting**: All packets that are received by the router +> are processed in this stage, regardless of the destination of the packet. +> Starting from vyos-1.5-rolling-202406120020, a new section was added to +> the firewall configuration. There are several actions that can be done in +> this stage, and currently these actions are also defined in different +> parts of the VyOS configuration. Order is important, and the relevant +> configuration that acts in this stage are: +> +> > - **Firewall prerouting**: rules defined under `set firewall [ipv4 | ipv6] prerouting raw...`. All rules defined in this section are +> > processed before connection tracking subsystem. +> > - **Conntrack Ignore**: rules defined under `set system conntrack ignore [ipv4 | ipv6] ...`. Starting from vyos-1.5-rolling-202406120020, +> > configuration done in this section can be done in `firewall [ipv4 | ipv6] prerouting ...`. For compatibility reasons, this feature is +> > still present, but it will be removed in the future. +> > - **Policy Route**: rules defined under `set policy [route | route6] ...`. +> > - **Destination NAT**: rules defined under `set [nat | nat66] destination...`. +> +> - **Destination is the router?**: choose an appropriate path based on +> destination IP address. Transit forward continues to **forward**, +> while traffic where the destination IP address is configured on the router +> continues to **input**. +> +> - **Input**: stage where traffic destined for the router itself can be +> filtered and controlled. This is where all rules for securing the router +> should take place. This includes ipv4 and ipv6 filtering rules, defined +> in: +> +> - `set firewall ipv4 input filter ...`. +> - `set firewall ipv6 input filter ...`. +> +> - **Forward**: stage where transit traffic can be filtered and controlled. +> This includes ipv4 and ipv6 filtering rules, defined in: +> +> - `set firewall ipv4 forward filter ...`. +> - `set firewall ipv6 forward filter ...`. +> +> - **Output**: stage where traffic that originates from the router itself +> can be filtered and controlled. Bear in mind that this traffic can be a +> new connection originated by a internal process running on the VyOS router +> such as NTP, or a response to traffic received externally through +> **input** (for example response to an ssh login attempt to the router). +> This includes ipv4 and ipv6 rules, and two different sections are present: +> +> - **Output Prerouting**: `set firewall [ipv4 | ipv6] output filter ...`. +> As described in **Prerouting**, rules defined in this section are +> processed before connection tracking subsystem. +> - **Output Filter**: `set firewall [ipv4 | ipv6] output filter ...`. +> +> - **Postrouting**: as in **Prerouting**, several actions defined in +> different parts of VyOS configuration are performed in this +> stage. This includes: +> +> - **Source NAT**: rules defined under `set [nat | nat66] destination...`. + +If the interface where the packet was received is part of a bridge, then +the packet is processed at the **Bridge Layer**: + +> - **Prerouting (Bridge)**: all packets that are received by the bridge are +> processed in this stage, regardless of the destination of the packet. +> First filters can be applied here, and/or also configure rules for +> ignoring connection tracking system. The relevant configuration that +> acts in: +> - `set firewall bridge prerouting filter ...`. +> - **Forward (Bridge)**: stage where traffic that is trespassing through the +> bridge is filtered and controlled: +> - `set firewall bridge forward filter ...`. +> - **Input (Bridge)**: stage where traffic destined for the bridge itself can +> be filtered and controlled: +> - `set firewall bridge input filter ...`. +> - **Output (Bridge)**: stage where traffic that originates from the bridge +> itself can be filtered and controlled: +> - `set firewall bridge output filter ...`. + +The main structure of the VyOS firewall CLI is shown next: + +``` 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 + + ... +``` + +Please, refer to appropriate section for more information about firewall +configuration: + +
+ +global-options +groups +bridge +ipv4 +ipv6 +flowtables + +
+ +
+ +
+ +Note + +
+ +**For more information** +of Netfilter hooks and Linux networking packet flows can be +found in [Netfilter-Hooks](https://wiki.nftables.org/wiki-nftables/index.php/Netfilter_hooks) + +
+ +## Zone-based firewall + +
+ +zone + +
+ +With zone-based firewalls a new concept was implemented, in addition to the +standard in and out traffic flows, a local flow was added. This local flow was +for traffic originating and destined to the router itself. Which means that +additional rules were required to secure the firewall itself from the network, +in addition to the existing inbound and outbound rules from the traditional +concept above. + +To configure VyOS with the +`zone-based firewall configuration ` + +As the example image below shows, the device now needs rules to allow/block +traffic to or from the services running on the device that have open +connections on that interface. + +
+ +
diff --git a/docs/configuration/firewall/md-ipv4.md b/docs/configuration/firewall/md-ipv4.md new file mode 100644 index 00000000..1db832b9 --- /dev/null +++ b/docs/configuration/firewall/md-ipv4.md @@ -0,0 +1,2142 @@ +--- +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: + +```{eval-rst} +.. 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. + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> action + [accept | continue | drop | jump | queue | reject | return | synproxy] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> action + [accept | continue | drop | jump | queue | reject | return | synproxy] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> action + [accept | continue | drop | jump | queue | reject | return] +``` + +```{eval-rst} +.. 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. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + jump-target +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + jump-target +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + jump-target +``` + +```{eval-rst} +.. 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. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + queue <0-65535> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + queue <0-65535> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + queue <0-65535> +``` + +```{eval-rst} +.. 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. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + queue-options bypass +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + queue-options bypass +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + queue-options bypass +``` + +```{eval-rst} +.. 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. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + queue-options fanout +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + queue-options fanout +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + queue-options fanout +``` + +```{eval-rst} +.. 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**. + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter default-action + [accept | drop] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter default-action + [accept | drop] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter default-action + [accept | drop] +``` + +```{eval-rst} +.. 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. +``` + +```{eval-rst} +.. 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. + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> log +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> log +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> log +``` + +```{eval-rst} +.. 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. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter default-log +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter default-log +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter default-log +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name default-log + + Use this command to enable logging of the default action on the specified + chain. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + log-options level [emerg | alert | crit | err | warn | notice + | info | debug] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + log-options level [emerg | alert | crit | err | warn | notice + | info | debug] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + log-options level [emerg | alert | crit | err | warn | notice + | info | debug] +``` + +```{eval-rst} +.. 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. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + log-options group <0-65535> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + log-options group <0-65535> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + log-options group <0-65535> +``` + +```{eval-rst} +.. 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. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + log-options snapshot-length <0-9000> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + log-options snapshot-length <0-9000> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + log-options snapshot-length <0-9000> +``` + +```{eval-rst} +.. 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. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + log-options queue-threshold <0-65535> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + log-options queue-threshold <0-65535> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + log-options queue-threshold <0-65535> +``` + +```{eval-rst} +.. 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. + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name description + + Provide a rule-set description for a custom firewall chain. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + description +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + description +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + description +``` + +```{eval-rst} +.. 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. + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> disable +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> disable +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> disable +``` + +```{eval-rst} +.. 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. + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + connection-status nat [destination | source] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + connection-status nat [destination | source] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + connection-status nat [destination | source] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name rule <1-999999> + connection-status nat [destination | source] + + Match based on nat connection status. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + connection-mark <1-2147483647> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + connection-mark <1-2147483647> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + connection-mark <1-2147483647> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name rule <1-999999> + connection-mark <1-2147483647> + + Match based on connection mark. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + conntrack-helper +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + conntrack-helper +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + conntrack-helper +``` + +```{eval-rst} +.. 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 +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + source address [address | addressrange | CIDR] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + source address [address | addressrange | CIDR] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + source address [address | addressrange | CIDR] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name rule <1-999999> + source address [address | addressrange | CIDR] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + destination address [address | addressrange | CIDR] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + destination address [address | addressrange | CIDR] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + destination address [address | addressrange | CIDR] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name rule <1-999999> + destination address [address | addressrange | CIDR] + + Match criteria based on source and/or destination address. This is similar + to the network groups part, but here you are able to negate the matching + addresses. + + .. code-block:: none + + set firewall ipv4 name FOO rule 50 source address 192.0.2.10-192.0.2.11 + # with a '!' the rule match everything except the specified subnet + set firewall ipv4 input filter FOO rule 51 source address !203.0.113.0/24 +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + source address-mask [address] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + source address-mask [address] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + source address-mask [address] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name rule <1-999999> + source address-mask [address] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + destination address-mask [address] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + destination address-mask [address] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + destination address-mask [address] +``` + +```{eval-rst} +.. 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 +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + source fqdn +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + source fqdn +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + source fqdn +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name rule <1-999999> + source fqdn +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + destination fqdn +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + destination fqdn +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + destination fqdn +``` + +```{eval-rst} +.. 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. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + source geoip country-code +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + source geoip country-code +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + source geoip country-code +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name rule <1-999999> + source geoip country-code +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + destination geoip country-code +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + destination geoip country-code +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + destination geoip country-code +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name rule <1-999999> + destination geoip country-code +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + source geoip inverse-match +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + source geoip inverse-match +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + source geoip inverse-match +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name rule <1-999999> + source geoip inverse-match +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + destination geoip inverse-match +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + destination geoip inverse-match +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + destination geoip inverse-match +``` + +```{eval-rst} +.. 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. + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + source mac-address +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + source mac-address +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + source mac-address +``` + +```{eval-rst} +.. 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 +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + source port [1-65535 | portname | start-end] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + source port [1-65535 | portname | start-end] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + source port [1-65535 | portname | start-end] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name rule <1-999999> + source port [1-65535 | portname | start-end] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + destination port [1-65535 | portname | start-end] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + destination port [1-65535 | portname | start-end] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + destination port [1-65535 | portname | start-end] +``` + +```{eval-rst} +.. 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: +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + source group address-group +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + source group address-group +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + source group address-group +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name rule <1-999999> + source group address-group +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + destination group address-group +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + destination group address-group +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + destination group address-group +``` + +```{eval-rst} +.. 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. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + source group dynamic-address-group +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + source group dynamic-address-group +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + source group dynamic-address-group +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name rule <1-999999> + source group dynamic-address-group +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + destination group dynamic-address-group +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + destination group dynamic-address-group +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + destination group dynamic-address-group +``` + +```{eval-rst} +.. 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. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + source group network-group +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + source group network-group +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + source group network-group +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name rule <1-999999> + source group network-group +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + destination group network-group +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + destination group network-group +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + destination group network-group +``` + +```{eval-rst} +.. 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. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + source group port-group +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + source group port-group +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + source group port-group +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name rule <1-999999> + source group port-group +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + destination group port-group +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + destination group port-group +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + destination group port-group +``` + +```{eval-rst} +.. 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. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + source group domain-group +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + source group domain-group +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + source group domain-group +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name rule <1-999999> + source group domain-group +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + destination group domain-group +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + destination group domain-group +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + destination group domain-group +``` + +```{eval-rst} +.. 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. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + source group mac-group +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + source group mac-group +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + source group mac-group +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name rule <1-999999> + source group mac-group +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + destination group mac-group +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + destination group mac-group +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + destination group mac-group +``` + +```{eval-rst} +.. 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. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + dscp [0-63 | start-end] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + dscp [0-63 | start-end] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + dscp [0-63 | start-end] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name rule <1-999999> + dscp [0-63 | start-end] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + dscp-exclude [0-63 | start-end] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + dscp-exclude [0-63 | start-end] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + dscp-exclude [0-63 | start-end] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name rule <1-999999> + dscp-exclude [0-63 | start-end] + + Match based on dscp value. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + fragment [match-frag | match-non-frag] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + fragment [match-frag | match-non-frag] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + fragment [match-frag | match-non-frag] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name rule <1-999999> + fragment [match-frag | match-non-frag] + + Match based on fragmentation. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + icmp [code | type] <0-255> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + icmp [code | type] <0-255> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + icmp [code | type] <0-255> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name rule <1-999999> + icmp [code | type] <0-255> + + Match based on icmp code and type. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + icmp type-name +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + icmp type-name +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + icmp type-name +``` + +```{eval-rst} +.. 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. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + inbound-interface name +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + inbound-interface name +``` + +```{eval-rst} +.. 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` +::: + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + inbound-interface group +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + inbound-interface group +``` + +```{eval-rst} +.. 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`` +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + outbound-interface name +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + outbound-interface name +``` + +```{eval-rst} +.. 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` +::: + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + outbound-interface group +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + outbound-interface group +``` + +```{eval-rst} +.. 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`` +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + ipsec [match-ipsec-in | match-ipsec-out | match-none-in | match-none-out] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + ipsec [match-ipsec-in | match-none-in] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + ipsec [match-ipsec-out | match-none-out] +``` + +```{eval-rst} +.. 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. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + limit burst <0-4294967295> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + limit burst <0-4294967295> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + limit burst <0-4294967295> +``` + +```{eval-rst} +.. 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. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + limit rate +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + limit rate +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + limit rate +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name rule <1-999999> + limit rate + + Specify the maximum average rate as **integer/unit**. For example: + **5/minutes** +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + packet-length +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + packet-length +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + packet-length +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name rule <1-999999> + packet-length +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + packet-length-exclude +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + packet-length-exclude +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + packet-length-exclude +``` + +```{eval-rst} +.. 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. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + packet-type [broadcast | host | multicast | other] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + packet-type [broadcast | host | multicast | other] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + packet-type [broadcast | host | multicast | other] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name rule <1-999999> + packet-type [broadcast | host | multicast | other] + + Match based on the packet type. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + protocol [ | <0-255> | all | tcp_udp] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + protocol [ | <0-255> | all | tcp_udp] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + protocol [ | <0-255> | all | tcp_udp] +``` + +```{eval-rst} +.. 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 +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + recent count <1-255> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + recent count <1-255> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + recent count <1-255> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name rule <1-999999> + recent count <1-255> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + recent time [second | minute | hour] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + recent time [second | minute | hour] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + recent time [second | minute | hour] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name rule <1-999999> + recent time [second | minute | hour] + + Match based on recently seen sources. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + tcp flags [not] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + tcp flags [not] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + tcp flags [not] +``` + +```{eval-rst} +.. 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' +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + state [established | invalid | new | related] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + state [established | invalid | new | related] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + state [established | invalid | new | related] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name rule <1-999999> + state [established | invalid | new | related] + + Match against the state of a packet. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + time startdate +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + time startdate +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + time startdate +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name rule <1-999999> + time startdate +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + time starttime +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + time starttime +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + time starttime +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name rule <1-999999> + time starttime +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + time stopdate +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + time stopdate +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + time stopdate +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name rule <1-999999> + time stopdate +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + time stoptime +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + time stoptime +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + time stoptime +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name rule <1-999999> + time stoptime +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + time weekdays +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + time weekdays +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + time weekdays +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name rule <1-999999> + time weekdays + + Time to match the defined rule. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + ttl <0-255> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + ttl <0-255> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + ttl <0-255> +``` + +```{eval-rst} +.. 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'. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + recent count <1-255> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + recent count <1-255> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + recent count <1-255> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name rule <1-999999> + recent count <1-255> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + recent time +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + recent time +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + recent time +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 name rule <1-999999> + recent time + + Match when 'count' amount of connections appear within 'time'. Use these + matching criteria to block brute-force attempts. +``` + +### Packet Modifications + +Starting from **VyOS-1.5-rolling-202410060007**, the firewall can modify +packets before sending them out. This feature provides more flexibility in +packet handling. + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 prerouting raw rule <1-999999> + set dscp <0-63> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + set dscp <0-63> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output [filter | raw] rule <1-999999> + set dscp <0-63> + + Set a specific value of Differentiated Services Codepoint (DSCP). +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 prerouting raw rule <1-999999> + set mark <1-2147483647> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + set mark <1-2147483647> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output [filter | raw] rule <1-999999> + set mark <1-2147483647> + + Set a specific packet mark value. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 prerouting raw rule <1-999999> + set tcp-mss <500-1460> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + set tcp-mss <500-1460> +``` + +```{eval-rst} +.. 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. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 prerouting raw rule <1-999999> + set ttl <0-255> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + set ttl <0-255> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output [filter | raw] rule <1-999999> + set ttl <0-255> + + Set the TTL (Time to Live) value. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + set connection-mark <0-2147483647> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output [filter | raw] rule <1-999999> + set connection-mark <0-2147483647> + + Set connection mark value. +``` + +## Synproxy + +Synproxy connections + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 [input | forward] filter rule <1-999999> + action synproxy +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 [input | forward] filter rule <1-999999> + protocol tcp +``` + +```{eval-rst} +.. 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 +``` + +```{eval-rst} +.. 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 + +```{eval-rst} +.. 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:~$ +``` + +```{eval-rst} +.. opcmd:: show firewall summary + + This shows you a summary of rule-sets and groups. + + .. code-block:: none + + vyos@vyos:~$ show firewall summary + Ruleset Summary + + IPv6 Ruleset: + + Ruleset Hook Ruleset Priority Description + -------------- -------------------- ------------------------- + forward filter + input filter + ipv6_name IPV6-VyOS_MANAGEMENT + ipv6_name IPV6-WAN_IN PUBLIC_INTERNET + + IPv4 Ruleset: + + Ruleset Hook Ruleset Priority Description + -------------- ------------------ ------------------------- + forward filter + input filter + name VyOS_MANAGEMENT + name WAN_IN PUBLIC_INTERNET + + Firewall Groups + + Name Type References Members + ----------------------- ------------------ ----------------------- ---------------- + PBX address_group WAN_IN-100 198.51.100.77 + SERVERS address_group WAN_IN-110 192.0.2.10 + WAN_IN-111 192.0.2.11 + WAN_IN-112 192.0.2.12 + WAN_IN-120 + WAN_IN-121 + WAN_IN-122 + SUPPORT address_group VyOS_MANAGEMENT-20 192.168.1.2 + WAN_IN-20 + PHONE_VPN_SERVERS address_group WAN_IN-160 10.6.32.2 + PINGABLE_ADRESSES address_group WAN_IN-170 192.168.5.2 + WAN_IN-171 + PBX ipv6_address_group IPV6-WAN_IN-100 2001:db8::1 + SERVERS ipv6_address_group IPV6-WAN_IN-110 2001:db8::2 + IPV6-WAN_IN-111 2001:db8::3 + IPV6-WAN_IN-112 2001:db8::4 + IPV6-WAN_IN-120 + IPV6-WAN_IN-121 + IPV6-WAN_IN-122 + SUPPORT ipv6_address_group IPV6-VyOS_MANAGEMENT-20 2001:db8::5 + IPV6-WAN_IN-20 + +``` + +```{eval-rst} +.. opcmd:: show firewall ipv4 [forward | input | output] filter +``` + +```{eval-rst} +.. 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 +``` + +```{eval-rst} +.. opcmd:: show firewall ipv4 [forward | input | output] + filter rule <1-999999> +``` + +```{eval-rst} +.. 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:~$ +``` + +```{eval-rst} +.. opcmd:: show firewall statistics + + This will show you statistics of all rule-sets since the last boot. +``` + +### Show Firewall log + +```{eval-rst} +.. opcmd:: show log firewall +``` + +```{eval-rst} +.. opcmd:: show log firewall ipv4 +``` + +```{eval-rst} +.. opcmd:: show log firewall ipv4 [forward | input | output | name] +``` + +```{eval-rst} +.. opcmd:: show log firewall ipv4 [forward | input | output] filter +``` + +```{eval-rst} +.. opcmd:: show log firewall ipv4 name +``` + +```{eval-rst} +.. opcmd:: show log firewall ipv4 [forward | input | output] filter rule +``` + +```{eval-rst} +.. 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 + +```{eval-rst} +.. opcmd:: update geoip + + Command to update GeoIP database and firewall sets. +``` diff --git a/docs/configuration/firewall/md-ipv6.md b/docs/configuration/firewall/md-ipv6.md new file mode 100644 index 00000000..969279dd --- /dev/null +++ b/docs/configuration/firewall/md-ipv6.md @@ -0,0 +1,2131 @@ +--- +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: + +```{eval-rst} +.. 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. + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> action + [accept | continue | drop | jump | queue | reject | return | synproxy] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> action + [accept | continue | drop | jump | queue | reject | return | synproxy] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> action + [accept | continue | drop | jump | queue | reject | return] +``` + +```{eval-rst} +.. 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. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + jump-target +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + jump-target +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + jump-target +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name rule <1-999999> + jump-target + + Use this command only when action is set to ``jump``. Specify the jump + target. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + queue <0-65535> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + queue <0-65535> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + queue <0-65535> +``` + +```{eval-rst} +.. 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. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + queue-options bypass +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + queue-options bypass +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + queue-options bypass +``` + +```{eval-rst} +.. 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. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + queue-options fanout +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + queue-options fanout +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + queue-options fanout +``` + +```{eval-rst} +.. 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**. + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter default-action + [accept | drop] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter default-action + [accept | drop] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter default-action + [accept | drop] +``` + +```{eval-rst} +.. 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. +``` + +```{eval-rst} +.. 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. + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> log +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> log +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> log +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name rule <1-999999> log + + Enable logging for matched packets. If this configuration command is not + present, logging is disabled. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter default-log +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter default-log +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter default-log +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name default-log + + Use this command to enable the logging of the default action on + the specified chain. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + log-options level [emerg | alert | crit | err | warn | notice + | info | debug] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + log-options level [emerg | alert | crit | err | warn | notice + | info | debug] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + log-options level [emerg | alert | crit | err | warn | notice + | info | debug] +``` + +```{eval-rst} +.. 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. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + log-options group <0-65535> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + log-options group <0-65535> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + log-options group <0-65535> +``` + +```{eval-rst} +.. 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. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + log-options snapshot-length <0-9000> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + log-options snapshot-length <0-9000> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + log-options snapshot-length <0-9000> +``` + +```{eval-rst} +.. 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. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + log-options queue-threshold <0-65535> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + log-options queue-threshold <0-65535> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + log-options queue-threshold <0-65535> +``` + +```{eval-rst} +.. 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. + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name description + + Provide a rule-set description to a custom firewall chain. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + description +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + description +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + description +``` + +```{eval-rst} +.. 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. + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> disable +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> disable +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> disable +``` + +```{eval-rst} +.. 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. + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + connection-status nat [destination | source] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + connection-status nat [destination | source] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + connection-status nat [destination | source] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name rule <1-999999> + connection-status nat [destination | source] + + Match packets based on NAT connection status. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + connection-mark <1-2147483647> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + connection-mark <1-2147483647> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + connection-mark <1-2147483647> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name rule <1-999999> + connection-mark <1-2147483647> + + Match packets based on connection mark. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + source address [address | addressrange | CIDR] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + source address [address | addressrange | CIDR] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + source address [address | addressrange | CIDR] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name rule <1-999999> + source address [address | addressrange | CIDR] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + destination address [address | addressrange | CIDR] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + destination address [address | addressrange | CIDR] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + destination address [address | addressrange | CIDR] +``` + +```{eval-rst} +.. 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 +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + source address-mask [address] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + source address-mask [address] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + source address-mask [address] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name rule <1-999999> + source address-mask [address] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + destination address-mask [address] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + destination address-mask [address] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + destination address-mask [address] +``` + +```{eval-rst} +.. 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. + + .. stop_vyoslinter + .. 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 + + .. start_vyoslinter +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + source fqdn +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + source fqdn +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + source fqdn +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name rule <1-999999> + source fqdn +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + destination fqdn +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + destination fqdn +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + destination fqdn +``` + +```{eval-rst} +.. 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. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + source geoip country-code +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + source geoip country-code +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + source geoip country-code +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name rule <1-999999> + source geoip country-code +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + destination geoip country-code +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + destination geoip country-code +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + destination geoip country-code +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name rule <1-999999> + destination geoip country-code +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + source geoip inverse-match +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + source geoip inverse-match +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + source geoip inverse-match +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name rule <1-999999> + source geoip inverse-match +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + destination geoip inverse-match +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + destination geoip inverse-match +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + destination geoip inverse-match +``` + +```{eval-rst} +.. 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. + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + source mac-address +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + source mac-address +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + source mac-address +``` + +```{eval-rst} +.. 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 +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + source port [1-65535 | portname | start-end] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + source port [1-65535 | portname | start-end] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + source port [1-65535 | portname | start-end] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name rule <1-999999> + source port [1-65535 | portname | start-end] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + destination port [1-65535 | portname | start-end] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + destination port [1-65535 | portname | start-end] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + destination port [1-65535 | portname | start-end] +``` + +```{eval-rst} +.. 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' +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + source group address-group +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + source group address-group +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + source group address-group +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name rule <1-999999> + source group address-group +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + destination group address-group +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + destination group address-group +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + destination group address-group +``` + +```{eval-rst} +.. 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. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + source group dynamic-address-group +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + source group dynamic-address-group +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + source group dynamic-address-group +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name rule <1-999999> + source group dynamic-address-group +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + destination group dynamic-address-group +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + destination group dynamic-address-group +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + destination group dynamic-address-group +``` + +```{eval-rst} +.. 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. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + source group network-group +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + source group network-group +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + source group network-group +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name rule <1-999999> + source group network-group +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + destination group network-group +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + destination group network-group +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + destination group network-group +``` + +```{eval-rst} +.. 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. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + source group port-group +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + source group port-group +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + source group port-group +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name rule <1-999999> + source group port-group +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + destination group port-group +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + destination group port-group +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + destination group port-group +``` + +```{eval-rst} +.. 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. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + source group domain-group +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + source group domain-group +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + source group domain-group +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name rule <1-999999> + source group domain-group +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + destination group domain-group +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + destination group domain-group +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + destination group domain-group +``` + +```{eval-rst} +.. 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. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + source group mac-group +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + source group mac-group +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + source group mac-group +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name rule <1-999999> + source group mac-group +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + destination group mac-group +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + destination group mac-group +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + destination group mac-group +``` + +```{eval-rst} +.. 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. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + dscp [0-63 | start-end] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + dscp [0-63 | start-end] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + dscp [0-63 | start-end] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name rule <1-999999> + dscp [0-63 | start-end] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + dscp-exclude [0-63 | start-end] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + dscp-exclude [0-63 | start-end] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + dscp-exclude [0-63 | start-end] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name rule <1-999999> + dscp-exclude [0-63 | start-end] + + Match based on dscp value. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + fragment [match-frag | match-non-frag] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + fragment [match-frag | match-non-frag] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + fragment [match-frag | match-non-frag] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name rule <1-999999> + fragment [match-frag | match-non-frag] + + Match packets based on fragmentation. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + icmpv6 [code | type] <0-255> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + icmpv6 [code | type] <0-255> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + icmpv6 [code | type] <0-255> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name rule <1-999999> + icmpv6 [code | type] <0-255> + + Match packets based on ICMP or ICMPv6 code and type. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + icmpv6 type-name +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + icmpv6 type-name +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + icmpv6 type-name +``` + +```{eval-rst} +.. 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. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + inbound-interface name +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + inbound-interface name +``` + +```{eval-rst} +.. 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` +::: + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + inbound-interface group +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + inbound-interface group +``` + +```{eval-rst} +.. 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`` +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + outbound-interface name +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + outbound-interface name +``` + +```{eval-rst} +.. 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` +::: + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + outbound-interface group +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + outbound-interface group +``` + +```{eval-rst} +.. 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`` +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + ipsec [match-ipsec-in | match-ipsec-out | match-none-in | match-none-out] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + ipsec [match-ipsec-in | match-none-in] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + ipsec [match-ipsec-out | match-none-out] +``` + +```{eval-rst} +.. 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. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + limit burst <0-4294967295> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + limit burst <0-4294967295> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + limit burst <0-4294967295> +``` + +```{eval-rst} +.. 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. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + limit rate +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + limit rate +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + limit rate +``` + +```{eval-rst} +.. 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``. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + packet-length +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + packet-length +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + packet-length +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name rule <1-999999> + packet-length +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + packet-length-exclude +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + packet-length-exclude +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + packet-length-exclude +``` + +```{eval-rst} +.. 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. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + packet-type [broadcast | host | multicast | other] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + packet-type [broadcast | host | multicast | other] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + packet-type [broadcast | host | multicast | other] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name rule <1-999999> + packet-type [broadcast | host | multicast | other] + + Match based on packet type. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + protocol [ | <0-255> | all | tcp_udp] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + protocol [ | <0-255> | all | tcp_udp] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + protocol [ | <0-255> | all | tcp_udp] +``` + +```{eval-rst} +.. 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 +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + recent count <1-255> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + recent count <1-255> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + recent count <1-255> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name rule <1-999999> + recent count <1-255> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + recent time [second | minute | hour] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + recent time [second | minute | hour] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + recent time [second | minute | hour] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name rule <1-999999> + recent time [second | minute | hour] + + Match packets based on recently seen sources. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + tcp flags [not] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + tcp flags [not] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + tcp flags [not] +``` + +```{eval-rst} +.. 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' +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + state [established | invalid | new | related] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + state [established | invalid | new | related] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + state [established | invalid | new | related] +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name rule <1-999999> + state [established | invalid | new | related] + + Match based on packet state. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + time startdate +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + time startdate +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + time startdate +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name rule <1-999999> + time startdate +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + time starttime +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + time starttime +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + time starttime +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name rule <1-999999> + time starttime +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + time stopdate +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + time stopdate +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + time stopdate +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name rule <1-999999> + time stopdate +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + time stoptime +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + time stoptime +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + time stoptime +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name rule <1-999999> + time stoptime +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + time weekdays +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + time weekdays +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + time weekdays +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name rule <1-999999> + time weekdays + + Match packets based on time criteria. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + hop-limit <0-255> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + hop-limit <0-255> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + hop-limit <0-255> +``` + +```{eval-rst} +.. 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. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + recent count <1-255> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + recent count <1-255> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + recent count <1-255> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 name rule <1-999999> + recent count <1-255> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + recent time +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + recent time +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + recent time +``` + +```{eval-rst} +.. 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. + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 prerouting raw rule <1-999999> + set dscp <0-63> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + set dscp <0-63> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output [filter | raw] rule <1-999999> + set dscp <0-63> + + Set a specific value of Differentiated Services Codepoint (DSCP). +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 prerouting raw rule <1-999999> + set mark <1-2147483647> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + set mark <1-2147483647> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output [filter | raw] rule <1-999999> + set mark <1-2147483647> + + Set a specific packet mark value. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 prerouting raw rule <1-999999> + set tcp-mss <500-1460> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + set tcp-mss <500-1460> +``` + +```{eval-rst} +.. 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. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 prerouting raw rule <1-999999> + set hop-limit <0-255> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + set hop-limit <0-255> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 output [filter | raw] rule <1-999999> + set hop-limit <0-255> + + Set hop limit value. +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + set connection-mark <0-2147483647> +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv4 output [filter | raw] rule <1-999999> + set connection-mark <0-2147483647> + + Set connection mark value. +``` + +## Synproxy + +Synproxy connections + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 [input | forward] filter rule <1-999999> + action synproxy +``` + +```{eval-rst} +.. cfgcmd:: set firewall ipv6 [input | forward] filter rule <1-999999> + protocol tcp +``` + +```{eval-rst} +.. 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. +``` + +```{eval-rst} +.. 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 + +```{eval-rst} +.. 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 +``` + +```{eval-rst} +.. opcmd:: show firewall summary + + This will show you a summary of rule-sets and groups + + .. code-block:: none + + vyos@vyos:~$ show firewall summary + Ruleset Summary + + IPv6 Ruleset: + + Ruleset Hook Ruleset Priority Description + -------------- -------------------- ------------------------- + forward filter + input filter + ipv6_name IPV6-VyOS_MANAGEMENT + ipv6_name IPV6-WAN_IN PUBLIC_INTERNET + + IPv4 Ruleset: + + Ruleset Hook Ruleset Priority Description + -------------- ------------------ ------------------------- + forward filter + input filter + name VyOS_MANAGEMENT + name WAN_IN PUBLIC_INTERNET + + Firewall Groups + + Name Type References Members + ----------------------- ------------------ ----------------------- ---------------- + PBX address_group WAN_IN-100 198.51.100.77 + SERVERS address_group WAN_IN-110 192.0.2.10 + WAN_IN-111 192.0.2.11 + WAN_IN-112 192.0.2.12 + WAN_IN-120 + WAN_IN-121 + WAN_IN-122 + SUPPORT address_group VyOS_MANAGEMENT-20 192.168.1.2 + WAN_IN-20 + PHONE_VPN_SERVERS address_group WAN_IN-160 10.6.32.2 + PINGABLE_ADRESSES address_group WAN_IN-170 192.168.5.2 + WAN_IN-171 + PBX ipv6_address_group IPV6-WAN_IN-100 2001:db8::1 + SERVERS ipv6_address_group IPV6-WAN_IN-110 2001:db8::2 + IPV6-WAN_IN-111 2001:db8::3 + IPV6-WAN_IN-112 2001:db8::4 + IPV6-WAN_IN-120 + IPV6-WAN_IN-121 + IPV6-WAN_IN-122 + SUPPORT ipv6_address_group IPV6-VyOS_MANAGEMENT-20 2001:db8::5 + IPV6-WAN_IN-20 + +``` + +```{eval-rst} +.. opcmd:: show firewall ipv6 [forward | input | output] filter +``` + +```{eval-rst} +.. 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:~$ +``` + +```{eval-rst} +.. opcmd:: show firewall ipv6 [forward | input | output] + filter rule <1-999999> +``` + +```{eval-rst} +.. opcmd:: show firewall ipv6 name rule <1-999999> +``` + +```{eval-rst} +.. opcmd:: show firewall ipv6 ipv6-name rule <1-999999> + + This command will give an overview of a rule in a single rule-set +``` + +```{eval-rst} +.. 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 + +``` + +```{eval-rst} +.. opcmd:: show firewall statistics + + Show statistics of all rule-sets since the last boot. +``` + +### Show Firewall log + +```{eval-rst} +.. opcmd:: show log firewall +``` + +```{eval-rst} +.. opcmd:: show log firewall ipv6 +``` + +```{eval-rst} +.. opcmd:: show log firewall ipv6 [forward | input | output | name] +``` + +```{eval-rst} +.. opcmd:: show log firewall ipv6 [forward | input | output] filter +``` + +```{eval-rst} +.. opcmd:: show log firewall ipv6 name +``` + +```{eval-rst} +.. opcmd:: show log firewall ipv6 [forward | input | output] filter rule +``` + +```{eval-rst} +.. 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 + +```{eval-rst} +.. opcmd:: update geoip + + Command used to update GeoIP database and firewall sets. +``` diff --git a/docs/configuration/firewall/md-zone.md b/docs/configuration/firewall/md-zone.md new file mode 100644 index 00000000..948c5b43 --- /dev/null +++ b/docs/configuration/firewall/md-zone.md @@ -0,0 +1,221 @@ +--- +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: + +```{eval-rst} +.. 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. + +```{eval-rst} +.. 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). +``` + +```{eval-rst} +.. 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 +``` + +```{eval-rst} +.. 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. +``` + +```{eval-rst} +.. cfgcmd:: set firewall zone default-log + + Enable logging of packets that match this zone's default-action (disabled + by default). +``` + +```{eval-rst} +.. 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. + +```{eval-rst} +.. cfgcmd:: set firewall zone from + firewall name +``` + +```{eval-rst} +.. 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` + +```{eval-rst} +.. cfgcmd:: set firewall zone default-firewall name + +``` + +```{eval-rst} +.. cfgcmd:: set firewall zone default-firewall ipv6-name + +``` + +## Operation-mode + +```{eval-rst} +.. 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 +``` + +```{eval-rst} +.. 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 +``` diff --git a/docs/configuration/highavailability/md-index.md b/docs/configuration/highavailability/md-index.md new file mode 100644 index 00000000..d5d8f390 --- /dev/null +++ b/docs/configuration/highavailability/md-index.md @@ -0,0 +1,527 @@ +--- +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. +``` + + +```{eval-rst} +.. cfgcmd:: set high-availability vrrp global-parameters garp master-delay <1-255> +``` + + +```{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: + + +```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 +``` + + +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: + + +```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 +``` + + +### 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: + + +```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" +``` + + +To know more about scripting, check the {ref}`command-scripting` section. + +## Virtual-server + +```{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 + + +```none +set high-availability virtual-server 203.0.113.1 real-server 192.0.2.11 health-check script +``` + + +### 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 + + +```none +set high-availability virtual-server 203.0.113.1 real-server 192.0.2.11 port '80' +``` + + +### 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. + + +```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' +``` + + +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. + + +```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' +``` + + +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..4538b145 --- /dev/null +++ b/docs/configuration/interfaces/md-bonding.md @@ -0,0 +1,753 @@ +--- +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 + +```{eval-rst} +.. cmdincludemd:: /_include/interface-common-with-dhcp.txt + :var0: bonding + :var1: bond0 +``` + +### Member interfaces + +```{eval-rst} +.. 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 + +```{eval-rst} +.. cfgcmd:: set interfaces bonding mode <802.3ad | active-backup | + broadcast | round-robin | transmit-load-balance | adaptive-load-balance | + xor-hash> + + **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)`. +``` + +```{eval-rst} +.. 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). +``` + +```{eval-rst} +.. 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. + +``` + +```{eval-rst} +.. 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. + +``` + +```{eval-rst} +.. 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`` + + .. list-table:: + :widths: 20 80 + + * - **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`` + + .. list-table:: + :widths: 20 80 + + * - **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`` + + .. list-table:: + :widths: 20 80 + + * - **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``. +``` + +```{eval-rst} +.. 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. +``` + +```{eval-rst} +.. cfgcmd:: set interfaces bonding arp-monitor interval