From 4b36114e053ee11d0cb264a1e4cfe4692d78f194 Mon Sep 17 00:00:00 2001 From: Yuriy Andamasov Date: Wed, 6 May 2026 14:40:28 +0300 Subject: Add incremental RST-to-MyST swap mechanism (#1857) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * feat: add swap_sources.py for incremental RST-to-MyST migration Pre-build swap/restore script that renames md-{name}.md → {name}.md before Sphinx builds and restores after. Includes state tracking, exclude file generation, collision detection, and partial-failure rollback. 10 tests cover all specified behaviors plus rollback path. Co-Authored-By: Claude Sonnet 4.6 * feat: add import_myst.py for importing MyST files from myst/* branches Adds scripts/import_myst.py with import_page, git_show, list_myst_files, list_rst_files, and do_import. Imported files are written as md-{name}.md alongside existing RST files; importing is decoupled from swap activation. Adds tests/test_import_myst.py covering single-page write, identical-skip, warn-on-different-without-force, force-overwrite, and nested-path creation. All 5 tests pass on Python 3.9. Co-Authored-By: Claude Sonnet 4.6 * feat: add MyST swap exclude patterns and directive config to conf.py 🤖 Generated by [robots](https://vyos.io) * feat: add swap-wrapped rendering targets to Makefile 🤖 Generated by [robots](https://vyos.io) * feat: add swap pre/post build hooks for ReadTheDocs 🤖 Generated by [robots](https://vyos.io) * feat: add empty _swap.txt, remove atexit from swap script The atexit handler in --swap mode caused immediate restore on process exit, breaking standalone usage. Makefile trap and RTD post_build handle restore reliably. 🤖 Generated by [robots](https://vyos.io) * feat: activate quick-start as MyST canary via swap mechanism Imports docs/md-quick-start.md from origin/myst/current and adds quick-start to docs/_swap.txt. Validates the swap pipeline end-to-end on one page: import_myst pulls the MD via git show, swap_sources renames md-quick-start.md to quick-start.md, sphinx-build renders quick-start.html with zero MD-specific warnings, and restore reverses the rename cleanly. 🤖 Generated by [robots](https://vyos.io) * feat: activate 106 visual-validated canaries via swap Imports 105 MD files (plus quick-start already present) from origin/myst/current and adds them to docs/_swap.txt. The selection is the BackstopJS visual-passers cohort: pages with <5% rendered diff vs the live RST docs at docs.vyos.io/en/latest/, filtered to those with an RST counterpart on current and no cmdincludemd usage (template-format reconciliation pending). Local sphinx-build with all 106 swapped: succeeded with 100 warnings (vs 95 baseline). The 5 new warnings are all undefined cross-reference labels, not build failures: - contributing/development.md (missing 'coding-guidelines') - operation/upgrade-recovery.md (3 missing 'how_it_works' / 'cancelling_recovery') - vpp/configuration/dataplane/{buffers,memory,unix}.md (missing 'vpp_config_dataplane_*' labels) Source list: ~/.claude/projects/-Users-vybot-GitHub-vyos-documentation/docs/2026-04-29-myst-conversion-audit/visual-passers-under-5pct.txt BackstopJS report: claude/gifted-hertz-74b9f9 worktree (visual-compare/), 2026-04-23 vs vyos--1838.org.readthedocs.build. 🤖 Generated by [robots](https://vyos.io) * fix: re-import 4 canary md-*.md files with xref label fixes Re-imports the dash-form-corrected versions of: - contributing/md-development.md (added (coding-guidelines)= anchor) - operation/md-upgrade-recovery.md (3 ref renames: how_it_works / cancelling_recovery -> dash form) - vpp/configuration/dataplane/md-buffers.md (vpp_config_dataplane_physmem -> vpp-config-dataplane-physmem) - vpp/configuration/dataplane/md-unix.md (vpp_config_dataplane_interface_rx_mode -> vpp-config-dataplane-interface-rx-mode) Source: origin/myst/current commit 59fbe3ea. Verified locally: clean swap-build no longer reports any of the 5 target labels (1 of 6 — vpp-config-hugepages — remains because system.md isn't in the canary swap list; that anchor lives there). 🤖 Generated by [robots](https://vyos.io) * fix: re-add 4 canary md-*.md files deleted by 242b334a Commit 242b334a accidentally staged deletions instead of modifications because the working tree had unprefixed *.md files left over from an incomplete swap-restore cycle. Re-imports the same 4 files from origin/myst/current with the xref label fixes applied: - contributing/md-development.md — (coding-guidelines)= anchor - operation/md-upgrade-recovery.md — how_it_works → how-it-works, cancelling_recovery → cancelling-recovery - vpp/configuration/dataplane/md-buffers.md — vpp_config_dataplane_physmem → vpp-config-dataplane-physmem - vpp/configuration/dataplane/md-unix.md — vpp_config_dataplane_interface_rx_mode → vpp-config-dataplane-interface-rx-mode Source: origin/myst/current commit 59fbe3ea. 🤖 Generated by [robots](https://vyos.io) * fix: resolve remaining xref label gaps in swap-active build Three small additions clear the cross-reference warnings tied to underscore-vs-dash label form mismatches and the vpp-config-hugepages reference that previously needed system.md in the canary set. - system.rst: add .. _vpp-config-hugepages: alongside the existing underscore label so memory.md references resolve regardless of whether system.md is swap-active. - md-lcp.md: add (vpp_config_dataplane_lcp_ignore-kernel-routes)= alongside dash form (carries upstream from myst/current 079fa786). - md-memory.md: add (vpp_config_dataplane_memory)= alongside dash form (also from myst/current 079fa786). Local clean swap-build with 106 canaries: before: 305 warnings, 8 undefined-label entries in our scope after: 300 warnings, 0 undefined-label entries in our scope Remaining undefined-label warnings (release-notes, prepare_commit) are in documentation.rst and unrelated to the canary swap mechanism. 🤖 Generated by [robots](https://vyos.io) * fix: re-add md-lcp.md and md-memory.md (deleted by 870c9e7e) Same disaster pattern as 242b334a: a swap-restore cycle left unprefixed *.md files in the working tree, and the subsequent git add staged deletions instead of modifications. Restoring the two affected md-*.md files from origin/myst/current 079fa786 (which has the dual underscore+dash anchors needed for the swap-active build). 🤖 Generated by [robots](https://vyos.io) * feat: expand canaries to 114; refresh 3 with cfgcmd body fix Adds 8 new visual-validated canaries from the post-cfgcmd-fix BackstopJS run (2026-04-29): - configuration/policy/as-path-list - configuration/policy/community-list - configuration/policy/extcommunity-list - configuration/policy/large-community-list - configuration/policy/local-route - configuration/policy/prefix-list - configuration/service/salt-minion - configuration/system/updates Refreshes 3 existing canaries whose MD content changed via the cfgcmd/opcmd single-line body fix on myst/current fc19ab5c: - configuration/firewall/global-options - configuration/firewall/groups - configuration/policy/route All 11 sourced from origin/myst/current. Net: 106 -> 114 canaries. 🤖 Generated by [robots](https://vyos.io) * fix: re-import md-cloud-init.md (block 3 fix from myst/current) 🤖 Generated by [robots](https://vyos.io) * feat(swap): import .md files and webp transition from myst/current Selective import from origin/myst/current (cf9c9b34): - Add/update 255 .md files (full MyST conversion plus webp ref updates) - Delete 175 PNG/JPG from docs/_static/images (webp twins already present) - Delete 5 autotest topology.png (webp twins already present) Preserved on swap (untouched): - All .rst files (incremental swap pattern) - conf.py, _ext/, _include/*.txt, .gitignore - 115 canary md-*.md files - 7 superpowers/specs/*.md design docs - Logos vyos-logo.png / vyos-logo-icon.png (referenced by conf.py) 🤖 Generated by [robots](https://vyos.io) * chore(swap): remove canary md-*.md files and docs/superpowers - Remove 115 canary md-*.md files (incremental swap helpers no longer needed) - Remove 8 files under docs/superpowers (project planning/design docs that shouldn't ship in the documentation tree) 🤖 Generated by [robots](https://vyos.io) * docs: address Copilot review feedback on imported MyST pages Fix issues flagged by Copilot review on PR #1857 (the same content lives in myst/current as the canonical source): Real bugs: - site-2-site-cisco.md: replace curly quote (U+2019) with ASCII apostrophe - rsa-keys.md: fix typo "key-pair nam>>" → "key-pair name>" - vmware.md: lowercase admonition directive (:::{NOTE} → :::{note}) - vpp/configuration/nat/index.md: remove blank line inside {include} fence Grammar: - vpp/configuration/interfaces/loopback.md: "bounded" → "bound" - vpp/configuration/sflow.md: "VyOS support" → "VyOS supports" - vpp/requirements.md: "bypass" → "bypasses" - vpp/configuration/dataplane/interface.md: "configures" → "configure" CI linter (IP addresses): - nmp.md: wrap 8.8.8.8 example with stop/start_vyoslinter - lac-lns.md: wrap LNS config block (contains 8.8.8.8) - wan-load-balancing.md: wrap whole file (illustrative non-RFC IPs) - policy/examples.md: replace 192.0.1.1 with RFC 5737 192.0.2.1 🤖 Generated by [robots](https://vyos.io) * fix(swap): address Copilot review feedback on swap infrastructure Category D — drop obsolete canary mechanism settings: - conf.py: remove '**/md-*.md' from exclude_patterns (no canaries left) - Makefile: replace malformed '*/_build/*' with '$(BUILDDIR)/**' and drop the '*/md-*' ignore (canary files no longer exist) Category C — script robustness: - import_myst.py: * list_myst_files() now raises SystemExit on git ls-tree failure instead of silently returning [] (would have masked typo'd --source refs) * list_rst_files() skips _build/ when scanning for .rst stems * import_page() rejects stems containing '..' or absolute paths and re-checks that the resolved destination stays under docs_dir * --dry-run uses a separate "would_import" counter; summary line now distinguishes dry-run from actual imports - swap_sources.py: * parse_swap_list() reads with explicit encoding='utf-8' * do_restore() validates state file version + entry shape before renaming files; raises with actionable message on corruption * State file reads/writes use explicit encoding='utf-8' throughout _swap.txt: - Wrap long comment line to satisfy 80-character doc-linter limit 🤖 Generated by [robots](https://vyos.io) * refactor(swap): rename imported .md files to md- prefix for swap mechanism Restore the canary file naming convention that swap_sources.py expects: the imported MyST pages now live as docs//md-.md alongside the existing docs//.rst, so swap_sources.py --swap can rename them into place at build time. - 254 .md files renamed (every page with a matching .rst counterpart) - 2 MyST-only pages left at their final names (no .rst exists, no swap needed): docs/copyright.md, docs/automation/terraform/terraformvyos.md All 114 stems listed in docs/_swap.txt now have a corresponding md-.md source file ready to swap in. 🤖 Generated by [robots](https://vyos.io) * docs: address CodeRabbit review feedback on imported MyST pages Fix issues flagged by CodeRabbit on PR #1857. All issues are pre-existing in the upstream RST docs and inherited by the MyST conversion. Real bugs: - inter-vrf-routing-vrf-lite.md: invalid IPv6 next-hop "2001:db8::*" → "2001:db8::1" - ipsec-pa-route-based.md: vendor mislabel "Cisco" → "Palo Alto" (header on line 39 and "Monitoring on Cisco side" section heading) - bgp-ipv6-unnumbered.md: AS number mismatch between configuration and verification output for both routers (Router A: 65020 → 64496; Router B: 65021 → 64499) - qos.md: class 30 used "match ADDRESS20" instead of ADDRESS30 — broke the documented pattern (classes 10/20/30 → ADDRESS10/20/30) Security: - OpenVPN_with_LDAP.md: redact full PEM private key material from the three "set pki ... private key '...'" lines and from the embedded OpenVPN client block; replace with / ...REDACTED... placeholders. Public certificates retained. 🤖 Generated by [robots](https://vyos.io) * feat(swap): default to serving MyST for all swapped pages Replace the previously-curated 114-stem _swap.txt with the full set of 254 imported md-prefixed pages, so MD is served by default at build time. To revert any specific page back to RST, remove its stem from _swap.txt (or comment it out). 🤖 Generated by [robots](https://vyos.io) * fix(ext): handle RST fallback in CmdInclude when _renderer absent `cmdincludemd` is in `myst_fence_as_directive`, so MyST routes fence blocks through `render_fence → render_restructuredtext → MockRSTParser`. In that path `self.state` is a plain docutils Body with no `_renderer`, crashing the build. Fall back to `nested_parse` when `_renderer` is unavailable so the directive works in both MyST and RST/MockRSTParser contexts. 🤖 Generated by [robots](https://vyos.io) * feat(conf): copy .md sources into HTML output for plain-text serving Adds a build-finished hook that mirrors every .md file from the Sphinx source tree into the HTML output directory verbatim, making unrendered MyST sources accessible alongside HTML renders at the same URL path. 🤖 Generated by [robots](https://vyos.io) * docs: address review feedback from PR #1857 Fix conversion artifacts, typos, grammar errors, and technical inaccuracies flagged by automated code review (Copilot + CodeRabbit). Infrastructure: add root-level md-*.md exclusion to conf.py, fix sphinx-autobuild ignore globs in Makefile. Content: fix curly quotes, invalid Go panic() calls, shell quoting in cURL examples, incorrect firewall command paths, typos across 22 documentation files, remove duplicate sections. 🤖 Generated by [robots](https://vyos.io) --------- Co-authored-by: Claude Sonnet 4.6 --- docs/_static/images/1u_vyos_back.jpg | Bin 586620 -> 0 bytes docs/_static/images/1u_vyos_front.jpg | Bin 363840 -> 0 bytes docs/_static/images/1u_vyos_front_10ge_open_1.jpg | Bin 1853769 -> 0 bytes docs/_static/images/1u_vyos_front_10ge_open_2.jpg | Bin 2294504 -> 0 bytes docs/_static/images/1u_vyos_front_10ge_open_3.jpg | Bin 2067314 -> 0 bytes docs/_static/images/1u_vyos_front_10ge_open_4.jpg | Bin 2447196 -> 0 bytes docs/_static/images/1u_vyos_front_open_1.jpg | Bin 956435 -> 0 bytes docs/_static/images/1u_vyos_front_open_2.jpg | Bin 1225208 -> 0 bytes docs/_static/images/1u_vyos_front_open_3.jpg | Bin 1337822 -> 0 bytes docs/_static/images/480px-Acrosser_ANDJ190N1_Back.jpg | Bin 11340 -> 0 bytes .../_static/images/480px-Acrosser_ANDJ190N1_Front.jpg | Bin 11138 -> 0 bytes docs/_static/images/600px-Partaker-i5.jpg | Bin 31015 -> 0 bytes docs/_static/images/ESP_AH.png | Bin 35607 -> 0 bytes docs/_static/images/IPSec_close_action_settings.png | Bin 22371 -> 0 bytes docs/_static/images/L3VPN_hub_and_spoke.png | Bin 134458 -> 0 bytes docs/_static/images/PA-ESP-group.png | Bin 27516 -> 0 bytes docs/_static/images/PA-IKE-GW-1.png | Bin 31121 -> 0 bytes docs/_static/images/PA-IKE-GW-2.png | Bin 19848 -> 0 bytes docs/_static/images/PA-IKE-group.png | Bin 26998 -> 0 bytes docs/_static/images/PA-IPsec-tunnel.png | Bin 33519 -> 0 bytes docs/_static/images/PA-tunnel-1.png | Bin 16308 -> 0 bytes docs/_static/images/PA-tunnel-2.png | Bin 18290 -> 0 bytes docs/_static/images/PA-tunnel-3.png | Bin 15779 -> 0 bytes docs/_static/images/VyOS_Dual-Hub_DMVPN.png | Bin 67747 -> 0 bytes docs/_static/images/Wan_load_balancing1.png | Bin 373848 -> 0 bytes docs/_static/images/Wan_load_balancing_exclude1.png | Bin 382563 -> 0 bytes docs/_static/images/ansible.png | Bin 204124 -> 0 bytes docs/_static/images/apu4_desk_1.jpg | Bin 816206 -> 0 bytes docs/_static/images/apu4_desk_2.jpg | Bin 288989 -> 0 bytes docs/_static/images/apu4_desk_3.jpg | Bin 831843 -> 0 bytes docs/_static/images/apu4_desk_4.jpg | Bin 804070 -> 0 bytes docs/_static/images/apu4_rack_1.jpg | Bin 305789 -> 0 bytes docs/_static/images/apu4_rack_2.jpg | Bin 623490 -> 0 bytes docs/_static/images/apu4_rack_3.jpg | Bin 1113842 -> 0 bytes docs/_static/images/apu4_rack_4.jpg | Bin 1676612 -> 0 bytes docs/_static/images/apu4_rack_5.jpg | Bin 1584027 -> 0 bytes docs/_static/images/apu4_rack_vyos_print.jpg | Bin 569311 -> 0 bytes docs/_static/images/aws.png | Bin 150759 -> 0 bytes docs/_static/images/blueprint-dmvpn.png | Bin 29626 -> 0 bytes docs/_static/images/boot-options.png | Bin 30582 -> 0 bytes docs/_static/images/cisco-vpn-ipsec.png | Bin 38659 -> 0 bytes docs/_static/images/cloud-aws-01.png | Bin 54783 -> 0 bytes docs/_static/images/cloud-aws-02.png | Bin 88657 -> 0 bytes docs/_static/images/cloud-aws-03.png | Bin 48191 -> 0 bytes docs/_static/images/cloud-aws-04.png | Bin 131948 -> 0 bytes docs/_static/images/cloud-aws-05.png | Bin 103661 -> 0 bytes docs/_static/images/cloud-aws-06.png | Bin 111207 -> 0 bytes docs/_static/images/cloud-aws-07.png | Bin 72764 -> 0 bytes docs/_static/images/cloud-aws-08.png | Bin 20893 -> 0 bytes docs/_static/images/cloud-azure-01.png | Bin 90521 -> 0 bytes docs/_static/images/cloud-azure-02.png | Bin 56507 -> 0 bytes docs/_static/images/cloud-azure-03.png | Bin 47364 -> 0 bytes docs/_static/images/cloud-azure-04.png | Bin 87475 -> 0 bytes docs/_static/images/cloud-azure-05.png | Bin 77301 -> 0 bytes docs/_static/images/cloud-azure-06.png | Bin 57830 -> 0 bytes docs/_static/images/cloud-gcp-01.png | Bin 5526 -> 0 bytes docs/_static/images/cloud-gcp-02.png | Bin 46685 -> 0 bytes docs/_static/images/cloud-gcp-03.png | Bin 106217 -> 0 bytes docs/_static/images/cloud-gcp-04.png | Bin 19727 -> 0 bytes docs/_static/images/cloud-gcp-05.png | Bin 26049 -> 0 bytes docs/_static/images/dhcp-relay-through-gre-bridge.png | Bin 31261 -> 0 bytes docs/_static/images/dual-hub-DMVPN.png | Bin 88497 -> 0 bytes docs/_static/images/eve-ng-vyos.png | Bin 4228 -> 0 bytes docs/_static/images/firewall-and-vrf-blueprints.png | Bin 84270 -> 0 bytes docs/_static/images/firewall-bridge-forward.png | Bin 26359 -> 0 bytes docs/_static/images/firewall-bridge-input.png | Bin 39158 -> 0 bytes docs/_static/images/firewall-bridge-output.png | Bin 34496 -> 0 bytes .../_static/images/firewall-flowtable-packet-flow.png | Bin 47883 -> 0 bytes docs/_static/images/firewall-fwd-packet-flow.png | Bin 30593 -> 0 bytes docs/_static/images/firewall-gral-packet-flow.png | Bin 49632 -> 0 bytes docs/_static/images/firewall-input-packet-flow.png | Bin 43944 -> 0 bytes docs/_static/images/firewall-netfilter.png | Bin 73608 -> 0 bytes docs/_static/images/firewall-traditional.png | Bin 53437 -> 0 bytes docs/_static/images/firewall-zonebased.png | Bin 55621 -> 0 bytes docs/_static/images/gns3-01.png | Bin 28912 -> 0 bytes docs/_static/images/gns3-02.png | Bin 179730 -> 0 bytes docs/_static/images/gns3-03.png | Bin 22829 -> 0 bytes docs/_static/images/gns3-04.png | Bin 35150 -> 0 bytes docs/_static/images/gns3-05.png | Bin 31728 -> 0 bytes docs/_static/images/gns3-06.png | Bin 29168 -> 0 bytes docs/_static/images/gns3-07.png | Bin 31199 -> 0 bytes docs/_static/images/gns3-08.png | Bin 29636 -> 0 bytes docs/_static/images/gns3-09.png | Bin 21881 -> 0 bytes docs/_static/images/gns3-10.png | Bin 30788 -> 0 bytes docs/_static/images/gns3-11.png | Bin 168937 -> 0 bytes docs/_static/images/gns3-12.png | Bin 58597 -> 0 bytes docs/_static/images/gns3-13.png | Bin 56994 -> 0 bytes docs/_static/images/gns3-14.png | Bin 28821 -> 0 bytes docs/_static/images/gns3-15.png | Bin 45453 -> 0 bytes docs/_static/images/gns3-16.png | Bin 54790 -> 0 bytes docs/_static/images/gns3-17.png | Bin 169380 -> 0 bytes docs/_static/images/gns3-20.png | Bin 55168 -> 0 bytes docs/_static/images/gns3-21.png | Bin 25663 -> 0 bytes docs/_static/images/gns3-215.png | Bin 44485 -> 0 bytes docs/_static/images/gns3-22.png | Bin 54674 -> 0 bytes docs/_static/images/gowin-01.png | Bin 355723 -> 0 bytes docs/_static/images/gowin-02.png | Bin 2613833 -> 0 bytes docs/_static/images/gowin-03.png | Bin 2268530 -> 0 bytes docs/_static/images/gowin-04.png | Bin 2165023 -> 0 bytes docs/_static/images/inter-vrf-routing-vrf-lite.png | Bin 104622 -> 0 bytes docs/_static/images/ipsec-vyos-pa.png | Bin 61250 -> 0 bytes docs/_static/images/json.png | Bin 26585 -> 0 bytes docs/_static/images/key.png | Bin 165894 -> 0 bytes docs/_static/images/keypairs.png | Bin 49718 -> 0 bytes docs/_static/images/lac-lns-diagram.jpg | Bin 35665 -> 0 bytes docs/_static/images/lac-lns-winclient.jpg | Bin 90842 -> 0 bytes docs/_static/images/ldapone.png | Bin 88753 -> 0 bytes docs/_static/images/ldaptwo.png | Bin 58322 -> 0 bytes docs/_static/images/mainschema.png | Bin 78790 -> 0 bytes docs/_static/images/multicast-basic.png | Bin 43708 -> 0 bytes docs/_static/images/nat_before_vpn_topology.png | Bin 19015 -> 0 bytes docs/_static/images/nmp1.png | Bin 128546 -> 0 bytes docs/_static/images/nmp2.png | Bin 52507 -> 0 bytes docs/_static/images/nmp3.png | Bin 107595 -> 0 bytes docs/_static/images/nmp4.png | Bin 72678 -> 0 bytes docs/_static/images/nmp5.png | Bin 115299 -> 0 bytes docs/_static/images/nmp6.png | Bin 130524 -> 0 bytes docs/_static/images/nmp7.png | Bin 100135 -> 0 bytes docs/_static/images/openvpn_site2site_diagram.jpg | Bin 24179 -> 0 bytes docs/_static/images/pbr_example_1.png | Bin 39170 -> 0 bytes .../images/policy-based-ipsec-and-firewall.png | Bin 42987 -> 0 bytes docs/_static/images/pppoe-ipv6-pd-diagram.jpg | Bin 19993 -> 0 bytes docs/_static/images/project.png | Bin 18173 -> 0 bytes docs/_static/images/qos1.png | Bin 135527 -> 0 bytes docs/_static/images/qos10.png | Bin 119669 -> 0 bytes docs/_static/images/qos2.png | Bin 140834 -> 0 bytes docs/_static/images/qos3.png | Bin 16699 -> 0 bytes docs/_static/images/qos4.png | Bin 17273 -> 0 bytes docs/_static/images/qos5.png | Bin 15868 -> 0 bytes docs/_static/images/qos6.png | Bin 139244 -> 0 bytes docs/_static/images/qos7.png | Bin 17775 -> 0 bytes docs/_static/images/qos8.png | Bin 17368 -> 0 bytes docs/_static/images/qos9.png | Bin 17065 -> 0 bytes docs/_static/images/reset-password-step-1.jpg | Bin 37351 -> 0 bytes docs/_static/images/reset-password-step-2.jpg | Bin 42278 -> 0 bytes docs/_static/images/reset-password-step-3.jpg | Bin 36932 -> 0 bytes docs/_static/images/reset-password-step-4.jpg | Bin 31564 -> 0 bytes docs/_static/images/reset-password-step-5.jpg | Bin 100973 -> 0 bytes docs/_static/images/service.png | Bin 195145 -> 0 bytes docs/_static/images/service_conntrack_sync-schema.png | Bin 56954 -> 0 bytes docs/_static/images/service_dhcp-relay01.png | Bin 153617 -> 0 bytes docs/_static/images/service_dhcpv6-relay01.png | Bin 150157 -> 0 bytes .../service_snmp_communication_principles_diagram.png | Bin 56582 -> 0 bytes docs/_static/images/sg.png | Bin 31817 -> 0 bytes docs/_static/images/sticky-connections.jpg | Bin 22252 -> 0 bytes docs/_static/images/traffic.png | Bin 36786 -> 0 bytes docs/_static/images/uefi_secureboot_01.png | Bin 60527 -> 0 bytes docs/_static/images/uefi_secureboot_02.png | Bin 14091 -> 0 bytes docs/_static/images/uefi_secureboot_03.png | Bin 14760 -> 0 bytes docs/_static/images/uefi_secureboot_04.png | Bin 7349 -> 0 bytes docs/_static/images/uefi_secureboot_05.png | Bin 6636 -> 0 bytes docs/_static/images/uefi_secureboot_06.png | Bin 7102 -> 0 bytes docs/_static/images/uefi_secureboot_07.png | Bin 12622 -> 0 bytes docs/_static/images/virt-libvirt-01.png | Bin 33227 -> 0 bytes docs/_static/images/virt-libvirt-02.png | Bin 30981 -> 0 bytes docs/_static/images/virt-libvirt-03.png | Bin 24547 -> 0 bytes docs/_static/images/virt-libvirt-04.png | Bin 28896 -> 0 bytes docs/_static/images/virt-libvirt-05.png | Bin 38080 -> 0 bytes docs/_static/images/virt-libvirt-06.png | Bin 28784 -> 0 bytes docs/_static/images/virt-libvirt-qc-01.png | Bin 33468 -> 0 bytes docs/_static/images/virt-libvirt-qc-02.png | Bin 26749 -> 0 bytes docs/_static/images/virt-libvirt-qc-03.png | Bin 28278 -> 0 bytes docs/_static/images/vpn_dmvpn_topology01.png | Bin 94382 -> 0 bytes docs/_static/images/vpn_s2s_ikev2.png | Bin 66279 -> 0 bytes docs/_static/images/vpn_s2s_ikev2_c.png | Bin 69496 -> 0 bytes docs/_static/images/vrf-example-topology-01.png | Bin 32567 -> 0 bytes docs/_static/images/vyos-downloads.png | Bin 65202 -> 0 bytes docs/_static/images/vyos-sr-isis.png | Bin 45339 -> 0 bytes docs/_static/images/vyos_1_4_nat66_simple.png | Bin 21021 -> 0 bytes docs/_static/images/vyos_1_5_nat66_dhcpv6_wdummy.png | Bin 349078 -> 0 bytes docs/_static/images/vyos_arista_bond_lacp.png | Bin 40622 -> 0 bytes docs/_static/images/vyosnew-downloads.png | Bin 64419 -> 0 bytes docs/_static/images/wireguard_qrcode.jpg | Bin 133939 -> 0 bytes docs/_static/images/wireguard_site2site_diagram.jpg | Bin 19987 -> 0 bytes docs/_static/images/zone-policy-diagram.png | Bin 113618 -> 0 bytes 175 files changed, 0 insertions(+), 0 deletions(-) delete mode 100644 docs/_static/images/1u_vyos_back.jpg delete mode 100644 docs/_static/images/1u_vyos_front.jpg delete mode 100644 docs/_static/images/1u_vyos_front_10ge_open_1.jpg delete mode 100644 docs/_static/images/1u_vyos_front_10ge_open_2.jpg delete mode 100644 docs/_static/images/1u_vyos_front_10ge_open_3.jpg delete mode 100644 docs/_static/images/1u_vyos_front_10ge_open_4.jpg delete mode 100644 docs/_static/images/1u_vyos_front_open_1.jpg delete mode 100644 docs/_static/images/1u_vyos_front_open_2.jpg delete mode 100644 docs/_static/images/1u_vyos_front_open_3.jpg delete mode 100644 docs/_static/images/480px-Acrosser_ANDJ190N1_Back.jpg delete mode 100644 docs/_static/images/480px-Acrosser_ANDJ190N1_Front.jpg delete mode 100644 docs/_static/images/600px-Partaker-i5.jpg delete mode 100644 docs/_static/images/ESP_AH.png delete mode 100644 docs/_static/images/IPSec_close_action_settings.png delete mode 100644 docs/_static/images/L3VPN_hub_and_spoke.png delete mode 100644 docs/_static/images/PA-ESP-group.png delete mode 100644 docs/_static/images/PA-IKE-GW-1.png delete mode 100644 docs/_static/images/PA-IKE-GW-2.png delete mode 100644 docs/_static/images/PA-IKE-group.png delete mode 100644 docs/_static/images/PA-IPsec-tunnel.png delete mode 100644 docs/_static/images/PA-tunnel-1.png delete mode 100644 docs/_static/images/PA-tunnel-2.png delete mode 100644 docs/_static/images/PA-tunnel-3.png delete mode 100644 docs/_static/images/VyOS_Dual-Hub_DMVPN.png delete mode 100644 docs/_static/images/Wan_load_balancing1.png delete mode 100644 docs/_static/images/Wan_load_balancing_exclude1.png delete mode 100644 docs/_static/images/ansible.png delete mode 100644 docs/_static/images/apu4_desk_1.jpg delete mode 100644 docs/_static/images/apu4_desk_2.jpg delete mode 100644 docs/_static/images/apu4_desk_3.jpg delete mode 100644 docs/_static/images/apu4_desk_4.jpg delete mode 100644 docs/_static/images/apu4_rack_1.jpg delete mode 100644 docs/_static/images/apu4_rack_2.jpg delete mode 100644 docs/_static/images/apu4_rack_3.jpg delete mode 100644 docs/_static/images/apu4_rack_4.jpg delete mode 100644 docs/_static/images/apu4_rack_5.jpg delete mode 100644 docs/_static/images/apu4_rack_vyos_print.jpg delete mode 100644 docs/_static/images/aws.png delete mode 100644 docs/_static/images/blueprint-dmvpn.png delete mode 100644 docs/_static/images/boot-options.png delete mode 100644 docs/_static/images/cisco-vpn-ipsec.png delete mode 100644 docs/_static/images/cloud-aws-01.png delete mode 100644 docs/_static/images/cloud-aws-02.png delete mode 100644 docs/_static/images/cloud-aws-03.png delete mode 100644 docs/_static/images/cloud-aws-04.png delete mode 100644 docs/_static/images/cloud-aws-05.png delete mode 100644 docs/_static/images/cloud-aws-06.png delete mode 100644 docs/_static/images/cloud-aws-07.png delete mode 100644 docs/_static/images/cloud-aws-08.png delete mode 100644 docs/_static/images/cloud-azure-01.png delete mode 100644 docs/_static/images/cloud-azure-02.png delete mode 100644 docs/_static/images/cloud-azure-03.png delete mode 100644 docs/_static/images/cloud-azure-04.png delete mode 100644 docs/_static/images/cloud-azure-05.png delete mode 100644 docs/_static/images/cloud-azure-06.png delete mode 100644 docs/_static/images/cloud-gcp-01.png delete mode 100644 docs/_static/images/cloud-gcp-02.png delete mode 100644 docs/_static/images/cloud-gcp-03.png delete mode 100644 docs/_static/images/cloud-gcp-04.png delete mode 100644 docs/_static/images/cloud-gcp-05.png delete mode 100644 docs/_static/images/dhcp-relay-through-gre-bridge.png delete mode 100644 docs/_static/images/dual-hub-DMVPN.png delete mode 100644 docs/_static/images/eve-ng-vyos.png delete mode 100644 docs/_static/images/firewall-and-vrf-blueprints.png delete mode 100644 docs/_static/images/firewall-bridge-forward.png delete mode 100644 docs/_static/images/firewall-bridge-input.png delete mode 100644 docs/_static/images/firewall-bridge-output.png delete mode 100644 docs/_static/images/firewall-flowtable-packet-flow.png delete mode 100644 docs/_static/images/firewall-fwd-packet-flow.png delete mode 100644 docs/_static/images/firewall-gral-packet-flow.png delete mode 100644 docs/_static/images/firewall-input-packet-flow.png delete mode 100644 docs/_static/images/firewall-netfilter.png delete mode 100644 docs/_static/images/firewall-traditional.png delete mode 100644 docs/_static/images/firewall-zonebased.png delete mode 100644 docs/_static/images/gns3-01.png delete mode 100644 docs/_static/images/gns3-02.png delete mode 100644 docs/_static/images/gns3-03.png delete mode 100644 docs/_static/images/gns3-04.png delete mode 100644 docs/_static/images/gns3-05.png delete mode 100644 docs/_static/images/gns3-06.png delete mode 100644 docs/_static/images/gns3-07.png delete mode 100644 docs/_static/images/gns3-08.png delete mode 100644 docs/_static/images/gns3-09.png delete mode 100644 docs/_static/images/gns3-10.png delete mode 100644 docs/_static/images/gns3-11.png delete mode 100644 docs/_static/images/gns3-12.png delete mode 100644 docs/_static/images/gns3-13.png delete mode 100644 docs/_static/images/gns3-14.png delete mode 100644 docs/_static/images/gns3-15.png delete mode 100644 docs/_static/images/gns3-16.png delete mode 100644 docs/_static/images/gns3-17.png delete mode 100644 docs/_static/images/gns3-20.png delete mode 100644 docs/_static/images/gns3-21.png delete mode 100644 docs/_static/images/gns3-215.png delete mode 100644 docs/_static/images/gns3-22.png delete mode 100644 docs/_static/images/gowin-01.png delete mode 100644 docs/_static/images/gowin-02.png delete mode 100644 docs/_static/images/gowin-03.png delete mode 100644 docs/_static/images/gowin-04.png delete mode 100644 docs/_static/images/inter-vrf-routing-vrf-lite.png delete mode 100644 docs/_static/images/ipsec-vyos-pa.png delete mode 100644 docs/_static/images/json.png delete mode 100644 docs/_static/images/key.png delete mode 100644 docs/_static/images/keypairs.png delete mode 100644 docs/_static/images/lac-lns-diagram.jpg delete mode 100644 docs/_static/images/lac-lns-winclient.jpg delete mode 100644 docs/_static/images/ldapone.png delete mode 100644 docs/_static/images/ldaptwo.png delete mode 100644 docs/_static/images/mainschema.png delete mode 100644 docs/_static/images/multicast-basic.png delete mode 100644 docs/_static/images/nat_before_vpn_topology.png delete mode 100644 docs/_static/images/nmp1.png delete mode 100644 docs/_static/images/nmp2.png delete mode 100644 docs/_static/images/nmp3.png delete mode 100644 docs/_static/images/nmp4.png delete mode 100644 docs/_static/images/nmp5.png delete mode 100644 docs/_static/images/nmp6.png delete mode 100644 docs/_static/images/nmp7.png delete mode 100644 docs/_static/images/openvpn_site2site_diagram.jpg delete mode 100644 docs/_static/images/pbr_example_1.png delete mode 100644 docs/_static/images/policy-based-ipsec-and-firewall.png delete mode 100644 docs/_static/images/pppoe-ipv6-pd-diagram.jpg delete mode 100644 docs/_static/images/project.png delete mode 100644 docs/_static/images/qos1.png delete mode 100644 docs/_static/images/qos10.png delete mode 100644 docs/_static/images/qos2.png delete mode 100644 docs/_static/images/qos3.png delete mode 100644 docs/_static/images/qos4.png delete mode 100644 docs/_static/images/qos5.png delete mode 100644 docs/_static/images/qos6.png delete mode 100644 docs/_static/images/qos7.png delete mode 100644 docs/_static/images/qos8.png delete mode 100644 docs/_static/images/qos9.png delete mode 100644 docs/_static/images/reset-password-step-1.jpg delete mode 100644 docs/_static/images/reset-password-step-2.jpg delete mode 100644 docs/_static/images/reset-password-step-3.jpg delete mode 100644 docs/_static/images/reset-password-step-4.jpg delete mode 100644 docs/_static/images/reset-password-step-5.jpg delete mode 100644 docs/_static/images/service.png delete mode 100644 docs/_static/images/service_conntrack_sync-schema.png delete mode 100644 docs/_static/images/service_dhcp-relay01.png delete mode 100644 docs/_static/images/service_dhcpv6-relay01.png delete mode 100644 docs/_static/images/service_snmp_communication_principles_diagram.png delete mode 100644 docs/_static/images/sg.png delete mode 100644 docs/_static/images/sticky-connections.jpg delete mode 100644 docs/_static/images/traffic.png delete mode 100644 docs/_static/images/uefi_secureboot_01.png delete mode 100644 docs/_static/images/uefi_secureboot_02.png delete mode 100644 docs/_static/images/uefi_secureboot_03.png delete mode 100644 docs/_static/images/uefi_secureboot_04.png delete mode 100644 docs/_static/images/uefi_secureboot_05.png delete mode 100644 docs/_static/images/uefi_secureboot_06.png delete mode 100644 docs/_static/images/uefi_secureboot_07.png delete mode 100644 docs/_static/images/virt-libvirt-01.png delete mode 100644 docs/_static/images/virt-libvirt-02.png delete mode 100644 docs/_static/images/virt-libvirt-03.png delete mode 100644 docs/_static/images/virt-libvirt-04.png delete mode 100644 docs/_static/images/virt-libvirt-05.png delete mode 100644 docs/_static/images/virt-libvirt-06.png delete mode 100644 docs/_static/images/virt-libvirt-qc-01.png delete mode 100644 docs/_static/images/virt-libvirt-qc-02.png delete mode 100644 docs/_static/images/virt-libvirt-qc-03.png delete mode 100644 docs/_static/images/vpn_dmvpn_topology01.png delete mode 100644 docs/_static/images/vpn_s2s_ikev2.png delete mode 100644 docs/_static/images/vpn_s2s_ikev2_c.png delete mode 100644 docs/_static/images/vrf-example-topology-01.png delete mode 100644 docs/_static/images/vyos-downloads.png delete mode 100644 docs/_static/images/vyos-sr-isis.png delete mode 100644 docs/_static/images/vyos_1_4_nat66_simple.png delete mode 100644 docs/_static/images/vyos_1_5_nat66_dhcpv6_wdummy.png delete mode 100644 docs/_static/images/vyos_arista_bond_lacp.png delete mode 100644 docs/_static/images/vyosnew-downloads.png delete mode 100644 docs/_static/images/wireguard_qrcode.jpg delete mode 100644 docs/_static/images/wireguard_site2site_diagram.jpg delete mode 100644 docs/_static/images/zone-policy-diagram.png (limited to 'docs/_static') diff --git a/docs/_static/images/1u_vyos_back.jpg b/docs/_static/images/1u_vyos_back.jpg deleted file mode 100644 index cd00c11c..00000000 Binary files a/docs/_static/images/1u_vyos_back.jpg and /dev/null differ diff --git a/docs/_static/images/1u_vyos_front.jpg b/docs/_static/images/1u_vyos_front.jpg deleted file mode 100644 index 3d135d56..00000000 Binary files a/docs/_static/images/1u_vyos_front.jpg and /dev/null differ diff --git a/docs/_static/images/1u_vyos_front_10ge_open_1.jpg b/docs/_static/images/1u_vyos_front_10ge_open_1.jpg deleted file mode 100644 index edfba5a3..00000000 Binary files a/docs/_static/images/1u_vyos_front_10ge_open_1.jpg and /dev/null differ diff --git a/docs/_static/images/1u_vyos_front_10ge_open_2.jpg b/docs/_static/images/1u_vyos_front_10ge_open_2.jpg deleted file mode 100644 index 4f48a116..00000000 Binary files a/docs/_static/images/1u_vyos_front_10ge_open_2.jpg and /dev/null differ diff --git a/docs/_static/images/1u_vyos_front_10ge_open_3.jpg b/docs/_static/images/1u_vyos_front_10ge_open_3.jpg deleted file mode 100644 index c102b903..00000000 Binary files a/docs/_static/images/1u_vyos_front_10ge_open_3.jpg and /dev/null differ diff --git a/docs/_static/images/1u_vyos_front_10ge_open_4.jpg b/docs/_static/images/1u_vyos_front_10ge_open_4.jpg deleted file mode 100644 index 2f270b7e..00000000 Binary files a/docs/_static/images/1u_vyos_front_10ge_open_4.jpg and /dev/null differ diff --git a/docs/_static/images/1u_vyos_front_open_1.jpg b/docs/_static/images/1u_vyos_front_open_1.jpg deleted file mode 100644 index d90d565e..00000000 Binary files a/docs/_static/images/1u_vyos_front_open_1.jpg and /dev/null differ diff --git a/docs/_static/images/1u_vyos_front_open_2.jpg b/docs/_static/images/1u_vyos_front_open_2.jpg deleted file mode 100644 index 6d112463..00000000 Binary files a/docs/_static/images/1u_vyos_front_open_2.jpg and /dev/null differ diff --git a/docs/_static/images/1u_vyos_front_open_3.jpg b/docs/_static/images/1u_vyos_front_open_3.jpg deleted file mode 100644 index 198ba3ce..00000000 Binary files a/docs/_static/images/1u_vyos_front_open_3.jpg and /dev/null differ diff --git a/docs/_static/images/480px-Acrosser_ANDJ190N1_Back.jpg b/docs/_static/images/480px-Acrosser_ANDJ190N1_Back.jpg deleted file mode 100644 index 6441c54a..00000000 Binary files a/docs/_static/images/480px-Acrosser_ANDJ190N1_Back.jpg and /dev/null differ diff --git a/docs/_static/images/480px-Acrosser_ANDJ190N1_Front.jpg b/docs/_static/images/480px-Acrosser_ANDJ190N1_Front.jpg deleted file mode 100644 index 5f216aa1..00000000 Binary files a/docs/_static/images/480px-Acrosser_ANDJ190N1_Front.jpg and /dev/null differ diff --git a/docs/_static/images/600px-Partaker-i5.jpg b/docs/_static/images/600px-Partaker-i5.jpg deleted file mode 100644 index 68196d41..00000000 Binary files a/docs/_static/images/600px-Partaker-i5.jpg and /dev/null differ diff --git a/docs/_static/images/ESP_AH.png b/docs/_static/images/ESP_AH.png deleted file mode 100644 index 6075c3f4..00000000 Binary files a/docs/_static/images/ESP_AH.png and /dev/null differ diff --git a/docs/_static/images/IPSec_close_action_settings.png b/docs/_static/images/IPSec_close_action_settings.png deleted file mode 100644 index 531643f7..00000000 Binary files a/docs/_static/images/IPSec_close_action_settings.png and /dev/null differ diff --git a/docs/_static/images/L3VPN_hub_and_spoke.png b/docs/_static/images/L3VPN_hub_and_spoke.png deleted file mode 100644 index d442cc1a..00000000 Binary files a/docs/_static/images/L3VPN_hub_and_spoke.png and /dev/null differ diff --git a/docs/_static/images/PA-ESP-group.png b/docs/_static/images/PA-ESP-group.png deleted file mode 100644 index c6411b66..00000000 Binary files a/docs/_static/images/PA-ESP-group.png and /dev/null differ diff --git a/docs/_static/images/PA-IKE-GW-1.png b/docs/_static/images/PA-IKE-GW-1.png deleted file mode 100644 index 863eeb3a..00000000 Binary files a/docs/_static/images/PA-IKE-GW-1.png and /dev/null differ diff --git a/docs/_static/images/PA-IKE-GW-2.png b/docs/_static/images/PA-IKE-GW-2.png deleted file mode 100644 index 21a16055..00000000 Binary files a/docs/_static/images/PA-IKE-GW-2.png and /dev/null differ diff --git a/docs/_static/images/PA-IKE-group.png b/docs/_static/images/PA-IKE-group.png deleted file mode 100644 index 06fd535d..00000000 Binary files a/docs/_static/images/PA-IKE-group.png and /dev/null differ diff --git a/docs/_static/images/PA-IPsec-tunnel.png b/docs/_static/images/PA-IPsec-tunnel.png deleted file mode 100644 index 2f8f4cb8..00000000 Binary files a/docs/_static/images/PA-IPsec-tunnel.png and /dev/null differ diff --git a/docs/_static/images/PA-tunnel-1.png b/docs/_static/images/PA-tunnel-1.png deleted file mode 100644 index 3c99c6c7..00000000 Binary files a/docs/_static/images/PA-tunnel-1.png and /dev/null differ diff --git a/docs/_static/images/PA-tunnel-2.png b/docs/_static/images/PA-tunnel-2.png deleted file mode 100644 index 6f073513..00000000 Binary files a/docs/_static/images/PA-tunnel-2.png and /dev/null differ diff --git a/docs/_static/images/PA-tunnel-3.png b/docs/_static/images/PA-tunnel-3.png deleted file mode 100644 index ca5a94e9..00000000 Binary files a/docs/_static/images/PA-tunnel-3.png and /dev/null differ diff --git a/docs/_static/images/VyOS_Dual-Hub_DMVPN.png b/docs/_static/images/VyOS_Dual-Hub_DMVPN.png deleted file mode 100644 index 9c25a308..00000000 Binary files a/docs/_static/images/VyOS_Dual-Hub_DMVPN.png and /dev/null differ diff --git a/docs/_static/images/Wan_load_balancing1.png b/docs/_static/images/Wan_load_balancing1.png deleted file mode 100644 index bde1edb6..00000000 Binary files a/docs/_static/images/Wan_load_balancing1.png and /dev/null differ diff --git a/docs/_static/images/Wan_load_balancing_exclude1.png b/docs/_static/images/Wan_load_balancing_exclude1.png deleted file mode 100644 index 1111535d..00000000 Binary files a/docs/_static/images/Wan_load_balancing_exclude1.png and /dev/null differ diff --git a/docs/_static/images/ansible.png b/docs/_static/images/ansible.png deleted file mode 100644 index 1d80b3f4..00000000 Binary files a/docs/_static/images/ansible.png and /dev/null differ diff --git a/docs/_static/images/apu4_desk_1.jpg b/docs/_static/images/apu4_desk_1.jpg deleted file mode 100644 index b7a3d08e..00000000 Binary files a/docs/_static/images/apu4_desk_1.jpg and /dev/null differ diff --git a/docs/_static/images/apu4_desk_2.jpg b/docs/_static/images/apu4_desk_2.jpg deleted file mode 100644 index fe356e1f..00000000 Binary files a/docs/_static/images/apu4_desk_2.jpg and /dev/null differ diff --git a/docs/_static/images/apu4_desk_3.jpg b/docs/_static/images/apu4_desk_3.jpg deleted file mode 100644 index af7dc406..00000000 Binary files a/docs/_static/images/apu4_desk_3.jpg and /dev/null differ diff --git a/docs/_static/images/apu4_desk_4.jpg b/docs/_static/images/apu4_desk_4.jpg deleted file mode 100644 index 37251af2..00000000 Binary files a/docs/_static/images/apu4_desk_4.jpg and /dev/null differ diff --git a/docs/_static/images/apu4_rack_1.jpg b/docs/_static/images/apu4_rack_1.jpg deleted file mode 100644 index 3793cd39..00000000 Binary files a/docs/_static/images/apu4_rack_1.jpg and /dev/null differ diff --git a/docs/_static/images/apu4_rack_2.jpg b/docs/_static/images/apu4_rack_2.jpg deleted file mode 100644 index b8caf976..00000000 Binary files a/docs/_static/images/apu4_rack_2.jpg and /dev/null differ diff --git a/docs/_static/images/apu4_rack_3.jpg b/docs/_static/images/apu4_rack_3.jpg deleted file mode 100644 index 08ff633e..00000000 Binary files a/docs/_static/images/apu4_rack_3.jpg and /dev/null differ diff --git a/docs/_static/images/apu4_rack_4.jpg b/docs/_static/images/apu4_rack_4.jpg deleted file mode 100644 index a88d62fe..00000000 Binary files a/docs/_static/images/apu4_rack_4.jpg and /dev/null differ diff --git a/docs/_static/images/apu4_rack_5.jpg b/docs/_static/images/apu4_rack_5.jpg deleted file mode 100644 index 644b8e0a..00000000 Binary files a/docs/_static/images/apu4_rack_5.jpg and /dev/null differ diff --git a/docs/_static/images/apu4_rack_vyos_print.jpg b/docs/_static/images/apu4_rack_vyos_print.jpg deleted file mode 100644 index a0bbaab2..00000000 Binary files a/docs/_static/images/apu4_rack_vyos_print.jpg and /dev/null differ diff --git a/docs/_static/images/aws.png b/docs/_static/images/aws.png deleted file mode 100644 index c1c111bb..00000000 Binary files a/docs/_static/images/aws.png and /dev/null differ diff --git a/docs/_static/images/blueprint-dmvpn.png b/docs/_static/images/blueprint-dmvpn.png deleted file mode 100644 index 85f189c1..00000000 Binary files a/docs/_static/images/blueprint-dmvpn.png and /dev/null differ diff --git a/docs/_static/images/boot-options.png b/docs/_static/images/boot-options.png deleted file mode 100644 index b00350bc..00000000 Binary files a/docs/_static/images/boot-options.png and /dev/null differ diff --git a/docs/_static/images/cisco-vpn-ipsec.png b/docs/_static/images/cisco-vpn-ipsec.png deleted file mode 100644 index bc19e8bc..00000000 Binary files a/docs/_static/images/cisco-vpn-ipsec.png and /dev/null differ diff --git a/docs/_static/images/cloud-aws-01.png b/docs/_static/images/cloud-aws-01.png deleted file mode 100644 index cda6542f..00000000 Binary files a/docs/_static/images/cloud-aws-01.png and /dev/null differ diff --git a/docs/_static/images/cloud-aws-02.png b/docs/_static/images/cloud-aws-02.png deleted file mode 100644 index 639d42fa..00000000 Binary files a/docs/_static/images/cloud-aws-02.png and /dev/null differ diff --git a/docs/_static/images/cloud-aws-03.png b/docs/_static/images/cloud-aws-03.png deleted file mode 100644 index 92d3e63b..00000000 Binary files a/docs/_static/images/cloud-aws-03.png and /dev/null differ diff --git a/docs/_static/images/cloud-aws-04.png b/docs/_static/images/cloud-aws-04.png deleted file mode 100644 index 3ae4fb2a..00000000 Binary files a/docs/_static/images/cloud-aws-04.png and /dev/null differ diff --git a/docs/_static/images/cloud-aws-05.png b/docs/_static/images/cloud-aws-05.png deleted file mode 100644 index fa3521a6..00000000 Binary files a/docs/_static/images/cloud-aws-05.png and /dev/null differ diff --git a/docs/_static/images/cloud-aws-06.png b/docs/_static/images/cloud-aws-06.png deleted file mode 100644 index c8f88ded..00000000 Binary files a/docs/_static/images/cloud-aws-06.png and /dev/null differ diff --git a/docs/_static/images/cloud-aws-07.png b/docs/_static/images/cloud-aws-07.png deleted file mode 100644 index d9f934ac..00000000 Binary files a/docs/_static/images/cloud-aws-07.png and /dev/null differ diff --git a/docs/_static/images/cloud-aws-08.png b/docs/_static/images/cloud-aws-08.png deleted file mode 100644 index db3030a0..00000000 Binary files a/docs/_static/images/cloud-aws-08.png and /dev/null differ diff --git a/docs/_static/images/cloud-azure-01.png b/docs/_static/images/cloud-azure-01.png deleted file mode 100644 index 2c7b1adb..00000000 Binary files a/docs/_static/images/cloud-azure-01.png and /dev/null differ diff --git a/docs/_static/images/cloud-azure-02.png b/docs/_static/images/cloud-azure-02.png deleted file mode 100644 index 286b8689..00000000 Binary files a/docs/_static/images/cloud-azure-02.png and /dev/null differ diff --git a/docs/_static/images/cloud-azure-03.png b/docs/_static/images/cloud-azure-03.png deleted file mode 100644 index 4661a1fb..00000000 Binary files a/docs/_static/images/cloud-azure-03.png and /dev/null differ diff --git a/docs/_static/images/cloud-azure-04.png b/docs/_static/images/cloud-azure-04.png deleted file mode 100644 index af12d337..00000000 Binary files a/docs/_static/images/cloud-azure-04.png and /dev/null differ diff --git a/docs/_static/images/cloud-azure-05.png b/docs/_static/images/cloud-azure-05.png deleted file mode 100644 index c5a32d2e..00000000 Binary files a/docs/_static/images/cloud-azure-05.png and /dev/null differ diff --git a/docs/_static/images/cloud-azure-06.png b/docs/_static/images/cloud-azure-06.png deleted file mode 100644 index 1cc7cbf1..00000000 Binary files a/docs/_static/images/cloud-azure-06.png and /dev/null differ diff --git a/docs/_static/images/cloud-gcp-01.png b/docs/_static/images/cloud-gcp-01.png deleted file mode 100644 index f7681d6e..00000000 Binary files a/docs/_static/images/cloud-gcp-01.png and /dev/null differ diff --git a/docs/_static/images/cloud-gcp-02.png b/docs/_static/images/cloud-gcp-02.png deleted file mode 100644 index 5a17efb4..00000000 Binary files a/docs/_static/images/cloud-gcp-02.png and /dev/null differ diff --git a/docs/_static/images/cloud-gcp-03.png b/docs/_static/images/cloud-gcp-03.png deleted file mode 100644 index 9881a5a3..00000000 Binary files a/docs/_static/images/cloud-gcp-03.png and /dev/null differ diff --git a/docs/_static/images/cloud-gcp-04.png b/docs/_static/images/cloud-gcp-04.png deleted file mode 100644 index 61ee2d5e..00000000 Binary files a/docs/_static/images/cloud-gcp-04.png and /dev/null differ diff --git a/docs/_static/images/cloud-gcp-05.png b/docs/_static/images/cloud-gcp-05.png deleted file mode 100644 index acaafc59..00000000 Binary files a/docs/_static/images/cloud-gcp-05.png and /dev/null differ diff --git a/docs/_static/images/dhcp-relay-through-gre-bridge.png b/docs/_static/images/dhcp-relay-through-gre-bridge.png deleted file mode 100644 index 1f3e7744..00000000 Binary files a/docs/_static/images/dhcp-relay-through-gre-bridge.png and /dev/null differ diff --git a/docs/_static/images/dual-hub-DMVPN.png b/docs/_static/images/dual-hub-DMVPN.png deleted file mode 100644 index 51ba9c14..00000000 Binary files a/docs/_static/images/dual-hub-DMVPN.png and /dev/null differ diff --git a/docs/_static/images/eve-ng-vyos.png b/docs/_static/images/eve-ng-vyos.png deleted file mode 100644 index fdd196a7..00000000 Binary files a/docs/_static/images/eve-ng-vyos.png and /dev/null differ diff --git a/docs/_static/images/firewall-and-vrf-blueprints.png b/docs/_static/images/firewall-and-vrf-blueprints.png deleted file mode 100644 index 8c3bf9f2..00000000 Binary files a/docs/_static/images/firewall-and-vrf-blueprints.png and /dev/null differ diff --git a/docs/_static/images/firewall-bridge-forward.png b/docs/_static/images/firewall-bridge-forward.png deleted file mode 100644 index 1294349b..00000000 Binary files a/docs/_static/images/firewall-bridge-forward.png and /dev/null differ diff --git a/docs/_static/images/firewall-bridge-input.png b/docs/_static/images/firewall-bridge-input.png deleted file mode 100644 index 20a46b2e..00000000 Binary files a/docs/_static/images/firewall-bridge-input.png and /dev/null differ diff --git a/docs/_static/images/firewall-bridge-output.png b/docs/_static/images/firewall-bridge-output.png deleted file mode 100644 index ab2fd3d7..00000000 Binary files a/docs/_static/images/firewall-bridge-output.png and /dev/null differ diff --git a/docs/_static/images/firewall-flowtable-packet-flow.png b/docs/_static/images/firewall-flowtable-packet-flow.png deleted file mode 100644 index fca7e13a..00000000 Binary files a/docs/_static/images/firewall-flowtable-packet-flow.png and /dev/null differ diff --git a/docs/_static/images/firewall-fwd-packet-flow.png b/docs/_static/images/firewall-fwd-packet-flow.png deleted file mode 100644 index 1ca213e8..00000000 Binary files a/docs/_static/images/firewall-fwd-packet-flow.png and /dev/null differ diff --git a/docs/_static/images/firewall-gral-packet-flow.png b/docs/_static/images/firewall-gral-packet-flow.png deleted file mode 100644 index 4fb5d516..00000000 Binary files a/docs/_static/images/firewall-gral-packet-flow.png and /dev/null differ diff --git a/docs/_static/images/firewall-input-packet-flow.png b/docs/_static/images/firewall-input-packet-flow.png deleted file mode 100644 index 20d356bd..00000000 Binary files a/docs/_static/images/firewall-input-packet-flow.png and /dev/null differ diff --git a/docs/_static/images/firewall-netfilter.png b/docs/_static/images/firewall-netfilter.png deleted file mode 100644 index dde3766b..00000000 Binary files a/docs/_static/images/firewall-netfilter.png and /dev/null differ diff --git a/docs/_static/images/firewall-traditional.png b/docs/_static/images/firewall-traditional.png deleted file mode 100644 index 7eb2b49d..00000000 Binary files a/docs/_static/images/firewall-traditional.png and /dev/null differ diff --git a/docs/_static/images/firewall-zonebased.png b/docs/_static/images/firewall-zonebased.png deleted file mode 100644 index 46b2f623..00000000 Binary files a/docs/_static/images/firewall-zonebased.png and /dev/null differ diff --git a/docs/_static/images/gns3-01.png b/docs/_static/images/gns3-01.png deleted file mode 100644 index a655d6aa..00000000 Binary files a/docs/_static/images/gns3-01.png and /dev/null differ diff --git a/docs/_static/images/gns3-02.png b/docs/_static/images/gns3-02.png deleted file mode 100644 index 3dffdd2b..00000000 Binary files a/docs/_static/images/gns3-02.png and /dev/null differ diff --git a/docs/_static/images/gns3-03.png b/docs/_static/images/gns3-03.png deleted file mode 100644 index fcab6c5d..00000000 Binary files a/docs/_static/images/gns3-03.png and /dev/null differ diff --git a/docs/_static/images/gns3-04.png b/docs/_static/images/gns3-04.png deleted file mode 100644 index afc30131..00000000 Binary files a/docs/_static/images/gns3-04.png and /dev/null differ diff --git a/docs/_static/images/gns3-05.png b/docs/_static/images/gns3-05.png deleted file mode 100644 index fee0dc65..00000000 Binary files a/docs/_static/images/gns3-05.png and /dev/null differ diff --git a/docs/_static/images/gns3-06.png b/docs/_static/images/gns3-06.png deleted file mode 100644 index c03cd89f..00000000 Binary files a/docs/_static/images/gns3-06.png and /dev/null differ diff --git a/docs/_static/images/gns3-07.png b/docs/_static/images/gns3-07.png deleted file mode 100644 index 89d0a565..00000000 Binary files a/docs/_static/images/gns3-07.png and /dev/null differ diff --git a/docs/_static/images/gns3-08.png b/docs/_static/images/gns3-08.png deleted file mode 100644 index aca0ff8a..00000000 Binary files a/docs/_static/images/gns3-08.png and /dev/null differ diff --git a/docs/_static/images/gns3-09.png b/docs/_static/images/gns3-09.png deleted file mode 100644 index 7ae38c30..00000000 Binary files a/docs/_static/images/gns3-09.png and /dev/null differ diff --git a/docs/_static/images/gns3-10.png b/docs/_static/images/gns3-10.png deleted file mode 100644 index 1ee70d58..00000000 Binary files a/docs/_static/images/gns3-10.png and /dev/null differ diff --git a/docs/_static/images/gns3-11.png b/docs/_static/images/gns3-11.png deleted file mode 100644 index 7990c73a..00000000 Binary files a/docs/_static/images/gns3-11.png and /dev/null differ diff --git a/docs/_static/images/gns3-12.png b/docs/_static/images/gns3-12.png deleted file mode 100644 index 9ad51f70..00000000 Binary files a/docs/_static/images/gns3-12.png and /dev/null differ diff --git a/docs/_static/images/gns3-13.png b/docs/_static/images/gns3-13.png deleted file mode 100644 index 5f9dd783..00000000 Binary files a/docs/_static/images/gns3-13.png and /dev/null differ diff --git a/docs/_static/images/gns3-14.png b/docs/_static/images/gns3-14.png deleted file mode 100644 index 447fcafe..00000000 Binary files a/docs/_static/images/gns3-14.png and /dev/null differ diff --git a/docs/_static/images/gns3-15.png b/docs/_static/images/gns3-15.png deleted file mode 100644 index 956b9edb..00000000 Binary files a/docs/_static/images/gns3-15.png and /dev/null differ diff --git a/docs/_static/images/gns3-16.png b/docs/_static/images/gns3-16.png deleted file mode 100644 index 4f75ffab..00000000 Binary files a/docs/_static/images/gns3-16.png and /dev/null differ diff --git a/docs/_static/images/gns3-17.png b/docs/_static/images/gns3-17.png deleted file mode 100644 index 64eff002..00000000 Binary files a/docs/_static/images/gns3-17.png and /dev/null differ diff --git a/docs/_static/images/gns3-20.png b/docs/_static/images/gns3-20.png deleted file mode 100644 index 17d92dea..00000000 Binary files a/docs/_static/images/gns3-20.png and /dev/null differ diff --git a/docs/_static/images/gns3-21.png b/docs/_static/images/gns3-21.png deleted file mode 100644 index e461016a..00000000 Binary files a/docs/_static/images/gns3-21.png and /dev/null differ diff --git a/docs/_static/images/gns3-215.png b/docs/_static/images/gns3-215.png deleted file mode 100644 index fde268ba..00000000 Binary files a/docs/_static/images/gns3-215.png and /dev/null differ diff --git a/docs/_static/images/gns3-22.png b/docs/_static/images/gns3-22.png deleted file mode 100644 index 6ed52c1d..00000000 Binary files a/docs/_static/images/gns3-22.png and /dev/null differ diff --git a/docs/_static/images/gowin-01.png b/docs/_static/images/gowin-01.png deleted file mode 100644 index 403ce52a..00000000 Binary files a/docs/_static/images/gowin-01.png and /dev/null differ diff --git a/docs/_static/images/gowin-02.png b/docs/_static/images/gowin-02.png deleted file mode 100644 index 413f2948..00000000 Binary files a/docs/_static/images/gowin-02.png and /dev/null differ diff --git a/docs/_static/images/gowin-03.png b/docs/_static/images/gowin-03.png deleted file mode 100644 index fbdbb142..00000000 Binary files a/docs/_static/images/gowin-03.png and /dev/null differ diff --git a/docs/_static/images/gowin-04.png b/docs/_static/images/gowin-04.png deleted file mode 100644 index c68b8731..00000000 Binary files a/docs/_static/images/gowin-04.png and /dev/null differ diff --git a/docs/_static/images/inter-vrf-routing-vrf-lite.png b/docs/_static/images/inter-vrf-routing-vrf-lite.png deleted file mode 100644 index 3acefee6..00000000 Binary files a/docs/_static/images/inter-vrf-routing-vrf-lite.png and /dev/null differ diff --git a/docs/_static/images/ipsec-vyos-pa.png b/docs/_static/images/ipsec-vyos-pa.png deleted file mode 100644 index 0929bcc7..00000000 Binary files a/docs/_static/images/ipsec-vyos-pa.png and /dev/null differ diff --git a/docs/_static/images/json.png b/docs/_static/images/json.png deleted file mode 100644 index 6c884e8e..00000000 Binary files a/docs/_static/images/json.png and /dev/null differ diff --git a/docs/_static/images/key.png b/docs/_static/images/key.png deleted file mode 100644 index 7d9366f4..00000000 Binary files a/docs/_static/images/key.png and /dev/null differ diff --git a/docs/_static/images/keypairs.png b/docs/_static/images/keypairs.png deleted file mode 100644 index 7e772ae9..00000000 Binary files a/docs/_static/images/keypairs.png and /dev/null differ diff --git a/docs/_static/images/lac-lns-diagram.jpg b/docs/_static/images/lac-lns-diagram.jpg deleted file mode 100644 index 4463a3c3..00000000 Binary files a/docs/_static/images/lac-lns-diagram.jpg and /dev/null differ diff --git a/docs/_static/images/lac-lns-winclient.jpg b/docs/_static/images/lac-lns-winclient.jpg deleted file mode 100644 index 9fa99152..00000000 Binary files a/docs/_static/images/lac-lns-winclient.jpg and /dev/null differ diff --git a/docs/_static/images/ldapone.png b/docs/_static/images/ldapone.png deleted file mode 100644 index 33ecf628..00000000 Binary files a/docs/_static/images/ldapone.png and /dev/null differ diff --git a/docs/_static/images/ldaptwo.png b/docs/_static/images/ldaptwo.png deleted file mode 100644 index 7cb9e0cb..00000000 Binary files a/docs/_static/images/ldaptwo.png and /dev/null differ diff --git a/docs/_static/images/mainschema.png b/docs/_static/images/mainschema.png deleted file mode 100644 index c39e5da2..00000000 Binary files a/docs/_static/images/mainschema.png and /dev/null differ diff --git a/docs/_static/images/multicast-basic.png b/docs/_static/images/multicast-basic.png deleted file mode 100644 index 3d4a3de3..00000000 Binary files a/docs/_static/images/multicast-basic.png and /dev/null differ diff --git a/docs/_static/images/nat_before_vpn_topology.png b/docs/_static/images/nat_before_vpn_topology.png deleted file mode 100644 index ae23c92d..00000000 Binary files a/docs/_static/images/nat_before_vpn_topology.png and /dev/null differ diff --git a/docs/_static/images/nmp1.png b/docs/_static/images/nmp1.png deleted file mode 100644 index 0b761a76..00000000 Binary files a/docs/_static/images/nmp1.png and /dev/null differ diff --git a/docs/_static/images/nmp2.png b/docs/_static/images/nmp2.png deleted file mode 100644 index 3190a099..00000000 Binary files a/docs/_static/images/nmp2.png and /dev/null differ diff --git a/docs/_static/images/nmp3.png b/docs/_static/images/nmp3.png deleted file mode 100644 index 0585b80e..00000000 Binary files a/docs/_static/images/nmp3.png and /dev/null differ diff --git a/docs/_static/images/nmp4.png b/docs/_static/images/nmp4.png deleted file mode 100644 index e0aa893e..00000000 Binary files a/docs/_static/images/nmp4.png and /dev/null differ diff --git a/docs/_static/images/nmp5.png b/docs/_static/images/nmp5.png deleted file mode 100644 index d3149034..00000000 Binary files a/docs/_static/images/nmp5.png and /dev/null differ diff --git a/docs/_static/images/nmp6.png b/docs/_static/images/nmp6.png deleted file mode 100644 index c4645e33..00000000 Binary files a/docs/_static/images/nmp6.png and /dev/null differ diff --git a/docs/_static/images/nmp7.png b/docs/_static/images/nmp7.png deleted file mode 100644 index 3e518e7e..00000000 Binary files a/docs/_static/images/nmp7.png and /dev/null differ diff --git a/docs/_static/images/openvpn_site2site_diagram.jpg b/docs/_static/images/openvpn_site2site_diagram.jpg deleted file mode 100644 index 05881e7d..00000000 Binary files a/docs/_static/images/openvpn_site2site_diagram.jpg and /dev/null differ diff --git a/docs/_static/images/pbr_example_1.png b/docs/_static/images/pbr_example_1.png deleted file mode 100644 index 3dff6db6..00000000 Binary files a/docs/_static/images/pbr_example_1.png and /dev/null differ diff --git a/docs/_static/images/policy-based-ipsec-and-firewall.png b/docs/_static/images/policy-based-ipsec-and-firewall.png deleted file mode 100644 index 6e9d43ac..00000000 Binary files a/docs/_static/images/policy-based-ipsec-and-firewall.png and /dev/null differ diff --git a/docs/_static/images/pppoe-ipv6-pd-diagram.jpg b/docs/_static/images/pppoe-ipv6-pd-diagram.jpg deleted file mode 100644 index 430848c8..00000000 Binary files a/docs/_static/images/pppoe-ipv6-pd-diagram.jpg and /dev/null differ diff --git a/docs/_static/images/project.png b/docs/_static/images/project.png deleted file mode 100644 index 6f844c23..00000000 Binary files a/docs/_static/images/project.png and /dev/null differ diff --git a/docs/_static/images/qos1.png b/docs/_static/images/qos1.png deleted file mode 100644 index 9c16e6a3..00000000 Binary files a/docs/_static/images/qos1.png and /dev/null differ diff --git a/docs/_static/images/qos10.png b/docs/_static/images/qos10.png deleted file mode 100644 index 2f90ffe7..00000000 Binary files a/docs/_static/images/qos10.png and /dev/null differ diff --git a/docs/_static/images/qos2.png b/docs/_static/images/qos2.png deleted file mode 100644 index 4d351344..00000000 Binary files a/docs/_static/images/qos2.png and /dev/null differ diff --git a/docs/_static/images/qos3.png b/docs/_static/images/qos3.png deleted file mode 100644 index 97efaeb7..00000000 Binary files a/docs/_static/images/qos3.png and /dev/null differ diff --git a/docs/_static/images/qos4.png b/docs/_static/images/qos4.png deleted file mode 100644 index b87b256e..00000000 Binary files a/docs/_static/images/qos4.png and /dev/null differ diff --git a/docs/_static/images/qos5.png b/docs/_static/images/qos5.png deleted file mode 100644 index 4a615755..00000000 Binary files a/docs/_static/images/qos5.png and /dev/null differ diff --git a/docs/_static/images/qos6.png b/docs/_static/images/qos6.png deleted file mode 100644 index 907d6104..00000000 Binary files a/docs/_static/images/qos6.png and /dev/null differ diff --git a/docs/_static/images/qos7.png b/docs/_static/images/qos7.png deleted file mode 100644 index 03ec5cd1..00000000 Binary files a/docs/_static/images/qos7.png and /dev/null differ diff --git a/docs/_static/images/qos8.png b/docs/_static/images/qos8.png deleted file mode 100644 index 3566ac00..00000000 Binary files a/docs/_static/images/qos8.png and /dev/null differ diff --git a/docs/_static/images/qos9.png b/docs/_static/images/qos9.png deleted file mode 100644 index 67d8afd2..00000000 Binary files a/docs/_static/images/qos9.png and /dev/null differ diff --git a/docs/_static/images/reset-password-step-1.jpg b/docs/_static/images/reset-password-step-1.jpg deleted file mode 100644 index 3b6f7703..00000000 Binary files a/docs/_static/images/reset-password-step-1.jpg and /dev/null differ diff --git a/docs/_static/images/reset-password-step-2.jpg b/docs/_static/images/reset-password-step-2.jpg deleted file mode 100644 index 265bc73b..00000000 Binary files a/docs/_static/images/reset-password-step-2.jpg and /dev/null differ diff --git a/docs/_static/images/reset-password-step-3.jpg b/docs/_static/images/reset-password-step-3.jpg deleted file mode 100644 index 98795757..00000000 Binary files a/docs/_static/images/reset-password-step-3.jpg and /dev/null differ diff --git a/docs/_static/images/reset-password-step-4.jpg b/docs/_static/images/reset-password-step-4.jpg deleted file mode 100644 index 6f70ea24..00000000 Binary files a/docs/_static/images/reset-password-step-4.jpg and /dev/null differ diff --git a/docs/_static/images/reset-password-step-5.jpg b/docs/_static/images/reset-password-step-5.jpg deleted file mode 100644 index 70c586e2..00000000 Binary files a/docs/_static/images/reset-password-step-5.jpg and /dev/null differ diff --git a/docs/_static/images/service.png b/docs/_static/images/service.png deleted file mode 100644 index e2a9bbbc..00000000 Binary files a/docs/_static/images/service.png and /dev/null differ diff --git a/docs/_static/images/service_conntrack_sync-schema.png b/docs/_static/images/service_conntrack_sync-schema.png deleted file mode 100644 index 1b5fe8fb..00000000 Binary files a/docs/_static/images/service_conntrack_sync-schema.png and /dev/null differ diff --git a/docs/_static/images/service_dhcp-relay01.png b/docs/_static/images/service_dhcp-relay01.png deleted file mode 100644 index cd7f30cf..00000000 Binary files a/docs/_static/images/service_dhcp-relay01.png and /dev/null differ diff --git a/docs/_static/images/service_dhcpv6-relay01.png b/docs/_static/images/service_dhcpv6-relay01.png deleted file mode 100644 index 9a10a10f..00000000 Binary files a/docs/_static/images/service_dhcpv6-relay01.png and /dev/null differ diff --git a/docs/_static/images/service_snmp_communication_principles_diagram.png b/docs/_static/images/service_snmp_communication_principles_diagram.png deleted file mode 100644 index eff2ce45..00000000 Binary files a/docs/_static/images/service_snmp_communication_principles_diagram.png and /dev/null differ diff --git a/docs/_static/images/sg.png b/docs/_static/images/sg.png deleted file mode 100644 index 8be51e1f..00000000 Binary files a/docs/_static/images/sg.png and /dev/null differ diff --git a/docs/_static/images/sticky-connections.jpg b/docs/_static/images/sticky-connections.jpg deleted file mode 100644 index 25fd72a9..00000000 Binary files a/docs/_static/images/sticky-connections.jpg and /dev/null differ diff --git a/docs/_static/images/traffic.png b/docs/_static/images/traffic.png deleted file mode 100644 index 74002b16..00000000 Binary files a/docs/_static/images/traffic.png and /dev/null differ diff --git a/docs/_static/images/uefi_secureboot_01.png b/docs/_static/images/uefi_secureboot_01.png deleted file mode 100644 index 02ec56b0..00000000 Binary files a/docs/_static/images/uefi_secureboot_01.png and /dev/null differ diff --git a/docs/_static/images/uefi_secureboot_02.png b/docs/_static/images/uefi_secureboot_02.png deleted file mode 100644 index 336d654d..00000000 Binary files a/docs/_static/images/uefi_secureboot_02.png and /dev/null differ diff --git a/docs/_static/images/uefi_secureboot_03.png b/docs/_static/images/uefi_secureboot_03.png deleted file mode 100644 index ff126842..00000000 Binary files a/docs/_static/images/uefi_secureboot_03.png and /dev/null differ diff --git a/docs/_static/images/uefi_secureboot_04.png b/docs/_static/images/uefi_secureboot_04.png deleted file mode 100644 index 90242299..00000000 Binary files a/docs/_static/images/uefi_secureboot_04.png and /dev/null differ diff --git a/docs/_static/images/uefi_secureboot_05.png b/docs/_static/images/uefi_secureboot_05.png deleted file mode 100644 index b08cb946..00000000 Binary files a/docs/_static/images/uefi_secureboot_05.png and /dev/null differ diff --git a/docs/_static/images/uefi_secureboot_06.png b/docs/_static/images/uefi_secureboot_06.png deleted file mode 100644 index 784f0eed..00000000 Binary files a/docs/_static/images/uefi_secureboot_06.png and /dev/null differ diff --git a/docs/_static/images/uefi_secureboot_07.png b/docs/_static/images/uefi_secureboot_07.png deleted file mode 100644 index 6ff450b4..00000000 Binary files a/docs/_static/images/uefi_secureboot_07.png and /dev/null differ diff --git a/docs/_static/images/virt-libvirt-01.png b/docs/_static/images/virt-libvirt-01.png deleted file mode 100644 index 06baea8e..00000000 Binary files a/docs/_static/images/virt-libvirt-01.png and /dev/null differ diff --git a/docs/_static/images/virt-libvirt-02.png b/docs/_static/images/virt-libvirt-02.png deleted file mode 100644 index b6c4b379..00000000 Binary files a/docs/_static/images/virt-libvirt-02.png and /dev/null differ diff --git a/docs/_static/images/virt-libvirt-03.png b/docs/_static/images/virt-libvirt-03.png deleted file mode 100644 index ac3891f0..00000000 Binary files a/docs/_static/images/virt-libvirt-03.png and /dev/null differ diff --git a/docs/_static/images/virt-libvirt-04.png b/docs/_static/images/virt-libvirt-04.png deleted file mode 100644 index b1218597..00000000 Binary files a/docs/_static/images/virt-libvirt-04.png and /dev/null differ diff --git a/docs/_static/images/virt-libvirt-05.png b/docs/_static/images/virt-libvirt-05.png deleted file mode 100644 index 5579c281..00000000 Binary files a/docs/_static/images/virt-libvirt-05.png and /dev/null differ diff --git a/docs/_static/images/virt-libvirt-06.png b/docs/_static/images/virt-libvirt-06.png deleted file mode 100644 index e0983d23..00000000 Binary files a/docs/_static/images/virt-libvirt-06.png and /dev/null differ diff --git a/docs/_static/images/virt-libvirt-qc-01.png b/docs/_static/images/virt-libvirt-qc-01.png deleted file mode 100644 index 49867bd0..00000000 Binary files a/docs/_static/images/virt-libvirt-qc-01.png and /dev/null differ diff --git a/docs/_static/images/virt-libvirt-qc-02.png b/docs/_static/images/virt-libvirt-qc-02.png deleted file mode 100644 index a71b8f64..00000000 Binary files a/docs/_static/images/virt-libvirt-qc-02.png and /dev/null differ diff --git a/docs/_static/images/virt-libvirt-qc-03.png b/docs/_static/images/virt-libvirt-qc-03.png deleted file mode 100644 index 4eefaa58..00000000 Binary files a/docs/_static/images/virt-libvirt-qc-03.png and /dev/null differ diff --git a/docs/_static/images/vpn_dmvpn_topology01.png b/docs/_static/images/vpn_dmvpn_topology01.png deleted file mode 100644 index 17433be6..00000000 Binary files a/docs/_static/images/vpn_dmvpn_topology01.png and /dev/null differ diff --git a/docs/_static/images/vpn_s2s_ikev2.png b/docs/_static/images/vpn_s2s_ikev2.png deleted file mode 100644 index f8050e3a..00000000 Binary files a/docs/_static/images/vpn_s2s_ikev2.png and /dev/null differ diff --git a/docs/_static/images/vpn_s2s_ikev2_c.png b/docs/_static/images/vpn_s2s_ikev2_c.png deleted file mode 100644 index 2d9e21b5..00000000 Binary files a/docs/_static/images/vpn_s2s_ikev2_c.png and /dev/null differ diff --git a/docs/_static/images/vrf-example-topology-01.png b/docs/_static/images/vrf-example-topology-01.png deleted file mode 100644 index 57357509..00000000 Binary files a/docs/_static/images/vrf-example-topology-01.png and /dev/null differ diff --git a/docs/_static/images/vyos-downloads.png b/docs/_static/images/vyos-downloads.png deleted file mode 100644 index 6bad2b19..00000000 Binary files a/docs/_static/images/vyos-downloads.png and /dev/null differ diff --git a/docs/_static/images/vyos-sr-isis.png b/docs/_static/images/vyos-sr-isis.png deleted file mode 100644 index 62430919..00000000 Binary files a/docs/_static/images/vyos-sr-isis.png and /dev/null differ diff --git a/docs/_static/images/vyos_1_4_nat66_simple.png b/docs/_static/images/vyos_1_4_nat66_simple.png deleted file mode 100644 index d7c54115..00000000 Binary files a/docs/_static/images/vyos_1_4_nat66_simple.png and /dev/null differ diff --git a/docs/_static/images/vyos_1_5_nat66_dhcpv6_wdummy.png b/docs/_static/images/vyos_1_5_nat66_dhcpv6_wdummy.png deleted file mode 100644 index 297fdd11..00000000 Binary files a/docs/_static/images/vyos_1_5_nat66_dhcpv6_wdummy.png and /dev/null differ diff --git a/docs/_static/images/vyos_arista_bond_lacp.png b/docs/_static/images/vyos_arista_bond_lacp.png deleted file mode 100644 index 6c9ef8ec..00000000 Binary files a/docs/_static/images/vyos_arista_bond_lacp.png and /dev/null differ diff --git a/docs/_static/images/vyosnew-downloads.png b/docs/_static/images/vyosnew-downloads.png deleted file mode 100644 index 294a4589..00000000 Binary files a/docs/_static/images/vyosnew-downloads.png and /dev/null differ diff --git a/docs/_static/images/wireguard_qrcode.jpg b/docs/_static/images/wireguard_qrcode.jpg deleted file mode 100644 index 0a9a98c0..00000000 Binary files a/docs/_static/images/wireguard_qrcode.jpg and /dev/null differ diff --git a/docs/_static/images/wireguard_site2site_diagram.jpg b/docs/_static/images/wireguard_site2site_diagram.jpg deleted file mode 100644 index 4a7a95e4..00000000 Binary files a/docs/_static/images/wireguard_site2site_diagram.jpg and /dev/null differ diff --git a/docs/_static/images/zone-policy-diagram.png b/docs/_static/images/zone-policy-diagram.png deleted file mode 100644 index cfde4af6..00000000 Binary files a/docs/_static/images/zone-policy-diagram.png and /dev/null differ -- cgit v1.2.3 From dfea790b36ddab4c6661436c8eed3cea7af5bd3a Mon Sep 17 00:00:00 2001 From: Daniil Baturin Date: Wed, 6 May 2026 14:08:24 +0100 Subject: Revert "Add incremental RST-to-MyST swap mechanism (#1857)" (#1892) This reverts commit 4b36114e053ee11d0cb264a1e4cfe4692d78f194. --- .readthedocs.yml | 5 - docs/Makefile | 42 +- docs/_ext/vyos.py | 14 +- docs/_static/images/1u_vyos_back.jpg | Bin 0 -> 586620 bytes docs/_static/images/1u_vyos_front.jpg | Bin 0 -> 363840 bytes docs/_static/images/1u_vyos_front_10ge_open_1.jpg | Bin 0 -> 1853769 bytes docs/_static/images/1u_vyos_front_10ge_open_2.jpg | Bin 0 -> 2294504 bytes docs/_static/images/1u_vyos_front_10ge_open_3.jpg | Bin 0 -> 2067314 bytes docs/_static/images/1u_vyos_front_10ge_open_4.jpg | Bin 0 -> 2447196 bytes docs/_static/images/1u_vyos_front_open_1.jpg | Bin 0 -> 956435 bytes docs/_static/images/1u_vyos_front_open_2.jpg | Bin 0 -> 1225208 bytes docs/_static/images/1u_vyos_front_open_3.jpg | Bin 0 -> 1337822 bytes .../images/480px-Acrosser_ANDJ190N1_Back.jpg | Bin 0 -> 11340 bytes .../images/480px-Acrosser_ANDJ190N1_Front.jpg | Bin 0 -> 11138 bytes docs/_static/images/600px-Partaker-i5.jpg | Bin 0 -> 31015 bytes docs/_static/images/ESP_AH.png | Bin 0 -> 35607 bytes .../_static/images/IPSec_close_action_settings.png | Bin 0 -> 22371 bytes docs/_static/images/L3VPN_hub_and_spoke.png | Bin 0 -> 134458 bytes docs/_static/images/PA-ESP-group.png | Bin 0 -> 27516 bytes docs/_static/images/PA-IKE-GW-1.png | Bin 0 -> 31121 bytes docs/_static/images/PA-IKE-GW-2.png | Bin 0 -> 19848 bytes docs/_static/images/PA-IKE-group.png | Bin 0 -> 26998 bytes docs/_static/images/PA-IPsec-tunnel.png | Bin 0 -> 33519 bytes docs/_static/images/PA-tunnel-1.png | Bin 0 -> 16308 bytes docs/_static/images/PA-tunnel-2.png | Bin 0 -> 18290 bytes docs/_static/images/PA-tunnel-3.png | Bin 0 -> 15779 bytes docs/_static/images/VyOS_Dual-Hub_DMVPN.png | Bin 0 -> 67747 bytes docs/_static/images/Wan_load_balancing1.png | Bin 0 -> 373848 bytes .../_static/images/Wan_load_balancing_exclude1.png | Bin 0 -> 382563 bytes docs/_static/images/ansible.png | Bin 0 -> 204124 bytes docs/_static/images/apu4_desk_1.jpg | Bin 0 -> 816206 bytes docs/_static/images/apu4_desk_2.jpg | Bin 0 -> 288989 bytes docs/_static/images/apu4_desk_3.jpg | Bin 0 -> 831843 bytes docs/_static/images/apu4_desk_4.jpg | Bin 0 -> 804070 bytes docs/_static/images/apu4_rack_1.jpg | Bin 0 -> 305789 bytes docs/_static/images/apu4_rack_2.jpg | Bin 0 -> 623490 bytes docs/_static/images/apu4_rack_3.jpg | Bin 0 -> 1113842 bytes docs/_static/images/apu4_rack_4.jpg | Bin 0 -> 1676612 bytes docs/_static/images/apu4_rack_5.jpg | Bin 0 -> 1584027 bytes docs/_static/images/apu4_rack_vyos_print.jpg | Bin 0 -> 569311 bytes docs/_static/images/aws.png | Bin 0 -> 150759 bytes docs/_static/images/blueprint-dmvpn.png | Bin 0 -> 29626 bytes docs/_static/images/boot-options.png | Bin 0 -> 30582 bytes docs/_static/images/cisco-vpn-ipsec.png | Bin 0 -> 38659 bytes docs/_static/images/cloud-aws-01.png | Bin 0 -> 54783 bytes docs/_static/images/cloud-aws-02.png | Bin 0 -> 88657 bytes docs/_static/images/cloud-aws-03.png | Bin 0 -> 48191 bytes docs/_static/images/cloud-aws-04.png | Bin 0 -> 131948 bytes docs/_static/images/cloud-aws-05.png | Bin 0 -> 103661 bytes docs/_static/images/cloud-aws-06.png | Bin 0 -> 111207 bytes docs/_static/images/cloud-aws-07.png | Bin 0 -> 72764 bytes docs/_static/images/cloud-aws-08.png | Bin 0 -> 20893 bytes docs/_static/images/cloud-azure-01.png | Bin 0 -> 90521 bytes docs/_static/images/cloud-azure-02.png | Bin 0 -> 56507 bytes docs/_static/images/cloud-azure-03.png | Bin 0 -> 47364 bytes docs/_static/images/cloud-azure-04.png | Bin 0 -> 87475 bytes docs/_static/images/cloud-azure-05.png | Bin 0 -> 77301 bytes docs/_static/images/cloud-azure-06.png | Bin 0 -> 57830 bytes docs/_static/images/cloud-gcp-01.png | Bin 0 -> 5526 bytes docs/_static/images/cloud-gcp-02.png | Bin 0 -> 46685 bytes docs/_static/images/cloud-gcp-03.png | Bin 0 -> 106217 bytes docs/_static/images/cloud-gcp-04.png | Bin 0 -> 19727 bytes docs/_static/images/cloud-gcp-05.png | Bin 0 -> 26049 bytes .../images/dhcp-relay-through-gre-bridge.png | Bin 0 -> 31261 bytes docs/_static/images/dual-hub-DMVPN.png | Bin 0 -> 88497 bytes docs/_static/images/eve-ng-vyos.png | Bin 0 -> 4228 bytes .../_static/images/firewall-and-vrf-blueprints.png | Bin 0 -> 84270 bytes docs/_static/images/firewall-bridge-forward.png | Bin 0 -> 26359 bytes docs/_static/images/firewall-bridge-input.png | Bin 0 -> 39158 bytes docs/_static/images/firewall-bridge-output.png | Bin 0 -> 34496 bytes .../images/firewall-flowtable-packet-flow.png | Bin 0 -> 47883 bytes docs/_static/images/firewall-fwd-packet-flow.png | Bin 0 -> 30593 bytes docs/_static/images/firewall-gral-packet-flow.png | Bin 0 -> 49632 bytes docs/_static/images/firewall-input-packet-flow.png | Bin 0 -> 43944 bytes docs/_static/images/firewall-netfilter.png | Bin 0 -> 73608 bytes docs/_static/images/firewall-traditional.png | Bin 0 -> 53437 bytes docs/_static/images/firewall-zonebased.png | Bin 0 -> 55621 bytes docs/_static/images/gns3-01.png | Bin 0 -> 28912 bytes docs/_static/images/gns3-02.png | Bin 0 -> 179730 bytes docs/_static/images/gns3-03.png | Bin 0 -> 22829 bytes docs/_static/images/gns3-04.png | Bin 0 -> 35150 bytes docs/_static/images/gns3-05.png | Bin 0 -> 31728 bytes docs/_static/images/gns3-06.png | Bin 0 -> 29168 bytes docs/_static/images/gns3-07.png | Bin 0 -> 31199 bytes docs/_static/images/gns3-08.png | Bin 0 -> 29636 bytes docs/_static/images/gns3-09.png | Bin 0 -> 21881 bytes docs/_static/images/gns3-10.png | Bin 0 -> 30788 bytes docs/_static/images/gns3-11.png | Bin 0 -> 168937 bytes docs/_static/images/gns3-12.png | Bin 0 -> 58597 bytes docs/_static/images/gns3-13.png | Bin 0 -> 56994 bytes docs/_static/images/gns3-14.png | Bin 0 -> 28821 bytes docs/_static/images/gns3-15.png | Bin 0 -> 45453 bytes docs/_static/images/gns3-16.png | Bin 0 -> 54790 bytes docs/_static/images/gns3-17.png | Bin 0 -> 169380 bytes docs/_static/images/gns3-20.png | Bin 0 -> 55168 bytes docs/_static/images/gns3-21.png | Bin 0 -> 25663 bytes docs/_static/images/gns3-215.png | Bin 0 -> 44485 bytes docs/_static/images/gns3-22.png | Bin 0 -> 54674 bytes docs/_static/images/gowin-01.png | Bin 0 -> 355723 bytes docs/_static/images/gowin-02.png | Bin 0 -> 2613833 bytes docs/_static/images/gowin-03.png | Bin 0 -> 2268530 bytes docs/_static/images/gowin-04.png | Bin 0 -> 2165023 bytes docs/_static/images/inter-vrf-routing-vrf-lite.png | Bin 0 -> 104622 bytes docs/_static/images/ipsec-vyos-pa.png | Bin 0 -> 61250 bytes docs/_static/images/json.png | Bin 0 -> 26585 bytes docs/_static/images/key.png | Bin 0 -> 165894 bytes docs/_static/images/keypairs.png | Bin 0 -> 49718 bytes docs/_static/images/lac-lns-diagram.jpg | Bin 0 -> 35665 bytes docs/_static/images/lac-lns-winclient.jpg | Bin 0 -> 90842 bytes docs/_static/images/ldapone.png | Bin 0 -> 88753 bytes docs/_static/images/ldaptwo.png | Bin 0 -> 58322 bytes docs/_static/images/mainschema.png | Bin 0 -> 78790 bytes docs/_static/images/multicast-basic.png | Bin 0 -> 43708 bytes docs/_static/images/nat_before_vpn_topology.png | Bin 0 -> 19015 bytes docs/_static/images/nmp1.png | Bin 0 -> 128546 bytes docs/_static/images/nmp2.png | Bin 0 -> 52507 bytes docs/_static/images/nmp3.png | Bin 0 -> 107595 bytes docs/_static/images/nmp4.png | Bin 0 -> 72678 bytes docs/_static/images/nmp5.png | Bin 0 -> 115299 bytes docs/_static/images/nmp6.png | Bin 0 -> 130524 bytes docs/_static/images/nmp7.png | Bin 0 -> 100135 bytes docs/_static/images/openvpn_site2site_diagram.jpg | Bin 0 -> 24179 bytes docs/_static/images/pbr_example_1.png | Bin 0 -> 39170 bytes .../images/policy-based-ipsec-and-firewall.png | Bin 0 -> 42987 bytes docs/_static/images/pppoe-ipv6-pd-diagram.jpg | Bin 0 -> 19993 bytes docs/_static/images/project.png | Bin 0 -> 18173 bytes docs/_static/images/qos1.png | Bin 0 -> 135527 bytes docs/_static/images/qos10.png | Bin 0 -> 119669 bytes docs/_static/images/qos2.png | Bin 0 -> 140834 bytes docs/_static/images/qos3.png | Bin 0 -> 16699 bytes docs/_static/images/qos4.png | Bin 0 -> 17273 bytes docs/_static/images/qos5.png | Bin 0 -> 15868 bytes docs/_static/images/qos6.png | Bin 0 -> 139244 bytes docs/_static/images/qos7.png | Bin 0 -> 17775 bytes docs/_static/images/qos8.png | Bin 0 -> 17368 bytes docs/_static/images/qos9.png | Bin 0 -> 17065 bytes docs/_static/images/reset-password-step-1.jpg | Bin 0 -> 37351 bytes docs/_static/images/reset-password-step-2.jpg | Bin 0 -> 42278 bytes docs/_static/images/reset-password-step-3.jpg | Bin 0 -> 36932 bytes docs/_static/images/reset-password-step-4.jpg | Bin 0 -> 31564 bytes docs/_static/images/reset-password-step-5.jpg | Bin 0 -> 100973 bytes docs/_static/images/service.png | Bin 0 -> 195145 bytes .../images/service_conntrack_sync-schema.png | Bin 0 -> 56954 bytes docs/_static/images/service_dhcp-relay01.png | Bin 0 -> 153617 bytes docs/_static/images/service_dhcpv6-relay01.png | Bin 0 -> 150157 bytes ...rvice_snmp_communication_principles_diagram.png | Bin 0 -> 56582 bytes docs/_static/images/sg.png | Bin 0 -> 31817 bytes docs/_static/images/sticky-connections.jpg | Bin 0 -> 22252 bytes docs/_static/images/traffic.png | Bin 0 -> 36786 bytes docs/_static/images/uefi_secureboot_01.png | Bin 0 -> 60527 bytes docs/_static/images/uefi_secureboot_02.png | Bin 0 -> 14091 bytes docs/_static/images/uefi_secureboot_03.png | Bin 0 -> 14760 bytes docs/_static/images/uefi_secureboot_04.png | Bin 0 -> 7349 bytes docs/_static/images/uefi_secureboot_05.png | Bin 0 -> 6636 bytes docs/_static/images/uefi_secureboot_06.png | Bin 0 -> 7102 bytes docs/_static/images/uefi_secureboot_07.png | Bin 0 -> 12622 bytes docs/_static/images/virt-libvirt-01.png | Bin 0 -> 33227 bytes docs/_static/images/virt-libvirt-02.png | Bin 0 -> 30981 bytes docs/_static/images/virt-libvirt-03.png | Bin 0 -> 24547 bytes docs/_static/images/virt-libvirt-04.png | Bin 0 -> 28896 bytes docs/_static/images/virt-libvirt-05.png | Bin 0 -> 38080 bytes docs/_static/images/virt-libvirt-06.png | Bin 0 -> 28784 bytes docs/_static/images/virt-libvirt-qc-01.png | Bin 0 -> 33468 bytes docs/_static/images/virt-libvirt-qc-02.png | Bin 0 -> 26749 bytes docs/_static/images/virt-libvirt-qc-03.png | Bin 0 -> 28278 bytes docs/_static/images/vpn_dmvpn_topology01.png | Bin 0 -> 94382 bytes docs/_static/images/vpn_s2s_ikev2.png | Bin 0 -> 66279 bytes docs/_static/images/vpn_s2s_ikev2_c.png | Bin 0 -> 69496 bytes docs/_static/images/vrf-example-topology-01.png | Bin 0 -> 32567 bytes docs/_static/images/vyos-downloads.png | Bin 0 -> 65202 bytes docs/_static/images/vyos-sr-isis.png | Bin 0 -> 45339 bytes docs/_static/images/vyos_1_4_nat66_simple.png | Bin 0 -> 21021 bytes .../images/vyos_1_5_nat66_dhcpv6_wdummy.png | Bin 0 -> 349078 bytes docs/_static/images/vyos_arista_bond_lacp.png | Bin 0 -> 40622 bytes docs/_static/images/vyosnew-downloads.png | Bin 0 -> 64419 bytes docs/_static/images/wireguard_qrcode.jpg | Bin 0 -> 133939 bytes .../_static/images/wireguard_site2site_diagram.jpg | Bin 0 -> 19987 bytes docs/_static/images/zone-policy-diagram.png | Bin 0 -> 113618 bytes docs/_swap.txt | 262 ---- docs/automation/md-cloud-init.md | 378 ----- docs/automation/md-command-scripting.md | 225 --- docs/automation/md-index.md | 16 - docs/automation/md-vyos-ansible.md | 101 -- docs/automation/md-vyos-api.md | 587 -------- docs/automation/md-vyos-govyos.md | 197 --- docs/automation/md-vyos-napalm.md | 152 -- docs/automation/md-vyos-netmiko.md | 76 - docs/automation/md-vyos-pyvyos.md | 149 -- docs/automation/md-vyos-salt.md | 211 --- docs/automation/terraform/md-index.md | 29 - docs/automation/terraform/md-terraformAWS.md | 548 ------- docs/automation/terraform/md-terraformAZ.md | 501 ------- docs/automation/terraform/md-terraformGoogle.md | 703 --------- docs/automation/terraform/md-terraformvSphere.md | 388 ----- docs/automation/terraform/terraformvyos.md | 44 - docs/conf.py | 29 +- .../DHCPRelay_through_GRE/_include/topology.png | Bin 0 -> 57080 bytes .../md-DHCPRelay_through_GRE.md | 89 -- .../autotest/L3VPN_EVPN/_include/topology.png | Bin 0 -> 102832 bytes .../autotest/L3VPN_EVPN/md-L3VPN_EVPN.md | 246 --- .../OpenVPN_with_LDAP/_include/topology.png | Bin 0 -> 40891 bytes .../OpenVPN_with_LDAP/md-OpenVPN_with_LDAP.md | 238 --- .../autotest/Wireguard/_include/topology.png | Bin 0 -> 158227 bytes .../autotest/Wireguard/md-Wireguard.md | 108 -- .../autotest/tunnelbroker/_include/topology.png | Bin 0 -> 34614 bytes .../autotest/tunnelbroker/md-tunnelbroker.md | 206 --- docs/configexamples/md-ansible.md | 212 --- docs/configexamples/md-azure-vpn-bgp.md | 134 -- docs/configexamples/md-azure-vpn-dual-bgp.md | 160 -- docs/configexamples/md-bgp-ipv6-unnumbered.md | 174 --- docs/configexamples/md-dmvpn-dualhub-dualcloud.md | 552 ------- docs/configexamples/md-firewall.md | 16 - docs/configexamples/md-fwall-and-bridge.md | 490 ------ docs/configexamples/md-fwall-and-vrf.md | 121 -- docs/configexamples/md-ha.md | 556 ------- docs/configexamples/md-index.md | 60 - .../md-inter-vrf-routing-vrf-lite.md | 797 ---------- docs/configexamples/md-ipsec-cisco-policy-based.md | 363 ----- docs/configexamples/md-ipsec-cisco-route-based.md | 406 ----- docs/configexamples/md-ipsec-pa-route-based.md | 412 ----- docs/configexamples/md-l3vpn-hub-and-spoke.md | 1091 -------------- docs/configexamples/md-lac-lns.md | 181 --- docs/configexamples/md-nmp.md | 76 - docs/configexamples/md-ospf-unnumbered.md | 118 -- .../md-policy-based-ipsec-and-firewall.md | 269 ---- docs/configexamples/md-pppoe-ipv6-basic.md | 114 -- docs/configexamples/md-qos.md | 201 --- docs/configexamples/md-segment-routing-isis.md | 277 ---- docs/configexamples/md-site-2-site-cisco.md | 170 --- docs/configexamples/md-wan-load-balancing.md | 183 --- docs/configexamples/md-zone-policy.md | 417 ------ docs/configuration/container/md-index.md | 479 ------ docs/configuration/firewall/md-bridge.md | 685 --------- docs/configuration/firewall/md-flowtables.md | 176 --- docs/configuration/firewall/md-global-options.md | 186 --- docs/configuration/firewall/md-groups.md | 477 ------ docs/configuration/firewall/md-index.md | 278 ---- docs/configuration/firewall/md-ipv4.md | 1517 ------------------- docs/configuration/firewall/md-ipv6.md | 1567 -------------------- docs/configuration/firewall/md-zone.md | 201 --- docs/configuration/highavailability/md-index.md | 561 ------- docs/configuration/interfaces/md-bonding.md | 764 ---------- docs/configuration/interfaces/md-bridge.md | 431 ------ docs/configuration/interfaces/md-dummy.md | 87 -- docs/configuration/interfaces/md-ethernet.md | 515 ------- docs/configuration/interfaces/md-geneve.md | 105 -- docs/configuration/interfaces/md-index.md | 26 - docs/configuration/interfaces/md-l2tpv3.md | 170 --- docs/configuration/interfaces/md-loopback.md | 67 - docs/configuration/interfaces/md-macsec.md | 319 ---- .../interfaces/md-openvpn-examples.md | 769 ---------- docs/configuration/interfaces/md-openvpn.md | 614 -------- docs/configuration/interfaces/md-pppoe.md | 419 ------ .../configuration/interfaces/md-pseudo-ethernet.md | 52 - docs/configuration/interfaces/md-sstp-client.md | 170 --- docs/configuration/interfaces/md-tunnel.md | 309 ---- .../interfaces/md-virtual-ethernet.md | 119 -- docs/configuration/interfaces/md-vti.md | 121 -- docs/configuration/interfaces/md-vxlan.md | 373 ----- docs/configuration/interfaces/md-wireguard.md | 434 ------ docs/configuration/interfaces/md-wireless.md | 923 ------------ docs/configuration/interfaces/md-wwan.md | 355 ----- docs/configuration/loadbalancing/md-haproxy.md | 510 ------- docs/configuration/loadbalancing/md-index.md | 15 - docs/configuration/loadbalancing/md-wan.md | 306 ---- docs/configuration/md-index.md | 23 - docs/configuration/nat/md-cgnat.md | 200 --- docs/configuration/nat/md-index.md | 13 - docs/configuration/nat/md-nat44.md | 788 ---------- docs/configuration/nat/md-nat64.md | 73 - docs/configuration/nat/md-nat66.md | 243 --- docs/configuration/pki/md-index.md | 583 -------- docs/configuration/policy/md-access-list.md | 70 - docs/configuration/policy/md-as-path-list.md | 29 - docs/configuration/policy/md-community-list.md | 29 - docs/configuration/policy/md-examples.md | 205 --- docs/configuration/policy/md-extcommunity-list.md | 33 - docs/configuration/policy/md-index.md | 53 - .../policy/md-large-community-list.md | 29 - docs/configuration/policy/md-local-route.md | 100 -- docs/configuration/policy/md-prefix-list.md | 152 -- docs/configuration/policy/md-route-map.md | 439 ------ docs/configuration/policy/md-route.md | 424 ------ docs/configuration/protocols/md-arp.md | 72 - docs/configuration/protocols/md-babel.md | 296 ---- docs/configuration/protocols/md-bfd.md | 205 --- docs/configuration/protocols/md-bgp.md | 1414 ------------------ docs/configuration/protocols/md-failover.md | 237 --- docs/configuration/protocols/md-igmp-proxy.md | 79 - docs/configuration/protocols/md-index.md | 25 - docs/configuration/protocols/md-isis.md | 746 ---------- docs/configuration/protocols/md-mpls.md | 285 ---- docs/configuration/protocols/md-multicast.md | 31 - docs/configuration/protocols/md-openfabric.md | 242 --- docs/configuration/protocols/md-ospf.md | 1504 ------------------- docs/configuration/protocols/md-pim.md | 282 ---- docs/configuration/protocols/md-pim6.md | 100 -- docs/configuration/protocols/md-rip.md | 294 ---- docs/configuration/protocols/md-rpki.md | 210 --- docs/configuration/protocols/md-segment-routing.md | 359 ----- docs/configuration/protocols/md-static.md | 298 ---- .../protocols/md-traffic-engineering.md | 54 - docs/configuration/service/md-broadcast-relay.md | 70 - docs/configuration/service/md-config-sync.md | 164 -- docs/configuration/service/md-conntrack-sync.md | 321 ---- docs/configuration/service/md-console-server.md | 139 -- docs/configuration/service/md-dhcp-relay.md | 205 --- docs/configuration/service/md-dhcp-server.md | 1178 --------------- docs/configuration/service/md-dns.md | 582 -------- docs/configuration/service/md-eventhandler.md | 130 -- docs/configuration/service/md-https.md | 138 -- docs/configuration/service/md-index.md | 29 - docs/configuration/service/md-ipoe-server.md | 512 ------- docs/configuration/service/md-lldp.md | 154 -- docs/configuration/service/md-mdns.md | 131 -- docs/configuration/service/md-monitoring.md | 334 ----- docs/configuration/service/md-ntp.md | 202 --- docs/configuration/service/md-pppoe-server.md | 753 ---------- docs/configuration/service/md-router-advert.md | 121 -- docs/configuration/service/md-salt-minion.md | 51 - docs/configuration/service/md-snmp.md | 258 ---- docs/configuration/service/md-ssh.md | 366 ----- docs/configuration/service/md-suricata.md | 93 -- docs/configuration/service/md-tftp-server.md | 78 - docs/configuration/service/md-webproxy.md | 459 ------ docs/configuration/system/md-acceleration.md | 158 -- docs/configuration/system/md-conntrack.md | 218 --- docs/configuration/system/md-console.md | 59 - docs/configuration/system/md-default-route.md | 40 - docs/configuration/system/md-flow-accounting.md | 209 --- docs/configuration/system/md-frr.md | 45 - docs/configuration/system/md-host-name.md | 70 - docs/configuration/system/md-index.md | 34 - docs/configuration/system/md-ip.md | 126 -- docs/configuration/system/md-ipv6.md | 193 --- docs/configuration/system/md-lcd.md | 41 - docs/configuration/system/md-login.md | 604 -------- docs/configuration/system/md-name-server.md | 65 - docs/configuration/system/md-option.md | 190 --- docs/configuration/system/md-proxy.md | 27 - docs/configuration/system/md-sflow.md | 66 - docs/configuration/system/md-sysctl.md | 16 - docs/configuration/system/md-syslog.md | 450 ------ docs/configuration/system/md-task-scheduler.md | 45 - docs/configuration/system/md-time-zone.md | 17 - docs/configuration/system/md-updates.md | 36 - docs/configuration/system/md-watchdog.md | 212 --- docs/configuration/trafficpolicy/md-index.md | 1299 ---------------- docs/configuration/vpn/ipsec/md-index.md | 11 - docs/configuration/vpn/ipsec/md-ipsec_general.md | 407 ----- .../vpn/ipsec/md-remoteaccess_ipsec.md | 186 --- docs/configuration/vpn/ipsec/md-site2site_ipsec.md | 780 ---------- .../vpn/ipsec/md-troubleshooting_ipsec.md | 313 ---- docs/configuration/vpn/md-dmvpn.md | 431 ------ docs/configuration/vpn/md-index.md | 14 - docs/configuration/vpn/md-l2tp.md | 624 -------- docs/configuration/vpn/md-openconnect.md | 330 ----- docs/configuration/vpn/md-pptp.md | 594 -------- docs/configuration/vpn/md-rsa-keys.md | 114 -- docs/configuration/vpn/md-sstp.md | 698 --------- docs/configuration/vrf/md-index.md | 646 -------- docs/contributing/md-build-vyos.md | 730 --------- docs/contributing/md-cla.md | 45 - docs/contributing/md-debugging.md | 204 --- docs/contributing/md-development.md | 549 ------- docs/contributing/md-index.md | 13 - docs/contributing/md-issues-features.md | 122 -- docs/contributing/md-testing.md | 207 --- docs/contributing/md-upstream-packages.md | 147 -- docs/installation/cloud/md-aws.md | 188 --- docs/installation/cloud/md-azure.md | 98 -- docs/installation/cloud/md-gcp.md | 61 - docs/installation/cloud/md-index.md | 10 - docs/installation/cloud/md-oracle.md | 17 - docs/installation/md-bare-metal.md | 626 -------- docs/installation/md-image.md | 113 -- docs/installation/md-index.md | 30 - docs/installation/md-install.md | 466 ------ docs/installation/md-secure-boot.md | 194 --- docs/installation/md-update.md | 105 -- docs/installation/virtual/md-docker.md | 72 - docs/installation/virtual/md-eve-ng.md | 14 - docs/installation/virtual/md-gns3.md | 191 --- docs/installation/virtual/md-index.md | 16 - docs/installation/virtual/md-libvirt.md | 186 --- docs/installation/virtual/md-proxmox.md | 80 - docs/installation/virtual/md-vmware.md | 38 - docs/introducing/md-about.md | 21 - docs/introducing/md-history.md | 171 --- docs/md-404.md | 13 - docs/md-cli.md | 868 ----------- docs/md-coverage.md | 59 - docs/md-documentation.md | 442 ------ docs/md-index.md | 113 -- docs/md-quick-start.md | 381 ----- docs/operation/md-boot-options.md | 55 - docs/operation/md-index.md | 12 - docs/operation/md-information.md | 106 -- docs/operation/md-password-recovery.md | 46 - docs/operation/md-raid.md | 236 --- docs/operation/md-upgrade-recovery.md | 70 - docs/troubleshooting/md-connectivity.md | 147 -- docs/troubleshooting/md-index.md | 17 - docs/troubleshooting/md-interfaces.md | 36 - docs/troubleshooting/md-monitoring.md | 152 -- docs/troubleshooting/md-system.md | 48 - docs/troubleshooting/md-terminal.md | 39 - docs/vpp/configuration/dataplane/md-buffers.md | 102 -- docs/vpp/configuration/dataplane/md-cpu.md | 71 - docs/vpp/configuration/dataplane/md-index.md | 36 - docs/vpp/configuration/dataplane/md-interface.md | 104 -- docs/vpp/configuration/dataplane/md-ipsec.md | 74 - docs/vpp/configuration/dataplane/md-ipv6.md | 46 - docs/vpp/configuration/dataplane/md-l2learn.md | 35 - docs/vpp/configuration/dataplane/md-lcp.md | 46 - docs/vpp/configuration/dataplane/md-logging.md | 59 - docs/vpp/configuration/dataplane/md-memory.md | 142 -- docs/vpp/configuration/dataplane/md-system.md | 212 --- docs/vpp/configuration/dataplane/md-unix.md | 57 - docs/vpp/configuration/dataplane/system.rst | 1 - docs/vpp/configuration/interfaces/md-bonding.md | 255 ---- docs/vpp/configuration/interfaces/md-bridge.md | 194 --- docs/vpp/configuration/interfaces/md-gre.md | 168 --- docs/vpp/configuration/interfaces/md-index.md | 49 - docs/vpp/configuration/interfaces/md-ipip.md | 119 -- docs/vpp/configuration/interfaces/md-loopback.md | 148 -- docs/vpp/configuration/interfaces/md-vxlan.md | 157 -- docs/vpp/configuration/interfaces/md-xconnect.md | 108 -- docs/vpp/configuration/md-acl.md | 582 -------- docs/vpp/configuration/md-index.md | 47 - docs/vpp/configuration/md-ipfix.md | 50 - docs/vpp/configuration/md-ipsec.md | 188 --- docs/vpp/configuration/md-sflow.md | 62 - docs/vpp/configuration/nat/md-cgnat.md | 249 ---- docs/vpp/configuration/nat/md-index.md | 41 - docs/vpp/configuration/nat/md-nat44.md | 755 ---------- docs/vpp/md-description.md | 87 -- docs/vpp/md-index.md | 25 - docs/vpp/md-limitations.md | 42 - docs/vpp/md-requirements.md | 131 -- docs/vpp/md-troubleshooting.md | 474 ------ scripts/import_myst.py | 270 ---- scripts/swap_sources.py | 327 ---- tests/test_import_myst.py | 101 -- tests/test_swap_sources.py | 238 --- 445 files changed, 13 insertions(+), 66642 deletions(-) create mode 100644 docs/_static/images/1u_vyos_back.jpg create mode 100644 docs/_static/images/1u_vyos_front.jpg create mode 100644 docs/_static/images/1u_vyos_front_10ge_open_1.jpg create mode 100644 docs/_static/images/1u_vyos_front_10ge_open_2.jpg create mode 100644 docs/_static/images/1u_vyos_front_10ge_open_3.jpg create mode 100644 docs/_static/images/1u_vyos_front_10ge_open_4.jpg create mode 100644 docs/_static/images/1u_vyos_front_open_1.jpg create mode 100644 docs/_static/images/1u_vyos_front_open_2.jpg create mode 100644 docs/_static/images/1u_vyos_front_open_3.jpg create mode 100644 docs/_static/images/480px-Acrosser_ANDJ190N1_Back.jpg create mode 100644 docs/_static/images/480px-Acrosser_ANDJ190N1_Front.jpg create mode 100644 docs/_static/images/600px-Partaker-i5.jpg create mode 100644 docs/_static/images/ESP_AH.png create mode 100644 docs/_static/images/IPSec_close_action_settings.png create mode 100644 docs/_static/images/L3VPN_hub_and_spoke.png create mode 100644 docs/_static/images/PA-ESP-group.png create mode 100644 docs/_static/images/PA-IKE-GW-1.png create mode 100644 docs/_static/images/PA-IKE-GW-2.png create mode 100644 docs/_static/images/PA-IKE-group.png create mode 100644 docs/_static/images/PA-IPsec-tunnel.png create mode 100644 docs/_static/images/PA-tunnel-1.png create mode 100644 docs/_static/images/PA-tunnel-2.png create mode 100644 docs/_static/images/PA-tunnel-3.png create mode 100644 docs/_static/images/VyOS_Dual-Hub_DMVPN.png create mode 100644 docs/_static/images/Wan_load_balancing1.png create mode 100644 docs/_static/images/Wan_load_balancing_exclude1.png create mode 100644 docs/_static/images/ansible.png create mode 100644 docs/_static/images/apu4_desk_1.jpg create mode 100644 docs/_static/images/apu4_desk_2.jpg create mode 100644 docs/_static/images/apu4_desk_3.jpg create mode 100644 docs/_static/images/apu4_desk_4.jpg create mode 100644 docs/_static/images/apu4_rack_1.jpg create mode 100644 docs/_static/images/apu4_rack_2.jpg create mode 100644 docs/_static/images/apu4_rack_3.jpg create mode 100644 docs/_static/images/apu4_rack_4.jpg create mode 100644 docs/_static/images/apu4_rack_5.jpg create mode 100644 docs/_static/images/apu4_rack_vyos_print.jpg create mode 100644 docs/_static/images/aws.png create mode 100644 docs/_static/images/blueprint-dmvpn.png create mode 100644 docs/_static/images/boot-options.png create mode 100644 docs/_static/images/cisco-vpn-ipsec.png create mode 100644 docs/_static/images/cloud-aws-01.png create mode 100644 docs/_static/images/cloud-aws-02.png create mode 100644 docs/_static/images/cloud-aws-03.png create mode 100644 docs/_static/images/cloud-aws-04.png create mode 100644 docs/_static/images/cloud-aws-05.png create mode 100644 docs/_static/images/cloud-aws-06.png create mode 100644 docs/_static/images/cloud-aws-07.png create mode 100644 docs/_static/images/cloud-aws-08.png create mode 100644 docs/_static/images/cloud-azure-01.png create mode 100644 docs/_static/images/cloud-azure-02.png create mode 100644 docs/_static/images/cloud-azure-03.png create mode 100644 docs/_static/images/cloud-azure-04.png create mode 100644 docs/_static/images/cloud-azure-05.png create mode 100644 docs/_static/images/cloud-azure-06.png create mode 100644 docs/_static/images/cloud-gcp-01.png create mode 100644 docs/_static/images/cloud-gcp-02.png create mode 100644 docs/_static/images/cloud-gcp-03.png create mode 100644 docs/_static/images/cloud-gcp-04.png create mode 100644 docs/_static/images/cloud-gcp-05.png create mode 100644 docs/_static/images/dhcp-relay-through-gre-bridge.png create mode 100644 docs/_static/images/dual-hub-DMVPN.png create mode 100644 docs/_static/images/eve-ng-vyos.png create mode 100644 docs/_static/images/firewall-and-vrf-blueprints.png create mode 100644 docs/_static/images/firewall-bridge-forward.png create mode 100644 docs/_static/images/firewall-bridge-input.png create mode 100644 docs/_static/images/firewall-bridge-output.png create mode 100644 docs/_static/images/firewall-flowtable-packet-flow.png create mode 100644 docs/_static/images/firewall-fwd-packet-flow.png create mode 100644 docs/_static/images/firewall-gral-packet-flow.png create mode 100644 docs/_static/images/firewall-input-packet-flow.png create mode 100644 docs/_static/images/firewall-netfilter.png create mode 100644 docs/_static/images/firewall-traditional.png create mode 100644 docs/_static/images/firewall-zonebased.png create mode 100644 docs/_static/images/gns3-01.png create mode 100644 docs/_static/images/gns3-02.png create mode 100644 docs/_static/images/gns3-03.png create mode 100644 docs/_static/images/gns3-04.png create mode 100644 docs/_static/images/gns3-05.png create mode 100644 docs/_static/images/gns3-06.png create mode 100644 docs/_static/images/gns3-07.png create mode 100644 docs/_static/images/gns3-08.png create mode 100644 docs/_static/images/gns3-09.png create mode 100644 docs/_static/images/gns3-10.png create mode 100644 docs/_static/images/gns3-11.png create mode 100644 docs/_static/images/gns3-12.png create mode 100644 docs/_static/images/gns3-13.png create mode 100644 docs/_static/images/gns3-14.png create mode 100644 docs/_static/images/gns3-15.png create mode 100644 docs/_static/images/gns3-16.png create mode 100644 docs/_static/images/gns3-17.png create mode 100644 docs/_static/images/gns3-20.png create mode 100644 docs/_static/images/gns3-21.png create mode 100644 docs/_static/images/gns3-215.png create mode 100644 docs/_static/images/gns3-22.png create mode 100644 docs/_static/images/gowin-01.png create mode 100644 docs/_static/images/gowin-02.png create mode 100644 docs/_static/images/gowin-03.png create mode 100644 docs/_static/images/gowin-04.png create mode 100644 docs/_static/images/inter-vrf-routing-vrf-lite.png create mode 100644 docs/_static/images/ipsec-vyos-pa.png create mode 100644 docs/_static/images/json.png create mode 100644 docs/_static/images/key.png create mode 100644 docs/_static/images/keypairs.png create mode 100644 docs/_static/images/lac-lns-diagram.jpg create mode 100644 docs/_static/images/lac-lns-winclient.jpg create mode 100644 docs/_static/images/ldapone.png create mode 100644 docs/_static/images/ldaptwo.png create mode 100644 docs/_static/images/mainschema.png create mode 100644 docs/_static/images/multicast-basic.png create mode 100644 docs/_static/images/nat_before_vpn_topology.png create mode 100644 docs/_static/images/nmp1.png create mode 100644 docs/_static/images/nmp2.png create mode 100644 docs/_static/images/nmp3.png create mode 100644 docs/_static/images/nmp4.png create mode 100644 docs/_static/images/nmp5.png create mode 100644 docs/_static/images/nmp6.png create mode 100644 docs/_static/images/nmp7.png create mode 100644 docs/_static/images/openvpn_site2site_diagram.jpg create mode 100644 docs/_static/images/pbr_example_1.png create mode 100644 docs/_static/images/policy-based-ipsec-and-firewall.png create mode 100644 docs/_static/images/pppoe-ipv6-pd-diagram.jpg create mode 100644 docs/_static/images/project.png create mode 100644 docs/_static/images/qos1.png create mode 100644 docs/_static/images/qos10.png create mode 100644 docs/_static/images/qos2.png create mode 100644 docs/_static/images/qos3.png create mode 100644 docs/_static/images/qos4.png create mode 100644 docs/_static/images/qos5.png create mode 100644 docs/_static/images/qos6.png create mode 100644 docs/_static/images/qos7.png create mode 100644 docs/_static/images/qos8.png create mode 100644 docs/_static/images/qos9.png create mode 100644 docs/_static/images/reset-password-step-1.jpg create mode 100644 docs/_static/images/reset-password-step-2.jpg create mode 100644 docs/_static/images/reset-password-step-3.jpg create mode 100644 docs/_static/images/reset-password-step-4.jpg create mode 100644 docs/_static/images/reset-password-step-5.jpg create mode 100644 docs/_static/images/service.png create mode 100644 docs/_static/images/service_conntrack_sync-schema.png create mode 100644 docs/_static/images/service_dhcp-relay01.png create mode 100644 docs/_static/images/service_dhcpv6-relay01.png create mode 100644 docs/_static/images/service_snmp_communication_principles_diagram.png create mode 100644 docs/_static/images/sg.png create mode 100644 docs/_static/images/sticky-connections.jpg create mode 100644 docs/_static/images/traffic.png create mode 100644 docs/_static/images/uefi_secureboot_01.png create mode 100644 docs/_static/images/uefi_secureboot_02.png create mode 100644 docs/_static/images/uefi_secureboot_03.png create mode 100644 docs/_static/images/uefi_secureboot_04.png create mode 100644 docs/_static/images/uefi_secureboot_05.png create mode 100644 docs/_static/images/uefi_secureboot_06.png create mode 100644 docs/_static/images/uefi_secureboot_07.png create mode 100644 docs/_static/images/virt-libvirt-01.png create mode 100644 docs/_static/images/virt-libvirt-02.png create mode 100644 docs/_static/images/virt-libvirt-03.png create mode 100644 docs/_static/images/virt-libvirt-04.png create mode 100644 docs/_static/images/virt-libvirt-05.png create mode 100644 docs/_static/images/virt-libvirt-06.png create mode 100644 docs/_static/images/virt-libvirt-qc-01.png create mode 100644 docs/_static/images/virt-libvirt-qc-02.png create mode 100644 docs/_static/images/virt-libvirt-qc-03.png create mode 100644 docs/_static/images/vpn_dmvpn_topology01.png create mode 100644 docs/_static/images/vpn_s2s_ikev2.png create mode 100644 docs/_static/images/vpn_s2s_ikev2_c.png create mode 100644 docs/_static/images/vrf-example-topology-01.png create mode 100644 docs/_static/images/vyos-downloads.png create mode 100644 docs/_static/images/vyos-sr-isis.png create mode 100644 docs/_static/images/vyos_1_4_nat66_simple.png create mode 100644 docs/_static/images/vyos_1_5_nat66_dhcpv6_wdummy.png create mode 100644 docs/_static/images/vyos_arista_bond_lacp.png create mode 100644 docs/_static/images/vyosnew-downloads.png create mode 100644 docs/_static/images/wireguard_qrcode.jpg create mode 100644 docs/_static/images/wireguard_site2site_diagram.jpg create mode 100644 docs/_static/images/zone-policy-diagram.png delete mode 100644 docs/_swap.txt delete mode 100644 docs/automation/md-cloud-init.md delete mode 100644 docs/automation/md-command-scripting.md delete mode 100644 docs/automation/md-index.md delete mode 100644 docs/automation/md-vyos-ansible.md delete mode 100644 docs/automation/md-vyos-api.md delete mode 100644 docs/automation/md-vyos-govyos.md delete mode 100644 docs/automation/md-vyos-napalm.md delete mode 100644 docs/automation/md-vyos-netmiko.md delete mode 100644 docs/automation/md-vyos-pyvyos.md delete mode 100644 docs/automation/md-vyos-salt.md delete mode 100644 docs/automation/terraform/md-index.md delete mode 100644 docs/automation/terraform/md-terraformAWS.md delete mode 100644 docs/automation/terraform/md-terraformAZ.md delete mode 100644 docs/automation/terraform/md-terraformGoogle.md delete mode 100644 docs/automation/terraform/md-terraformvSphere.md delete mode 100644 docs/automation/terraform/terraformvyos.md create mode 100644 docs/configexamples/autotest/DHCPRelay_through_GRE/_include/topology.png delete mode 100644 docs/configexamples/autotest/DHCPRelay_through_GRE/md-DHCPRelay_through_GRE.md create mode 100644 docs/configexamples/autotest/L3VPN_EVPN/_include/topology.png delete mode 100644 docs/configexamples/autotest/L3VPN_EVPN/md-L3VPN_EVPN.md create mode 100644 docs/configexamples/autotest/OpenVPN_with_LDAP/_include/topology.png delete mode 100644 docs/configexamples/autotest/OpenVPN_with_LDAP/md-OpenVPN_with_LDAP.md create mode 100644 docs/configexamples/autotest/Wireguard/_include/topology.png delete mode 100644 docs/configexamples/autotest/Wireguard/md-Wireguard.md create mode 100644 docs/configexamples/autotest/tunnelbroker/_include/topology.png delete mode 100644 docs/configexamples/autotest/tunnelbroker/md-tunnelbroker.md delete mode 100644 docs/configexamples/md-ansible.md delete mode 100644 docs/configexamples/md-azure-vpn-bgp.md delete mode 100644 docs/configexamples/md-azure-vpn-dual-bgp.md delete mode 100644 docs/configexamples/md-bgp-ipv6-unnumbered.md delete mode 100644 docs/configexamples/md-dmvpn-dualhub-dualcloud.md delete mode 100644 docs/configexamples/md-firewall.md delete mode 100644 docs/configexamples/md-fwall-and-bridge.md delete mode 100644 docs/configexamples/md-fwall-and-vrf.md delete mode 100644 docs/configexamples/md-ha.md delete mode 100644 docs/configexamples/md-index.md delete mode 100644 docs/configexamples/md-inter-vrf-routing-vrf-lite.md delete mode 100644 docs/configexamples/md-ipsec-cisco-policy-based.md delete mode 100644 docs/configexamples/md-ipsec-cisco-route-based.md delete mode 100644 docs/configexamples/md-ipsec-pa-route-based.md delete mode 100644 docs/configexamples/md-l3vpn-hub-and-spoke.md delete mode 100644 docs/configexamples/md-lac-lns.md delete mode 100644 docs/configexamples/md-nmp.md delete mode 100644 docs/configexamples/md-ospf-unnumbered.md delete mode 100644 docs/configexamples/md-policy-based-ipsec-and-firewall.md delete mode 100644 docs/configexamples/md-pppoe-ipv6-basic.md delete mode 100644 docs/configexamples/md-qos.md delete mode 100644 docs/configexamples/md-segment-routing-isis.md delete mode 100644 docs/configexamples/md-site-2-site-cisco.md delete mode 100644 docs/configexamples/md-wan-load-balancing.md delete mode 100644 docs/configexamples/md-zone-policy.md delete mode 100644 docs/configuration/container/md-index.md delete mode 100644 docs/configuration/firewall/md-bridge.md delete mode 100644 docs/configuration/firewall/md-flowtables.md delete mode 100644 docs/configuration/firewall/md-global-options.md delete mode 100644 docs/configuration/firewall/md-groups.md delete mode 100644 docs/configuration/firewall/md-index.md delete mode 100644 docs/configuration/firewall/md-ipv4.md delete mode 100644 docs/configuration/firewall/md-ipv6.md delete mode 100644 docs/configuration/firewall/md-zone.md delete mode 100644 docs/configuration/highavailability/md-index.md delete mode 100644 docs/configuration/interfaces/md-bonding.md delete mode 100644 docs/configuration/interfaces/md-bridge.md delete mode 100644 docs/configuration/interfaces/md-dummy.md delete mode 100644 docs/configuration/interfaces/md-ethernet.md delete mode 100644 docs/configuration/interfaces/md-geneve.md delete mode 100644 docs/configuration/interfaces/md-index.md delete mode 100644 docs/configuration/interfaces/md-l2tpv3.md delete mode 100644 docs/configuration/interfaces/md-loopback.md delete mode 100644 docs/configuration/interfaces/md-macsec.md delete mode 100644 docs/configuration/interfaces/md-openvpn-examples.md delete mode 100644 docs/configuration/interfaces/md-openvpn.md delete mode 100644 docs/configuration/interfaces/md-pppoe.md delete mode 100644 docs/configuration/interfaces/md-pseudo-ethernet.md delete mode 100644 docs/configuration/interfaces/md-sstp-client.md delete mode 100644 docs/configuration/interfaces/md-tunnel.md delete mode 100644 docs/configuration/interfaces/md-virtual-ethernet.md delete mode 100644 docs/configuration/interfaces/md-vti.md delete mode 100644 docs/configuration/interfaces/md-vxlan.md delete mode 100644 docs/configuration/interfaces/md-wireguard.md delete mode 100644 docs/configuration/interfaces/md-wireless.md delete mode 100644 docs/configuration/interfaces/md-wwan.md delete mode 100644 docs/configuration/loadbalancing/md-haproxy.md delete mode 100644 docs/configuration/loadbalancing/md-index.md delete mode 100644 docs/configuration/loadbalancing/md-wan.md delete mode 100644 docs/configuration/md-index.md delete mode 100644 docs/configuration/nat/md-cgnat.md delete mode 100644 docs/configuration/nat/md-index.md delete mode 100644 docs/configuration/nat/md-nat44.md delete mode 100644 docs/configuration/nat/md-nat64.md delete mode 100644 docs/configuration/nat/md-nat66.md delete mode 100644 docs/configuration/pki/md-index.md delete mode 100644 docs/configuration/policy/md-access-list.md delete mode 100644 docs/configuration/policy/md-as-path-list.md delete mode 100644 docs/configuration/policy/md-community-list.md delete mode 100644 docs/configuration/policy/md-examples.md delete mode 100644 docs/configuration/policy/md-extcommunity-list.md delete mode 100644 docs/configuration/policy/md-index.md delete mode 100644 docs/configuration/policy/md-large-community-list.md delete mode 100644 docs/configuration/policy/md-local-route.md delete mode 100644 docs/configuration/policy/md-prefix-list.md delete mode 100644 docs/configuration/policy/md-route-map.md delete mode 100644 docs/configuration/policy/md-route.md delete mode 100644 docs/configuration/protocols/md-arp.md delete mode 100644 docs/configuration/protocols/md-babel.md delete mode 100644 docs/configuration/protocols/md-bfd.md delete mode 100644 docs/configuration/protocols/md-bgp.md delete mode 100644 docs/configuration/protocols/md-failover.md delete mode 100644 docs/configuration/protocols/md-igmp-proxy.md delete mode 100644 docs/configuration/protocols/md-index.md delete mode 100644 docs/configuration/protocols/md-isis.md delete mode 100644 docs/configuration/protocols/md-mpls.md delete mode 100644 docs/configuration/protocols/md-multicast.md delete mode 100644 docs/configuration/protocols/md-openfabric.md delete mode 100644 docs/configuration/protocols/md-ospf.md delete mode 100644 docs/configuration/protocols/md-pim.md delete mode 100644 docs/configuration/protocols/md-pim6.md delete mode 100644 docs/configuration/protocols/md-rip.md delete mode 100644 docs/configuration/protocols/md-rpki.md delete mode 100644 docs/configuration/protocols/md-segment-routing.md delete mode 100644 docs/configuration/protocols/md-static.md delete mode 100644 docs/configuration/protocols/md-traffic-engineering.md delete mode 100644 docs/configuration/service/md-broadcast-relay.md delete mode 100644 docs/configuration/service/md-config-sync.md delete mode 100644 docs/configuration/service/md-conntrack-sync.md delete mode 100644 docs/configuration/service/md-console-server.md delete mode 100644 docs/configuration/service/md-dhcp-relay.md delete mode 100644 docs/configuration/service/md-dhcp-server.md delete mode 100644 docs/configuration/service/md-dns.md delete mode 100644 docs/configuration/service/md-eventhandler.md delete mode 100644 docs/configuration/service/md-https.md delete mode 100644 docs/configuration/service/md-index.md delete mode 100644 docs/configuration/service/md-ipoe-server.md delete mode 100644 docs/configuration/service/md-lldp.md delete mode 100644 docs/configuration/service/md-mdns.md delete mode 100644 docs/configuration/service/md-monitoring.md delete mode 100644 docs/configuration/service/md-ntp.md delete mode 100644 docs/configuration/service/md-pppoe-server.md delete mode 100644 docs/configuration/service/md-router-advert.md delete mode 100644 docs/configuration/service/md-salt-minion.md delete mode 100644 docs/configuration/service/md-snmp.md delete mode 100644 docs/configuration/service/md-ssh.md delete mode 100644 docs/configuration/service/md-suricata.md delete mode 100644 docs/configuration/service/md-tftp-server.md delete mode 100644 docs/configuration/service/md-webproxy.md delete mode 100644 docs/configuration/system/md-acceleration.md delete mode 100644 docs/configuration/system/md-conntrack.md delete mode 100644 docs/configuration/system/md-console.md delete mode 100644 docs/configuration/system/md-default-route.md delete mode 100644 docs/configuration/system/md-flow-accounting.md delete mode 100644 docs/configuration/system/md-frr.md delete mode 100644 docs/configuration/system/md-host-name.md delete mode 100644 docs/configuration/system/md-index.md delete mode 100644 docs/configuration/system/md-ip.md delete mode 100644 docs/configuration/system/md-ipv6.md delete mode 100644 docs/configuration/system/md-lcd.md delete mode 100644 docs/configuration/system/md-login.md delete mode 100644 docs/configuration/system/md-name-server.md delete mode 100644 docs/configuration/system/md-option.md delete mode 100644 docs/configuration/system/md-proxy.md delete mode 100644 docs/configuration/system/md-sflow.md delete mode 100644 docs/configuration/system/md-sysctl.md delete mode 100644 docs/configuration/system/md-syslog.md delete mode 100644 docs/configuration/system/md-task-scheduler.md delete mode 100644 docs/configuration/system/md-time-zone.md delete mode 100644 docs/configuration/system/md-updates.md delete mode 100644 docs/configuration/system/md-watchdog.md delete mode 100644 docs/configuration/trafficpolicy/md-index.md delete mode 100644 docs/configuration/vpn/ipsec/md-index.md delete mode 100644 docs/configuration/vpn/ipsec/md-ipsec_general.md delete mode 100644 docs/configuration/vpn/ipsec/md-remoteaccess_ipsec.md delete mode 100644 docs/configuration/vpn/ipsec/md-site2site_ipsec.md delete mode 100644 docs/configuration/vpn/ipsec/md-troubleshooting_ipsec.md delete mode 100644 docs/configuration/vpn/md-dmvpn.md delete mode 100644 docs/configuration/vpn/md-index.md delete mode 100644 docs/configuration/vpn/md-l2tp.md delete mode 100644 docs/configuration/vpn/md-openconnect.md delete mode 100644 docs/configuration/vpn/md-pptp.md delete mode 100644 docs/configuration/vpn/md-rsa-keys.md delete mode 100644 docs/configuration/vpn/md-sstp.md delete mode 100644 docs/configuration/vrf/md-index.md delete mode 100644 docs/contributing/md-build-vyos.md delete mode 100644 docs/contributing/md-cla.md delete mode 100644 docs/contributing/md-debugging.md delete mode 100644 docs/contributing/md-development.md delete mode 100644 docs/contributing/md-index.md delete mode 100644 docs/contributing/md-issues-features.md delete mode 100644 docs/contributing/md-testing.md delete mode 100644 docs/contributing/md-upstream-packages.md delete mode 100644 docs/installation/cloud/md-aws.md delete mode 100644 docs/installation/cloud/md-azure.md delete mode 100644 docs/installation/cloud/md-gcp.md delete mode 100644 docs/installation/cloud/md-index.md delete mode 100644 docs/installation/cloud/md-oracle.md delete mode 100644 docs/installation/md-bare-metal.md delete mode 100644 docs/installation/md-image.md delete mode 100644 docs/installation/md-index.md delete mode 100644 docs/installation/md-install.md delete mode 100644 docs/installation/md-secure-boot.md delete mode 100644 docs/installation/md-update.md delete mode 100644 docs/installation/virtual/md-docker.md delete mode 100644 docs/installation/virtual/md-eve-ng.md delete mode 100644 docs/installation/virtual/md-gns3.md delete mode 100644 docs/installation/virtual/md-index.md delete mode 100644 docs/installation/virtual/md-libvirt.md delete mode 100644 docs/installation/virtual/md-proxmox.md delete mode 100644 docs/installation/virtual/md-vmware.md delete mode 100644 docs/introducing/md-about.md delete mode 100644 docs/introducing/md-history.md delete mode 100644 docs/md-404.md delete mode 100644 docs/md-cli.md delete mode 100644 docs/md-coverage.md delete mode 100644 docs/md-documentation.md delete mode 100644 docs/md-index.md delete mode 100644 docs/md-quick-start.md delete mode 100644 docs/operation/md-boot-options.md delete mode 100644 docs/operation/md-index.md delete mode 100644 docs/operation/md-information.md delete mode 100644 docs/operation/md-password-recovery.md delete mode 100644 docs/operation/md-raid.md delete mode 100644 docs/operation/md-upgrade-recovery.md delete mode 100644 docs/troubleshooting/md-connectivity.md delete mode 100644 docs/troubleshooting/md-index.md delete mode 100644 docs/troubleshooting/md-interfaces.md delete mode 100644 docs/troubleshooting/md-monitoring.md delete mode 100644 docs/troubleshooting/md-system.md delete mode 100644 docs/troubleshooting/md-terminal.md delete mode 100644 docs/vpp/configuration/dataplane/md-buffers.md delete mode 100644 docs/vpp/configuration/dataplane/md-cpu.md delete mode 100644 docs/vpp/configuration/dataplane/md-index.md delete mode 100644 docs/vpp/configuration/dataplane/md-interface.md delete mode 100644 docs/vpp/configuration/dataplane/md-ipsec.md delete mode 100644 docs/vpp/configuration/dataplane/md-ipv6.md delete mode 100644 docs/vpp/configuration/dataplane/md-l2learn.md delete mode 100644 docs/vpp/configuration/dataplane/md-lcp.md delete mode 100644 docs/vpp/configuration/dataplane/md-logging.md delete mode 100644 docs/vpp/configuration/dataplane/md-memory.md delete mode 100644 docs/vpp/configuration/dataplane/md-system.md delete mode 100644 docs/vpp/configuration/dataplane/md-unix.md delete mode 100644 docs/vpp/configuration/interfaces/md-bonding.md delete mode 100644 docs/vpp/configuration/interfaces/md-bridge.md delete mode 100644 docs/vpp/configuration/interfaces/md-gre.md delete mode 100644 docs/vpp/configuration/interfaces/md-index.md delete mode 100644 docs/vpp/configuration/interfaces/md-ipip.md delete mode 100644 docs/vpp/configuration/interfaces/md-loopback.md delete mode 100644 docs/vpp/configuration/interfaces/md-vxlan.md delete mode 100644 docs/vpp/configuration/interfaces/md-xconnect.md delete mode 100644 docs/vpp/configuration/md-acl.md delete mode 100644 docs/vpp/configuration/md-index.md delete mode 100644 docs/vpp/configuration/md-ipfix.md delete mode 100644 docs/vpp/configuration/md-ipsec.md delete mode 100644 docs/vpp/configuration/md-sflow.md delete mode 100644 docs/vpp/configuration/nat/md-cgnat.md delete mode 100644 docs/vpp/configuration/nat/md-index.md delete mode 100644 docs/vpp/configuration/nat/md-nat44.md delete mode 100644 docs/vpp/md-description.md delete mode 100644 docs/vpp/md-index.md delete mode 100644 docs/vpp/md-limitations.md delete mode 100644 docs/vpp/md-requirements.md delete mode 100644 docs/vpp/md-troubleshooting.md delete mode 100644 scripts/import_myst.py delete mode 100644 scripts/swap_sources.py delete mode 100644 tests/test_import_myst.py delete mode 100644 tests/test_swap_sources.py (limited to 'docs/_static') diff --git a/.readthedocs.yml b/.readthedocs.yml index 6539873e..f0ea8c49 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -8,11 +8,6 @@ build: os: ubuntu-22.04 tools: python: "3.10" - jobs: - pre_build: - - python3 scripts/swap_sources.py --swap - post_build: - - python3 scripts/swap_sources.py --restore # Build documentation in the docs/ directory with Sphinx sphinx: diff --git a/docs/Makefile b/docs/Makefile index ae12b802..cb6226af 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -12,44 +12,22 @@ AUTOHOST = 0.0.0.0 AUTOPORT = 8000 AUTOOPTS = --watch . -SWAP = python3 ../scripts/swap_sources.py - # Put it first so that "make" without argument is like "make help". help: @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) -.PHONY: help Makefile swap restore html dirhtml pdf livehtml defaultvalue - -swap: - $(SWAP) --swap - -restore: - $(SWAP) --restore - -html: swap - @trap '$(SWAP) --restore' EXIT; \ - $(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) - -dirhtml: swap - @trap '$(SWAP) --restore' EXIT; \ - $(SPHINXBUILD) -M dirhtml "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) - -pdf: swap - @trap '$(SWAP) --restore' EXIT; \ - $(SPHINXBUILD) -M latexpdf "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) - -livehtml: swap - @trap '$(SWAP) --restore' EXIT; \ - sphinx-autobuild --host $(AUTOHOST) --port $(AUTOPORT) \ - --ignore '$(BUILDDIR)/**' \ - --ignore '**/_build/**' \ - --ignore '**/md-*' \ - "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) - -defaultvalue: export VYOS_DEFAULT=True -defaultvalue: html +.PHONY: help Makefile # Catch-all target: route all unknown targets to Sphinx using the new # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). %: Makefile @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +livehtml: + sphinx-autobuild --host $(AUTOHOST) --port $(AUTOPORT) $(AUTOOPTS) \ + "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + + +defaultvalue: export VYOS_DEFAULT=True +defaultvalue: + @$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) \ No newline at end of file diff --git a/docs/_ext/vyos.py b/docs/_ext/vyos.py index 527178d1..2f4dede9 100644 --- a/docs/_ext/vyos.py +++ b/docs/_ext/vyos.py @@ -364,18 +364,8 @@ class CmdInclude(SphinxDirective): line = re.sub('{{\s?var' + str(i) + '\s?}}',value,line) new_include_lines.append(line) - if hasattr(self.state, '_renderer'): - self.state._renderer.nested_render_text(''.join(new_include_lines), self.lineno) - return [] - from docutils.statemachine import ViewList - from docutils import nodes - content = ''.join(new_include_lines) - vl = ViewList() - for i, line in enumerate(content.splitlines(keepends=False)): - vl.append(line, include_file[1], i) - node = nodes.Element() - self.state.nested_parse(vl, self.content_offset, node, match_titles=True) - return node.children + self.state._renderer.nested_render_text(''.join(new_include_lines), self.lineno) + return [] class CfgcmdlistDirective(Directive): diff --git a/docs/_static/images/1u_vyos_back.jpg b/docs/_static/images/1u_vyos_back.jpg new file mode 100644 index 00000000..cd00c11c Binary files /dev/null and b/docs/_static/images/1u_vyos_back.jpg differ diff --git a/docs/_static/images/1u_vyos_front.jpg b/docs/_static/images/1u_vyos_front.jpg new file mode 100644 index 00000000..3d135d56 Binary files /dev/null and b/docs/_static/images/1u_vyos_front.jpg differ diff --git a/docs/_static/images/1u_vyos_front_10ge_open_1.jpg b/docs/_static/images/1u_vyos_front_10ge_open_1.jpg new file mode 100644 index 00000000..edfba5a3 Binary files /dev/null and b/docs/_static/images/1u_vyos_front_10ge_open_1.jpg differ diff --git a/docs/_static/images/1u_vyos_front_10ge_open_2.jpg b/docs/_static/images/1u_vyos_front_10ge_open_2.jpg new file mode 100644 index 00000000..4f48a116 Binary files /dev/null and b/docs/_static/images/1u_vyos_front_10ge_open_2.jpg differ diff --git a/docs/_static/images/1u_vyos_front_10ge_open_3.jpg b/docs/_static/images/1u_vyos_front_10ge_open_3.jpg new file mode 100644 index 00000000..c102b903 Binary files /dev/null and b/docs/_static/images/1u_vyos_front_10ge_open_3.jpg differ diff --git a/docs/_static/images/1u_vyos_front_10ge_open_4.jpg b/docs/_static/images/1u_vyos_front_10ge_open_4.jpg new file mode 100644 index 00000000..2f270b7e Binary files /dev/null and b/docs/_static/images/1u_vyos_front_10ge_open_4.jpg differ diff --git a/docs/_static/images/1u_vyos_front_open_1.jpg b/docs/_static/images/1u_vyos_front_open_1.jpg new file mode 100644 index 00000000..d90d565e Binary files /dev/null and b/docs/_static/images/1u_vyos_front_open_1.jpg differ diff --git a/docs/_static/images/1u_vyos_front_open_2.jpg b/docs/_static/images/1u_vyos_front_open_2.jpg new file mode 100644 index 00000000..6d112463 Binary files /dev/null and b/docs/_static/images/1u_vyos_front_open_2.jpg differ diff --git a/docs/_static/images/1u_vyos_front_open_3.jpg b/docs/_static/images/1u_vyos_front_open_3.jpg new file mode 100644 index 00000000..198ba3ce Binary files /dev/null and b/docs/_static/images/1u_vyos_front_open_3.jpg differ diff --git a/docs/_static/images/480px-Acrosser_ANDJ190N1_Back.jpg b/docs/_static/images/480px-Acrosser_ANDJ190N1_Back.jpg new file mode 100644 index 00000000..6441c54a Binary files /dev/null and b/docs/_static/images/480px-Acrosser_ANDJ190N1_Back.jpg differ diff --git a/docs/_static/images/480px-Acrosser_ANDJ190N1_Front.jpg b/docs/_static/images/480px-Acrosser_ANDJ190N1_Front.jpg new file mode 100644 index 00000000..5f216aa1 Binary files /dev/null and b/docs/_static/images/480px-Acrosser_ANDJ190N1_Front.jpg differ diff --git a/docs/_static/images/600px-Partaker-i5.jpg b/docs/_static/images/600px-Partaker-i5.jpg new file mode 100644 index 00000000..68196d41 Binary files /dev/null and b/docs/_static/images/600px-Partaker-i5.jpg differ diff --git a/docs/_static/images/ESP_AH.png b/docs/_static/images/ESP_AH.png new file mode 100644 index 00000000..6075c3f4 Binary files /dev/null and b/docs/_static/images/ESP_AH.png differ diff --git a/docs/_static/images/IPSec_close_action_settings.png b/docs/_static/images/IPSec_close_action_settings.png new file mode 100644 index 00000000..531643f7 Binary files /dev/null and b/docs/_static/images/IPSec_close_action_settings.png differ diff --git a/docs/_static/images/L3VPN_hub_and_spoke.png b/docs/_static/images/L3VPN_hub_and_spoke.png new file mode 100644 index 00000000..d442cc1a Binary files /dev/null and b/docs/_static/images/L3VPN_hub_and_spoke.png differ diff --git a/docs/_static/images/PA-ESP-group.png b/docs/_static/images/PA-ESP-group.png new file mode 100644 index 00000000..c6411b66 Binary files /dev/null and b/docs/_static/images/PA-ESP-group.png differ diff --git a/docs/_static/images/PA-IKE-GW-1.png b/docs/_static/images/PA-IKE-GW-1.png new file mode 100644 index 00000000..863eeb3a Binary files /dev/null and b/docs/_static/images/PA-IKE-GW-1.png differ diff --git a/docs/_static/images/PA-IKE-GW-2.png b/docs/_static/images/PA-IKE-GW-2.png new file mode 100644 index 00000000..21a16055 Binary files /dev/null and b/docs/_static/images/PA-IKE-GW-2.png differ diff --git a/docs/_static/images/PA-IKE-group.png b/docs/_static/images/PA-IKE-group.png new file mode 100644 index 00000000..06fd535d Binary files /dev/null and b/docs/_static/images/PA-IKE-group.png differ diff --git a/docs/_static/images/PA-IPsec-tunnel.png b/docs/_static/images/PA-IPsec-tunnel.png new file mode 100644 index 00000000..2f8f4cb8 Binary files /dev/null and b/docs/_static/images/PA-IPsec-tunnel.png differ diff --git a/docs/_static/images/PA-tunnel-1.png b/docs/_static/images/PA-tunnel-1.png new file mode 100644 index 00000000..3c99c6c7 Binary files /dev/null and b/docs/_static/images/PA-tunnel-1.png differ diff --git a/docs/_static/images/PA-tunnel-2.png b/docs/_static/images/PA-tunnel-2.png new file mode 100644 index 00000000..6f073513 Binary files /dev/null and b/docs/_static/images/PA-tunnel-2.png differ diff --git a/docs/_static/images/PA-tunnel-3.png b/docs/_static/images/PA-tunnel-3.png new file mode 100644 index 00000000..ca5a94e9 Binary files /dev/null and b/docs/_static/images/PA-tunnel-3.png differ diff --git a/docs/_static/images/VyOS_Dual-Hub_DMVPN.png b/docs/_static/images/VyOS_Dual-Hub_DMVPN.png new file mode 100644 index 00000000..9c25a308 Binary files /dev/null and b/docs/_static/images/VyOS_Dual-Hub_DMVPN.png differ diff --git a/docs/_static/images/Wan_load_balancing1.png b/docs/_static/images/Wan_load_balancing1.png new file mode 100644 index 00000000..bde1edb6 Binary files /dev/null and b/docs/_static/images/Wan_load_balancing1.png differ diff --git a/docs/_static/images/Wan_load_balancing_exclude1.png b/docs/_static/images/Wan_load_balancing_exclude1.png new file mode 100644 index 00000000..1111535d Binary files /dev/null and b/docs/_static/images/Wan_load_balancing_exclude1.png differ diff --git a/docs/_static/images/ansible.png b/docs/_static/images/ansible.png new file mode 100644 index 00000000..1d80b3f4 Binary files /dev/null and b/docs/_static/images/ansible.png differ diff --git a/docs/_static/images/apu4_desk_1.jpg b/docs/_static/images/apu4_desk_1.jpg new file mode 100644 index 00000000..b7a3d08e Binary files /dev/null and b/docs/_static/images/apu4_desk_1.jpg differ diff --git a/docs/_static/images/apu4_desk_2.jpg b/docs/_static/images/apu4_desk_2.jpg new file mode 100644 index 00000000..fe356e1f Binary files /dev/null and b/docs/_static/images/apu4_desk_2.jpg differ diff --git a/docs/_static/images/apu4_desk_3.jpg b/docs/_static/images/apu4_desk_3.jpg new file mode 100644 index 00000000..af7dc406 Binary files /dev/null and b/docs/_static/images/apu4_desk_3.jpg differ diff --git a/docs/_static/images/apu4_desk_4.jpg b/docs/_static/images/apu4_desk_4.jpg new file mode 100644 index 00000000..37251af2 Binary files /dev/null and b/docs/_static/images/apu4_desk_4.jpg differ diff --git a/docs/_static/images/apu4_rack_1.jpg b/docs/_static/images/apu4_rack_1.jpg new file mode 100644 index 00000000..3793cd39 Binary files /dev/null and b/docs/_static/images/apu4_rack_1.jpg differ diff --git a/docs/_static/images/apu4_rack_2.jpg b/docs/_static/images/apu4_rack_2.jpg new file mode 100644 index 00000000..b8caf976 Binary files /dev/null and b/docs/_static/images/apu4_rack_2.jpg differ diff --git a/docs/_static/images/apu4_rack_3.jpg b/docs/_static/images/apu4_rack_3.jpg new file mode 100644 index 00000000..08ff633e Binary files /dev/null and b/docs/_static/images/apu4_rack_3.jpg differ diff --git a/docs/_static/images/apu4_rack_4.jpg b/docs/_static/images/apu4_rack_4.jpg new file mode 100644 index 00000000..a88d62fe Binary files /dev/null and b/docs/_static/images/apu4_rack_4.jpg differ diff --git a/docs/_static/images/apu4_rack_5.jpg b/docs/_static/images/apu4_rack_5.jpg new file mode 100644 index 00000000..644b8e0a Binary files /dev/null and b/docs/_static/images/apu4_rack_5.jpg differ diff --git a/docs/_static/images/apu4_rack_vyos_print.jpg b/docs/_static/images/apu4_rack_vyos_print.jpg new file mode 100644 index 00000000..a0bbaab2 Binary files /dev/null and b/docs/_static/images/apu4_rack_vyos_print.jpg differ diff --git a/docs/_static/images/aws.png b/docs/_static/images/aws.png new file mode 100644 index 00000000..c1c111bb Binary files /dev/null and b/docs/_static/images/aws.png differ diff --git a/docs/_static/images/blueprint-dmvpn.png b/docs/_static/images/blueprint-dmvpn.png new file mode 100644 index 00000000..85f189c1 Binary files /dev/null and b/docs/_static/images/blueprint-dmvpn.png differ diff --git a/docs/_static/images/boot-options.png b/docs/_static/images/boot-options.png new file mode 100644 index 00000000..b00350bc Binary files /dev/null and b/docs/_static/images/boot-options.png differ diff --git a/docs/_static/images/cisco-vpn-ipsec.png b/docs/_static/images/cisco-vpn-ipsec.png new file mode 100644 index 00000000..bc19e8bc Binary files /dev/null and b/docs/_static/images/cisco-vpn-ipsec.png differ diff --git a/docs/_static/images/cloud-aws-01.png b/docs/_static/images/cloud-aws-01.png new file mode 100644 index 00000000..cda6542f Binary files /dev/null and b/docs/_static/images/cloud-aws-01.png differ diff --git a/docs/_static/images/cloud-aws-02.png b/docs/_static/images/cloud-aws-02.png new file mode 100644 index 00000000..639d42fa Binary files /dev/null and b/docs/_static/images/cloud-aws-02.png differ diff --git a/docs/_static/images/cloud-aws-03.png b/docs/_static/images/cloud-aws-03.png new file mode 100644 index 00000000..92d3e63b Binary files /dev/null and b/docs/_static/images/cloud-aws-03.png differ diff --git a/docs/_static/images/cloud-aws-04.png b/docs/_static/images/cloud-aws-04.png new file mode 100644 index 00000000..3ae4fb2a Binary files /dev/null and b/docs/_static/images/cloud-aws-04.png differ diff --git a/docs/_static/images/cloud-aws-05.png b/docs/_static/images/cloud-aws-05.png new file mode 100644 index 00000000..fa3521a6 Binary files /dev/null and b/docs/_static/images/cloud-aws-05.png differ diff --git a/docs/_static/images/cloud-aws-06.png b/docs/_static/images/cloud-aws-06.png new file mode 100644 index 00000000..c8f88ded Binary files /dev/null and b/docs/_static/images/cloud-aws-06.png differ diff --git a/docs/_static/images/cloud-aws-07.png b/docs/_static/images/cloud-aws-07.png new file mode 100644 index 00000000..d9f934ac Binary files /dev/null and b/docs/_static/images/cloud-aws-07.png differ diff --git a/docs/_static/images/cloud-aws-08.png b/docs/_static/images/cloud-aws-08.png new file mode 100644 index 00000000..db3030a0 Binary files /dev/null and b/docs/_static/images/cloud-aws-08.png differ diff --git a/docs/_static/images/cloud-azure-01.png b/docs/_static/images/cloud-azure-01.png new file mode 100644 index 00000000..2c7b1adb Binary files /dev/null and b/docs/_static/images/cloud-azure-01.png differ diff --git a/docs/_static/images/cloud-azure-02.png b/docs/_static/images/cloud-azure-02.png new file mode 100644 index 00000000..286b8689 Binary files /dev/null and b/docs/_static/images/cloud-azure-02.png differ diff --git a/docs/_static/images/cloud-azure-03.png b/docs/_static/images/cloud-azure-03.png new file mode 100644 index 00000000..4661a1fb Binary files /dev/null and b/docs/_static/images/cloud-azure-03.png differ diff --git a/docs/_static/images/cloud-azure-04.png b/docs/_static/images/cloud-azure-04.png new file mode 100644 index 00000000..af12d337 Binary files /dev/null and b/docs/_static/images/cloud-azure-04.png differ diff --git a/docs/_static/images/cloud-azure-05.png b/docs/_static/images/cloud-azure-05.png new file mode 100644 index 00000000..c5a32d2e Binary files /dev/null and b/docs/_static/images/cloud-azure-05.png differ diff --git a/docs/_static/images/cloud-azure-06.png b/docs/_static/images/cloud-azure-06.png new file mode 100644 index 00000000..1cc7cbf1 Binary files /dev/null and b/docs/_static/images/cloud-azure-06.png differ diff --git a/docs/_static/images/cloud-gcp-01.png b/docs/_static/images/cloud-gcp-01.png new file mode 100644 index 00000000..f7681d6e Binary files /dev/null and b/docs/_static/images/cloud-gcp-01.png differ diff --git a/docs/_static/images/cloud-gcp-02.png b/docs/_static/images/cloud-gcp-02.png new file mode 100644 index 00000000..5a17efb4 Binary files /dev/null and b/docs/_static/images/cloud-gcp-02.png differ diff --git a/docs/_static/images/cloud-gcp-03.png b/docs/_static/images/cloud-gcp-03.png new file mode 100644 index 00000000..9881a5a3 Binary files /dev/null and b/docs/_static/images/cloud-gcp-03.png differ diff --git a/docs/_static/images/cloud-gcp-04.png b/docs/_static/images/cloud-gcp-04.png new file mode 100644 index 00000000..61ee2d5e Binary files /dev/null and b/docs/_static/images/cloud-gcp-04.png differ diff --git a/docs/_static/images/cloud-gcp-05.png b/docs/_static/images/cloud-gcp-05.png new file mode 100644 index 00000000..acaafc59 Binary files /dev/null and b/docs/_static/images/cloud-gcp-05.png differ diff --git a/docs/_static/images/dhcp-relay-through-gre-bridge.png b/docs/_static/images/dhcp-relay-through-gre-bridge.png new file mode 100644 index 00000000..1f3e7744 Binary files /dev/null and b/docs/_static/images/dhcp-relay-through-gre-bridge.png differ diff --git a/docs/_static/images/dual-hub-DMVPN.png b/docs/_static/images/dual-hub-DMVPN.png new file mode 100644 index 00000000..51ba9c14 Binary files /dev/null and b/docs/_static/images/dual-hub-DMVPN.png differ diff --git a/docs/_static/images/eve-ng-vyos.png b/docs/_static/images/eve-ng-vyos.png new file mode 100644 index 00000000..fdd196a7 Binary files /dev/null and b/docs/_static/images/eve-ng-vyos.png differ diff --git a/docs/_static/images/firewall-and-vrf-blueprints.png b/docs/_static/images/firewall-and-vrf-blueprints.png new file mode 100644 index 00000000..8c3bf9f2 Binary files /dev/null and b/docs/_static/images/firewall-and-vrf-blueprints.png differ diff --git a/docs/_static/images/firewall-bridge-forward.png b/docs/_static/images/firewall-bridge-forward.png new file mode 100644 index 00000000..1294349b Binary files /dev/null and b/docs/_static/images/firewall-bridge-forward.png differ diff --git a/docs/_static/images/firewall-bridge-input.png b/docs/_static/images/firewall-bridge-input.png new file mode 100644 index 00000000..20a46b2e Binary files /dev/null and b/docs/_static/images/firewall-bridge-input.png differ diff --git a/docs/_static/images/firewall-bridge-output.png b/docs/_static/images/firewall-bridge-output.png new file mode 100644 index 00000000..ab2fd3d7 Binary files /dev/null and b/docs/_static/images/firewall-bridge-output.png differ diff --git a/docs/_static/images/firewall-flowtable-packet-flow.png b/docs/_static/images/firewall-flowtable-packet-flow.png new file mode 100644 index 00000000..fca7e13a Binary files /dev/null and b/docs/_static/images/firewall-flowtable-packet-flow.png differ diff --git a/docs/_static/images/firewall-fwd-packet-flow.png b/docs/_static/images/firewall-fwd-packet-flow.png new file mode 100644 index 00000000..1ca213e8 Binary files /dev/null and b/docs/_static/images/firewall-fwd-packet-flow.png differ diff --git a/docs/_static/images/firewall-gral-packet-flow.png b/docs/_static/images/firewall-gral-packet-flow.png new file mode 100644 index 00000000..4fb5d516 Binary files /dev/null and b/docs/_static/images/firewall-gral-packet-flow.png differ diff --git a/docs/_static/images/firewall-input-packet-flow.png b/docs/_static/images/firewall-input-packet-flow.png new file mode 100644 index 00000000..20d356bd Binary files /dev/null and b/docs/_static/images/firewall-input-packet-flow.png differ diff --git a/docs/_static/images/firewall-netfilter.png b/docs/_static/images/firewall-netfilter.png new file mode 100644 index 00000000..dde3766b Binary files /dev/null and b/docs/_static/images/firewall-netfilter.png differ diff --git a/docs/_static/images/firewall-traditional.png b/docs/_static/images/firewall-traditional.png new file mode 100644 index 00000000..7eb2b49d Binary files /dev/null and b/docs/_static/images/firewall-traditional.png differ diff --git a/docs/_static/images/firewall-zonebased.png b/docs/_static/images/firewall-zonebased.png new file mode 100644 index 00000000..46b2f623 Binary files /dev/null and b/docs/_static/images/firewall-zonebased.png differ diff --git a/docs/_static/images/gns3-01.png b/docs/_static/images/gns3-01.png new file mode 100644 index 00000000..a655d6aa Binary files /dev/null and b/docs/_static/images/gns3-01.png differ diff --git a/docs/_static/images/gns3-02.png b/docs/_static/images/gns3-02.png new file mode 100644 index 00000000..3dffdd2b Binary files /dev/null and b/docs/_static/images/gns3-02.png differ diff --git a/docs/_static/images/gns3-03.png b/docs/_static/images/gns3-03.png new file mode 100644 index 00000000..fcab6c5d Binary files /dev/null and b/docs/_static/images/gns3-03.png differ diff --git a/docs/_static/images/gns3-04.png b/docs/_static/images/gns3-04.png new file mode 100644 index 00000000..afc30131 Binary files /dev/null and b/docs/_static/images/gns3-04.png differ diff --git a/docs/_static/images/gns3-05.png b/docs/_static/images/gns3-05.png new file mode 100644 index 00000000..fee0dc65 Binary files /dev/null and b/docs/_static/images/gns3-05.png differ diff --git a/docs/_static/images/gns3-06.png b/docs/_static/images/gns3-06.png new file mode 100644 index 00000000..c03cd89f Binary files /dev/null and b/docs/_static/images/gns3-06.png differ diff --git a/docs/_static/images/gns3-07.png b/docs/_static/images/gns3-07.png new file mode 100644 index 00000000..89d0a565 Binary files /dev/null and b/docs/_static/images/gns3-07.png differ diff --git a/docs/_static/images/gns3-08.png b/docs/_static/images/gns3-08.png new file mode 100644 index 00000000..aca0ff8a Binary files /dev/null and b/docs/_static/images/gns3-08.png differ diff --git a/docs/_static/images/gns3-09.png b/docs/_static/images/gns3-09.png new file mode 100644 index 00000000..7ae38c30 Binary files /dev/null and b/docs/_static/images/gns3-09.png differ diff --git a/docs/_static/images/gns3-10.png b/docs/_static/images/gns3-10.png new file mode 100644 index 00000000..1ee70d58 Binary files /dev/null and b/docs/_static/images/gns3-10.png differ diff --git a/docs/_static/images/gns3-11.png b/docs/_static/images/gns3-11.png new file mode 100644 index 00000000..7990c73a Binary files /dev/null and b/docs/_static/images/gns3-11.png differ diff --git a/docs/_static/images/gns3-12.png b/docs/_static/images/gns3-12.png new file mode 100644 index 00000000..9ad51f70 Binary files /dev/null and b/docs/_static/images/gns3-12.png differ diff --git a/docs/_static/images/gns3-13.png b/docs/_static/images/gns3-13.png new file mode 100644 index 00000000..5f9dd783 Binary files /dev/null and b/docs/_static/images/gns3-13.png differ diff --git a/docs/_static/images/gns3-14.png b/docs/_static/images/gns3-14.png new file mode 100644 index 00000000..447fcafe Binary files /dev/null and b/docs/_static/images/gns3-14.png differ diff --git a/docs/_static/images/gns3-15.png b/docs/_static/images/gns3-15.png new file mode 100644 index 00000000..956b9edb Binary files /dev/null and b/docs/_static/images/gns3-15.png differ diff --git a/docs/_static/images/gns3-16.png b/docs/_static/images/gns3-16.png new file mode 100644 index 00000000..4f75ffab Binary files /dev/null and b/docs/_static/images/gns3-16.png differ diff --git a/docs/_static/images/gns3-17.png b/docs/_static/images/gns3-17.png new file mode 100644 index 00000000..64eff002 Binary files /dev/null and b/docs/_static/images/gns3-17.png differ diff --git a/docs/_static/images/gns3-20.png b/docs/_static/images/gns3-20.png new file mode 100644 index 00000000..17d92dea Binary files /dev/null and b/docs/_static/images/gns3-20.png differ diff --git a/docs/_static/images/gns3-21.png b/docs/_static/images/gns3-21.png new file mode 100644 index 00000000..e461016a Binary files /dev/null and b/docs/_static/images/gns3-21.png differ diff --git a/docs/_static/images/gns3-215.png b/docs/_static/images/gns3-215.png new file mode 100644 index 00000000..fde268ba Binary files /dev/null and b/docs/_static/images/gns3-215.png differ diff --git a/docs/_static/images/gns3-22.png b/docs/_static/images/gns3-22.png new file mode 100644 index 00000000..6ed52c1d Binary files /dev/null and b/docs/_static/images/gns3-22.png differ diff --git a/docs/_static/images/gowin-01.png b/docs/_static/images/gowin-01.png new file mode 100644 index 00000000..403ce52a Binary files /dev/null and b/docs/_static/images/gowin-01.png differ diff --git a/docs/_static/images/gowin-02.png b/docs/_static/images/gowin-02.png new file mode 100644 index 00000000..413f2948 Binary files /dev/null and b/docs/_static/images/gowin-02.png differ diff --git a/docs/_static/images/gowin-03.png b/docs/_static/images/gowin-03.png new file mode 100644 index 00000000..fbdbb142 Binary files /dev/null and b/docs/_static/images/gowin-03.png differ diff --git a/docs/_static/images/gowin-04.png b/docs/_static/images/gowin-04.png new file mode 100644 index 00000000..c68b8731 Binary files /dev/null and b/docs/_static/images/gowin-04.png differ diff --git a/docs/_static/images/inter-vrf-routing-vrf-lite.png b/docs/_static/images/inter-vrf-routing-vrf-lite.png new file mode 100644 index 00000000..3acefee6 Binary files /dev/null and b/docs/_static/images/inter-vrf-routing-vrf-lite.png differ diff --git a/docs/_static/images/ipsec-vyos-pa.png b/docs/_static/images/ipsec-vyos-pa.png new file mode 100644 index 00000000..0929bcc7 Binary files /dev/null and b/docs/_static/images/ipsec-vyos-pa.png differ diff --git a/docs/_static/images/json.png b/docs/_static/images/json.png new file mode 100644 index 00000000..6c884e8e Binary files /dev/null and b/docs/_static/images/json.png differ diff --git a/docs/_static/images/key.png b/docs/_static/images/key.png new file mode 100644 index 00000000..7d9366f4 Binary files /dev/null and b/docs/_static/images/key.png differ diff --git a/docs/_static/images/keypairs.png b/docs/_static/images/keypairs.png new file mode 100644 index 00000000..7e772ae9 Binary files /dev/null and b/docs/_static/images/keypairs.png differ diff --git a/docs/_static/images/lac-lns-diagram.jpg b/docs/_static/images/lac-lns-diagram.jpg new file mode 100644 index 00000000..4463a3c3 Binary files /dev/null and b/docs/_static/images/lac-lns-diagram.jpg differ diff --git a/docs/_static/images/lac-lns-winclient.jpg b/docs/_static/images/lac-lns-winclient.jpg new file mode 100644 index 00000000..9fa99152 Binary files /dev/null and b/docs/_static/images/lac-lns-winclient.jpg differ diff --git a/docs/_static/images/ldapone.png b/docs/_static/images/ldapone.png new file mode 100644 index 00000000..33ecf628 Binary files /dev/null and b/docs/_static/images/ldapone.png differ diff --git a/docs/_static/images/ldaptwo.png b/docs/_static/images/ldaptwo.png new file mode 100644 index 00000000..7cb9e0cb Binary files /dev/null and b/docs/_static/images/ldaptwo.png differ diff --git a/docs/_static/images/mainschema.png b/docs/_static/images/mainschema.png new file mode 100644 index 00000000..c39e5da2 Binary files /dev/null and b/docs/_static/images/mainschema.png differ diff --git a/docs/_static/images/multicast-basic.png b/docs/_static/images/multicast-basic.png new file mode 100644 index 00000000..3d4a3de3 Binary files /dev/null and b/docs/_static/images/multicast-basic.png differ diff --git a/docs/_static/images/nat_before_vpn_topology.png b/docs/_static/images/nat_before_vpn_topology.png new file mode 100644 index 00000000..ae23c92d Binary files /dev/null and b/docs/_static/images/nat_before_vpn_topology.png differ diff --git a/docs/_static/images/nmp1.png b/docs/_static/images/nmp1.png new file mode 100644 index 00000000..0b761a76 Binary files /dev/null and b/docs/_static/images/nmp1.png differ diff --git a/docs/_static/images/nmp2.png b/docs/_static/images/nmp2.png new file mode 100644 index 00000000..3190a099 Binary files /dev/null and b/docs/_static/images/nmp2.png differ diff --git a/docs/_static/images/nmp3.png b/docs/_static/images/nmp3.png new file mode 100644 index 00000000..0585b80e Binary files /dev/null and b/docs/_static/images/nmp3.png differ diff --git a/docs/_static/images/nmp4.png b/docs/_static/images/nmp4.png new file mode 100644 index 00000000..e0aa893e Binary files /dev/null and b/docs/_static/images/nmp4.png differ diff --git a/docs/_static/images/nmp5.png b/docs/_static/images/nmp5.png new file mode 100644 index 00000000..d3149034 Binary files /dev/null and b/docs/_static/images/nmp5.png differ diff --git a/docs/_static/images/nmp6.png b/docs/_static/images/nmp6.png new file mode 100644 index 00000000..c4645e33 Binary files /dev/null and b/docs/_static/images/nmp6.png differ diff --git a/docs/_static/images/nmp7.png b/docs/_static/images/nmp7.png new file mode 100644 index 00000000..3e518e7e Binary files /dev/null and b/docs/_static/images/nmp7.png differ diff --git a/docs/_static/images/openvpn_site2site_diagram.jpg b/docs/_static/images/openvpn_site2site_diagram.jpg new file mode 100644 index 00000000..05881e7d Binary files /dev/null and b/docs/_static/images/openvpn_site2site_diagram.jpg differ diff --git a/docs/_static/images/pbr_example_1.png b/docs/_static/images/pbr_example_1.png new file mode 100644 index 00000000..3dff6db6 Binary files /dev/null and b/docs/_static/images/pbr_example_1.png differ diff --git a/docs/_static/images/policy-based-ipsec-and-firewall.png b/docs/_static/images/policy-based-ipsec-and-firewall.png new file mode 100644 index 00000000..6e9d43ac Binary files /dev/null and b/docs/_static/images/policy-based-ipsec-and-firewall.png differ diff --git a/docs/_static/images/pppoe-ipv6-pd-diagram.jpg b/docs/_static/images/pppoe-ipv6-pd-diagram.jpg new file mode 100644 index 00000000..430848c8 Binary files /dev/null and b/docs/_static/images/pppoe-ipv6-pd-diagram.jpg differ diff --git a/docs/_static/images/project.png b/docs/_static/images/project.png new file mode 100644 index 00000000..6f844c23 Binary files /dev/null and b/docs/_static/images/project.png differ diff --git a/docs/_static/images/qos1.png b/docs/_static/images/qos1.png new file mode 100644 index 00000000..9c16e6a3 Binary files /dev/null and b/docs/_static/images/qos1.png differ diff --git a/docs/_static/images/qos10.png b/docs/_static/images/qos10.png new file mode 100644 index 00000000..2f90ffe7 Binary files /dev/null and b/docs/_static/images/qos10.png differ diff --git a/docs/_static/images/qos2.png b/docs/_static/images/qos2.png new file mode 100644 index 00000000..4d351344 Binary files /dev/null and b/docs/_static/images/qos2.png differ diff --git a/docs/_static/images/qos3.png b/docs/_static/images/qos3.png new file mode 100644 index 00000000..97efaeb7 Binary files /dev/null and b/docs/_static/images/qos3.png differ diff --git a/docs/_static/images/qos4.png b/docs/_static/images/qos4.png new file mode 100644 index 00000000..b87b256e Binary files /dev/null and b/docs/_static/images/qos4.png differ diff --git a/docs/_static/images/qos5.png b/docs/_static/images/qos5.png new file mode 100644 index 00000000..4a615755 Binary files /dev/null and b/docs/_static/images/qos5.png differ diff --git a/docs/_static/images/qos6.png b/docs/_static/images/qos6.png new file mode 100644 index 00000000..907d6104 Binary files /dev/null and b/docs/_static/images/qos6.png differ diff --git a/docs/_static/images/qos7.png b/docs/_static/images/qos7.png new file mode 100644 index 00000000..03ec5cd1 Binary files /dev/null and b/docs/_static/images/qos7.png differ diff --git a/docs/_static/images/qos8.png b/docs/_static/images/qos8.png new file mode 100644 index 00000000..3566ac00 Binary files /dev/null and b/docs/_static/images/qos8.png differ diff --git a/docs/_static/images/qos9.png b/docs/_static/images/qos9.png new file mode 100644 index 00000000..67d8afd2 Binary files /dev/null and b/docs/_static/images/qos9.png differ diff --git a/docs/_static/images/reset-password-step-1.jpg b/docs/_static/images/reset-password-step-1.jpg new file mode 100644 index 00000000..3b6f7703 Binary files /dev/null and b/docs/_static/images/reset-password-step-1.jpg differ diff --git a/docs/_static/images/reset-password-step-2.jpg b/docs/_static/images/reset-password-step-2.jpg new file mode 100644 index 00000000..265bc73b Binary files /dev/null and b/docs/_static/images/reset-password-step-2.jpg differ diff --git a/docs/_static/images/reset-password-step-3.jpg b/docs/_static/images/reset-password-step-3.jpg new file mode 100644 index 00000000..98795757 Binary files /dev/null and b/docs/_static/images/reset-password-step-3.jpg differ diff --git a/docs/_static/images/reset-password-step-4.jpg b/docs/_static/images/reset-password-step-4.jpg new file mode 100644 index 00000000..6f70ea24 Binary files /dev/null and b/docs/_static/images/reset-password-step-4.jpg differ diff --git a/docs/_static/images/reset-password-step-5.jpg b/docs/_static/images/reset-password-step-5.jpg new file mode 100644 index 00000000..70c586e2 Binary files /dev/null and b/docs/_static/images/reset-password-step-5.jpg differ diff --git a/docs/_static/images/service.png b/docs/_static/images/service.png new file mode 100644 index 00000000..e2a9bbbc Binary files /dev/null and b/docs/_static/images/service.png differ diff --git a/docs/_static/images/service_conntrack_sync-schema.png b/docs/_static/images/service_conntrack_sync-schema.png new file mode 100644 index 00000000..1b5fe8fb Binary files /dev/null and b/docs/_static/images/service_conntrack_sync-schema.png differ diff --git a/docs/_static/images/service_dhcp-relay01.png b/docs/_static/images/service_dhcp-relay01.png new file mode 100644 index 00000000..cd7f30cf Binary files /dev/null and b/docs/_static/images/service_dhcp-relay01.png differ diff --git a/docs/_static/images/service_dhcpv6-relay01.png b/docs/_static/images/service_dhcpv6-relay01.png new file mode 100644 index 00000000..9a10a10f Binary files /dev/null and b/docs/_static/images/service_dhcpv6-relay01.png differ diff --git a/docs/_static/images/service_snmp_communication_principles_diagram.png b/docs/_static/images/service_snmp_communication_principles_diagram.png new file mode 100644 index 00000000..eff2ce45 Binary files /dev/null and b/docs/_static/images/service_snmp_communication_principles_diagram.png differ diff --git a/docs/_static/images/sg.png b/docs/_static/images/sg.png new file mode 100644 index 00000000..8be51e1f Binary files /dev/null and b/docs/_static/images/sg.png differ diff --git a/docs/_static/images/sticky-connections.jpg b/docs/_static/images/sticky-connections.jpg new file mode 100644 index 00000000..25fd72a9 Binary files /dev/null and b/docs/_static/images/sticky-connections.jpg differ diff --git a/docs/_static/images/traffic.png b/docs/_static/images/traffic.png new file mode 100644 index 00000000..74002b16 Binary files /dev/null and b/docs/_static/images/traffic.png differ diff --git a/docs/_static/images/uefi_secureboot_01.png b/docs/_static/images/uefi_secureboot_01.png new file mode 100644 index 00000000..02ec56b0 Binary files /dev/null and b/docs/_static/images/uefi_secureboot_01.png differ diff --git a/docs/_static/images/uefi_secureboot_02.png b/docs/_static/images/uefi_secureboot_02.png new file mode 100644 index 00000000..336d654d Binary files /dev/null and b/docs/_static/images/uefi_secureboot_02.png differ diff --git a/docs/_static/images/uefi_secureboot_03.png b/docs/_static/images/uefi_secureboot_03.png new file mode 100644 index 00000000..ff126842 Binary files /dev/null and b/docs/_static/images/uefi_secureboot_03.png differ diff --git a/docs/_static/images/uefi_secureboot_04.png b/docs/_static/images/uefi_secureboot_04.png new file mode 100644 index 00000000..90242299 Binary files /dev/null and b/docs/_static/images/uefi_secureboot_04.png differ diff --git a/docs/_static/images/uefi_secureboot_05.png b/docs/_static/images/uefi_secureboot_05.png new file mode 100644 index 00000000..b08cb946 Binary files /dev/null and b/docs/_static/images/uefi_secureboot_05.png differ diff --git a/docs/_static/images/uefi_secureboot_06.png b/docs/_static/images/uefi_secureboot_06.png new file mode 100644 index 00000000..784f0eed Binary files /dev/null and b/docs/_static/images/uefi_secureboot_06.png differ diff --git a/docs/_static/images/uefi_secureboot_07.png b/docs/_static/images/uefi_secureboot_07.png new file mode 100644 index 00000000..6ff450b4 Binary files /dev/null and b/docs/_static/images/uefi_secureboot_07.png differ diff --git a/docs/_static/images/virt-libvirt-01.png b/docs/_static/images/virt-libvirt-01.png new file mode 100644 index 00000000..06baea8e Binary files /dev/null and b/docs/_static/images/virt-libvirt-01.png differ diff --git a/docs/_static/images/virt-libvirt-02.png b/docs/_static/images/virt-libvirt-02.png new file mode 100644 index 00000000..b6c4b379 Binary files /dev/null and b/docs/_static/images/virt-libvirt-02.png differ diff --git a/docs/_static/images/virt-libvirt-03.png b/docs/_static/images/virt-libvirt-03.png new file mode 100644 index 00000000..ac3891f0 Binary files /dev/null and b/docs/_static/images/virt-libvirt-03.png differ diff --git a/docs/_static/images/virt-libvirt-04.png b/docs/_static/images/virt-libvirt-04.png new file mode 100644 index 00000000..b1218597 Binary files /dev/null and b/docs/_static/images/virt-libvirt-04.png differ diff --git a/docs/_static/images/virt-libvirt-05.png b/docs/_static/images/virt-libvirt-05.png new file mode 100644 index 00000000..5579c281 Binary files /dev/null and b/docs/_static/images/virt-libvirt-05.png differ diff --git a/docs/_static/images/virt-libvirt-06.png b/docs/_static/images/virt-libvirt-06.png new file mode 100644 index 00000000..e0983d23 Binary files /dev/null and b/docs/_static/images/virt-libvirt-06.png differ diff --git a/docs/_static/images/virt-libvirt-qc-01.png b/docs/_static/images/virt-libvirt-qc-01.png new file mode 100644 index 00000000..49867bd0 Binary files /dev/null and b/docs/_static/images/virt-libvirt-qc-01.png differ diff --git a/docs/_static/images/virt-libvirt-qc-02.png b/docs/_static/images/virt-libvirt-qc-02.png new file mode 100644 index 00000000..a71b8f64 Binary files /dev/null and b/docs/_static/images/virt-libvirt-qc-02.png differ diff --git a/docs/_static/images/virt-libvirt-qc-03.png b/docs/_static/images/virt-libvirt-qc-03.png new file mode 100644 index 00000000..4eefaa58 Binary files /dev/null and b/docs/_static/images/virt-libvirt-qc-03.png differ diff --git a/docs/_static/images/vpn_dmvpn_topology01.png b/docs/_static/images/vpn_dmvpn_topology01.png new file mode 100644 index 00000000..17433be6 Binary files /dev/null and b/docs/_static/images/vpn_dmvpn_topology01.png differ diff --git a/docs/_static/images/vpn_s2s_ikev2.png b/docs/_static/images/vpn_s2s_ikev2.png new file mode 100644 index 00000000..f8050e3a Binary files /dev/null and b/docs/_static/images/vpn_s2s_ikev2.png differ diff --git a/docs/_static/images/vpn_s2s_ikev2_c.png b/docs/_static/images/vpn_s2s_ikev2_c.png new file mode 100644 index 00000000..2d9e21b5 Binary files /dev/null and b/docs/_static/images/vpn_s2s_ikev2_c.png differ diff --git a/docs/_static/images/vrf-example-topology-01.png b/docs/_static/images/vrf-example-topology-01.png new file mode 100644 index 00000000..57357509 Binary files /dev/null and b/docs/_static/images/vrf-example-topology-01.png differ diff --git a/docs/_static/images/vyos-downloads.png b/docs/_static/images/vyos-downloads.png new file mode 100644 index 00000000..6bad2b19 Binary files /dev/null and b/docs/_static/images/vyos-downloads.png differ diff --git a/docs/_static/images/vyos-sr-isis.png b/docs/_static/images/vyos-sr-isis.png new file mode 100644 index 00000000..62430919 Binary files /dev/null and b/docs/_static/images/vyos-sr-isis.png differ diff --git a/docs/_static/images/vyos_1_4_nat66_simple.png b/docs/_static/images/vyos_1_4_nat66_simple.png new file mode 100644 index 00000000..d7c54115 Binary files /dev/null and b/docs/_static/images/vyos_1_4_nat66_simple.png differ diff --git a/docs/_static/images/vyos_1_5_nat66_dhcpv6_wdummy.png b/docs/_static/images/vyos_1_5_nat66_dhcpv6_wdummy.png new file mode 100644 index 00000000..297fdd11 Binary files /dev/null and b/docs/_static/images/vyos_1_5_nat66_dhcpv6_wdummy.png differ diff --git a/docs/_static/images/vyos_arista_bond_lacp.png b/docs/_static/images/vyos_arista_bond_lacp.png new file mode 100644 index 00000000..6c9ef8ec Binary files /dev/null and b/docs/_static/images/vyos_arista_bond_lacp.png differ diff --git a/docs/_static/images/vyosnew-downloads.png b/docs/_static/images/vyosnew-downloads.png new file mode 100644 index 00000000..294a4589 Binary files /dev/null and b/docs/_static/images/vyosnew-downloads.png differ diff --git a/docs/_static/images/wireguard_qrcode.jpg b/docs/_static/images/wireguard_qrcode.jpg new file mode 100644 index 00000000..0a9a98c0 Binary files /dev/null and b/docs/_static/images/wireguard_qrcode.jpg differ diff --git a/docs/_static/images/wireguard_site2site_diagram.jpg b/docs/_static/images/wireguard_site2site_diagram.jpg new file mode 100644 index 00000000..4a7a95e4 Binary files /dev/null and b/docs/_static/images/wireguard_site2site_diagram.jpg differ diff --git a/docs/_static/images/zone-policy-diagram.png b/docs/_static/images/zone-policy-diagram.png new file mode 100644 index 00000000..cfde4af6 Binary files /dev/null and b/docs/_static/images/zone-policy-diagram.png differ diff --git a/docs/_swap.txt b/docs/_swap.txt deleted file mode 100644 index 3ffcdaf6..00000000 --- a/docs/_swap.txt +++ /dev/null @@ -1,262 +0,0 @@ -# Incremental MyST swap list -# One page stem per line (relative to docs/, no extension) -# Pages listed here will render from MD instead of RST at build time. -# -# Default: every imported md-*.md page is listed below so MD is served -# by default. To revert a specific page back to RST, remove its line -# (or comment it out). - -404 -automation/cloud-init -automation/command-scripting -automation/index -automation/terraform/index -automation/terraform/terraformAWS -automation/terraform/terraformAZ -automation/terraform/terraformGoogle -automation/terraform/terraformvSphere -automation/vyos-ansible -automation/vyos-api -automation/vyos-govyos -automation/vyos-napalm -automation/vyos-netmiko -automation/vyos-pyvyos -automation/vyos-salt -cli -configexamples/ansible -configexamples/autotest/DHCPRelay_through_GRE/DHCPRelay_through_GRE -configexamples/autotest/L3VPN_EVPN/L3VPN_EVPN -configexamples/autotest/OpenVPN_with_LDAP/OpenVPN_with_LDAP -configexamples/autotest/Wireguard/Wireguard -configexamples/autotest/tunnelbroker/tunnelbroker -configexamples/azure-vpn-bgp -configexamples/azure-vpn-dual-bgp -configexamples/bgp-ipv6-unnumbered -configexamples/dmvpn-dualhub-dualcloud -configexamples/firewall -configexamples/fwall-and-bridge -configexamples/fwall-and-vrf -configexamples/ha -configexamples/index -configexamples/inter-vrf-routing-vrf-lite -configexamples/ipsec-cisco-policy-based -configexamples/ipsec-cisco-route-based -configexamples/ipsec-pa-route-based -configexamples/l3vpn-hub-and-spoke -configexamples/lac-lns -configexamples/nmp -configexamples/ospf-unnumbered -configexamples/policy-based-ipsec-and-firewall -configexamples/pppoe-ipv6-basic -configexamples/qos -configexamples/segment-routing-isis -configexamples/site-2-site-cisco -configexamples/wan-load-balancing -configexamples/zone-policy -configuration/container/index -configuration/firewall/bridge -configuration/firewall/flowtables -configuration/firewall/global-options -configuration/firewall/groups -configuration/firewall/index -configuration/firewall/ipv4 -configuration/firewall/ipv6 -configuration/firewall/zone -configuration/highavailability/index -configuration/index -configuration/interfaces/bonding -configuration/interfaces/bridge -configuration/interfaces/dummy -configuration/interfaces/ethernet -configuration/interfaces/geneve -configuration/interfaces/index -configuration/interfaces/l2tpv3 -configuration/interfaces/loopback -configuration/interfaces/macsec -configuration/interfaces/openvpn -configuration/interfaces/openvpn-examples -configuration/interfaces/pppoe -configuration/interfaces/pseudo-ethernet -configuration/interfaces/sstp-client -configuration/interfaces/tunnel -configuration/interfaces/virtual-ethernet -configuration/interfaces/vti -configuration/interfaces/vxlan -configuration/interfaces/wireguard -configuration/interfaces/wireless -configuration/interfaces/wwan -configuration/loadbalancing/haproxy -configuration/loadbalancing/index -configuration/loadbalancing/wan -configuration/nat/cgnat -configuration/nat/index -configuration/nat/nat44 -configuration/nat/nat64 -configuration/nat/nat66 -configuration/pki/index -configuration/policy/access-list -configuration/policy/as-path-list -configuration/policy/community-list -configuration/policy/examples -configuration/policy/extcommunity-list -configuration/policy/index -configuration/policy/large-community-list -configuration/policy/local-route -configuration/policy/prefix-list -configuration/policy/route -configuration/policy/route-map -configuration/protocols/arp -configuration/protocols/babel -configuration/protocols/bfd -configuration/protocols/bgp -configuration/protocols/failover -configuration/protocols/igmp-proxy -configuration/protocols/index -configuration/protocols/isis -configuration/protocols/mpls -configuration/protocols/multicast -configuration/protocols/openfabric -configuration/protocols/ospf -configuration/protocols/pim -configuration/protocols/pim6 -configuration/protocols/rip -configuration/protocols/rpki -configuration/protocols/segment-routing -configuration/protocols/static -configuration/protocols/traffic-engineering -configuration/service/broadcast-relay -configuration/service/config-sync -configuration/service/conntrack-sync -configuration/service/console-server -configuration/service/dhcp-relay -configuration/service/dhcp-server -configuration/service/dns -configuration/service/eventhandler -configuration/service/https -configuration/service/index -configuration/service/ipoe-server -configuration/service/lldp -configuration/service/mdns -configuration/service/monitoring -configuration/service/ntp -configuration/service/pppoe-server -configuration/service/router-advert -configuration/service/salt-minion -configuration/service/snmp -configuration/service/ssh -configuration/service/suricata -configuration/service/tftp-server -configuration/service/webproxy -configuration/system/acceleration -configuration/system/conntrack -configuration/system/console -configuration/system/default-route -configuration/system/flow-accounting -configuration/system/frr -configuration/system/host-name -configuration/system/index -configuration/system/ip -configuration/system/ipv6 -configuration/system/lcd -configuration/system/login -configuration/system/name-server -configuration/system/option -configuration/system/proxy -configuration/system/sflow -configuration/system/sysctl -configuration/system/syslog -configuration/system/task-scheduler -configuration/system/time-zone -configuration/system/updates -configuration/system/watchdog -configuration/trafficpolicy/index -configuration/vpn/dmvpn -configuration/vpn/index -configuration/vpn/ipsec/index -configuration/vpn/ipsec/ipsec_general -configuration/vpn/ipsec/remoteaccess_ipsec -configuration/vpn/ipsec/site2site_ipsec -configuration/vpn/ipsec/troubleshooting_ipsec -configuration/vpn/l2tp -configuration/vpn/openconnect -configuration/vpn/pptp -configuration/vpn/rsa-keys -configuration/vpn/sstp -configuration/vrf/index -contributing/build-vyos -contributing/cla -contributing/debugging -contributing/development -contributing/index -contributing/issues-features -contributing/testing -contributing/upstream-packages -coverage -documentation -index -installation/bare-metal -installation/cloud/aws -installation/cloud/azure -installation/cloud/gcp -installation/cloud/index -installation/cloud/oracle -installation/image -installation/index -installation/install -installation/secure-boot -installation/update -installation/virtual/docker -installation/virtual/eve-ng -installation/virtual/gns3 -installation/virtual/index -installation/virtual/libvirt -installation/virtual/proxmox -installation/virtual/vmware -introducing/about -introducing/history -operation/boot-options -operation/index -operation/information -operation/password-recovery -operation/raid -operation/upgrade-recovery -quick-start -troubleshooting/connectivity -troubleshooting/index -troubleshooting/interfaces -troubleshooting/monitoring -troubleshooting/system -troubleshooting/terminal -vpp/configuration/acl -vpp/configuration/dataplane/buffers -vpp/configuration/dataplane/cpu -vpp/configuration/dataplane/index -vpp/configuration/dataplane/interface -vpp/configuration/dataplane/ipsec -vpp/configuration/dataplane/ipv6 -vpp/configuration/dataplane/l2learn -vpp/configuration/dataplane/lcp -vpp/configuration/dataplane/logging -vpp/configuration/dataplane/memory -vpp/configuration/dataplane/system -vpp/configuration/dataplane/unix -vpp/configuration/index -vpp/configuration/interfaces/bonding -vpp/configuration/interfaces/bridge -vpp/configuration/interfaces/gre -vpp/configuration/interfaces/index -vpp/configuration/interfaces/ipip -vpp/configuration/interfaces/loopback -vpp/configuration/interfaces/vxlan -vpp/configuration/interfaces/xconnect -vpp/configuration/ipfix -vpp/configuration/ipsec -vpp/configuration/nat/cgnat -vpp/configuration/nat/index -vpp/configuration/nat/nat44 -vpp/configuration/sflow -vpp/description -vpp/index -vpp/limitations -vpp/requirements -vpp/troubleshooting diff --git a/docs/automation/md-cloud-init.md b/docs/automation/md-cloud-init.md deleted file mode 100644 index b6350b54..00000000 --- a/docs/automation/md-cloud-init.md +++ /dev/null @@ -1,378 +0,0 @@ ---- -lastproofread: '2026-04-13' ---- - -(cloud-init)= - -# VyOS cloud-init - -VyOS instances in cloud and virtualized environments are initialized using the -industry-standard `cloud-init`. Through `cloud-init`, VyOS injects SSH -keys, configures network settings, and applies custom configurations during the -initial instance boot. - -## Configuration sources - -VyOS `cloud-init` obtains configuration data from the following sources: - -- `meta-data`: Instance-specific details provided by the cloud platform or - hypervisor. In some cloud environments, this data is available via an HTTP - endpoint at `http://169.254.169.254`. -- `network configuration`: Network settings such as IP addresses, routes, and - DNS (only available on certain cloud and virtualization platforms). -- `user-data`: User-supplied CLI configuration commands. - -## User-data - -Major cloud providers support injecting `user-data` as plain text or base64 -encoding text during initial instance boot. As `user-data` has a strict size -limit of \~16384 bytes, long configuration command lists can be compressed using -`gzip`. - -The recommended method for configuring VyOS instances via `user-data` is to -use the `cloud-config` syntax described below. - -## Cloud-config modules - -By default, VyOS enables only two `cloud-config` modules: - -- `write_files`: Inserts user-provided files such as encryption keys, - certificates, or `config.boot` into the filesystem during the initial - instance boot. See [Cloud-init-write_files] for file syntax and file format - requirements. -- `vyos_userdata`: Executes user-provided CLI configuration commands during - the initial instance boot. - -The files to insert and the CLI commands to execute must be provided in a -`cloud-config` YAML file. - -## Cloud-config file format - -`cloud-config` files are written in YAML and must begin with the -`#cloud-config` line. Only `vyos_config_commands` and `write_files` are -supported as top-level keys. The use of these keys is described in the -following two sections. - -## Vyos_config_commands key - -Use the `vyos_config_commands` key to define configuration commands for -initializing your VyOS instance. Commands must follow the set-style syntax -and can include both `set` and `delete` statements. - -Syntax requirements: - -- Place one command per line. -- Enclose values in single quotes. -- Avoid single quotes within commands or values. - -Applying commands from `cloud-config` overrides both settings configured via -`meta-data` and default VyOS settings. After commands are applied, -`cloud-init` automatically performs `commit` and `save`. - -The following is an example of a `cloud-config` file: - -```yaml -#cloud-config -vyos_config_commands: - - set system host-name 'vyos-prod-ashburn' - - set service ntp server 1.pool.ntp.org - - set service ntp server 2.pool.ntp.org - - delete interfaces ethernet eth1 address 'dhcp' - - set interfaces ethernet eth1 address '192.0.2.247/24' - - set protocols static route 198.51.100.0/24 next-hop '192.0.2.1' -``` - - -### Instance defaults/fallbacks - -If no external configuration data is provided, VyOS applies the following -defaults: - -- **SSH:** port 22. -- **Credentials:** `vyos`/`vyos`. -- **Networking:** DHCP is enabled on the first Ethernet interface. - -All defaults can be overridden via `user-data` configurations. - -## Write_files key - -VyOS allows you to run custom scripts during the initial instance boot to -execute operational, configuration, and standard Linux commands. - -Use the `write_files` key to insert these scripts into the -`/opt/vyatta/etc/config/scripts/` directory. - -Depending on when your commands need to run, use one of the following paths: - -- `/opt/vyatta/etc/config/scripts/vyos-preconfig-bootup.script`: Commands - defined here are executed before the system configuration is applied. -- `/opt/vyatta/etc/config/scripts/vyos-postconfig-bootup.script`: Commands - defined here are executed after the system configuration is applied. - -In both cases, commands are executed with `root` privileges. - -:::{note} -Use the `/opt/vyatta/etc/config/` path instead of `/config/scripts/` as -referenced in the {ref}`command-scripting` section. The `/config/scripts/` -directory is not mounted when the `write_files` module runs. -::: - -The following example shows how to use `write_files` to execute an -operational command **after** the initial configuration is complete: - -```yaml -#cloud-config -write_files: - - path: /opt/vyatta/etc/config/scripts/vyos-postconfig-bootup.script - owner: root:vyattacfg - permissions: '0775' - content: | - #!/bin/vbash - source /opt/vyatta/etc/functions/script-template - filename=/tmp/bgp_status_`date +"%Y_%m_%d_%I_%M_%p"`.log - run show ip bgp summary >> $filename -``` - -You can combine standard Linux commands to fetch data and VyOS configuration -commands (like `set` and `commit`) in the same script. - -The following example sets the `hostname` based on the instance identifier -obtained from the EC2 Instance Metadata Service (IMDS). - -```yaml -#cloud-config -write_files: - - path: /opt/vyatta/etc/config/scripts/vyos-postconfig-bootup.script - owner: root:vyattacfg - permissions: '0775' - content: | - #!/bin/vbash - source /opt/vyatta/etc/functions/script-template - hostname=`curl -s http://169.254.169.254/latest/meta-data/instance-id` - configure - set system host-name $hostname - commit - exit -``` - - -## NoCloud - -Injecting configuration data is not limited to cloud platforms. The NoCloud -data source allows you to inject `user-data` and `meta-data` on -virtualization platforms such as VMware, Hyper-V, and KVM. - -The simplest way to use the NoCloud data source is to create a `seed.iso` -file and attach it to the virtual machine as a CD drive. The volume must be -formatted as a VFAT or ISO 9660 file system with the label `cidata` or -`CIDATA`. - -Create text files named `user-data` and `meta-data`. On Linux-based -systems, use the `mkisofs` utility to create the `seed.iso` file. The -following syntax adds these files to the ISO 9660 file system: - -```none -mkisofs -joliet -rock -volid "cidata" -output seed.iso meta-data user-data -``` - -Once generated, attach the `seed.iso` file to your virtual machine. The -following example shows how to attach the file as a CD drive using KVM: - -```none -$ virt-install -n vyos_r1 \ - --ram 4096 \ - --vcpus 2 \ - --cdrom seed.iso \ - --os-type linux \ - --os-variant debian10 \ - --network network=default \ - --graphics vnc \ - --hvm \ - --virt-type kvm \ - --disk path=/var/lib/libvirt/images/vyos_kvm.qcow2,bus=virtio \ - --import \ - --noautoconsole -``` - -For more information on the NoCloud data source, visit the [NoCloud] page in -the `cloud-init` documentation. - -## Troubleshooting - -If your configuration does not apply as expected, follow these troubleshooting -steps: - -1. **Validate your YAML**: Ensure your `cloud-config` file follows proper - YAML syntax. Online resources such as [YAML Lint](https://www.yamllint.com/) - provide simple validation tools. -2. **Check the logs**: `cloud-init` writes logs to `/var/log/cloud-init.log`. - Filter for VyOS-specific entries using: - -```none -sudo grep vyos /var/log/cloud-init.log -``` - - -## Cloud-init on Proxmox - -Before you begin, review the `cloud-init` [network-config-docs] to -understand how to import user and network configuration data. - -Key considerations: - -- Define VyOS configuration commands in the `user-data` file. -- Avoid including network configuration data in the `user-data` file. -- If no network configuration data is provided, the DHCP client is enabled on - the first interface. This happens at the OS level and is not reflected in the - VyOS CLI. - -The following example shows how to disable the DHCP client on `eth0` to -address this behavior. - -In this example: - -- **Proxmox IP address**: `192.168.0.253/24`. -- **Storage**: The `local` volume is mounted at `/var/lib/vz` and contains - all content types, including snippets. - -The goal is to remove the default DHCP client from the first interface and -apply a custom configuration during the initial instance boot using -`cloud-init`. - -### Generate .qcow2 image - -First, generate a VyOS `.qcow2` image with `cloud-init` support from the -[vyos-vm-images] repository: - -1. Clone the `vyos-vm-images` repository and comment out the `download-iso` - role in `qemu.yml`. -2. Download your preferred VyOS `.iso` file and save it as `/tmp/vyos.iso`. -3. Generate the `.qcow2` image (using a 10G disk size for this example): - -```sh -sudo ansible-playbook qemu.yml -e disk_size=10 \ - -e iso_local=/tmp/vyos.iso -e grub_console=serial -e vyos_version=1.5.0 \ - -e cloud_init=true -e cloud_init_ds=NoCloud -``` - -This generates your new image at `/tmp/vyos-1.5.0-cloud-init-10G-qemu.qcow2`. - -4. Copy the resulting image to the Proxmox server: - -```sh -sudo scp /tmp/vyos-1.5.0-cloud-init-10G-qemu.qcow2 root@192.168.0.253:/tmp/ -``` - - -### Prepare cloud-init files - -Create the following files on your Proxmox server to proceed with this setup: - -- `user-data`: Contains VyOS configuration commands. -- `network-config`: Disables the DHCP client on the first interface. -- `meta-data`: An empty file (required by `cloud-init`). - -All files must be placed in the `/tmp/` directory. - -Follow these steps to create the required files: - -1. Navigate to the `/tmp/` directory: - - ```sh - cd /tmp/ - ``` - -2. Create the `user-data` file. Begin the file with `#cloud-config` and - include VyOS configuration commands. - - ```none - #cloud-config - vyos_config_commands: - - set system host-name 'vyos-BRAS' - - set service ntp server '1.pool.ntp.org' - - set service ntp server '2.pool.ntp.org' - - delete interfaces ethernet eth0 address 'dhcp' - - set interfaces ethernet eth0 address '198.51.100.2/30' - - set interfaces ethernet eth0 description 'WAN - ISP01' - - set interfaces ethernet eth1 address '192.168.25.1/24' - - set interfaces ethernet eth1 description 'Coming through VLAN 25' - - set interfaces ethernet eth2 address '192.168.26.1/24' - - set interfaces ethernet eth2 description 'Coming through VLAN 26' - - set protocols static route 0.0.0.0/0 next-hop '198.51.100.1' - ``` - -3. Create the `network-config` file. Include the following: - - ```none - version: 2 - ethernets: - eth0: - dhcp4: false - dhcp6: false - ``` - -4. Create the required empty `meta-data` file. - -### Create seed.iso - -Once you have created the necessary files, generate the `seed.iso` image and -mount it as a CD drive to the new VM. - -```sh -mkisofs -joliet -rock -volid "cidata" -output seed.iso meta-data \ -user-data network-config -``` - -:::{note} -Be careful while copying and pasting the above commands. Double quotes may need -to be corrected. -::: - -### Create the VM - -Note that the following settings apply to this particular example and may -require adjustment for other setups: - -- **VM ID**: `555`. -- **VM and .iso file storage**: The local volume (`directory` type, - mounted at `/var/lib/vz`). -- **VM resources**: Can be modified as needed. - -The `seed.iso` file was previously created in the `/tmp/` directory. Move -it to `/var/lib/vz/template/iso`: - -```sh -mv /tmp/seed.iso /var/lib/vz/template/iso/ -``` - -On the Proxmox server: - -```none -## Create VM, import disk and define boot order -qm create 555 --name vyos-1.5.0-cloudinit --memory 1024 --net0 virtio,bridge=vmbr0 -qm importdisk 555 vyos-1.5.0-cloud-init-10G-qemu.qcow2 local -qm set 555 --virtio0 local:555/vm-555-disk-0.raw -qm set 555 --boot order=virtio0 - -## Import seed.iso for cloud init -qm set 555 --ide2 media=cdrom,file=local:iso/seed.iso - -## Since this server has 1 nic, lets add network intefaces (vlan 25 and 26) -qm set 555 --net1 virtio,bridge=vmbr0,firewall=1,tag=25 -qm set 555 --net2 virtio,bridge=vmbr0,firewall=1,tag=26 -``` - - -### Power on and verify the VM - -Power on the VM using the CLI or GUI. After it boots, verify the configuration. - -### References - -- Cloud-init [network-config-docs]. -- Proxmox [Cloud-init-Support]. -[cloud-init-support]: -[cloud-init-write_files]: https://cloudinit.readthedocs.io/en/latest/topics/examples.html#writing-out-arbitrary-files -[network-config-docs]: https://cloudinit.readthedocs.io/en/latest/topics/network-config.html -[nocloud]: https://cloudinit.readthedocs.io/en/latest/reference/datasources/nocloud.html -[vyos-vm-images]: https://github.com/vyos/vyos-vm-images diff --git a/docs/automation/md-command-scripting.md b/docs/automation/md-command-scripting.md deleted file mode 100644 index 7e736152..00000000 --- a/docs/automation/md-command-scripting.md +++ /dev/null @@ -1,225 +0,0 @@ ---- -lastproofread: '2026-03-16' ---- - -(command-scripting)= - -# Command scripting - -VyOS supports executing configuration and operational commands non-interactively -from shell scripts. - -To include VyOS-specific functions and aliases, source the -`/opt/vyatta/etc/functions/script-template` file at the beginning of your -script. - -```none -#!/bin/vbash -source /opt/vyatta/etc/functions/script-template -exit -``` - - -## Script execute permissions - -Simply placing script files in `/config/scripts/` does not mean the system -can execute them. - -To make your scripts executable, grant them **execute permissions**. Use the -following command: - -```none -chmod +x /config/scripts/script-name.sh -``` - - -## Run configuration commands - -In scripts, present configuration commands as in a standard configuration -session. - -For example, to disable a BGP peer during a VRRP transition to the backup -state, use the following syntax: - -```none -#!/bin/vbash -source /opt/vyatta/etc/functions/script-template -configure -set protocols bgp system-as 65536 -set protocols bgp neighbor 192.168.2.1 shutdown -commit -exit -``` - - -## Run operational commands - -In scripts, **always** prefix operational commands with `run`. - -```none -#!/bin/vbash -source /opt/vyatta/etc/functions/script-template -run show interfaces -exit -``` - - -## Run commands remotely - -You can execute multiple **operational commands** on a remote VyOS system by -passing a script block over SSH. - -```none -ssh 192.0.2.1 'vbash -s' < -[salt]: https://docs.saltproject.io/en/latest/contents.html diff --git a/docs/automation/terraform/md-index.md b/docs/automation/terraform/md-index.md deleted file mode 100644 index dc787db1..00000000 --- a/docs/automation/terraform/md-index.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -lastproofread: '2026-03-23' ---- - -# VyOS Terraform - -VyOS supports development infrastructure via Terraform and provisioning -via Ansible. -Terraform allows you to automate the deployment of instances on a number of -cloud and virtual platforms. This section shows how to deploy VyOS on -multiple platforms: AWS, Microsoft Azure, Google Cloud Platform (GCP), -and VMware vSphere. -For more information, see the -official documentation for [Terraform] and [Ansible]. - -```{toctree} -:caption: Guides -:maxdepth: 1 - -terraformvyos -terraformAWS -terraformAZ -terraformGoogle -terraformvSphere -``` - -[ansible]: https://docs.ansible.com -[install]: https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli -[terraform]: https://developer.hashicorp.com/terraform/intro diff --git a/docs/automation/terraform/md-terraformAWS.md b/docs/automation/terraform/md-terraformAWS.md deleted file mode 100644 index 488e7926..00000000 --- a/docs/automation/terraform/md-terraformAWS.md +++ /dev/null @@ -1,548 +0,0 @@ ---- -lastproofread: '2026-03-16' ---- - -(terraformaws)= - -# Deploy VyOS on AWS with Terraform and Ansible - -You can use Terraform to quickly deploy VyOS-based infrastructure -on AWS and remove infrastructure when it's no longer needed. -Additionally, you can use Ansible for provisioning. - -```{eval-rst} -.. image:: /_static/images/aws.webp - :width: 50% - :align: center - :alt: Network Topology Diagram -``` - -On this page you'll learn how to: -- Create the necessary files for Terraform and Ansible. -- Use Terraform to create a single instance on AWS and use Ansible for - provisioning. - -## Prepare to deploy VyOS with Terraform on AWS - -To create a single instance and install your configuration using -Terraform, Ansible, and AWS, follow these steps: - -### AWS - -1. Create an account with AWS and get your `access_key` and `secret_key`. -2. Create a key [pair] and download your `.pem` key. - -```{eval-rst} -.. image:: /_static/images/keypairs.webp - :width: 50% - :align: center - :alt: Network Topology Diagram -``` - -3. Create a security [group] for the new VyOS instance and open all traffic. - -```{eval-rst} -.. image:: /_static/images/sg.webp - :width: 50% - :align: center - :alt: Network Topology Diagram -``` - -```{eval-rst} -.. image:: /_static/images/traffic.webp - :width: 50% - :align: center - :alt: Network Topology Diagram -``` - - -### Terraform - -```{eval-rst} -1. Create an UNIX or Windows instance. - -2. Download and install - `Terraform `__. - -3. Create a folder, for example ``/root/awsterraform``: - - .. code-block:: none - - mkdir /root/awsterraform - -.. stop_vyoslinter - -4. Copy all files into your Terraform project - (``vyos.tf``, ``var.tf``, ``terraform.tfvars``, ``version.tf``). - See `Structure of files in Terraform for AWS <#structure-of-files-in-terraform-for-aws>`__ for more details. - -.. start_vyoslinter - -5. Run the following commands: - -.. code-block:: none - - cd / - terraform init -``` - -### Ansible - -```{eval-rst} -1. Create a UNIX instance whenever you need. - -2. Download and install Ansible - -3. Create a folder, for example ``/root/aws/``. - -.. stop_vyoslinter - -4. Copy all files into your Ansible project - (``ansible.cfg``, ``instance.yml``, - ``mykey.pem``, and ``all``). - See `Structure of files in Ansible for AWS <#structure-of-files-in-ansible-for-aws>`__ for more details. - You can obtain ``mykey.pem`` by creating a key `pair `__ in AWS and - downloading your ``.pem`` key. -``` - -### Deploy with Terraform - -Run the following commands on your Terraform instance: - -```none -cd / -terraform plan -terraform apply -yes -``` - -## Create an AWS instance and check its configuration - -```none -root@localhost:~/awsterraform# terraform apply - -Terraform used the selected providers to generate the following execution plan. -Resource actions are indicated with the following symbols: - + create - -Terraform will perform the following actions: - - # aws_instance.myVyOSec2 will be created - + resource "aws_instance" "myVyOSec2" { - + ami = "ami-************62c2d" - + arn = (known after apply) - + associate_public_ip_address = (known after apply) - + availability_zone = (known after apply) - + cpu_core_count = (known after apply) - + cpu_threads_per_core = (known after apply) - + disable_api_stop = (known after apply) - + disable_api_termination = (known after apply) - + ebs_optimized = (known after apply) - + get_password_data = false - + host_id = (known after apply) - + host_resource_group_arn = (known after apply) - + iam_instance_profile = (known after apply) - + id = (known after apply) - + instance_initiated_shutdown_behavior = (known after apply) - + instance_lifecycle = (known after apply) - + instance_state = (known after apply) - + instance_type = "t2.micro" - + ipv6_address_count = (known after apply) - + ipv6_addresses = (known after apply) - + key_name = "awsterraform" - + monitoring = (known after apply) - + outpost_arn = (known after apply) - + password_data = (known after apply) - + placement_group = (known after apply) - + placement_partition_number = (known after apply) - + primary_network_interface_id = (known after apply) - + private_dns = (known after apply) - + private_ip = (known after apply) - + public_dns = (known after apply) - + public_ip = (known after apply) - + secondary_private_ips = (known after apply) - + security_groups = [ - + "awsterraformsg", - ] - + source_dest_check = true - + spot_instance_request_id = (known after apply) - + subnet_id = (known after apply) - + tags = { - + "name" = "VyOS System" - } - + tags_all = { - + "name" = "VyOS System" - } - + tenancy = (known after apply) - + user_data = (known after apply) - + user_data_base64 = (known after apply) - + user_data_replace_on_change = false - + vpc_security_group_ids = (known after apply) - } - - # local_file.ip will be created - + resource "local_file" "ip" { - + content = (known after apply) - + content_base64sha256 = (known after apply) - + content_base64sha512 = (known after apply) - + content_md5 = (known after apply) - + content_sha1 = (known after apply) - + content_sha256 = (known after apply) - + content_sha512 = (known after apply) - + directory_permission = "0777" - + file_permission = "0777" - + filename = "ip.txt" - + id = (known after apply) - } - - # null_resource.SSHconnection1 will be created - + resource "null_resource" "SSHconnection1" { - + id = (known after apply) - } - - # null_resource.SSHconnection2 will be created - + resource "null_resource" "SSHconnection2" { - + id = (known after apply) - } - -Plan: 4 to add, 0 to change, 0 to destroy. - -Changes to Outputs: - + my_IP = (known after apply) - -Do you want to perform these actions? - Terraform will perform the actions described above. - Only 'yes' will be accepted to approve. - - Enter a value: yes - -aws_instance.myVyOSec2: Creating... -aws_instance.myVyOSec2: Still creating... [10s elapsed] -aws_instance.myVyOSec2: Still creating... [20s elapsed] -aws_instance.myVyOSec2: Still creating... [30s elapsed] -aws_instance.myVyOSec2: Still creating... [40s elapsed] -aws_instance.myVyOSec2: Creation complete after 44s [id=i-09edfca15aac2fe0a] -null_resource.SSHconnection1: Creating... -null_resource.SSHconnection2: Creating... -null_resource.SSHconnection1: Provisioning with 'file'... -null_resource.SSHconnection2: Provisioning with 'remote-exec'... -null_resource.SSHconnection2 (remote-exec): Connecting to remote host via SSH... -null_resource.SSHconnection2 (remote-exec): Host: 10.217.80.104 -null_resource.SSHconnection2 (remote-exec): User: root -null_resource.SSHconnection2 (remote-exec): Password: true -null_resource.SSHconnection2 (remote-exec): Private key: false -null_resource.SSHconnection2 (remote-exec): Certificate: false -null_resource.SSHconnection2 (remote-exec): SSH Agent: false -null_resource.SSHconnection2 (remote-exec): Checking Host Key: false -null_resource.SSHconnection2 (remote-exec): Target Platform: unix -local_file.ip: Creating... -local_file.ip: Creation complete after 0s [id=e8e91f2e24579cd28b92e2d152c0c24c3bf4b52c] -null_resource.SSHconnection2 (remote-exec): Connected! -null_resource.SSHconnection1: Creation complete after 0s [id=7070868940858935600] - -null_resource.SSHconnection2 (remote-exec): PLAY [integration of terraform and ansible] ************************************ - -null_resource.SSHconnection2 (remote-exec): TASK [Wait 300 seconds, but only start checking after 60 seconds] ************** -null_resource.SSHconnection2: Still creating... [10s elapsed] -null_resource.SSHconnection2: Still creating... [20s elapsed] -null_resource.SSHconnection2: Still creating... [30s elapsed] -null_resource.SSHconnection2: Still creating... [40s elapsed] -null_resource.SSHconnection2: Still creating... [50s elapsed] -null_resource.SSHconnection2: Still creating... [1m0s elapsed] -null_resource.SSHconnection2 (remote-exec): ok: [54.xxx.xxx.xxx] - -null_resource.SSHconnection2 (remote-exec): TASK [Configure general settings for the vyos hosts group] ********************* -null_resource.SSHconnection2: Still creating... [1m10s elapsed] -null_resource.SSHconnection2 (remote-exec): changed: [54.xxx.xxx.xxx] - -null_resource.SSHconnection2 (remote-exec): PLAY RECAP ********************************************************************* -null_resource.SSHconnection2 (remote-exec): 54.xxx.xxx.xxx : ok=2 changed=1 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 - -null_resource.SSHconnection2: Creation complete after 1m16s [id=4902256962410024771] - -Apply complete! Resources: 4 added, 0 changed, 0 destroyed. - -Outputs: - -my_IP = "54.xxx.xxx.xxx" -``` - -After running all the commands, your VyOS instance is deployed on -AWS with your specified configuration. -To delete the instance, type the following command: - -```none -terraform destroy -``` - -## Troubleshooting - -1. If Ansible doesn't connect via SSH to your AWS instance, verify that - your SSH key is in the path `/root/aws/`. You might need to - increase the timeout in `instance.yml` from 300 seconds to 500 - seconds or more, depending on your location. Make sure that the - security group allows access to the instance. -2. If Terraform doesn't connect via SSH to your Ansible instance, - verify the correct login and password in the `VyOS.tf` file. - -```{eval-rst} - .. code-block:: none - - connection { - type = "ssh" - user = "root" # open root access using login and password on your Ansible - password = var.password # check password in the file terraform.tfvars isn't empty - host = var.host # check the correct IP address of your Ansible host - } -``` - -Make sure Ansible can ping from Terraform. - -## Structure of files in Terraform for AWS - -```none -. -├── vyos.tf # The main script -├── var.tf # The file of all variables in "vyos.tf" -├── versions.tf # File for the changing version of Terraform. -└── terraform.tfvars # The value of all variables (passwords, login, ip adresses and so on) -``` - -## File contents of Terraform for AWS - -`vyos.tf` - -```none -############################################################################## -# Build a VyOS VM from the Marketplace. -# Find the necessary AMI image_ in AWS. -# -# The vyos.tf script uses default values (you can change them as -# needed) -# AWS Region = "us-east-1" -# AMI = "standard AMI of VyOS from AWS Marketplace" -# Size of VM = "t2.micro" -# AWS Region = "us-east-1" -# After deploying the AWS instance and getting an IP address, the IP address is copied into the file -#"ip.txt" and copied to the Ansible node for provisioning. -############################################################################## - -provider "aws" { - access_key = var.access - secret_key = var.secret - region = var.region -} - -variable "region" { - default = "us-east-1" - description = "AWS Region" -} - -variable "ami" { - default = "ami-**************3b3" # ami image please enter your details - description = "Amazon Machine Image ID for VyOS" -} - -variable "type" { - default = "t2.micro" - description = "Size of VM" -} - -# my resource for VyOS - -resource "aws_instance" "myVyOSec2" { - ami = var.ami - key_name = "awsterraform" # Please enter your details from 1.2 of Preparation steps for deploying VyOS on AWS - security_groups = ["awsterraformsg"] # Please enter your details from 1.3 of Preparation steps for deploying VyOS on AWS - instance_type = var.type - tags = { - name = "VyOS System" - } -} - -############################################################################## -# Specific variable (to getting type "terraform plan"): -# aws_instance.myVyOSec2.public_ip - the information about public IP address -# of our instance, needs for provisioning and SSH connection from Ansible -############################################################################## - -output "my_IP"{ -value = aws_instance.myVyOSec2.public_ip -} - -############################################################################## -# The IP address of the AWS instance is copied to the ip.txt file -# on the local Terraform system. The ip.txt file contains the public -# IP address in the format: xxx.xxx.xxx.xxx -############################################################################## - -resource "local_file" "ip" { - content = aws_instance.myVyOSec2.public_ip - filename = "ip.txt" -} - -#connecting to the Ansible control node using SSH connection - -############################################################################## -# The "SSHconnection1" and "SSHconnection2" steps retrieve ip.txt -# from the Terraform node and run the Ansible playbook remotely. -############################################################################## - -resource "null_resource" "SSHconnection1" { -depends_on = [aws_instance.myVyOSec2] -connection { - type = "ssh" - user = "root" - password = var.password - host = var.host -} - -# Copy the ip.txt file to the Ansible control node from the local -# system - provisioner "file" { - source = "ip.txt" - destination = "/root/aws/ip.txt" # The folder of your Ansible project - } -} - -resource "null_resource" "SSHconnection2" { -depends_on = [aws_instance.myVyOSec2] -connection { - type = "ssh" - user = "root" - password = var.password - host = var.host -} -# Run Ansible playbook on remote Linux OS -provisioner "remote-exec" { - inline = [ - "cd /root/aws/", - "ansible-playbook instance.yml" # more detailed in "File contents of Ansible for AWS" -] -} -} -``` - -`var.tf` - -```none -variable "password" { - description = "pass for Ansible" - type = string - sensitive = true -} -variable "host"{ - description = "The IP of my Ansible" - type = string -} -variable "access" { - description = "my access_key for AWS" - type = string - sensitive = true -} -variable "secret" { - description = "my secret_key for AWS" - type = string - sensitive = true -} -``` - -`versions.tf` - -```none - terraform { - required_providers { - aws = { - source = "hashicorp/aws" - version = "~> 5.0" - } - } -} -``` - -`terraform.tfvars` - -```none -password = "" # password for Ansible SSH -host = "" # IP of my Ansible -access = "" # access_key for AWS -secret = "" # secret_key for AWS -``` - -## Structure of files in Ansible for AWS - -```none -. -├── group_vars - └── all -├── ansible.cfg -├── mykey.pem -└── instance.yml -``` - -## File contents of Ansible for AWS - -`ansible.cfg` - -```none -[defaults] -inventory = /root/aws/ip.txt -host_key_checking= False -private_key_file = /root/aws/awsterraform.pem # check the name -remote_user=vyos -``` - -`mykey.pem` - -```none -Copy your key.pem from AWS -``` - -`instance.yml` - -```none -############################################################################## -# About tasks: -# "Wait 300 seconds, but only start checking after 60 seconds" - -# attempts SSH connection every 60 seconds until 300 seconds -# "Configure general settings for the VyOS hosts group" - -# provisions the AWS VyOS node -# Add all necessary VyOS commands under the "lines:" block -############################################################################## - -- name: integration of terraform and ansible - hosts: all - gather_facts: 'no' - - tasks: - - - name: "Wait 300 seconds, but only start checking after 60 seconds" - wait_for_connection: - delay: 60 - timeout: 300 - - - name: "Configure general settings for the VyOS hosts group" - vyos_config: - lines: - - set system name-server xxx.xxx.xxx.xxx - save: - true -``` - -`group_vars/all` - -```none -ansible_connection: ansible.netcommon.network_cli -ansible_network_os: vyos.vyos.vyos -ansible_user: vyos -``` - - -## Source files on GitHub - -All files related to deploying VyOS on AWS with Terraform and Ansible -can be found in the [vyos-automation] repository. - -[group]: https://docs.aws.amazon.com/cli/latest/userguide/cli-services-ec2-sg.html -[pair]: https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/create-key-pairs.html -[vyos-automation]: diff --git a/docs/automation/terraform/md-terraformAZ.md b/docs/automation/terraform/md-terraformAZ.md deleted file mode 100644 index b1b8fac0..00000000 --- a/docs/automation/terraform/md-terraformAZ.md +++ /dev/null @@ -1,501 +0,0 @@ ---- -lastproofread: '2026-03-19' ---- - -(terraformaz)= - -# Deploy VyOS on Microsoft Azure with Terraform and Ansible - -You can use Terraform to quickly deploy VyOS-based infrastructure -on Microsoft Azure (hereafter referred to as *Azure*) and remove -infrastructure when it's no longer needed. -Additionally, you can use Ansible for provisioning. - -On this page you'll learn how to: - -- Create the necessary files for Terraform and Ansible. -- Use Terraform to create a single instance on Azure and use Ansible for - provisioning. - -## Prepare to deploy VyOS with Terraform on Azure - -To create a single instance and install your configuration using -Terraform, Ansible, and Azure, follow these steps: - -### Azure - -- Create an [Azure account](https://azure.microsoft.com/). - -### Terraform - -```{eval-rst} -1. Create an UNIX or Windows instance. - -2. Download and install - `Terraform `__. - -3. Create the folder for example ``/root/azvyos/``. - -.. code-block:: none - - mkdir /root/azvyos - -.. stop_vyoslinter - -4. Copy all files into your Terraform project "/root/azvyos" - (``vyos.tf``, ``var.tf``, ``terraform.tfvars``). For more details, see - `Structure of files in Terraform for Azure <#structure-of-files-in-terraform-for-azure>`_. - -.. start_vyoslinter - -5. Log in to Azure using the command: - - .. code-block:: none - - az login - -6. Run the following commands to initialize Terraform: - - .. code-block:: none - - cd / - terraform init -``` - - -### Ansible - -1. Create an UNIX instance either locally or in the cloud. - -2. Download and install Ansible - -3. Create a folder, for example `/root/az/`. - -4. Copy all files into your Ansible project `/root/az/` (`ansible.cfg`, - `instance.yml`, `all`). For more details, see - [Structure of files in Ansible for Azure](#structure-of-files-in-ansible-for-azure) - -### Deploy with Terraform - -Run the following commands on your Terraform instance: - -```none -cd / -terraform plan -terraform apply -yes -``` - -After executing all the commands, your VyOS instance is deployed to -Azure with your configuration. -If you need to delete the instance, run the following command: - -```none -terraform destroy -``` - - -## Structure of files in Terraform for Azure - -```none -. -├── vyos.tf # The main script -├── var.tf # File for the Terraform version. -└── terraform.tfvars # Values for all variables (passwords, - # login, IP addresses, etc.) -``` - - -## File contents of Terraform for Azure - -`vyos.tf` - -```none -############################################################################## -# HashiCorp Guide to Using Terraform on Azure -# This Terraform configuration will create the following: -# Resource group with a virtual network and subnet -# A VyOS server without SSH key (only login+password) -############################################################################## - -# Choose a provider - -provider "azurerm" { - features {} -} - -# Create a resource group. In Azure, every resource belongs to a -# resource group. - -resource "azurerm_resource_group" "azure_vyos" { - name = "${var.resource_group}" - location = "${var.location}" -} - -# The next resource is a Virtual Network. - -resource "azurerm_virtual_network" "vnet" { - name = "${var.virtual_network_name}" - location = "${var.location}" - address_space = ["${var.address_space}"] - resource_group_name = "${var.resource_group}" -} - -# Build a subnet to run your VMs. - -resource "azurerm_subnet" "subnet" { - name = "${var.prefix}subnet" - virtual_network_name = "${azurerm_virtual_network.vnet.name}" - resource_group_name = "${var.resource_group}" - address_prefixes = ["${var.subnet_prefix}"] -} - -############################################################################## -# Build a VyOS VM from the Marketplace. -# To find the necessary image, use the command: -# -# az vm image list --offer vyos --all -# -# Now that you have a network, you can deploy a VyOS server. -# An Azure Virtual Machine has several components. In this example, -# you build a security group, a network interface, a public IP -# address, a storage account, and finally the VM itself. Terraform -# handles all the dependencies automatically, and each resource is -# named with user-defined variables. -############################################################################## - - -# Security group to allow inbound access on port 22 (SSH) - -resource "azurerm_network_security_group" "vyos-sg" { - name = "${var.prefix}-sg" - location = "${var.location}" - resource_group_name = "${var.resource_group}" - - security_rule { - name = "SSH" - priority = 100 - direction = "Inbound" - access = "Allow" - protocol = "Tcp" - source_port_range = "*" - destination_port_range = "22" - source_address_prefix = "${var.source_network}" - destination_address_prefix = "*" - } -} - -# A network interface. - -resource "azurerm_network_interface" "vyos-nic" { - name = "${var.prefix}vyos-nic" - location = "${var.location}" - resource_group_name = "${var.resource_group}" - - ip_configuration { - name = "${var.prefix}ipconfig" - subnet_id = "${azurerm_subnet.subnet.id}" - private_ip_address_allocation = "Dynamic" - public_ip_address_id = "${azurerm_public_ip.vyos-pip.id}" - } -} - -# Add a public IP address. - -resource "azurerm_public_ip" "vyos-pip" { - name = "${var.prefix}-ip" - location = "${var.location}" - resource_group_name = "${var.resource_group}" - allocation_method = "Dynamic" -} - -# Build a virtual machine. This is a standard VyOS instance from -# Marketplace. - -resource "azurerm_virtual_machine" "vyos" { - name = "${var.hostname}-vyos" - location = "${var.location}" - resource_group_name = "${var.resource_group}" - vm_size = "${var.vm_size}" - - network_interface_ids = ["${azurerm_network_interface.vyos-nic.id}"] - delete_os_disk_on_termination = "true" - -# To find information about the plan, use the command: -# az vm image list --offer vyos --all - - plan { - publisher = "sentriumsl" - name = "vyos-1-3" - product = "vyos-1-2-lts-on-azure" - } - - storage_image_reference { - publisher = "${var.image_publisher}" - offer = "${var.image_offer}" - sku = "${var.image_sku}" - version = "${var.image_version}" - } - - storage_os_disk { - name = "${var.hostname}-osdisk" - managed_disk_type = "Standard_LRS" - caching = "ReadWrite" - create_option = "FromImage" - } - - os_profile { - computer_name = "${var.hostname}" - admin_username = "${var.admin_username}" - admin_password = "${var.admin_password}" - } - - os_profile_linux_config { - disable_password_authentication = false - } -} - -data "azurerm_public_ip" "example" { - depends_on = ["azurerm_virtual_machine.vyos"] - name = "vyos-ip" - resource_group_name = "${var.resource_group}" -} -output "public_ip_address" { - value = data.azurerm_public_ip.example.ip_address -} - -# IP of AZ instance copied to a file ip.txt in the local system. - -resource "local_file" "ip" { - content = data.azurerm_public_ip.example.ip_address - filename = "ip.txt" -} - -# Connect to the Ansible control node via SSH - -resource "null_resource" "nullremote1" { -depends_on = ["azurerm_virtual_machine.vyos"] -connection { - type = "ssh" - user = "root" - password = var.password - host = var.host -} - -# Copy the ip.txt file to the Ansible control node from the local -# system - - provisioner "file" { - source = "ip.txt" - destination = "/root/az/ip.txt" - } -} - -resource "null_resource" "nullremote2" { -depends_on = ["azurerm_virtual_machine.vyos"] -connection { - type = "ssh" - user = "root" - password = var.password - host = var.host -} - -# Run the Ansible playbook on the remote Linux OS - -provisioner "remote-exec" { - - inline = [ - "cd /root/az/", - "ansible-playbook instance.yml" -] -} -} -``` - -`var.tf` - -```none -############################################################################## -# Variables File -# -# Default values for all variables used in Terraform code. -############################################################################## - -variable "resource_group" { - description = "The name of your Azure Resource Group." - default = "my_resource_group" -} - -variable "prefix" { - description = "This prefix will be included in the name of some resources." - default = "vyos" -} - -variable "hostname" { - description = "Virtual machine hostname. Used for local hostname, DNS, and storage-related names." - default = "vyos_terraform" -} - -variable "location" { - description = "The region where the virtual network is created." - default = "centralus" -} - -variable "virtual_network_name" { - description = "The name for your virtual network." - default = "vnet" -} - -variable "address_space" { - description = "The address space that is used by the virtual network. You can supply more than one address space. Changing this forces a new resource to be created." - default = "10.0.0.0/16" -} - -variable "subnet_prefix" { - description = "The address prefix to use for the subnet." - default = "10.0.10.0/24" -} - -variable "storage_account_tier" { - description = "Defines the storage tier. Valid options are Standard and Premium." - default = "Standard" -} - -variable "storage_replication_type" { - description = "Defines the replication type to use for this storage account. Valid options include LRS, GRS etc." - default = "LRS" -} - -# The most cost-effective size - -variable "vm_size" { - description = "Specifies the size of the virtual machine." - default = "Standard_B1s" -} - -variable "image_publisher" { - description = "Name of the publisher of the image (az vm image list)" - default = "sentriumsl" -} - -variable "image_offer" { - description = "Name of the offer (az vm image list)" - default = "vyos-1-2-lts-on-azure" -} - -variable "image_sku" { - description = "Image SKU to apply (az vm image list)" - default = "vyos-1-3" -} - -variable "image_version" { - description = "Version of the image to apply (az vm image list)" - default = "1.3.3" -} - -variable "admin_username" { - description = "Administrator user name" - default = "vyos" -} - -variable "admin_password" { - description = "Administrator password" - type = string - sensitive = true -} - -variable "source_network" { - description = "Allow access from this network prefix. Defaults to '*'." - default = "*" -} - -variable "password" { - description = "pass for Ansible" - type = string - sensitive = true -} -variable "host"{ - description = "IP of my Ansible" -} -``` - -`terraform.tfvars` - -```none -password = "" # password for Ansible SSH -host = "" # IP of my Ansible -``` - - -## Structure of files in Ansible for Azure - -```none -. -├── group_vars - └── all -├── ansible.cfg -└── instance.yml -``` - - -## File contents of Ansible for Azure - -`ansible.cfg` - -```none -[defaults] -inventory = /root/az/ip.txt -host_key_checking= False -remote_user=vyos -``` - -`instance.yml` - -```none -############################################################################## -# About tasks: -# "Wait 300 seconds, but only start checking after 60 seconds" - Tries -# to make SSH connection every 60 seconds until 300 seconds. -# "Configure general settings for the VyOS hosts group" - Provision -# the Azure VyOS node. -# Add all necessary commands for VyOS under the block "lines:" -############################################################################## - - -- name: integration of terraform and ansible - hosts: all - gather_facts: 'no' - - tasks: - - - name: "Wait 300 seconds, but only start checking after 60 seconds" - wait_for_connection: - delay: 60 - timeout: 300 - - - name: "Configure general settings for the VyOS hosts group" - vyos_config: - lines: - - set system name-server xxx.xxx.xxx.xxx - save: - true -``` - -`group_vars/all` - -```none -ansible_connection: ansible.netcommon.network_cli -ansible_network_os: vyos.vyos.vyos - -# user and password gets from terraform variables "admin_username" and "admin_password" in the file /root/azvyos/var.tf -ansible_user: vyos -ansible_ssh_pass: "{{ vault_vyos_ssh_pass }}" -``` - - -## Source files on GitHub - -All files related to deploying VyOS on Azure with Terraform and Ansible -can be found in the [vyos-automation] repository. - -[vyos-automation]: diff --git a/docs/automation/terraform/md-terraformGoogle.md b/docs/automation/terraform/md-terraformGoogle.md deleted file mode 100644 index f9c002a7..00000000 --- a/docs/automation/terraform/md-terraformGoogle.md +++ /dev/null @@ -1,703 +0,0 @@ ---- -lastproofread: '2026-03-23' ---- - -(terraformgoogle)= - -# Deploy VyOS on Google Cloud with Terraform and Ansible - -Using Terraform, you can quickly deploy VyOS-based infrastructure on -Google Cloud Platform (GCP) and remove the -infrastructure when it's no longer needed. -Additionally, you can use Ansible for provisioning. - -On this page you'll learn how to: - -- Create the necessary files for Terraform and Ansible. -- Use Terraform to create a single instance on GCP and use Ansible for - provisioning. - -## Prepare to deploy VyOS with Terraform on GCP - -To create a single instance and install your configuration using -Terraform, Ansible, and GCP, follow these steps: - -### GCP - -1. Create an account with GCP and a new project. - -```{image} /_static/images/project.webp -:align: center -:alt: Network Topology Diagram -:width: 50% -``` - -2. Create a service account and download your key (a JSON file). - -```{image} /_static/images/service.webp -:align: center -:alt: Network Topology Diagram -:width: 50% -``` - -```{image} /_static/images/key.webp -:align: center -:alt: Network Topology Diagram -:width: 50% -``` - -The .JSON file downloads automatically after you create it and looks -like the following: - -```{image} /_static/images/json.webp -:align: center -:alt: Network Topology Diagram -:width: 50% -``` - -### Terraform - -1. Create an UNIX or Windows instance. - -2. Download and install - [Terraform](https://developer.hashicorp.com/terraform/install). - -3. Create the folder. For example, `/root/google`. - -```none -mkdir /root/google -``` - -4. Copy all files into your Terraform project `/root/google` - (`vyos.tf`, `var.tf`, `terraform.tfvars`, `mykey.json`). - For more details, - see [Structure of files Terraform for Google Cloud](#structure-of-files-in-terraform-for-google-cloud) - - - -5. Run the following commands: - -```none -cd / -terraform init -``` - -### Ansible - -1. Create an UNIX instance either locally or in the cloud. - -2. Download and install Ansible - -3. Create the folder for example /root/google/ - -4. Copy all files into your Ansible project `/root/google/` - (`ansible.cfg`, `instance.yml`, `mykey.json`, and `all`). For more - details, see [Structure of files in Ansible for Google Cloud](#structure-of-files-in-ansible-for-google-cloud) - -You obtain `mykey.json` when you create a service account in GCP -and download the key (a JSON file). - -### Deploy with Terraform - -Run the following commands on your Terraform instance: - -```none -cd / -terraform plan -terraform apply -yes -``` - -## Create a GCP instance and check its configuration - -```none -# terraform apply - -Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following symbols: - + create - -Terraform will perform the following actions: - - # google_compute_firewall.tcp_22[0] will be created - + resource "google_compute_firewall" "tcp_22" { - + creation_timestamp = (known after apply) - + destination_ranges = (known after apply) - + direction = (known after apply) - + enable_logging = (known after apply) - + id = (known after apply) - + name = "vyos-tcp-22" - + network = "default" - + priority = 1000 - + project = "vyosproject" - + self_link = (known after apply) - + source_ranges = [ - + "0.0.0.0/0", - ] - + target_tags = [ - + "vyos-deployment", - ] - - + allow { - + ports = [ - + "22", - ] - + protocol = "tcp" - } - } - - # google_compute_firewall.udp_500_4500[0] will be created - + resource "google_compute_firewall" "udp_500_4500" { - + creation_timestamp = (known after apply) - + destination_ranges = (known after apply) - + direction = (known after apply) - + enable_logging = (known after apply) - + id = (known after apply) - + name = "vyos-udp-500-4500" - + network = "default" - + priority = 1000 - + project = "vyosproject" - + self_link = (known after apply) - + source_ranges = [ - + "0.0.0.0/0", - ] - + target_tags = [ - + "vyos-deployment", - ] - - + allow { - + ports = [ - + "500", - + "4500", - ] - + protocol = "udp" - } - } - - # google_compute_instance.default will be created - + resource "google_compute_instance" "default" { - + can_ip_forward = true - + cpu_platform = (known after apply) - + current_status = (known after apply) - + deletion_protection = false - + effective_labels = (known after apply) - + guest_accelerator = (known after apply) - + id = (known after apply) - + instance_id = (known after apply) - + label_fingerprint = (known after apply) - + machine_type = "n2-highcpu-4" - + metadata = { - + "enable-oslogin" = "FALSE" - + "serial-port-enable" = "TRUE" - + "user-data" = "" - } - + metadata_fingerprint = (known after apply) - + min_cpu_platform = (known after apply) - + name = "vyos" - + project = "vyosproject" - + self_link = (known after apply) - + tags_fingerprint = (known after apply) - + terraform_labels = (known after apply) - + zone = "us-west1-a" - - + boot_disk { - + auto_delete = true - + device_name = (known after apply) - + disk_encryption_key_sha256 = (known after apply) - + kms_key_self_link = (known after apply) - + mode = "READ_WRITE" - + source = (known after apply) - - + initialize_params { - + image = "projects/sentrium-public/global/images/vyos-1-3-5-20231222143039" - + labels = (known after apply) - + provisioned_iops = (known after apply) - + provisioned_throughput = (known after apply) - + size = (known after apply) - + type = (known after apply) - } - } - - + network_interface { - + internal_ipv6_prefix_length = (known after apply) - + ipv6_access_type = (known after apply) - + ipv6_address = (known after apply) - + name = (known after apply) - + network = "default" - + network_ip = (known after apply) - + nic_type = "GVNIC" - + stack_type = (known after apply) - + subnetwork = "default" - + subnetwork_project = (known after apply) - - + access_config { - + nat_ip = (known after apply) - + network_tier = (known after apply) - } - } - } - - # local_file.ip will be created - + resource "local_file" "ip" { - + content = (known after apply) - + content_base64sha256 = (known after apply) - + content_base64sha512 = (known after apply) - + content_md5 = (known after apply) - + content_sha1 = (known after apply) - + content_sha256 = (known after apply) - + content_sha512 = (known after apply) - + directory_permission = "0777" - + file_permission = "0777" - + filename = "ip.txt" - + id = (known after apply) - } - - # null_resource.SSHconnection1 will be created - + resource "null_resource" "SSHconnection1" { - + id = (known after apply) - } - - # null_resource.SSHconnection2 will be created - + resource "null_resource" "SSHconnection2" { - + id = (known after apply) - } - -Plan: 6 to add, 0 to change, 0 to destroy. - -Changes to Outputs: - + public_ip_address = (known after apply) -╷ -│ Warning: Quoted references are deprecated -│ -│ on vyos.tf line 126, in resource "null_resource" "SSHconnection1": -│ 126: depends_on = ["google_compute_instance.default"] -│ -│ In this context, references are expected literally rather than in quotes. Terraform 0.11 and earlier required quotes, but quoted references are now deprecated and will be removed in a -│ future version of Terraform. Remove the quotes surrounding this reference to silence this warning. -│ -│ (and one more similar warning elsewhere) -╵ - -Do you want to perform these actions? - Terraform will perform the actions described above. - Only 'yes' will be accepted to approve. - - Enter a value: yes - -google_compute_firewall.udp_500_4500[0]: Creating... -google_compute_firewall.tcp_22[0]: Creating... -google_compute_instance.default: Creating... -google_compute_firewall.udp_500_4500[0]: Still creating... [10s elapsed] -google_compute_firewall.tcp_22[0]: Still creating... [10s elapsed] -google_compute_instance.default: Still creating... [10s elapsed] -google_compute_firewall.tcp_22[0]: Creation complete after 16s [id=projects/vyosproject/global/firewalls/vyos-tcp-22] -google_compute_firewall.udp_500_4500[0]: Creation complete after 16s [id=projects/vyosproject/global/firewalls/vyos-udp-500-4500] -google_compute_instance.default: Creation complete after 20s [id=projects/vyosproject/zones/us-west1-a/instances/vyos] -null_resource.SSHconnection1: Creating... -null_resource.SSHconnection2: Creating... -null_resource.SSHconnection1: Provisioning with 'file'... -null_resource.SSHconnection2: Provisioning with 'remote-exec'... -null_resource.SSHconnection2 (remote-exec): Connecting to remote host via SSH... -null_resource.SSHconnection2 (remote-exec): Host: 10.***.***.104 -null_resource.SSHconnection2 (remote-exec): User: root -null_resource.SSHconnection2 (remote-exec): Password: true -null_resource.SSHconnection2 (remote-exec): Private key: false -null_resource.SSHconnection2 (remote-exec): Certificate: false -null_resource.SSHconnection2 (remote-exec): SSH Agent: false -null_resource.SSHconnection2 (remote-exec): Checking Host Key: false -null_resource.SSHconnection2 (remote-exec): Target Platform: unix -local_file.ip: Creating... -local_file.ip: Creation complete after 0s [id=7d568c3b994a018c942a3cdb952ccbf3c729d0ca] -null_resource.SSHconnection2 (remote-exec): Connected! -null_resource.SSHconnection1: Creation complete after 4s [id=5175298735911137161] - -null_resource.SSHconnection2 (remote-exec): PLAY [integration of terraform and ansible] ************************************ - -null_resource.SSHconnection2 (remote-exec): TASK [Wait 300 seconds, but only start checking after 60 seconds] ************** -null_resource.SSHconnection2: Still creating... [10s elapsed] -null_resource.SSHconnection2: Still creating... [20s elapsed] -null_resource.SSHconnection2: Still creating... [30s elapsed] -null_resource.SSHconnection2: Still creating... [40s elapsed] -null_resource.SSHconnection2: Still creating... [50s elapsed] -null_resource.SSHconnection2: Still creating... [1m0s elapsed] -null_resource.SSHconnection2: Still creating... [1m10s elapsed] -null_resource.SSHconnection2 (remote-exec): ok: [104.***.***.158] - -null_resource.SSHconnection2 (remote-exec): TASK [Configure general settings for the vyos hosts group] ********************* -null_resource.SSHconnection2: Still creating... [1m20s elapsed] -null_resource.SSHconnection2 (remote-exec): changed: [104.***.***.158] - -null_resource.SSHconnection2 (remote-exec): PLAY RECAP ********************************************************************* -null_resource.SSHconnection2 (remote-exec): 104.***.***.158 : ok=2 changed=1 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 - -null_resource.SSHconnection2: Creation complete after 1m22s [id=3355727070503709742] - -Apply complete! Resources: 6 added, 0 changed, 0 destroyed. - -Outputs: - -public_ip_address = "104.***.***.158" -``` - -After running all the commands, your VyOS instance is deployed on -GCP with your specified configuration. -To delete the instance, type the following command: - -```none -terraform destroy -``` - -## Troubleshooting - -- Increase the timeout value in `instance.yml` from 300 seconds to - 500 seconds or more (depends on your location). Ensure that the - security group allows access to the instance. -- If Terraform doesn't connect via SSH to your Ansible instance: - Check the correct login and password in the `VyOS.tf` file. - -```none -connection { - type = "ssh" - user = "root" # open root access using login and password on your Ansible - password = var.password # check password in the file terraform.tfvars isn't empty - host = var.host # check the correct IP address of your Ansible host -} -``` - -Verify that Ansible can ping from Terraform. - -## Structure of files in Terraform for Google Cloud - -```none -. -├── vyos.tf # The main script -├── ***.JSON # The credential file from GCP -├── var.tf # The file of all variables in "vyos.tf" -└── terraform.tfvars # The value of all variables (passwords, login, IP addresses and so on) -``` - -## File contents of Terraform for Google Cloud - -`vyos.tf` - -```none -############################################################################## -# Build a VyOS VM from the Marketplace -# -# After deploying the GCP instance and getting an IP address, the IP address is copied into the file -#"ip.txt" and copied to the Ansible node for provisioning. -############################################################################## - -terraform { - required_providers { - google = { - source = "hashicorp/google" - } - } -} - -provider "google" { - project = var.project_id - request_timeout = "60s" - credentials = file(var.gcp_auth_file) -} - -locals { - network_interfaces = [for i, n in var.networks : { - network = n, - subnetwork = length(var.sub_networks) > i ? element(var.sub_networks, i) : null - external_ip = length(var.external_ips) > i ? element(var.external_ips, i) : "NONE" - } - ] -} - -resource "google_compute_instance" "default" { - name = var.goog_cm_deployment_name - machine_type = var.machine_type - zone = var.zone - - metadata = { - enable-oslogin = "FALSE" - serial-port-enable = "TRUE" - user-data = var.vyos_user_data - } - boot_disk { - initialize_params { - image = var.image - } - } - - can_ip_forward = true - - dynamic "network_interface" { - for_each = local.network_interfaces - content { - network = network_interface.value.network - subnetwork = network_interface.value.subnetwork - nic_type = "GVNIC" - dynamic "access_config" { - for_each = network_interface.value.external_ip == "NONE" ? [] : [1] - content { - nat_ip = network_interface.value.external_ip == "EPHEMERAL" ? null : network_interface.value.external_ip - } - } - } - } -} - -resource "google_compute_firewall" "tcp_22" { - count = var.enable_tcp_22 ? 1 : 0 - - name = "${var.goog_cm_deployment_name}-tcp-22" - network = element(var.networks, 0) - - allow { - ports = ["22"] - protocol = "tcp" - } - - source_ranges = ["0.0.0.0/0"] - - target_tags = ["${var.goog_cm_deployment_name}-deployment"] -} - -resource "google_compute_firewall" "udp_500_4500" { - count = var.enable_udp_500_4500 ? 1 : 0 - - name = "${var.goog_cm_deployment_name}-udp-500-4500" - network = element(var.networks, 0) - - allow { - ports = ["500", "4500"] - protocol = "udp" - } - - source_ranges = ["0.0.0.0/0"] - - target_tags = ["${var.goog_cm_deployment_name}-deployment"] -} - -output "public_ip_address" { - value = google_compute_instance.default.network_interface[0].access_config[0].nat_ip -} - -############################################################################## -# -# IP of google instance copied to a file ip.txt in local system Terraform -# ip.txt looks like: -# cat ./ip.txt -# ххх.ххх.ххх.ххх -############################################################################## - -resource "local_file" "ip" { - content = google_compute_instance.default.network_interface[0].access_config[0].nat_ip - filename = "ip.txt" -} - -#connecting to the Ansible control node using SSH connection - -############################################################################## -# Steps "SSHconnection1" and "SSHconnection2" need to get file ip.txt from the terraform node and start remotely the playbook of Ansible. -############################################################################## - -resource "null_resource" "SSHconnection1" { -depends_on = ["google_compute_instance.default"] -connection { - type = "ssh" - user = "root" - password = var.password - host = var.host -} - -#copying the ip.txt file to the Ansible control node from local system - - provisioner "file" { - source = "ip.txt" - destination = "/root/google/ip.txt" # The folder of your Ansible project - } -} - -resource "null_resource" "SSHconnection2" { -depends_on = ["google_compute_instance.default"] -connection { - type = "ssh" - user = "root" - password = var.password - host = var.host -} - -#command to run Ansible playbook on remote Linux OS - -provisioner "remote-exec" { - inline = [ - "cd /root/google/", - "ansible-playbook instance.yml" # more detailed in "File contents of Ansible for Google Cloud" -] -} -} -``` - -`var.tf` - -```none -variable "image" { - type = string - default = "projects/sentrium-public/global/images/vyos-1-3-5-20231222143039" -} - -variable "project_id" { - type = string -} - -variable "zone" { - type = string -} - -############################################################################## -# You can choose a lower cost machine type than n2-highcpu-4 -############################################################################## - -variable "machine_type" { - type = string - default = "n2-highcpu-4" -} - -variable "networks" { - description = "The network name to attach the VM instance." - type = list(string) - default = ["default"] -} - -variable "sub_networks" { - description = "The sub network name to attach the VM instance." - type = list(string) - default = ["default"] -} - -variable "external_ips" { - description = "The external IPs assigned to the VM for public access." - type = list(string) - default = ["EPHEMERAL"] -} - -variable "enable_tcp_22" { - description = "Allow SSH traffic from the Internet" - type = bool - default = true -} - -variable "enable_udp_500_4500" { - description = "Allow IKE/IPSec traffic from the Internet" - type = bool - default = true -} - -variable "vyos_user_data" { - type = string - default = "" -} - -// Marketplace requires this variable name to be declared -variable "goog_cm_deployment_name" { - description = "VyOS Universal Router Deployment" - type = string - default = "vyos" -} - -# GCP authentication file -variable "gcp_auth_file" { - type = string - description = "GCP authentication file" -} - -variable "password" { - description = "pass for Ansible" - type = string - sensitive = true -} -variable "host"{ - description = "The IP of my Ansible" - type = string -} -``` - -`terraform.tfvars` - -```none -############################################################################## -# Must be filled in -############################################################################## - -zone = "us-west1-a" -gcp_auth_file = "/root/***/***.json" # path of your .json file -project_id = "" # the google project -password = "" # password for Ansible SSH -host = "" # IP of my Ansible -``` - -## Structure of files in Ansible for Google Cloud - -```none -. -├── group_vars - └── all -├── ansible.cfg -└── instance.yml -``` - -## File contents of Ansible for Google Cloud - -`ansible.cfg` - -```none -[defaults] -inventory = /root/google/ip.txt -host_key_checking= False -remote_user=vyos -``` - -`instance.yml` - -```none -############################################################################## -# About tasks: -# "Wait 300 seconds, but only start checking after 60 seconds" - try to make ssh connection every 60 seconds until 300 seconds -# "Configure general settings for the VyOS hosts group" - make provisioning into Google Cloud VyOS node -# Add all necessary VyOS commands under the "lines:" block -############################################################################## - - -- name: integration of terraform and ansible - hosts: all - gather_facts: 'no' - - tasks: - - - name: "Wait 300 seconds, but only start checking after 60 seconds" - wait_for_connection: - delay: 60 - timeout: 300 - - - name: "Configure general settings for the VyOS hosts group" - vyos_config: - lines: - - set system name-server xxx.xxx.xxx.xxx - save: - true -``` - -`group_vars/all` - -```none -ansible_connection: ansible.netcommon.network_cli -ansible_network_os: vyos.vyos.vyos -ansible_user: vyos -ansible_ssh_pass: vyos -``` - - -## Source files on GitHub - -All files related to deploying VyOS on Google Cloud Platform with -Terraform and Ansible can be found in the [vyos-automation] repository. - -[vyos-automation]: diff --git a/docs/automation/terraform/md-terraformvSphere.md b/docs/automation/terraform/md-terraformvSphere.md deleted file mode 100644 index abcef5fa..00000000 --- a/docs/automation/terraform/md-terraformvSphere.md +++ /dev/null @@ -1,388 +0,0 @@ ---- -lastproofread: '2026-03-23' ---- - -(terraformvSphere)= - -# Deploy VyOS on VMware vSphere with Terraform and Ansible - -You can use Terraform to quickly deploy VyOS-based infrastructure -on VMware vSphere (hereafter referred to as *vSphere*) and remove -infrastructure when it's no longer needed. -Additionally, you can use Ansible for provisioning. - -On this page you'll learn how to: - -- Create the necessary files for Terraform and Ansible. -- Use Terraform to create a single instance on vSphere and use Ansible for - provisioning. - -## Prepare to deploy VyOS with Terraform on vSphere - -To create a single instance and install your configuration using -Terraform, Ansible, and vSphere, follow these steps: - -### vSphere - -- Add all necessary data to the `terraform.tfvars` - [file]() - and create resources. - -### Terraform - -- Create an UNIX or Windows instance. -- Download and install - [Terraform](https://developer.hashicorp.com/terraform/install). -- Create the folder for example `/root/vsphereterraform`. - -```none -mkdir /root/vsphereterraform -``` - -- Copy all files into your Terraform project `/root/vsphereterraform` - (`vyos.tf`, `var.tf`, `terraform.tfvars`, `version.tf`). - For more details, - see [Structure of files in Terraform for vSphere](#structure-of-files-in-terraform-for-vsphere) -- Run the following commands: - -```none -cd / -terraform init -``` - - -### Ansible - -- Create an UNIX instance either locally or in the cloud. -- Download and install Ansible. -- Create the folder. For example, `/root/vsphereterraform/`. -- Copy all files into your Ansible project `/root/vsphereterraform/` - (`ansible.cfg`, `instance.yml`, `all`). For more details, see - [Structure of files in Ansible for vSphere](#structure-of-files-in-ansible-for-vsphere) - -### Deploy with Terraform - -Run the following commands on your Terraform instance: - -```none -cd / -terraform plan -terraform apply -yes -``` - -After executing these commands, your VyOS instance is deployed to -vSphere with your configuration. -If you need to delete the instance, run the following command: - -```none -terraform destroy -``` - -## Structure of files in Terraform for vSphere - -```none -. -├── vyos.tf # The main script. -├── versions.tf # File for Terraform version. -├── var.tf # File for Terraform version. -└── terraform.tfvars # Values for all variables (passwords, - # login, IP addresses, etc.). -``` - -## File contents of Terraform for vSphere - -`vyos.tf` - -```none -provider "vsphere" { - user = var.vsphere_user - password = var.vsphere_password - vsphere_server = var.vsphere_server - allow_unverified_ssl = true -} - -data "vsphere_datacenter" "datacenter" { - name = var.datacenter -} - -data "vsphere_datastore" "datastore" { - name = var.datastore - datacenter_id = data.vsphere_datacenter.datacenter.id -} - -data "vsphere_compute_cluster" "cluster" { - name = var.cluster - datacenter_id = data.vsphere_datacenter.datacenter.id -} - -data "vsphere_resource_pool" "default" { - name = format("%s%s", data.vsphere_compute_cluster.cluster.name, "/Resources/terraform") # set as you need - datacenter_id = data.vsphere_datacenter.datacenter.id -} - -data "vsphere_host" "host" { - name = var.host - datacenter_id = data.vsphere_datacenter.datacenter.id -} - -data "vsphere_network" "network" { - name = var.network_name - datacenter_id = data.vsphere_datacenter.datacenter.id -} - -# Deployment of VM from Remote OVF -resource "vsphere_virtual_machine" "vmFromRemoteOvf" { - name = var.remotename - datacenter_id = data.vsphere_datacenter.datacenter.id - datastore_id = data.vsphere_datastore.datastore.id - host_system_id = data.vsphere_host.host.id - resource_pool_id = data.vsphere_resource_pool.default.id - network_interface { - network_id = data.vsphere_network.network.id - } - wait_for_guest_net_timeout = 2 - wait_for_guest_ip_timeout = 2 - - ovf_deploy { - allow_unverified_ssl_cert = true - remote_ovf_url = var.url_ova - disk_provisioning = "thin" - ip_protocol = "IPv4" - ip_allocation_policy = "dhcpPolicy" - ovf_network_map = { - "Network 1" = data.vsphere_network.network.id - "Network 2" = data.vsphere_network.network.id - } - } - vapp { - properties = { - "password" = "12345678", - "local-hostname" = "terraform_vyos" - } - } -} - -output "ip" { - description = "default ip address of the deployed VM" - value = vsphere_virtual_machine.vmFromRemoteOvf.default_ip_address -} - -# IP of vSphere instance copied to a file ip.txt in local system - -resource "local_file" "ip" { - content = vsphere_virtual_machine.vmFromRemoteOvf.default_ip_address - filename = "ip.txt" -} - -#Connecting to the Ansible control node using SSH connection - -resource "null_resource" "nullremote1" { -depends_on = ["vsphere_virtual_machine.vmFromRemoteOvf"] -connection { - type = "ssh" - user = "root" - password = var.ansiblepassword - host = var.ansiblehost - -} - -# Copying the ip.txt file to the Ansible control node from local system - - provisioner "file" { - source = "ip.txt" - destination = "/root/vsphere/ip.txt" - } -} - -resource "null_resource" "nullremote2" { -depends_on = ["vsphere_virtual_machine.vmFromRemoteOvf"] -connection { - type = "ssh" - user = "root" - password = var.ansiblepassword - host = var.ansiblehost -} - -# Command to run ansible playbook on remote Linux OS - -provisioner "remote-exec" { - - inline = [ - "cd /root/vsphere/", - "ansible-playbook instance.yml" -] -} -} -``` - -`versions.tf` - -```none -# Copyright (c) HashiCorp, Inc. -# SPDX-License-Identifier: MPL-2.0 - -terraform { - required_providers { - vsphere = { - source = "hashicorp/vsphere" - version = "2.4.0" - } - } -} -``` - -`var.tf` - -```none -# Copyright (c) HashiCorp, Inc. -# SPDX-License-Identifier: MPL-2.0 - -variable "vsphere_server" { - description = "vSphere server" - type = string -} - -variable "vsphere_user" { - description = "vSphere username" - type = string -} - -variable "vsphere_password" { - description = "vSphere password" - type = string - sensitive = true -} - -variable "datacenter" { - description = "vSphere data center" - type = string -} - -variable "cluster" { - description = "vSphere cluster" - type = string -} - -variable "datastore" { - description = "vSphere datastore" - type = string -} - -variable "network_name" { - description = "vSphere network name" - type = string -} - -variable "host" { - description = "Name of your host" - type = string -} - -variable "remotename" { - description = "The name of your VM" - type = string -} - -variable "url_ova" { - description = "The URL to the .OVA file or cloud storage" - type = string -} - -variable "ansiblepassword" { - description = "Ansible password" - type = string -} - -variable "ansiblehost" { - description = "Ansible host name or IP" - type = string -} -``` - -`terraform.tfvars` - -```none -vsphere_user = "" -vsphere_password = "" -vsphere_server = "" -datacenter = "" -datastore = "" -cluster = "" -network_name = "" -host = "" -url_ova = "" -ansiblepassword = "" -ansiblehost = "" -remotename = "" -``` - -## Structure of files in Ansible for vSphere - -```none -. -├── group_vars - └── all -├── ansible.cfg -└── instance.yml -``` - -## File contents of Ansible for vSphere - -`ansible.cfg` - -```none -[defaults] -inventory = /root/vsphere/ip.txt -host_key_checking= False -remote_user=vyos -``` - -`instance.yml` - -```none -############################################################################## -# About tasks: -# "Wait 300 seconds, but only start checking after 60 seconds" - try to make ssh connection every 60 seconds until 300 seconds -# "Configure general settings for the VyOS hosts group" - make provisioning into vSphere VyOS node -# You have to add all necessary commands of VyOS under the block "lines:" -############################################################################## - - -- name: integration of terraform and ansible - hosts: all - gather_facts: 'no' - - tasks: - - - name: "Wait 300 seconds, but only start checking after 60 seconds" - wait_for_connection: - delay: 60 - timeout: 300 - - name: "Configure general settings for the VyOS hosts group" - vyos_config: - lines: - - set system name-server 192.0.2.1 - save: - true -``` - -`group_vars/all` - -```none -ansible_connection: ansible.netcommon.network_cli -ansible_network_os: vyos.vyos.vyos - -# user and password gets from terraform variables "admin_username" and "admin_password" -ansible_user: vyos -# get from vyos.tf "vapp" -ansible_ssh_pass: 12345678 -``` - - -## Source files on GitHub - -All files related to deploying VyOS on vSphere with Terraform and Ansible -can be found in the [vyos-automation] repository. - -[vyos-automation]: diff --git a/docs/automation/terraform/terraformvyos.md b/docs/automation/terraform/terraformvyos.md deleted file mode 100644 index bfe1b6d1..00000000 --- a/docs/automation/terraform/terraformvyos.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -lastproofread: '2024-03-03' ---- - -(terraformvyos)= - -# Terraform for VyOS - -VyOS supports development infrastructure via Terraform and -provisioning via Ansible. Terraform allows you to automate the -process of deploying instances on many cloud and virtual -platforms. In this article, we will look at using Terraform to -deploy VyOS on platforms - AWS, Azure, and vSphere. For more -details about Terraform please have a look at [link]. - -You will need to [install] Terraform before proceeding. - -Structure of files in the standard Terraform project: - -```none -. -├── main.tf # The main script -├── version.tf # File for the changing version of Terraform. -├── variables.tf # The file of all variables in "main.tf" -└── terraform.tfvars # The value of all variables (passwords, login, IP addresses and so on) -``` - -General commands that we will use for running Terraform scripts - -```none -cd / # go to the Terraform project -terraform init # install all add-ons and providers (AWS, Azure, and so on) -terraform plan # show what is changing -terraform apply # run script -yes # apply running -``` - -% stop_vyoslinter - -% start_vyoslinter - -[install]: https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli -[link]: https://developer.hashicorp.com/terraform/intro - diff --git a/docs/conf.py b/docs/conf.py index 083baa61..1c1014e0 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -13,7 +13,6 @@ # documentation root, use os.path.abspath to make it absolute, like shown here. # import os -import shutil import sys sys.path.append(os.path.abspath("./_ext")) @@ -67,9 +66,6 @@ autosectionlabel_prefix_document = True # source_suffix = ['.rst', '.md'] source_suffix = ['.rst', '.md'] -myst_enable_extensions = ["colon_fence", "deflist", "fieldlist", "substitution"] -myst_fence_as_directive = ["cfgcmd", "opcmd", "cmdincludemd"] - # The master toctree document. master_doc = 'index' @@ -89,17 +85,7 @@ gettext_uuid = False # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. # This pattern also affects html_static_path and html_extra_path . -exclude_patterns = [ - u'_build', 'Thumbs.db', '.DS_Store', '_include/vyos-1x', - 'md-*.md', '**/md-*.md', -] - -import pathlib -_build = pathlib.Path(__file__).parent / '_build' -if (_build / '_swap_state.json').exists() and (_build / '_swap_exclude.txt').exists(): - exclude_patterns.extend( - s for s in (line.strip() for line in (_build / '_swap_exclude.txt').read_text().splitlines()) if s - ) +exclude_patterns = [u'_build', 'Thumbs.db', '.DS_Store', '_include/vyos-1x'] # The name of the Pygments (syntax highlighting) style to use. pygments_style = 'sphinx' @@ -231,18 +217,5 @@ def _prefer_webp(app): app.builder.supported_image_types = ['image/webp'] + types -def _copy_md_sources(app, exception): - """Copy .md source files verbatim into the HTML output tree.""" - if exception is not None: - return - src = pathlib.Path(app.srcdir) - out = pathlib.Path(app.outdir) - for path in src.rglob("*.md"): - dest = out / path.relative_to(src) - dest.parent.mkdir(parents=True, exist_ok=True) - shutil.copy2(path, dest) - - def setup(app): app.connect('builder-inited', _prefer_webp) - app.connect('build-finished', _copy_md_sources) diff --git a/docs/configexamples/autotest/DHCPRelay_through_GRE/_include/topology.png b/docs/configexamples/autotest/DHCPRelay_through_GRE/_include/topology.png new file mode 100644 index 00000000..952b664b Binary files /dev/null and b/docs/configexamples/autotest/DHCPRelay_through_GRE/_include/topology.png differ diff --git a/docs/configexamples/autotest/DHCPRelay_through_GRE/md-DHCPRelay_through_GRE.md b/docs/configexamples/autotest/DHCPRelay_through_GRE/md-DHCPRelay_through_GRE.md deleted file mode 100644 index 1633b349..00000000 --- a/docs/configexamples/autotest/DHCPRelay_through_GRE/md-DHCPRelay_through_GRE.md +++ /dev/null @@ -1,89 +0,0 @@ -# DHCP Relay through GRE-Bridge - -```{eval-rst} -| Testdate: 2023-05-11 -| Version: 1.4-rolling-202305100734 -``` - -This simple structure shows how to configure a DHCP Relay over a GRE Bridge -interface. - -## Topology - -The topology has 3 VyOS routers and one client. Between the DHCP Server and -the DHCP Relay is a GRE tunnel. The `transport` VyOS represent a large -Network. - -```{image} _include/topology.webp -:alt: Ansible Example topology image -``` - - -## Configuration - -First, we configure the transport network and the Tunnel interface. - -Transport: - -```{literalinclude} _include/transport.conf -:language: none -``` - -DHCP-Server - -```{literalinclude} _include/dhcp-server.conf -:language: none -:lines: 1-8 -``` - -DHCP-Relay - -```{literalinclude} _include/dhcp-relay.conf -:language: none -:lines: 1-8 -``` - -After this, we need the DHCP-Server and Relay configuration. -To get a testable result, we just have one IP in the DHCP range. -Expand it as you need it. - -DHCP-Server - -```{literalinclude} _include/dhcp-server.conf -:language: none -:lines: 9-13 -``` - -DHCP-Relay - -```{literalinclude} _include/dhcp-relay.conf -:language: none -:lines: 9-10 -``` - - -## Test the result - -Ping the Client from the DHCP Server. - -```none -vyos@dhcp-server:~$ ping 192.168.0.30 count 4 -PING 192.168.0.30 (192.168.0.30) 56(84) bytes of data. -64 bytes from 192.168.0.30: icmp_seq=1 ttl=63 time=1.02 ms -64 bytes from 192.168.0.30: icmp_seq=2 ttl=63 time=1.06 ms -64 bytes from 192.168.0.30: icmp_seq=3 ttl=63 time=1.21 ms -64 bytes from 192.168.0.30: icmp_seq=4 ttl=63 time=1.16 ms - ---- 192.168.0.30 ping statistics --- -4 packets transmitted, 4 received, 0% packet loss, time 3004ms -rtt min/avg/max/mdev = 1.016/1.112/1.214/0.077 ms -``` - -And show all DHCP Leases - -```none -vyos@dhcp-server:~$ show dhcp server leases -IP Address MAC address State Lease start Lease expiration Remaining Pool Hostname ------------- ----------------- ------- ------------------- ------------------- ----------- ---------- ---------- -192.168.0.30 00:50:79:66:68:05 active 2023/05/11 13:08:50 2023/05/12 13:08:50 23:59:16 DHCPTun100 VPCS -``` diff --git a/docs/configexamples/autotest/L3VPN_EVPN/_include/topology.png b/docs/configexamples/autotest/L3VPN_EVPN/_include/topology.png new file mode 100644 index 00000000..18ecaabb Binary files /dev/null and b/docs/configexamples/autotest/L3VPN_EVPN/_include/topology.png differ diff --git a/docs/configexamples/autotest/L3VPN_EVPN/md-L3VPN_EVPN.md b/docs/configexamples/autotest/L3VPN_EVPN/md-L3VPN_EVPN.md deleted file mode 100644 index b74452e1..00000000 --- a/docs/configexamples/autotest/L3VPN_EVPN/md-L3VPN_EVPN.md +++ /dev/null @@ -1,246 +0,0 @@ -# L3VPN EVPN with VyOS - -```{eval-rst} -| Testdate: 2023-05-11 -| Version: 1.4-rolling-202305100734 -``` - -I spun up a new lab in EVE-NG, which represents this as the -"Foo Bar - Service Provider Inc." that has 3 points of presence (PoP) in random -datacenters/sites named PE1, PE2, and PE3. Each PoP aggregates at least two -customers. - -I named the customers blue, red and green which is common practice in -VRF (Virtual Routing and Forwarding) documentation scenarios. - -- PE1 is located in an industrial area that holds multiple office buildings. - All customers have a site in this area. -- PE2 is located in a smaller area where by coincidence two customers - (blue and red) share an office building. -- PE3 is located in a smaller area where by coincidence two customers - (blue and green) are located. - -## Management VRF - -A brief excursion into VRFs: This has been one of the longest-standing feature -requests of VyOS (dating back to 2016) which can be described as -"a VLAN for layer 2 is what a VRF is for layer 3". -With VRFs, a router/system can hold multiple, isolated routing tables on the -same system. If you wonder what's the difference between multiple tables that -people used for policy-based routing since forever, it's that a VRF also -isolates connected routes rather than just static and dynamically learned -routes, so it allows NICs in different VRFs to use conflicting network -ranges without issues. - -VyOS 1.3 added initial support for VRFs (including IPv4/IPv6 static routing) -and VyOS 1.4 now enables full dynamic routing protocol support for -OSPF, IS-IS, and BGP for individual VRFs. - -The lab I built is using a VRF (called **mgmt**) to provide out-of-band -SSH access to the PE (Provider Edge) routers. - -```{literalinclude} _include/PE1.conf -:language: none -:lines: 1-6 -``` - - -## Topology - -We use the following network topology in this example: - -```{image} _include/topology.webp -:alt: L3VPN EVPN with VyOS topology image -``` - - -## Core network - -I chose to run OSPF as the IGP (Interior Gateway Protocol). -All required BGP sessions are established via a dummy interfaces -(similar to the loopback, but in Linux you can have only one loopback, -while there can be many dummy interfaces) on the PE routers. In case of a link -failure, traffic is diverted in the other direction in this triangle setup and -BGP sessions will not go down. One could even enable -BFD (Bidirectional Forwarding Detection) on the links for a faster -failover and resilience in the network. - -Regular VyOS users will notice that the BGP syntax has changed in VyOS 1.4 from -even the prior post about this subject. This is due to T1711, where it was -finally decided to get rid of the redundant BGP ASN (Autonomous System Number) -specification on the CLI and move it to a single leaf node -(set protocols bgp local-as). - -It's important to note that all your existing configurations will be migrated -automatically on image upgrade. Nothing to do on your side. - -PE1 - -```{literalinclude} _include/PE1.conf -:language: none -:lines: 8-38 -``` - -PE2 - -```{literalinclude} _include/PE2.conf -:language: none -:lines: 8-38 -``` - -PE3 - -```{literalinclude} _include/PE3.conf -:language: none -:lines: 8-38 -``` - - -## Tenant networks (VRFs) - -Once all routers can be safely remotely managed and the core network is -operational, we can now setup the tenant networks. - -Every tenant is assigned an individual VRF that would support overlapping -address ranges for customers blue, red and green. In our example, -we do not use overlapping ranges to make it easier when showing debug commands. - -Thus you can easily match it to one of the devices/networks below. - -Every router that provides access to a customer network needs to have the -customer network (VRF + VNI) configured. To make our own lives easier, -we utilize the same VRF table id (local routing table number) and -VNI (Virtual Network Identifier) per tenant on all our routers. - -- blue uses local routing table id and VNI 2000 -- red uses local routing table id and VNI 3000 -- green uses local routing table id and VNI 4000 - -PE1 - -```{literalinclude} _include/PE1.conf -:language: none -:lines: 40-96 -``` - -PE2 - -```{literalinclude} _include/PE2.conf -:language: none -:lines: 40-89 -``` - -PE3 - -```{literalinclude} _include/PE3.conf -:language: none -:lines: 40-89 -``` - - -## Testing and debugging - -You managed to come this far, now we want to see the network and routing -tables in action. - -Show routes for all VRFs - -```none -vyos@PE1:~$ show ip route vrf all -Codes: K - kernel route, C - connected, S - static, R - RIP, - O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, - T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, - f - OpenFabric, - > - selected route, * - FIB route, q - queued, r - rejected, b - backup - t - trapped, o - offload failure - -VRF blue: -C>* 10.1.1.0/24 is directly connected, br2000, 00:01:13 -B>* 10.1.2.0/24 [200/0] via 172.29.255.2, br2000 onlink, weight 1, 00:00:49 -B>* 10.1.3.0/24 [200/0] via 172.29.255.3, br2000 onlink, weight 1, 00:00:49 - -VRF default: -O 172.29.0.2/31 [110/1] is directly connected, eth1, weight 1, 00:01:09 -C>* 172.29.0.2/31 is directly connected, eth1, 00:01:12 -O>* 172.29.0.4/31 [110/2] via 172.29.0.3, eth1, weight 1, 00:00:46 - * via 172.29.0.7, eth3, weight 1, 00:00:46 -O 172.29.0.6/31 [110/1] is directly connected, eth3, weight 1, 00:01:09 -C>* 172.29.0.6/31 is directly connected, eth3, 00:01:12 -C>* 172.29.255.1/32 is directly connected, dum0, 00:01:14 -O>* 172.29.255.2/32 [110/20] via 172.29.0.3, eth1, weight 1, 00:00:50 -O>* 172.29.255.3/32 [110/20] via 172.29.0.7, eth3, weight 1, 00:00:45 - -VRF green: -C>* 10.3.1.0/24 is directly connected, br4000, 00:01:13 -B>* 10.3.3.0/24 [200/0] via 172.29.255.3, br4000 onlink, weight 1, 00:00:49 - -VRF mgmt: -S>* 0.0.0.0/0 [210/0] via 10.100.0.1, eth0, weight 1, 00:01:45 -C>* 10.100.0.0/24 is directly connected, eth0, 00:01:45 - -VRF red: -C>* 10.2.1.0/24 is directly connected, br3000, 00:01:13 -B>* 10.2.2.0/24 [200/0] via 172.29.255.2, br3000 onlink, weight 1, 00:00:49 -``` - -Information about Ethernet Virtual Private Networks - -```none -vyos@PE1:~$ show bgp l2vpn evpn -BGP table version is 1, local router ID is 172.29.255.1 -Status codes: s suppressed, d damped, h history, * valid, > best, i - internal -Origin codes: i - IGP, e - EGP, ? - incomplete -EVPN type-1 prefix: [1]:[EthTag]:[ESI]:[IPlen]:[VTEP-IP]:[Frag-id] -EVPN type-2 prefix: [2]:[EthTag]:[MAClen]:[MAC]:[IPlen]:[IP] -EVPN type-3 prefix: [3]:[EthTag]:[IPlen]:[OrigIP] -EVPN type-4 prefix: [4]:[ESI]:[IPlen]:[OrigIP] -EVPN type-5 prefix: [5]:[EthTag]:[IPlen]:[IP] - - Network Next Hop Metric LocPrf Weight Path -Route Distinguisher: 10.1.1.1:5 -*> [5]:[0]:[24]:[10.1.1.0] - 172.29.255.1 0 32768 ? - ET:8 RT:100:2000 Rmac:4e:bb:3c:ba:bd:a6 -Route Distinguisher: 10.1.2.1:4 -*>i[5]:[0]:[24]:[10.1.2.0] - 172.29.255.2 0 100 0 ? - RT:100:2000 ET:8 Rmac:26:07:da:eb:fc:ea -Route Distinguisher: 10.1.3.1:4 -*>i[5]:[0]:[24]:[10.1.3.0] - 172.29.255.3 0 100 0 ? - RT:100:2000 ET:8 Rmac:26:98:28:24:6e:54 -Route Distinguisher: 10.2.1.1:6 -*> [5]:[0]:[24]:[10.2.1.0] - 172.29.255.1 0 32768 ? - ET:8 RT:100:3000 Rmac:50:00:00:01:00:05 -Route Distinguisher: 10.2.2.1:5 -*>i[5]:[0]:[24]:[10.2.2.0] - 172.29.255.2 0 100 0 ? - RT:100:3000 ET:8 Rmac:50:00:00:02:00:05 -Route Distinguisher: 10.3.1.1:7 -*> [5]:[0]:[24]:[10.3.1.0] - 172.29.255.1 0 32768 ? - ET:8 RT:100:4000 Rmac:50:00:00:01:00:06 -Route Distinguisher: 10.3.3.1:6 -*>i[5]:[0]:[24]:[10.3.3.0] - 172.29.255.3 0 100 0 ? - RT:100:4000 ET:8 Rmac:06:32:9d:22:55:8a - -Displayed 7 out of 7 total prefixes -``` - -If we need to retrieve information about a specific host/network inside -the EVPN network we need to run - -```none -vyos@PE2:~$ show bgp l2vpn evpn 10.3.1.10 -BGP routing table entry for 10.3.1.1:7:[5]:[0]:[24]:[10.3.1.0] -Paths: (1 available, best #1) - Not advertised to any peer - Route [5]:[0]:[24]:[10.3.1.0] VNI 4000 - Local - 172.29.255.1 (metric 20) from 172.29.255.1 (172.29.255.1) - Origin incomplete, metric 0, localpref 100, valid, internal, best (First path received) - Extended Community: RT:100:4000 ET:8 Rmac:50:00:00:01:00:06 - Last update: Thu May 11 13:31:13 2023 -``` diff --git a/docs/configexamples/autotest/OpenVPN_with_LDAP/_include/topology.png b/docs/configexamples/autotest/OpenVPN_with_LDAP/_include/topology.png new file mode 100644 index 00000000..382e44f6 Binary files /dev/null and b/docs/configexamples/autotest/OpenVPN_with_LDAP/_include/topology.png differ diff --git a/docs/configexamples/autotest/OpenVPN_with_LDAP/md-OpenVPN_with_LDAP.md b/docs/configexamples/autotest/OpenVPN_with_LDAP/md-OpenVPN_with_LDAP.md deleted file mode 100644 index bd1ccfc4..00000000 --- a/docs/configexamples/autotest/OpenVPN_with_LDAP/md-OpenVPN_with_LDAP.md +++ /dev/null @@ -1,238 +0,0 @@ -(examples-openvpn-with-ldap)= - -# OpenVPN with LDAP - -```{eval-rst} -| Testdate: 2023-05-11 -| Version: 1.4-rolling-202305100734 -``` - -This LAB shows how to use OpenVPN with a Active Directory authentication method. - -Topology consists of: -: - Windows Server 2019 with a running Active Directory - - VyOS as a OpenVPN Server - - VyOS as Client - -```{image} _include/topology.webp -:alt: OpenVPN with LDAP topology image -``` - - -## Active Directory on Windows server - -The lab assumes a full running Active Directory on the Windows Server. -Here are some PowerShell commands to quickly add a Test Active Directory. - -```powershell -# install the Active Directory Server role -Install-WindowsFeature AD-Domain-Services -IncludeManagementTools - -# install the Active Directory Server role -Install-ADDSForest -DomainName "vyos.local" -DomainNetBiosName "VYOS" -InstallDns:$true -NoRebootCompletion:$true - -# create test user01 and binduser -New-ADUser binduser -AccountPassword(Read-Host -AsSecureString "Input Password") -Enabled $true -New-ADUser user01 -AccountPassword(Read-Host -AsSecureString "Input Password") -Enabled $true -``` - - -## Configure VyOS as OpenVPN Server - -In this example OpenVPN will be setup with a client certificate and username / password authentication. - -First a CA, a signed server and client ceftificate and a Diffie-Hellman parameter musst be generated and installed. -Please look {ref}`here ` for more information. - -```{eval-rst} -| Add the LDAP plugin configuration file `/config/auth/ldap-auth.config` -``` - -```{eval-rst} -| Check all possible settings `here `_. -``` - -```{literalinclude} _include/ldap-auth.config -:language: none -``` - -Now generate all required certificates on the ovpn-server: - -First the CA - -```none -vyos@ovpn-server# run generate pki ca install OVPN-CA -``` - -after this create a signed server and a client certificate - -```none -vyos@ovpn-server# run generate pki certificate sign OVPN-CA install SRV -vyos@ovpn-server# run generate pki certificate sign OVPN-CA install CLIENT -``` - -and last the DH Key - -```none -vyos@ovpn-server# run generate pki dh install DH -``` - -after all these steps the config look like this: - -```none -set pki ca OVPN-CA certificate 'MIIFnTCCA4WgAwIBAgIUIPFIXvCxYdavCnSPFNjr6lUtlsswDQYJKoZIhvcNAQELBQAwVzELMAkGA1UEBhMCR0IxEzARBgNVBAgMClNvbWUtU3RhdGUxEjAQBgNVBAcMCVNvbWUtQ2l0eTENMAsGA1UECgwEVnlPUzEQMA4GA1UEAwwHdnlvcy5pbzAeFw0yMzA1MTExMjM4MjJaFw0zMzA1MDgxMjM4MjJaMFcxCzAJBgNVBAYTAkdCMRMwEQYDVQQIDApTb21lLVN0YXRlMRIwEAYDVQQHDAlTb21lLUNpdHkxDTALBgNVBAoMBFZ5T1MxEDAOBgNVBAMMB3Z5b3MuaW8wggIiMA0GCSqGSIb3DQEBAQUAA4ICDwAwggIKAoICAQDg45vAzS6xNqU+Pa7wk1Imt1/az1C22Sbp3wPJLfgOmy0K3TA5qVsx/c/8gatsatMkCsekGnK5BPzCDd5eCCLo//B25HFO6fBYRNvHvVyCUx7QEXw4FHFNG88zCIizx114AGtVwZfGGG9xCc53xjLPUpH6iqTXme41cCFFQlqXwZ7fuySieSdoV8SAsJTTOsGCEUEcDEnNPn6tX3KWTzNuyFPECy8WCmNgWNyG2nmH+U7WRTX0ehZ5dZyU5au7TxpRN4a+JtE0gNqcWJ+nh1A543q2pcRoQpPAzHFclgj8wG/EyauQMY/LC4tLc6moPaNlTwA9HJv8s6xUqpzNptDoUHKOqKuw2JRFnno5SCQ788KkKNgVWBy2o3BGoewfHFhAdR61CXeLpmuneuhi96GcM031gW8ptXbd4DkCF7H6KRtqeIvwiyG79ttC8kZf01Sn1fM5fTjGxaE38dAk/RchtHRC6rtFavHJjB2cUcCkhhQofUE6IR2dYJZ1cw0Wy5CI3bXHf43BpvDGmuxIlNGirTq8wf5RCWzDJJgmkQpYhUYe8x4faF4gTo00uH4ZvAYjQu3JNZGkb50p4kM9Mu5rQAiZJUeMAz/QD+EIV9xXgOk14+BbnHKWbZ7Ou5emewFuE/bjl79oNJklpXdc4soRkCPCTEGK3zDBdmUtCYk1DwIDAQABo2EwXzAPBgNVHRMBAf8EBTADAQH/MA4GA1UdDwEB/wQEAwIBhjAdBgNVHSUEFjAUBggrBgEFBQcDAgYIKwYBBQUHAwEwHQYDVR0OBBYEFP5NDac/yC+mQmaTpZDUv9GZMGMBMA0GCSqGSIb3DQEBCwUAA4ICAQDEqpF2ibwYFxsF1XDIPS5/Gs0sZTZBuByNm5d2+jTyO7d5alZUdbvobbwhxZOhWasmFNyPLr4TYmZm5zF+efFsiOxjyRuEoVU+Fe8rZmpRIF/+6+nYX5r9vMI4QxGjeeyP20OHJ85Kvz182CTsITrM15Vw/kVVjAVzFI5Gm/QolalAoFQza9rAL4kDqaUszjHjPbysvDpGF+NLPjiYDHXcty/BC48bnuzAeEM60SGZ7EXvf8l0X8YsO7z39w6780A/3rbZvFhCYMKp/+p5xBRDjnX91dM6DJw73RwYQ1KHbHk9wWUwnL1giL71jzp/y4Oj6SSK2PQv+OnO80J6Zg06WIQx9xYcxr108Xh9FotUrlG7GYPI3Udf95t6SjuydDhULAVD0lMBxlDe9DHW1k1q1pOXaHZg926tY66xx/lda6dcuwJjA2Dx5JI6L0u9ureQmQAtxvnoTCtf+hR1iX/IkskZCKs34SjNiCnBuw/DNfdOpfaABm7y+tWiXBwnu5l/K8poXcQYQByyZj6YMmpgsbVPr5KNsLWOgRA81M6IPof8qxvnFrkazhiQWh1YHSjnaHtA3z5/BdgwHVICuFyrIOlbkKyJOjKcKBsDdMwIV0tsnpnyli2xEPZKu1tAQFAavXrK/RGYYhOZ3e0aRSV8hlP8i/mf7p0I45cJiBCqPg==' -set pki ca OVPN-CA private key '' -set pki certificate SRV certificate 'MIIFtTCCA52gAwIBAgIUeZnSAMPohIvKL/1Fy/pW2cV73HkwDQYJKoZIhvcNAQELBQAwVzELMAkGA1UEBhMCR0IxEzARBgNVBAgMClNvbWUtU3RhdGUxEjAQBgNVBAcMCVNvbWUtQ2l0eTENMAsGA1UECgwEVnlPUzEQMA4GA1UEAwwHdnlvcy5pbzAeFw0yMzA1MTExMjM4MzFaFw0zMzA1MDgxMjM4MzFaMFsxCzAJBgNVBAYTAkdCMRMwEQYDVQQIDApTb21lLVN0YXRlMRIwEAYDVQQHDAlTb21lLUNpdHkxDTALBgNVBAoMBFZ5T1MxFDASBgNVBAMMC292cG4tc2VydmVyMIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEApDWzTcB5LFM/tacaRHvpchBKLigJ5FlqNNfJ2vnP87KfCmTA5tkWF7MtuY990tHZtl1vQ3Pim4d6XBOngiQmaw7tZeWAIrv1L2/VBjORUrLrQhkkg9nSpcYFxoyUQzukTY75PcwhYLkS6ZO/vPPSBuh97f3XR645Aauf7ZIk2NsUidP2uGZz/Sr5VC7ovH2l3zz1kIHPCinfvpPEVb5oTt7qEffk4vnKjy9RY+H1hZowvcAp1zfLaOt/dXaK6vfNutbmwDHbYAlIals0EcjtTr+63ymxmupn7RBjgWtK7MgocGZnt6HKJ4J6teP3WgiSd+I9pdFG4wHZOSVL3axf3rBx7q09DMn/Snvfbly+SlhXw9Ebk368J6j6rhNUkxo/M9fbfgxS0JnNjHInRNAvRQW5CgQfT9KyUdxR63BeSnngk2XYX+bDinb0ig+VDpZcr6PgOBR8aNFsCPbXRwDy0bmuFnFYMzs/7ZmFQhzE6rQykHvVvAsyv7FYrlW0E02H4+Xe6bEVpE1fLcH8OCGY2cfuTfq1Ax6R4r+tdHYW1kzFLjwdh3uqTLF11zcbkAwd78E/ItrfEadvgxrYR9gfhX79AkK0VHmZ/hzrLFeGznnVcqoTKgq21dfMfQG2P13QvqS7tCE5swM9N09ASVrifyVDuoL6jaW96wgeqR6eHMECAwEAAaN1MHMwDAYDVR0TAQH/BAIwADAOBgNVHQ8BAf8EBAMCB4AwEwYDVR0lBAwwCgYIKwYBBQUHAwEwHQYDVR0OBBYEFE1U3Zamfuv6ocYiF9q7H//U8h+AMB8GA1UdIwQYMBaAFP5NDac/yC+mQmaTpZDUv9GZMGMBMA0GCSqGSIb3DQEBCwUAA4ICAQBZwHvGj/jziNFwXS2W1Q11I12YANmVhISP39AA7DNhXR+E1hXFs+U52ehurZoLTi5YTjd8PD0KcE58mw8CLsFQB/+pni9EwJuAhpMb6XsmYEp0PeOH7C/q5eOc4TB/NBsvEa5IdTmUoewmjubKeJ8OHdRBMI77Me53lSC6iskc9DGyixSLqQogQW4aiTposFJOW/YugBy7kiuygmFNJv4luDbyRBb9131zH0qSSishLT4Bp5lXQNYWI4AU0JeyQcYaSHWCr0h6H9GN3QOf/emc3/2Tee40FcEMsszJBRnQ3IISzU5xVLlfU02SJMpjvFT2MGfHAs7obrNbwiFeoLZ6fQeGLe53aOQ5M9XeW5bdIeR2ZrLoO1hW33x5jYI8nLnU0FnqpMMY14r7LZE/mjwfdrTsGChFzsLasB0Tj++mGMOXw3DSusppub17AE2bO2uO6J9XMlbkOC8EmDCF1Hetija4D3aunhtu6jRBOcR8DHVBqNae2YgUk1ALqGrNUGFH4bEioTjDDx2GieOtp9rUwJMlkAyUEe0k/wzcBLjZaO8KBCtrmTdr1wMXizPT+XcjAlzRNXvHiZFq0NG5Rnim+LH9tp90EHzO7EeVXV+LegnIKQqboIrY3KOw5Qx8ska+t1WrWHpyzpwsA0WjA6sDTyWthgNYSxb1ikNGO8STCA==' -set pki certificate SRV private key '' -set pki certificate CLIENT certificate 'MIIFsDCCA5igAwIBAgIUSzQgwzGsfJFecGxCwLXVsGCLMkAwDQYJKoZIhvcNAQELBQAwVzELMAkGA1UEBhMCR0IxEzARBgNVBAgMClNvbWUtU3RhdGUxEjAQBgNVBAcMCVNvbWUtQ2l0eTENMAsGA1UECgwEVnlPUzEQMA4GA1UEAwwHdnlvcy5pbzAeFw0yMzA1MTExMjM4MzlaFw0zMzA1MDgxMjM4MzlaMFYxCzAJBgNVBAYTAkdCMRMwEQYDVQQIDApTb21lLVN0YXRlMRIwEAYDVQQHDAlTb21lLUNpdHkxDTALBgNVBAoMBFZ5T1MxDzANBgNVBAMMBmNsaWVudDCCAiIwDQYJKoZIhvcNAQEBBQADggIPADCCAgoCggIBANHNJOSwcDbRqziL1gXYnHIq7P7vEUFvS8d/XLYJ1xIpcYTRXTut2CTGRar7fZZicu7x0yoK4TzrHvGVf1o4NC4NSGV5RX6kwRdrfWBmvpIkjSLGtCREFyhb+PHDpnsIS7cfN9udC0vocqVlx/xM/sfcP6Vja/uFp+9TQcneJIxYw34zkF+TtOVbE3pP5VxU7ZAj8F5/q1ONhTMdzG4Ol4/0nBqZfdYA3LVDeSSNIJNF5jlaKXXFHz1EJRemTYDx+f5bfCVcK2Qs8fU9jCFBlATjMu9O5rgk6nMLRwEnJZuZ1gj2tWQvz4e9yo5yUqf1PUhOrn3c81MRliUNHKr+CkxgQJal6P3Ar3q4iftJih3K+/j4o194mQ/Dt/Et+/Qn/DUFk2FB0rTMcQwJLTEAzxtTdmBJeJpipIPDR0u7UMZLNh/raQ8s3FsbY4uYORt2f5YQlCVHbth4dRa9xa+oRbm7eomNACIbWfkLh5Bzud1+qIfdBMZKaZbnf0HEeuH0J5LBJeova8EPxWbYMJPrRHzu5gowkIKl+uIxcy8IiNTA9YEoJVonCjmlr8NEtYShrIVbicdMNSI3pOQR60MFhkHwBjSU2l/z+4wwLxtzq/c2xKw9yrOZ46ZVLwGDFq8rPwp7/P9r6mDKsbn6jIvGOeH71dMZvoc4lCaClw+hKIzLAgMBAAGjdTBzMAwGA1UdEwEB/wQCMAAwDgYDVR0PAQH/BAQDAgeAMBMGA1UdJQQMMAoGCCsGAQUFBwMCMB0GA1UdDgQWBBS6j30FmL6kZW7rDH8QjRMoWoA/njAfBgNVHSMEGDAWgBT+TQ2nP8gvpkJmk6WQ1L/RmTBjATANBgkqhkiG9w0BAQsFAAOCAgEANW2Y4bgaB9oexEjj6rkGvePtQmXRkF/adVQREY9iZDGTe72ePybVzrfMkZHjse3o7JvXWRIVVztWSzEpv5noIOX7lAioGG3wsFTHotTFR0zrYJHXHBcV2Neq4Kx2Ta/TZwD8QnZHAAxEQ1pYb4fxwN/A60VElAZoz9zYsbrJyVrfuHDL9queQxPFzqis+7W1BiVIcv4rn0DMQ560jTGh4t4rImOSu5gUsUrQaih85XDdOBPxViSNwfVdZJIgbvamudpfEaKsIun/uCjcxpNnzIp0rhyYmDeqVat4GnTV7Sy48e/Uvcq71ZWbBYJF4+yW4pylIU2Sh/Uy2sAz4C2M71FlFB7qsmcnPRsFFHf+r1NyD1lkVI9k2371fTG/Kub9V0rOz4pvKz4Em5b4MUPdDbZOqJ8hQ+atGE3ovFJIovA3NFb0OtnyC4l+kG7dfjqFudOnmDa+Qsya+2YOxBZBIRfuhlXhb6Y6Smsk9R6x0jBmcQTPS5ZmvKaTxQCFc53xMdQNAswjiI2L9rw4BcqQfVmf/vpoN+VusD/XEv2V0Ixm10YybA7BI/tixh9vwj3fdQXVLy3jSYjVBd5WOFPizbQZeD10ElvlLqZZyWrP/Wre7Nmi/gEOnhBXXmo034fFF/vXf0JRpQsd2oDs24+4XwZYb8mbM31j7Nx8YvhR+64=' -set pki certificate CLIENT private key '' -set pki dh DH parameters 'MIIBCAKCAQEAzPOQWrWaIX2qt4sbV6bRbUnFx4jmeE+WXC8GIvulnC4pIr1nt2Gc/7uNfEPjDZ4X6csD3X6zAWxtSuWeNuml9Yuy+tS8gI7d0FlbQRAFO/9GIlRuVdMcbCtEhg8ja7Y0g3fQjOSQJ9mqFo7sRoXyYQALD+MDEJOxhnV7neCrgDi1pqnN4xZLoR9DLARp0ad30VIvnv0ay55wxFWAKh2iwNRwyeXIEOtUDBkfcLGSNNfK0kQsos/J8Q+7YXmk4cN9tiVX4xR92edVO4z/vhMkjsGKLSDm/E6EMusX+N0UhQ3dv7qDgeSS8vDsqBm8XJonumNZLvFbYt2ARGRZYL6DUwIBAg==' -``` - -Once all the required certificates and keys are installed, the remaining -OpenVPN Server configuration can be carried out. - -```{literalinclude} _include/ovpn-server.conf -:language: none -``` - - -## Client configuration - -One advantage of having the client certificate stored is the ability to create the client configuration. - -```none -vyos@ovpn-server:~$ generate openvpn client-config interface vtun10 ca OVPN-CA certificate CLIENT -``` - -save the output to a file and import it in nearly all openvpn clients. - -```none -client -nobind -remote 198.51.100.254 1194 -remote-cert-tls server -proto udp -dev tun -dev-type tun -persist-key -persist-tun -verb 3 - -# Encryption options - -keysize 256 -comp-lzo no - - ------BEGIN CERTIFICATE----- -MIIFnTCCA4WgAwIBAgIUIPFIXvCxYdavCnSPFNjr6lUtlsswDQYJKoZIhvcNAQEL -BQAwVzELMAkGA1UEBhMCR0IxEzARBgNVBAgMClNvbWUtU3RhdGUxEjAQBgNVBAcM -CVNvbWUtQ2l0eTENMAsGA1UECgwEVnlPUzEQMA4GA1UEAwwHdnlvcy5pbzAeFw0y -MzA1MTExMjM4MjJaFw0zMzA1MDgxMjM4MjJaMFcxCzAJBgNVBAYTAkdCMRMwEQYD -VQQIDApTb21lLVN0YXRlMRIwEAYDVQQHDAlTb21lLUNpdHkxDTALBgNVBAoMBFZ5 -T1MxEDAOBgNVBAMMB3Z5b3MuaW8wggIiMA0GCSqGSIb3DQEBAQUAA4ICDwAwggIK -AoICAQDg45vAzS6xNqU+Pa7wk1Imt1/az1C22Sbp3wPJLfgOmy0K3TA5qVsx/c/8 -gatsatMkCsekGnK5BPzCDd5eCCLo//B25HFO6fBYRNvHvVyCUx7QEXw4FHFNG88z -CIizx114AGtVwZfGGG9xCc53xjLPUpH6iqTXme41cCFFQlqXwZ7fuySieSdoV8SA -sJTTOsGCEUEcDEnNPn6tX3KWTzNuyFPECy8WCmNgWNyG2nmH+U7WRTX0ehZ5dZyU -5au7TxpRN4a+JtE0gNqcWJ+nh1A543q2pcRoQpPAzHFclgj8wG/EyauQMY/LC4tL -c6moPaNlTwA9HJv8s6xUqpzNptDoUHKOqKuw2JRFnno5SCQ788KkKNgVWBy2o3BG -oewfHFhAdR61CXeLpmuneuhi96GcM031gW8ptXbd4DkCF7H6KRtqeIvwiyG79ttC -8kZf01Sn1fM5fTjGxaE38dAk/RchtHRC6rtFavHJjB2cUcCkhhQofUE6IR2dYJZ1 -cw0Wy5CI3bXHf43BpvDGmuxIlNGirTq8wf5RCWzDJJgmkQpYhUYe8x4faF4gTo00 -uH4ZvAYjQu3JNZGkb50p4kM9Mu5rQAiZJUeMAz/QD+EIV9xXgOk14+BbnHKWbZ7O -u5emewFuE/bjl79oNJklpXdc4soRkCPCTEGK3zDBdmUtCYk1DwIDAQABo2EwXzAP -BgNVHRMBAf8EBTADAQH/MA4GA1UdDwEB/wQEAwIBhjAdBgNVHSUEFjAUBggrBgEF -BQcDAgYIKwYBBQUHAwEwHQYDVR0OBBYEFP5NDac/yC+mQmaTpZDUv9GZMGMBMA0G -CSqGSIb3DQEBCwUAA4ICAQDEqpF2ibwYFxsF1XDIPS5/Gs0sZTZBuByNm5d2+jTy -O7d5alZUdbvobbwhxZOhWasmFNyPLr4TYmZm5zF+efFsiOxjyRuEoVU+Fe8rZmpR -IF/+6+nYX5r9vMI4QxGjeeyP20OHJ85Kvz182CTsITrM15Vw/kVVjAVzFI5Gm/Qo -lalAoFQza9rAL4kDqaUszjHjPbysvDpGF+NLPjiYDHXcty/BC48bnuzAeEM60SGZ -7EXvf8l0X8YsO7z39w6780A/3rbZvFhCYMKp/+p5xBRDjnX91dM6DJw73RwYQ1KH -bHk9wWUwnL1giL71jzp/y4Oj6SSK2PQv+OnO80J6Zg06WIQx9xYcxr108Xh9FotU -rlG7GYPI3Udf95t6SjuydDhULAVD0lMBxlDe9DHW1k1q1pOXaHZg926tY66xx/ld -a6dcuwJjA2Dx5JI6L0u9ureQmQAtxvnoTCtf+hR1iX/IkskZCKs34SjNiCnBuw/D -NfdOpfaABm7y+tWiXBwnu5l/K8poXcQYQByyZj6YMmpgsbVPr5KNsLWOgRA81M6I -Pof8qxvnFrkazhiQWh1YHSjnaHtA3z5/BdgwHVICuFyrIOlbkKyJOjKcKBsDdMwI -V0tsnpnyli2xEPZKu1tAQFAavXrK/RGYYhOZ3e0aRSV8hlP8i/mf7p0I45cJiBCq -Pg== ------END CERTIFICATE----- - - - - ------BEGIN CERTIFICATE----- -MIIFsDCCA5igAwIBAgIUSzQgwzGsfJFecGxCwLXVsGCLMkAwDQYJKoZIhvcNAQEL -BQAwVzELMAkGA1UEBhMCR0IxEzARBgNVBAgMClNvbWUtU3RhdGUxEjAQBgNVBAcM -CVNvbWUtQ2l0eTENMAsGA1UECgwEVnlPUzEQMA4GA1UEAwwHdnlvcy5pbzAeFw0y -MzA1MTExMjM4MzlaFw0zMzA1MDgxMjM4MzlaMFYxCzAJBgNVBAYTAkdCMRMwEQYD -VQQIDApTb21lLVN0YXRlMRIwEAYDVQQHDAlTb21lLUNpdHkxDTALBgNVBAoMBFZ5 -T1MxDzANBgNVBAMMBmNsaWVudDCCAiIwDQYJKoZIhvcNAQEBBQADggIPADCCAgoC -ggIBANHNJOSwcDbRqziL1gXYnHIq7P7vEUFvS8d/XLYJ1xIpcYTRXTut2CTGRar7 -fZZicu7x0yoK4TzrHvGVf1o4NC4NSGV5RX6kwRdrfWBmvpIkjSLGtCREFyhb+PHD -pnsIS7cfN9udC0vocqVlx/xM/sfcP6Vja/uFp+9TQcneJIxYw34zkF+TtOVbE3pP -5VxU7ZAj8F5/q1ONhTMdzG4Ol4/0nBqZfdYA3LVDeSSNIJNF5jlaKXXFHz1EJRem -TYDx+f5bfCVcK2Qs8fU9jCFBlATjMu9O5rgk6nMLRwEnJZuZ1gj2tWQvz4e9yo5y -Uqf1PUhOrn3c81MRliUNHKr+CkxgQJal6P3Ar3q4iftJih3K+/j4o194mQ/Dt/Et -+/Qn/DUFk2FB0rTMcQwJLTEAzxtTdmBJeJpipIPDR0u7UMZLNh/raQ8s3FsbY4uY -ORt2f5YQlCVHbth4dRa9xa+oRbm7eomNACIbWfkLh5Bzud1+qIfdBMZKaZbnf0HE -euH0J5LBJeova8EPxWbYMJPrRHzu5gowkIKl+uIxcy8IiNTA9YEoJVonCjmlr8NE -tYShrIVbicdMNSI3pOQR60MFhkHwBjSU2l/z+4wwLxtzq/c2xKw9yrOZ46ZVLwGD -Fq8rPwp7/P9r6mDKsbn6jIvGOeH71dMZvoc4lCaClw+hKIzLAgMBAAGjdTBzMAwG -A1UdEwEB/wQCMAAwDgYDVR0PAQH/BAQDAgeAMBMGA1UdJQQMMAoGCCsGAQUFBwMC -MB0GA1UdDgQWBBS6j30FmL6kZW7rDH8QjRMoWoA/njAfBgNVHSMEGDAWgBT+TQ2n -P8gvpkJmk6WQ1L/RmTBjATANBgkqhkiG9w0BAQsFAAOCAgEANW2Y4bgaB9oexEjj -6rkGvePtQmXRkF/adVQREY9iZDGTe72ePybVzrfMkZHjse3o7JvXWRIVVztWSzEp -v5noIOX7lAioGG3wsFTHotTFR0zrYJHXHBcV2Neq4Kx2Ta/TZwD8QnZHAAxEQ1pY -b4fxwN/A60VElAZoz9zYsbrJyVrfuHDL9queQxPFzqis+7W1BiVIcv4rn0DMQ560 -jTGh4t4rImOSu5gUsUrQaih85XDdOBPxViSNwfVdZJIgbvamudpfEaKsIun/uCjc -xpNnzIp0rhyYmDeqVat4GnTV7Sy48e/Uvcq71ZWbBYJF4+yW4pylIU2Sh/Uy2sAz -4C2M71FlFB7qsmcnPRsFFHf+r1NyD1lkVI9k2371fTG/Kub9V0rOz4pvKz4Em5b4 -MUPdDbZOqJ8hQ+atGE3ovFJIovA3NFb0OtnyC4l+kG7dfjqFudOnmDa+Qsya+2YO -xBZBIRfuhlXhb6Y6Smsk9R6x0jBmcQTPS5ZmvKaTxQCFc53xMdQNAswjiI2L9rw4 -BcqQfVmf/vpoN+VusD/XEv2V0Ixm10YybA7BI/tixh9vwj3fdQXVLy3jSYjVBd5W -OFPizbQZeD10ElvlLqZZyWrP/Wre7Nmi/gEOnhBXXmo034fFF/vXf0JRpQsd2oDs -24+4XwZYb8mbM31j7Nx8YvhR+64= ------END CERTIFICATE----- - - - - ------BEGIN PRIVATE KEY----- -...REDACTED... ------END PRIVATE KEY----- - - -``` - - -### Configure VyOS as client - -```none -set interfaces openvpn vtun10 authentication username 'user01' -set interfaces openvpn vtun10 authentication password '$ecret' -set interfaces openvpn vtun10 encryption cipher 'aes256' -set interfaces openvpn vtun10 hash 'sha512' -set interfaces openvpn vtun10 mode 'client' -set interfaces openvpn vtun10 persistent-tunnel -set interfaces openvpn vtun10 protocol 'udp' -set interfaces openvpn vtun10 remote-host '198.51.100.254' -set interfaces openvpn vtun10 remote-port '1194' -set interfaces openvpn vtun10 tls ca-certificate 'OVPN-CA' -set interfaces openvpn vtun10 tls certificate 'CLIENT' -``` - - -## Monitoring - -If the client is connected successfully you can check the status - -```none -vyos@ovpn-server:~$ show openvpn server -OpenVPN status on vtun10 - -Client CN Remote Host Tunnel IP Local Host TX bytes RX bytes Connected Since ------------ ------------------ ----------- ------------------- ---------- ---------- ------------------- -client 198.51.100.1:55150 10.23.1.6 198.51.100.254:1194 4.7 KB 4.7 KB 2023-05-11 12:47:11 -``` diff --git a/docs/configexamples/autotest/Wireguard/_include/topology.png b/docs/configexamples/autotest/Wireguard/_include/topology.png new file mode 100644 index 00000000..43c0018e Binary files /dev/null and b/docs/configexamples/autotest/Wireguard/_include/topology.png differ diff --git a/docs/configexamples/autotest/Wireguard/md-Wireguard.md b/docs/configexamples/autotest/Wireguard/md-Wireguard.md deleted file mode 100644 index 7bbf4c55..00000000 --- a/docs/configexamples/autotest/Wireguard/md-Wireguard.md +++ /dev/null @@ -1,108 +0,0 @@ -# Wireguard - -```{eval-rst} -| Testdate: 2024-01-13 -| Version: 1.5-rolling-202401121239 -``` - -This simple structure show how to connect two offices. One remote branch and the -central office. - -## Topology - -The topology have a central and a branch VyOS router and one client, to -test, in each site. - -```{image} _include/topology.webp -:alt: Ansible Example topology image -``` - - -## Configuration - -Set the local subnet on eth2 and the public ip address eth1 on each site. - -Central - -```{literalinclude} _include/central.conf -:language: none -:lines: 1-2 -``` - -Branch - -```{literalinclude} _include/branch.conf -:language: none -:lines: 1-2 -``` - -Next thing to do, is to create a wireguard keypair on each side. -After this, the public key can be displayed, to save for later. - -```none -vyos@central:~$ generate pki wireguard -Private key: wHQS+ib3eMIp2DxRiAeXfFVaSCMMP1YHBaKfSR1xfV8= -Public key: RCMy6BAER0uEcPvspUb3K38MHyHJpK5kiV5IOX943HI= -``` - -After you have each public key. The wireguard interfaces can be setup. - -Central - -```{literalinclude} _include/central.conf -:language: none -:lines: 4-12 -``` - -Branch - -```{literalinclude} _include/branch.conf -:language: none -:lines: 4-12 -``` - -To reach the network, a route must be set on each VyOS host. -In this structure, a static interface route will fit the requirements. - -Central - -```{literalinclude} _include/central.conf -:language: none -:lines: 14 -``` - -Branch - -```{literalinclude} _include/branch.conf -:language: none -:lines: 14 -``` - - -## Testing and debugging - -After all is done and commit, let's take a look if the Wireguard interface is -up and running. - -```none -vyos@central:~$ show interfaces wireguard -Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down -Interface IP Address S/L Description ---------- ---------- --- ----------- -wg01 192.168.0.1/24 u/u VPN-to-Branch -``` - -And ping the Branch PC from your central router to check the response. - -```none -vyos@central:~$ ping 10.0.2.100 count 4 -PING 10.0.2.100 (10.0.2.100) 56(84) bytes of data. -64 bytes from 10.0.2.100: icmp_seq=1 ttl=63 time=0.894 ms -64 bytes from 10.0.2.100: icmp_seq=2 ttl=63 time=0.869 ms -64 bytes from 10.0.2.100: icmp_seq=3 ttl=63 time=0.966 ms -64 bytes from 10.0.2.100: icmp_seq=4 ttl=63 time=0.998 ms - ---- 10.0.2.100 ping statistics --- -4 packets transmitted, 4 received, 0% packet loss, time 3004ms -rtt min/avg/max/mdev = 0.869/0.931/0.998/0.052 ms -``` diff --git a/docs/configexamples/autotest/tunnelbroker/_include/topology.png b/docs/configexamples/autotest/tunnelbroker/_include/topology.png new file mode 100644 index 00000000..e70d55bc Binary files /dev/null and b/docs/configexamples/autotest/tunnelbroker/_include/topology.png differ diff --git a/docs/configexamples/autotest/tunnelbroker/md-tunnelbroker.md b/docs/configexamples/autotest/tunnelbroker/md-tunnelbroker.md deleted file mode 100644 index 6c59a491..00000000 --- a/docs/configexamples/autotest/tunnelbroker/md-tunnelbroker.md +++ /dev/null @@ -1,206 +0,0 @@ -(examples-tunnelbroker-ipv6)= - -# Tunnelbroker.net (IPv6) - -```{eval-rst} -| Testdate: 2024-01-13 -| Version: 1.5-rolling-202401121239 -``` - -This guide walks through the setup of for an -IPv6 Tunnel. - -## Prerequisites - -- A public, routable IPv4 address. This does not necessarily need to be static, - but you will need to update the tunnel endpoint when/if your IP address - changes, which can be done with a script and a scheduled task. -- Account at -- Requested a "Regular Tunnel". You want to choose a location that is closest - to your physical location for the best response time. - -### Topology - -The example topology has 2 VyOS routers. One as the WAN router and one as a -client, to test a single LAN setup - -```{image} _include/topology.webp -:alt: Tunnelbroker topology image -``` - - -### Configuration - -First, we configure the `vyos-wan` interface to get a DHCP address. - -```{literalinclude} _include/vyos-wan.conf -:language: none -``` - -Now we are able to setup the tunnel interface. - -```{literalinclude} _include/vyos-wan_tun0.conf -:language: none -:lines: 1-5 -``` - -:::{note} -The `source-address` is the Tunnelbroker client IPv4 -address or if there is NAT the current WAN interface address. - -If `source-address` is dynamic, the tunnel will cease working once -the address changes. To avoid having to manually update -`source-address` each time the dynamic IP changes, an address of -'0.0.0.0' can be specified. -::: - -Setup the IPv6 default route to the tunnel interface - -```{literalinclude} _include/vyos-wan_tun0.conf -:language: none -:lines: 7 -``` - -Now you should be able to ping a public IPv6 Address - -```none -vyos@vyos-wan:~$ ping 2001:470:20::2 count 4 -PING 2001:470:20::2(2001:470:20::2) 56 data bytes -64 bytes from 2001:470:20::2: icmp_seq=1 ttl=64 time=33.8 ms -64 bytes from 2001:470:20::2: icmp_seq=2 ttl=64 time=43.9 ms -64 bytes from 2001:470:20::2: icmp_seq=3 ttl=64 time=43.4 ms -64 bytes from 2001:470:20::2: icmp_seq=4 ttl=64 time=42.5 ms - ---- 2001:470:20::2 ping statistics --- -4 packets transmitted, 4 received, 0% packet loss, time 2999ms -rtt min/avg/max/mdev = 33.802/40.920/43.924/4.139 ms -``` - -Assuming the pings are successful, you need to add some DNS servers. -Some options: - -```{literalinclude} _include/vyos-wan_tun0.conf -:language: none -:lines: 13 -``` - -You should now be able to ping something by IPv6 DNS name: - -```none -vyos@vyos-wan:~$ ping tunnelbroker.net count 4 -PING tunnelbroker.net(tunnelbroker.net (2001:470:0:63::2)) 56 data bytes -64 bytes from tunnelbroker.net (2001:470:0:63::2): icmp_seq=1 ttl=48 time=285 ms -64 bytes from tunnelbroker.net (2001:470:0:63::2): icmp_seq=2 ttl=48 time=186 ms -64 bytes from tunnelbroker.net (2001:470:0:63::2): icmp_seq=3 ttl=48 time=178 ms -64 bytes from tunnelbroker.net (2001:470:0:63::2): icmp_seq=4 ttl=48 time=177 ms - ---- tunnelbroker.net ping statistics --- -4 packets transmitted, 4 received, 0% packet loss, time 3002ms -rtt min/avg/max/mdev = 176.707/206.638/285.128/45.457 ms -``` - - -### LAN Configuration - -At this point, your VyOS install should have full IPv6, but now your LAN devices -need access. - -With Tunnelbroker.net, you have two options: - -- Routed /64. This is the default assignment. In IPv6-land, it's good for a - single "LAN", and is somewhat equivalent to a /24. -- Routed /48. This is something you can request by clicking the "Assign /48" - link in the Tunnelbroker.net tunnel config. It allows you to have up to 65k - -Unlike IPv4, IPv6 is really not designed to be broken up smaller than /64. So -if you ever want to have multiple LANs, VLANs, DMZ, etc, you'll want to ignore -the assigned /64, and request the /48 and use that. - -## Single LAN Setup - -Single LAN setup where eth2 is your LAN interface. Use the Tunnelbroker -Routed /64 prefix: - -```{literalinclude} _include/vyos-wan_tun0.conf -:language: none -:lines: 9-11 -``` - -Please note, 'autonomous-flag' and 'on-link-flag' are enabled by default, -'valid-lifetime' and 'preferred-lifetime' are set to default values of -30 days and 4 hours respectively. - -And the `client` to receive an IPv6 address with stateless autoconfig. - -```{literalinclude} _include/client.conf -:language: none -``` - -This accomplishes a few things: -- Sets your LAN interface's IP address -- Enables router advertisements. This is an IPv6 alternative for DHCP (though - DHCPv6 can still be used). With RAs, Your devices will automatically find the - information they need for routing and DNS. - -Now the Client is able to ping a public IPv6 address - -```none -vyos@client:~$ ping 2001:470:20::2 count 4 -PING 2001:470:20::2(2001:470:20::2) 56 data bytes -64 bytes from 2001:470:20::2: icmp_seq=1 ttl=63 time=32.1 ms -64 bytes from 2001:470:20::2: icmp_seq=2 ttl=63 time=41.8 ms -64 bytes from 2001:470:20::2: icmp_seq=3 ttl=63 time=41.7 ms -64 bytes from 2001:470:20::2: icmp_seq=4 ttl=63 time=47.1 ms - ---- 2001:470:20::2 ping statistics --- -4 packets transmitted, 4 received, 0% packet loss, time 3005ms -rtt min/avg/max/mdev = 32.128/40.688/47.107/5.403 ms -``` - - -## Multiple LAN/DMZ Setup - -That's how you can expand the example above. -Use the `Routed /48` information. This allows you to assign a -different /64 to every interface, LAN, or even device. Or you could break your -network into smaller chunks like /56 or /60. - -The format of these addresses: -- `2001:470:xxxx::/48`: The whole subnet. xxxx should come from Tunnelbroker. -- `2001:470:xxxx:1::/64`: A subnet suitable for a LAN -- `2001:470:xxxx:2::/64`: Another subnet -- `2001:470:xxxx:ffff::/64`: The last usable /64 subnet. - -In the above examples, 1,2,ffff are all chosen by you. You can use 1-ffff -(1-65535). - -So, when your LAN is eth1, your DMZ is eth2, your cameras are on eth3, etc: - -```none -set interfaces ethernet eth1 address '2001:470:xxxx:1::1/64' -set service router-advert interface eth1 name-server '2001:470:20::2' -set service router-advert interface eth1 prefix 2001:470:xxxx:1::/64 - -set interfaces ethernet eth2 address '2001:470:xxxx:2::1/64' -set service router-advert interface eth2 name-server '2001:470:20::2' -set service router-advert interface eth2 prefix 2001:470:xxxx:2::/64 - -set interfaces ethernet eth3 address '2001:470:xxxx:3::1/64' -set service router-advert interface eth3 name-server '2001:470:20::2' -set service router-advert interface eth3 prefix 2001:470:xxxx:3::/64 -``` - -Please note, 'autonomous-flag' and 'on-link-flag' are enabled by default, -'valid-lifetime' and 'preferred-lifetime' are set to default values of -30 days and 4 hours respectively. - -## Firewall - -Finally, don't forget the -{ref}`Firewall `. The usage is -identical, except instead of `set firewall ipv4 name NAME`, you would -use `set firewall ipv6 name NAME`. - -Similarly, to attach the firewall, you would use -`set firewall ipv6 name NAME rule N inbound-interface name eth0` or -`set firewall zone LOCAL from WAN firewall ipv6-name`. diff --git a/docs/configexamples/md-ansible.md b/docs/configexamples/md-ansible.md deleted file mode 100644 index 8bbd9306..00000000 --- a/docs/configexamples/md-ansible.md +++ /dev/null @@ -1,212 +0,0 @@ ---- -lastproofread: '2024-04-09' ---- - -(examples-ansible)= - -# Ansible example - -## Setting up Ansible on a server running the Debian operating system. - -In this example, we will set up a simple use of Ansible to configure -multiple VyOS routers. -We have four pre-configured routers with this configuration: - -Using the general schema for example: - -```{image} /_static/images/ansible.webp -:align: center -:alt: Network Topology Diagram -:width: 80% -``` - -We have four pre-configured routers with this configuration: - -```none -set interfaces ethernet eth0 address dhcp -set service ssh -commit -save -``` - -- vyos7 - 192.0.2.105 -- vyos8 - 192.0.2.106 -- vyos9 - 192.0.2.107 -- vyos10 - 192.0.2.108 - -## Install Ansible: - -```none -# apt-get install ansible -Do you want to continue? [Y/n] y -``` - - -## Install Paramiko: - -```none -#apt-get install -y python3-paramiko -``` - - -## Check the version: - -```none -# ansible --version -ansible 2.10.8 -config file = None -configured module search path = ['/root/.ansible/plugins/modules', '/usr/share/ansible/plugins/modules'] -ansible python module location = /usr/lib/python3/dist-packages/ansible -executable location = /usr/bin/ansible -python version = 3.9.2 (default, Feb 28 2021, 17:03:44) [GCC 10.2.1 20210110] -``` - - -## Basic configuration of ansible.cfg: - -```none -# nano /root/ansible.cfg -[defaults] -host_key_checking = no -``` - - -## Add all the VyOS hosts: - -```none -# nano /root/hosts -[vyos_hosts] -vyos7 ansible_ssh_host=192.0.2.105 -vyos8 ansible_ssh_host=192.0.2.106 -vyos9 ansible_ssh_host=192.0.2.107 -vyos10 ansible_ssh_host=192.0.2.108 -``` - - -## Add general variables: - -```none -# mkdir /root/group_vars/ -# nano /root/group_vars/vyos_hosts -ansible_python_interpreter: /usr/bin/python3 -ansible_network_os: vyos -ansible_connection: network_cli -ansible_user: vyos -ansible_ssh_pass: vyos -``` - - -## Add a simple playbook with the tasks for each router: - -```none -# nano /root/main.yml - ---- -- hosts: vyos_hosts - gather_facts: 'no' - tasks: - - name: Configure general settings for the vyos hosts group - vyos_config: - lines: - - set system name-server 192.0.2.1 - - set interfaces ethernet eth0 description '#WAN#' - - set interfaces ethernet eth1 description '#LAN#' - - set interfaces ethernet eth2 disable - - set interfaces ethernet eth3 disable - - set system host-name {{ inventory_hostname }} - save: true -``` - - -## Start the playbook: - -```none -ansible-playbook -i hosts main.yml -PLAY [vyos_hosts] ************************************************************** - -TASK [Configure general settings for the vyos hosts group] ********************* -ok: [vyos9] -ok: [vyos10] -ok: [vyos7] -ok: [vyos8] - -PLAY RECAP ********************************************************************* -vyos10 : ok=2 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 -vyos7 : ok=2 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 -vyos8 : ok=2 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 -vyos9 : ok=2 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 -``` - - -## Check the result on the vyos10 router: - -```none -vyos@vyos10:~$ show interfaces -Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down -Interface IP Address S/L Description ---------- ---------- --- ----------- -eth0 192.0.2.108/24 u/u WAN -eth1 - u/u LAN -eth2 - A/D -eth3 - A/D -lo 127.0.0.1/8 u/u - ::1/128 - -vyos@vyos10:~$ sh configuration commands | grep 192.0.2.1 -set system name-server '192.0.2.1' -``` - - -## The simple way without configuration of the hostname (one task for all routers): - -```none -# nano /root/hosts_v2 -[vyos_hosts_group] -vyos7 ansible_ssh_host=192.0.2.105 -vyos8 ansible_ssh_host=192.0.2.106 -vyos9 ansible_ssh_host=192.0.2.107 -vyos10 ansible_ssh_host=192.0.2.108 -[vyos_hosts_group:vars] -ansible_python_interpreter=/usr/bin/python3 -ansible_user=vyos -ansible_ssh_pass=vyos -ansible_network_os=vyos -ansible_connection=network_cli - -# nano /root/main_v2.yml ---- -- hosts: vyos_hosts_group - connection: network_cli - gather_facts: 'no' - tasks: - - name: Configure remote vyos_hosts_group - vyos_config: - lines: - - set system name-server 192.0.2.1 - - set interfaces ethernet eth0 description WAN - - set interfaces ethernet eth1 description LAN - - set interfaces ethernet eth2 disable - - set interfaces ethernet eth3 disable - save: true -``` - -```none -# ansible-playbook -i hosts_v2 main_v2.yml - -PLAY [vyos_hosts_group] ******************************************************** - -TASK [Configure remote vyos_hosts_group] *************************************** -ok: [vyos8] -ok: [vyos7] -ok: [vyos9] -ok: [vyos10] - -PLAY RECAP ********************************************************************* -vyos10 : ok=1 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 -vyos7 : ok=1 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 -vyos8 : ok=1 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 -vyos9 : ok=1 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 -``` - -In the next chapter of the example, we'll use Ansible with jinja2 -templates and variables. diff --git a/docs/configexamples/md-azure-vpn-bgp.md b/docs/configexamples/md-azure-vpn-bgp.md deleted file mode 100644 index 83d77e53..00000000 --- a/docs/configexamples/md-azure-vpn-bgp.md +++ /dev/null @@ -1,134 +0,0 @@ ---- -lastproofread: '2021-06-28' ---- - -(examples-azure-vpn-bgp)= - -# Route-Based Site-to-Site VPN to Azure (BGP over IKEv2/IPsec) - -This guide shows an example of a route-based IKEv2 site-to-site VPN to -Azure using VTI and BGP for dynamic routing updates. - -For redundant / active-active configurations see -{ref}`examples-azure-vpn-dual-bgp` - -## Prerequisites - -- A pair of Azure VNet Gateways deployed in active-passive - configuration with BGP enabled. -- A local network gateway deployed in Azure representing - the Vyos device, matching the below Vyos settings except for - address space, which only requires the Vyos private IP, in - this example 10.10.0.5/32 -- A connection resource deployed in Azure linking the - Azure VNet gateway and the local network gateway representing - the Vyos device. - -## Example - -```{eval-rst} -+---------------------------------------+---------------------+ -| WAN Interface | eth0 | -+---------------------------------------+---------------------+ -| On-premises address space | 10.10.0.0/16 | -+---------------------------------------+---------------------+ -| Azure address space | 10.0.0.0/16 | -+---------------------------------------+---------------------+ -| Vyos public IP | 198.51.100.3 | -+---------------------------------------+---------------------+ -| Vyos private IP | 10.10.0.5 | -+---------------------------------------+---------------------+ -| Azure VNet Gateway public IP | 203.0.113.2 | -+---------------------------------------+---------------------+ -| Azure VNet Gateway BGP IP | 10.0.0.4 | -+---------------------------------------+---------------------+ -| Pre-shared key | ch00s3-4-s3cur3-psk | -+---------------------------------------+---------------------+ -| Vyos ASN | 64499 | -+---------------------------------------+---------------------+ -| Azure ASN | 65540 | -+---------------------------------------+---------------------+ -``` - -## Vyos configuration - -- Configure the IKE and ESP settings to match a subset - of those supported by Azure: - -```none -set vpn ipsec esp-group AZURE lifetime '3600' -set vpn ipsec esp-group AZURE mode 'tunnel' -set vpn ipsec esp-group AZURE pfs 'dh-group2' -set vpn ipsec esp-group AZURE proposal 1 encryption 'aes256' -set vpn ipsec esp-group AZURE proposal 1 hash 'sha1' - -set vpn ipsec ike-group AZURE dead-peer-detection action 'restart' -set vpn ipsec ike-group AZURE dead-peer-detection interval '15' -set vpn ipsec ike-group AZURE dead-peer-detection timeout '30' -set vpn ipsec ike-group AZURE ikev2-reauth -set vpn ipsec ike-group AZURE key-exchange 'ikev2' -set vpn ipsec ike-group AZURE lifetime '28800' -set vpn ipsec ike-group AZURE proposal 1 dh-group '2' -set vpn ipsec ike-group AZURE proposal 1 encryption 'aes256' -set vpn ipsec ike-group AZURE proposal 1 hash 'sha1' -``` - -- Enable IPsec on eth0 - -```none -set vpn ipsec interface 'eth0' -``` - -- Configure a VTI with a dummy IP address - -```none -set interfaces vti vti1 address '10.10.1.5/32' -set interfaces vti vti1 description 'Azure Tunnel' -``` - -- Clamp the VTI's MSS to 1350 to avoid PMTU blackholes. - -```none -set interfaces vti vti1 ip adjust-mss 1350 -``` - -- Configure the VPN tunnel - -```none -set vpn ipsec authentication psk azure id '198.51.100.3' -set vpn ipsec authentication psk azure id '203.0.113.2' -set vpn ipsec authentication psk azure secret 'ch00s3-4-s3cur3-psk' -set vpn ipsec site-to-site peer 203.0.113.2 authentication local-id '198.51.100.3' -set vpn ipsec site-to-site peer 203.0.113.2 authentication mode 'pre-shared-secret' -set vpn ipsec site-to-site peer 203.0.113.2 authentication remote-id '203.0.113.2' -set vpn ipsec site-to-site peer 203.0.113.2 connection-type 'initiate' -set vpn ipsec site-to-site peer 203.0.113.2 description 'AZURE PRIMARY TUNNEL' -set vpn ipsec site-to-site peer 203.0.113.2 ike-group 'AZURE' -set vpn ipsec site-to-site peer 203.0.113.2 ikev2-reauth 'inherit' -set vpn ipsec site-to-site peer 203.0.113.2 local-address '10.10.0.5' -set vpn ipsec site-to-site peer 203.0.113.2 remote-address '203.0.113.2' -set vpn ipsec site-to-site peer 203.0.113.2 vti bind 'vti1' -set vpn ipsec site-to-site peer 203.0.113.2 vti esp-group 'AZURE' -``` - -- **Important**: Add an interface route to reach Azure's BGP listener - -```none -set protocols static route 10.0.0.4/32 interface vti1 -``` - -- Configure your BGP settings - -```none -set protocols bgp system-as 64499 -set protocols bgp neighbor 10.0.0.4 remote-as '65540' -set protocols bgp neighbor 10.0.0.4 address-family ipv4-unicast soft-reconfiguration 'inbound' -set protocols bgp neighbor 10.0.0.4 timers holdtime '30' -set protocols bgp neighbor 10.0.0.4 timers keepalive '10' -``` - -- **Important**: Disable connected check - -```none -set protocols bgp neighbor 10.0.0.4 disable-connected-check -``` diff --git a/docs/configexamples/md-azure-vpn-dual-bgp.md b/docs/configexamples/md-azure-vpn-dual-bgp.md deleted file mode 100644 index 967debd4..00000000 --- a/docs/configexamples/md-azure-vpn-dual-bgp.md +++ /dev/null @@ -1,160 +0,0 @@ ---- -lastproofread: '2021-06-28' ---- - -(examples-azure-vpn-dual-bgp)= - -# Route-Based Redundant Site-to-Site VPN to Azure (BGP over IKEv2/IPsec) - -This guide shows an example of a redundant (active-active) route-based IKEv2 -site-to-site VPN to Azure using VTI -and BGP for dynamic routing updates. - -## Prerequisites - -- A pair of Azure VNet Gateways deployed in active-active - configuration with BGP enabled. -- A local network gateway deployed in Azure representing - the Vyos device, matching the below Vyos settings except for - address space, which only requires the Vyos private IP, in - this example 10.10.0.5/32 -- A connection resource deployed in Azure linking the - Azure VNet gateway and the local network gateway representing - the Vyos device. - -## Example - -```{eval-rst} -+---------------------------------------+---------------------+ -| WAN Interface | eth0 | -+---------------------------------------+---------------------+ -| On-premises address space | 10.10.0.0/16 | -+---------------------------------------+---------------------+ -| Azure address space | 10.0.0.0/16 | -+---------------------------------------+---------------------+ -| Vyos public IP | 198.51.100.3 | -+---------------------------------------+---------------------+ -| Vyos private IP | 10.10.0.5 | -+---------------------------------------+---------------------+ -| Azure VNet Gateway 1 public IP | 203.0.113.2 | -+---------------------------------------+---------------------+ -| Azure VNet Gateway 2 public IP | 203.0.113.3 | -+---------------------------------------+---------------------+ -| Azure VNet Gateway BGP IP | 10.0.0.4,10.0.0.5 | -+---------------------------------------+---------------------+ -| Pre-shared key | ch00s3-4-s3cur3-psk | -+---------------------------------------+---------------------+ -| Vyos ASN | 64499 | -+---------------------------------------+---------------------+ -| Azure ASN | 65540 | -+---------------------------------------+---------------------+ -``` - -## Vyos configuration - -- Configure the IKE and ESP settings to match a subset - of those supported by Azure: - -```none -set vpn ipsec esp-group AZURE lifetime '3600' -set vpn ipsec esp-group AZURE mode 'tunnel' -set vpn ipsec esp-group AZURE pfs 'dh-group2' -set vpn ipsec esp-group AZURE proposal 1 encryption 'aes256' -set vpn ipsec esp-group AZURE proposal 1 hash 'sha1' - -set vpn ipsec ike-group AZURE dead-peer-detection action 'restart' -set vpn ipsec ike-group AZURE dead-peer-detection interval '15' -set vpn ipsec ike-group AZURE dead-peer-detection timeout '30' -set vpn ipsec ike-group AZURE ikev2-reauth -set vpn ipsec ike-group AZURE key-exchange 'ikev2' -set vpn ipsec ike-group AZURE lifetime '28800' -set vpn ipsec ike-group AZURE proposal 1 dh-group '2' -set vpn ipsec ike-group AZURE proposal 1 encryption 'aes256' -set vpn ipsec ike-group AZURE proposal 1 hash 'sha1' -``` - -- Enable IPsec on eth0 - -```none -set vpn ipsec interface 'eth0' -``` - -- Configure two VTIs with a dummy IP address each - -```none -set interfaces vti vti1 address '10.10.1.5/32' -set interfaces vti vti1 description 'Azure Primary Tunnel' - -set interfaces vti vti2 address '10.10.1.6/32' -set interfaces vti vti2 description 'Azure Secondary Tunnel' -``` - -- Clamp the VTI's MSS to 1350 to avoid PMTU blackholes. - -```none -set interfaces vti vti1 ip adjust-mss 1350 -set interfaces vti vti2 ip adjust-mss 1350 -``` - -- Configure the VPN tunnels - -```none -set vpn ipsec authentication psk azure id '198.51.100.3' -set vpn ipsec authentication psk azure id '203.0.113.2' -set vpn ipsec authentication psk azure id '203.0.113.3' -set vpn ipsec authentication psk azure secret 'ch00s3-4-s3cur3-psk' - -set vpn ipsec site-to-site peer azure-primary authentication local-id '198.51.100.3' -set vpn ipsec site-to-site peer azure-primary authentication mode 'pre-shared-secret' -set vpn ipsec site-to-site peer azure-primary authentication remote-id '203.0.113.2' -set vpn ipsec site-to-site peer azure-primary connection-type 'initiate' -set vpn ipsec site-to-site peer azure-primary description 'AZURE PRIMARY TUNNEL' -set vpn ipsec site-to-site peer azure-primary ike-group 'AZURE' -set vpn ipsec site-to-site peer azure-primary ikev2-reauth 'inherit' -set vpn ipsec site-to-site peer azure-primary local-address '10.10.0.5' -set vpn ipsec site-to-site peer azure-primary remote-address '203.0.113.2' -set vpn ipsec site-to-site peer azure-primary vti bind 'vti1' -set vpn ipsec site-to-site peer azure-primary vti esp-group 'AZURE' - -set vpn ipsec site-to-site peer azure-secondary authentication local-id '198.51.100.3' -set vpn ipsec site-to-site peer azure-secondary authentication mode 'pre-shared-secret' -set vpn ipsec site-to-site peer azure-secondary authentication remote-id '203.0.113.3' -set vpn ipsec site-to-site peer azure-secondary connection-type 'initiate' -set vpn ipsec site-to-site peer azure-secondary description 'AZURE secondary TUNNEL' -set vpn ipsec site-to-site peer azure-secondary ike-group 'AZURE' -set vpn ipsec site-to-site peer azure-secondary ikev2-reauth 'inherit' -set vpn ipsec site-to-site peer azure-secondary local-address '10.10.0.5' -set vpn ipsec site-to-site peer azure-secondary remote-address '203.0.113.3' -set vpn ipsec site-to-site peer azure-secondary vti bind 'vti2' -set vpn ipsec site-to-site peer azure-secondary vti esp-group 'AZURE' -``` - -- **Important**: Add an interface route to reach both Azure's BGP listeners - -```none -set protocols static route 10.0.0.4/32 interface vti1 -set protocols static route 10.0.0.5/32 interface vti2 -``` - -- Configure your BGP settings - -```none -set protocols bgp system-as 64499 -set protocols bgp neighbor 10.0.0.4 remote-as '65540' -set protocols bgp neighbor 10.0.0.4 address-family ipv4-unicast soft-reconfiguration 'inbound' -set protocols bgp neighbor 10.0.0.4 timers holdtime '30' -set protocols bgp neighbor 10.0.0.4 timers keepalive '10' - -set protocols bgp neighbor 10.0.0.5 remote-as '65540' -set protocols bgp neighbor 10.0.0.5 address-family ipv4-unicast soft-reconfiguration 'inbound' -set protocols bgp neighbor 10.0.0.5 timers holdtime '30' -set protocols bgp neighbor 10.0.0.5 timers keepalive '10' -``` - -- **Important**: Disable connected check, otherwise the routes learned - from Azure will not be imported into the routing table. - -```none -set protocols bgp neighbor 10.0.0.4 disable-connected-check -set protocols bgp neighbor 10.0.0.5 disable-connected-check -``` diff --git a/docs/configexamples/md-bgp-ipv6-unnumbered.md b/docs/configexamples/md-bgp-ipv6-unnumbered.md deleted file mode 100644 index 4fa29834..00000000 --- a/docs/configexamples/md-bgp-ipv6-unnumbered.md +++ /dev/null @@ -1,174 +0,0 @@ ---- -lastproofread: '2021-06-28' ---- - -(examples-bgp-ipv6-unnumbered)= - -# BGP IPv6 unnumbered with extended nexthop - -General information can be found in the {ref}`routing-bgp` chapter. - -## Configuration - -- Router A: - -```none -set protocols bgp system-as 64496 -set protocols bgp address-family ipv4-unicast redistribute connected -set protocols bgp address-family ipv6-unicast redistribute connected -set protocols bgp neighbor eth1 interface v6only -set protocols bgp neighbor eth1 interface v6only peer-group 'fabric' -set protocols bgp neighbor eth2 interface v6only -set protocols bgp neighbor eth2 interface v6only peer-group 'fabric' -set protocols bgp parameters bestpath as-path multipath-relax -set protocols bgp parameters bestpath compare-routerid -set protocols bgp parameters default no-ipv4-unicast -set protocols bgp parameters router-id '192.168.0.1' -set protocols bgp peer-group fabric address-family ipv4-unicast -set protocols bgp peer-group fabric address-family ipv6-unicast -set protocols bgp peer-group fabric capability extended-nexthop -set protocols bgp peer-group fabric remote-as 'external' -``` - -- Router B: - -```none -set protocols bgp system-as 64499 -set protocols bgp address-family ipv4-unicast redistribute connected -set protocols bgp address-family ipv6-unicast redistribute connected -set protocols bgp neighbor eth1 interface v6only -set protocols bgp neighbor eth1 interface v6only peer-group 'fabric' -set protocols bgp neighbor eth2 interface v6only -set protocols bgp neighbor eth2 interface v6only peer-group 'fabric' -set protocols bgp parameters bestpath as-path multipath-relax -set protocols bgp parameters bestpath compare-routerid -set protocols bgp parameters default no-ipv4-unicast -set protocols bgp parameters router-id '192.168.0.2' -set protocols bgp peer-group fabric address-family ipv4-unicast -set protocols bgp peer-group fabric address-family ipv6-unicast -set protocols bgp peer-group fabric capability extended-nexthop -set protocols bgp peer-group fabric remote-as 'external' -``` - - -## Results - -- Router A: - -```none -vyos@vyos:~$ show interfaces -Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down -Interface IP Address S/L Description ---------- ---------- --- ----------- -eth0 198.51.100.34/24 u/u -eth1 - u/u -eth2 - u/u -lo 127.0.0.1/8 u/u - 192.168.0.1/32 - ::1/128 -``` - -```none -vyos@vyos:~$ show ip route -Codes: K - kernel route, C - connected, S - static, R - RIP, - O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, - T - Table, v - VNC, V - VNC-Direct, A - Babel, D - SHARP, - F - PBR, f - OpenFabric, - > - selected route, * - FIB route - -S>* 0.0.0.0/0 [210/0] via 198.51.100.34, eth0, 03:21:53 -C>* 198.51.100.0/24 is directly connected, eth0, 03:21:53 -C>* 192.168.0.1/32 is directly connected, lo, 03:21:56 -B>* 192.168.0.2/32 [20/0] via fe80::a00:27ff:fe3b:7ed2, eth2, 00:05:07 - * via fe80::a00:27ff:fe7b:4000, eth1, 00:05:07 -``` - -```none -vyos@vyos:~$ ping 192.168.0.2 -PING 192.168.0.2 (192.168.0.2) 56(84) bytes of data. -64 bytes from 192.168.0.2: icmp_seq=1 ttl=64 time=0.575 ms -64 bytes from 192.168.0.2: icmp_seq=2 ttl=64 time=0.628 ms -64 bytes from 192.168.0.2: icmp_seq=3 ttl=64 time=0.581 ms -64 bytes from 192.168.0.2: icmp_seq=4 ttl=64 time=0.682 ms -64 bytes from 192.168.0.2: icmp_seq=5 ttl=64 time=0.597 ms - ---- 192.168.0.2 ping statistics --- -5 packets transmitted, 5 received, 0% packet loss, time 4086ms -rtt min/avg/max/mdev = 0.575/0.612/0.682/0.047 ms -``` - -```none -vyos@vyos:~$ show ip bgp summary - -IPv4 Unicast Summary: -BGP router identifier 192.168.0.1, local AS number 64496 vrf-id 0 -BGP table version 4 -RIB entries 5, using 800 bytes of memory -Peers 2, using 41 KiB of memory -Peer groups 1, using 64 bytes of memory - -Neighbor V AS MsgRcvd MsgSent TblVer InQ OutQ Up/Down State/PfxRcd -eth1 4 64499 13 13 0 0 0 00:05:33 2 -eth2 4 64499 13 14 0 0 0 00:05:29 2 - -Total number of neighbors 2 -``` - -- Router B: - -```none -vyos@vyos:~$ show interfaces -Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down -Interface IP Address S/L Description ---------- ---------- --- ----------- -eth0 198.51.100.33/24 u/u -eth1 - u/u -eth2 - u/u -lo 127.0.0.1/8 u/u - 192.168.0.2/32 - ::1/128 -``` - -```none -vyos@vyos:~$ show ip route -Codes: K - kernel route, C - connected, S - static, R - RIP, - O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, - T - Table, v - VNC, V - VNC-Direct, A - Babel, D - SHARP, - F - PBR, f - OpenFabric, - > - selected route, * - FIB route - -S>* 0.0.0.0/0 [210/0] via 198.51.100.33, eth0, 00:44:08 -C>* 198.51.100.0/24 is directly connected, eth0, 00:44:09 -B>* 192.168.0.1/32 [20/0] via fe80::a00:27ff:fe2d:205d, eth1, 00:06:18 - * via fe80::a00:27ff:fe93:e142, eth2, 00:06:18 -C>* 192.168.0.2/32 is directly connected, lo, 00:44:11 -``` - -```none -vyos@vyos:~$ ping 192.168.0.1 -PING 192.168.0.1 (192.168.0.1) 56(84) bytes of data. -64 bytes from 192.168.0.1: icmp_seq=1 ttl=64 time=0.427 ms -64 bytes from 192.168.0.1: icmp_seq=2 ttl=64 time=0.471 ms -64 bytes from 192.168.0.1: icmp_seq=3 ttl=64 time=0.782 ms -64 bytes from 192.168.0.1: icmp_seq=4 ttl=64 time=0.715 ms - ---- 192.168.0.1 ping statistics --- -4 packets transmitted, 4 received, 0% packet loss, time 3051ms -rtt min/avg/max/mdev = 0.427/0.598/0.782/0.155 ms -``` - -```none -vyos@vyos:~$ show ip bgp summary -IPv4 Unicast Summary: -BGP router identifier 192.168.0.2, local AS number 64499 vrf-id 0 -BGP table version 4 -RIB entries 5, using 800 bytes of memory -Peers 2, using 41 KiB of memory -Peer groups 1, using 64 bytes of memory - -Neighbor V AS MsgRcvd MsgSent TblVer InQ OutQ Up/Down State/PfxRcd -eth1 4 64496 14 14 0 0 0 00:06:40 2 -eth2 4 64496 14 14 0 0 0 00:06:37 2 - -Total number of neighbors 2 -``` diff --git a/docs/configexamples/md-dmvpn-dualhub-dualcloud.md b/docs/configexamples/md-dmvpn-dualhub-dualcloud.md deleted file mode 100644 index 20c1a064..00000000 --- a/docs/configexamples/md-dmvpn-dualhub-dualcloud.md +++ /dev/null @@ -1,552 +0,0 @@ ---- -lastproofread: '2024-02-21' ---- - -(examples-dmvpn-dualhub-dualcloud)= - -# DMVPN Dual HUB Dual Cloud - -This document is to describe a basic setup to build DMVPN network with two Hubs and two clouds using DMVPN Phase3. -OSPF is used as routing protocol inside DMVPN. - -In this example we use VyOS 1.5 as HUBs and Spokes (HUB-1, HUB-2, SPOKE-2, SPOKE-3) and Cisco IOSv 15.5(3)M (SPOKE-1) -as a Spoke. - -## Network Topology - -```{image} /_static/images/dual-hub-DMVPN.webp -:align: center -:alt: DMVPN Network Topology -:width: 80% -``` - - -## Configurations - -### Underlay configuration - -Networks 192.168.X.0/24 are used as LANs for every spoke. - -HUB-1 - -```none -set interfaces ethernet eth0 address '10.0.0.2/30' -set protocols static route 0.0.0.0/0 next-hop 10.0.0.1 -``` - -HUB-2 - -```none -set interfaces ethernet eth0 address '10.0.1.2/30' -set protocols static route 0.0.0.0/0 next-hop 10.0.1.1 -``` - -Spoke-1 - -```none -interface GigabitEthernet0/0 - ip address 10.0.11.2 255.255.255.252 - duplex auto - speed auto - media-type rj45 -! -interface GigabitEthernet0/1 - ip address 192.168.11.1 255.255.255.0 - ip ospf 1 area 0 - duplex auto - speed auto - media-type rj45 -! -ip route 0.0.0.0 0.0.0.0 10.0.11.1 -``` - -Spoke-2 - -```none -set interfaces ethernet eth0 address '10.0.12.2/30' -set interfaces ethernet eth1 address '192.168.12.1/24' -set protocols static route 0.0.0.0/0 next-hop 10.0.12.1 -``` - -Spoke-3 - -```none -set interfaces ethernet eth0 address '10.0.13.2/30' -set interfaces ethernet eth1 address '192.168.13.1/24' -set protocols static route 0.0.0.0/0 next-hop 10.0.13.1 -``` - - -### NHRP configuration - -The next step is to configure the NHRP protocol. In a Dual cloud network, every HUB has to be configured with one GRE -multipoint tunnel interface and every spoke has to be configured with two tunnel interfaces, one tunnel to each hub. -In this example tunnel networks are 10.100.100.0/24 for the first cloud and 10.100.101.0/24 for the second cloud. -But VyOS uses FRR for NHRP, that is why the tunnel address mask must be /32. - -HUB-1 - -```none -set interfaces tunnel tun100 address '10.100.100.1/32' -set interfaces tunnel tun100 enable-multicast -set interfaces tunnel tun100 encapsulation 'gre' -set interfaces tunnel tun100 ip adjust-mss '1360' -set interfaces tunnel tun100 mtu '1436' -set interfaces tunnel tun100 parameters ip key '42' -set interfaces tunnel tun100 source-interface 'eth0' -set protocols nhrp tunnel tun100 authentication 'vyos' -set protocols nhrp tunnel tun100 holdtime '300' -set protocols nhrp tunnel tun100 multicast 'dynamic' -set protocols nhrp tunnel tun100 network-id '1' -set protocols nhrp tunnel tun100 redirect -set protocols nhrp tunnel tun100 registration-no-unique -``` - -HUB-2 - -```none -set interfaces tunnel tun101 address '10.100.101.1/32' -set interfaces tunnel tun101 enable-multicast -set interfaces tunnel tun101 encapsulation 'gre' -set interfaces tunnel tun101 ip adjust-mss '1360' -set interfaces tunnel tun101 mtu '1436' -set interfaces tunnel tun101 parameters ip key '43' -set interfaces tunnel tun101 source-interface 'eth0' -set protocols nhrp tunnel tun101 authentication 'vyos' -set protocols nhrp tunnel tun101 holdtime '300' -set protocols nhrp tunnel tun101 multicast 'dynamic' -set protocols nhrp tunnel tun101 network-id '2' -set protocols nhrp tunnel tun101 redirect -set protocols nhrp tunnel tun101 registration-no-unique -``` - -Spoke-1 - -```none -interface Tunnel100 - ip address 10.100.100.11 255.255.255.0 - no ip redirects - ip mtu 1436 - ip nhrp authentication vyos - ip nhrp map multicast 10.0.0.2 - ip nhrp network-id 1 - ip nhrp holdtime 300 - ip nhrp nhs 10.100.100.1 nbma 10.0.0.2 - ip nhrp shortcut - ip tcp adjust-mss 1360 - tunnel source GigabitEthernet0/0 - tunnel mode gre multipoint - tunnel key 42 -! -interface Tunnel101 - ip address 10.100.101.11 255.255.255.0 - no ip redirects - ip mtu 1436 - ip nhrp authentication vyos - ip nhrp map multicast 10.0.1.2 - ip nhrp network-id 2 - ip nhrp holdtime 300 - ip nhrp nhs 10.100.101.1 nbma 10.0.1.2 - ip nhrp shortcut - ip tcp adjust-mss 1360 - tunnel source GigabitEthernet0/0 - tunnel mode gre multipoint - tunnel key 43 -``` - -Spoke-2 - -```none -set interfaces tunnel tun100 address '10.100.100.12/32' -set interfaces tunnel tun100 enable-multicast -set interfaces tunnel tun100 encapsulation 'gre' -set interfaces tunnel tun100 ip adjust-mss '1360' -set interfaces tunnel tun100 mtu '1436' -set interfaces tunnel tun100 parameters ip key '42' -set interfaces tunnel tun100 source-interface 'eth0' -set interfaces tunnel tun101 address '10.100.101.12/32' -set interfaces tunnel tun101 enable-multicast -set interfaces tunnel tun101 encapsulation 'gre' -set interfaces tunnel tun101 ip adjust-mss '1360' -set interfaces tunnel tun101 mtu '1436' -set interfaces tunnel tun101 parameters ip key '43' -set interfaces tunnel tun101 source-interface 'eth0' -set protocols nhrp tunnel tun100 authentication 'vyos' -set protocols nhrp tunnel tun100 holdtime '300' -set protocols nhrp tunnel tun100 multicast '10.0.0.2' -set protocols nhrp tunnel tun100 network-id '1' -set protocols nhrp tunnel tun100 nhs tunnel-ip dynamic nbma '10.0.0.2' -set protocols nhrp tunnel tun100 registration-no-unique -set protocols nhrp tunnel tun100 shortcut -set protocols nhrp tunnel tun101 authentication 'vyos' -set protocols nhrp tunnel tun101 holdtime '300' -set protocols nhrp tunnel tun101 multicast '10.0.1.2' -set protocols nhrp tunnel tun101 network-id '2' -set protocols nhrp tunnel tun101 nhs tunnel-ip dynamic nbma '10.0.1.2' -set protocols nhrp tunnel tun101 registration-no-unique -set protocols nhrp tunnel tun101 shortcut -``` - -Spoke-3 - -```none -set protocols nhrp tunnel tun100 authentication 'vyos' -set protocols nhrp tunnel tun100 holdtime '300' -set protocols nhrp tunnel tun100 multicast '10.0.0.2' -set protocols nhrp tunnel tun100 network-id '1' -set protocols nhrp tunnel tun100 nhs tunnel-ip dynamic nbma '10.0.0.2' -set protocols nhrp tunnel tun100 registration-no-unique -set protocols nhrp tunnel tun100 shortcut -set protocols nhrp tunnel tun101 authentication 'vyos' -set protocols nhrp tunnel tun101 holdtime '300' -set protocols nhrp tunnel tun101 multicast '10.0.1.2' -set protocols nhrp tunnel tun101 network-id '2' -set protocols nhrp tunnel tun101 nhs tunnel-ip dynamic nbma '10.0.1.2' -set protocols nhrp tunnel tun101 registration-no-unique -set protocols nhrp tunnel tun101 shortcut -``` - - -### Overlay configuration - -The last step is to configure the routing protocol. In this scenario, OSPF was chosen as the dynamic routing protocol. -But you can use iBGP or eBGP. To form fast convergence it is possible to use BFD protocol. - -HUB-1 - -```none -set protocols ospf interface tun100 area '0' -set protocols ospf interface tun100 network 'point-to-multipoint' -set protocols ospf interface tun100 passive disable -set protocols ospf passive-interface 'default' -``` - -HUB-2 - -```none -set protocols ospf interface tun101 area '0' -set protocols ospf interface tun101 network 'point-to-multipoint' -set protocols ospf interface tun101 passive disable -set protocols ospf passive-interface 'default' -``` - -Spoke-1 - -```none -interface Tunnel100 - ip ospf network point-to-multipoint - ip ospf dead-interval 40 - ip ospf hello-interval 10 - ip ospf 1 area 0 -! -interface Tunnel101 - ip ospf network point-to-multipoint - ip ospf dead-interval 40 - ip ospf hello-interval 10 - ip ospf 1 area 0 -! -router ospf 1 - passive-interface default - no passive-interface Tunnel100 - no passive-interface Tunnel101 -``` - -Spoke-2 - -```none -set protocols ospf interface eth1 area '0' -set protocols ospf interface tun100 area '0' -set protocols ospf interface tun100 network 'point-to-multipoint' -set protocols ospf interface tun100 passive disable -set protocols ospf interface tun101 area '0' -set protocols ospf interface tun101 network 'point-to-multipoint' -set protocols ospf interface tun101 passive disable -set protocols ospf passive-interface 'default' -``` - -Spoke-3 - -```none -set protocols ospf interface eth1 area '0' -set protocols ospf interface tun100 area '0' -set protocols ospf interface tun100 network 'point-to-multipoint' -set protocols ospf interface tun100 passive disable -set protocols ospf interface tun101 area '0' -set protocols ospf interface tun101 network 'point-to-multipoint' -set protocols ospf interface tun101 passive disable -set protocols ospf passive-interface 'default' -``` - - -### Security configuration - -Tunnels can be encrypted by IPSEC for security. - -HUB-1 - -```{eval-rst} - .. code-block:: none - - set vpn ipsec esp-group ESP-HUB lifetime '1800' - set vpn ipsec esp-group ESP-HUB mode 'transport' - set vpn ipsec esp-group ESP-HUB pfs 'disable' - set vpn ipsec esp-group ESP-HUB proposal 1 encryption 'aes256' - set vpn ipsec esp-group ESP-HUB proposal 1 hash 'sha1' - set vpn ipsec ike-group IKE-HUB key-exchange 'ikev1' - set vpn ipsec ike-group IKE-HUB lifetime '3600' - set vpn ipsec ike-group IKE-HUB proposal 1 dh-group '2' - set vpn ipsec ike-group IKE-HUB proposal 1 encryption 'aes256' - set vpn ipsec ike-group IKE-HUB proposal 1 hash 'sha1' - set vpn ipsec interface 'eth0' - set vpn ipsec profile NHRPVPN authentication mode 'pre-shared-secret' - set vpn ipsec profile NHRPVPN authentication pre-shared-secret 'secret' - set vpn ipsec profile NHRPVPN bind tunnel 'tun100' - set vpn ipsec profile NHRPVPN esp-group 'ESP-HUB' - set vpn ipsec profile NHRPVPN ike-group 'IKE-HUB' -``` - -HUB-2 - -```{eval-rst} - .. code-block:: none - - set vpn ipsec esp-group ESP-HUB lifetime '1800' - set vpn ipsec esp-group ESP-HUB mode 'transport' - set vpn ipsec esp-group ESP-HUB pfs 'disable' - set vpn ipsec esp-group ESP-HUB proposal 1 encryption 'aes256' - set vpn ipsec esp-group ESP-HUB proposal 1 hash 'sha1' - set vpn ipsec ike-group IKE-HUB key-exchange 'ikev1' - set vpn ipsec ike-group IKE-HUB lifetime '3600' - set vpn ipsec ike-group IKE-HUB proposal 1 dh-group '2' - set vpn ipsec ike-group IKE-HUB proposal 1 encryption 'aes256' - set vpn ipsec ike-group IKE-HUB proposal 1 hash 'sha1' - set vpn ipsec interface 'eth0' - set vpn ipsec profile NHRPVPN authentication mode 'pre-shared-secret' - set vpn ipsec profile NHRPVPN authentication pre-shared-secret 'secret' - set vpn ipsec profile NHRPVPN bind tunnel 'tun101' - set vpn ipsec profile NHRPVPN esp-group 'ESP-HUB' - set vpn ipsec profile NHRPVPN ike-group 'IKE-HUB' -``` - -VyOS Spokes have the same configuration - -```{eval-rst} - .. code-block:: none - - set vpn ipsec esp-group ESP-HUB lifetime '1800' - set vpn ipsec esp-group ESP-HUB mode 'transport' - set vpn ipsec esp-group ESP-HUB pfs 'disable' - set vpn ipsec esp-group ESP-HUB proposal 1 encryption 'aes256' - set vpn ipsec esp-group ESP-HUB proposal 1 hash 'sha1' - set vpn ipsec ike-group IKE-HUB key-exchange 'ikev1' - set vpn ipsec ike-group IKE-HUB lifetime '3600' - set vpn ipsec ike-group IKE-HUB proposal 1 dh-group '2' - set vpn ipsec ike-group IKE-HUB proposal 1 encryption 'aes256' - set vpn ipsec ike-group IKE-HUB proposal 1 hash 'sha1' - set vpn ipsec interface 'eth0' - set vpn ipsec profile NHRPVPN authentication mode 'pre-shared-secret' - set vpn ipsec profile NHRPVPN authentication pre-shared-secret 'secret' - set vpn ipsec profile NHRPVPN bind tunnel 'tun100' - set vpn ipsec profile NHRPVPN bind tunnel 'tun101' - set vpn ipsec profile NHRPVPN esp-group 'ESP-HUB' - set vpn ipsec profile NHRPVPN ike-group 'IKE-HUB' -``` - -SPOKE-1 - -```{eval-rst} - .. code-block:: none - - crypto isakmp policy 1 - encr aes 256 - authentication pre-share - group 2 - lifetime 3600 - crypto isakmp key secret address 0.0.0.0 - ! - ! - crypto ipsec transform-set ESP_TRANSFORMSET esp-aes 256 esp-sha-hmac - mode transport - ! - ! - crypto ipsec profile gre_protection - set security-association lifetime seconds 1800 - set transform-set ESP_TRANSFORMSET - ! - interface Tunnel100 - tunnel protection ipsec profile gre_protection shared - ! - interface Tunnel101 - tunnel protection ipsec profile gre_protection shared -``` - - -## Monitoring - -All spokes created IPSec tunnels to Hubs, are registered on Hubs using NHRP protocol and formed adjacency in OSPF. - -```none -vyos@HUB-1:~$ show vpn ipsec sa -Connection State Uptime Bytes In/Out Packets In/Out Remote address Remote ID Proposal --------------------------- ------- -------- -------------- ---------------- ---------------- ----------- ------------------------ -dmvpn-NHRPVPN-tun100-child up 6m1s 4K/5K 51/56 10.0.13.2 10.0.13.2 AES_CBC_256/HMAC_SHA1_96 -dmvpn-NHRPVPN-tun100-child up 6m36s 4K/6K 56/65 10.0.12.2 10.0.12.2 AES_CBC_256/HMAC_SHA1_96 -dmvpn-NHRPVPN-tun100-child up 8m49s 6K/6K 73/77 10.0.11.2 10.0.11.2 AES_CBC_256/HMAC_SHA1_96 - -vyos@HUB-1:~$ show ip nhrp cache -Iface Type Protocol NBMA Claimed NBMA Flags Identity -tun100 dynamic 10.100.100.12 10.0.12.2 10.0.12.2 T 10.0.12.2 -tun100 dynamic 10.100.100.13 10.0.13.2 10.0.13.2 T 10.0.13.2 -tun100 dynamic 10.100.100.11 10.0.11.2 10.0.11.2 T 10.0.11.2 -tun100 local 10.100.100.1 10.0.0.2 10.0.0.2 - - -vyos@HUB-1:~$ show ip ospf neighbor - -Neighbor ID Pri State Up Time Dead Time Address Interface RXmtL RqstL DBsmL -192.168.11.1 1 Full/DROther 17m01s 36.201s 10.100.100.11 tun100:10.100.100.1 0 0 0 -192.168.12.1 1 Full/DROther 9m42s 37.443s 10.100.100.12 tun100:10.100.100.1 0 0 0 -192.168.13.1 1 Full/DROther 9m15s 35.053s 10.100.100.13 tun100:10.100.100.1 0 0 0 -``` - -First, we see that LANs are accessible through hubs using OSPF routes. - -```none -SPOKE-1#show ip route -Codes: L - local, C - connected, S - static, R - RIP, M - mobile, B - BGP - D - EIGRP, EX - EIGRP external, O - OSPF, IA - OSPF inter area - N1 - OSPF NSSA external type 1, N2 - OSPF NSSA external type 2 - E1 - OSPF external type 1, E2 - OSPF external type 2 - i - IS-IS, su - IS-IS summary, L1 - IS-IS level-1, L2 - IS-IS level-2 - ia - IS-IS inter area, * - candidate default, U - per-user static route - o - ODR, P - periodic downloaded static route, H - NHRP, l - LISP - a - application route - + - replicated route, % - next hop override, p - overrides from PfR - -Gateway of last resort is 10.0.11.1 to network 0.0.0.0 -..... - 192.168.11.0/24 is variably subnetted, 2 subnets, 2 masks -C 192.168.11.0/24 is directly connected, GigabitEthernet0/1 -L 192.168.11.1/32 is directly connected, GigabitEthernet0/1 -O 192.168.12.0/24 [110/1002] via 10.100.101.1, 00:14:36, Tunnel101 - [110/1002] via 10.100.100.1, 00:16:13, Tunnel100 -O 192.168.13.0/24 [110/1002] via 10.100.101.1, 00:14:36, Tunnel101 - [110/1002] via 10.100.100.1, 00:15:45, Tunnel100 - - -vyos@SPOKE-2:~$ show ip route -Codes: K - kernel route, C - connected, L - local, S - static, - R - RIP, O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, - T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, - f - OpenFabric, t - Table-Direct, - > - selected route, * - FIB route, q - queued, r - rejected, b - backup - t - trapped, o - offload failure - -...... -O>* 192.168.11.0/24 [110/3] via 10.100.100.1, tun100 onlink, weight 1, 00:12:36 - * via 10.100.101.1, tun101 onlink, weight 1, 00:12:36 -O 192.168.12.0/24 [110/1] is directly connected, eth1, weight 1, 01:24:40 -C>* 192.168.12.0/24 is directly connected, eth1, weight 1, 01:24:43 -L>* 192.168.12.1/32 is directly connected, eth1, weight 1, 01:24:43 -O>* 192.168.13.0/24 [110/3] via 10.100.100.1, tun100 onlink, weight 1, 00:12:36 - * via 10.100.101.1, tun101 onlink, weight 1, 00:12:36 -``` - -After initiating traffic between SPOKES sites, Phase 3 of DMVPN will work. -For instance, traceroute was generated from PC-SPOKE-2 to PC-SPOKE-1 - -```none -PC-SPOKE-2 : 192.168.12.2 255.255.255.0 gateway 192.168.12.1 - -PC-SPOKE-2> trace 192.168.11.2 -trace to 192.168.11.2, 8 hops max, press Ctrl+C to stop - 1 192.168.12.1 0.558 ms 0.378 ms 0.561 ms - 2 10.100.101.1 1.768 ms 1.158 ms 1.744 ms - 3 10.100.101.11 7.196 ms 4.971 ms 4.793 ms - 4 *192.168.11.2 7.747 ms (ICMP type:3, code:3, Destination port unreachable) - -PC-SPOKE-2> trace 192.168.11.2 -trace to 192.168.11.2, 8 hops max, press Ctrl+C to stop - 1 192.168.12.1 0.562 ms 0.396 ms 0.364 ms - 2 10.100.100.11 4.401 ms 4.399 ms 4.174 ms - 3 *192.168.11.2 3.241 ms (ICMP type:3, code:3, Destination port unreachable) -``` - -First trace goes via HUB but the second goes directly from SPOKE-1 to SPOKE-2. -Now routing tables are changed. LAN networks 192.168.12.0/24 and 192.168.11.0/24 available directly via SPOKES. - -```none -vyos@SPOKE-2:~$ show ip route -Codes: K - kernel route, C - connected, L - local, S - static, - R - RIP, O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, - T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, - f - OpenFabric, t - Table-Direct, - > - selected route, * - FIB route, q - queued, r - rejected, b - backup - t - trapped, o - offload failure - -N>* 192.168.11.0/24 [10/0] via 10.100.100.11, tun100 onlink, weight 1, 00:00:14 -O 192.168.11.0/24 [110/3] via 10.100.100.1, tun100 onlink, weight 1, 00:00:54 - via 10.100.101.1, tun101 onlink, weight 1, 00:00:54 - - -SPOKE-1# show ip route next-hop-override -Codes: L - local, C - connected, S - static, R - RIP, M - mobile, B - BGP - D - EIGRP, EX - EIGRP external, O - OSPF, IA - OSPF inter area - N1 - OSPF NSSA external type 1, N2 - OSPF NSSA external type 2 - E1 - OSPF external type 1, E2 - OSPF external type 2 - i - IS-IS, su - IS-IS summary, L1 - IS-IS level-1, L2 - IS-IS level-2 - ia - IS-IS inter area, * - candidate default, U - per-user static route - o - ODR, P - periodic downloaded static route, H - NHRP, l - LISP - a - application route - + - replicated route, % - next hop override, p - overrides from PfR - -Gateway of last resort is 10.0.11.1 to network 0.0.0.0 - -O % 192.168.12.0/24 [110/1002] via 10.100.101.1, 00:24:09, Tunnel101 - [110/1002] via 10.100.100.1, 00:25:46, Tunnel100 - [NHO][110/1] via 10.100.100.12, 00:00:03, Tunnel100 -``` - -NHRP shows shortcuts on Spokes - -```none -vyos@SPOKE-2:~$ show ip nhrp shortcut -Type Prefix Via Identity -dynamic 192.168.11.0/24 10.100.100.11 10.0.11.2 - -SPOKE-1# show ip nhrp shortcut -10.100.100.12/32 via 10.100.100.12 - Tunnel100 created 00:09:59, expire 00:02:21 - Type: dynamic, Flags: router nhop rib nho - NBMA address: 10.0.12.2 -192.168.12.0/24 via 10.100.100.12 - Tunnel100 created 00:02:38, expire 00:02:21 - Type: dynamic, Flags: router rib nho - NBMA address: 10.0.12.2 -``` - -A new Spoke to Spoke IPSec tunnel is created - -```none -SPOKE-1#show crypto isakmp sa -IPv4 Crypto ISAKMP SA -dst src state conn-id status -10.0.0.2 10.0.11.2 QM_IDLE 1002 ACTIVE -10.0.12.2 10.0.11.2 QM_IDLE 1004 ACTIVE -10.0.1.2 10.0.11.2 QM_IDLE 1003 ACTIVE - -vyos@SPOKE-2:~$ show vpn ipsec sa -Connection State Uptime Bytes In/Out Packets In/Out Remote address Remote ID Proposal --------------------------- ------- -------- -------------- ---------------- ---------------- ----------- ------------------------ -dmvpn-NHRPVPN-tun100-child up 7m26s 4K/4K 57/53 10.0.0.2 10.0.0.2 AES_CBC_256/HMAC_SHA1_96 -dmvpn-NHRPVPN-tun100-child up 11m48s 316B/1K 3/15 10.0.11.2 10.0.11.2 AES_CBC_256/HMAC_SHA1_96 -dmvpn-NHRPVPN-tun101-child up 5m58s 5K/4K 62/51 10.0.1.2 10.0.1.2 AES_CBC_256/HMAC_SHA1_96 -``` - - -## Summary - -If one of the Hubs loses connectivity to the Internet, the other Hub will be available and take the main role. -This is a simple example where only one internet connection is used. But in the real world, there can be two -connections to the Internet. In this case, there is a recommendation to build each tunnel via each Internet connection, -choose the main cloud, and manipulate traffic via a routing protocol. It allows the creation failover on link-level -connections too. diff --git a/docs/configexamples/md-firewall.md b/docs/configexamples/md-firewall.md deleted file mode 100644 index 5d170511..00000000 --- a/docs/configexamples/md-firewall.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -lastproofread: '2024-09-11' ---- - -# Firewall Examples - -This section contains examples of firewall configurations for various -deployments. - -```{toctree} -:maxdepth: 2 - -fwall-and-vrf -fwall-and-bridge -zone-policy -``` diff --git a/docs/configexamples/md-fwall-and-bridge.md b/docs/configexamples/md-fwall-and-bridge.md deleted file mode 100644 index d6602592..00000000 --- a/docs/configexamples/md-fwall-and-bridge.md +++ /dev/null @@ -1,490 +0,0 @@ ---- -lastproofread: '2024-09-11' ---- - -# Bridge and firewall example - -## Scenario and requirements - -This example shows how to configure a VyOS router with bridge interfaces and -firewall rules. - -Three non VLAN-aware bridges are going to be configured, and each one has its -own requirements. - -- Bridge br0: - : - Isolated layer 2 bridge. - - Accept only IPv6 communication within the bridge. -- Bridge br1: - : - Drop all DHCP discover packets. - - Accept all ARP packets. - - Within the bridge, accept only new IPv4 connections from host 10.1.1.102 - - Drop all other IPv4 connections. - - Drop all IPv6 connections. - - Accept access to router itself. - - Allow connections to internet - - Drop connections to other LANs. -- Bridge br2: - : - Accept all DHCP discover packets. - - Accept only DHCP offers from valid server and|or trusted bridge port. - - Accept all ARP packets. - - Accept all IPv4 connections. - - Drop all IPv6 connections. - - Deny access to the router. - - Allow connections to internet. - - Allow connections to bridge br1. - -## Configuration - -### Bridges and interfaces configuration - -First, we need to configure the interfaces and bridges: - -```none -# Brige br0 -set interfaces bridge br0 description 'Isolated L2 bridge' -set interfaces bridge br0 member interface eth1 -set interfaces bridge br0 member interface eth2 -set interfaces ethernet eth1 description 'br0' -set interfaces ethernet eth2 description 'br0' - -# Bridge br1: -set interfaces bridge br1 address '10.1.1.1/24' -set interfaces bridge br1 description 'L3 bridge br1' -set interfaces bridge br1 member interface eth3 -set interfaces bridge br1 member interface eth4 -set interfaces ethernet eth3 description 'br1' -set interfaces ethernet eth4 description 'br1' - -# Bridge br2: -set interfaces bridge br2 address '10.2.2.1/24' -set interfaces bridge br2 description 'L3 bridge br2' -set interfaces bridge br2 member interface eth5 -set interfaces bridge br2 member interface eth6 -set interfaces bridge br2 member interface eth7 -set interfaces ethernet eth5 description 'br2 - Host' -set interfaces ethernet eth6 description 'br2 - Trusted DHCP Server' -set interfaces ethernet eth7 description 'br2' -``` - - -### Bridge firewall configuration - -In this section, we are going to configure the firewall rules that will be used -in bridge firewall, and will control the traffic within each bridge. - -We are going to use custom firewall rulesets, one for each bridge that will -be used in `prerouting`, and one for each bridge that will be used in the -`forward` chain. - -Also, we are going to use firewall interface groups in order to simplify the -firewall configuration. - -So first, let's create the required firewall interface groups: - -```none -# Bridge br0 interface-group: -set firewall group interface-group br0-ifaces interface 'br0' -set firewall group interface-group br0-ifaces interface 'eth1' -set firewall group interface-group br0-ifaces interface 'eth2' - -# Bridge br1 interface-group: -set firewall group interface-group br1-ifaces interface 'br1' -set firewall group interface-group br1-ifaces interface 'eth3' -set firewall group interface-group br1-ifaces interface 'eth4' - -# Bridge br2 interface-group: -set firewall group interface-group br2-ifaces interface 'br2' -set firewall group interface-group br2-ifaces interface 'eth5' -set firewall group interface-group br2-ifaces interface 'eth6' -set firewall group interface-group br2-ifaces interface 'eth7' -``` - -As said before, we are going to create custom firewall rulesets for each -bridge, that will be used in the `prerouting` chain, in order to drop as much -unwanted traffic as early as possible. So, custom rulesets used in -`prerouting` chain are going to be `br0-pre`, `br1-pre`, and `br2-pre`: - -```none -# Prerouting - Catch all traffic for br0 -set firewall bridge prerouting filter rule 10 action 'jump' -set firewall bridge prerouting filter rule 10 description 'br0 traffic' -set firewall bridge prerouting filter rule 10 inbound-interface group 'br0-ifaces' -set firewall bridge prerouting filter rule 10 jump-target 'br0-pre' - -# Prerouting - Catch all traffic for br1 -set firewall bridge prerouting filter rule 20 action 'jump' -set firewall bridge prerouting filter rule 20 description 'br1 traffic' -set firewall bridge prerouting filter rule 20 inbound-interface group 'br1-ifaces' -set firewall bridge prerouting filter rule 20 jump-target 'br1-pre' - -# Prerouting - Catch all traffic for br2 -set firewall bridge prerouting filter rule 30 action 'jump' -set firewall bridge prerouting filter rule 30 description 'br2 traffic' -set firewall bridge prerouting filter rule 30 inbound-interface group 'br2-ifaces' -set firewall bridge prerouting filter rule 30 jump-target 'br2-pre' -``` - -And then create the custom rulesets: - -```none -### br0 - br0-pre - # Requirements: accept only IPv6 communication within the bridge -set firewall bridge name br0-pre rule 10 description 'Accept IPv6 traffic' -set firewall bridge name br0-pre rule 10 action 'accept' -set firewall bridge name br0-pre rule 10 ethernet-type 'ipv6' - # And drop everything else -set firewall bridge name br0-pre default-action 'drop' - -### br1 - br1-pre - # Requirements: drop all DHCP discover packets -set firewall bridge name br1-pre rule 10 description 'Drop DHCP discover' -set firewall bridge name br1-pre rule 10 action 'drop' -set firewall bridge name br1-pre rule 10 protocol 'udp' -set firewall bridge name br1-pre rule 10 source port '68' -set firewall bridge name br1-pre rule 10 destination port '67' -set firewall bridge name br1-pre rule 10 destination mac-address 'ff:ff:ff:ff:ff:ff' -set firewall bridge name br1-pre rule 10 log - # Requirement: drop all IPv6 connections -set firewall bridge name br1-pre rule 20 description 'Drop IPv6 traffic' -set firewall bridge name br1-pre rule 20 action 'drop' -set firewall bridge name br1-pre rule 20 ethernet-type 'ipv6' - # Accept everything else so it can be parsed later -set firewall bridge name br1-pre default-action 'accept' - -### br2 - br2-pre - # Requirements: drop all IPv6 connections -set firewall bridge name br2-pre rule 10 description 'Drop IPv6 traffic' -set firewall bridge name br2-pre rule 10 action 'drop' -set firewall bridge name br2-pre rule 10 ethernet-type 'ipv6' - # Accept everything else so it can be parsed later -set firewall bridge name br2-pre default-action 'accept' -``` - -Now, in the `forward` chain, we are going to define state policies, and -custom rulesets for each bridge that would be used in the `forward` chain. -These rulesets are `br0-fwd`, `br1-fwd`, and `br2-fwd`: - -```none -# Forward - State policies if not defined globally -set firewall bridge forward filter rule 5 action 'accept' -set firewall bridge forward filter rule 5 state 'established' -set firewall bridge forward filter rule 5 state 'related' -set firewall bridge forward filter rule 10 action 'drop' -set firewall bridge forward filter rule 10 state 'invalid' - -# Forward - Catch all traffic for br0 -set firewall bridge forward filter rule 110 description 'br0 traffic' -set firewall bridge forward filter rule 110 action 'jump' -set firewall bridge forward filter rule 110 inbound-interface group 'br0-ifaces' -set firewall bridge forward filter rule 110 jump-target 'br0-fwd' - -# Forward - Catch all traffic for br1 -set firewall bridge forward filter rule 120 description 'br1 traffic' -set firewall bridge forward filter rule 120 action 'jump' -set firewall bridge forward filter rule 120 inbound-interface group 'br1-ifaces' -set firewall bridge forward filter rule 120 jump-target 'br1-fwd' - -# Forward - Catch all traffic for br2 -set firewall bridge forward filter rule 130 description 'br2 traffic' -set firewall bridge forward filter rule 130 action 'jump' -set firewall bridge forward filter rule 130 inbound-interface group 'br2-ifaces' -set firewall bridge forward filter rule 130 jump-target 'br2-fwd' - -# Forward - Default action drop: -set firewall bridge forward filter default-action 'drop' -``` - -And the content of the custom rulesets: - -```none -### br0 - br0-fwd - # Accept everything that wasn't dropped in prerouting -set firewall bridge name br0-fwd default-action 'accept' - -### br1 - br1-fwd - # Requirement: Accept all ARP packets -set firewall bridge name br1-fwd rule 10 description 'Accept ARP' -set firewall bridge name br1-fwd rule 10 action 'accept' -set firewall bridge name br1-fwd rule 10 ethernet-type 'arp' - # Requirement: Accept only new IPv4 connections from host 10.1.1.102 -set firewall bridge name br1-fwd rule 20 description 'Accept ipv4 from host' -set firewall bridge name br1-fwd rule 20 action 'accept' -set firewall bridge name br1-fwd rule 20 source address '10.1.1.102' -set firewall bridge name br1-fwd rule 20 state 'new' - # Drop everything else within the bridge: -set firewall bridge name br1-fwd default-action 'drop' - -### br2 - br2-fwd - # Requirement: Accept all DHCP discover packets -set firewall bridge name br2-fwd rule 10 description 'Accept DHCP discover' -set firewall bridge name br2-fwd rule 10 action 'accept' -set firewall bridge name br2-fwd rule 10 protocol 'udp' -set firewall bridge name br2-fwd rule 10 source port '68' -set firewall bridge name br2-fwd rule 10 destination port '67' -set firewall bridge name br2-fwd rule 10 destination mac-address 'ff:ff:ff:ff:ff:ff' - # Requirement: Accept only DHCP offers from valid server on port eth6 -set firewall bridge name br2-fwd rule 20 description 'Accept DHCP offers from trusted interface' -set firewall bridge name br2-fwd rule 20 action 'accept' -set firewall bridge name br2-fwd rule 20 protocol 'udp' -set firewall bridge name br2-fwd rule 20 source port '67' -set firewall bridge name br2-fwd rule 20 destination port '68' -set firewall bridge name br2-fwd rule 20 inbound-interface name 'eth6' -set firewall bridge name br2-fwd rule 22 description 'Drop all other DHCP offers' -set firewall bridge name br2-fwd rule 22 action 'drop' -set firewall bridge name br2-fwd rule 22 protocol 'udp' -set firewall bridge name br2-fwd rule 22 source port '67' -set firewall bridge name br2-fwd rule 22 destination port '68' -set firewall bridge name br2-fwd rule 22 log - - # Accept all ARP packets -set firewall bridge name br2-fwd rule 30 description 'Accept ARP' -set firewall bridge name br2-fwd rule 30 action 'accept' -set firewall bridge name br2-fwd rule 30 ethernet-type 'arp' - # Accept all IPv4 connections -set firewall bridge name br2-fwd rule 40 description 'Accept ipv4' -set firewall bridge name br2-fwd rule 40 action 'accept' -set firewall bridge name br2-fwd rule 40 ethernet-type 'ipv4' - # Drop everything else -set firewall bridge name br2-fwd default-action 'drop' -``` - - -### IP firewall configuration - -Since some of the requirements listed above exceed the capabilities of the -bridge firewall, we need to use the IP firewall to implement them. -For bridge br1 and br2, we need to control the traffic that is going to the -router itself, to other local networks, and to the Internet. - -As a reminder, here's a link to the {doc}`firewall documentation -`, where you can find more information about -the packet flow for traffic that comes from bridge layer and should be analized -by the IP firewall. - -Access to the router itself is controlled by the base chain `input`, and -rules to accomplish all the requirements are: - -```none -# First of all, if not using global state policies, we need to define them: -set firewall ipv4 input filter rule 10 state 'established' -set firewall ipv4 input filter rule 10 state 'related' -set firewall ipv4 input filter rule 10 action 'accept' -set firewall ipv4 input filter rule 20 state 'invalid' -set firewall ipv4 input filter rule 20 action 'drop' - -# Input - br1 - Accept access to router itself -set firewall ipv4 input filter rule 110 description "Accept access from br1" -set firewall ipv4 input filter rule 110 action 'accept' -set firewall ipv4 input filter rule 110 inbound-interface group 'br1-ifaces' - -# Input - br2 - Deny access to the router -set firewall ipv4 input filter rule 120 description "Deny access from br2" -set firewall ipv4 input filter rule 120 action 'drop' -set firewall ipv4 input filter rule 120 inbound-interface group 'br2-ifaces' -``` - -And for traffic that is going to other local networks, and to he Internet, we -need to use the base chain `forward`. As in the bridge firewall, we are -going to use custom rulesets for each bridge, that would be used in the -`forward` chain. Those rulesets are `ip-br1-fwd` and `ip-br2-fwd`: - -```none -# First of all, if not using global state policies, we need to define them: -set firewall ipv4 forward filter rule 5 action 'accept' -set firewall ipv4 forward filter rule 5 state 'established' -set firewall ipv4 forward filter rule 5 state 'related' -set firewall ipv4 forward filter rule 10 action 'drop' -set firewall ipv4 forward filter rule 10 state 'invalid' - -# Forward - Catch all traffic for br1 -set firewall ipv4 forward filter rule 110 description 'br1 traffic' -set firewall ipv4 forward filter rule 110 action 'jump' -set firewall ipv4 forward filter rule 110 inbound-interface group 'br1-ifaces' -set firewall ipv4 forward filter rule 110 jump-target 'ip-br1-fwd' - -# Forward - Catch all traffic for br2 -set firewall ipv4 forward filter rule 120 description 'br2 traffic' -set firewall ipv4 forward filter rule 120 action 'jump' -set firewall ipv4 forward filter rule 120 inbound-interface group 'br2-ifaces' -set firewall ipv4 forward filter rule 120 jump-target 'ip-br2-fwd' - -# Forward - Default action drop: -set firewall ipv4 forward filter default-action 'drop' -``` - -And the content of the custom rulesets: - -```none -### br1 - ip-br1-fwd - # Requirement: Allow connections to internet -set firewall ipv4 name ip-br1-fwd rule 10 description 'br1 - allow internet access' -set firewall ipv4 name ip-br1-fwd rule 10 action 'accept' -set firewall ipv4 name ip-br1-fwd rule 10 outbound-interface name 'eth0' - # Requirement: Drop all other connections -set firewall ipv4 name ip-br1-fwd default-action 'drop' - -### br2 - ip-br2-fwd - # Requirement: Allow connections to internet -set firewall ipv4 name ip-br2-fwd rule 10 description 'br2 - allow internet access' -set firewall ipv4 name ip-br2-fwd rule 10 action 'accept' -set firewall ipv4 name ip-br2-fwd rule 10 outbound-interface name 'eth0' - # Requirement: Allow connections to br1 -set firewall ipv4 name ip-br2-fwd rule 20 description 'br2 - allow access to br1' -set firewall ipv4 name ip-br2-fwd rule 20 action 'accept' -set firewall ipv4 name ip-br2-fwd rule 20 outbound-interface group 'br1-ifaces' - # Requirement: Drop all other connections -set firewall ipv4 name ip-br2-fwd default-action 'drop' -``` - - -## Validation - -While testing the configuration, we can check logs in order to ensure that -we are accepting and/or blocking the correct traffic. - -For example, while a host tries to get an IP address from a DHCP server in -br1 all DHCP discover are dropped, and in br2, we can see that DHCP offers from -untrusted servers are dropped: - -```none -vyos@bridge:~$ show log firewall bridge -Sep 17 14:22:35 kernel: [bri-NAM-br2-fwd-22-D]IN=eth7 OUT=eth5 MAC=50:00:00:09:00:00:50:00:00:04:00:00:08:00 SRC=10.2.2.199 DST=10.2.2.92 LEN=322 TOS=0x10 PREC=0x00 TTL=128 ID=0 DF PROTO=UDP SPT=67 DPT=68 LEN=302 -Sep 17 14:28:18 kernel: [bri-NAM-br1-pre-10-D]IN=eth3 OUT= MAC=ff:ff:ff:ff:ff:ff:00:50:79:66:68:0c:08:00 SRC=0.0.0.0 DST=255.255.255.255 LEN=392 TOS=0x10 PREC=0x00 TTL=16 ID=0 PROTO=UDP SPT=68 DPT=67 LEN=372 -Sep 17 14:28:19 kernel: [bri-NAM-br1-pre-10-D]IN=eth3 OUT= MAC=ff:ff:ff:ff:ff:ff:00:50:79:66:68:0c:08:00 SRC=0.0.0.0 DST=255.255.255.255 LEN=392 TOS=0x10 PREC=0x00 TTL=16 ID=0 PROTO=UDP SPT=68 DPT=67 LEN=372 -``` - -And with operational mode commands, we can check rules matchers, actions, and -counters. - -Bridge firewall ruleset: - -```none -vyos@bri:~$ show firewall bridge -Rulesets bridge Information - ---------------------------------- -bridge Firewall "forward filter" - -Rule Action Protocol Packets Bytes Conditions -------- -------- ---------- --------- ------- ----------------------------------------- -5 accept all 19 1916 ct state { established, related } accept -10 drop all 0 0 ct state invalid -110 jump all 2 208 iifname @I_br0-ifaces jump NAME_br0-fwd -120 jump all 10 670 iifname @I_br1-ifaces jump NAME_br1-fwd -130 jump all 12 3086 iifname @I_br2-ifaces jump NAME_br2-fwd -default drop all 0 0 - ---------------------------------- -bridge Firewall "name br0-fwd" - -Rule Action Protocol Packets Bytes -------- -------- ---------- --------- ------- -default accept all 2 208 - ---------------------------------- -bridge Firewall "name br0-pre" - -Rule Action Protocol Packets Bytes Conditions -------- -------- ---------- --------- ------- ---------------------- -10 accept all 18 1872 ether type ip6 accept -default drop all 9 1476 - ---------------------------------- -bridge Firewall "name br1-fwd" - -Rule Action Protocol Packets Bytes Conditions -------- -------- ---------- --------- ------- ---------------------------------------- -10 accept all 5 250 ether type arp accept -20 accept all 3 252 ct state new ip saddr 10.1.1.102 accept -default drop all 2 168 - ---------------------------------- -bridge Firewall "name br1-pre" - -Rule Action Protocol Packets Bytes Conditions -------- -------- ---------- --------- ------- ---------------------------------------------------------------------------------------- -10 drop udp 3 1176 ether daddr ff:ff:ff:ff:ff:ff udp sport 68 udp dport 67 prefix "[bri-NAM-br1-pre-10-D]" -20 drop all 0 0 ether type ip6 -default accept all 58 4430 - ---------------------------------- -bridge Firewall "name br2-fwd" - -Rule Action Protocol Packets Bytes Conditions -------- -------- ---------- --------- ------- --------------------------------------------------------------- -10 accept udp 4 1312 ether daddr ff:ff:ff:ff:ff:ff udp sport 68 udp dport 67 accept -20 accept udp 2 656 udp sport 67 udp dport 68 iifname "eth6" accept -22 drop udp 1 322 udp sport 67 udp dport 68 prefix "[bri-NAM-br2-fwd-22-D]" -30 accept all 2 92 ether type arp accept -40 accept all 3 704 ether type ip accept -default drop all 0 0 - ---------------------------------- -bridge Firewall "name br2-pre" - -Rule Action Protocol Packets Bytes Conditions -------- -------- ---------- --------- ------- -------------- -10 drop all 7 728 ether type ip6 -default accept all 77 7548 - ---------------------------------- -bridge Firewall "prerouting filter" - -Rule Action Protocol Packets Bytes Conditions -------- -------- ---------- --------- ------- ---------------------------------------- -10 jump all 27 3348 iifname @I_br0-ifaces jump NAME_br0-pre -20 jump all 61 5606 iifname @I_br1-ifaces jump NAME_br1-pre -30 jump all 84 8276 iifname @I_br2-ifaces jump NAME_br2-pre -default drop all 0 0 - -vyos@bridge:~$ -``` - -IPv4 firewall ruleset: - -```none -vyos@bridge:~$ show firewall ipv4 -Rulesets ipv4 Information - ---------------------------------- -ipv4 Firewall "forward filter" - -Rule Action Protocol Packets Bytes Conditions -------- -------- ---------- --------- ------- ------------------------------------------- -5 accept all 76 6384 ct state { established, related } accept -10 drop all 0 0 ct state invalid -110 jump all 13 1092 iifname @I_br1-ifaces jump NAME_ip-br1-fwd -120 jump all 3 252 iifname @I_br2-ifaces jump NAME_ip-br2-fwd -default drop all 0 0 - ---------------------------------- -ipv4 Firewall "input filter" - -Rule Action Protocol Packets Bytes Conditions -------- -------- ---------- --------- ------- ----------------------------------------- -10 accept all 0 0 ct state { established, related } accept -20 drop all 0 0 ct state invalid -110 accept all 10 720 iifname @I_br1-ifaces accept -120 drop all 26 2672 iifname @I_br2-ifaces -default accept all 3037 991621 - ---------------------------------- -ipv4 Firewall "name ip-br1-fwd" - -Rule Action Protocol Packets Bytes Conditions -------- -------- ---------- --------- ------- ---------------------- -10 accept all 5 420 oifname "eth0" accept -default drop all 8 672 - ---------------------------------- -ipv4 Firewall "name ip-br2-fwd" - -Rule Action Protocol Packets Bytes Conditions -------- -------- ---------- --------- ------- ----------------------------- -10 accept all 1 84 oifname "eth0" accept -20 accept all 2 168 oifname @I_br1-ifaces accept -default drop all 0 0 - -vyos@bridge:~$ -``` diff --git a/docs/configexamples/md-fwall-and-vrf.md b/docs/configexamples/md-fwall-and-vrf.md deleted file mode 100644 index da9949db..00000000 --- a/docs/configexamples/md-fwall-and-vrf.md +++ /dev/null @@ -1,121 +0,0 @@ -# VRF and firewall example - -## Scenario and requirements - -This example shows how to configure a VyOS router with VRFs and firewall rules. - -Diagram used in this example: - -```{image} /_static/images/firewall-and-vrf-blueprints.webp -:align: center -:alt: Network Topology Diagram -:width: 80% -``` - -As exposed in the diagram, there are four VRFs. These VRFs are `MGMT`, -`WAN`, `LAN` and `PROD`, and their requirements are: - -```{eval-rst} -* VRF MGMT: - * Allow connections to LAN and PROD. - * Deny connections to internet(WAN). - * Allow connections to the router. -* VRF LAN: - * Allow connections to PROD. - * Allow connections to internet(WAN). -* VRF PROD: - * Only accepts connections. -* VRF WAN: - * Allow connection to PROD. -``` - -## Configuration - -First, we need to configure the interfaces and VRFs: - -```none -set interfaces ethernet eth1 address '10.100.100.1/24' -set interfaces ethernet eth1 vrf 'MGMT' -set interfaces ethernet eth2 vif 150 address '10.150.150.1/24' -set interfaces ethernet eth2 vif 150 vrf 'LAN' -set interfaces ethernet eth2 vif 160 address '10.160.160.1/24' -set interfaces ethernet eth2 vif 160 vrf 'LAN' -set interfaces ethernet eth2 vif 3500 address '172.16.20.1/24' -set interfaces ethernet eth2 vif 3500 vrf 'PROD' -set interfaces loopback lo -set interfaces pppoe pppoe0 authentication password 'p4ssw0rd' -set interfaces pppoe pppoe0 authentication username 'vyos' -set interfaces pppoe pppoe0 source-interface 'eth0' -set interfaces pppoe pppoe0 vrf 'WAN' -set vrf bind-to-all -set vrf name LAN protocols static route 0.0.0.0/0 interface pppoe0 vrf 'WAN' -set vrf name LAN protocols static route 10.100.100.0/24 interface eth1 vrf 'MGMT' -set vrf name LAN protocols static route 172.16.20.0/24 interface eth2.3500 vrf 'PROD' -set vrf name LAN table '103' -set vrf name MGMT protocols static route 10.150.150.0/24 interface eth2.150 vrf 'LAN' -set vrf name MGMT protocols static route 10.160.160.0/24 interface eth2.160 vrf 'LAN' -set vrf name MGMT protocols static route 172.16.20.0/24 interface eth2.3500 vrf 'PROD' -set vrf name MGMT table '102' -set vrf name PROD protocols static route 0.0.0.0/0 interface pppoe0 vrf 'WAN' -set vrf name PROD protocols static route 10.100.100.0/24 interface eth1 vrf 'MGMT' -set vrf name PROD protocols static route 10.150.150.0/24 interface eth2.150 vrf 'LAN' -set vrf name PROD protocols static route 10.160.160.0/24 interface eth2.160 vrf 'LAN' -set vrf name PROD table '104' -set vrf name WAN protocols static route 10.150.150.0/24 interface eth2.150 vrf 'LAN' -set vrf name WAN protocols static route 10.160.160.0/24 interface eth2.160 vrf 'LAN' -set vrf name WAN protocols static route 172.16.20.0/24 interface eth2.3500 vrf 'PROD' -set vrf name WAN table '101' -``` - -And before firewall rules are shown, we need to pay attention how to configure -and match interfaces and VRFs. In case where an interface is assigned to a -non-default VRF, if we want to use inbound-interface or outbound-interface in -firewall rules, we need to: - -- For **inbound-interface**: use the interface name with the VRF name, like - `MGMT` or `LAN`. -- For **outbound-interface**: use the interface name, like `eth0`, `vtun0`, - `eth2*` or similar. - -Next, we need to configure the firewall rules. First we will define all rules -for transit traffic between VRFs. - -```none -set firewall ipv4 forward filter default-action 'drop' -set firewall ipv4 forward filter default-log -set firewall ipv4 forward filter rule 10 action 'accept' -set firewall ipv4 forward filter rule 10 description 'MGMT - Allow to LAN and PROD' -set firewall ipv4 forward filter rule 10 inbound-interface name 'MGMT' -set firewall ipv4 forward filter rule 10 outbound-interface name 'eth2*' -set firewall ipv4 forward filter rule 99 action 'drop' -set firewall ipv4 forward filter rule 99 description 'MGMT - Drop all going to mgmt' -set firewall ipv4 forward filter rule 99 outbound-interface name 'eth1' -set firewall ipv4 forward filter rule 120 action 'accept' -set firewall ipv4 forward filter rule 120 description 'LAN - Allow to PROD' -set firewall ipv4 forward filter rule 120 inbound-interface name 'LAN' -set firewall ipv4 forward filter rule 120 outbound-interface name 'eth2.3500' -set firewall ipv4 forward filter rule 130 action 'accept' -set firewall ipv4 forward filter rule 130 description 'LAN - Allow internet' -set firewall ipv4 forward filter rule 130 inbound-interface name 'LAN' -set firewall ipv4 forward filter rule 130 outbound-interface name 'pppoe0' -``` - -Also, we are adding global state policies, in order to allow established and -related traffic, in order not to drop valid responses: - -```none -set firewall global-options state-policy established action 'accept' -set firewall global-options state-policy invalid action 'drop' -set firewall global-options state-policy related action 'accept' -``` - -And finally, we need to allow input connections to the router itself only from -vrf MGMT: - -```none -set firewall ipv4 input filter default-action 'drop' -set firewall ipv4 input filter default-log -set firewall ipv4 input filter rule 10 action 'accept' -set firewall ipv4 input filter rule 10 description 'MGMT - Allow input' -set firewall ipv4 input filter rule 10 inbound-interface name 'MGMT' -``` diff --git a/docs/configexamples/md-ha.md b/docs/configexamples/md-ha.md deleted file mode 100644 index c3fd4f84..00000000 --- a/docs/configexamples/md-ha.md +++ /dev/null @@ -1,556 +0,0 @@ ---- -lastproofread: '2021-06-28' ---- - -(example-high-availability)= - -# High Availability Walkthrough - -This document walks you through a complete HA setup of two VyOS machines. This -design is based on a VM as the primary router and a physical machine as a -backup, using VRRP, BGP, OSPF, and conntrack sharing. - -This document aims to walk you through setting everything up, so -at a point where you can reboot any machine and not lose more than a few -seconds worth of connectivity. - -## Design - -This is based on a real-life production design. One of the complex issues -is ensuring you have redundant data INTO your network. We do this with a pair -of Cisco Nexus switches and using Virtual PortChannels that are spanned across -them. As a bonus, this also allows for complete switch failure without -an outage. How you achieve this yourself is left as an exercise to the reader. -But our setup is documented here. - -### Walkthrough suggestion - -The `commit` command is implied after every section. If you make an error, -`commit` will warn you and you can fix it before getting too far into things. -Please ensure you commit early and commit often. - -If you are following through this document, it is strongly suggested you -complete the entire document, ONLY doing the virtual router1 steps, and then -come back and walk through it AGAIN on the backup hardware router. - -This ensures you don't go too fast or miss a step. However, it will make your -life easier to configure the fixed IP address and default route now on the -hardware router. - -### Example Network - -In this document, we have been allocated 203.0.113.0/24 by our upstream -provider, which we are publishing on VLAN100. - -They want us to establish a BGP session to their routers on 192.0.2.11 and -192.0.2.12 from our routers 192.0.2.21 and 192.0.2.22. They are AS 65550 and -we are AS 65551. - -Our routers are going to have a floating IP address of 203.0.113.1, and use -.2 and .3 as their fixed IPs. - -We are going to use 10.200.201.0/24 for an 'internal' network on VLAN201. - -When traffic is originated from the 10.200.201.0/24 network, it will be -masqueraded to 203.0.113.1 - -For connection between sites, we are running a WireGuard link to two REMOTE -routers and using OSPF over those links to distribute routes. That remote -site is expected to send traffic from anything in 10.201.0.0/16 - -### VLANs - -These are the vlans we will be using: - -- 50: Upstream, using the 192.0.2.0/24 network allocated by them. -- 100: 'Public' network, using our 203.0.113.0/24 network. -- 201: 'Internal' network, using 10.200.201.0/24 - -### Hardware - -- switch1 (Nexus 10gb Switch) -- switch2 (Nexus 10gb Switch) -- compute1 (VMware ESXi 6.5) -- compute2 (VMware ESXi 6.5) -- compute3 (VMware ESXi 6.5) -- router2 (Random 1RU machine with 4 NICs) - -Note that router1 is a VM that runs on one of the compute nodes. - -### Network Cabling - -- From Datacenter - This connects into port 1 on both switches, and is tagged - as VLAN 50 -- Cisco VPC Crossconnect - Ports 39 and 40 bonded between each switch -- Hardware Router - Port 8 of each switch -- compute1 - Port 9 of each switch -- compute2 - Port 10 of each switch -- compute3 - Port 11 of each switch - -This is ignoring the extra Out-of-band management networking, which should be -on totally different switches, and a different feed into the rack, and is out -of scope of this. - -:::{note} -Our implementation uses VMware's Distributed Port Groups, which allows -VMware to use LACP. This is a part of the ENTERPRISE licence, and is not -available on a free licence. If you are implementing this and do not have -access to DPGs, you should not use VMware, and use some other virtualization -platform instead. -::: - -## Basic Setup (via console) - -Create your router1 VM. So it can withstand a VM Host failing or a -network link failing. Using VMware, this is achieved by enabling vSphere DRS, -vSphere Availability, and creating a Distributed Port Group that uses LACP. - -Many other Hypervisors do this, and I'm hoping that this document will be -expanded to document how to do this for others. - -Create an 'All VLANs' network group, that passes all trunked traffic through -to the VM. Attach this network group to router1 as eth0. - -:::{note} -VMware: You must DISABLE SECURITY on this Port group. Make sure that -`Promiscuous Mode`, `MAC address changes` and `Forged transmits` are -enabled. All of these will be done as part of failover. -::: - -### Bonding on Hardware Router - -Create a LACP bond on the hardware router. We are assuming that eth0 and eth1 -are connected to port 8 on both switches, and that those ports are configured -as a Port-Channel. - -```none -set interfaces bonding bond0 description 'Switch Port-Channel' -set interfaces bonding bond0 hash-policy 'layer2' -set interfaces bonding bond0 member interface 'eth0' -set interfaces bonding bond0 member interface 'eth1' -set interfaces bonding bond0 mode '802.3ad' -``` - - -### Assign external IP addresses - -VLAN 100 and 201 will have floating IP addresses, but VLAN50 does not, as this -is talking directly to upstream. Create our IP address on vlan50. - -For the hardware router, replace `eth0` with `bond0`. As (almost) every -command is identical, this will not be specified unless different things need -to be performed on different hosts. - -```none -set interfaces ethernet eth0 vif 50 address '192.0.2.21/24' -``` - -In this case, the hardware router has a different IP, so it would be - -```none -set interfaces ethernet bond0 vif 50 address '192.0.2.22/24' -``` - - -### Add (temporary) default route - -It is assumed that the routers provided by upstream are capable of acting as a -default router, add that as a static route. - -```none -set protocols static route 0.0.0.0/0 next-hop 192.0.2.11 -commit -save -``` - - -### Enable SSH - -Enable SSH so you can now SSH into the routers, rather than using the console. - -```none -set service ssh -commit -save -``` - -At this point, you should be able to SSH into both of them, and will no longer -need access to the console (unless you break something!) - -## VRRP Configuration - -We are setting up VRRP so that it does NOT fail back when a machine returns into -service, and it prioritizes router1 over router2. - -### Internal Network - -This has a floating IP address of 10.200.201.1/24, using virtual router ID 201. -The difference between them is the interface name, hello-source-address, and -peer-address. - -**router1** - -```none -set interfaces ethernet eth0 vif 201 address 10.200.201.2/24 -set high-availability vrrp group int hello-source-address '10.200.201.2' -set high-availability vrrp group int interface 'eth0.201' -set high-availability vrrp group int peer-address '10.200.201.3' -set high-availability vrrp group int no-preempt -set high-availability vrrp group int priority '200' -set high-availability vrrp group int address '10.200.201.1/24' -set high-availability vrrp group int vrid '201' -``` - -**router2** - -```none -set interfaces ethernet bond0 vif 201 address 10.200.201.3/24 -set high-availability vrrp group int hello-source-address '10.200.201.3' -set high-availability vrrp group int interface 'bond0.201' -set high-availability vrrp group int peer-address '10.200.201.2' -set high-availability vrrp group int no-preempt -set high-availability vrrp group int priority '100' -set high-availability vrrp group int address '10.200.201.1/24' -set high-availability vrrp group int vrid '201' -``` - - -### Public Network - -This has a floating IP address of 203.0.113.1/24, using virtual router ID 113. -The virtual router ID is just a random number between 1 and 254, and can be set -to whatever you want. Best practices suggest you try to keep them unique -enterprise-wide. - -**router1** - -```none -set interfaces ethernet eth0 vif 100 address 203.0.113.2/24 -set high-availability vrrp group public hello-source-address '203.0.113.2' -set high-availability vrrp group public interface 'eth0.100' -set high-availability vrrp group public peer-address '203.0.113.3' -set high-availability vrrp group public no-preempt -set high-availability vrrp group public priority '200' -set high-availability vrrp group public address '203.0.113.1/24' -set high-availability vrrp group public vrid '113' -``` - -**router2** - -```none -set interfaces ethernet bond0 vif 100 address 203.0.113.3/24 -set high-availability vrrp group public hello-source-address '203.0.113.3' -set high-availability vrrp group public interface 'bond0.100' -set high-availability vrrp group public peer-address '203.0.113.2' -set high-availability vrrp group public no-preempt -set high-availability vrrp group public priority '100' -set high-availability vrrp group public address '203.0.113.1/24' -set high-availability vrrp group public vrid '113' -``` - - -### Create VRRP sync-group - -The sync group is used to replicate connection tracking. It needs to be assigned -to a random VRRP group, and we are creating a sync group called `sync` using -the vrrp group `int`. - -```none -set high-availability vrrp sync-group sync member 'int' -``` - - -### Testing - -At this point, you should be able to see both IP addresses when you run -`show interfaces`, and `show vrrp` should show both interfaces in MASTER -state (and SLAVE state on router2). - -```none -vyos@router1:~$ show vrrp -Name Interface VRID State Last Transition --------- ----------- ------ ------- ----------------- -int eth0.201 201 MASTER 100s -public eth0.100 113 MASTER 200s -vyos@router1:~$ -``` - -You should be able to ping to and from all the IPs you have allocated. - -## NAT and conntrack-sync - -Masquerade Traffic originating from 10.200.201.0/24 that is heading out the -public interface. - -:::{note} -We explicitly exclude the primary upstream network so that BGP or -OSPF traffic doesn't accidentally get NAT'ed. -::: - -```none -set nat source rule 10 destination address '!192.0.2.0/24' -set nat source rule 10 outbound-interface name 'eth0.50' -set nat source rule 10 source address '10.200.201.0/24' -set nat source rule 10 translation address '203.0.113.1' -``` - - -### Configure conntrack-sync and enable helpers - -Conntrack helper modules are enabled by default, but they tend to cause more -problems than they're worth in complex networks. You can disable all of them -at one go. - -```none -delete system conntrack modules -``` - -Now enable replication between nodes. Replace eth0.201 with bond0.201 on the -hardware router. - -```none -set service conntrack-sync accept-protocol 'tcp,udp,icmp' -set service conntrack-sync event-listen-queue-size '8' -set service conntrack-sync failover-mechanism vrrp sync-group 'sync' -set service conntrack-sync interface eth0.201 -set service conntrack-sync mcast-group '224.0.0.50' -set service conntrack-sync sync-queue-size '8' -``` - -(ha-contracktesting)= - -### Testing - -The simplest way to test is to look at the connection tracking stats on the -standby hardware router with the command `show conntrack-sync statistics`. -The numbers should be very close to the numbers on the primary router. - -When you have both routers up, you should be able to establish a connection -from a NAT'ed machine out to the internet, reboot the active machine, and that -connection should be preserved, and will not drop out. - -## OSPF Over WireGuard - -Wireguard doesn't have the concept of an up or down link, due to its design. -This complicates AND simplifies using it for network transport, as for reliable -state detection you need to use SOMETHING to detect when the link is down. - -If you use a routing protocol itself, you solve two problems at once. This is -only a basic example, and is provided as a starting point. - -### Configure Wireguard - -There is plenty of instructions and documentation on setting up Wireguard. The -only important thing you need to remember is to only use one WireGuard -interface per OSPF connection. - -We use small /30's from 10.254.60/24 for the point-to-point links. - -**router1** - -Replace the 203.0.113.3 with whatever the other router's IP address is. - -```none -set interfaces wireguard wg01 address '10.254.60.1/30' -set interfaces wireguard wg01 description 'router1-to-offsite1' -set interfaces wireguard wg01 peer OFFSITE1 allowed-ips '0.0.0.0/0' -set interfaces wireguard wg01 peer OFFSITE1 endpoint '203.0.113.3:50001' -set interfaces wireguard wg01 peer OFFSITE1 persistent-keepalive '15' -set interfaces wireguard wg01 peer OFFSITE1 pubkey 'GEFMOWzAyau42/HwdwfXnrfHdIISQF8YHj35rOgSZ0o=' -set interfaces wireguard wg01 port '50001' -set protocols ospf interface wg01 authentication md5 key-id 1 md5-key 'i360KoCwUGZvPq7e' -set protocols ospf interface wg01 cost '11' -set protocols ospf interface wg01 dead-interval '5' -set protocols ospf interface wg01 hello-interval '1' -set protocols ospf interface wg01 network 'point-to-point' -set protocols ospf interface wg01 priority '1' -set protocols ospf interface wg01 retransmit-interval '5' -set protocols ospf interface wg01 transmit-delay '1' -``` - -**offsite1** - -This is connecting back to the STATIC IP of router1, not the floating. - -```none -set interfaces wireguard wg01 address '10.254.60.2/30' -set interfaces wireguard wg01 description 'offsite1-to-router1' -set interfaces wireguard wg01 peer ROUTER1 allowed-ips '0.0.0.0/0' -set interfaces wireguard wg01 peer ROUTER1 endpoint '192.0.2.21:50001' -set interfaces wireguard wg01 peer ROUTER1 persistent-keepalive '15' -set interfaces wireguard wg01 peer ROUTER1 pubkey 'CKwMV3ZaLntMule2Kd3G7UyVBR7zE8/qoZgLb82EE2Q=' -set interfaces wireguard wg01 port '50001' -set protocols ospf interface wg01 authentication md5 key-id 1 md5-key 'i360KoCwUGZvPq7e' -set protocols ospf interface wg01 cost '11' -set protocols ospf interface wg01 dead-interval '5' -set protocols ospf interface wg01 hello-interval '1' -set protocols ospf interface wg01 network 'point-to-point' -set protocols ospf interface wg01 priority '1' -set protocols ospf interface wg01 retransmit-interval '5' -set protocols ospf interface wg01 transmit-delay '1' -``` - - -### Test WireGuard - -Make sure you can ping 10.254.60.1 and .2 from both routers. - -### Create Export Filter - -We only want to export the networks we know. Always do a whitelist on your route -filters, both importing and exporting. A good rule of thumb is -**'If you are not the default router for a network, don't advertise -it'**. This means we explicitly do not want to advertise the 192.0.2.0/24 -network (but do want to advertise 10.200.201.0 and 203.0.113.0, which we ARE -the default route for). This filter is applied to `redistribute connected`. -If we WERE to advertise it, the remote machines would see 192.0.2.21 available -via their default route, establish the connection, and then OSPF would say -'192.0.2.0/24 is available via this tunnel', at which point the tunnel would -break, OSPF would drop the routes, and then 192.0.2.0/24 would be reachable via -default again. This is called 'flapping'. - -```none -set policy access-list 150 description 'Outbound OSPF Redistribution' -set policy access-list 150 rule 10 action 'permit' -set policy access-list 150 rule 10 destination any -set policy access-list 150 rule 10 source inverse-mask '0.0.0.255' -set policy access-list 150 rule 10 source network '10.200.201.0' -set policy access-list 150 rule 20 action 'permit' -set policy access-list 150 rule 20 destination any -set policy access-list 150 rule 20 source inverse-mask '0.0.0.255' -set policy access-list 150 rule 20 source network '203.0.113.0' -set policy access-list 150 rule 100 action 'deny' -set policy access-list 150 rule 100 destination any -set policy access-list 150 rule 100 source any -``` - - -### Create Import Filter - -We only want to import networks we know. Our OSPF peer should only be -advertising networks in the 10.201.0.0/16 range. Note that this is an INVERSE -MATCH. You deny in access-list 100 to accept the route. - -```none -set policy access-list 100 description 'Inbound OSPF Routes from Peers' -set policy access-list 100 rule 10 action 'deny' -set policy access-list 100 rule 10 destination any -set policy access-list 100 rule 10 source inverse-mask '0.0.255.255' -set policy access-list 100 rule 10 source network '10.201.0.0' -set policy access-list 100 rule 100 action 'permit' -set policy access-list 100 rule 100 destination any -set policy access-list 100 rule 100 source any -set policy route-map PUBOSPF rule 100 action 'deny' -set policy route-map PUBOSPF rule 100 match ip address access-list '100' -set policy route-map PUBOSPF rule 500 action 'permit' -``` - - -### Enable OSPF - -Every router **must** have a unique router-id. -The 'reference-bandwidth' is used because when OSPF was originally designed, -the idea of a link faster than 1gbit was unheard of, and it does not scale -correctly. - -```none -set protocols ospf area 0.0.0.0 authentication 'md5' -set protocols ospf area 0.0.0.0 network '10.254.60.0/24' -set protocols ospf auto-cost reference-bandwidth '10000' -set protocols ospf log-adjacency-changes -set protocols ospf parameters abr-type 'cisco' -set protocols ospf parameters router-id '10.254.60.2' -set system ip protocol ospf route-map PUBOSPF -``` - - -### Test OSPF - -When you have enabled OSPF on both routers, you should be able to see each -other with the command `show ip ospf neighbour`. The state must be 'Full' -or '2-Way'. If it is not, then there is a network connectivity issue between the -hosts. This is often caused by NAT or MTU issues. You should not see any new -routes (unless this is the second pass) in the output of `show ip route` - -## Advertise connected routes - -As a reminder, only advertise routes that you are the default router for. This -is why we are NOT announcing the 192.0.2.0/24 network, because if that was -announced into OSPF, the other routers would try to connect to that network -over a tunnel that connects to that network! - -```none -set protocols ospf access-list 150 export 'connected' -set protocols ospf redistribute connected -``` - -You should now be able to see the advertised network on the other host. - -### Duplicate configuration - -At this point, you now need to create the X link between all four routers. -Use a different /30 for each link. - -### Priorities - -Set the cost on the secondary links to be 200. This means that they will not -be used unless the primary links are down. - -```none -set protocols ospf interface wg01 cost '10' -set protocols ospf interface wg01 cost '200' -``` - -This will be visible in 'show ip route'. - -## BGP - -BGP is an extremely complex network protocol. An example is provided here. - -:::{note} -Router id's must be unique. -::: - -**router1** - -The `redistribute ospf` command is there purely as an example of how this can -be expanded. In this walkthrough, it will be filtered by BGPOUT rule 10000, as -it is not 203.0.113.0/24. - -```none -set policy prefix-list BGPOUT description 'BGP Export List' -set policy prefix-list BGPOUT rule 10 action 'deny' -set policy prefix-list BGPOUT rule 10 description 'Do not advertise short masks' -set policy prefix-list BGPOUT rule 10 ge '25' -set policy prefix-list BGPOUT rule 10 prefix '0.0.0.0/0' -set policy prefix-list BGPOUT rule 100 action 'permit' -set policy prefix-list BGPOUT rule 100 description 'Our network' -set policy prefix-list BGPOUT rule 100 prefix '203.0.113.0/24' -set policy prefix-list BGPOUT rule 10000 action 'deny' -set policy prefix-list BGPOUT rule 10000 prefix '0.0.0.0/0' - -set policy route-map BGPOUT description 'BGP Export Filter' -set policy route-map BGPOUT rule 10 action 'permit' -set policy route-map BGPOUT rule 10 match ip address prefix-list 'BGPOUT' -set policy route-map BGPOUT rule 10000 action 'deny' -set policy route-map BGPPREPENDOUT description 'BGP Export Filter' -set policy route-map BGPPREPENDOUT rule 10 action 'permit' -set policy route-map BGPPREPENDOUT rule 10 set as-path prepend '65551 65551 65551' -set policy route-map BGPPREPENDOUT rule 10 match ip address prefix-list 'BGPOUT' -set policy route-map BGPPREPENDOUT rule 10000 action 'deny' - -set protocols bgp system-as 65551 -set protocols bgp address-family ipv4-unicast network 192.0.2.0/24 -set protocols bgp address-family ipv4-unicast redistribute connected metric '50' -set protocols bgp address-family ipv4-unicast redistribute ospf metric '50' -set protocols bgp neighbor 192.0.2.11 address-family ipv4-unicast route-map export 'BGPOUT' -set protocols bgp neighbor 192.0.2.11 address-family ipv4-unicast soft-reconfiguration inbound -set protocols bgp neighbor 192.0.2.11 remote-as '65550' -set protocols bgp neighbor 192.0.2.11 update-source '192.0.2.21' -set protocols bgp parameters router-id '192.0.2.21' -``` - -**router2** - -This is identical, but you use the BGPPREPENDOUT route-map to advertise the -route with a longer path. diff --git a/docs/configexamples/md-index.md b/docs/configexamples/md-index.md deleted file mode 100644 index e5a81305..00000000 --- a/docs/configexamples/md-index.md +++ /dev/null @@ -1,60 +0,0 @@ -(examples)= - -# Configuration Blueprints - -This chapter contains various configuration examples: - -```{toctree} -:maxdepth: 2 - -firewall -bgp-ipv6-unnumbered -ospf-unnumbered -azure-vpn-bgp -azure-vpn-dual-bgp -ha -wan-load-balancing -pppoe-ipv6-basic -l3vpn-hub-and-spoke -lac-lns -inter-vrf-routing-vrf-lite -dmvpn-dualhub-dualcloud -qos -segment-routing-isis -nmp -ansible -ipsec-cisco-policy-based -ipsec-cisco-route-based -ipsec-pa-route-based -policy-based-ipsec-and-firewall -site-2-site-cisco -``` - - -## Configuration Blueprints (autotest) - -The next pages contain fully automated configuration examples. - -Each lab will build and test from an external script. -The page content is generated, so changes will not take effect. - -A host `vyos-oobm` will be used as an SSH proxy. This host is just -necessary for the lab tests. - -The process will do the following steps: -1. create the lab on a eve-ng server -2. configure each host in the lab -3. do some defined tests -4. optional do an upgrade to a higher version and do step 3 again. -5. generate the documentation and include files -6. shutdown and destroy the lab, if there is no error - -```{toctree} -:maxdepth: 1 - -autotest/DHCPRelay_through_GRE/DHCPRelay_through_GRE -autotest/tunnelbroker/tunnelbroker -autotest/L3VPN_EVPN/L3VPN_EVPN -autotest/Wireguard/Wireguard -autotest/OpenVPN_with_LDAP/OpenVPN_with_LDAP -``` diff --git a/docs/configexamples/md-inter-vrf-routing-vrf-lite.md b/docs/configexamples/md-inter-vrf-routing-vrf-lite.md deleted file mode 100644 index 349a6f14..00000000 --- a/docs/configexamples/md-inter-vrf-routing-vrf-lite.md +++ /dev/null @@ -1,797 +0,0 @@ -# Inter-VRF Routing over VRF Lite - -**Virtual Routing and Forwarding** is a technology that allow multiple instance -of a routing table to exist within a single device. One of the key aspect of -**VRFs** is that do not share the same routes or interfaces, therefore packets -are forwarded between interfaces that belong to the same VRF only. - -Any information related to a VRF is not exchanged between devices -or in the -same device- by default, this is a technique called **VRF-Lite**. - -Keep networks isolated is -in general- a good principle, but there are cases -where you might need that some network can access other in a different VRF. - -The scope of this document is to cover such cases in a dynamic way without the -use of MPLS-LDP. - -General information about L3VPNs can be found in the {ref}`configuration/vrf/index:L3VPN VRFs` chapter. - -## Overview - -Let’s say we have a requirement to have multiple networks. - -- LAN 1 -- LAN 2 -- Management -- Internet - -Both LANs have to be able to route between each other, both will have managed -devices through a dedicated management network and both will need Internet -access yet the LAN2 will need access to some set of outside networks, not all. -The management network will need access to both LANs but cannot have access -to/from the outside. - -This scenario could be a nightmare applying regular routing and might need -filtering in multiple interfaces. - -A simple solution could be using different routing tables, or VRFs -for all the networks so we can keep the routing restrictions. -But for us to route between the different VRFs we would need a cable or a -logical connection between each other: - -- One cable/logical connection between LAN1 and LAN2 -- One cable/logical connection between LAN1 and Internet -- One cable/logical connection between LAN2 and Internet -- One cable/logical connection between LAN1 and Management -- One cable/logical connection between LAN2 and Management - -As we can see this is unpractical. - -To address this scenario we will use to our advantage an extension of the BGP -routing protocol that will help us in the “Export” between VRFs without the -need for MPLS. - -MP-BGP or MultiProtocol BGP introduces two main concepts to solve this -limitation: -\- Route Distinguisher (RD): Is used to distinguish between different VRFs -–called VPNs- inside the BGP Process. The RD is appended to each IPv4 Network -that is advertised into BGP for that VPN making it a unique VPNv4 route. -\- Route Target (RT): This is an extended BGP community append to the VPNv4 route -in the Import/Export process. When a route passes from the VRF routing table -into the BGP process it will add the configured export extended community(ies) -for that VPN. When that route needs to go from BGP into the VRF routing table -will only pass if that given VPN import policy matches any of the appended -community(ies) into that prefix. - -## Topology - -```{image} /_static/images/inter-vrf-routing-vrf-lite.webp -:align: center -:alt: Network Topology Diagram -:width: 70% -``` - - -### IP Schema - -```{eval-rst} -+----------+------------+----------------+------------------+ -| Device-A | Device-B | IPv4 Network | IPv6 Network | -+----------+------------+----------------+------------------+ -| Core | LAN1 | 10.1.1.0/30 | 2001:db8::/127 | -+----------+------------+----------------+------------------+ -| Core | LAN2 | 172.16.2.0/30 | 2001:db8::2/127 | -+----------+------------+----------------+------------------+ -| Core | Management | 192.168.3.0/30 | 2001:db8::4/127 | -+----------+------------+----------------+------------------+ -| Core | ISP | 10.2.2.0/30 | 2001:db8::6/127 | -+----------+------------+----------------+------------------+ -``` - -### RD & RT Schema - -```{eval-rst} -+------------+-----------+-----------+ -| VRF | RD | RT | -+------------+-----------+-----------+ -| LAN1 | 64496:1 | 64496:1 | -+------------+-----------+-----------+ -| LAN2 | 64496:2 | 64496:2 | -+------------+-----------+-----------+ -| Management | 64496:50 | 64496:50 | -+------------+-----------+-----------+ -| Internet | 64496:100 | 64496:100 | -+------------+-----------+-----------+ -``` - -## Configurations - -:::{note} -We use a static route configuration in between the Core and each -LAN and Management router, and BGP between the Core router and the ISP router -but any dynamic routing protocol can be used. -::: - -### Remote Networks - -The following template configuration can be used in each remote router based -in our topology. - -```none -# Interface Configuration -set interface eth eth address - -# Static default route back to Core -set procotols static route 0.0.0.0/0 next-hop -``` - - -### Core Router - -#### Step 1: VRF and Configurations to remote networks - -- Configuration - -Set the VRF name and Table ID, set interface address and bind it to the VRF. -Last add the static route to the remote network. - -```none -# VRF name and table ID (MANDATORY) -set vrf name table - -# Interface Configuration -set interface eth eth address - -# Assign interface to VRF -set interface eth eth vrf - -# Static route to remote Network -set vrf name protocols static route next-hop -``` - -- Verification - -Checking the routing table of the VRF should reveal both static and connected -entries active. A PING test between the Core and remote router is a way to -validate connectivity within the VRF. - -```none -# show ip route vrf -# show ipv6 route vrf - -vyos@Core:~$ show ip route vrf LAN1 -Codes: K - kernel route, C - connected, S - static, R - RIP, - O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, - T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, - f - OpenFabric, - > - selected route, * - FIB route, q - queued, r - rejected, b - backup - t - trapped, o - offload failure - -VRF LAN1: -S>* 10.0.0.0/24 [1/0] via 10.1.1.2, eth0, weight 1, 00:05:41 -C>* 10.1.1.0/30 is directly connected, eth0, 00:05:44 - -vyos@Core:~$ show ipv6 route vrf LAN1 -Codes: K - kernel route, C - connected, S - static, R - RIPng, - O - OSPFv3, I - IS-IS, B - BGP, N - NHRP, T - Table, - v - VNC, V - VNC-Direct, A - Babel, F - PBR, - f - OpenFabric, - > - selected route, * - FIB route, q - queued, r - rejected, b - backup - t - trapped, o - offload failure - -VRF LAN1: -C>* 2001:db8::/127 is directly connected, eth0, 00:18:43 -S>* 2001:db8:0:1::/64 [1/0] via 2001:db8::1, eth0, weight 1, 00:16:03 -C>* fe80::/64 is directly connected, eth0, 00:18:43 - -# ping vrf - -vyos@Core:~$ ping 10.1.1.2 vrf LAN1 -PING 10.1.1.2 (10.1.1.2) 56(84) bytes of data. -64 bytes from 10.1.1.2: icmp_seq=1 ttl=64 time=1.52 ms -64 bytes from 10.1.1.2: icmp_seq=2 ttl=64 time=0.830 ms -^C ---- 10.1.1.2 ping statistics --- -2 packets transmitted, 2 received, 0% packet loss, time 1002ms -rtt min/avg/max/mdev = 0.830/1.174/1.518/0.344 ms -vyos@Core:~$ ping 10.0.0.1 vrf LAN1 -PING 10.0.0.1 (10.0.0.1) 56(84) bytes of data. -64 bytes from 10.0.0.1: icmp_seq=1 ttl=64 time=0.785 ms -64 bytes from 10.0.0.1: icmp_seq=2 ttl=64 time=0.948 ms -^C ---- 10.0.0.1 ping statistics --- -2 packets transmitted, 2 received, 0% packet loss, time 1002ms -rtt min/avg/max/mdev = 0.785/0.866/0.948/0.081 ms - -vyos@Core:~$ ping 2001:db8:0:1::1 vrf LAN1 -PING 2001:db8:0:1::1(2001:db8:0:1::1) 56 data bytes -64 bytes from 2001:db8:0:1::1: icmp_seq=1 ttl=64 time=3.04 ms -64 bytes from 2001:db8:0:1::1: icmp_seq=2 ttl=64 time=1.04 ms -64 bytes from 2001:db8:0:1::1: icmp_seq=3 ttl=64 time=0.925 ms -^C ---- 2001:db8:0:1::1 ping statistics --- -3 packets transmitted, 3 received, 0% packet loss, time 2004ms -rtt min/avg/max/mdev = 0.925/1.665/3.035/0.969 ms -``` - - -#### Step 2: BGP Configuration for VRF-Lite - -- Configuration - -Setting BGP global local-as as well inside the VRF. Redistribute static -routes to inject configured networks into the BGP process but still inside -the VRF. - -```none -# set BGP global local-as -set protocols bgp system-as - -# set BGP VRF local-as and redistribution -set vrf name protocols bgp address-family redistribute static -``` - -- Verification - -Check the BGP VRF table and verify if the static routes are injected showing -the correct next-hop information. - -```none -# show ip bgp vrf -# show bgp vrf ipv6 - -vyos@Core:~$ show ip bgp vrf LAN1 -BGP table version is 3, local router ID is 10.1.1.1, vrf id 8 -Default local pref 100, local AS 64496 -Status codes: s suppressed, d damped, h history, * valid, > best, = multipath, - i internal, r RIB-failure, S Stale, R Removed -Nexthop codes: @NNN nexthop's vrf id, < announce-nh-self -Origin codes: i - IGP, e - EGP, ? - incomplete -RPKI validation codes: V valid, I invalid, N Not found - - Network Next Hop Metric LocPrf Weight Path -*> 10.0.0.0/24 10.1.1.2 0 32768 ? - -vyos@Core# run show bgp vrf LAN1 ipv6 -BGP table version is 13, local router ID is 10.1.1.1, vrf id 8 -Default local pref 100, local AS 64496 -Status codes: s suppressed, d damped, h history, * valid, > best, = multipath, - i internal, r RIB-failure, S Stale, R Removed -Nexthop codes: @NNN nexthop's vrf id, < announce-nh-self -Origin codes: i - IGP, e - EGP, ? - incomplete -RPKI validation codes: V valid, I invalid, N Not found - - Network Next Hop Metric LocPrf Weight Path -*> 2001:db8:0:1::/64 - 2001:db8::1 0 32768 ? -``` - - -#### Step 3: VPN Configuration - -- Configuration - -Within the VRF we set the Route-Distinguisher (RD) and Route-Targets (RT), -then we enable the export/import VPN. - -```none -# set Route-distinguisher -set vrf name protocols bgp address-family rd vpn export '' - -# set route-target for import/export -# Note: RT are a list that can be more than one community between apostrophe -# and separated by blank space. Ex: ' ' -set vrf name protocols bgp address-family route-target vpn export '' -set vrf name protocols bgp address-family route-target vpn import '' - -# Enable VPN export/import under this VRF -set vrf name protocols bgp address-family export vpn -set vrf name protocols bgp address-family import vpn -``` - -A key point to understand is that if we need two VRFs to communicate between -each other EXPORT rt from VRF1 has to be in the IMPORT rt list from VRF2. But -this is only in ONE direction, to complete the communication the EXPORT rt from -VRF2 has to be in the IMPORT rt list from VRF1. - -There are some cases where this is not needed -for example, in some -DDoS appliance- but most inter-vrf routing designs use the above configurations. - -- Verification - -After configured all the VRFs involved in this topology we take a deeper look -at both BGP and Routing table for the VRF LAN1 - -```none -# show ip bgp vrf -# show bgp vrf ipv6 - -vyos@Core# run show ip bgp vrf LAN1 -BGP table version is 53, local router ID is 10.1.1.1, vrf id 8 -Default local pref 100, local AS 64496 -Status codes: s suppressed, d damped, h history, * valid, > best, = multipath, - i internal, r RIB-failure, S Stale, R Removed -Nexthop codes: @NNN nexthop's vrf id, < announce-nh-self -Origin codes: i - IGP, e - EGP, ? - incomplete -RPKI validation codes: V valid, I invalid, N Not found - - Network Next Hop Metric LocPrf Weight Path -*> 0.0.0.0/0 10.2.2.2@7< 0 64497 i -*> 10.0.0.0/24 10.1.1.2 0 32768 ? -*> 10.2.2.0/30 10.2.2.2@7< 0 0 64497 ? -*> 192.0.2.0/24 10.2.2.2@7< 0 0 64497 ? -*> 192.168.0.0/24 192.168.3.2@11< 0 32768 ? -*> 198.51.100.0/24 10.2.2.2@7< 0 0 64497 ? -*> 203.0.113.0/24 10.2.2.2@7< 0 0 64497 ? - -vyos@Core# run show bgp vrf LAN1 ipv6 -BGP table version is 13, local router ID is 10.1.1.1, vrf id 8 -Default local pref 100, local AS 64496 -Status codes: s suppressed, d damped, h history, * valid, > best, = multipath, - i internal, r RIB-failure, S Stale, R Removed -Nexthop codes: @NNN nexthop's vrf id, < announce-nh-self -Origin codes: i - IGP, e - EGP, ? - incomplete -RPKI validation codes: V valid, I invalid, N Not found - -Network Next Hop Metric LocPrf Weight Path -*> ::/0 fe80::5200:ff:fe02:3@7< - 0 64497 i -*> 2001:db8::6/127 fe80::5200:ff:fe02:3@7< - 0 0 64497 ? -*> 2001:db8:0:1::/64 - 2001:db8::1 0 32768 ? -*> 2001:db8:0:3::/64 - 2001:db8::5@11< 0 32768 ? -*> 2001:db8:1::/48 fe80::5200:ff:fe02:3@7< - 0 0 64497 ? -*> 2001:db8:2::/48 fe80::5200:ff:fe02:3@7< - 0 0 64497 ? -*> 2001:db8:3::/48 fe80::5200:ff:fe02:3@7< - 0 0 64497 ? - -# show ip route vrf -# show ipv6 route vrf - -vyos@Core:~$ show ip route vrf LAN1 -Codes: K - kernel route, C - connected, S - static, R - RIP, - O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, - T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, - f - OpenFabric, - > - selected route, * - FIB route, q - queued, r - rejected, b - backup - t - trapped, o - offload failure - -VRF LAN1: -B>* 0.0.0.0/0 [20/0] via 10.2.2.2, eth3 (vrf Internet), weight 1, 00:00:38 -S>* 10.0.0.0/24 [1/0] via 10.1.1.2, eth0, weight 1, 00:29:57 -C>* 10.1.1.0/30 is directly connected, eth0, 00:29:59 -B 10.2.2.0/30 [20/0] via 10.2.2.2 (vrf Internet) inactive, weight 1, 00:00:38 -B>* 172.16.0.0/24 [20/0] via 172.16.2.2, eth1 (vrf LAN2), weight 1, 00:00:38 -B>* 192.0.2.0/24 [20/0] via 10.2.2.2, eth3 (vrf Internet), weight 1, 00:00:38 -B>* 198.51.100.0/24 [20/0] via 10.2.2.2, eth3 (vrf Internet), weight 1, 00:00:38 -B>* 203.0.113.0/24 [20/0] via 10.2.2.2, eth3 (vrf Internet), weight 1, 00:00:38 - -vyos@Core# run show ipv6 route vrf LAN1 -Codes: K - kernel route, C - connected, S - static, R - RIPng, - O - OSPFv3, I - IS-IS, B - BGP, N - NHRP, T - Table, - v - VNC, V - VNC-Direct, A - Babel, F - PBR, - f - OpenFabric, - > - selected route, * - FIB route, q - queued, r - rejected, b - backup - t - trapped, o - offload failure - -VRF LAN1: -B>* ::/0 [20/0] via fe80::5200:ff:fe02:3, eth3 (vrf Internet), weight 1, 00:07:50 -C>* 2001:db8::/127 is directly connected, eth0, 05:33:43 -B>* 2001:db8::6/127 [20/0] via fe80::5200:ff:fe02:3, eth3 (vrf Internet), weight 1, 00:07:50 -S>* 2001:db8:0:1::/64 [1/0] via 2001:db8::1, eth0, weight 1, 05:31:03 -B>* 2001:db8:0:3::/64 [20/0] via 2001:db8::5, eth2 (vrf Management), weight 1, 00:07:50 -B>* 2001:db8:1::/48 [20/0] via fe80::5200:ff:fe02:3, eth3 (vrf Internet), weight 1, 00:07:50 -B>* 2001:db8:2::/48 [20/0] via fe80::5200:ff:fe02:3, eth3 (vrf Internet), weight 1, 00:07:50 -B>* 2001:db8:3::/48 [20/0] via fe80::5200:ff:fe02:3, eth3 (vrf Internet), weight 1, 00:07:50 -C>* fe80::/64 is directly connected, eth0, 05:33:43 -``` - -As we can see in the BGP table any imported route has been injected with a "@" -followed by the VPN id; In the routing table of the VRF, if the route was -installed, we can see -between round brackets- the exported VRF table. - -#### Step 4: End to End verification - -Now we perform some end-to-end testing -- From Management to LAN1/LAN2 - -```none -vyos@Management:~$ ping 10.0.0.1 source-address 192.168.0.1 -PING 10.0.0.1 (10.0.0.1) from 192.168.0.1 : 56(84) bytes of data. -64 bytes from 10.0.0.1: icmp_seq=1 ttl=63 time=1.93 ms -64 bytes from 10.0.0.1: icmp_seq=2 ttl=63 time=2.12 ms -64 bytes from 10.0.0.1: icmp_seq=3 ttl=63 time=2.12 ms -^C ---- 10.0.0.1 ping statistics --- -3 packets transmitted, 3 received, 0% packet loss, time 2005ms -rtt min/avg/max/mdev = 1.931/2.056/2.123/0.088 ms -vyos@Management:~$ ping 172.16.0.1 source-address 192.168.0.1 -PING 172.16.0.1 (172.16.0.1) from 192.168.0.1 : 56(84) bytes of data. -64 bytes from 172.16.0.1: icmp_seq=1 ttl=63 time=1.62 ms -64 bytes from 172.16.0.1: icmp_seq=2 ttl=63 time=1.75 ms -^C ---- 172.16.0.1 ping statistics --- -2 packets transmitted, 2 received, 0% packet loss, time 1001ms -rtt min/avg/max/mdev = 1.621/1.686/1.752/0.065 ms -vyos@Management:~$ ping 2001:db8:0:1::1 source-address 2001:db8:0:3::1 -PING 2001:db8:0:1::1(2001:db8:0:1::1) from 2001:db8:0:3::1 : 56 data bytes -64 bytes from 2001:db8:0:1::1: icmp_seq=1 ttl=63 time=2.44 ms -64 bytes from 2001:db8:0:1::1: icmp_seq=2 ttl=63 time=2.40 ms -64 bytes from 2001:db8:0:1::1: icmp_seq=3 ttl=63 time=2.41 ms -^C ---- 2001:db8:0:1::1 ping statistics --- -3 packets transmitted, 3 received, 0% packet loss, time 2003ms -rtt min/avg/max/mdev = 2.399/2.418/2.442/0.017 ms -vyos@Management:~$ ping 2001:db8:0:2::1 source-address 2001:db8:0:3::1 -PING 2001:db8:0:2::1(2001:db8:0:2::1) from 2001:db8:0:3::1 : 56 data bytes -64 bytes from 2001:db8:0:2::1: icmp_seq=1 ttl=63 time=1.66 ms -64 bytes from 2001:db8:0:2::1: icmp_seq=2 ttl=63 time=1.99 ms -64 bytes from 2001:db8:0:2::1: icmp_seq=3 ttl=63 time=1.88 ms -64 bytes from 2001:db8:0:2::1: icmp_seq=4 ttl=63 time=2.32 ms -^C ---- 2001:db8:0:2::1 ping statistics --- -4 packets transmitted, 4 received, 0% packet loss, time 3005ms -rtt min/avg/max/mdev = 1.660/1.960/2.315/0.236 ms -``` - -- From Management to Outside (fails as intended) - -```none -vyos@Management:~$ show ip route -Codes: K - kernel route, C - connected, S - static, R - RIP, - O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, - T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, - f - OpenFabric, - > - selected route, * - FIB route, q - queued, r - rejected, b - backup - t - trapped, o - offload failure - -S>* 0.0.0.0/0 [1/0] via 192.168.3.1, eth2, weight 1, 00:01:58 -C>* 192.168.0.0/24 is directly connected, dum0, 00:02:05 -C>* 192.168.3.0/30 is directly connected, eth2, 00:02:03 -vyos@Management:~$ ping 192.0.2.1 -PING 192.0.2.1 (192.0.2.1) 56(84) bytes of data. -From 192.168.3.1 icmp_seq=1 Destination Net Unreachable -From 192.168.3.1 icmp_seq=2 Destination Net Unreachable -^C ---- 192.0.2.1 ping statistics --- -2 packets transmitted, 0 received, +2 errors, 100% packet loss, time 1002ms - -vyos@Management:~$ ping 195.51.100.1 -PING 195.51.100.1 (195.51.100.1) 56(84) bytes of data. -From 192.168.3.1 icmp_seq=1 Destination Net Unreachable -From 192.168.3.1 icmp_seq=2 Destination Net Unreachable -From 192.168.3.1 icmp_seq=3 Destination Net Unreachable -^C ---- 195.51.100.1 ping statistics --- -3 packets transmitted, 0 received, +3 errors, 100% packet loss, time 2003ms - -vyos@Management:~$ ping 2001:db8:1::1 -PING 2001:db8:1::1(2001:db8:1::1) 56 data bytes -From 2001:db8::4 icmp_seq=1 Destination unreachable: No route -From 2001:db8::4 icmp_seq=2 Destination unreachable: No route -^C ---- 2001:db8:1::1 ping statistics --- -2 packets transmitted, 0 received, +2 errors, 100% packet loss, time 1002ms - -vyos@Management:~$ ping 2001:db8:2::1 -PING 2001:db8:2::1(2001:db8:2::1) 56 data bytes -From 2001:db8::4 icmp_seq=1 Destination unreachable: No route -From 2001:db8::4 icmp_seq=2 Destination unreachable: No route -^C ---- 2001:db8:2::1 ping statistics --- -2 packets transmitted, 0 received, +2 errors, 100% packet loss, time 1002ms -``` - -- LAN1 to Outside - -```none -vyos@LAN1:~$ ping 192.0.2.1 source-address 10.0.0.1 -PING 192.0.2.1 (192.0.2.1) from 10.0.0.1 : 56(84) bytes of data. -64 bytes from 192.0.2.1: icmp_seq=1 ttl=63 time=1.47 ms -64 bytes from 192.0.2.1: icmp_seq=2 ttl=63 time=1.41 ms -64 bytes from 192.0.2.1: icmp_seq=3 ttl=63 time=1.80 ms -^C ---- 192.0.2.1 ping statistics --- -3 packets transmitted, 3 received, 0% packet loss, time 2004ms -rtt min/avg/max/mdev = 1.414/1.563/1.803/0.171 ms -vyos@LAN1:~$ ping 198.51.100.1 source-address 10.0.0.1 -PING 198.51.100.1 (198.51.100.1) from 10.0.0.1 : 56(84) bytes of data. -64 bytes from 198.51.100.1: icmp_seq=1 ttl=63 time=1.71 ms -64 bytes from 198.51.100.1: icmp_seq=2 ttl=63 time=1.83 ms -^C ---- 198.51.100.1 ping statistics --- -2 packets transmitted, 2 received, 0% packet loss, time 1002ms -rtt min/avg/max/mdev = 1.705/1.766/1.828/0.061 ms -vyos@LAN1:~$ ping 203.0.113.1 source-address 10.0.0.1 -PING 203.0.113.1 (203.0.113.1) from 10.0.0.1 : 56(84) bytes of data. -64 bytes from 203.0.113.1: icmp_seq=1 ttl=63 time=1.25 ms -64 bytes from 203.0.113.1: icmp_seq=2 ttl=63 time=1.88 ms -^C ---- 203.0.113.1 ping statistics --- -2 packets transmitted, 2 received, 0% packet loss, time 1003ms -rtt min/avg/max/mdev = 1.249/1.566/1.884/0.317 ms -vyos@LAN1:~$ ping 2001:db8:1::1 source-address 2001:db8:0:1::1 -PING 2001:db8:1::1(2001:db8:1::1) from 2001:db8:0:1::1 : 56 data bytes -64 bytes from 2001:db8:1::1: icmp_seq=1 ttl=63 time=2.35 ms -64 bytes from 2001:db8:1::1: icmp_seq=2 ttl=63 time=2.29 ms -64 bytes from 2001:db8:1::1: icmp_seq=3 ttl=63 time=2.22 ms -^C ---- 2001:db8:1::1 ping statistics --- -3 packets transmitted, 3 received, 0% packet loss, time 2004ms -rtt min/avg/max/mdev = 2.215/2.285/2.352/0.055 ms -vyos@LAN1:~$ ping 2001:db8:2::1 source-address 2001:db8:0:1::1 -PING 2001:db8:2::1(2001:db8:2::1) from 2001:db8:0:1::1 : 56 data bytes -64 bytes from 2001:db8:2::1: icmp_seq=1 ttl=63 time=1.37 ms -64 bytes from 2001:db8:2::1: icmp_seq=2 ttl=63 time=2.68 ms -64 bytes from 2001:db8:2::1: icmp_seq=3 ttl=63 time=2.00 ms -^C ---- 2001:db8:2::1 ping statistics --- -3 packets transmitted, 3 received, 0% packet loss, time 2003ms -rtt min/avg/max/mdev = 1.367/2.015/2.679/0.535 ms -``` - -:::{note} -we are using "source-address" option cause we are not redistributing -connected interfaces into BGP on the Core router hence there is no comeback -route and ping will fail. -::: - -- LAN1 to LAN2 - -```none -vyos@LAN1:~$ ping 172.16.0.1 source-address 10.0.0.1 -PING 172.16.0.1 (172.16.0.1) from 10.0.0.1 : 56(84) bytes of data. -64 bytes from 172.16.0.1: icmp_seq=1 ttl=63 time=3.00 ms -64 bytes from 172.16.0.1: icmp_seq=2 ttl=63 time=2.20 ms -^C ---- 172.16.0.1 ping statistics --- -2 packets transmitted, 2 received, 0% packet loss, time 1002ms -rtt min/avg/max/mdev = 2.199/2.600/3.001/0.401 ms -vyos@LAN1:~$ ping 2001:db8:0:2::1 source 2001:db8:0:1::1 -PING 2001:db8:0:2::1(2001:db8:0:2::1) from 2001:db8:0:1::1 : 56 data bytes -64 bytes from 2001:db8:0:2::1: icmp_seq=1 ttl=63 time=4.82 ms -64 bytes from 2001:db8:0:2::1: icmp_seq=2 ttl=63 time=1.95 ms -64 bytes from 2001:db8:0:2::1: icmp_seq=3 ttl=63 time=1.98 ms -^C ---- 2001:db8:0:2::1 ping statistics --- -3 packets transmitted, 3 received, 0% packet loss, time 2003ms -rtt min/avg/max/mdev = 1.949/2.915/4.815/1.343 ms -``` - - -## Conclusions - -Inter-VRF routing is a well-known solution to address complex routing scenarios -that enable -in a dynamic way- to leak routes between VRFs. Is recommended to -take special consideration while designing route-targets and its application as -it can minimize future interventions while creating a new VRF will automatically -take the desired effect in its propagation. - -## Appendix-A - -### Full configuration from all devices - -- Core - -```none -set interfaces ethernet eth0 address '10.1.1.1/30' -set interfaces ethernet eth0 address '2001:db8::/127' -set interfaces ethernet eth0 vrf 'LAN1' -set interfaces ethernet eth1 address '172.16.2.1/30' -set interfaces ethernet eth1 address '2001:db8::2/127' -set interfaces ethernet eth1 vrf 'LAN2' -set interfaces ethernet eth2 address '192.168.3.1/30' -set interfaces ethernet eth2 address '2001:db8::4/127' -set interfaces ethernet eth2 vrf 'Management' -set interfaces ethernet eth3 address '10.2.2.1/30' -set interfaces ethernet eth3 address '2001:db8::6/127' -set interfaces ethernet eth3 vrf 'Internet' -set protocols bgp address-family ipv4-unicast -set protocols bgp system-as '64496' -set vrf name Internet protocols bgp address-family ipv4-unicast export vpn -set vrf name Internet protocols bgp address-family ipv4-unicast import vpn -set vrf name Internet protocols bgp address-family ipv4-unicast rd vpn export '64496:100' -set vrf name Internet protocols bgp address-family ipv4-unicast route-target vpn export '64496:100' -set vrf name Internet protocols bgp address-family ipv4-unicast route-target vpn import '64496:1 64496:2' -set vrf name Internet protocols bgp address-family ipv6-unicast export vpn -set vrf name Internet protocols bgp address-family ipv6-unicast import vpn -set vrf name Internet protocols bgp address-family ipv6-unicast rd vpn export '64496:100' -set vrf name Internet protocols bgp address-family ipv6-unicast route-target vpn export '64496:100' -set vrf name Internet protocols bgp address-family ipv6-unicast route-target vpn import '64496:1 64496:2' -set vrf name Internet protocols bgp neighbor 10.2.2.2 address-family ipv4-unicast -set vrf name Internet protocols bgp neighbor 10.2.2.2 remote-as '64497' -set vrf name Internet protocols bgp neighbor 2001:db8::7 address-family ipv6-unicast -set vrf name Internet protocols bgp neighbor 2001:db8::7 remote-as '64497' -set vrf name Internet table '104' -set vrf name LAN1 protocols bgp address-family ipv4-unicast export vpn -set vrf name LAN1 protocols bgp address-family ipv4-unicast import vpn -set vrf name LAN1 protocols bgp address-family ipv4-unicast rd vpn export '64496:1' -set vrf name LAN1 protocols bgp address-family ipv4-unicast redistribute static -set vrf name LAN1 protocols bgp address-family ipv4-unicast route-target vpn export '64496:1' -set vrf name LAN1 protocols bgp address-family ipv4-unicast route-target vpn import '64496:100 64496:50 64496:2' -set vrf name LAN1 protocols bgp address-family ipv6-unicast export vpn -set vrf name LAN1 protocols bgp address-family ipv6-unicast import vpn -set vrf name LAN1 protocols bgp address-family ipv6-unicast rd vpn export '64496:1' -set vrf name LAN1 protocols bgp address-family ipv6-unicast redistribute static -set vrf name LAN1 protocols bgp address-family ipv6-unicast route-target vpn export '64496:1' -set vrf name LAN1 protocols bgp address-family ipv6-unicast route-target vpn import '64496:100 64496:50 64496:2' -set vrf name LAN1 protocols static route 10.0.0.0/24 next-hop 10.1.1.2 -set vrf name LAN1 protocols static route6 2001:db8:0:1::/64 next-hop 2001:db8::1 -set vrf name LAN1 table '101' -set vrf name LAN2 protocols bgp address-family ipv4-unicast export vpn -set vrf name LAN2 protocols bgp address-family ipv4-unicast import vpn -set vrf name LAN2 protocols bgp address-family ipv4-unicast rd vpn export '64496:2' -set vrf name LAN2 protocols bgp address-family ipv4-unicast redistribute static -set vrf name LAN2 protocols bgp address-family ipv4-unicast route-target vpn export '64496:2' -set vrf name LAN2 protocols bgp address-family ipv4-unicast route-target vpn import '64496:100 64496:50 64496:1' -set vrf name LAN2 protocols bgp address-family ipv6-unicast export vpn -set vrf name LAN2 protocols bgp address-family ipv6-unicast import vpn -set vrf name LAN2 protocols bgp address-family ipv6-unicast rd vpn export '64496:2' -set vrf name LAN2 protocols bgp address-family ipv6-unicast redistribute static -set vrf name LAN2 protocols bgp address-family ipv6-unicast route-target vpn export '64496:2' -set vrf name LAN2 protocols bgp address-family ipv6-unicast route-target vpn import '64496:100 64496:50 64496:1' -set vrf name LAN2 protocols static route 172.16.0.0/24 next-hop 172.16.2.2 -set vrf name LAN2 protocols static route6 2001:db8:0:2::/64 next-hop 2001:db8::3 -set vrf name LAN2 table '102' -set vrf name Management protocols bgp address-family ipv4-unicast export vpn -set vrf name Management protocols bgp address-family ipv4-unicast import vpn -set vrf name Management protocols bgp address-family ipv4-unicast rd vpn export '64496:50' -set vrf name Management protocols bgp address-family ipv4-unicast redistribute static -set vrf name Management protocols bgp address-family ipv4-unicast route-target vpn export '64496:50' -set vrf name Management protocols bgp address-family ipv4-unicast route-target vpn import '64496:1 64496:2' -set vrf name Management protocols bgp address-family ipv6-unicast export vpn -set vrf name Management protocols bgp address-family ipv6-unicast import vpn -set vrf name Management protocols bgp address-family ipv6-unicast rd vpn export '64496:50' -set vrf name Management protocols bgp address-family ipv6-unicast redistribute static -set vrf name Management protocols bgp address-family ipv6-unicast route-target vpn export '64496:50' -set vrf name Management protocols bgp address-family ipv6-unicast route-target vpn import '64496:1 64496:2' -set vrf name Management protocols static route 192.168.0.0/24 next-hop 192.168.3.2 -set vrf name Management protocols static route6 2001:db8:0:3::/64 next-hop 2001:db8::5 -set vrf name Management table '103' -``` - -- LAN1 - -```none -set interfaces dummy dum0 address '10.0.0.1/24' -set interfaces dummy dum0 address '2001:db8:0:1::1/64' -set interfaces ethernet eth0 address '10.1.1.2/30' -set interfaces ethernet eth0 address '2001:db8::1/127' -set protocols static route 0.0.0.0/0 next-hop 10.1.1.1 -set protocols static route6 ::/0 next-hop 2001:db8::1 -``` - -- LAN2 - -```none -set interfaces dummy dum0 address '172.16.0.1/24' -set interfaces dummy dum0 address '2001:db8:0:2::1/64' -set interfaces ethernet eth0 hw-id '50:00:00:03:00:00' -set interfaces ethernet eth1 address '172.16.2.2/30' -set interfaces ethernet eth1 address '2001:db8::3/127' -set protocols static route 0.0.0.0/0 next-hop 172.16.2.1 -set protocols static route6 ::/0 next-hop 2001:db8::2 -``` - -- Management - -```none -set interfaces dummy dum0 address '192.168.0.1/24' -set interfaces dummy dum0 address '2001:db8:0:3::1/64' -set interfaces ethernet eth2 address '192.168.3.2/30' -set interfaces ethernet eth2 address '2001:db8::5/127' -set protocols static route 0.0.0.0/0 next-hop 192.168.3.1 -set protocols static route6 ::/0 next-hop 2001:db8::4 -``` - -- ISP - -```none -set interfaces dummy dum0 address '192.0.2.1/24' -set interfaces dummy dum0 address '2001:db8:1::1/48' -set interfaces dummy dum1 address '198.51.100.1/24' -set interfaces dummy dum1 address '2001:db8:2::1/48' -set interfaces dummy dum2 address '203.0.113.1/24' -set interfaces dummy dum2 address '2001:db8:3::1/48' -set interfaces ethernet eth3 address '10.2.2.2/30' -set interfaces ethernet eth3 address '2001:db8::7/127' -set protocols bgp address-family ipv4-unicast redistribute connected -set protocols bgp address-family ipv6-unicast redistribute connected -set protocols bgp system-as '64497' -set protocols bgp neighbor 10.2.2.1 address-family ipv4-unicast default-originate -set protocols bgp neighbor 10.2.2.1 remote-as '64496' -set protocols bgp neighbor 2001:db8::6 address-family ipv6-unicast default-originate -set protocols bgp neighbor 2001:db8::6 remote-as '64496' -set protocols static route 0.0.0.0/0 next-hop 10.2.2.1 -set protocols static route6 ::/0 next-hop 2001:db8::6 -``` - - -## Appendix-B - -### Route-Filtering - -When importing routes using MP-BGP it is possible to filter a subset of them -before are injected in the BGP table. One of the most common case is to use a -route-map with an prefix-list. -- Configuration - -We create a prefix-list first and add all the routes we need to. - -```none -# set both ipv4 and ipv6 policies - -set policy prefix-list LAN2-Internet rule 1 action 'permit' -set policy prefix-list LAN2-Internet rule 1 le '24' -set policy prefix-list LAN2-Internet rule 1 prefix '198.51.0.0/16' -set policy prefix-list LAN2-Internet rule 2 action 'permit' -set policy prefix-list LAN2-Internet rule 2 prefix '192.0.2.0/24' -set policy prefix-list LAN2-Internet rule 3 action 'permit' -set policy prefix-list LAN2-Internet rule 3 prefix '192.168.0.0/24' -set policy prefix-list LAN2-Internet rule 4 action 'permit' -set policy prefix-list LAN2-Internet rule 4 prefix '10.0.0.0/24' - -set policy prefix-list6 LAN2-Internet-v6 rule 1 action 'permit' -set policy prefix-list6 LAN2-Internet-v6 rule 1 prefix '2001:db8:1::/48' -set policy prefix-list6 LAN2-Internet-v6 rule 2 action 'permit' -set policy prefix-list6 LAN2-Internet-v6 rule 2 prefix '2001:db8:2::/48' -set policy prefix-list6 LAN2-Internet-v6 rule 3 action 'permit' -set policy prefix-list6 LAN2-Internet-v6 rule 3 prefix '2001:db8:0:3::/64' -set policy prefix-list6 LAN2-Internet-v6 rule 4 action 'permit' -set policy prefix-list6 LAN2-Internet-v6 rule 4 prefix '2001:db8:0:1::/64' -``` - -Then add a route-map and reference to above prefix. Consider that the actions -taken inside the prefix will MATCH the routes that will be affected by the -actions inside the rules of the route-map. - -```none -set policy route-map LAN2-Internet rule 1 action 'permit' -set policy route-map LAN2-Internet rule 1 match ip address prefix-list 'LAN2-Internet' - -set policy route-map LAN2-Internet-v6 rule 1 action 'permit' -set policy route-map LAN2-Internet-v6 rule 1 match ipv6 address prefix-list 'LAN2-Internet-v6' -``` - -We are using a "white list" approach by allowing only what is necessary. In case -that need to implement a "black list" approach then you will need to change the -action in the route-map for a deny BUT you need to add a rule that permits the -rest due to the implicit deny in the route-map. - -Then we need to attach the policy to the BGP process. This needs to be under -the import statement in the vrf we need to filter. - -```none -set vrf name LAN2 protocols bgp address-family ipv4-unicast route-map vpn import 'LAN2-Internet' -set vrf name LAN2 protocols bgp address-family ipv6-unicast route-map vpn import 'LAN2-Internet-v6' -``` - -- Verification - -```none -# show ip route vrf LAN2 - -B>* 10.0.0.0/24 [20/0] via 10.1.1.2, eth0 (vrf LAN1), weight 1, 00:45:28 -S>* 172.16.0.0/24 [1/0] via 172.16.2.2, eth1, weight 1, 00:45:32 -C>* 172.16.2.0/30 is directly connected, eth1, 00:45:39 -B>* 192.0.2.0/24 [20/0] via 10.2.2.2, eth3 (vrf Internet), weight 1, 00:45:24 -B>* 192.168.0.0/24 [20/0] via 192.168.3.2, eth2 (vrf Managment), weight 1, 00:45:27 -B>* 198.51.100.0/24 [20/0] via 10.2.2.2, eth3 (vrf Internet), weight 1, 00:45:24 - -# show ipv6 route vrf LAN2 - -C>* 2001:db8::2/127 is directly connected, eth1, 00:46:26 -B>* 2001:db8:0:1::/64 [20/0] via 2001:db8::1, eth0 (vrf LAN1), weight 1, 00:46:17 -S>* 2001:db8:0:2::/64 [1/0] via 2001:db8::3, eth1, weight 1, 00:46:21 -B>* 2001:db8:0:3::/64 [20/0] via 2001:db8::5, eth2 (vrf Managment), weight 1, 00:46:16 -B>* 2001:db8:1::/48 [20/0] via fe80::5200:ff:fe02:3, eth3 (vrf Internet), weight 1, 00:46:13 -B>* 2001:db8:2::/48 [20/0] via fe80::5200:ff:fe02:3, eth3 (vrf Internet), weight 1, 00:46:13 -C>* fe80::/64 is directly connected, eth1, 00:46:27 -``` - -As we can see even if both VRF LAN1 and LAN2 has the same import RTs we are able -to select which routes are effectively imported and installed. diff --git a/docs/configexamples/md-ipsec-cisco-policy-based.md b/docs/configexamples/md-ipsec-cisco-policy-based.md deleted file mode 100644 index 7a31601d..00000000 --- a/docs/configexamples/md-ipsec-cisco-policy-based.md +++ /dev/null @@ -1,363 +0,0 @@ ---- -lastproofread: '2025-06-26' ---- - -(examples-ipsec-cisco-policy-based)= - -# Policy-based Site-to-Site VPN IPsec between VyOS and Cisco - -This document is to describe a basic setup using policy-based -site-to-site VPN IPsec. In this example we use VyOS 1.5 and -Cisco IOS. Cisco initiates IPsec connection only if interesting -traffic present. For stable work we recommend configuring an -initiator role on VyOS side. - -## Network Topology - -```{image} /_static/images/cisco-vpn-ipsec.webp -:align: center -:alt: Network Topology Diagram -``` - - -## Prerequirements - -**VyOS:** - -```{eval-rst} -+---------+----------------+ -| WAN IP | 10.0.1.2/30 | -+---------+----------------+ -| LAN1 IP | 192.168.0.1/24 | -+---------+----------------+ -| LAN2 IP | 192.168.1.1/24 | -+---------+----------------+ -``` - -**Cisco:** - -```{eval-rst} -+---------+-----------------+ -| WAN IP | 10.0.2.2/30 | -+---------+-----------------+ -| LAN1 IP | 192.168.10.1/24 | -+---------+-----------------+ -| LAN2 IP | 192.168.11.1/24 | -+---------+-----------------+ -``` - -**IKE parameters:** - -```{eval-rst} -+-------------------+---------+ -| Encryption | AES-256 | -+-------------------+---------+ -| HASH | SHA-1 | -+-------------------+---------+ -| Diff-Helman Group | 14 | -+-------------------+---------+ -| Life-Time | 28800 | -+-------------------+---------+ -| IKE Version | 2 | -+-------------------+---------+ -``` - -**IPsec parameters:** - -```{eval-rst} -+------------+---------+ -| Encryption | AES-256 | -+------------+---------+ -| HASH | SHA-256 | -+------------+---------+ -| Life-Time | 3600 | -+------------+---------+ -| PFS | disable | -+------------+---------+ -``` - -```{eval-rst} -**Traffic Selectors** - 192.168.0.0/24 <==> 192.168.10.0/24 - - 192.168.1.0/24 <==> 192.168.11.0/24 -``` - -**Hosts configuration** - -```{eval-rst} -+--------+--------------+ -| PC1 IP | 192.168.0.2 | -+--------+--------------+ -| PC2 IP | 192.168.1.2 | -+--------+--------------+ -| PC3 IP | 192.168.10.2 | -+--------+--------------+ -| PC4 IP | 192.168.11.2 | -+--------+--------------+ -``` - -## Configuration - -:::{note} -Pfs is disabled in Cisco by default. -::: - -### VyOS - -```none -set interfaces ethernet eth0 address '10.0.1.2/30' -set interfaces ethernet eth1 address '192.168.0.1/24' -set interfaces ethernet eth2 address '192.168.1.1/24' -set protocols static route 0.0.0.0/0 next-hop 10.0.1.1 -set vpn ipsec authentication psk AUTH-PSK id '10.0.1.2' -set vpn ipsec authentication psk AUTH-PSK id '10.0.2.2' -set vpn ipsec authentication psk AUTH-PSK secret 'dGVzdA==' -set vpn ipsec authentication psk AUTH-PSK secret-type 'base64' -set vpn ipsec esp-group ESP-GROUP lifetime '3600' -set vpn ipsec esp-group ESP-GROUP pfs 'disable' -set vpn ipsec esp-group ESP-GROUP proposal 10 encryption 'aes256' -set vpn ipsec esp-group ESP-GROUP proposal 10 hash 'sha256' -set vpn ipsec ike-group IKE-GROUP close-action 'start' -set vpn ipsec ike-group IKE-GROUP dead-peer-detection action 'restart' -set vpn ipsec ike-group IKE-GROUP dead-peer-detection interval '10' -set vpn ipsec ike-group IKE-GROUP key-exchange 'ikev2' -set vpn ipsec ike-group IKE-GROUP lifetime '28800' -set vpn ipsec ike-group IKE-GROUP proposal 10 dh-group '14' -set vpn ipsec ike-group IKE-GROUP proposal 10 encryption 'aes256' -set vpn ipsec ike-group IKE-GROUP proposal 10 hash 'sha1' -set vpn ipsec site-to-site peer CISCO authentication local-id '10.0.1.2' -set vpn ipsec site-to-site peer CISCO authentication mode 'pre-shared-secret' -set vpn ipsec site-to-site peer CISCO authentication remote-id '10.0.2.2' -set vpn ipsec site-to-site peer CISCO connection-type 'initiate' -set vpn ipsec site-to-site peer CISCO default-esp-group 'ESP-GROUP' -set vpn ipsec site-to-site peer CISCO ike-group 'IKE-GROUP' -set vpn ipsec site-to-site peer CISCO local-address '10.0.1.2' -set vpn ipsec site-to-site peer CISCO remote-address '10.0.2.2' -set vpn ipsec site-to-site peer CISCO tunnel 1 local prefix '192.168.0.0/24' -set vpn ipsec site-to-site peer CISCO tunnel 1 remote prefix '192.168.10.0/24' -set vpn ipsec site-to-site peer CISCO tunnel 2 local prefix '192.168.1.0/24' -set vpn ipsec site-to-site peer CISCO tunnel 2 remote prefix '192.168.11.0/24' -``` - - -### Cisco - -```none -crypto ikev2 proposal aes-cbc-256-proposal - encryption aes-cbc-256 - integrity sha1 - group 14 -! -crypto ikev2 policy policy1 - match address local 10.0.2.2 - proposal aes-cbc-256-proposal -! -crypto ikev2 keyring keys - peer VyOS - address 10.0.1.2 - pre-shared-key local test - pre-shared-key remote test -! -crypto ikev2 profile IKEv2-profile - match identity remote address 10.0.1.2 255.255.255.255 - authentication remote pre-share - authentication local pre-share - keyring local keys - lifetime 28800 -! -crypto ipsec transform-set TS esp-aes 256 esp-sha256-hmac - mode tunnel -! -crypto map IPSEC-map 10 ipsec-isakmp - set peer 10.0.1.2 - set security-association lifetime seconds 3600 - set transform-set TS - set ikev2-profile IKEv2-profile - match address cryptoacl -! -interface GigabitEthernet0/0 - ip address 10.0.2.2 255.255.255.252 - crypto map IPSEC-map -! -interface GigabitEthernet0/1 - ip address 192.168.10.1 255.255.255.0 -! -interface GigabitEthernet0/2 - ip address 192.168.11.1 255.255.255.0 -! -ip route 0.0.0.0 0.0.0.0 10.0.2.1 -! -ip access-list extended cryptoacl - permit ip 192.168.10.0 0.0.0.255 192.168.0.0 0.0.0.255 - permit ip 192.168.11.0 0.0.0.255 192.168.1.0 0.0.0.255 -``` - - -## Monitoring - -### Monitoring on VyOS side - -IKE SAs: - -```none -vyos@vyos:~$ show vpn ike sa -Peer ID / IP Local ID / IP ------------- ------------- -10.0.2.2 10.0.2.2 10.0.1.2 10.0.1.2 - - State IKEVer Encrypt Hash D-H Group NAT-T A-Time L-Time - ----- ------ ------- ---- --------- ----- ------ ------ - up IKEv2 AES_CBC_256 HMAC_SHA1_96 MODP_2048 no 304 26528 -``` - -IPsec SAs: - -```none -vyos@vyos:~$ show vpn ipsec sa -Connection State Uptime Bytes In/Out Packets In/Out Remote address Remote ID Proposal --------------- ------- -------- -------------- ---------------- ---------------- ----------- ----------------------------- -CISCO-tunnel-1 up 6m6s 0B/0B 0/0 10.0.2.2 10.0.2.2 AES_CBC_256/HMAC_SHA2_256_128 -CISCO-tunnel-2 up 6m6s 0B/0B 0/0 10.0.2.2 10.0.2.2 AES_CBC_256/HMAC_SHA2_256_128 -``` - - -### Monitoring on Cisco side - -IKE SAs: - -```none -Cisco#show crypto ikev2 sa - IPv4 Crypto IKEv2 SA - -Tunnel-id Local Remote fvrf/ivrf Status -1 10.0.2.2/4500 10.0.1.2/4500 none/none READY - Encr: AES-CBC, keysize: 256, PRF: SHA1, Hash: SHA96, DH Grp:14, Auth sign: PSK, Auth verify: PSK - Life/Active Time: 28800/471 sec - - IPv6 Crypto IKEv2 SA -``` - -IPsec SAs: - -```none - Cisco#show crypto ipsec sa - -interface: GigabitEthernet0/0 - Crypto map tag: IPSEC-map, local addr 10.0.2.2 - - protected vrf: (none) - local ident (addr/mask/prot/port): (192.168.11.0/255.255.255.0/0/0) - remote ident (addr/mask/prot/port): (192.168.1.0/255.255.255.0/0/0) - current_peer 10.0.1.2 port 4500 - PERMIT, flags={origin_is_acl,} - #pkts encaps: 0, #pkts encrypt: 0, #pkts digest: 0 - #pkts decaps: 0, #pkts decrypt: 0, #pkts verify: 0 - #pkts compressed: 0, #pkts decompressed: 0 - #pkts not compressed: 0, #pkts compr. failed: 0 - #pkts not decompressed: 0, #pkts decompress failed: 0 - #send errors 0, #recv errors 0 - - local crypto endpt.: 10.0.2.2, remote crypto endpt.: 10.0.1.2 - plaintext mtu 1438, path mtu 1500, ip mtu 1500, ip mtu idb GigabitEthernet0/0 - current outbound spi: 0xC81F83DA(3357508570) - PFS (Y/N): N, DH group: none - - inbound esp sas: - spi: 0x8C63C51E(2355348766) - transform: esp-256-aes esp-sha256-hmac , - in use settings ={Tunnel, } - conn id: 23, flow_id: SW:23, sibling_flags 80000040, crypto map: IPSEC-map - sa timing: remaining key lifetime (k/sec): (4231729/3585) - IV size: 16 bytes - replay detection support: Y - Status: ACTIVE(ACTIVE) - - inbound ah sas: - - inbound pcp sas: - - outbound esp sas: - spi: 0xC81F83DA(3357508570) - transform: esp-256-aes esp-sha256-hmac , - in use settings ={Tunnel, } - conn id: 24, flow_id: SW:24, sibling_flags 80000040, crypto map: IPSEC-map - sa timing: remaining key lifetime (k/sec): (4231729/3585) - IV size: 16 bytes - replay detection support: Y - Status: ACTIVE(ACTIVE) - - outbound ah sas: - - outbound pcp sas: - - protected vrf: (none) - local ident (addr/mask/prot/port): (192.168.10.0/255.255.255.0/0/0) - remote ident (addr/mask/prot/port): (192.168.0.0/255.255.255.0/0/0) - current_peer 10.0.1.2 port 4500 - PERMIT, flags={origin_is_acl,} - #pkts encaps: 0, #pkts encrypt: 0, #pkts digest: 0 - #pkts decaps: 0, #pkts decrypt: 0, #pkts verify: 0 - #pkts compressed: 0, #pkts decompressed: 0 - #pkts not compressed: 0, #pkts compr. failed: 0 - #pkts not decompressed: 0, #pkts decompress failed: 0 - #send errors 0, #recv errors 0 - - local crypto endpt.: 10.0.2.2, remote crypto endpt.: 10.0.1.2 - plaintext mtu 1438, path mtu 1500, ip mtu 1500, ip mtu idb GigabitEthernet0/0 - current outbound spi: 0xC40C7A20(3289152032) - PFS (Y/N): N, DH group: none - - inbound esp sas: - spi: 0x2948B6CB(692631243) - transform: esp-256-aes esp-sha256-hmac , - in use settings ={Tunnel, } - conn id: 21, flow_id: SW:21, sibling_flags 80000040, crypto map: IPSEC-map - sa timing: remaining key lifetime (k/sec): (4194891/3581) - IV size: 16 bytes - replay detection support: Y - Status: ACTIVE(ACTIVE) - - inbound ah sas: - - inbound pcp sas: - - outbound esp sas: - spi: 0xC40C7A20(3289152032) - transform: esp-256-aes esp-sha256-hmac , - in use settings ={Tunnel, } - conn id: 22, flow_id: SW:22, sibling_flags 80000040, crypto map: IPSEC-map - sa timing: remaining key lifetime (k/sec): (4194891/3581) - IV size: 16 bytes - replay detection support: Y - Status: ACTIVE(ACTIVE) - - outbound ah sas: - - outbound pcp sas: -``` - - -### Checking Connectivity - -ICMP packets from PC1 to PC3. - -```none -PC1> ping 192.168.10.2 - -84 bytes from 192.168.10.2 icmp_seq=1 ttl=62 time=8.479 ms -84 bytes from 192.168.10.2 icmp_seq=2 ttl=62 time=3.344 ms -84 bytes from 192.168.10.2 icmp_seq=3 ttl=62 time=3.139 ms -84 bytes from 192.168.10.2 icmp_seq=4 ttl=62 time=3.176 ms -84 bytes from 192.168.10.2 icmp_seq=5 ttl=62 time=3.978 ms -``` - -ICMP packets from PC2 to PC4. - -```none -PC2> ping 192.168.11.2 - -84 bytes from 192.168.11.2 icmp_seq=1 ttl=62 time=9.687 ms -84 bytes from 192.168.11.2 icmp_seq=2 ttl=62 time=3.286 ms -84 bytes from 192.168.11.2 icmp_seq=3 ttl=62 time=2.972 ms -``` diff --git a/docs/configexamples/md-ipsec-cisco-route-based.md b/docs/configexamples/md-ipsec-cisco-route-based.md deleted file mode 100644 index 40a3985b..00000000 --- a/docs/configexamples/md-ipsec-cisco-route-based.md +++ /dev/null @@ -1,406 +0,0 @@ ---- -lastproofread: '2025-06-26' ---- - -(examples-ipsec-cisco-route-based)= - -# Route-based Site-to-Site VPN IPsec between VyOS and Cisco - -This document is to describe a basic setup using route-based -site-to-site VPN IPsec. In this example we use VyOS 1.5 and -Cisco IOS. Cisco initiates IPsec connection only if interesting -traffic present. For stable work we recommend configuring an -initiator role on VyOS side. OSPF is selected as routing protocol -inside the tunnel. - -## Network Topology - -```{eval-rst} -.. image:: /_static/images/cisco-vpn-ipsec.webp - :align: center - :alt: Network Topology Diagram -``` - - -## Prerequirements - -**VyOS:** - -```{eval-rst} -+---------+----------------+ -| WAN IP | 10.0.1.2/30 | -+---------+----------------+ -| LAN1 IP | 192.168.0.1/24 | -+---------+----------------+ -| LAN2 IP | 192.168.1.1/24 | -+---------+----------------+ -``` - -**Cisco:** - -```{eval-rst} -+---------+-----------------+ -| WAN IP | 10.0.2.2/30 | -+---------+-----------------+ -| LAN1 IP | 192.168.10.1/24 | -+---------+-----------------+ -| LAN2 IP | 192.168.11.1/24 | -+---------+-----------------+ -``` - -**IKE parameters:** - -```{eval-rst} -+-------------------+---------+ -| Encryption | AES-128 | -+-------------------+---------+ -| HASH | SHA-1 | -+-------------------+---------+ -| Diff-Helman Group | 14 | -+-------------------+---------+ -| Life-Time | 28800 | -+-------------------+---------+ -| IKE Version | 1 | -+-------------------+---------+ -``` - -**IPsec parameters:** - -```{eval-rst} -+------------+---------+ -| Encryption | AES-256 | -+------------+---------+ -| HASH | SHA-256 | -+------------+---------+ -| Life-Time | 3600 | -+------------+---------+ -| PFS | disable | -+------------+---------+ -``` - -**Hosts configuration** - -```{eval-rst} -+--------+--------------+ -| PC1 IP | 192.168.0.2 | -+--------+--------------+ -| PC2 IP | 192.168.1.2 | -+--------+--------------+ -| PC3 IP | 192.168.10.2 | -+--------+--------------+ -| PC4 IP | 192.168.11.2 | -+--------+--------------+ -``` - -## Configuration - -:::{note} -Pfs is disabled in Cisco by default. -::: - -### VyOS - -```none -set interfaces ethernet eth0 address '10.0.1.2/30' -set interfaces ethernet eth1 address '192.168.0.1/24' -set interfaces ethernet eth2 address '192.168.1.1/24' -set interfaces vti vti1 address '10.100.100.1/30' -set interfaces vti vti1 mtu '1438' -set protocols ospf area 0 network '10.100.100.0/30' -set protocols ospf area 0 network '192.168.0.0/24' -set protocols ospf area 0 network '192.168.1.0/24' -set protocols ospf interface eth1 passive -set protocols ospf interface eth2 passive -set protocols ospf interface vti1 network 'point-to-point' -set protocols ospf parameters router-id '2.2.2.2' -set protocols static route 0.0.0.0/0 next-hop 10.0.1.1 -set vpn ipsec authentication psk AUTH-PSK id '10.0.1.2' -set vpn ipsec authentication psk AUTH-PSK id '10.0.2.2' -set vpn ipsec authentication psk AUTH-PSK secret 'dGVzdA==' -set vpn ipsec authentication psk AUTH-PSK secret-type 'base64' -set vpn ipsec esp-group ESP-GROUP lifetime '3600' -set vpn ipsec esp-group ESP-GROUP pfs 'disable' -set vpn ipsec esp-group ESP-GROUP proposal 10 encryption 'aes256' -set vpn ipsec esp-group ESP-GROUP proposal 10 hash 'sha256' -set vpn ipsec ike-group IKE-GROUP close-action 'start' -set vpn ipsec ike-group IKE-GROUP dead-peer-detection action 'restart' -set vpn ipsec ike-group IKE-GROUP dead-peer-detection interval '10' -set vpn ipsec ike-group IKE-GROUP dead-peer-detection timeout '30' -set vpn ipsec ike-group IKE-GROUP key-exchange 'ikev1' -set vpn ipsec ike-group IKE-GROUP lifetime '28800' -set vpn ipsec ike-group IKE-GROUP proposal 10 dh-group '14' -set vpn ipsec ike-group IKE-GROUP proposal 10 encryption 'aes128' -set vpn ipsec ike-group IKE-GROUP proposal 10 hash 'sha1' -set vpn ipsec options disable-route-autoinstall -set vpn ipsec site-to-site peer CISCO authentication local-id '10.0.1.2' -set vpn ipsec site-to-site peer CISCO authentication mode 'pre-shared-secret' -set vpn ipsec site-to-site peer CISCO authentication remote-id '10.0.2.2' -set vpn ipsec site-to-site peer CISCO connection-type 'initiate' -set vpn ipsec site-to-site peer CISCO default-esp-group 'ESP-GROUP' -set vpn ipsec site-to-site peer CISCO ike-group 'IKE-GROUP' -set vpn ipsec site-to-site peer CISCO local-address '10.0.1.2' -set vpn ipsec site-to-site peer CISCO remote-address '10.0.2.2' -set vpn ipsec site-to-site peer CISCO vti bind 'vti1' -``` - - -### Cisco - -```none -crypto isakmp policy 10 - encr aes - authentication pre-share - group 14 - lifetime 28800 -crypto isakmp key test address 10.0.1.2 -! -! -crypto ipsec transform-set TS esp-aes 256 esp-sha256-hmac - mode transport -! -crypto ipsec profile IPsec-profile - set transform-set TS -! -! -! -! -! -! -! -interface Loopback0 - ip address 1.1.1.1 255.255.255.255 -! -interface Tunnel10 - ip address 10.100.100.2 255.255.255.252 - ip ospf network point-to-point - tunnel source GigabitEthernet0/0 - tunnel mode ipsec ipv4 - tunnel destination 10.0.1.2 - tunnel protection ipsec profile IPsec-profile -! -interface GigabitEthernet0/0 - ip address 10.0.2.2 255.255.255.252 - duplex auto - speed auto - media-type rj45 -! -interface GigabitEthernet0/1 - ip address 192.168.10.1 255.255.255.0 - duplex auto - speed auto - media-type rj45 -! -interface GigabitEthernet0/2 - ip address 192.168.11.1 255.255.255.0 - duplex auto - speed auto - media-type rj45 -! -router ospf 1 - router-id 1.1.1.1 - passive-interface GigabitEthernet0/1 - passive-interface GigabitEthernet0/2 - network 10.100.100.0 0.0.0.3 area 0 - network 192.168.10.0 0.0.0.255 area 0 - network 192.168.11.0 0.0.0.255 area 0 -! -ip route 0.0.0.0 0.0.0.0 10.0.2.1 -``` - - -## Monitoring - -### Monitoring on VyOS side - -IKE SAs: - -```none -vyos@vyos:~$ show vpn ike sa -Peer ID / IP Local ID / IP ------------- ------------- -10.0.2.2 10.0.2.2 10.0.1.2 10.0.1.2 - - State IKEVer Encrypt Hash D-H Group NAT-T A-Time L-Time - ----- ------ ------- ---- --------- ----- ------ ------ - up IKEv1 AES_CBC_128 HMAC_SHA1_96 MODP_2048 no 8175 18439 -``` - -IPsec SAs: - -```none -vyos@vyos:~$ show vpn ipsec sa -Connection State Uptime Bytes In/Out Packets In/Out Remote address Remote ID Proposal ------------- ------- -------- -------------- ---------------- ---------------- ----------- ----------------------------- -CISCO-vti up 34m59s 17K/14K 224/213 10.0.2.2 10.0.2.2 AES_CBC_256/HMAC_SHA2_256_128 -``` - -OSPF Neighbor Status: - -```none -vyos@vyos:~$ show ip ospf neighbor - -Neighbor ID Pri State Up Time Dead Time Address Interface RXmtL RqstL DBsmL -1.1.1.1 1 Full/- 1h29m37s 39.317s 10.100.100.2 vti1:10.100.100.1 0 0 0 -``` - -Routing Table: - -```none -vyos@vyos:~$ show ip route -Codes: K - kernel route, C - connected, L - local, S - static, - R - RIP, O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, - T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, - f - OpenFabric, t - Table-Direct, - > - selected route, * - FIB route, q - queued, r - rejected, b - backup - t - trapped, o - offload failure -S>* 0.0.0.0/0 [1/0] via 10.0.1.1, eth0, weight 1, 00:07:54 -C>* 10.0.1.0/30 is directly connected, eth0, weight 1, 00:07:59 -L>* 10.0.1.2/32 is directly connected, eth0, weight 1, 00:07:59 -O 10.100.100.0/30 [110/1] is directly connected, vti1, weight 1, 00:07:50 -C>* 10.100.100.0/30 is directly connected, vti1, weight 1, 00:07:50 -L>* 10.100.100.1/32 is directly connected, vti1, weight 1, 00:07:50 -O 192.168.0.0/24 [110/1] is directly connected, eth1, weight 1, 00:07:54 -C>* 192.168.0.0/24 is directly connected, eth1, weight 1, 00:07:59 -L>* 192.168.0.1/32 is directly connected, eth1, weight 1, 00:07:59 -O 192.168.1.0/24 [110/1] is directly connected, eth2, weight 1, 00:07:54 -C>* 192.168.1.0/24 is directly connected, eth2, weight 1, 00:07:59 -L>* 192.168.1.1/32 is directly connected, eth2, weight 1, 00:07:59 -O>* 192.168.10.0/24 [110/2] via 10.100.100.2, vti1, weight 1, 00:07:34 -O>* 192.168.11.0/24 [110/2] via 10.100.100.2, vti1, weight 1, 00:07:34 -``` - - -### Monitoring on Cisco side - -IKE SAs: - -```none -Cisco#show crypto isakmp sa -IPv4 Crypto ISAKMP SA -dst src state conn-id status -10.0.1.2 10.0.2.2 QM_IDLE 1002 ACTIVE - -IPv6 Crypto ISAKMP SA -``` - -IPsec SAs: - -```none -Cisco#show crypto ipsec sa - -interface: Tunnel10 - Crypto map tag: Tunnel10-head-0, local addr 10.0.2.2 - - protected vrf: (none) - local ident (addr/mask/prot/port): (0.0.0.0/0.0.0.0/0/0) - remote ident (addr/mask/prot/port): (0.0.0.0/0.0.0.0/0/0) - current_peer 10.0.1.2 port 500 - PERMIT, flags={origin_is_acl,} - #pkts encaps: 1295, #pkts encrypt: 1295, #pkts digest: 1295 - #pkts decaps: 1238, #pkts decrypt: 1238, #pkts verify: 1238 - #pkts compressed: 0, #pkts decompressed: 0 - #pkts not compressed: 0, #pkts compr. failed: 0 - #pkts not decompressed: 0, #pkts decompress failed: 0 - #send errors 0, #recv errors 0 - - local crypto endpt.: 10.0.2.2, remote crypto endpt.: 10.0.1.2 - plaintext mtu 1438, path mtu 1500, ip mtu 1500, ip mtu idb GigabitEthernet0/0 - current outbound spi: 0xC3E9B307(3286872839) - PFS (Y/N): N, DH group: none - - inbound esp sas: - spi: 0x2740C328(658555688) - transform: esp-256-aes esp-sha256-hmac , - in use settings ={Tunnel, } - conn id: 7, flow_id: SW:7, sibling_flags 80000040, crypto map: Tunnel10-head-0 - sa timing: remaining key lifetime (k/sec): (4173824/1401) - IV size: 16 bytes - replay detection support: Y - Status: ACTIVE(ACTIVE) - - inbound ah sas: - - inbound pcp sas: - - outbound esp sas: - spi: 0xC3E9B307(3286872839) - transform: esp-256-aes esp-sha256-hmac , - in use settings ={Tunnel, } - conn id: 8, flow_id: SW:8, sibling_flags 80000040, crypto map: Tunnel10-head-0 - sa timing: remaining key lifetime (k/sec): (4173819/1401) - IV size: 16 bytes - replay detection support: Y - Status: ACTIVE(ACTIVE) - - outbound ah sas: - - outbound pcp sas: -``` - -OSPF Neighbor Status: - -```none -Cisco# show ip ospf neighbor - -Neighbor ID Pri State Dead Time Address Interface -2.2.2.2 0 FULL/ - 00:00:35 10.100.100.1 Tunnel10 -``` - -Routing Table: - -```none -Cisco#show ip route -Codes: L - local, C - connected, S - static, R - RIP, M - mobile, B - BGP - D - EIGRP, EX - EIGRP external, O - OSPF, IA - OSPF inter area - N1 - OSPF NSSA external type 1, N2 - OSPF NSSA external type 2 - E1 - OSPF external type 1, E2 - OSPF external type 2 - i - IS-IS, su - IS-IS summary, L1 - IS-IS level-1, L2 - IS-IS level-2 - ia - IS-IS inter area, * - candidate default, U - per-user static route - o - ODR, P - periodic downloaded static route, H - NHRP, l - LISP - a - application route - + - replicated route, % - next hop override, p - overrides from PfR - -Gateway of last resort is 10.0.2.1 to network 0.0.0.0 - -S* 0.0.0.0/0 [1/0] via 10.0.2.1 - 1.0.0.0/32 is subnetted, 1 subnets -C 1.1.1.1 is directly connected, Loopback0 - 10.0.0.0/8 is variably subnetted, 4 subnets, 2 masks -C 10.0.2.0/30 is directly connected, GigabitEthernet0/0 -L 10.0.2.2/32 is directly connected, GigabitEthernet0/0 -C 10.100.100.0/30 is directly connected, Tunnel10 -L 10.100.100.2/32 is directly connected, Tunnel10 -O 192.168.0.0/24 [110/1001] via 10.100.100.1, 00:09:36, Tunnel10 -O 192.168.1.0/24 [110/1001] via 10.100.100.1, 00:09:36, Tunnel10 - 192.168.10.0/24 is variably subnetted, 2 subnets, 2 masks -C 192.168.10.0/24 is directly connected, GigabitEthernet0/1 -L 192.168.10.1/32 is directly connected, GigabitEthernet0/1 - 192.168.11.0/24 is variably subnetted, 2 subnets, 2 masks -C 192.168.11.0/24 is directly connected, GigabitEthernet0/2 -L 192.168.11.1/32 is directly connected, GigabitEthernet0/2 -``` - - -### Checking Connectivity - -ICMP packets from PC1 to PC3. - -```none -PC1> ping 192.168.10.2 - -84 bytes from 192.168.10.2 icmp_seq=1 ttl=62 time=8.479 ms -84 bytes from 192.168.10.2 icmp_seq=2 ttl=62 time=3.344 ms -84 bytes from 192.168.10.2 icmp_seq=3 ttl=62 time=3.139 ms -84 bytes from 192.168.10.2 icmp_seq=4 ttl=62 time=3.176 ms -84 bytes from 192.168.10.2 icmp_seq=5 ttl=62 time=3.978 ms -``` - -ICMP packets from PC2 to PC4. - -```none -PC2> ping 192.168.11.2 - -84 bytes from 192.168.11.2 icmp_seq=1 ttl=62 time=9.687 ms -84 bytes from 192.168.11.2 icmp_seq=2 ttl=62 time=3.286 ms -84 bytes from 192.168.11.2 icmp_seq=3 ttl=62 time=2.972 ms -``` diff --git a/docs/configexamples/md-ipsec-pa-route-based.md b/docs/configexamples/md-ipsec-pa-route-based.md deleted file mode 100644 index c4a9e06c..00000000 --- a/docs/configexamples/md-ipsec-pa-route-based.md +++ /dev/null @@ -1,412 +0,0 @@ ---- -lastproofread: '2025-06-26' ---- - -(examples-ipsec-pa-route-based)= - -# Route-based Site-to-Site VPN IPsec between VyOS and Palo Alto - -This document is to describe a basic setup using route-based -site-to-site VPN IPsec. In this example we use VyOS 1.5 and -PA 11.0.0. OSPF is selected as routing protocol inside the -tunnel. - -Since this example focuses on IPsec configuration it does not -include firewall configuration. - -## Network Topology - -```{image} /_static/images/ipsec-vyos-pa.webp -:align: center -:alt: Network Topology Diagram -``` - - -## Prerequirements - -**VyOS:** - -```{eval-rst} -+---------+----------------+ -| WAN IP | 10.0.1.2/30 | -+---------+----------------+ -| LAN1 IP | 192.168.0.1/24 | -+---------+----------------+ -| LAN2 IP | 192.168.1.1/24 | -+---------+----------------+ -``` - -**Palo Alto:** - -```{eval-rst} -+---------+-----------------+ -| WAN IP | 10.0.2.2/30 | -+---------+-----------------+ -| LAN1 IP | 192.168.10.1/24 | -+---------+-----------------+ -| LAN2 IP | 192.168.11.1/24 | -+---------+-----------------+ -``` - -**IKE parameters:** - -```{eval-rst} -+-------------------+---------+ -| Encryption | AES-128 | -+-------------------+---------+ -| HASH | SHA-1 | -+-------------------+---------+ -| Diff-Helman Group | 14 | -+-------------------+---------+ -| Life-Time | 28800 | -+-------------------+---------+ -| IKE Version | 1 | -+-------------------+---------+ -``` - -**IPsec parameters:** - -```{eval-rst} -+------------+---------+ -| Encryption | AES-256 | -+------------+---------+ -| HASH | SHA-256 | -+------------+---------+ -| Life-Time | 3600 | -+------------+---------+ -| PFS | disable | -+------------+---------+ -``` - -**Hosts configuration** - -```{eval-rst} -+--------+--------------+ -| PC1 IP | 192.168.0.2 | -+--------+--------------+ -| PC2 IP | 192.168.1.2 | -+--------+--------------+ -| PC3 IP | 192.168.10.2 | -+--------+--------------+ -| PC4 IP | 192.168.11.2 | -+--------+--------------+ -``` - -## Configuration - -### VyOS - -```none -set interfaces ethernet eth0 address '10.0.1.2/30' -set interfaces ethernet eth1 address '192.168.0.1/24' -set interfaces ethernet eth2 address '192.168.1.1/24' -set interfaces vti vti1 address '10.100.100.1/30' -set interfaces vti vti1 mtu '1438' -set protocols ospf area 0 network '10.100.100.0/30' -set protocols ospf area 0 network '192.168.0.0/24' -set protocols ospf area 0 network '192.168.1.0/24' -set protocols ospf interface eth1 passive -set protocols ospf interface eth2 passive -set protocols ospf interface vti1 network 'point-to-point' -set protocols ospf parameters router-id '2.2.2.2' -set protocols static route 0.0.0.0/0 next-hop 10.0.1.1 -set vpn ipsec authentication psk AUTH-PSK id '10.0.1.2' -set vpn ipsec authentication psk AUTH-PSK id '10.0.2.2' -set vpn ipsec authentication psk AUTH-PSK secret 'dGVzdA==' -set vpn ipsec authentication psk AUTH-PSK secret-type 'base64' -set vpn ipsec esp-group ESP-GROUP lifetime '3600' -set vpn ipsec esp-group ESP-GROUP pfs 'disable' -set vpn ipsec esp-group ESP-GROUP proposal 10 encryption 'aes256' -set vpn ipsec esp-group ESP-GROUP proposal 10 hash 'sha256' -set vpn ipsec ike-group IKE-GROUP close-action 'start' -set vpn ipsec ike-group IKE-GROUP dead-peer-detection action 'restart' -set vpn ipsec ike-group IKE-GROUP dead-peer-detection interval '10' -set vpn ipsec ike-group IKE-GROUP dead-peer-detection timeout '30' -set vpn ipsec ike-group IKE-GROUP key-exchange 'ikev1' -set vpn ipsec ike-group IKE-GROUP lifetime '28800' -set vpn ipsec ike-group IKE-GROUP proposal 10 dh-group '14' -set vpn ipsec ike-group IKE-GROUP proposal 10 encryption 'aes128' -set vpn ipsec ike-group IKE-GROUP proposal 10 hash 'sha1' -set vpn ipsec options disable-route-autoinstall -set vpn ipsec site-to-site peer PA authentication local-id '10.0.1.2' -set vpn ipsec site-to-site peer PA authentication mode 'pre-shared-secret' -set vpn ipsec site-to-site peer PA authentication remote-id '10.0.2.2' -set vpn ipsec site-to-site peer PA connection-type 'initiate' -set vpn ipsec site-to-site peer PA default-esp-group 'ESP-GROUP' -set vpn ipsec site-to-site peer PA ike-group 'IKE-GROUP' -set vpn ipsec site-to-site peer PA local-address '10.0.1.2' -set vpn ipsec site-to-site peer PA remote-address '10.0.2.2' -set vpn ipsec site-to-site peer PA vti bind 'vti1' -``` - - -### Palo Alto - -```{eval-rst} -GUI Configuration: - Network -> Network Profiles -> IKE Crypto - - .. image:: /_static/images/PA-IKE-group.webp - :align: center - - Network -> Network Profiles -> IKE Gateways - - .. image:: /_static/images/PA-IKE-GW-1.webp - :align: center - - .. image:: /_static/images/PA-IKE-GW-2.webp - :align: center - - Network -> Network Profiles -> IPSec Crypto - - .. image:: /_static/images/PA-ESP-group.webp - :align: center - - Network -> Interfaces - - .. image:: /_static/images/PA-tunnel-1.webp - :align: center - - .. image:: /_static/images/PA-tunnel-2.webp - :align: center - - .. image:: /_static/images/PA-tunnel-3.webp - :align: center - - Network -> IPSec Tunnels - - .. image:: /_static/images/PA-IPsec-tunnel.webp - :align: center -``` -CLI configuration with OSPF: -```none -set network interface ethernet ethernet1/1 layer3 ip 10.0.2.2/30 -set network interface ethernet ethernet1/1 layer3 interface-management-profile Allow -set network interface ethernet ethernet1/2 layer3 ip 192.168.10.1/24 -set network interface ethernet ethernet1/1 layer3 interface-management-profile Allow -set network interface ethernet ethernet1/3 layer3 ip 192.168.11.1/24 -set network interface ethernet ethernet1/1 layer3 interface-management-profile Allow -set network interface tunnel units tunnel.1 ip 10.100.100.2/30 -set network interface tunnel units tunnel.1 interface-management-profile Allow -set network interface tunnel units tunnel.1 mtu 1438 -set network profiles interface-management-profile Allow ping yes -set network ike crypto-profiles ike-crypto-profiles IKE-GROUP hash sha1 -set network ike crypto-profiles ike-crypto-profiles IKE-GROUP dh-group group14 -set network ike crypto-profiles ike-crypto-profiles IKE-GROUP encryption aes-128-cbc -set network ike crypto-profiles ike-crypto-profiles IKE-GROUP lifetime seconds 28800 -set network ike crypto-profiles ipsec-crypto-profiles ESP-GROUP esp authentication sha256 -set network ike crypto-profiles ipsec-crypto-profiles ESP-GROUP esp encryption aes-256-cbc -set network ike crypto-profiles ipsec-crypto-profiles ESP-GROUP lifetime seconds 3600 -set network ike crypto-profiles ipsec-crypto-profiles ESP-GROUP dh-group no-pfs -set network ike gateway VyOS authentication pre-shared-key key test -set network ike gateway VyOS protocol ikev1 dpd enable yes -set network ike gateway VyOS protocol ikev1 exchange-mode main -set network ike gateway VyOS protocol ikev1 ike-crypto-profile IKE-GROUP -set network ike gateway VyOS protocol ikev2 dpd enable yes -set network ike gateway VyOS protocol version ikev1 -set network ike gateway VyOS protocol-common nat-traversal enable yes -set network ike gateway VyOS protocol-common fragmentation enable no -set network ike gateway VyOS protocol-common passive-mode yes -set network ike gateway VyOS local-address interface ethernet1/1 -set network ike gateway VyOS peer-address ip 10.0.1.2 -set network ike gateway VyOS local-id id 10.0.2.2 -set network ike gateway VyOS local-id type ipaddr -set network ike gateway VyOS peer-id id 10.0.1.2 -set network ike gateway VyOS peer-id type ipaddr -set network tunnel ipsec VyOS-tunnel auto-key ike-gateway VyOS -set network tunnel ipsec VyOS-tunnel auto-key ipsec-crypto-profile ESP-GROUP -set network tunnel ipsec VyOS-tunnel tunnel-monitor enable no -set network tunnel ipsec VyOS-tunnel tunnel-interface tunnel.1 -set network tunnel ipsec VyOS-tunnel anti-replay no -set network virtual-router default protocol ospf enable yes -set network virtual-router default protocol ospf area 0.0.0.0 type normal -set network virtual-router default protocol ospf area 0.0.0.0 interface tunnel.1 enable yes -set network virtual-router default protocol ospf area 0.0.0.0 interface tunnel.1 passive no -set network virtual-router default protocol ospf area 0.0.0.0 interface tunnel.1 link-type p2p -set network virtual-router default protocol ospf area 0.0.0.0 interface ethernet1/2 enable yes -set network virtual-router default protocol ospf area 0.0.0.0 interface ethernet1/2 passive yes -set network virtual-router default protocol ospf area 0.0.0.0 interface ethernet1/2 link-type broadcast -set network virtual-router default protocol ospf area 0.0.0.0 interface ethernet1/3 enable yes -set network virtual-router default protocol ospf area 0.0.0.0 interface ethernet1/3 passive yes -set network virtual-router default protocol ospf area 0.0.0.0 interface ethernet1/3 link-type broadcast -set network virtual-router default protocol ospf router-id 1.1.1.1 -set network virtual-router default interface [ ethernet1/1 ethernet1/2 ethernet1/3 tunnel.1 ] -``` - -## Monitoring -### Monitoring on VyOS side - -IKE SAs: - -```none -vyos@vyos:~$ show vpn ike sa -Peer ID / IP Local ID / IP ------------- ------------- -10.0.2.2 10.0.2.2 10.0.1.2 10.0.1.2 - - State IKEVer Encrypt Hash D-H Group NAT-T A-Time L-Time - ----- ------ ------- ---- --------- ----- ------ ------ - up IKEv1 AES_CBC_128 HMAC_SHA1_96 MODP_2048 no 1372 25802 -``` - -IPsec SAs: - -```none -vyos@vyos:~$ show vpn ipsec sa -Connection State Uptime Bytes In/Out Packets In/Out Remote address Remote ID Proposal ------------- ------- -------- -------------- ---------------- ---------------- ----------- ----------------------------- -PA-vti up 23m27s 9K/10K 149/151 10.0.2.2 10.0.2.2 AES_CBC_256/HMAC_SHA2_256_128 -``` - -OSPF Neighbor Status: - -```none -vyos@vyos:~$ show ip ospf neighbor - -Neighbor ID Pri State Up Time Dead Time Address Interface RXmtL RqstL DBsmL -1.1.1.1 1 Full/- 23m56s 37.948s 10.100.100.2 vti1:10.100.100.1 0 0 0 -``` - -Routing Table: - -```none -vyos@vyos:~$ show ip route -Codes: K - kernel route, C - connected, L - local, S - static, - R - RIP, O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, - T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, - f - OpenFabric, t - Table-Direct, - > - selected route, * - FIB route, q - queued, r - rejected, b - backup - t - trapped, o - offload failure - -S>* 0.0.0.0/0 [1/0] via 10.0.1.1, eth0, weight 1, 00:27:30 -C>* 10.0.1.0/30 is directly connected, eth0, weight 1, 00:27:34 -L>* 10.0.1.2/32 is directly connected, eth0, weight 1, 00:27:34 -O 10.100.100.0/30 [110/1] is directly connected, vti1, weight 1, 00:24:34 -C>* 10.100.100.0/30 is directly connected, vti1, weight 1, 00:24:34 -L>* 10.100.100.1/32 is directly connected, vti1, weight 1, 00:24:34 -O 192.168.0.0/24 [110/1] is directly connected, eth1, weight 1, 00:27:29 -C>* 192.168.0.0/24 is directly connected, eth1, weight 1, 00:27:34 -L>* 192.168.0.1/32 is directly connected, eth1, weight 1, 00:27:34 -O 192.168.1.0/24 [110/1] is directly connected, eth2, weight 1, 00:27:29 -C>* 192.168.1.0/24 is directly connected, eth2, weight 1, 00:27:34 -L>* 192.168.1.1/32 is directly connected, eth2, weight 1, 00:27:34 -O>* 192.168.10.0/24 [110/11] via 10.100.100.2, vti1, weight 1, 00:24:19 -O>* 192.168.11.0/24 [110/11] via 10.100.100.2, vti1, weight 1, 00:24:19 -``` - -### Monitoring on Palo Alto side - -IKE SAs: - -```none -admin@PA-VM> show vpn ike-sa - -IKEv1 phase-1 SAs -GwID/client IP Peer-Address Gateway Name Role Mode Algorithm Established Expiration V ST Xt Phase2 --------------- ------------ ------------ ---- ---- --------- ----------- ---------- - -- -- ------ -1 10.0.1.2 VyOS Resp Main PSK/DH14/A128/SHA1 Jul.31 01:35:00 Jul.31 09:35:00 v1 13 1 1 - -Show IKEv1 IKE SA: Total 1 gateways found. 1 ike sa found. - - -IKEv1 phase-2 SAs -Gateway Name TnID Tunnel GwID/IP Role Algorithm SPI(in) SPI(out) MsgID ST Xt ------------- ---- ------ ------- ---- --------- ------- -------- ----- -- -- -VyOS 1 VyOS-tunnel 1 Resp ESP/ /tunl/SHA2 8827A3D9 C204F4FA BD202829 9 1 - -Show IKEv1 phase2 SA: Total 1 gateways found. 1 ike sa found. - - -There is no IKEv2 SA found. -``` - -IPsec SAs: - -```none -admin@PA-VM> show vpn ipsec-sa - -GwID/client IP TnID Peer-Address Tunnel(Gateway) Algorithm SPI(in) SPI(out) life(Sec/KB) remain-time(Sec) --------------- ---- ------------ --------------- --------- ------- -------- ------------ ---------------- -1 1 10.0.1.2 VyOS-tunnel(VyOS) ESP/A256/SHA256 8827A3D9 C204F4FA 3600/Unlimited 2733 - -Show IPSec SA: Total 1 tunnels found. 1 ipsec sa found. -``` - -OSPF Neighbor Status: - -```none -admin@PA-VM> show routing protocol ospf neighbor - - Options: 0x80:reserved, O:Opaq-LSA capability, DC:demand circuits, EA:Ext-Attr LSA capability, - N/P:NSSA option, MC:multicase, E:AS external LSA capability, T:TOS capability - ========== - virtual router: default - neighbor address: 10.100.100.1 - local address binding: 0.0.0.0 - type: dynamic - status: full - neighbor router ID: 2.2.2.2 - area id: 0.0.0.0 - neighbor priority: 1 - lifetime remain: 32 - messages pending: 0 - LSA request pending: 0 - options: 0x02: E - hello suppressed: no - restart helper status: not helping - restart helper time remaining: 0 - restart helper exit reason: none -``` - -Routing Table: - -```none -admin@PA-VM> show routing route - -flags: A:active, ?:loose, C:connect, H:host, S:static, ~:internal, R:rip, O:ospf, B:bgp, - Oi:ospf intra-area, Oo:ospf inter-area, O1:ospf ext-type-1, O2:ospf ext-type-2, E:ecmp, M:multicast - - -VIRTUAL ROUTER: default (id 1) - ========== -destination nexthop metric flags age interface next-AS -0.0.0.0/0 10.0.2.1 10 A S ethernet1/1 -10.0.2.0/30 10.0.2.2 0 A C ethernet1/1 -10.0.2.2/32 0.0.0.0 0 A H -10.100.100.0/30 0.0.0.0 10 Oi 1273 tunnel.1 -10.100.100.0/30 10.100.100.2 0 A C tunnel.1 -10.100.100.2/32 0.0.0.0 0 A H -192.168.0.0/24 10.100.100.1 11 A Oi 1253 tunnel.1 -192.168.1.0/24 10.100.100.1 11 A Oi 1253 tunnel.1 -192.168.10.0/24 0.0.0.0 10 Oi 1273 ethernet1/2 -192.168.10.0/24 192.168.10.1 0 A C ethernet1/2 -192.168.10.1/32 0.0.0.0 0 A H -192.168.11.0/24 0.0.0.0 10 Oi 1273 ethernet1/3 -192.168.11.0/24 192.168.11.1 0 A C ethernet1/3 -192.168.11.1/32 0.0.0.0 0 A H -total routes shown: 14 -``` - -### Checking Connectivity - -ICMP packets from PC1 to PC3. - -```none -PC1> ping 192.168.10.2 - -84 bytes from 192.168.10.2 icmp_seq=1 ttl=62 time=8.479 ms -84 bytes from 192.168.10.2 icmp_seq=2 ttl=62 time=3.344 ms -84 bytes from 192.168.10.2 icmp_seq=3 ttl=62 time=3.139 ms -84 bytes from 192.168.10.2 icmp_seq=4 ttl=62 time=3.176 ms -84 bytes from 192.168.10.2 icmp_seq=5 ttl=62 time=3.978 ms -``` - -ICMP packets from PC2 to PC4. - -```none -PC2> ping 192.168.11.2 - -84 bytes from 192.168.11.2 icmp_seq=1 ttl=62 time=9.687 ms -84 bytes from 192.168.11.2 icmp_seq=2 ttl=62 time=3.286 ms -84 bytes from 192.168.11.2 icmp_seq=3 ttl=62 time=2.972 ms -``` diff --git a/docs/configexamples/md-l3vpn-hub-and-spoke.md b/docs/configexamples/md-l3vpn-hub-and-spoke.md deleted file mode 100644 index 3c719926..00000000 --- a/docs/configexamples/md-l3vpn-hub-and-spoke.md +++ /dev/null @@ -1,1091 +0,0 @@ -# L3VPN for Hub-and-Spoke connectivity with VyOS - -IP/MPLS technology is widely used by various service providers and large -enterprises in order to achieve better network scalability, manageability -and flexibility. It also provides the possibility to deliver different -services for the customers in a seamless manner. -Layer 3 VPN (L3VPN) is a type of VPN mode that is built and delivered -through OSI layer 3 networking technologies. Often the border gateway -protocol (BGP) is used to send and receive VPN-related data that is -responsible for the control plane. L3VPN utilizes virtual routing and -forwarding (VRF) techniques to receive and deliver user data as well as -separate data planes of the end-users. It is built using a combination of -IP- and MPLS-based information. Generally, L3VPNs are used to send data -on back-end VPN infrastructures, such as for VPN connections between data -centres, HQs and branches. - -An L3VPN consists of multiple access links, multiple VPN routing and -forwarding (VRF) tables, and multiple MPLS paths or multiple P2MP LSPs. -An L3VPN can be configured to connect two or more customer sites. -In hub-and-spoke MPLS L3VPN environments, the spoke routers need to have -unique Route Distinguishers (RDs). In order to use the hub site as a -transit point for connectivity in such an environment, the spoke sites -export their routes to the hub. Spokes can talk to hubs, but never have -direct paths to other spokes. All traffic between spokes is controlled -and delivered over the hub site. - -To deploy a Layer3 VPN with MPLS on VyOS, we should meet a couple -requirements in order to properly implement the solution. -We'll use the following nodes in our LAB environment: - -- 2 x Route reflectors (VyOS-RRx) -- 4 x Provider routers (VyOS-Px) -- 3 x Provider Edge (VyOs-PEx) -- 3 x Customer Edge (VyOS-CEx) - -The following software was used in the creation of this document: - -- Operating system: VyOS -- Version: 1.4-rolling-202110310317 -- Image name: vyos-1.4-rolling-202110310317-amd64.iso - -**NOTE:** VyOS Router (tested with VyOS 1.4-rolling-202110310317) -– The configurations below are specifically for VyOS 1.4.x. - -General information can be found in the -{ref}`configuration/vrf/index:L3VPN VRFs` chapter. - -## Topology - -```{image} /_static/images/L3VPN_hub_and_spoke.webp -:align: center -:alt: Network Topology Diagram -:width: 80% -``` - - -## How does it work? - -As we know the main assumption of L3VPN “Hub and Spoke” is, that the -traffic between spokes have to pass via hub, in our scenario VyOS-PE2 -is the Hub PE -and the VyOS-CE1-HUB is the central customer office device that is responsible -for controlling access between all spokes and announcing its network prefixes -(10.0.0.100/32). VyOS-PE2 has the main VRF (its name is BLUE_HUB), its -own Route-Distinguisher(RD) and route-target import/export lists. -Multiprotocol-BGP(MP-BGP) delivers L3VPN related control-plane information to -the nodes across network where PEs Spokes import the route-target 60535:1030 -(this is export route-target of vrf BLUE_HUB) and export its own route-target -60535:1011(this is vrf BLUE_SPOKE export route-target). Therefore, the -Customer edge nodes can only learn the network prefixes of the HUB site -[10.0.0.100/32]. For this example VyOS-CE1 has network prefixes -[10.0.0.80/32] / VyOS-CE2 has network prefixes [10.0.0.90/32]. -Route-Reflector devices VyOS-RR1 and VyOS-RR2 are used to simplify network -routes exchange and minimize iBGP peerings between devices. - -L3VPN configuration parameters table: - -```{eval-rst} -+----------+-------+------------+-----------------+-------------+-------------+ -| Node | Role | VRF | RD | RT import | RT export | -+----------+-------+------------+-----------------+-------------+-------------+ -| VyOS-PE2 | Hub | BLUE_HUB | 10.80.80.1:1011 | 65035:1011 | 65035:1030 | -| | | | | 65035:1030 | | -+----------+-------+------------+-----------------+-------------+-------------+ -| VyOS-PE1 | Spoke | BLUE_SPOKE | 10.50.50.1:1011 | 65035:1030 | 65035:1011 | -+----------+-------+------------+-----------------+-------------+-------------+ -| VyOS-PE3 | Spoke | BLUE_SPOKE | 10.60.60.1:1011 | 65035:1030 | 65035:1011 | -+----------+-------+------------+-----------------+-------------+-------------+ -``` - -## Configuration - -### Step-1: Configuring IGP and enabling MPLS LDP - -At the first step we need to configure the IP/MPLS backbone network using OSPF -as IGP protocol and LDP as label-switching protocol for the base connectivity -between **P** (rovider), **P** (rovider) **E** (dge) and **R** (oute) **R** -(eflector) nodes: -- VyOS-P1: - -```none -# interfaces -set interfaces dummy dum10 address '10.0.0.3/32' -set interfaces ethernet eth0 address '172.16.30.1/24' -set interfaces ethernet eth1 address '172.16.40.1/24' -set interfaces ethernet eth2 address '172.16.90.1/24' -set interfaces ethernet eth3 address '172.16.10.1/24' -set interfaces ethernet eth5 address '172.16.100.1/24' - -# protocols ospf+ldp -set protocols mpls interface 'eth1' -set protocols mpls interface 'eth2' -set protocols mpls interface 'eth3' -set protocols mpls interface 'eth5' -set protocols mpls interface 'eth0' -set protocols mpls ldp discovery transport-ipv4-address '10.0.0.3' -set protocols mpls ldp interface 'eth0' -set protocols mpls ldp interface 'eth1' -set protocols mpls ldp interface 'eth2' -set protocols mpls ldp interface 'eth3' -set protocols mpls ldp interface 'eth5' -set protocols mpls ldp router-id '10.0.0.3' -set protocols ospf area 0 network '0.0.0.0/0' -set protocols ospf parameters abr-type 'cisco' -set protocols ospf parameters router-id '10.0.0.3' -``` - -- VyOS-P2: - -```none -# interfaces -set interfaces dummy dum10 address '10.0.0.4/32' -set interfaces ethernet eth0 address '172.16.30.2/24' -set interfaces ethernet eth1 address '172.16.20.1/24' -set interfaces ethernet eth2 address '172.16.120.1/24' -set interfaces ethernet eth3 address '172.16.60.1/24' - -# protocols ospf+ldp -set protocols mpls interface 'eth1' -set protocols mpls interface 'eth2' -set protocols mpls interface 'eth3' -set protocols mpls interface 'eth0' -set protocols mpls ldp discovery transport-ipv4-address '10.0.0.4' -set protocols mpls ldp interface 'eth0' -set protocols mpls ldp interface 'eth1' -set protocols mpls ldp interface 'eth2' -set protocols mpls ldp interface 'eth3' -set protocols mpls ldp router-id '10.0.0.4' -set protocols ospf area 0 network '0.0.0.0/0' -set protocols ospf parameters abr-type 'cisco' -set protocols ospf parameters router-id '10.0.0.4' -``` - -- VyOS-P3: - -```none -# interfaces -set interfaces dummy dum10 address '10.0.0.5/32' -set interfaces ethernet eth0 address '172.16.110.1/24' -set interfaces ethernet eth1 address '172.16.40.2/24' -set interfaces ethernet eth2 address '172.16.50.1/24' -set interfaces ethernet eth3 address '172.16.70.1/24' - -# protocols ospf + ldp -set protocols mpls interface 'eth1' -set protocols mpls interface 'eth2' -set protocols mpls interface 'eth3' -set protocols mpls interface 'eth0' -set protocols mpls ldp discovery transport-ipv4-address '10.0.0.5' -set protocols mpls ldp interface 'eth0' -set protocols mpls ldp interface 'eth1' -set protocols mpls ldp interface 'eth2' -set protocols mpls ldp interface 'eth3' -set protocols mpls ldp router-id '10.0.0.5' -set protocols ospf area 0 network '0.0.0.0/0' -set protocols ospf parameters abr-type 'cisco' -set protocols ospf parameters router-id '10.0.0.5' -``` - -- VyOS-P4: - -```none -# interfaces -set interfaces dummy dum10 address '10.0.0.6/32' -set interfaces ethernet eth0 address '172.16.80.2/24' -set interfaces ethernet eth1 address '172.16.130.1/24' -set interfaces ethernet eth2 address '172.16.50.2/24' -set interfaces ethernet eth3 address '172.16.60.2/24' -set interfaces ethernet eth5 address '172.16.140.1/24' - - -# protocols ospf + ldp -set protocols mpls interface 'eth1' -set protocols mpls interface 'eth2' -set protocols mpls interface 'eth3' -set protocols mpls interface 'eth0' -set protocols mpls interface 'eth5' -set protocols mpls ldp discovery transport-ipv4-address '10.0.0.6' -set protocols mpls ldp interface 'eth0' -set protocols mpls ldp interface 'eth1' -set protocols mpls ldp interface 'eth2' -set protocols mpls ldp interface 'eth3' -set protocols mpls ldp interface 'eth5' -set protocols mpls ldp router-id '10.0.0.6' -set protocols ospf area 0 network '0.0.0.0/0' -set protocols ospf parameters abr-type 'cisco' -set protocols ospf parameters router-id '10.0.0.6' -``` - -- VyOS-PE1: - -```none -# interfaces -set interfaces dummy dum10 address '10.0.0.7/32' -set interfaces ethernet eth0 address '172.16.90.2/24' - -# protocols ospf + ldp -set protocols mpls interface 'eth0' -set protocols mpls ldp discovery transport-ipv4-address '10.0.0.7' -set protocols mpls ldp interface 'eth0' -set protocols mpls ldp router-id '10.0.0.7' -set protocols ospf area 0 network '0.0.0.0/0' -set protocols ospf parameters abr-type 'cisco' -set protocols ospf parameters router-id '10.0.0.7' -``` - -- VyOS-PE2: - -```none -# interfaces -set interfaces dummy dum10 address '10.0.0.8/32' -set interfaces ethernet eth0 address '172.16.110.2/24' -set interfaces ethernet eth1 address '172.16.100.2/24' -set interfaces ethernet eth2 address '172.16.80.1/24' - -# protocols ospf + ldp -set protocols mpls interface 'eth0' -set protocols mpls interface 'eth1' -set protocols mpls ldp discovery transport-ipv4-address '10.0.0.8' -set protocols mpls ldp interface 'eth0' -set protocols mpls ldp interface 'eth1' -set protocols mpls ldp router-id '10.0.0.8' -set protocols ospf area 0 network '0.0.0.0/0' -set protocols ospf parameters abr-type 'cisco' -set protocols ospf parameters router-id '10.0.0.8' -``` - -- VyOS-PE3: - -```none -# interfaces -set interfaces dummy dum10 address '10.0.0.10/32' -set interfaces ethernet eth0 address '172.16.140.2/24' - -# protocols ospf + ldp -set protocols mpls interface 'eth0' -set protocols mpls ldp discovery transport-ipv4-address '10.0.0.10' -set protocols mpls ldp interface 'eth0' -set protocols mpls ldp router-id '10.0.0.10' -set protocols ospf area 0 network '0.0.0.0/0' -set protocols ospf parameters abr-type 'cisco' -set protocols ospf parameters router-id '10.0.0.10' -``` - -- VyOS-RR1: - -```none -# interfaces -set interfaces ethernet eth1 address '172.16.20.2/24' -set interfaces ethernet eth2 address '172.16.10.2/24' -set interfaces dummy dum10 address '10.0.0.1/32' - -# protocols ospf + ldp -set protocols mpls interface 'eth1' -set protocols mpls interface 'eth2' -set protocols mpls ldp discovery transport-ipv4-address '10.0.0.1' -set protocols mpls ldp interface 'eth1' -set protocols mpls ldp interface 'eth2' -set protocols mpls ldp router-id '10.0.0.1' -set protocols ospf area 0 network '0.0.0.0/0' -set protocols ospf parameters abr-type 'cisco' -set protocols ospf parameters router-id '10.0.0.1' -``` - -- VyOS-RR2: - -```none -# interfaces -set interfaces ethernet eth0 address '172.16.80.1/24' -set interfaces ethernet eth1 address '172.16.70.2/24' -set interfaces dummy dum10 address '10.0.0.2/32' - -# protocols ospf + ldp -set protocols mpls interface 'eth0' -set protocols mpls interface 'eth1' -set protocols mpls ldp discovery transport-ipv4-address '10.0.0.2' -set protocols mpls ldp interface 'eth1' -set protocols mpls ldp interface 'eth0' -set protocols mpls ldp router-id '10.0.0.2' -set protocols ospf area 0 network '0.0.0.0/0' -set protocols ospf parameters abr-type 'cisco' -set protocols ospf parameters router-id '10.0.0.2' -``` - - -### Step-2: Configuring iBGP for L3VPN control-plane - -At this step we are going to enable iBGP protocol on MPLS nodes and -Route Reflectors (two routers for redundancy) that will deliver IPv4 -VPN (L3VPN) routes between them: -- VyOS-RR1: - -```none -set protocols bgp system-as '65001' -set protocols bgp neighbor 10.0.0.7 address-family ipv4-vpn route-reflector-client -set protocols bgp neighbor 10.0.0.7 peer-group 'RR_VPNv4' -set protocols bgp neighbor 10.0.0.8 address-family ipv4-vpn route-reflector-client -set protocols bgp neighbor 10.0.0.8 peer-group 'RR_VPNv4' -set protocols bgp neighbor 10.0.0.10 address-family ipv4-vpn route-reflector-client -set protocols bgp neighbor 10.0.0.10 peer-group 'RR_VPNv4' -set protocols bgp parameters cluster-id '10.0.0.1' -set protocols bgp parameters log-neighbor-changes -set protocols bgp parameters router-id '10.0.0.1' -set protocols bgp peer-group RR_VPNv4 remote-as '65001' -set protocols bgp peer-group RR_VPNv4 update-source 'dum10' -``` - -- VyOS-RR2: - -```none -set protocols bgp system-as '65001' -set protocols bgp neighbor 10.0.0.7 address-family ipv4-vpn route-reflector-client -set protocols bgp neighbor 10.0.0.7 peer-group 'RR_VPNv4' -set protocols bgp neighbor 10.0.0.8 address-family ipv4-vpn route-reflector-client -set protocols bgp neighbor 10.0.0.8 peer-group 'RR_VPNv4' -set protocols bgp neighbor 10.0.0.10 address-family ipv4-vpn route-reflector-client -set protocols bgp neighbor 10.0.0.10 peer-group 'RR_VPNv4' -set protocols bgp parameters cluster-id '10.0.0.1' -set protocols bgp parameters log-neighbor-changes -set protocols bgp parameters router-id '10.0.0.2' -set protocols bgp peer-group RR_VPNv4 remote-as '65001' -set protocols bgp peer-group RR_VPNv4 update-source 'dum10' -``` - -- VyOS-PE1: - -```none -set protocols bgp system-as '65001' -set protocols bgp neighbor 10.0.0.1 address-family ipv4-vpn nexthop-self -set protocols bgp neighbor 10.0.0.1 peer-group 'RR_VPNv4' -set protocols bgp neighbor 10.0.0.2 address-family ipv4-vpn nexthop-self -set protocols bgp neighbor 10.0.0.2 peer-group 'RR_VPNv4' -set protocols bgp parameters log-neighbor-changes -set protocols bgp parameters router-id '10.0.0.7' -set protocols bgp peer-group RR_VPNv4 remote-as '65001' -set protocols bgp peer-group RR_VPNv4 update-source 'dum10' -``` - -- VyOS-PE2: - -```none -set protocols bgp system-as '65001' -set protocols bgp neighbor 10.0.0.1 address-family ipv4-vpn nexthop-self -set protocols bgp neighbor 10.0.0.1 peer-group 'RR_VPNv4' -set protocols bgp neighbor 10.0.0.2 address-family ipv4-vpn nexthop-self -set protocols bgp neighbor 10.0.0.2 peer-group 'RR_VPNv4' -set protocols bgp parameters log-neighbor-changes -set protocols bgp parameters router-id '10.0.0.8' -set protocols bgp peer-group RR_VPNv4 remote-as '65001' -set protocols bgp peer-group RR_VPNv4 update-source 'dum10' -``` - -- VyOS-PE3: - -```none -set protocols bgp system-as '65001' -set protocols bgp neighbor 10.0.0.1 address-family ipv4-vpn nexthop-self -set protocols bgp neighbor 10.0.0.1 peer-group 'RR_VPNv4' -set protocols bgp neighbor 10.0.0.2 address-family ipv4-vpn nexthop-self -set protocols bgp neighbor 10.0.0.2 peer-group 'RR_VPNv4' -set protocols bgp parameters log-neighbor-changes -set protocols bgp parameters router-id '10.0.0.10' -set protocols bgp peer-group RR_VPNv4 remote-as '65001' -set protocols bgp peer-group RR_VPNv4 update-source 'dum10' -``` - - -### Step-3: Configuring L3VPN VRFs on PE nodes - -This section provides configuration steps for setting up VRFs on our -PE nodes including CE facing interfaces, BGP, rd and route-target -import/export based on the pre-defined parameters. -- VyOS-PE1: - -```none -# VRF settings -set vrf name BLUE_SPOKE table '200' -set vrf name BLUE_SPOKE protocols bgp address-family ipv4-unicast export vpn -set vrf name BLUE_SPOKE protocols bgp address-family ipv4-unicast import vpn -set vrf name BLUE_SPOKE protocols bgp address-family ipv4-unicast label vpn export 'auto' -set vrf name BLUE_SPOKE protocols bgp address-family ipv4-unicast network 10.50.50.0/24 -set vrf name BLUE_SPOKE protocols bgp address-family ipv4-unicast rd vpn export '10.50.50.1:1011' -set vrf name BLUE_SPOKE protocols bgp address-family ipv4-unicast redistribute connected -set vrf name BLUE_SPOKE protocols bgp address-family ipv4-unicast route-target vpn export '65035:1011' -set vrf name BLUE_SPOKE protocols bgp address-family ipv4-unicast route-target vpn import '65035:1030' -set vrf name BLUE_SPOKE protocols bgp neighbor 10.50.50.2 address-family ipv4-unicast as-override -set vrf name BLUE_SPOKE protocols bgp neighbor 10.50.50.2 remote-as '65035' - -# interfaces -set interfaces ethernet eth3 address '10.50.50.1/24' -set interfaces ethernet eth3 vrf 'BLUE_SPOKE' -``` - -- VyOS-PE2: - -```none -# VRF settings -set vrf name BLUE_HUB table '400' -set vrf name BLUE_HUB protocols bgp address-family ipv4-unicast export vpn -set vrf name BLUE_HUB protocols bgp address-family ipv4-unicast import vpn -set vrf name BLUE_HUB protocols bgp address-family ipv4-unicast label vpn export 'auto' -set vrf name BLUE_HUB protocols bgp address-family ipv4-unicast network 10.80.80.0/24 -set vrf name BLUE_HUB protocols bgp address-family ipv4-unicast rd vpn export '10.80.80.1:1011' -set vrf name BLUE_HUB protocols bgp address-family ipv4-unicast redistribute connected -set vrf name BLUE_HUB protocols bgp address-family ipv4-unicast route-target vpn export '65035:1030' -set vrf name BLUE_HUB protocols bgp address-family ipv4-unicast route-target vpn import '65035:1011 65050:2011 65035:1030' -set vrf name BLUE_HUB protocols bgp neighbor 10.80.80.2 address-family ipv4-unicast as-override -set vrf name BLUE_HUB protocols bgp neighbor 10.80.80.2 remote-as '65035' - -# interfaces -set interfaces ethernet eth3 address '10.80.80.1/24' -set interfaces ethernet eth3 vrf 'BLUE_HUB' -``` - -- VyOS-PE3: - -```none -# VRF settings -set vrf name BLUE_SPOKE table '200' -set vrf name BLUE_SPOKE protocols bgp address-family ipv4-unicast export vpn -set vrf name BLUE_SPOKE protocols bgp address-family ipv4-unicast import vpn -set vrf name BLUE_SPOKE protocols bgp address-family ipv4-unicast label vpn export 'auto' -set vrf name BLUE_SPOKE protocols bgp address-family ipv4-unicast network 10.60.60.0/24 -set vrf name BLUE_SPOKE protocols bgp address-family ipv4-unicast rd vpn export '10.60.60.1:1011' -set vrf name BLUE_SPOKE protocols bgp address-family ipv4-unicast redistribute connected -set vrf name BLUE_SPOKE protocols bgp address-family ipv4-unicast route-target vpn export '65035:1011' -set vrf name BLUE_SPOKE protocols bgp address-family ipv4-unicast route-target vpn import '65035:1030' -set vrf name BLUE_SPOKE protocols bgp neighbor 10.60.60.2 address-family ipv4-unicast as-override -set vrf name BLUE_SPOKE protocols bgp neighbor 10.60.60.2 remote-as '65035' - -# interfaces -set interfaces ethernet eth3 address '10.60.60.1/24' -set interfaces ethernet eth3 vrf 'BLUE_SPOKE' -``` - - -### Step-4: Configuring CE nodes - -Dynamic routing used between CE and PE nodes and eBGP peering -established for the route exchanging between them. All routes -received by PEs are then exported to L3VPN and delivered from -Spoke sites to Hub and vise-versa based on previously -configured L3VPN parameters. -- VyOS-CE1-SPOKE: - -```none -# interfaces -set interfaces dummy dum20 address '10.0.0.80/32' -set interfaces ethernet eth0 address '10.50.50.2/24' - -# BGP for peering with PE -set protocols bgp system-as 65035 -set protocols bgp address-family ipv4-unicast network 10.0.0.80/32 -set protocols bgp neighbor 10.50.50.1 ebgp-multihop '2' -set protocols bgp neighbor 10.50.50.1 remote-as '65001' -set protocols bgp neighbor 10.50.50.1 update-source 'eth0' -set protocols bgp parameters log-neighbor-changes -set protocols bgp parameters router-id '10.50.50.2' -``` - -- VyOS-CE1-HUB: - -```none -# interfaces -set interfaces dummy dum20 address '10.0.0.100/32' -set interfaces ethernet eth0 address '10.80.80.2/24' - -# BGP for peering with PE -set protocols bgp system-as 65035 -set protocols bgp address-family ipv4-unicast network 10.0.0.100/32 -set protocols bgp address-family ipv4-unicast redistribute connected -set protocols bgp neighbor 10.80.80.1 ebgp-multihop '2' -set protocols bgp neighbor 10.80.80.1 remote-as '65001' -set protocols bgp neighbor 10.80.80.1 update-source 'eth0' -set protocols bgp parameters log-neighbor-changes -set protocols bgp parameters router-id '10.80.80.2' -``` - -- VyOS-CE2-SPOKE: - -```none -# interfaces -set interfaces dummy dum20 address '10.0.0.90/32' -set interfaces ethernet eth0 address '10.60.60.2/24' - -# BGP for peering with PE -set protocols bgp system-as 65035 -set protocols bgp address-family ipv4-unicast network 10.0.0.90/32 -set protocols bgp neighbor 10.60.60.1 ebgp-multihop '2' -set protocols bgp neighbor 10.60.60.1 remote-as '65001' -set protocols bgp neighbor 10.60.60.1 update-source 'eth0' -set protocols bgp parameters log-neighbor-changes -set protocols bgp parameters router-id '10.60.60.2' -``` - - -### Step-5: Verification - -This section describes verification commands for MPLS/BGP/LDP -protocols and L3VPN related routes as well as diagnosis and -reachability checks between CE nodes. - -Let’s check IPv4 routing and MPLS information on provider nodes -(same procedure for all P nodes): -- “show ip ospf neighbor” for checking ospf relationship - -```none -vyos@VyOS-P1:~$ show ip ospf neighbor - -Neighbor ID Pri State Dead Time Address Interface RXmtL RqstL DBsmL -10.0.0.4 1 Full/Backup 34.718s 172.16.30.2 eth0:172.16.30.1 0 0 0 -10.0.0.5 1 Full/Backup 35.132s 172.16.40.2 eth1:172.16.40.1 0 0 0 -10.0.0.7 1 Full/Backup 34.764s 172.16.90.2 eth2:172.16.90.1 0 0 0 -10.0.0.1 1 Full/Backup 35.642s 172.16.10.2 eth3:172.16.10.1 0 0 0 -10.0.0.8 1 Full/Backup 35.484s 172.16.100.2 eth5:172.16.100.1 0 0 0 -``` - -- “show mpls ldp neighbor “ for checking ldp neighbors - -```none -vyos@VyOS-P1:~$ show mpls ldp neighbor -AF ID State Remote Address Uptime -ipv4 10.0.0.1 OPERATIONAL 10.0.0.1 07w5d06h -ipv4 10.0.0.4 OPERATIONAL 10.0.0.4 09w3d00h -ipv4 10.0.0.5 OPERATIONAL 10.0.0.5 09w2d23h -ipv4 10.0.0.7 OPERATIONAL 10.0.0.7 03w0d01h -ipv4 10.0.0.8 OPERATIONAL 10.0.0.8 01w3d02h -``` - -- “show mpls ldp binding” for checking mpls label assignment - -```none -vyos@VyOS-P1:~$ show mpls ldp discovery -AF Destination Nexthop Local Label Remote Label In Use -ipv4 10.0.0.1/32 10.0.0.1 23 imp-null yes -ipv4 10.0.0.1/32 10.0.0.4 23 20 no -ipv4 10.0.0.1/32 10.0.0.5 23 17 no -ipv4 10.0.0.1/32 10.0.0.7 23 16 no -ipv4 10.0.0.1/32 10.0.0.8 23 16 no -ipv4 10.0.0.2/32 10.0.0.1 20 16 no -ipv4 10.0.0.2/32 10.0.0.4 20 22 no -ipv4 10.0.0.2/32 10.0.0.5 20 24 yes -ipv4 10.0.0.2/32 10.0.0.7 20 17 no -ipv4 10.0.0.2/32 10.0.0.8 20 17 no -ipv4 10.0.0.3/32 10.0.0.1 imp-null 17 no -ipv4 10.0.0.3/32 10.0.0.4 imp-null 16 no -ipv4 10.0.0.3/32 10.0.0.5 imp-null 18 no -ipv4 10.0.0.3/32 10.0.0.7 imp-null 18 no -ipv4 10.0.0.3/32 10.0.0.8 imp-null 18 no -ipv4 10.0.0.4/32 10.0.0.1 16 18 no -ipv4 10.0.0.4/32 10.0.0.4 16 imp-null yes -ipv4 10.0.0.4/32 10.0.0.5 16 19 no -ipv4 10.0.0.4/32 10.0.0.7 16 19 no -ipv4 10.0.0.4/32 10.0.0.8 16 19 no -ipv4 10.0.0.5/32 10.0.0.1 21 19 no -ipv4 10.0.0.5/32 10.0.0.4 21 17 no -ipv4 10.0.0.5/32 10.0.0.5 21 imp-null yes -ipv4 10.0.0.5/32 10.0.0.7 21 20 no -ipv4 10.0.0.5/32 10.0.0.8 21 20 no -ipv4 10.0.0.6/32 10.0.0.1 17 20 no -ipv4 10.0.0.6/32 10.0.0.4 17 23 yes -ipv4 10.0.0.6/32 10.0.0.5 17 21 yes -ipv4 10.0.0.6/32 10.0.0.7 17 21 no -ipv4 10.0.0.6/32 10.0.0.8 17 21 no -ipv4 10.0.0.7/32 10.0.0.1 22 21 no -ipv4 10.0.0.7/32 10.0.0.4 22 18 no -ipv4 10.0.0.7/32 10.0.0.5 22 20 no -ipv4 10.0.0.7/32 10.0.0.7 22 imp-null yes -ipv4 10.0.0.7/32 10.0.0.8 22 22 no -ipv4 10.0.0.8/32 10.0.0.1 24 22 no -ipv4 10.0.0.8/32 10.0.0.4 24 19 no -ipv4 10.0.0.8/32 10.0.0.5 24 16 no -ipv4 10.0.0.8/32 10.0.0.7 24 22 no -ipv4 10.0.0.8/32 10.0.0.8 24 imp-null yes -ipv4 10.0.0.9/32 10.0.0.1 18 23 no -ipv4 10.0.0.9/32 10.0.0.4 18 21 yes -ipv4 10.0.0.9/32 10.0.0.5 18 22 no -ipv4 10.0.0.9/32 10.0.0.7 18 23 no -ipv4 10.0.0.9/32 10.0.0.8 18 23 no -ipv4 10.0.0.10/32 10.0.0.1 19 24 no -ipv4 10.0.0.10/32 10.0.0.4 19 24 yes -ipv4 10.0.0.10/32 10.0.0.5 19 23 yes -ipv4 10.0.0.10/32 10.0.0.7 19 24 no -ipv4 10.0.0.10/32 10.0.0.8 19 24 no -``` - -Now we’re checking iBGP status and routes from route-reflector -nodes to other devices: -- “show bgp ipv4 vpn summary” for checking BGP VPNv4 neighbors: - -```none -vyos@VyOS-RR1:~$ show bgp ipv4 vpn summary -BGP router identifier 10.0.0.1, local AS number 65001 vrf-id 0 -BGP table version 0 -RIB entries 9, using 1728 bytes of memory -Peers 4, using 85 KiB of memory -Peer groups 1, using 64 bytes of memory - -Neighbor V AS MsgRcvd MsgSent TblVer InQ OutQ Up/Down State/PfxRcd PfxSnt -10.0.0.7 4 65001 7719 7733 0 0 0 5d07h56m 2 10 -10.0.0.8 4 65001 7715 7724 0 0 0 5d08h28m 4 10 -10.0.0.9 4 65001 7713 7724 0 0 0 5d08h28m 2 10 -10.0.0.10 4 65001 7713 7724 0 0 0 5d08h28m 2 10 - -Total number of neighbors 4 -``` - -- “show bgp ipv4 vpn” for checking all VPNv4 prefixes information: - -```none -vyos@VyOS-RR1:~$ show bgp ipv4 vpn -BGP table version is 2, local router ID is 10.0.0.1, vrf id 0 -Default local pref 100, local AS 65001 -Status codes: s suppressed, d damped, h history, * valid, > best, = multipath, - i internal, r RIB-failure, S Stale, R Removed -Nexthop codes: @NNN nexthop's vrf id, < announce-nh-self -Origin codes: i - IGP, e - EGP, ? - incomplete - - Network Next Hop Metric LocPrf Weight Path -Route Distinguisher: 10.50.50.1:1011 -*>i10.50.50.0/24 10.0.0.7 0 100 0 i - UN=10.0.0.7 EC{65035:1011} label=80 type=bgp, subtype=0 -*>i80.80.80.80/32 10.0.0.7 0 100 0 65035 i - UN=10.0.0.7 EC{65035:1011} label=80 type=bgp, subtype=0 -Route Distinguisher: 10.60.60.1:1011 -*>i10.60.60.0/24 10.0.0.10 0 100 0 i - UN=10.0.0.10 EC{65035:1011} label=80 type=bgp, subtype=0 -*>i90.90.90.90/32 10.0.0.10 0 100 0 65035 i - UN=10.0.0.10 EC{65035:1011} label=80 type=bgp, subtype=0 -Route Distinguisher: 10.80.80.1:1011 -*>i10.80.80.0/24 10.0.0.8 0 100 0 i - UN=10.0.0.8 EC{65035:1030} label=80 type=bgp, subtype=0 -*>i100.100.100.100/32 - 10.0.0.8 0 100 0 65035 i - UN=10.0.0.8 EC{65035:1030} label=80 type=bgp, subtype=0 -Route Distinguisher: 172.16.80.1:2011 -*>i10.110.110.0/24 10.0.0.8 0 100 0 65050 i - UN=10.0.0.8 EC{65050:2011} label=81 type=bgp, subtype=0 -*>i172.16.80.0/24 10.0.0.8 0 100 0 i - UN=10.0.0.8 EC{65050:2011} label=81 type=bgp, subtype=0 -Route Distinguisher: 172.16.100.1:2011 -*>i10.210.210.0/24 10.0.0.9 0 100 0 65050 i - UN=10.0.0.9 EC{65050:2011} label=80 type=bgp, subtype=0 -*>i172.16.100.0/24 10.0.0.9 0 100 0 i - UN=10.0.0.9 EC{65050:2011} label=80 type=bgp, subtype=0 -``` - -- “show bgp ipv4 vpn x.x.x.x/x” for checking best path selected - for specific VPNv4 destination - -```none -vyos@VyOS-RR1:~$ show bgp ipv4 vpn 10.0.0.100/32 -BGP routing table entry for 10.80.80.1:1011:10.0.0.100/32 -not allocated -Paths: (1 available, best #1) - Advertised to non peer-group peers: - 10.0.0.7 10.0.0.8 10.0.0.9 10.0.0.10 - 65035, (Received from a RR-client) - 10.0.0.8 from 10.0.0.8 (10.0.0.8) - Origin incomplete, metric 0, localpref 100, valid, internal, best (First path received) - Extended Community: RT:65035:1030 - Remote label: 80 - Last update: Tue Oct 19 13:45:32 202 -``` - -Also we can verify how PE devices receives VPNv4 networks from the RRs -and installing them to the specific customer VRFs: -- “show bgp ipv4 vpn summary” for checking iBGP neighbors against - route-reflector devices: - -```none -vyos@VyOS-PE1:~$ show bgp ipv4 vpn summary -BGP router identifier 10.0.0.7, local AS number 65001 vrf-id 0 -BGP table version 0 -RIB entries 9, using 1728 bytes of memory -Peers 2, using 43 KiB of memory -Peer groups 1, using 64 bytes of memory - -Neighbor V AS MsgRcvd MsgSent TblVer InQ OutQ Up/Down State/PfxRcd PfxSnt -10.0.0.1 4 65001 8812 8794 0 0 0 01:18:42 8 2 -10.0.0.2 4 65001 8800 8792 0 0 0 6d02h27m 8 2 -``` - -- “show bgp vrf all” for checking all the prefix learning on BGP - : within VRFs: - -```none -vyos@VyOS-PE1:~$ show bgp vrf all - -Instance default: -No BGP prefixes displayed, 0 exist - -Instance BLUE_SPOKE: -BGP table version is 8, local router ID is 10.50.50.1, vrf id 6 -Default local pref 100, local AS 65001 -Status codes: s suppressed, d damped, h history, * valid, > best, = multipath, - i internal, r RIB-failure, S Stale, R Removed -Nexthop codes: @NNN nexthop's vrf id, < announce-nh-self -Origin codes: i - IGP, e - EGP, ? - incomplete - - Network Next Hop Metric LocPrf Weight Path -* 10.50.50.0/24 0.0.0.0 0 32768 ? -*> 0.0.0.0 0 32768 i -*> 10.80.80.0/24 10.0.0.8@0< 0 100 0 i -* 10.0.0.8@0< 0 100 0 i -*> 10.0.0.80/32 10.50.50.2 0 0 65035 i -*> 10.0.0.100/32 - 10.0.0.8@0< 0 100 0 65035 ? -* 10.0.0.8@0< 0 100 0 65035 ? -``` - -- “show bgp vrf BLUE_SPOKE summary” for checking EBGP neighbor - : information between PE and CE: - -```none -vyos@VyOS-PE1:~$ show bgp vrf BLUE_SPOKE summary - -IPv4 Unicast Summary: -BGP router identifier 10.50.50.1, local AS number 65001 vrf-id 6 -BGP table version 8 -RIB entries 7, using 1344 bytes of memory -Peers 1, using 21 KiB of memory - -Neighbor V AS MsgRcvd MsgSent TblVer InQ OutQ Up/Down State/PfxRcd PfxSnt -10.50.50.2 4 65035 9019 9023 0 0 0 6d06h12m 1 4 - -Total number of neighbors 1 -``` - -- “show ip route vrf BLUE_SPOKE” for viewing the RIB in our Spoke PE. - : Using this command we are also able to check the transport and - customer label (inner/outer) for Hub network prefix (10.0.0.100/32): - -```none -vyos@VyOS-PE1:~$ show ip route vrf BLUE_SPOKE - -Codes: K - kernel route, C - connected, S - static, R - RIP, - O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, - T - Table, v - VNC, V - VNC-Direct, A - Babel, D - SHARP, - F - PBR, f - OpenFabric, - > - selected route, * - FIB route, q - queued, r - rejected, b - backup - -VRF BLUE_SPOKE: -K>* 0.0.0.0/0 [255/8192] unreachable (ICMP unreachable), 03w0d23h -C>* 10.50.50.0/24 is directly connected, eth3, 03w0d23h -B> 10.80.80.0/24 [200/0] via 10.0.0.8 (vrf default) (recursive), label 80, weight 1, 04:22:00 - * via 172.16.90.1, eth0 (vrf default), label 24/80, weight 1, 04:22:00 -B>* 10.0.0.80/32 [20/0] via 10.50.50.2, eth3, weight 1, 6d05h30m -B> 10.0.0.100/32 [200/0] via 10.0.0.8 (vrf default) (recursive), label 80, weight 1, 04:22:00 - * via 172.16.90.1, eth0 (vrf default), label 24/80, weight 1, 04:22:00 -``` - -- “show bgp ipv4 vpn x.x.x.x/32” for checking the best-path to the - : specific VPNv4 destination including extended community and - remotelabel information. This procedure is the same on all Spoke nodes: - -```none -vyos@VyOS-PE1:~$ show bgp ipv4 vpn 10.0.0.100/32 -BGP routing table entry for 10.80.80.1:1011:10.0.0.100/32 -not allocated -Paths: (2 available, best #1) - Not advertised to any peer - 65035 - 10.0.0.8 from 10.0.0.1 (10.0.0.8) - Origin incomplete, metric 0, localpref 100, valid, internal, best (Neighbor IP) - Extended Community: RT:65035:1030 - Originator: 10.0.0.8, Cluster list: 10.0.0.1 - Remote label: 80 - Last update: Tue Oct 19 13:45:26 2021 - 65035 - 10.0.0.8 from 10.0.0.2 (10.0.0.8) - Origin incomplete, metric 0, localpref 100, valid, internal - Extended Community: RT:65035:1030 - Originator: 10.0.0.8, Cluster list: 10.0.0.1 - Remote label: 80 - Last update: Wed Oct 13 12:39:34 202 -``` - -Now, let’s check routing information on out Hub PE: -- “show bgp ipv4 vpn summary” for checking iBGP neighbors again - : VyOS-RR1/RR2 - -```none -vyos@VyOS-PE2:~$ show bgp ipv4 vpn summary -BGP router identifier 10.0.0.8, local AS number 65001 vrf-id 0 -BGP table version 0 -RIB entries 9, using 1728 bytes of memory -Peers 2, using 43 KiB of memory -Peer groups 1, using 64 bytes of memory - -Neighbor V AS MsgRcvd MsgSent TblVer InQ OutQ Up/Down State/PfxRcd PfxSnt -10.0.0.1 4 65001 15982 15949 0 0 0 05:41:28 6 4 -10.0.0.2 4 65001 9060 9054 0 0 0 6d06h47m 6 4 - -Total number of neighbors -``` - -- “show bgp vrf all” for checking all the prefixes learning on BGP - -```none -vyos@VyOS-PE2:~$ show bgp vrf all - -Instance default: -No BGP prefixes displayed, 0 exist - -Instance BLUE_HUB: -BGP table version is 50, local router ID is 10.80.80.1, vrf id 8 -Default local pref 100, local AS 65001 -Status codes: s suppressed, d damped, h history, * valid, > best, = multipath, - i internal, r RIB-failure, S Stale, R Removed -Nexthop codes: @NNN nexthop's vrf id, < announce-nh-self -Origin codes: i - IGP, e - EGP, ? - incomplete - - Network Next Hop Metric LocPrf Weight Path -*> 10.50.50.0/24 10.0.0.7@0< 0 100 0 i -* 10.0.0.7@0< 0 100 0 i -*> 10.60.60.0/24 10.0.0.10@0< 0 100 0 i -* 10.0.0.10@0< 0 100 0 i -* 10.80.80.0/24 10.80.80.2 0 0 65035 ? -* 0.0.0.0 0 32768 i -*> 0.0.0.0 0 32768 ? -*> 10.110.110.0/24 172.16.80.2@9< 0 0 65050 i -*> 10.210.210.0/24 10.0.0.9@0< 0 100 0 65050 i -* 10.0.0.9@0< 0 100 0 65050 i -*> 10.0.0.80/32 10.0.0.7@0< 0 100 0 65035 i -* 10.0.0.7@0< 0 100 0 65035 i -*> 10.0.0.90/32 10.0.0.10@0< 0 100 0 65035 i -* 10.0.0.10@0< 0 100 0 65035 i -*> 10.0.0.100/32 - 10.80.80.2 0 0 65035 ? -*> 172.16.80.0/24 0.0.0.0@9< 0 32768 ? - 0.0.0.0@9< 0 32768 i -*> 172.16.100.0/24 10.0.0.9@0< 0 100 0 i -* 10.0.0.9@0< 0 100 0 i -``` - -- “show bgp vrf BLUE_HUB summary” for checking EBGP neighbor - : CE Hub device - -```none -vyos@VyOS-PE2:~$ show bgp vrf BLUE_HUB summary - -IPv4 Unicast Summary: -BGP router identifier 10.80.80.1, local AS number 65001 vrf-id 8 -BGP table version 50 -RIB entries 19, using 3648 bytes of memory -Peers 1, using 21 KiB of memory - -Neighbor V AS MsgRcvd MsgSent TblVer InQ OutQ Up/Down State/PfxRcd PfxSnt -10.80.80.2 4 65035 15954 15972 0 0 0 01w4d01h 2 10 -``` - -- “show ip route vrf BLUE_HUB” to view the RIB in our Hub PE. - : With this command we are able to check the transport and - customer label (inner/outer) for network spokes prefixes - 10.0.0.80/32 - 10.0.0.90/32 - -```none -vyos@VyOS-PE2:~$ show ip route vrf BLUE_HUB - -Codes: K - kernel route, C - connected, S - static, R - RIP, - O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, - T - Table, v - VNC, V - VNC-Direct, A - Babel, D - SHARP, - F - PBR, f - OpenFabric, - > - selected route, * - FIB route, q - queued, r - rejected, b - backup - -VRF BLUE_HUB: -K>* 0.0.0.0/0 [255/8192] unreachable (ICMP unreachable), 01w4d01h -B> 10.50.50.0/24 [200/0] via 10.0.0.7 (vrf default) (recursive), label 144, weight 1, 05:53:15 - * via 172.16.100.1, eth1 (vrf default), label 22/144, weight 1, 05:53:15 -B> 10.60.60.0/24 [200/0] via 10.0.0.10 (vrf default) (recursive), label 144, weight 1, 05:53:15 - * via 172.16.110.1, eth0 (vrf default), label 23/144, weight 1, 05:53:15 -C>* 10.80.80.0/24 is directly connected, eth3, 01w4d01h -B>* 10.110.110.0/24 [200/0] via 172.16.80.2, eth2 (vrf GREEN), weight 1, 01w4d01h -B> 10.210.210.0/24 [200/0] via 10.0.0.9 (vrf default) (recursive), label 144, weight 1, 05:53:15 - * via 172.16.100.1, eth1 (vrf default), label 18/144, weight 1, 05:53:15 - * via 172.16.110.1, eth0 (vrf default), label 22/144, weight 1, 05:53:15 -B> 10.0.0.80/32 [200/0] via 10.0.0.7 (vrf default) (recursive), label 144, weight 1, 05:53:15 - * via 172.16.100.1, eth1 (vrf default), label 22/144, weight 1, 05:53:15 -B> 10.0.0.90/32 [200/0] via 10.0.0.10 (vrf default) (recursive), label 144, weight 1, 05:53:15 - * via 172.16.110.1, eth0 (vrf default), label 23/144, weight 1, 05:53:15 -B>* 10.0.0.100/32 [20/0] via 10.80.80.2, eth3, weight 1, 01w4d01h -B>* 172.16.80.0/24 [200/0] is directly connected, eth2 (vrf GREEN), weight 1, 01w4d01h -B> 172.16.100.0/24 [200/0] via 10.0.0.9 (vrf default) (recursive), label 144, weight 1, 05:53:15 - * via 172.16.100.1, eth1 (vrf default), label 18/144, weight 1, 05:53:15 - * via 172.16.110.1, eth0 (vrf default), label 22/144, weight 1, 05:53:15 -``` - -- “show bgp ipv4 vpn x.x.x.x/32” for checking best-path, - : extended community and remote label of specific destination - -```none -vyos@VyOS-PE2:~$ show bgp ipv4 vpn 10.0.0.80/32 -BGP routing table entry for 10.50.50.1:1011:10.0.0.80/32 -not allocated -Paths: (2 available, best #1) - Not advertised to any peer - 65035 - 10.0.0.7 from 10.0.0.1 (10.0.0.7) - Origin IGP, metric 0, localpref 100, valid, internal, best (Neighbor IP) - Extended Community: RT:65035:1011 - Originator: 10.0.0.7, Cluster list: 10.0.0.1 - Remote label: 144 - Last update: Tue Oct 19 13:45:30 2021 - 65035 - 10.0.0.7 from 10.0.0.2 (10.0.0.7) - Origin IGP, metric 0, localpref 100, valid, internal - Extended Community: RT:65035:1011 - Originator: 10.0.0.7, Cluster list: 10.0.0.1 - Remote label: 144 - Last update: Wed Oct 13 12:39:37 2021 - -vyos@VyOS-PE2:~$ show bgp ipv4 vpn 10.0.0.90/32 -BGP routing table entry for 10.60.60.1:1011:10.0.0.90/32 -not allocated -Paths: (2 available, best #1) - Not advertised to any peer - 65035 - 10.0.0.10 from 10.0.0.1 (10.0.0.10) - Origin IGP, metric 0, localpref 100, valid, internal, best (Neighbor IP) - Extended Community: RT:65035:1011 - Originator: 10.0.0.10, Cluster list: 10.0.0.1 - Remote label: 144 - Last update: Tue Oct 19 13:45:30 2021 - 65035 - 10.0.0.10 from 10.0.0.2 (10.0.0.10) - Origin IGP, metric 0, localpref 100, valid, internal - Extended Community: RT:65035:1011 - Originator: 10.0.0.10, Cluster list: 10.0.0.1 - Remote label: 144 - Last update: Wed Oct 13 12:45:44 2021 -``` - -Finally, let’s check the reachability between CEs: -- VyOS-CE1-SPOKE -----> VyOS-CE-HUB - -```none -# check rib -vyos@VyOS-CE1-SPOKE:~$ show ip route -Codes: K - kernel route, C - connected, S - static, R - RIP, - O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, - T - Table, v - VNC, V - VNC-Direct, A - Babel, D - SHARP, - F - PBR, f - OpenFabric, - > - selected route, * - FIB route, q - queued, r - rejected, b - backup - -B 10.50.50.0/24 [20/0] via 10.50.50.1 inactive, weight 1, 6d07h53m -C>* 10.50.50.0/24 is directly connected, eth0, 09w0d00h -B>* 10.80.80.0/24 [20/0] via 10.50.50.1, eth0, weight 1, 6d07h53m -C>* 10.0.0.80/32 is directly connected, dum20, 09w0d00h -B>* 10.0.0.100/32 [20/0] via 10.50.50.1, eth0, weight 1, 6d07h53m - -# check icmp -vyos@VyOS-CE1-SPOKE:~$ ping 10.0.0.100 interface 10.0.0.80 -PING 10.0.0.100 (10.0.0.100) from 10.0.0.80 : 56(84) bytes of data. -64 bytes from 10.0.0.100: icmp_seq=1 ttl=62 time=6.52 ms -64 bytes from 10.0.0.100: icmp_seq=2 ttl=62 time=4.13 ms -64 bytes from 10.0.0.100: icmp_seq=3 ttl=62 time=4.04 ms -64 bytes from 10.0.0.100: icmp_seq=4 ttl=62 time=4.03 ms -^C ---- 10.0.0.100 ping statistics --- -4 packets transmitted, 4 received, 0% packet loss, time 8ms -rtt min/avg/max/mdev = 4.030/4.680/6.518/1.064 ms - -# check network path -vyos@VyOS-CE1-SPOKE:~$ traceroute 10.0.0.100 -traceroute to 10.0.0.100 (10.0.0.100), 30 hops max, 60 byte packets - 1 10.50.50.1 (10.50.50.1) 1.041 ms 1.252 ms 1.835 ms - 2 * * * - 3 10.0.0.100 (10.0.0.100) 9.225 ms 9.159 ms 9.121 m -``` - -- VyOS-CE-HUB -------> VyOS-CE1-SPOKE -- VyOS-CE-HUB -------> VyOS-CE2-SPOKE - -```none -# check rib -vyos@VyOS-CE-HUB:~$ show ip route -Codes: K - kernel route, C - connected, S - static, R - RIP, - O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, - T - Table, v - VNC, V - VNC-Direct, A - Babel, D - SHARP, - F - PBR, f - OpenFabric, - > - selected route, * - FIB route, q - queued, r - rejected, b - backup - -B>* 10.50.50.0/24 [20/0] via 10.80.80.1, eth0, weight 1, 6d08h04m -B>* 10.60.60.0/24 [20/0] via 10.80.80.1, eth0, weight 1, 6d08h35m -C>* 10.80.80.0/24 is directly connected, eth0, 01w6d07h -B>* 10.110.110.0/24 [20/0] via 10.80.80.1, eth0, weight 1, 01w4d02h -B>* 10.210.210.0/24 [20/0] via 10.80.80.1, eth0, weight 1, 6d08h35m -B>* 10.0.0.80/32 [20/0] via 10.80.80.1, eth0, weight 1, 6d08h04m -B>* 10.0.0.90/32 [20/0] via 10.80.80.1, eth0, weight 1, 6d08h35m -C>* 10.0.0.100/32 is directly connected, dum20, 01w6d07h -B>* 172.16.80.0/24 [20/0] via 10.80.80.1, eth0, weight 1, 01w4d02h -B>* 172.16.100.0/24 [20/0] via 10.80.80.1, eth0, weight 1, 6d08h35m - -# check icmp -vyos@VyOS-CE-HUB:~$ ping 10.0.0.80 interface 10.0.0.100 c 4 -PING 10.0.0.80 (10.0.0.80) from 10.0.0.100 : 56(84) bytes of data. -64 bytes from 10.0.0.80: icmp_seq=1 ttl=62 time=3.31 ms -64 bytes from 10.0.0.80: icmp_seq=2 ttl=62 time=4.23 ms -64 bytes from 10.0.0.80: icmp_seq=3 ttl=62 time=3.89 ms -64 bytes from 10.0.0.80: icmp_seq=4 ttl=62 time=3.22 ms - ---- 10.0.0.80 ping statistics --- -4 packets transmitted, 4 received, 0% packet loss, time 9ms -rtt min/avg/max/mdev = 3.218/3.661/4.226/0.421 ms - -vyos@VyOS-CE-HUB:~$ ping 10.0.0.90 interface 10.0.0.100 c 4 -PING 10.0.0.90 (10.0.0.90) from 10.0.0.100 : 56(84) bytes of data. -64 bytes from 10.0.0.90: icmp_seq=1 ttl=62 time=7.46 ms -64 bytes from 10.0.0.90: icmp_seq=2 ttl=62 time=4.43 ms -64 bytes from 10.0.0.90: icmp_seq=3 ttl=62 time=4.60 ms -^C ---- 10.0.0.90 ping statistics --- -3 packets transmitted, 3 received, 0% packet loss, time 6ms -rtt min/avg/max/mdev = 4.430/5.498/7.463/1.391 ms - -# check network path -vyos@VyOS-CE-HUB:~$ traceroute 10.0.0.80 -traceroute to 10.0.0.80 (10.0.0.80), 30 hops max, 60 byte packets - 1 10.80.80.1 (10.80.80.1) 1.563 ms 1.341 ms 1.075 ms - 2 * * * - 3 10.0.0.80 (10.0.0.80) 8.125 ms 8.019 ms 7.781 ms - -vyos@VyOS-CE-HUB:~$ traceroute 10.0.0.90 -traceroute to 10.0.0.90 (10.0.0.90), 30 hops max, 60 byte packets - 1 10.80.80.1 (10.80.80.1) 1.305 ms 1.137 ms 1.097 ms - 2 * * * - 3 * * * - 4 10.0.0.90 (10.0.0.90) 9.358 ms 9.325 ms 9.292 ms -``` - -- VyOS-CE2-SPOKE -------> VyOS-CE-HUB - -```none -# check rib -vyos@rt-ce2-SPOKE:~$ show ip route -Codes: K - kernel route, C - connected, S - static, R - RIP, - O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, - T - Table, v - VNC, V - VNC-Direct, A - Babel, D - SHARP, - F - PBR, f - OpenFabric, - > - selected route, * - FIB route, q - queued, r - rejected, b - backup - -B 10.60.60.0/24 [20/0] via 10.60.60.1 inactive, weight 1, 02w6d00h -C>* 10.60.60.0/24 is directly connected, eth0, 02w6d00h -B>* 10.80.80.0/24 [20/0] via 10.60.60.1, eth0, weight 1, 6d08h46m -C>* 10.0.0.90/32 is directly connected, dum20, 02w6d00h -B>* 10.0.0.100/32 [20/0] via 10.60.60.1, eth0, weight 1, 6d08h46m - -# check icmp -vyos@rt-ce2-SPOKE:~$ ping 10.0.0.100 interface 10.0.0.90 c 4 -PING 10.0.0.100 (10.0.0.100) from 10.0.0.90 : 56(84) bytes of data. -64 bytes from 10.0.0.100: icmp_seq=1 ttl=62 time=4.97 ms -64 bytes from 10.0.0.100: icmp_seq=2 ttl=62 time=4.45 ms -64 bytes from 10.0.0.100: icmp_seq=3 ttl=62 time=4.20 ms -64 bytes from 10.0.0.100: icmp_seq=4 ttl=62 time=4.29 ms - ---- 10.0.0.100 ping statistics --- -4 packets transmitted, 4 received, 0% packet loss, time 9ms -rtt min/avg/max/mdev = 4.201/4.476/4.971/0.309 ms - -# check network path -vyos@rt-ce2-SPOKE:~$ traceroute 10.0.0.100 -traceroute to 10.0.0.100 (10.0.0.100), 30 hops max, 60 byte packets - 1 10.60.60.1 (10.60.60.1) 1.343 ms 1.190 ms 1.152 ms - 2 * * * - 3 * * * - 4 10.0.0.100 (10.0.0.100) 7.504 ms 7.480 ms 7.488 ms -``` - -**Note:** At the moment, trace mpls doesn’t show labels/paths. So we’ll -see `* * *` for the transit routers of the mpls backbone. diff --git a/docs/configexamples/md-lac-lns.md b/docs/configexamples/md-lac-lns.md deleted file mode 100644 index 51a96f8b..00000000 --- a/docs/configexamples/md-lac-lns.md +++ /dev/null @@ -1,181 +0,0 @@ ---- -lastproofread: '2024-02-21' ---- - -(examples-lac-lns)= - -# PPPoE over L2TP - -This document is to describe a basic setup using PPPoE over L2TP. -LAC and LNS are components of the broadband topology. -LAC - L2TP access concentrator -LNS - L2TP Network Server -LAC and LNS forms L2TP tunnel. LAC receives packets from PPPoE clients and -forward them to LNS. LNS is the termination point that comes from PPP packets -from the remote client. - -In this example we use VyOS 1.5 as LNS and Cisco IOS as LAC. -All users with domain **vyos.io** will be tunneled to LNS via L2TP. - -## Network Topology - -```{image} /_static/images/lac-lns-diagram.webp -:align: center -:alt: Network Topology Diagram -:width: 60% -``` - - -## Configurations - -### LAC - -```none -aaa new-model -! -aaa authentication ppp default local -! -vpdn enable -vpdn aaa attribute nas-ip-address vpdn-nas -! -vpdn-group LAC - request-dialin - protocol l2tp - domain vyos.io - initiate-to ip 192.168.139.100 - source-ip 192.168.139.101 - local name LAC - l2tp tunnel password 0 test123 -! -bba-group pppoe MAIN-BBA - virtual-template 1 -! -interface GigabitEthernet0/0 - description To LNS - ip address 192.168.139.101 255.255.255.0 - duplex auto - speed auto - media-type rj45 -! -interface GigabitEthernet0/1 - description To PPPoE clients - no ip address - duplex auto - speed auto - media-type rj45 - pppoe enable group MAIN-BBA -! -interface Virtual-Template1 - description pppoe MAIN-BBA - no ip address - no peer default ip address - ppp mtu adaptive - ppp authentication chap -! -``` - - -### LNS - -% stop_vyoslinter - -```none -set interfaces ethernet eth0 address '192.168.139.100/24' -set nat source rule 100 outbound-interface name 'eth0' -set nat source rule 100 source address '10.0.0.0/24' -set nat source rule 100 translation address 'masquerade' -set protocols static route 0.0.0.0/0 next-hop 192.168.139.2 -set vpn l2tp remote-access authentication mode 'radius' -set vpn l2tp remote-access authentication radius server 192.168.139.110 key 'radiustest' -set vpn l2tp remote-access client-ip-pool TEST-POOL range '10.0.0.2-10.0.0.100' -set vpn l2tp remote-access default-pool 'TEST-POOL' -set vpn l2tp remote-access gateway-address '10.0.0.1' -set vpn l2tp remote-access lns host-name 'LAC' -set vpn l2tp remote-access lns shared-secret 'test123' -set vpn l2tp remote-access name-server '8.8.8.8' -set vpn l2tp remote-access ppp-options disable-ccp -``` - -% start_vyoslinter - -:::{note} -This setup requires the Compression Control Protocol (CCP) -being disabled, the command `set vpn l2tp remote-access ppp-options disable-ccp` -accomplishes that. -::: - -### Client - -In this lab we use Windows PPPoE client. - -```{image} /_static/images/lac-lns-winclient.webp -:align: center -:alt: Window PPPoE Client Configuration -:width: 100% -``` - - -### Monitoring - -Monitoring on LNS side - -```none -vyos@vyos:~$ show l2tp-server sessions - ifname | username | ip | ip6 | ip6-dp | calling-sid | rate-limit | state | uptime | rx-bytes | tx-bytes ---------+--------------+----------+-----+--------+-----------------+------------+--------+----------+-----------+---------- - l2tp0 | test@vyos.io | 10.0.0.2 | | | 192.168.139.101 | | active | 00:00:35 | 188.4 KiB | 9.3 MiB -``` - -Monitoring on LAC side - -```none -Router#show pppoe session - 1 session in FORWARDED (FWDED) State - 1 session total -Uniq ID PPPoE RemMAC Port VT VA State - SID LocMAC VA-st Type - 1 1 000c.290b.20a6 Gi0/1 1 N/A FWDED - 0c58.88ac.0001 - -Router#show l2tp -L2TP Tunnel and Session Information Total tunnels 1 sessions 1 - -LocTunID RemTunID Remote Name State Remote Address Sessn L2TP Class/ - Count VPDN Group -23238 2640 LAC est 192.168.139.100 1 LAC - -LocID RemID TunID Username, Intf/ State Last Chg Uniq ID - Vcid, Circuit -25641 25822 23238 test@vyos.io, Gi0/1 est 00:05:36 1 -``` - -Monitoring on RADIUS Server side - -```none -root@Radius:~# cat /var/log/freeradius/radacct/192.168.139.100/detail-20240221 -Wed Feb 21 13:37:17 2024 - User-Name = "test@vyos.io" - NAS-Port = 0 - NAS-Port-Id = "l2tp0" - NAS-Port-Type = Virtual - Service-Type = Framed-User - Framed-Protocol = PPP - Calling-Station-Id = "192.168.139.101" - Called-Station-Id = "192.168.139.100" - Acct-Status-Type = Start - Acct-Authentic = RADIUS - Acct-Session-Id = "45c731e169d9a4f1" - Acct-Session-Time = 0 - Acct-Input-Octets = 0 - Acct-Output-Octets = 0 - Acct-Input-Packets = 0 - Acct-Output-Packets = 0 - Acct-Input-Gigawords = 0 - Acct-Output-Gigawords = 0 - Framed-IP-Address = 10.0.0.2 - NAS-IP-Address = 192.168.139.100 - Event-Timestamp = "Feb 21 2024 13:37:17 UTC" - Tmp-String-9 = "ai:" - Acct-Unique-Session-Id = "ea6a1089816f19c0d0f1819bc61c3318" - Timestamp = 1708522637 -``` diff --git a/docs/configexamples/md-nmp.md b/docs/configexamples/md-nmp.md deleted file mode 100644 index 63231a09..00000000 --- a/docs/configexamples/md-nmp.md +++ /dev/null @@ -1,76 +0,0 @@ ---- -lastproofread: '2023-03-26' ---- - -(examples-nmp)= - -# NMP example - -Consider how to quickly set up NMP and VyOS for monitoring. -NMP is multi-vendor network monitoring from 'SolarWinds' built to -scale and expand with the needs of your network. - -## Configuration 'VyOS' - -First prepare our VyOS router for connection to NMP. We have to set -up the SNMP protocol and connectivity between the router and NMP. - -% stop_vyoslinter - -```none -set interfaces ethernet eth0 address 'dhcp' -set system name-server '8.8.8.8' -set service snmp community router authorization 'test' -set service snmp community router network '0.0.0.0/0' -``` - -% start_vyoslinter - - -## Configuration 'NMP' - -Next, you should just follow the pictures: - -```{image} /_static/images/nmp1.webp -:align: center -:alt: Network Topology Diagram -:width: 80% -``` - -```{image} /_static/images/nmp2.webp -:align: center -:alt: Network Topology Diagram -:width: 80% -``` - -```{image} /_static/images/nmp3.webp -:align: center -:alt: Network Topology Diagram -:width: 80% -``` - -```{image} /_static/images/nmp4.webp -:align: center -:alt: Network Topology Diagram -:width: 80% -``` - -```{image} /_static/images/nmp5.webp -:align: center -:alt: Network Topology Diagram -:width: 80% -``` - -```{image} /_static/images/nmp6.webp -:align: center -:alt: Network Topology Diagram -:width: 80% -``` - -```{image} /_static/images/nmp7.webp -:align: center -:alt: Network Topology Diagram -:width: 80% -``` - -In the end, you'll get a powerful instrument for monitoring the VyOS systems. diff --git a/docs/configexamples/md-ospf-unnumbered.md b/docs/configexamples/md-ospf-unnumbered.md deleted file mode 100644 index 9174d1b4..00000000 --- a/docs/configexamples/md-ospf-unnumbered.md +++ /dev/null @@ -1,118 +0,0 @@ ---- -lastproofread: '2021-06-29' ---- - -(examples-ospf-unnumbered)= - -# OSPF unnumbered with ECMP - -General information can be found in the {ref}`routing-ospf` chapter. - -## Configuration - -- Router A: - -```none -set interfaces ethernet eth0 address '10.0.0.1/24' -set interfaces ethernet eth1 address '192.168.0.1/32' -set interfaces ethernet eth1 ip ospf authentication md5 key-id 1 md5-key 'yourpassword' -set interfaces ethernet eth1 ip ospf network 'point-to-point' -set interfaces ethernet eth2 address '192.168.0.1/32' -set interfaces ethernet eth2 ip ospf authentication md5 key-id 1 md5-key 'yourpassword' -set interfaces ethernet eth2 ip ospf network 'point-to-point' -set interfaces loopback lo address '192.168.0.1/32' -set protocols ospf area 0.0.0.0 authentication 'md5' -set protocols ospf area 0.0.0.0 network '192.168.0.1/32' -set protocols ospf parameters router-id '192.168.0.1' -set protocols ospf redistribute connected -``` - -- Router B: - -```none -set interfaces ethernet eth0 address '10.0.0.2/24' -set interfaces ethernet eth1 address '192.168.0.2/32' -set interfaces ethernet eth1 ip ospf authentication md5 key-id 1 md5-key 'yourpassword' -set interfaces ethernet eth1 ip ospf network 'point-to-point' -set interfaces ethernet eth2 address '192.168.0.2/32' -set interfaces ethernet eth2 ip ospf authentication md5 key-id 1 md5-key 'yourpassword' -set interfaces ethernet eth2 ip ospf network 'point-to-point' -set interfaces loopback lo address '192.168.0.2/32' -set protocols ospf area 0.0.0.0 authentication 'md5' -set protocols ospf area 0.0.0.0 network '192.168.0.2/32' -set protocols ospf parameters router-id '192.168.0.2' -set protocols ospf redistribute connected -``` - - -## Results - -- Router A: - -```none -vyos@vyos:~$ show interfaces -Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down -Interface IP Address S/L Description ---------- ---------- --- ----------- -eth0 10.0.0.1/24 u/u -eth1 192.168.0.1/32 u/u -eth2 192.168.0.1/32 u/u -lo 127.0.0.1/8 u/u - 192.168.0.1/32 - ::1/128 -``` - -```none -vyos@vyos:~$ show ip route -Codes: K - kernel route, C - connected, S - static, R - RIP, - O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, - T - Table, v - VNC, V - VNC-Direct, A - Babel, D - SHARP, - F - PBR, f - OpenFabric, - > - selected route, * - FIB route, q - queued route, r - rejected route - -S>* 0.0.0.0/0 [210/0] via 10.0.0.254, eth0, 00:57:34 -O 10.0.0.0/24 [110/20] via 192.168.0.2, eth1 onlink, 00:13:21 - via 192.168.0.2, eth2 onlink, 00:13:21 -C>* 10.0.0.0/24 is directly connected, eth0, 00:57:35 -O 192.168.0.1/32 [110/0] is directly connected, lo, 00:48:53 -C * 192.168.0.1/32 is directly connected, eth2, 00:56:31 -C * 192.168.0.1/32 is directly connected, eth1, 00:56:31 -C>* 192.168.0.1/32 is directly connected, lo, 00:57:36 -O>* 192.168.0.2/32 [110/1] via 192.168.0.2, eth1 onlink, 00:29:03 - * via 192.168.0.2, eth2 onlink, 00:29:03 -``` - -- Router B: - -```none -vyos@vyos:~$ show interfaces -Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down -Interface IP Address S/L Description ---------- ---------- --- ----------- -eth0 10.0.0.2/24 u/u -eth1 192.168.0.2/32 u/u -eth2 192.168.0.2/32 u/u -lo 127.0.0.1/8 u/u - 192.168.0.2/32 - ::1/128 -``` - -```none -vyos@vyos:~$ show ip route -Codes: K - kernel route, C - connected, S - static, R - RIP, - O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, - T - Table, v - VNC, V - VNC-Direct, A - Babel, D - SHARP, - F - PBR, f - OpenFabric, - > - selected route, * - FIB route, q - queued route, r - rejected route - -S>* 0.0.0.0/0 [210/0] via 10.0.0.254, eth0, 00:57:34 -O 10.0.0.0/24 [110/20] via 192.168.0.1, eth1 onlink, 00:13:21 - via 192.168.0.1, eth2 onlink, 00:13:21 -C>* 10.0.0.0/24 is directly connected, eth0, 00:57:35 -O 192.168.0.2/32 [110/0] is directly connected, lo, 00:48:53 -C * 192.168.0.2/32 is directly connected, eth2, 00:56:31 -C * 192.168.0.2/32 is directly connected, eth1, 00:56:31 -C>* 192.168.0.2/32 is directly connected, lo, 00:57:36 -O>* 192.168.0.1/32 [110/1] via 192.168.0.1, eth1 onlink, 00:29:03 - * via 192.168.0.1, eth2 onlink, 00:29:03 -``` diff --git a/docs/configexamples/md-policy-based-ipsec-and-firewall.md b/docs/configexamples/md-policy-based-ipsec-and-firewall.md deleted file mode 100644 index 86bc9318..00000000 --- a/docs/configexamples/md-policy-based-ipsec-and-firewall.md +++ /dev/null @@ -1,269 +0,0 @@ -(examples-policy-based-ipsec-and-firewall)= - -# Policy-Based Site-to-Site VPN and Firewall Configuration - -This guide shows an example policy-based IKEv2 site-to-site VPN between two -VyOS routers, and firewall configuration. - -For simplicity, configuration and tests are done only using IPv4, and firewall -configuration is done only on one router. - -## Network Topology and requirements - -This configuration example and the requirements consists of: - -- Two VyOS routers with public IP address. - -- 2 private subnets on each site. - -- Local subnets should be able to reach internet using source NAT. - -- Communication between private subnets should be done through IPSec tunnel - without NAT. - -- Configuration of basic firewall in one site, in order to: - - > - Protect the router on 'WAN' interface, allowing only IPSec connections - > and SSH access from trusted IPs. - > - Allow access to the router only from trusted networks. - > - Allow DNS requests only only for local networks. - > - Allow ICMP on all interfaces. - > - Allow all new connections from local subnets. - > - Allow connections from LANs to LANs through the tunnel. - -```{image} /_static/images/policy-based-ipsec-and-firewall.webp -``` - - -## Configuration - -Interface and routing configuration: - -```none -# LEFT router: -set interfaces ethernet eth0 address '198.51.100.14/30' -set interfaces ethernet eth1 vif 111 address '10.1.11.1/24' -set interfaces ethernet eth2 vif 112 address '10.1.12.1/24' -set protocols static route 0.0.0.0/0 next-hop 198.51.100.13 - -# RIGHT router: -set interfaces ethernet eth0 address '192.0.2.130/30' -set interfaces ethernet eth1 vif 221 address '10.2.21.1/24' -set interfaces ethernet eth2 vif 222 address '10.2.22.1/24' -``` - -IPSec configuration: - -```none -# LEFT router: -set vpn ipsec authentication psk RIGHT id '198.51.100.14' -set vpn ipsec authentication psk RIGHT id '192.0.2.130' -set vpn ipsec authentication psk RIGHT secret 'p4ssw0rd' -set vpn ipsec esp-group ESP-GROUP mode 'tunnel' -set vpn ipsec esp-group ESP-GROUP proposal 1 encryption 'aes256' -set vpn ipsec esp-group ESP-GROUP proposal 1 hash 'sha256' -set vpn ipsec ike-group IKE-GROUP key-exchange 'ikev2' -set vpn ipsec ike-group IKE-GROUP proposal 1 dh-group '14' -set vpn ipsec ike-group IKE-GROUP proposal 1 encryption 'aes256' -set vpn ipsec ike-group IKE-GROUP proposal 1 hash 'sha256' -set vpn ipsec interface 'eth0' -set vpn ipsec site-to-site peer RIGHT authentication mode 'pre-shared-secret' -set vpn ipsec site-to-site peer RIGHT connection-type 'initiate' -set vpn ipsec site-to-site peer RIGHT default-esp-group 'ESP-GROUP' -set vpn ipsec site-to-site peer RIGHT ike-group 'IKE-GROUP' -set vpn ipsec site-to-site peer RIGHT local-address '198.51.100.14' -set vpn ipsec site-to-site peer RIGHT remote-address '192.0.2.130' -set vpn ipsec site-to-site peer RIGHT tunnel 0 local prefix '10.1.11.0/24' -set vpn ipsec site-to-site peer RIGHT tunnel 0 remote prefix '10.2.21.0/24' -set vpn ipsec site-to-site peer RIGHT tunnel 1 local prefix '10.1.11.0/24' -set vpn ipsec site-to-site peer RIGHT tunnel 1 remote prefix '10.2.22.0/24' -set vpn ipsec site-to-site peer RIGHT tunnel 2 local prefix '10.1.12.0/24' -set vpn ipsec site-to-site peer RIGHT tunnel 2 remote prefix '10.2.21.0/24' -set vpn ipsec site-to-site peer RIGHT tunnel 3 local prefix '10.1.12.0/24' -set vpn ipsec site-to-site peer RIGHT tunnel 3 remote prefix '10.2.22.0/24' - -# RIGHT router: -set vpn ipsec authentication psk LEFT id '192.0.2.130' -set vpn ipsec authentication psk LEFT id '198.51.100.14' -set vpn ipsec authentication psk LEFT secret 'p4ssw0rd' -set vpn ipsec esp-group ESP-GROUP mode 'tunnel' -set vpn ipsec esp-group ESP-GROUP proposal 1 encryption 'aes256' -set vpn ipsec esp-group ESP-GROUP proposal 1 hash 'sha256' -set vpn ipsec ike-group IKE-GROUP key-exchange 'ikev2' -set vpn ipsec ike-group IKE-GROUP proposal 1 dh-group '14' -set vpn ipsec ike-group IKE-GROUP proposal 1 encryption 'aes256' -set vpn ipsec ike-group IKE-GROUP proposal 1 hash 'sha256' -set vpn ipsec interface 'eth0' -set vpn ipsec site-to-site peer LEFT authentication mode 'pre-shared-secret' -set vpn ipsec site-to-site peer LEFT connection-type 'none' -set vpn ipsec site-to-site peer LEFT default-esp-group 'ESP-GROUP' -set vpn ipsec site-to-site peer LEFT ike-group 'IKE-GROUP' -set vpn ipsec site-to-site peer LEFT local-address '192.0.2.130' -set vpn ipsec site-to-site peer LEFT remote-address '198.51.100.14' -set vpn ipsec site-to-site peer LEFT tunnel 0 local prefix '10.2.21.0/24' -set vpn ipsec site-to-site peer LEFT tunnel 0 remote prefix '10.1.11.0/24' -set vpn ipsec site-to-site peer LEFT tunnel 1 local prefix '10.2.22.0/24' -set vpn ipsec site-to-site peer LEFT tunnel 1 remote prefix '10.1.11.0/24' -set vpn ipsec site-to-site peer LEFT tunnel 2 local prefix '10.2.21.0/24' -set vpn ipsec site-to-site peer LEFT tunnel 2 remote prefix '10.1.12.0/24' -set vpn ipsec site-to-site peer LEFT tunnel 3 local prefix '10.2.22.0/24' -set vpn ipsec site-to-site peer LEFT tunnel 3 remote prefix '10.1.12.0/24' -``` - -Firewall Configuration: - -```none -# Firewall Groups: -set firewall group network-group LOCAL-NETS network '10.1.11.0/24' -set firewall group network-group LOCAL-NETS network '10.1.12.0/24' -set firewall group network-group REMOTE-NETS network '10.2.21.0/24' -set firewall group network-group REMOTE-NETS network '10.2.22.0/24' -set firewall group network-group TRUSTED network '198.51.100.125/32' -set firewall group network-group TRUSTED network '203.0.113.0/24' -set firewall group network-group TRUSTED network '10.1.11.0/24' -set firewall group network-group TRUSTED network '192.168.70.0/24' - -# Forward traffic: default drop and only allow what is needed -set firewall ipv4 forward filter default-action 'drop' - -# Forward traffic: global state policies -set firewall ipv4 forward filter rule 1 action 'accept' -set firewall ipv4 forward filter rule 1 state established 'enable' -set firewall ipv4 forward filter rule 1 state related 'enable' -set firewall ipv4 forward filter rule 2 action 'drop' -set firewall ipv4 forward filter rule 2 state invalid 'enable' - -# Forward traffic: Accept all connections from local networks -set firewall ipv4 forward filter rule 10 action 'accept' -set firewall ipv4 forward filter rule 10 source group network-group 'LOCAL-NETS' - -# Forward traffic: accept connections from remote LANs to local LANs -set firewall ipv4 forward filter rule 20 action 'accept' -set firewall ipv4 forward filter rule 20 destination group network-group 'LOCAL-NETS' -set firewall ipv4 forward filter rule 20 source group network-group 'REMOTE-NETS' - -# Input traffic: default drop and only allow what is needed -set firewall ipv4 input filter default-action 'drop' - -# Input traffic: global state policies -set firewall ipv4 input filter rule 1 action 'accept' -set firewall ipv4 input filter rule 1 state established 'enable' -set firewall ipv4 input filter rule 1 state related 'enable' -set firewall ipv4 input filter rule 2 action 'drop' -set firewall ipv4 input filter rule 2 state invalid 'enable' - -# Input traffic: add rules needed for ipsec connection -set firewall ipv4 input filter rule 10 action 'accept' -set firewall ipv4 input filter rule 10 destination port '500,4500' -set firewall ipv4 input filter rule 10 inbound-interface name 'eth0' -set firewall ipv4 input filter rule 10 protocol 'udp' -set firewall ipv4 input filter rule 15 action 'accept' -set firewall ipv4 input filter rule 15 inbound-interface name 'eth0' -set firewall ipv4 input filter rule 15 protocol 'esp' - -# Input traffic: accept ssh connection from trusted ips -set firewall ipv4 input filter rule 20 action 'accept' -set firewall ipv4 input filter rule 20 destination port '22' -set firewall ipv4 input filter rule 20 protocol 'tcp' -set firewall ipv4 input filter rule 20 source group network-group 'TRUSTED' - -# Input traffic: accept dns requests only from local networks. -set firewall ipv4 input filter rule 25 action 'accept' -set firewall ipv4 input filter rule 25 destination port '53' -set firewall ipv4 input filter rule 25 protocol 'udp' -set firewall ipv4 input filter rule 25 source group network-group 'LOCAL-NETS' - -# Input traffic: allow icmp -set firewall ipv4 input filter rule 30 action 'accept' -set firewall ipv4 input filter rule 30 protocol 'icmp' -``` - -And NAT Configuration: - -```none -set nat source rule 10 destination group network-group 'REMOTE-NETS' -set nat source rule 10 exclude -set nat source rule 10 outbound-interface name 'eth0' -set nat source rule 10 source group network-group 'LOCAL-NETS' -set nat source rule 20 outbound-interface name 'eth0' -set nat source rule 20 source group network-group 'LOCAL-NETS' -set nat source rule 20 translation address 'masquerade' -``` - -## Checking through op-mode commands - -After some testing, we can check IPSec status, and counter on every tunnel: - -```none -vyos@LEFT:~$ show vpn ipsec sa -Connection State Uptime Bytes In/Out Packets In/Out Remote address Remote ID Proposal --------------- ------- -------- -------------- ---------------- ---------------- ----------- --------------------------------------- -RIGHT-tunnel-0 up 36m24s 840B/840B 10/10 192.0.2.130 192.0.2.130 AES_CBC_256/HMAC_SHA2_256_128/MODP_2048 -RIGHT-tunnel-1 up 36m33s 588B/588B 7/7 192.0.2.130 192.0.2.130 AES_CBC_256/HMAC_SHA2_256_128/MODP_2048 -RIGHT-tunnel-2 up 35m50s 1K/1K 15/15 192.0.2.130 192.0.2.130 AES_CBC_256/HMAC_SHA2_256_128/MODP_2048 -RIGHT-tunnel-3 up 36m54s 2K/2K 32/32 192.0.2.130 192.0.2.130 AES_CBC_256/HMAC_SHA2_256_128/MODP_2048 -vyos@LEFT:~$ -``` - -Also, we can check firewall counters: - -```none -vyos@LEFT:~$ show firewall -Rulesets Information - ---------------------------------- -IPv4 Firewall "forward filter" - -Rule Action Protocol Packets Bytes Conditions -------- -------- ---------- --------- ------- ------------------------------------------------------ -1 accept all 681 96545 ct state { established, related } accept -2 drop all 0 0 ct state invalid -10 accept all 360 27205 ip saddr @N_LOCAL-NETS accept -20 accept all 8 648 ip daddr @N_LOCAL-NETS ip saddr @N_REMOTE-NETS accept -default drop all - ---------------------------------- -IPv4 Firewall "input filter" - -Rule Action Protocol Packets Bytes Conditions -------- -------- ---------- --------- ------- ---------------------------------------------- -1 accept all 901 123709 ct state { established, related } accept -2 drop all 0 0 ct state invalid -10 accept udp 0 0 udp dport { 500, 4500 } iifname "eth0" accept -15 accept esp 0 0 meta l4proto esp iifname "eth0" accept -20 accept tcp 1 60 tcp dport 22 ip saddr @N_TRUSTED accept -25 accept udp 0 0 udp dport 53 ip saddr @N_LOCAL-NETS accept -30 accept icmp 0 0 meta l4proto icmp accept -default drop all - -vyos@LEFT:~$ -vyos@LEFT:~$ show firewall statistics -Rulesets Statistics - ---------------------------------- -IPv4 Firewall "forward filter" - -Rule Packets Bytes Action Source Destination Inbound-Interface Outbound-interface -------- --------- ------- -------- ----------- ------------- ------------------- -------------------- -1 681 96545 accept any any any any -2 0 0 drop any any any any -10 360 27205 accept LOCAL-NETS any any any -20 8 648 accept REMOTE-NETS LOCAL-NETS any any -default N/A N/A drop any any any any - ---------------------------------- -IPv4 Firewall "input filter" - -Rule Packets Bytes Action Source Destination Inbound-Interface Outbound-interface -------- --------- ------- -------- ---------- ------------- ------------------- -------------------- -1 905 124213 accept any any any any -2 0 0 drop any any any any -10 0 0 accept any any eth0 any -15 0 0 accept any any eth0 any -20 1 60 accept TRUSTED any any any -25 0 0 accept LOCAL-NETS any any any -30 0 0 accept any any any any -default N/A N/A drop any any any any - -vyos@LEFT:~$ -``` diff --git a/docs/configexamples/md-pppoe-ipv6-basic.md b/docs/configexamples/md-pppoe-ipv6-basic.md deleted file mode 100644 index 76984f4b..00000000 --- a/docs/configexamples/md-pppoe-ipv6-basic.md +++ /dev/null @@ -1,114 +0,0 @@ ---- -lastproofread: '2021-06-29' ---- - -(examples-pppoe-ipv6-basic)= - -# PPPoE IPv6 Basic Setup for Home Network - -This document is to describe a basic setup using PPPoE with DHCPv6-PD + -SLAAC to construct a typical home network. The user can follow the steps -described here to quickly setup a working network and use this as a starting -point to further configure or fine-tune other settings. - -To achieve this, your ISP is required to support DHCPv6-PD. If you're not sure, -please contact your ISP for more information. - -## Network Topology - -```{image} /_static/images/pppoe-ipv6-pd-diagram.webp -:align: center -:alt: Network Topology Diagram -:width: 60% -``` - - -## Configurations - -### PPPoE Setup - -```none -set interfaces pppoe pppoe0 authentication password -set interfaces pppoe pppoe0 authentication username -set interfaces pppoe pppoe0 service-name -set interfaces pppoe pppoe0 source-interface 'eth0' -``` - -- Fill `password` and `user` with the credential provided by your ISP. -- `service-name` can be an arbitrary string. - -### DHCPv6-PD Setup - -During address configuration, in addition to assigning an address to the WAN -interface, ISP also provides a prefix to allow the router to configure addresses -of LAN interface and other nodes connecting to LAN, which is called prefix -delegation (PD). - -```none -set interfaces pppoe pppoe0 ipv6 address autoconf -set interfaces pppoe pppoe0 dhcpv6-options pd 0 interface eth1 address '100' -``` - -- Here we use the prefix to configure the address of eth1 (LAN) to form - `::64`, where `64` is hexadecimal of address 100. - - - -- For home network users, most of time ISP only provides /64 prefix, hence - there is no need to set SLA ID and prefix length. See {ref}`pppoe-interface` - for more information. - -### Router Advertisement - -We need to enable router advertisement for LAN network so that PC can receive -the prefix and use SLAAC to configure the address automatically. - -```none -set service router-advert interface eth1 link-mtu '1492' -set service router-advert interface eth1 name-server -set service router-advert interface eth1 prefix ::/64 valid-lifetime '172800' -``` - -- Set MTU in advertisement to 1492 because of PPPoE header overhead. -- Set DNS server address in the advertisement so that clients can obtain it by - using RDNSS option. Most operating systems (Windows, Linux, Mac) should - already support it. -- Here we set the prefix to `::/64` to indicate advertising any /64 prefix - the LAN interface is assigned. -- Since some ISPs disconnects continuous connection for every 2~3 days, we set - `valid-lifetime` to 2 days to allow PC for phasing out old address. - -### Basic Firewall - -To have basic protection while keeping IPv6 network functional, we need to: -- Allow all established and related traffic for router and LAN -- Allow all icmpv6 packets for router and LAN -- Allow DHCPv6 packets for router - -```none -set firewall ipv6 name WAN_IN default-action 'drop' -set firewall ipv6 name WAN_IN rule 10 action 'accept' -set firewall ipv6 name WAN_IN rule 10 state established 'enable' -set firewall ipv6 name WAN_IN rule 10 state related 'enable' -set firewall ipv6 name WAN_IN rule 20 action 'accept' -set firewall ipv6 name WAN_IN rule 20 protocol 'icmpv6' -set firewall ipv6 name WAN_LOCAL default-action 'drop' -set firewall ipv6 name WAN_LOCAL rule 10 action 'accept' -set firewall ipv6 name WAN_LOCAL rule 10 state established 'enable' -set firewall ipv6 name WAN_LOCAL rule 10 state related 'enable' -set firewall ipv6 name WAN_LOCAL rule 20 action 'accept' -set firewall ipv6 name WAN_LOCAL rule 20 protocol 'icmpv6' -set firewall ipv6 name WAN_LOCAL rule 30 action 'accept' -set firewall ipv6 name WAN_LOCAL rule 30 destination port '546' -set firewall ipv6 name WAN_LOCAL rule 30 protocol 'udp' -set firewall ipv6 name WAN_LOCAL rule 30 source port '547' -set firewall ipv6 forward filter rule 10 action jump -set firewall ipv6 forward filter rule 10 jump-target 'WAN_IN' -set firewall ipv6 forward filter rule 10 inbound-interface name 'pppoe0' -set firewall ipv6 input filter rule 10 action jump -set firewall ipv6 input filter rule 10 jump-target 'WAN_LOCAL' -set firewall ipv6 input filter rule 10 inbound-interface name 'pppoe0' -``` - -Note to allow the router to receive DHCPv6 response from ISP. We need to allow -packets with source port 547 (server) and destination port 546 (client). diff --git a/docs/configexamples/md-qos.md b/docs/configexamples/md-qos.md deleted file mode 100644 index e8335584..00000000 --- a/docs/configexamples/md-qos.md +++ /dev/null @@ -1,201 +0,0 @@ ---- -lastproofread: '2023-02-18' ---- - -(examples-qos)= - -# QoS example - -## Configuration 'dcsp' and shaper using QoS - -In this case, we'll try to make a simple lab using QoS and the -general ability of the VyOS system. -We recommend you to go through the main article about -[QoS](https://docs.vyos.io/en/latest/configuration/trafficpolicy/index.html) -first. - -Using the general schema for example: - -```{image} /_static/images/qos1.webp -:align: center -:alt: Network Topology Diagram -:width: 80% -``` - -We have four hosts on the local network 172.17.1.0/24. All hosts are -labeled CS0 by default. We need to replace labels on all hosts except -vpc8. -We will replace the labels on the nearest router “VyOS3” using the IP -addresses of the sources. - -- 172.17.1.2 CS0 -> CS4 -- 172.17.1.3 CS0 -> CS5 -- 172.17.1.4 CS0 -> CS6 -- 172.17.1.40 CS0 by default - -Next, we will replace only all CS4 labels on the “VyOS2” router. - -- CS4 -> CS5 - -In the end, we will configure the traffic shaper using QoS mechanisms -on the “VYOS2” router. - -## Configuration: - -Set IP addresses on all VPCs and a default gateway 172.17.1.1. We'll -use in this case only static routes. -On the VyOS3 router, we need to change the 'dscp' labels for the -VPCs. To do this, we use this configuration. - -```none -set interfaces ethernet eth0 address '10.1.1.100/24' -set interfaces ethernet eth1 address '172.17.1.1/24' -set protocols static route 0.0.0.0/0 next-hop 10.1.1.1 -set qos policy shaper vyos3 class 10 match ADDRESS10 ip source address '172.17.1.2/32' -set qos policy shaper vyos3 class 10 set-dscp 'CS4' -set qos policy shaper vyos3 class 20 match ADDRESS20 ip source address '172.17.1.3/32' -set qos policy shaper vyos3 class 20 set-dscp 'CS5' -set qos policy shaper vyos3 class 30 match ADDRESS30 ip source address '172.17.1.4/32' -set qos policy shaper vyos3 class 30 set-dscp 'CS6' -set qos policy shaper vyos3 default bandwidth '10%' -set qos policy shaper vyos3 default ceiling '100%' -set qos policy shaper vyos3 default priority '7' -set qos policy shaper vyos3 default queue-type 'fair-queue' -set qos interface eth0 egress 'vyos3' -``` - -Main rules: - -- ADDRESS10 change CS0 -> CS4 source 172.17.1.2/32 -- ADDRESS20 change CS0 -> CS5 source 172.17.1.3/32 -- ADDRESS30 change CS0 -> CS6 source 172.17.1.4/32 - -Check the result - -```{image} /_static/images/qos2.webp -:align: center -:alt: Network Topology Diagram -:width: 80% -``` - -Before the interface eth0 on router VyOS3 - -```{image} /_static/images/qos3.webp -:align: center -:alt: Network Topology Diagram -:width: 80% -``` - -After the interface eth0 on router VyOS3 - -```{image} /_static/images/qos4.webp -:align: center -:alt: Network Topology Diagram -:width: 80% -``` - -On the router, VyOS4 set all traffic as CS4. We have to configure the -default class and class for changing all labels from CS0 to CS4 - -```none -set interfaces ethernet eth0 address '10.2.1.100/24' -set protocols static route 0.0.0.0/0 next-hop 10.2.1.1 -set qos policy shaper vyos4 class 10 bandwidth '100%' -set qos policy shaper vyos4 class 10 burst '15k' -set qos policy shaper vyos4 class 10 match ALL ether protocol 'all' -set qos policy shaper vyos4 class 10 queue-type 'fair-queue' -set qos policy shaper vyos4 class 10 set-dscp 'CS4' -set qos policy shaper vyos4 default bandwidth '10%' -set qos policy shaper vyos4 default burst '15k' -set qos policy shaper vyos4 default ceiling '100%' -set qos policy shaper vyos4 default priority '7' -set qos policy shaper vyos4 default queue-type 'fair-queue' - set qos interface eth0 egress 'vyos4' -``` - -Next on the router VyOS2 we will change labels on all incoming -traffic only from CS4-> CS6 - -```{image} /_static/images/qos5.webp -:align: center -:alt: Network Topology Diagram -:width: 80% -``` - -```none -set interfaces ethernet eth0 address '10.1.1.1/24' -set interfaces ethernet eth1 address '10.2.1.1/24' -set interfaces ethernet eth2 address '10.9.9.1/24' -set protocols static route 172.17.1.0/24 next-hop 10.1.1.100 -set qos policy shaper vyos2 class 10 bandwidth '100%' -set qos policy shaper vyos2 class 10 burst '15k' -set qos policy shaper vyos2 class 10 match VYOS2 ip dscp 'CS4' -set qos policy shaper vyos2 class 10 queue-type 'fair-queue' -set qos policy shaper vyos2 class 10 set-dscp 'CS5' -set qos policy shaper vyos2 default bandwidth '100%' -set qos policy shaper vyos2 default burst '15k' -set qos policy shaper vyos2 default ceiling '100%' -set qos policy shaper vyos2 default priority '7' -set qos policy shaper vyos2 default queue-type 'fair-queue' - set qos interface eth2 egress 'vyos2' -``` - -```{image} /_static/images/qos6.webp -:align: center -:alt: Network Topology Diagram -:width: 80% -``` - -- 172.17.1.2/24 CS0 - -```{image} /_static/images/qos7.webp -:align: center -:alt: Network Topology Diagram -:width: 80% -``` - -- 172.17.1.2/24 CS0 - > CS4 - -```{image} /_static/images/qos8.webp -:align: center -:alt: Network Topology Diagram -:width: 80% -``` - -- 172.17.1.2/24 CS4 - > CS5 - -```{image} /_static/images/qos9.webp -:align: center -:alt: Network Topology Diagram -:width: 80% -``` - -In the end, on the router “VyOS2” we will set outgoing bandwidth -limits between the “VyOS3” and “VyOS1” routers. Let's set a limit for -IP 10.1.1.100 = 5 Mbps(Tx). We will check the result of the work -with the help of the “iPerf” utility. - -Set up bandwidth limits on the eth2 interface of the router “VyOS2”. - -```none -vyos@vyos2# show qos policy shaper vyos2 class 20 -bandwidth 5mbit -description "for VyOS3 eth0" -match VyOS3 { - ip { - source { - address 10.1.1.100/32 - } - } -} -``` - -Check the result. - -```{image} /_static/images/qos10.webp -:align: center -:alt: Network Topology Diagram -:width: 80% -``` - -As we see shaper is working and the traffic will not work over 5 Mbit/s. diff --git a/docs/configexamples/md-segment-routing-isis.md b/docs/configexamples/md-segment-routing-isis.md deleted file mode 100644 index 41ba2389..00000000 --- a/docs/configexamples/md-segment-routing-isis.md +++ /dev/null @@ -1,277 +0,0 @@ ---- -lastproofread: '2023-04-10' ---- - -(examples-segment-routing-isis)= - -# Segment-routing IS-IS example - -When utilizing VyOS in an environment with Cisco IOS-XR gear you can use this -blue print as an initial setup to get MPLS ISIS-SR working between those two -devices.The lab was build using {abbr}`EVE-NG (Emulated Virtual -Environment NG)`. - -:::{figure} /_static/images/vyos-sr-isis.webp -:alt: ISIS-SR network - -ISIS-SR example network -::: - -The below configuration is used as example where we keep focus on -VyOS-P1/VyOS-P2/XRv-P3 which we share the settings. - -## Configuration - -- VyOS-P1: - -```none -set interfaces dummy dum0 address '192.0.2.1/32' -set interfaces ethernet eth1 address '192.0.2.5/30' -set interfaces ethernet eth1 mtu '8000' -set interfaces ethernet eth3 address '192.0.2.21/30' -set interfaces ethernet eth3 mtu '8000' -set protocols isis interface dum0 passive -set protocols isis interface eth1 network point-to-point -set protocols isis interface eth3 network point-to-point -set protocols isis level 'level-2' -set protocols isis log-adjacency-changes -set protocols isis metric-style 'wide' -set protocols isis net '49.0000.0000.0000.0001.00' -set protocols isis segment-routing maximum-label-depth '8' -set protocols isis segment-routing prefix 192.0.2.1/32 index value '1' -set protocols mpls interface 'eth1' -set protocols mpls interface 'eth3' -set system host-name 'P1-VyOS' -``` - -- XRv-P3: - -```none -hostname P3-VyOS -interface Loopback0 - ipv4 address 192.0.2.3 255.255.255.255 -! -interface GigabitEthernet0/0/0/1 - mtu 8014 - ipv4 address 192.0.2.6 255.255.255.252 -! -interface GigabitEthernet0/0/0/2 - mtu 8014 - ipv4 address 192.0.2.18 255.255.255.252 -! -router isis VyOS - is-type level-2-only - net 49.0000.0000.0000.0003.00 - log adjacency changes - address-family ipv4 unicast - metric-style wide - segment-routing mpls - ! - interface Loopback0 - passive - address-family ipv4 unicast - prefix-sid index 3 - ! - ! - interface GigabitEthernet0/0/0/1 - point-to-point - address-family ipv4 unicast - ! - ! - interface GigabitEthernet0/0/0/2 - point-to-point - address-family ipv4 unicast - ! - ! -! -``` - -- VyOS-P2: - -```none -set interfaces dummy dum0 address '192.0.2.2/32' -set interfaces ethernet eth2 address '192.0.2.17/30' -set interfaces ethernet eth2 mtu '8000' -set interfaces ethernet eth3 address '192.0.2.26/30' -set interfaces ethernet eth3 mtu '8000' -set protocols isis interface dum0 passive -set protocols isis interface eth2 network point-to-point -set protocols isis interface eth3 network point-to-point -set protocols isis level 'level-2' -set protocols isis log-adjacency-changes -set protocols isis metric-style 'wide' -set protocols isis net '49.0000.0000.0000.0002.00' -set protocols isis segment-routing maximum-label-depth '8' -set protocols isis segment-routing prefix 192.0.2.2/32 index value '2' -set protocols mpls interface 'eth2' -set protocols mpls interface 'eth3' -set system host-name 'P2-VyOS' -``` - -This gives us MPLS segment routing enabled and labels forwarding : - -```none -vyos@P1-VyOS:~$ show mpls table -Inbound Label Type Nexthop Outbound Label ------------------------------------------------------------------ -15000 SR (IS-IS) 192.0.2.6 implicit-null -15001 SR (IS-IS) 192.0.2.22 implicit-null -15002 SR (IS-IS) fe80::5200:ff:fe04:3 implicit-null -16002 SR (IS-IS) 192.0.2.6 16002 -16003 SR (IS-IS) 192.0.2.6 implicit-null -16011 SR (IS-IS) 192.0.2.22 implicit-null - -vyos@P2-VyOS:~$ show mpls table -Inbound Label Type Nexthop Outbound Label -------------------------------------------------------- -15000 SR (IS-IS) 192.0.2.18 implicit-null -16001 SR (IS-IS) 192.0.2.18 16001 -16003 SR (IS-IS) 192.0.2.18 implicit-null -16011 SR (IS-IS) 192.0.2.18 16011 - -RP/0/0/CPU0:P3-VyOS#show mpls forwarding -Tue Mar 28 17:47:18.928 UTC -Local Outgoing Prefix Outgoing Next Hop Bytes -Label Label or ID Interface Switched ------- ----------- ------------------ ------------ --------------- ------------ -16001 Pop SR Pfx (idx 1) Gi0/0/0/1 192.0.2.5 0 -16002 Pop SR Pfx (idx 2) Gi0/0/0/2 192.0.2.17 0 -16011 16011 SR Pfx (idx 11) Gi0/0/0/1 192.0.2.5 0 -24000 Pop SR Adj (idx 1) Gi0/0/0/1 192.0.2.5 0 -24001 Pop SR Adj (idx 3) Gi0/0/0/1 192.0.2.5 0 -24002 Pop SR Adj (idx 1) Gi0/0/0/2 192.0.2.17 0 -24003 Pop SR Adj (idx 3) Gi0/0/0/2 192.0.2.17 0 -``` - -VyOS is able to check MSD per devices: - -```none -vyos@P1-VyOS:~$ show isis segment-routing node -Area VyOS: -IS-IS L1 SR-Nodes: - -IS-IS L2 SR-Nodes: - -System ID SRGB SRLB Algorithm MSD ---------------------------------------------------------------- -0000.0000.0001 16000 - 23999 15000 - 15999 SPF 8 -0000.0000.0002 16000 - 23999 15000 - 15999 SPF 8 -0000.0000.0003 16000 - 23999 0 - 4294967295 SPF 10 -0000.0000.0011 16000 - 23999 15000 - 15999 SPF 8 - -vyos@P2-VyOS:~$ show isis segment-routing node -Area VyOS: - IS-IS L1 SR-Nodes: - - IS-IS L2 SR-Nodes: - - System ID SRGB SRLB Algorithm MSD - --------------------------------------------------------------- - 0000.0000.0001 16000 - 23999 15000 - 15999 SPF 8 - 0000.0000.0002 16000 - 23999 15000 - 15999 SPF 8 - 0000.0000.0003 16000 - 23999 0 - 4294967295 SPF 10 - 0000.0000.0011 16000 - 23999 15000 - 15999 SPF 8 -``` - -Here is the routing tables showing the MPLS segment routing label operations: - -```none -vyos@P1-VyOS:~$ show ip route isis -Codes: K - kernel route, C - connected, S - static, R - RIP, - O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, - T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, - f - OpenFabric, - > - selected route, * - FIB route, q - queued, r - rejected, b - backup - t - trapped, o - offload failure - -I>* 192.0.2.2/32 [115/30] via 192.0.2.6, eth1, label 16002, weight 1, 1d03h18m -I>* 192.0.2.3/32 [115/10] via 192.0.2.6, eth1, label implicit-null, weight 1, 1d03h18m -I 192.0.2.4/30 [115/20] via 192.0.2.6, eth1 inactive, weight 1, 1d03h18m -I>* 192.0.2.11/32 [115/20] via 192.0.2.22, eth3, label implicit-null, weight 1, 1d02h47m -I>* 192.0.2.16/30 [115/20] via 192.0.2.6, eth1, weight 1, 1d03h18m -I 192.0.2.20/30 [115/20] via 192.0.2.22, eth3 inactive, weight 1, 1d02h48m -I>* 192.0.2.24/30 [115/30] via 192.0.2.6, eth1, weight 1, 1d03h18m - - -vyos@P2-VyOS:~$ show ip route isis -Codes: K - kernel route, C - connected, S - static, R - RIP, - O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, - T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, - f - OpenFabric, - > - selected route, * - FIB route, q - queued, r - rejected, b - backup - t - trapped, o - offload failure - -I>* 192.0.2.1/32 [115/30] via 192.0.2.18, eth2, label 16001, weight 1, 1d03h17m -I>* 192.0.2.3/32 [115/10] via 192.0.2.18, eth2, label implicit-null, weight 1, 1d03h17m -I>* 192.0.2.4/30 [115/20] via 192.0.2.18, eth2, weight 1, 1d03h17m -I>* 192.0.2.11/32 [115/40] via 192.0.2.18, eth2, label 16011, weight 1, 1d02h47m -I 192.0.2.16/30 [115/20] via 192.0.2.18, eth2 inactive, weight 1, 1d03h17m -I>* 192.0.2.20/30 [115/30] via 192.0.2.18, eth2, weight 1, 1d03h17m - -RP/0/0/CPU0:P3-VyOS#show route isis -Tue Mar 28 18:19:16.417 UTC - -i L2 192.0.2.1/32 [115/20] via 192.0.2.5, 1d03h, GigabitEthernet0/0/0/1 -i L2 192.0.2.2/32 [115/20] via 192.0.2.17, 1d03h, GigabitEthernet0/0/0/2 -i L2 192.0.2.11/32 [115/30] via 192.0.2.5, 1d02h, GigabitEthernet0/0/0/1 -i L2 192.0.2.20/30 [115/20] via 192.0.2.5, 1d03h, GigabitEthernet0/0/0/1 -i L2 192.0.2.24/30 [115/20] via 192.0.2.17, 1d03h, GigabitEthernet0/0/0/2 -``` - -Information about prefix-sid and label-operation from VyOS - -```none -vyos@P1-VyOS:~$ show isis route prefix-sid -Area VyOS: -IS-IS L2 IPv4 routing table: - - Prefix Metric Interface Nexthop SID Label Op. - ---------------------------------------------------------------------- - 192.0.2.1/32 0 - - - - - 192.0.2.2/32 30 eth1 192.0.2.6 2 Swap(16002, 16002) - 192.0.2.3/32 10 eth1 192.0.2.6 3 Pop(16003) - 192.0.2.4/30 20 eth1 192.0.2.6 - - - 192.0.2.16/30 20 eth1 192.0.2.6 - - - 192.0.2.20/30 0 - - - - - 192.0.2.24/30 30 eth1 192.0.2.6 - - - - vyos@P2-VyOS:~$ show isis route prefix-sid - Area VyOS: - IS-IS L2 IPv4 routing table: - - Prefix Metric Interface Nexthop SID Label Op. - ----------------------------------------------------------------------- - 192.0.2.1/32 30 eth2 192.0.2.18 1 Swap(16001, 16001) - 192.0.2.2/32 0 - - - - - 192.0.2.3/32 10 eth2 192.0.2.18 3 Pop(16003) - 192.0.2.4/30 20 eth2 192.0.2.18 - - - 192.0.2.16/30 20 eth2 192.0.2.18 - - - 192.0.2.20/30 30 eth2 192.0.2.18 - - - 192.0.2.24/30 0 - - - - -``` - -Ping between VyOS-P1 / VyOS-P2 to confirm reachability: - -```none -vyos@P1-VyOS:~$ ping 192.0.2.2 source-address 192.0.2.1 -PING 192.0.2.2 (192.0.2.2) from 192.0.2.1 : 56(84) bytes of data. -64 bytes from 192.0.2.2: icmp_seq=1 ttl=63 time=3.47 ms -64 bytes from 192.0.2.2: icmp_seq=2 ttl=63 time=2.06 ms -64 bytes from 192.0.2.2: icmp_seq=3 ttl=63 time=3.90 ms -64 bytes from 192.0.2.2: icmp_seq=4 ttl=63 time=3.87 ms -^C ---- 192.0.2.2 ping statistics --- -4 packets transmitted, 4 received, 0% packet loss, time 3004ms -rtt min/avg/max/mdev = 2.064/3.326/3.903/0.748 ms - -vyos@P2-VyOS:~$ ping 192.0.2.1 source-address 192.0.2.2 -PING 192.0.2.1 (192.0.2.1) from 192.0.2.2 : 56(84) bytes of data. -64 bytes from 192.0.2.1: icmp_seq=1 ttl=63 time=2.91 ms -64 bytes from 192.0.2.1: icmp_seq=2 ttl=63 time=3.23 ms -64 bytes from 192.0.2.1: icmp_seq=3 ttl=63 time=2.91 ms -64 bytes from 192.0.2.1: icmp_seq=4 ttl=63 time=2.85 ms -^C ---- 192.0.2.1 ping statistics --- -4 packets transmitted, 4 received, 0% packet loss, time 3005ms -rtt min/avg/max/mdev = 2.846/2.972/3.231/0.151 ms -``` diff --git a/docs/configexamples/md-site-2-site-cisco.md b/docs/configexamples/md-site-2-site-cisco.md deleted file mode 100644 index d8ca2c18..00000000 --- a/docs/configexamples/md-site-2-site-cisco.md +++ /dev/null @@ -1,170 +0,0 @@ -(examples-site-2-site-cisco)= - -# Site-to-Site IPSec VPN to Cisco using FlexVPN - -This guide shows a sample configuration for FlexVPN site-to-site Internet -Protocol Security (IPsec)/Generic Routing Encapsulation (GRE) tunnel. - -FlexVPN is a newer "solution" for deployment of VPNs and it utilizes IKEv2 as -the key exchange protocol. The result is a flexible and scalable VPN solution -that can be easily adapted to fit various network needs. It can also support a -variety of encryption methods, including AES and 3DES. - -The lab was built using EVE-NG. - -## Configuration - -### VyOS - -- GRE: - -```none -set interfaces tunnel tun1 encapsulation 'gre' -set interfaces tunnel tun1 ip adjust-mss '1336' -set interfaces tunnel tun1 mtu '1376' -set interfaces tunnel tun1 remote '10.1.1.6' -set interfaces tunnel tun1 source-address '198.51.100.1' -``` - -- IPsec: - -```none -set vpn ipsec authentication psk vyos_cisco_l id 'vyos.net' -set vpn ipsec authentication psk vyos_cisco_l id 'cisco.hub.net' -set vpn ipsec authentication psk vyos_cisco_l secret 'secret' -set vpn ipsec esp-group e1 lifetime '3600' -set vpn ipsec esp-group e1 mode 'tunnel' -set vpn ipsec esp-group e1 pfs 'disable' -set vpn ipsec esp-group e1 proposal 1 encryption 'aes128' -set vpn ipsec esp-group e1 proposal 1 hash 'sha256' -set vpn ipsec ike-group i1 key-exchange 'ikev2' -set vpn ipsec ike-group i1 lifetime '28800' -set vpn ipsec ike-group i1 proposal 1 dh-group '5' -set vpn ipsec ike-group i1 proposal 1 encryption 'aes256' -set vpn ipsec ike-group i1 proposal 1 hash 'sha256' -set vpn ipsec interface 'eth2' -set vpn ipsec options disable-route-autoinstall -set vpn ipsec options flexvpn -set vpn ipsec options interface 'tun1' -set vpn ipsec options virtual-ip -set vpn ipsec site-to-site peer cisco_hub authentication local-id 'vyos.net' -set vpn ipsec site-to-site peer cisco_hub authentication mode 'pre-shared-secret' -set vpn ipsec site-to-site peer cisco_hub authentication remote-id 'cisco.hub.net' -set vpn ipsec site-to-site peer cisco_hub connection-type 'initiate' -set vpn ipsec site-to-site peer cisco_hub default-esp-group 'e1' -set vpn ipsec site-to-site peer cisco_hub ike-group 'i1' -set vpn ipsec site-to-site peer cisco_hub local-address '198.51.100.1' -set vpn ipsec site-to-site peer cisco_hub remote-address '10.1.1.6' -set vpn ipsec site-to-site peer cisco_hub tunnel 1 local prefix '198.51.100.1/32' -set vpn ipsec site-to-site peer cisco_hub tunnel 1 protocol 'gre' -set vpn ipsec site-to-site peer cisco_hub tunnel 1 remote prefix '10.1.1.6/32' -set vpn ipsec site-to-site peer cisco_hub virtual-address '0.0.0.0' -``` - - -### Cisco - -```none -aaa new-model -! -! -aaa authorization network default local -! -crypto ikev2 name-mangler GET_DOMAIN - fqdn all - email all -! -! -crypto ikev2 authorization policy vyos - pool mypool - aaa attribute list mylist - route set interface - route accept any tag 100 distance 5 -! -crypto ikev2 keyring mykeys - peer peer1 - identity fqdn vyos.net - pre-shared-key local secret - pre-shared-key remote secret -crypto ikev2 profile my_profile - match identity remote fqdn vyos.net - identity local fqdn cisco.hub.net - authentication remote pre-share - authentication local pre-share - keyring local mykeys - dpd 10 3 periodic - aaa authorization group psk list local name-mangler GET_DOMAIN - aaa authorization user psk cached - virtual-template 1 -! -! -! -crypto ipsec transform-set TSET esp-aes esp-sha256-hmac - mode tunnel -! -! -crypto ipsec profile my-ipsec-profile - set transform-set TSET - set ikev2-profile my_profile -! -interface Virtual-Template1 type tunnel - no ip address - ip mtu 1376 - ip nhrp network-id 1 - ip nhrp shortcut virtual-template 1 - ip tcp adjust-mss 1336 - tunnel path-mtu-discovery - tunnel protection ipsec profile my-ipsec-profile - ! - ip local pool my_pool 172.16.122.1 172.16.122.254 -``` - -Since the tunnel is a point-to-point GRE tunnel, it behaves like any other -point-to-point interface (for example: serial, dialer), and it is possible to -run any Interior Gateway Protocol (IGP)/Exterior Gateway Protocol (EGP) over -the link in order to exchange routing information - -## Verification - -```none -vyos@vyos$ show interfaces -Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down -Interface IP Address S/L Description ---------- ---------- --- ----------- -eth0 - u/u -eth1 - u/u -eth2 198.51.100.1/24 u/u -eth3 172.16.1.2/24 u/u -lo 127.0.0.1/8 u/u - ::1/128 -tun1 172.16.122.2/32 u/u - -vyos@vyos:~$ show vpn ipsec sa -Connection State Uptime Bytes In/Out Packets In/Out Remote address Remote ID Proposal ------------------- ------- -------- -------------- ---------------- ---------------- --------------------- ----------------------------- -cisco_hub-tunnel-1 up 44m17s 35K/31K 382/367 10.1.1.6 cisco.hub.net AES_CBC_128/HMAC_SHA2_256_128 - - -Hub#sh crypto ikev2 sa detailed - IPv4 Crypto IKEv2 SA - -Tunnel-id Local Remote fvrf/ivrf Status -5 10.1.1.6/4500 198.51.100.1/4500 none/none READY - Encr: AES-CBC, keysize: 256, PRF: SHA256, Hash: SHA256, DH Grp:5, Auth sign: PSK, Auth verify: PSK - Life/Active Time: 86400/2694 sec - CE id: 0, Session-id: 2 - Status Description: Negotiation done - Local spi: C94EE2DC92A60C47 Remote spi: 9AF0EF151BECF14C - Local id: cisco.hub.net - Remote id: vyos.net - Local req msg id: 269 Remote req msg id: 0 - Local next msg id: 269 Remote next msg id: 0 - Local req queued: 269 Remote req queued: 0 - Local window: 5 Remote window: 1 - DPD configured for 10 seconds, retry 3 - Fragmentation not configured. - Extended Authentication not configured. - NAT-T is not detected - Cisco Trust Security SGT is disabled - Assigned host addr: 172.16.122.2 -``` diff --git a/docs/configexamples/md-wan-load-balancing.md b/docs/configexamples/md-wan-load-balancing.md deleted file mode 100644 index b9357523..00000000 --- a/docs/configexamples/md-wan-load-balancing.md +++ /dev/null @@ -1,183 +0,0 @@ ---- -lastproofread: '2021-06-29' ---- - -(wan-load-balancing)= - - -# WAN Load Balancer examples - -% stop_vyoslinter - -## Example 1: Distributing load evenly - -The setup used in this example is shown in the following diagram: - -```{image} /_static/images/Wan_load_balancing1.webp -:align: center -:alt: Network Topology Diagram -:width: 80% -``` - - -### Overview - -> - All traffic coming in through eth2 is balanced between eth0 and eth1 -> on the router. -> - Pings will be sent to four targets for health testing (33.44.55.66, -> 44.55.66.77, 55.66.77.88 and 66.77.88.99). -> - All outgoing packets are assigned the source address of the assigned -> interface (SNAT). -> - eth0 is set to be removed from the load balancer's interface pool -> after 5 ping failures, eth1 will be removed after 4 ping failures. - -### Create static routes to ping targets - -Create static routes through the two ISPs towards the ping targets and -commit the changes: - -```none -set protocols static route 33.44.55.66/32 next-hop 11.22.33.1 -set protocols static route 44.55.66.77/32 next-hop 11.22.33.1 -set protocols static route 55.66.77.88/32 next-hop 22.33.44.1 -set protocols static route 66.77.88.99/32 next-hop 22.33.44.1 -``` - - -### Configure the load balancer - -Configure the WAN load balancer with the parameters described above: - -```none -set load-balancing wan interface-health eth0 failure-count 5 -set load-balancing wan interface-health eth0 nexthop 11.22.33.1 -set load-balancing wan interface-health eth0 test 10 type ping -set load-balancing wan interface-health eth0 test 10 target 33.44.55.66 -set load-balancing wan interface-health eth0 test 20 type ping -set load-balancing wan interface-health eth0 test 20 target 44.55.66.77 -set load-balancing wan interface-health eth1 failure-count 4 -set load-balancing wan interface-health eth1 nexthop 22.33.44.1 -set load-balancing wan interface-health eth1 test 10 type ping -set load-balancing wan interface-health eth1 test 10 target 55.66.77.88 -set load-balancing wan interface-health eth1 test 20 type ping -set load-balancing wan interface-health eth1 test 20 target 66.77.88.99 -set load-balancing wan rule 10 inbound-interface eth2 -set load-balancing wan rule 10 interface eth0 -set load-balancing wan rule 10 interface eth1 -``` - - -## Example 2: Failover based on interface weights - -This example uses the failover mode. -(wan-example2-overview)= - -### Overview - -In this example, eth0 is the primary interface and eth1 is the secondary -interface. To provide simple failover functionality. If eth0 fails, eth1 -takes over. - -### Create interface weight based configuration - -The configuration steps are the same as in the previous example, except -rule 10. So we keep the configuration, remove rule 10 and add a new rule -for the failover mode: - -```none -delete load-balancing wan rule 10 -set load-balancing wan rule 10 failover -set load-balancing wan rule 10 inbound-interface eth2 -set load-balancing wan rule 10 interface eth0 weight 10 -set load-balancing wan rule 10 interface eth1 weight 1 -``` - - -## Example 3: Failover based on rule order - -The previous example used the failover command to send traffic through -eth1 if eth0 fails. In this example, failover functionality is provided -by rule order. -(wan-example3-overview)= - -### Overview - -Two rules will be created, the first rule directs traffic coming in -from eth2 to eth0 and the second rule directs the traffic to eth1. If -eth0 fails the first rule is bypassed and the second rule matches, -directing traffic to eth1. - -### Create rule order based configuration - -We keep the configuration from the previous example, delete rule 10 -and create the two new rules as described: - -```none -delete load-balancing wan rule 10 -set load-balancing wan rule 10 inbound-interface eth2 -set load-balancing wan rule 10 interface eth0 -set load-balancing wan rule 20 inbound-interface eth2 -set load-balancing wan rule 20 interface eth1 -``` - - -## Example 4: Failover based on rule order - priority traffic - -A rule order for prioritizing traffic is useful in scenarios where the -secondary link has a lower speed and should only carry high priority -traffic. It is assumed for this example that eth1 is connected to a -slower connection than eth0 and should prioritize VoIP traffic. -(wan-example4-overview)= - -### Overview - -A rule order for prioritizing traffic is useful in scenarios where the -secondary link has a lower speed and should only carry high priority -traffic. It is assumed for this example that eth1 is connected to a -slower connection than eth0 and should prioritize VoIP traffic. - -### Create rule order based configuration with low speed secondary link - -We keep the configuration from the previous example, delete rule 20 and -create a new rule as described: - -```none -delete load-balancing wan rule 20 -set load-balancing wan rule 20 inbound-interface eth2 -set load-balancing wan rule 20 interface eth1 -set load-balancing wan rule 20 destination port sip -set load-balancing wan rule 20 protocol tcp -set protocols static route 0.0.0.0/0 next-hop 11.22.33.1 -``` - - -## Example 5: Exclude traffic from load balancing - -In this example two LAN interfaces exist in different subnets instead -of one like in the previous examples: - -```{image} /_static/images/Wan_load_balancing_exclude1.webp -:align: center -:alt: Network Topology Diagram -:width: 80% -``` - - -### Adding a rule for the second interface - -Based on the previous example, another rule for traffic from the second -interface eth3 can be added to the load balancer. However, traffic meant -to flow between the LAN subnets will be sent to eth0 and eth1 as well. -To prevent this, another rule is required. This rule excludes traffic -between the local subnets from the load balancer. It also excludes -locally-sources packets (required for web caching with load balancing). -eth+ is used as an alias that refers to all ethernet interfaces: - -```none -set load-balancing wan rule 5 exclude -set load-balancing wan rule 5 inbound-interface eth+ -set load-balancing wan rule 5 destination address 10.0.0.0/8 -``` - -% start_vyoslinter - diff --git a/docs/configexamples/md-zone-policy.md b/docs/configexamples/md-zone-policy.md deleted file mode 100644 index 2cd773a9..00000000 --- a/docs/configexamples/md-zone-policy.md +++ /dev/null @@ -1,417 +0,0 @@ ---- -lastproofread: '2024-06-14' ---- - -(examples-zone-policy)= - -# Zone-Policy example - -:::{note} -In {vytask}`T2199` the syntax of the zone configuration was changed. -The zone configuration moved from `zone-policy zone ` to `firewall -zone `. -::: - -## Native IPv4 and IPv6 - -We have three networks. - -```none -WAN - 172.16.10.0/24, 2001:0DB8:0:9999::0/64 -LAN - 192.168.100.0/24, 2001:0DB8:0:AAAA::0/64 -DMZ - 192.168.200.0/24, 2001:0DB8:0:BBBB::0/64 -``` - -**This specific example is for a router on a stick, but is very easily -adapted for however many NICs you have**: - -- Internet - 192.168.200.100 - TCP/80 -- Internet - 192.168.200.100 - TCP/443 -- Internet - 192.168.200.100 - TCP/25 -- Internet - 192.168.200.100 - TCP/53 -- VyOS acts as DHCP, DNS forwarder, NAT, router and firewall. -- 192.168.200.200/2001:0DB8:0:BBBB::200 is an internal/external DNS, web - and mail (SMTP/IMAP) server. -- 192.168.100.10/2001:0DB8:0:AAAA::10 is the administrator's console. It - can SSH to VyOS. -- LAN and DMZ hosts have basic outbound access: Web, FTP, SSH. -- LAN can access DMZ resources. -- DMZ cannot access LAN resources. -- Inbound WAN connect to DMZ host. - -```{image} /_static/images/zone-policy-diagram.webp -:align: center -:alt: Network Topology Diagram -:width: 80% -``` - -The VyOS interface is assigned the .1/:1 address of their respective -networks. WAN is on VLAN 10, LAN on VLAN 20, and DMZ on VLAN 30. - -It will look something like this: - -```none -interfaces { - ethernet eth0 { - duplex auto - hw-id 00:53:ed:6e:2a:92 - smp_affinity auto - speed auto - vif 10 { - address 172.16.10.1/24 - address 2001:db8:0:9999::1/64 - } - vif 20 { - address 192.168.100.1/24 - address 2001:db8:0:AAAA::1/64 - } - vif 30 { - address 192.168.200.1/24 - address 2001:db8:0:BBBB::1/64 - } - } - loopback lo { - } -} -``` - - -## Zones Basics - -Each interface is assigned to a zone. The interface can be physical or -virtual such as tunnels (VPN, PPTP, GRE, etc) and are treated exactly -the same. - -Traffic flows from zone A to zone B. That flow is what I refer to as a -zone-pair-direction. eg. A->B and B->A are two zone-pair-destinations. - -Ruleset are created per zone-pair-direction. - -I name rule sets to indicate which zone-pair-direction they represent. -eg. ZoneA-ZoneB or ZoneB-ZoneA. LAN-DMZ, DMZ-LAN. - -In VyOS, you have to have unique Ruleset names. In the event of overlap, -I add a "-6" to the end of v6 rulesets. eg. LAN-DMZ, LAN-DMZ-6. This -allows for each auto-completion and uniqueness. - -In this example we have 4 zones. LAN, WAN, DMZ, Local. The local zone is -the firewall itself. - -If your computer is on the LAN and you need to SSH into your VyOS box, -you would need a rule to allow it in the LAN-Local ruleset. If you want -to access a webpage from your VyOS box, you need a rule to allow it in -the Local-LAN ruleset. - -In rules, it is good to keep them named consistently. As the number of -rules you have grows, the more consistency you have, the easier your -life will be. - -```none -Rule 1 - State Established, Related -Rule 2 - State Invalid -Rule 100 - ICMP -Rule 200 - Web -Rule 300 - FTP -Rule 400 - NTP -Rule 500 - SMTP -Rule 600 - DNS -Rule 700 - DHCP -Rule 800 - SSH -Rule 900 - IMAPS -``` - -The first two rules are to deal with the idiosyncrasies of VyOS and -iptables. - -Zones and Rulesets both have a default action statement. When using -Zone-Policies, the default action is set by the zone-policy statement -and is represented by rule 10000. - -It is good practice to log both accepted and denied traffic. It can save -you significant headaches when trying to troubleshoot a connectivity -issue. - -To add logging to the default rule, do: - -```none -set firewall name default-log -``` - -By default, iptables does not allow traffic for established sessions to -return, so you must explicitly allow this. I do this by adding two rules -to every ruleset. 1 allows established and related state packets through -and rule 2 drops and logs invalid state packets. We place the -established/related rule at the top because the vast majority of traffic -on a network is established and the invalid rule to prevent invalid -state packets from mistakenly being matched against other rules. Having -the most matched rule listed first reduces CPU load in high volume -environments. Note: I have filed a bug to have this added as a default -action as well. - -''It is important to note, that you do not want to add logging to the -established state rule as you will be logging both the inbound and -outbound packets for each session instead of just the initiation of the -session. Your logs will be massive in a very short period of time.'' - -In VyOS you must have the interfaces created before you can apply it to -the zone and the rulesets must be created prior to applying it to a -zone-policy. - -I create/configure the interfaces first. Build out the rulesets for each -zone-pair-direction which includes at least the three state rules. Then -I setup the zone-policies. - -Zones do not allow for a default action of accept; either drop or -reject. It is important to remember this because if you apply an -interface to a zone and commit, any active connections will be dropped. -Specifically, if you are SSH’d into VyOS and add local or the interface -you are connecting through to a zone and do not have rulesets in place -to allow SSH and established sessions, you will not be able to connect. - -The following are the rules that were created for this example (may not -be complete), both in IPv4 and IPv6. If there is no IP specified, then -the source/destination address is not explicit. - -```none -WAN - DMZ:192.168.200.200 - tcp/80 -WAN - DMZ:192.168.200.200 - tcp/443 -WAN - DMZ:192.168.200.200 - tcp/25 -WAN - DMZ:192.168.200.200 - tcp/53 -WAN - DMZ:2001:0DB8:0:BBBB::200 - tcp/80 -WAN - DMZ:2001:0DB8:0:BBBB::200 - tcp/443 -WAN - DMZ:2001:0DB8:0:BBBB::200 - tcp/25 -WAN - DMZ:2001:0DB8:0:BBBB::200 - tcp/53 - -DMZ - Local - tcp/53 -DMZ - Local - tcp/123 -DMZ - Local - tcp/67,68 - -LAN - Local - tcp/53 -LAN - Local - tcp/123 -LAN - Local - tcp/67,68 -LAN:192.168.100.10 - Local - tcp/22 -LAN:2001:0DB8:0:AAAA::10 - Local - tcp/22 - -LAN - WAN - tcp/80 -LAN - WAN - tcp/443 -LAN - WAN - tcp/22 -LAN - WAN - tcp/20,21 - -DMZ - WAN - tcp/80 -DMZ - WAN - tcp/443 -DMZ - WAN - tcp/22 -DMZ - WAN - tcp/20,21 -DMZ - WAN - tcp/53 -DMZ - WAN - udp/53 - -Local - WAN - tcp/80 -Local - WAN - tcp/443 -Local - WAN - tcp/20,21 - -Local - DMZ - tcp/25 -Local - DMZ - tcp/67,68 -Local - DMZ - tcp/53 -Local - DMZ - udp/53 - -Local - LAN - tcp/67,68 - -LAN - DMZ - tcp/80 -LAN - DMZ - tcp/443 -LAN - DMZ - tcp/993 -LAN:2001:0DB8:0:AAAA::10 - DMZ:2001:0DB8:0:BBBB::200 - tcp/22 -LAN:192.168.100.10 - DMZ:192.168.200.200 - tcp/22 -``` - -Since we have 4 zones, we need to setup the following rulesets. - -```none -Lan-wan -Lan-local -Lan-dmz -Wan-lan -Wan-local -Wan-dmz -Local-lan -Local-wan -Local-dmz -Dmz-lan -Dmz-wan -Dmz-local -``` - -Even if the two zones will never communicate, it is a good idea to -create the zone-pair-direction rulesets and set default-log. This -will allow you to log attempts to access the networks. Without it, you -will never see the connection attempts. - -This is an example of the three base rules. - -```none -name wan-lan { - default-action drop - default-log - rule 1 { - action accept - state { - established enable - related enable - } - } - rule 2 { - action drop - log enable - state { - invalid enable - } - } -} -``` - -Here is an example of an IPv6 DMZ-WAN ruleset. - -```none -ipv6-name dmz-wan-6 { - default-action drop - default-log - rule 1 { - action accept - state { - established enable - related enable - } - } - rule 2 { - action drop - log enable - state { - invalid enable - } - } - rule 100 { - action accept - log enable - protocol ipv6-icmp - } - rule 200 { - action accept - destination { - port 80,443 - } - log enable - protocol tcp - } - rule 300 { - action accept - destination { - port 20,21 - } - log enable - protocol tcp - } - rule 500 { - action accept - destination { - port 25 - } - log enable - protocol tcp - source { - address 2001:db8:0:BBBB::200 - } - } - rule 600 { - action accept - destination { - port 53 - } - log enable - protocol tcp_udp - source { - address 2001:db8:0:BBBB::200 - } - } - rule 800 { - action accept - destination { - port 22 - } - log enable - protocol tcp - } -} -``` - -Once you have all of your rulesets built, then you need to create your -zone-policy. - -Start by setting the interface and default action for each zone. - -```none -set firewall zone dmz default-action drop -set firewall zone dmz interface eth0.30 -``` - -In this case, we are setting the v6 ruleset that represents traffic -sourced from the LAN, destined for the DMZ. Because the zone-policy -firewall syntax is a little awkward, I keep it straight by thinking of -it backwards. - -```none -set firewall zone dmz from lan firewall ipv6-name lan-dmz-6 -``` - -DMZ-LAN policy is LAN-DMZ. You can get a rhythm to it when you build out -a bunch at one time. - -In the end, you will end up with something like this config. I took out -everything but the Firewall, Interfaces, and zone-policy sections. It is -long enough as is. - -## IPv6 Tunnel - -If you are using a IPv6 tunnel from HE.net or someone else, the basis is -the same except you have two WAN interfaces. One for v4 and one for v6. - -You would have 5 zones instead of just 4 and you would configure your v6 -ruleset between your tunnel interface and your LAN/DMZ zones instead of -to the WAN. - -LAN, WAN, DMZ, local and TUN (tunnel) - -v6 pairs would be: - -```none -lan-tun -lan-local -lan-dmz -tun-lan -tun-local -tun-dmz -local-lan -local-tun -local-dmz -dmz-lan -dmz-tun -dmz-local -``` - -Notice, none go to WAN since WAN wouldn't have a v6 address on it. - -You would have to add a couple of rules on your wan-local ruleset to -allow protocol 41 in. - -Something like: - -```none -rule 400 { - action accept - destination { - address 172.16.10.1 - } - log enable - protocol 41 - source { - address ip.of.tunnel.broker - } -} -``` diff --git a/docs/configuration/container/md-index.md b/docs/configuration/container/md-index.md deleted file mode 100644 index db46db38..00000000 --- a/docs/configuration/container/md-index.md +++ /dev/null @@ -1,479 +0,0 @@ ---- -lastproofread: '2024-07-03' ---- - -# Container - -The VyOS container implementation is based on [Podman](https://podman.io/) as -a daemonless container engine. - -## Configuration - -```{cfgcmd} set container name \ image - -Sets the image name in the hub registry - -:::{code-block} none -set container name mysql-server image mysql:8.0 -::: - -If a registry is not specified, Docker.io will be used as the container -registry unless an alternative registry is specified using -`set container registry ` or the registry is included -in the image name - -:::{code-block} none -set container name mysql-server image quay.io/mysql:8.0 -::: -``` - - -```{cfgcmd} set container name \ entrypoint \ - -Override the default entrypoint from the image for a container. -``` - - -```{cfgcmd} set container name \ command \ - -Override the default command from the image for a container. -``` - - -```{cfgcmd} set container name \ arguments \ - -Set the command arguments for a container. -``` - - -```{cfgcmd} set container name \ host-name \ - -Set the host name for a container. -``` - - -```{cfgcmd} set container name \ allow-host-pid - -The container and the host share the same process namespace. -This means that processes running on the host are visible inside the -container, and processes inside the container are visible on the host. - -The command translates to "--pid host" when the container is created. -``` - - -```{cfgcmd} set container name \ allow-host-networks - -Allow host networking in a container. The network stack of the container is -not isolated from the host and will use the host IP. - -The command translates to "--net host" when the container is created. - -:::{note} -**allow-host-networks** cannot be used with **network** -::: -``` - - -```{cfgcmd} set container name \ network \ - -Attaches user-defined network to a container. -Only one network must be specified and must already exist. -``` - - -```{cfgcmd} set container name \ network \ address \ - -Optionally set a specific static IPv4 or IPv6 address for the container. -This address must be within the named network prefix. - -:::{note} -The first IP in the container network is reserved by the -engine and cannot be used -::: -``` - - -```{cfgcmd} set container name \ name-server \ - -Optionally set a custom name server. -If a container network is used with DNS enabled, -this setting will not have any effect. -``` - - -```{cfgcmd} set container name \ description \ - -Set a container description -``` - - -```{cfgcmd} set container name \ environment \ value \ - -Add custom environment variables. -Multiple environment variables are allowed. -The following commands translate to "-e key=value" when the container -is created. - -:::{code-block} none -set container name mysql-server environment MYSQL_DATABASE value 'zabbix' -set container name mysql-server environment MYSQL_USER value 'zabbix' -set container name mysql-server environment MYSQL_PASSWORD value 'zabbix_pwd' -set container name mysql-server environment MYSQL_ROOT_PASSWORD value 'root_pwd' -::: -``` - - -```{cfgcmd} set container name \ port \ source \ - -``` -```{cfgcmd} set container name \ port \ destination \ -``` - -```{cfgcmd} set container name \ port \ protocol \ - -Publish a port for the container. - -:::{code-block} none -set container name zabbix-web-nginx-mysql port http source 80 -set container name zabbix-web-nginx-mysql port http destination 8080 -set container name zabbix-web-nginx-mysql port http protocol tcp -::: -``` -:::{note} -Port publishing cannot be used with **network**. For this purpose, a workaround -using destination NAT and static IP assignment for the container is available. -::: -```{cfgcmd} set container name \ volume \ source \ -``` - -```{cfgcmd} set container name \ volume \ destination \ - -Mount a volume into the container - -:::{code-block} none -set container name coredns volume 'corefile' source /config/coredns/Corefile -set container name coredns volume 'corefile' destination /etc/Corefile -::: -``` - -```{cfgcmd} set container name \ volume \ mode \ - -Volume is either mounted as rw (read-write - default) or ro (read-only) -``` - -```{cfgcmd} set container name \ tmpfs \ destination \ - -Mount a tmpfs *(ramdisk)* filesystem to the given path within the container. -``` - -```{cfgcmd} set container name \ tmpfs \ size \ - -Size in MB for tmpfs filesystem, maximum size is 64GB or 50% of the -systems total available memory. -``` - -```{cfgcmd} set container name \ uid \ -``` - -```{cfgcmd} set container name \ gid \ - -Set the User ID or Group ID of the container -``` - -```{cfgcmd} set container name \ restart [no | on-failure | always] - -Set the restart behavior of the container. - -- **no**: Do not restart containers on exit -- **on-failure**: Restart containers when they exit with a non-zero -exit code, retrying indefinitely (default) -- **always**: Restart containers when they exit, regardless of status, -retrying indefinitely -``` - -```{cfgcmd} set container name \ cpu-quota \ - -This specifies the number of CPU resources the container can use. - -Default is 0 for unlimited. -For example, 1.25 limits the container to use up to 1.25 cores -worth of CPU time. -This can be a decimal number with up to three decimal places. - -The command translates to "--cpus=\" when the container is created. -``` - -```{cfgcmd} set container name \ memory \ - -Constrain the memory available to the container. - -Default is 512 MB. Use 0 MB for unlimited memory. -``` - -```{cfgcmd} set container name \ device \ source \ -``` - -```{cfgcmd} set container name \ device \ destination \ - -Add a host device to the container. -``` - -```{cfgcmd} set container name \ capability \ - -Set container capabilities or permissions. - -- **net-admin**: Network operations (interface, firewall, routing tables) -- **net-bind-service**: Bind a socket to privileged ports -(port numbers less than 1024) -- **net-raw**: Permission to create raw network sockets -- **setpcap**: Capability sets (from bounded or inherited set) -- **sys-admin**: Administration operations (quotactl, mount, sethostname, -setdomainame) -- **sys-time**: Permission to set system clock -``` - -```{cfgcmd} set container name \ sysctl parameter \ value \ - -Set container sysctl values. - -The subset of possible parameters are: - -- Kernel Parameters: kernel.msgmax, kernel.msgmnb, kernel.msgmni, kernel.sem, -kernel.shmall, kernel.shmmax, kernel.shmmni, kernel.shm_rmid_forced -- Parameters beginning with fs.mqueue.* -- Parameters beginning with net.* (only if user-defined network is used) -``` - -```{cfgcmd} set container name \ label \ value \ - -Add metadata label for this container. -``` - -```{cfgcmd} set container name \ disable - -Disable a container. -``` - -### Container Health checks - - -By default, no health checks are run, even when defined by the image. - -```{cfgcmd} set container name \ health-check - -Default health check is run for the container if defined by the image. -``` - -```{cfgcmd} set container name \ health-check command \ - -Override the default health check command from the image for a container. -``` - -```{cfgcmd} set container name \ health-check interval \ - -Override the default health-check interval. For example: `60` -``` - -```{cfgcmd} set container name \ health-check timeout \ - -Override the default health-check timeout. For example: `10` -``` - -```{cfgcmd} set container name \ health-check retries \ - -Number of health check retries before container is considered unhealthy. For example: `1` -``` - -### Container Networks - -```{cfgcmd} set container network \ - -Creates a named container network -``` - -```{cfgcmd} set container network \ description - -A brief description what this network is all about. -``` - -```{cfgcmd} set container network \ prefix \ - -Define IPv4 and/or IPv6 prefix for a given network name. -Both IPv4 and IPv6 can be used in parallel. -``` - -```{cfgcmd} set container network \ mtu \ - -Configure {abbr}`MTU (Maximum Transmission Unit)` for a given network. It -is the size (in bytes) of the largest ethernet frame sent on this link. -``` - -```{cfgcmd} set container network \ no-name-server - -Disable Domain Name System (DNS) plugin for this network. -``` - -```{cfgcmd} set container network \ vrf \ - -Bind container network to a given VRF instance. -``` - -### Container Registry - -```{cfgcmd} set container registry \ - -Adds registry to list of unqualified-search-registries. By default, for any -image that does not include the registry in the image name, VyOS will use -docker.io and quay.io as the container registry. -``` - -```{cfgcmd} set container registry \ disable - -Disable a given container registry -``` - -```{cfgcmd} set container registry \ authentication username -``` - -```{cfgcmd} set container registry \ authentication password - -Some container registries require credentials to be used. - -Credentials can be defined here and will only be used when adding a -container image to the system. -``` - -```{cfgcmd} set container registry \ insecure - -Allow registry access over unencrypted HTTP or TLS connections with -untrusted certificates. -``` - -```{cfgcmd} set container registry \ mirror address \ -``` - -```{cfgcmd} set container registry \ mirror host-name \ -``` - -```{cfgcmd} set container registry \ mirror port \ -``` - -```{cfgcmd} set container registry \ mirror path \ - -Registry mirror, use ``(host-name|address)[:port][/path]``. - -If you have mirror http://192.168.1.1:8080 for docker.io, you can use ``docker.io/some/repo`` or run ``podman pull docker.io/some/repo`` - -:::{code-block} none -set container registry docker.io mirror address 192.168.1.1 -set container registry docker.io mirror port 8080 -set container registry docker.io insecure -::: -If http://192.168.1.1:8080 is your own registry, you can use ``192.168.1.1:8080/some/repo`` or run ``podman pull 192.168.1.1:8080/some/repo`` - -:::{code-block} none -set container registry 192.168.1.1:8080 insecure -::: -``` - -### Log Configuration - -```{cfgcmd} set container name \ log-driver [k8s-file | journald | none] - -Set the default log driver for containers. - -- **k8s-file**: Log to a plain text file in Kubernetes-style format. -- **journald**: Log to the system journal -- **none**: Disable logging for the container - -Current default is journald. - -``` - -## Operation Commands - -```{opcmd} add container image \ - -Pull a new image for container -``` -```{opcmd} show container - -Show the list of all active containers. -``` -```{opcmd} show container image - -Show the local container images. -``` -```{opcmd} show container log \ - -Show logs from a given container -``` -```{opcmd} show container network - -Show a list available container networks -``` -```{opcmd} restart container \ - -Restart a given container -``` -```{opcmd} update container image \ - -Update container image -``` -```{opcmd} delete container image \ [force] - -Delete a particular container image based on it's image ID. -You can also delete all container images at once. - -You can not delete a container image if it has more then one tag -assigned, this is why there is a `force` option to pass down to -the container image to also remove those images. -``` - -## Example Configuration - -For the sake of demonstration, [example #1 in the official documentation](https://www.zabbix.com/documentation/current/manual/installation/containers) -to the declarative VyOS CLI syntax. - -```none -set container network zabbix prefix 172.20.0.0/16 -set container network zabbix description 'Network for Zabbix component containers' - -set container name mysql-server image mysql:8.0 -set container name mysql-server network zabbix - -set container name mysql-server environment 'MYSQL_DATABASE' value 'zabbix' -set container name mysql-server environment 'MYSQL_USER' value 'zabbix' -set container name mysql-server environment 'MYSQL_PASSWORD' value 'zabbix_pwd' -set container name mysql-server environment 'MYSQL_ROOT_PASSWORD' value 'root_pwd' - -set container name zabbix-java-gateway image zabbix/zabbix-java-gateway:alpine-5.2-latest -set container name zabbix-java-gateway network zabbix - -set container name zabbix-server-mysql image zabbix/zabbix-server-mysql:alpine-5.2-latest -set container name zabbix-server-mysql network zabbix - -set container name zabbix-server-mysql environment 'DB_SERVER_HOST' value 'mysql-server' -set container name zabbix-server-mysql environment 'MYSQL_DATABASE' value 'zabbix' -set container name zabbix-server-mysql environment 'MYSQL_USER' value 'zabbix' -set container name zabbix-server-mysql environment 'MYSQL_PASSWORD' value 'zabbix_pwd' -set container name zabbix-server-mysql environment 'MYSQL_ROOT_PASSWORD' value 'root_pwd' -set container name zabbix-server-mysql environment 'ZBX_JAVAGATEWAY' value 'zabbix-java-gateway' - -set container name zabbix-server-mysql port zabbix source 10051 -set container name zabbix-server-mysql port zabbix destination 10051 - -set container name zabbix-web-nginx-mysql image zabbix/zabbix-web-nginx-mysql:alpine-5.2-latest -set container name zabbix-web-nginx-mysql network zabbix - -set container name zabbix-web-nginx-mysql environment 'MYSQL_DATABASE' value 'zabbix' -set container name zabbix-web-nginx-mysql environment 'ZBX_SERVER_HOST' value 'zabbix-server-mysql' -set container name zabbix-web-nginx-mysql environment 'DB_SERVER_HOST' value 'mysql-server' -set container name zabbix-web-nginx-mysql environment 'MYSQL_USER' value 'zabbix' -set container name zabbix-web-nginx-mysql environment 'MYSQL_PASSWORD' value 'zabbix_pwd' -set container name zabbix-web-nginx-mysql environment 'MYSQL_ROOT_PASSWORD' value 'root_pwd' - -set container name zabbix-web-nginx-mysql port http source 80 -set container name zabbix-web-nginx-mysql port http destination 8080 -``` diff --git a/docs/configuration/firewall/md-bridge.md b/docs/configuration/firewall/md-bridge.md deleted file mode 100644 index f0e94f9e..00000000 --- a/docs/configuration/firewall/md-bridge.md +++ /dev/null @@ -1,685 +0,0 @@ ---- -lastproofread: '2026-03-28' ---- - -(firewall-configuration)= - -# Bridge Firewall Configuration - -## Overview - -Learn more about bridge firewall configuration -and related op-mode commands. - -The following commands are covered in this section: - -```{cfgcmd} set firewall bridge \ -``` - -From the main structure defined in -{doc}`Firewall Overview` -in this section you can find detailed information only for the next part -of the general structure: - -```none -- set firewall - * bridge - - forward - + filter - - input - + filter - - output - + filter - - prerouting - + filter - - name - + custom_name -``` - -Traffic that is received by the router on an interface that is a member of a -bridge is processed on the **Bridge Layer**. Before the bridge decision is -made, all packets are analyzed at **Prerouting**. First filters can be applied -here, and also rules for ignoring connection tracking system can be configured. -The relevant configuration that acts in **prerouting** is: - - -- `set firewall bridge prerouting filter ...`. - - -For traffic that needs to be switched internally by the bridge, the base -chain is **forward**, and its base command for filtering is `set firewall -bridge forward filter ...`, which happens in stage 4, highlighted with red -color. - - -:::{figure} /_static/images/firewall-bridge-forward.webp -::: - - -For traffic destined to the router itself or that needs to be routed -(assuming a layer3 bridge is configured), the base chain is **input**, and the -base command is `set firewall bridge input filter ...` and the path is: - - -:::{figure} /_static/images/firewall-bridge-input.webp -::: - - -If it's not dropped, then the packet is sent to **IP Layer**, and will be -processed by the **IP Layer** firewall: IPv4 or IPv6 ruleset. Check once again -the {doc}`general packet flow diagram` if -needed. - - -For traffic that originates from the bridge itself, the base chain is -**output**, and the base command is `set firewall bridge output filter -...`, and the path is: - - -:::{figure} /_static/images/firewall-bridge-output.webp -::: - - -Custom bridge firewall chains can be created with the command `set firewall -bridge name ...`. To use such a custom chain, a rule with action jump -and the appropriate target must be defined in a base chain. - - -## Bridge Rules - - -For firewall filtering, firewall rules need to be created. Each rule is -numbered, has an action to apply if the rule is matched, and the ability -to specify multiple matching criteria. Data packets go through the rules -from 1 - 999999, so order is crucial. At the first match the action of the -rule will be executed. - - -### Actions - - -If a rule is defined, an action must also be defined for it. This tells the -firewall what to do if all matching criteria in the rule are met. - - -In firewall bridge rules, the action can be: - - -- `accept`: accept the packet. -- `continue`: continue parsing next rule. -- `drop`: drop the packet. -- `jump`: jump to another custom chain. -- `return`: Return from the current chain and continue at the next rule - of the last chain. -- `queue`: Enqueue packet to userspace. -- `notrack`: ignore connection tracking system. This action is only - available in prerouting chain. - -```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> action [accept | continue | drop | jump | queue | return] -``` - -```{cfgcmd} set firewall bridge input filter rule \<1-999999\> action [accept | continue | drop | jump | queue | return] -``` - -```{cfgcmd} set firewall bridge output filter rule \<1-999999\> action [accept | continue | drop | jump | queue | return] -``` - -```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> action [accept | continue | drop | jump | notrack | queue | return] -``` - -```{cfgcmd} set firewall bridge name \ rule \<1-999999\> action [accept | continue | drop | jump | queue | return] - -This required setting defines the action of the current rule. If action is -set to jump, then jump-target is also needed. -``` - -```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> jump-target \ -``` - -```{cfgcmd} set firewall bridge input filter rule \<1-999999\> jump-target \ -``` - -```{cfgcmd} set firewall bridge output filter rule \<1-999999\> jump-target \ -``` - -```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> jump-target \ -``` - -```{cfgcmd} set firewall bridge name \ rule \<1-999999\> jump-target \ -``` - -If action is set to ``queue``, use next command to specify the queue -target. Range is also supported: - -```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> queue \<0-65535\> -``` - -```{cfgcmd} set firewall bridge input filter rule \<1-999999\> queue \<0-65535\> -``` - -```{cfgcmd} set firewall bridge output filter rule \<1-999999\> queue \<0-65535\> -``` - -```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> queue \<0-65535\> -``` - -```{cfgcmd} set firewall bridge name \ rule \<1-999999\> queue \<0-65535\> - -Also, if action is set to ``queue``, use next command to specify the queue -options. Possible options are ``bypass`` and ``fanout``: -``` - -```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> queue-options bypass -``` - -```{cfgcmd} set firewall bridge input filter rule \<1-999999\> queue-options bypass -``` - -```{cfgcmd} set firewall bridge output filter rule \<1-999999\> queue-options bypass -``` - -```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> queue-options bypass -``` - -```{cfgcmd} set firewall bridge name \ rule \<1-999999\> queue-options bypass -``` - -```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> queue-options fanout -``` - -```{cfgcmd} set firewall bridge input filter rule \<1-999999\> queue-options fanout -``` - -```{cfgcmd} set firewall bridge output filter rule \<1-999999\> queue-options fanout -``` - -```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> queue-options fanout -``` - -```{cfgcmd} set firewall bridge name \ rule \<1-999999\> queue-options fanout -``` - -Also, **default-action** is an action that takes place whenever a packet does -not match any rule in its chain. For base chains, possible options for -**default-action** are **accept** or **drop**. - -```{cfgcmd} set firewall bridge forward filter default-action [accept | drop] -``` - -```{cfgcmd} set firewall bridge input filter default-action [accept | drop] -``` - -```{cfgcmd} set firewall bridge output filter default-action [accept | drop] -``` - -```{cfgcmd} set firewall bridge prerouting filter default-action [accept | drop] -``` - -```{cfgcmd} set firewall bridge name \ default-action [accept | continue | drop | jump | reject | return] - -This sets the default action of the rule-set if a packet does not match -any of the rules in that chain. If default-action is set to ``jump``, then -``default-jump-target`` is also needed. Note that for base chains, default -action can only be set to ``accept`` or ``drop``, while on custom chains -more actions are available. -``` - -```{cfgcmd} set firewall bridge name \ default-jump-target \ - -To be used only when ``default-action`` is set to ``jump``. Use this -command to specify jump target for default rule. -``` -:::{note} -**Important note about default-actions:** -If the default action for any base chain is not defined, then the default -action is set to **accept** for that chain. For custom chains, if the -default action is not defined, then the default-action is set to **drop**. -::: - - -### Firewall Logs - - -You can enable logging for every firewall rule. If enabled, other log options -can be configured. - -```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> log -``` - -```{cfgcmd} set firewall bridge input filter rule \<1-999999\> log -``` - -```{cfgcmd} set firewall bridge output filter rule \<1-999999\> log -``` - -```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> log -``` - -```{cfgcmd} set firewall bridge name \ rule \<1-999999\> log - -Enable logging for the matched packet. If this configuration command is not -present, then the log is not enabled. -``` - -```{cfgcmd} set firewall bridge forward filter default-log -``` - -```{cfgcmd} set firewall bridge input filter default-log -``` - -```{cfgcmd} set firewall bridge output filter default-log -``` - -```{cfgcmd} set firewall bridge prerouting filter default-log -``` - -```{cfgcmd} set firewall bridge name \ default-log - -Use this command to enable the logging of the default action on -the specified chain. -``` - -```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> log-options level [emerg | alert | crit | err | warn | notice | info | debug] -``` - -```{cfgcmd} set firewall bridge input filter rule \<1-999999\> log-options level [emerg | alert | crit | err | warn | notice | info | debug] -``` - -```{cfgcmd} set firewall bridge output filter rule \<1-999999\> log-options level [emerg | alert | crit | err | warn | notice | info | debug] -``` - -```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> log-options level [emerg | alert | crit | err | warn | notice | info | debug] -``` - -```{cfgcmd} set firewall bridge name \ rule \<1-999999\> log-options level [emerg | alert | crit | err | warn | notice | info | debug] - -Define log-level. Only applicable if rule log is enabled. -``` - -```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> log-options group \<0-65535\> -``` - -```{cfgcmd} set firewall bridge input filter rule \<1-999999\> log-options group \<0-65535\> -``` - -```{cfgcmd} set firewall bridge output filter rule \<1-999999\> log-options group \<0-65535\> -``` - -```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> log-options group \<0-65535\> -``` - -```{cfgcmd} set firewall bridge name \ rule \<1-999999\> log-options group \<0-65535\> - -Define the log group to send messages to. Only applicable if rule log is -enabled. -``` - -```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> log-options snapshot-length \<0-9000\> -``` - -```{cfgcmd} set firewall bridge input filter rule \<1-999999\> log-options snapshot-length \<0-9000\> -``` - -```{cfgcmd} set firewall bridge output filter rule \<1-999999\> log-options snapshot-length \<0-9000\> -``` - -```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> log-options snapshot-length \<0-9000\> -``` - -```{cfgcmd} set firewall bridge name \ rule \<1-999999\> log-options snapshot-length \<0-9000\> - -Define length of packet payload to include in netlink message. Only -applicable if rule log is enabled and the log group is defined. -``` - -```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> log-options queue-threshold \<0-65535\> -``` - -```{cfgcmd} set firewall bridge input filter rule \<1-999999\> log-options queue-threshold \<0-65535\> -``` - -```{cfgcmd} set firewall bridge output filter rule \<1-999999\> log-options queue-threshold \<0-65535\> -``` - -```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> log-options queue-threshold \<0-65535\> -``` - -```{cfgcmd} set firewall bridge name \ rule \<1-999999\> log-options queue-threshold \<0-65535\> - -Define the number of packets to queue inside the kernel before sending them -to userspace. Only applicable if rule log is enabled and the log group is -defined. -``` - -### Firewall Description - - -You can define a description for reference for every custom chain. - -```{cfgcmd} set firewall bridge name \ description \ - -Provide a rule-set description to a custom firewall chain. -``` - -```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> description \ -``` - -```{cfgcmd} set firewall bridge input filter rule \<1-999999\> description \ -``` - -```{cfgcmd} set firewall bridge output filter rule \<1-999999\> description \ -``` - -```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> description \ -``` - -```{cfgcmd} set firewall bridge name \ rule \<1-999999\> description \ - -Provide a description for each rule. -``` - -### Rule Status - - -By default, when you define a rule, it is enabled. In some cases, it is -useful to disable the rule instead of removing it. - -```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> disable -``` - -```{cfgcmd} set firewall bridge input filter rule \<1-999999\> disable -``` - -```{cfgcmd} set firewall bridge output filter rule \<1-999999\> disable -``` - -```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> disable -``` - -```{cfgcmd} set firewall bridge name \ rule \<1-999999\> disable - -Command for disabling a rule but keep it in the configuration. -``` - -### Matching criteria - - -There are many matching criteria against which a packet can be tested. Refer -to {doc}`IPv4` and -{doc}`IPv6` matching criteria for more details. - - -Since bridges operate at layer 2, both matchers for IPv4 and IPv6 are -supported in bridge firewall configuration. Same applies to firewall groups. - - -Same specific matching criteria that can be used in bridge firewall are -described in this section: - -```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> ethernet-type [802.1q | 802.1ad | arp | ipv4 | ipv6] -``` - -```{cfgcmd} set firewall bridge input filter rule \<1-999999\> ethernet-type [802.1q | 802.1ad | arp | ipv4 | ipv6] -``` - -```{cfgcmd} set firewall bridge output filter rule \<1-999999\> ethernet-type [802.1q | 802.1ad | arp | ipv4 | ipv6] -``` - -```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> ethernet-type [802.1q | 802.1ad | arp | ipv4 | ipv6] -``` - -```{cfgcmd} set firewall bridge name \ rule \<1-999999\> ethernet-type [802.1q | 802.1ad | arp | ipv4 | ipv6] - -Match based on the Ethernet type of the packet. -``` - -```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> vlan ethernet-type [802.1q | 802.1ad | arp | ipv4 | ipv6] -``` - -```{cfgcmd} set firewall bridge input filter rule \<1-999999\> vlan ethernet-type [802.1q | 802.1ad | arp | ipv4 | ipv6] -``` - -```{cfgcmd} set firewall bridge output filter rule \<1-999999\> vlan ethernet-type [802.1q | 802.1ad | arp | ipv4 | ipv6] -``` - -```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> vlan ethernet-type [802.1q | 802.1ad | arp | ipv4 | ipv6] -``` - -```{cfgcmd} set firewall bridge name \ rule \<1-999999\> vlan ethernet-type [802.1q | 802.1ad | arp | ipv4 | ipv6] - -Match based on the Ethernet type of the packet when it is VLAN tagged. -``` - -```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> vlan id \<0-4096\> -``` - -```{cfgcmd} set firewall bridge input filter rule \<1-999999\> vlan id \<0-4096\> -``` - -```{cfgcmd} set firewall bridge output filter rule \<1-999999\> vlan id \<0-4096\> -``` - -```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> vlan id \<0-4096\> -``` - -```{cfgcmd} set firewall bridge name \ rule \<1-999999\> vlan id \<0-4096\> - -Match based on VLAN identifier. Range is also supported. -``` - -```{cfgcmd} set firewall bridge forward filter rule \<1-999999\> vlan priority \<0-7\> -``` - -```{cfgcmd} set firewall bridge input filter rule \<1-999999\> vlan priority \<0-7\> -``` - -```{cfgcmd} set firewall bridge output filter rule \<1-999999\> vlan priority \<0-7\> -``` - -```{cfgcmd} set firewall bridge prerouting filter rule \<1-999999\> vlan priority \<0-7\> -``` - -```{cfgcmd} set firewall bridge name \ rule \<1-999999\> vlan priority \<0-7\> - -Match based on VLAN priority (Priority Code Point - PCP). Range is also -supported. -``` - -### Packet Modifications - - -Starting from **VyOS-1.5-rolling-202410060007**, the firewall can modify -packets before they are sent out. This feature provides more flexibility in -packet handling. - -```{cfgcmd} set firewall bridge [prerouting | forward | output] filter rule \<1-999999\> set dscp \<0-63\> - -Set a specific value of Differentiated Services Codepoint (DSCP). -``` - -```{cfgcmd} set firewall bridge [prerouting | forward | output] filter rule \<1-999999\> set mark \<1-2147483647\> - -Set a specific packet mark value. -``` - -```{cfgcmd} set firewall bridge [prerouting | forward | output] filter rule \<1-999999\> set tcp-mss \<500-1460\> - -Set the TCP-MSS (TCP maximum segment size) for the connection. -``` - -```{cfgcmd} set firewall bridge [prerouting | forward | output] filter rule \<1-999999\> set ttl \<0-255\> - -Set the TTL (Time to Live) value. -``` - -```{cfgcmd} set firewall bridge [prerouting | forward | output] filter rule \<1-999999\> set hop-limit \<0-255\> - -Set hop limit value. -``` - -```{cfgcmd} set firewall bridge [forward | output] filter rule \<1-999999\> set connection-mark \<0-2147483647\> - -Set connection mark value. -``` - -### Use IP firewall - -By default, for switched traffic, only the rules defined under `set firewall -bridge` are applied. There are two global-options that can be configured in -order to force deeper analysis of the packet on the IP layer. These options -are: - -```{cfgcmd} set firewall global-options apply-to-bridged-traffic ipv4 - -This command enables the IPv4 firewall for bridged traffic. If this option -is used, packets are also parsed by rules defined in ``set firewall ipv4 -...`` -``` - -```{cfgcmd} set firewall global-options apply-to-bridged-traffic ipv6 - -This command enables the IPv6 firewall for bridged traffic. If this option -is used, packets are also parsed by rules defined in ``set firewall ipv6 -...`` -``` - -## Operation-mode Firewall -### Rule-set overview - -In this section you can find all useful firewall op-mode commands. -General commands for firewall configuration, counter and statistics: - -```{opcmd} show firewall -``` - -```{opcmd} show firewall summary -``` - -```{opcmd} show firewall statistics -``` - -And, to print only bridge firewall information: - -```{opcmd} show firewall bridge -``` - -```{opcmd} show firewall bridge forward filter -``` - -```{opcmd} show firewall bridge forward filter rule \ -``` - -```{opcmd} show firewall bridge name \ -``` - -```{opcmd} show firewall bridge name \ rule \ -``` - -### Show Firewall log - -```{opcmd} show log firewall -``` - -```{opcmd} show log firewall bridge -``` - -```{opcmd} show log firewall bridge forward -``` - -```{opcmd} show log firewall bridge forward filter -``` - -```{opcmd} show log firewall bridge name \ -``` - -```{opcmd} show log firewall bridge forward filter rule \ -``` - -```{opcmd} show log firewall bridge name \ rule \ - -Show the logs of all firewall; show all bridge firewall logs; show all logs -for forward hook; show all logs for forward hook and priority filter; show -all logs for particular custom chain; show logs for specific Rule-Set. -``` - -### Example - -Configuration example: - -```none -set firewall bridge forward filter default-action 'drop' -set firewall bridge forward filter default-log -set firewall bridge forward filter rule 10 action 'continue' -set firewall bridge forward filter rule 10 inbound-interface name 'eth2' -set firewall bridge forward filter rule 10 vlan id '22' -set firewall bridge forward filter rule 20 action 'drop' -set firewall bridge forward filter rule 20 inbound-interface group 'TRUNK-RIGHT' -set firewall bridge forward filter rule 20 vlan id '60' -set firewall bridge forward filter rule 30 action 'jump' -set firewall bridge forward filter rule 30 jump-target 'TEST' -set firewall bridge forward filter rule 30 outbound-interface name '!eth1' -set firewall bridge forward filter rule 35 action 'accept' -set firewall bridge forward filter rule 35 vlan id '11' -set firewall bridge forward filter rule 40 action 'continue' -set firewall bridge forward filter rule 40 destination mac-address '66:55:44:33:22:11' -set firewall bridge forward filter rule 40 source mac-address '11:22:33:44:55:66' -set firewall bridge name TEST default-action 'accept' -set firewall bridge name TEST default-log -set firewall bridge name TEST rule 10 action 'continue' -set firewall bridge name TEST rule 10 log -set firewall bridge name TEST rule 10 vlan priority '0' -``` - -And op-mode commands: - -```none -vyos@BRI:~$ show firewall bridge -Rulesets bridge Information - ---------------------------------- -bridge Firewall "forward filter" - -Rule Action Protocol Packets Bytes Conditions -------- -------- ---------- --------- ------- --------------------------------------------------------------------- -10 continue all 0 0 iifname "eth2" vlan id 22 continue -20 drop all 0 0 iifname @I_TRUNK-RIGHT vlan id 60 -30 jump all 2130 170688 oifname != "eth1" jump NAME_TEST -35 accept all 2080 168616 vlan id 11 accept -40 continue all 0 0 ether daddr 66:55:44:33:22:11 ether saddr 11:22:33:44:55:66 continue -default drop all 0 0 - ---------------------------------- -bridge Firewall "name TEST" - -Rule Action Protocol Packets Bytes Conditions -------- -------- ---------- --------- ------- -------------------------------------------------- -10 continue all 2130 170688 vlan pcp 0 prefix "[bri-NAM-TEST-10-C]" continue -default accept all 2130 170688 - -vyos@BRI:~$ -vyos@BRI:~$ show firewall bridge name TEST -Ruleset Information - ---------------------------------- -bridge Firewall "name TEST" - -Rule Action Protocol Packets Bytes Conditions -------- -------- ---------- --------- ------- -------------------------------------------------- -10 continue all 2130 170688 vlan pcp 0 prefix "[bri-NAM-TEST-10-C]" continue -default accept all 2130 170688 - -vyos@BRI:~$ -``` - -Inspect logs: - -```none -vyos@BRI:~$ show log firewall bridge -Dec 05 14:37:47 kernel: [bri-NAM-TEST-10-C]IN=eth1 OUT=eth2 ARP HTYPE=1 PTYPE=0x0800 OPCODE=1 MACSRC=50:00:00:04:00:00 IPSRC=10.11.11.101 MACDST=00:00:00:00:00:00 IPDST=10.11.11.102 -Dec 05 14:37:48 kernel: [bri-NAM-TEST-10-C]IN=eth1 OUT=eth2 ARP HTYPE=1 PTYPE=0x0800 OPCODE=1 MACSRC=50:00:00:04:00:00 IPSRC=10.11.11.101 MACDST=00:00:00:00:00:00 IPDST=10.11.11.102 -Dec 05 14:37:49 kernel: [bri-NAM-TEST-10-C]IN=eth1 OUT=eth2 ARP HTYPE=1 PTYPE=0x0800 OPCODE=1 MACSRC=50:00:00:04:00:00 IPSRC=10.11.11.101 MACDST=00:00:00:00:00:00 IPDST=10.11.11.102 -... -vyos@BRI:~$ show log firewall bridge forward filter -Dec 05 14:42:22 kernel: [bri-FWD-filter-default-D]IN=eth2 OUT=eth1 MAC=33:33:00:00:00:16:50:00:00:06:00:00:86:dd SRC=0000:0000:0000:0000:0000:0000:0000:0000 DST=ff02:0000:0000:0000:0000:0000:0000:0016 LEN=96 TC=0 HOPLIMIT=1 FLOWLBL=0 PROTO=ICMPv6 TYPE=143 CODE=0 -Dec 05 14:42:22 kernel: [bri-FWD-filter-default-D]IN=eth2 OUT=eth1 MAC=33:33:00:00:00:16:50:00:00:06:00:00:86:dd SRC=0000:0000:0000:0000:0000:0000:0000:0000 DST=ff02:0000:0000:0000:0000:0000:0000:0016 LEN=96 TC=0 HOPLIMIT=1 FLOWLBL=0 PROTO=ICMPv6 TYPE=143 CODE=0 -``` diff --git a/docs/configuration/firewall/md-flowtables.md b/docs/configuration/firewall/md-flowtables.md deleted file mode 100644 index 24d0675e..00000000 --- a/docs/configuration/firewall/md-flowtables.md +++ /dev/null @@ -1,176 +0,0 @@ ---- -lastproofread: '2026-03-30' ---- - -(firewall-flowtables-configuration)= - -# Flowtables Firewall Configuration - -```{include} /_include/need_improvement.txt -``` - - -## Overview - -This section provides information on firewall configuration for flowtables. - -```{cfgcmd} set firewall flowtable ... -``` - -To learn about the general traffic flow in VyOS firewalls, -see {doc}`Firewall `. - -```none -- set firewall - * flowtable - - custom_flow_table - + ... -``` - -Flowtables let you define a fastpath through the flowtable datapath. -Flowtables support layer 3 (IPv4 and IPv6) and layer 4 (TCP and UDP) -protocols. - -:::{figure} /_static/images/firewall-flowtable-packet-flow.webp -::: - -After the first packet successfully traverses the IP forwarding path (black -circles path), you can offload subsequent packets to the flowtable through your -ruleset. You specify when to add a flow to the flowtable during forward -filtering (red circle number 6). - -When a packet finds a matching entry in the flowtable (flowtable hit), the -system transmits it to the output netdevice. This means packets bypass the -classic IP forwarding path and use the **Fast Path** (orange circles path). -As a result, you do not see these packets from any Netfilter hooks after -ingress. If no matching entry exists in the flowtable (flowtable miss), the -packet traverses the classic IP forwarding path. - -:::{note} -**Flowtable Reference:** - -::: - -## Flowtable Configuration - -To use flowtables, you need to configure the following: -> - Create a flowtable that includes the interfaces -> that are going to be used by the flowtable. -> - Create a firewall rule. Set the action to -> `offload` and use your desired flowtable for `offload-target`. - -Creating a flow table: - -```{cfgcmd} set firewall flowtable \ interface \ - -Specify interfaces to use in the flowtable. -``` - -```{cfgcmd} set firewall flowtable \ description \ -``` - -Provide a description for the flow table. - -```{cfgcmd} set firewall flowtable \ offload \ - -Specify the offload type the flowtable uses: ``hardware`` or -``software``. The default is ``software`` offload. -``` -:::{note} -**Hardware offload**: Make sure your network interface controller -(NIC) supports hardware offloading and that you have the necessary drivers -> installed before enabling this option. -::: - -Creating rules for using flow tables: - -```{cfgcmd} set firewall [ipv4 | ipv6] forward filter rule \<1-999999\> action offload - -Create a firewall rule in the forward chain with the action set to -``offload``. -``` - -```{cfgcmd} set firewall [ipv4 | ipv6] forward filter rule \<1-999999\> offload-target \ - -Create a firewall rule in the forward chain and specify which flowtable -to use. Only applicable if the action is ``offload``. -``` - -## Configuration Example - -Consider the following in this setup: -> - This example uses two interfaces in the flowtables: `eth0` and `eth1`. -> - The example provides a minimal firewall ruleset with filtering rules -> and rules for using flowtable offload capabilities. - -The first packet is evaluated by the firewall path, so a -desired connection should be explicitly accepted. -The same should occur for traffic in reverse order. -In most cases, state policies are -used to accept a connection in the reverse path. - -In the following example only traffic coming from interface `eth0`, -TCP protocol, and destination port 1122 is accepted. -All other traffic to the router is dropped. - -### Commands - -```none -set firewall flowtable FT01 interface 'eth0' -set firewall flowtable FT01 interface 'eth1' -set firewall ipv4 forward filter default-action 'drop' -set firewall ipv4 forward filter rule 10 action 'offload' -set firewall ipv4 forward filter rule 10 offload-target 'FT01' -set firewall ipv4 forward filter rule 10 state 'established' -set firewall ipv4 forward filter rule 10 state 'related' -set firewall ipv4 forward filter rule 20 action 'accept' -set firewall ipv4 forward filter rule 20 state 'established' -set firewall ipv4 forward filter rule 20 state 'related' -set firewall ipv4 forward filter rule 110 action 'accept' -set firewall ipv4 forward filter rule 110 destination address '192.0.2.100' -set firewall ipv4 forward filter rule 110 destination port '1122' -set firewall ipv4 forward filter rule 110 inbound-interface name 'eth0' -set firewall ipv4 forward filter rule 110 protocol 'tcp' -``` - -### Explanation - -Here's what happens for a desired connection: -> 1. A packet arrives on `eth0` with destination address `192.0.2.100`, TCP -> protocol, and destination port 1122. Assume this address is reachable -> through interface `eth1`. -> 2. For this first packet, the connection state is **new**. Neither rule 10 -> nor rule 20 applies. -> 3. Rule 110 matches, so the connection is accepted. -> 4. When the server 192.0.2.100 replies, the connection state becomes -> **established**, and rule 20 accepts the reply. -> 5. The router receives the second packet for this connection. Because the -> connection state is **established**, rule 10 matches and adds a new -> entry in the flowtable FT01 for this connection. -> 6. Subsequent packets skip the traditional path and use the **Fast Path** -> for offloading. - -### Checks - -Check the conntrack table to verify that the system accepted and properly -offloaded connections. - -```none -vyos@FlowTables:~$ show firewall ipv4 forward filter -Ruleset Information - ---------------------------------- -ipv4 Firewall "forward filter" - -Rule Action Protocol Packets Bytes Conditions -------- -------- ---------- --------- ------- ---------------------------------------------------------------- -10 offload all 8 468 ct state { established, related } flow add @VYOS_FLOWTABLE_FT01 -20 accept all 8 468 ct state { established, related } accept -110 accept tcp 2 120 ip daddr 192.0.2.100 tcp dport 1122 iifname "eth0" accept -default drop all 7 420 - -vyos@FlowTables:~$ sudo conntrack -L | grep tcp -conntrack v1.4.6 (conntrack-tools): 5 flow entries have been shown. -tcp 6 src=198.51.100.100 dst=192.0.2.100 sport=41676 dport=1122 src=192.0.2.100 dst=198.51.100.100 sport=1122 dport=41676 [OFFLOAD] mark=0 use=2 -vyos@FlowTables:~$ -``` diff --git a/docs/configuration/firewall/md-global-options.md b/docs/configuration/firewall/md-global-options.md deleted file mode 100644 index 0f6d91ac..00000000 --- a/docs/configuration/firewall/md-global-options.md +++ /dev/null @@ -1,186 +0,0 @@ ---- -lastproofread: '2026-03-30' ---- - -(firewall-global-options-configuration)= - -# Global Options Firewall Configuration - -## Overview - -Some firewall settings are global and affect the entire system. This section -provides information about these global options that you can configure using -the VyOS CLI. - -Configuration commands covered in this section: - -```{cfgcmd} set firewall global-options ... -``` - -## Configuration - -```{cfgcmd} set firewall global-options all-ping [enable | disable] - -By default, when VyOS receives an ICMP echo request packet destined for -itself, it answers with an ICMP echo reply, unless your firewall prevents -it. - -You can set firewall rules to accept, drop, or reject ICMP in, out, or -local traffic. You can also use the **firewall global-options all-ping** -command. This command affects only LOCAL traffic (packets destined for your -VyOS system), not IN or OUT traffic. - -:::{note} -**firewall global-options all-ping** affects only LOCAL traffic -and always behaves in the most restrictive way -::: -:::{code-block} none -set firewall global-options all-ping enable -::: -When you set this command, VyOS answers every ICMP echo request addressed -to itself, but that response occurs only if no other rule drops or rejects -local echo requests. In case of conflict, VyOS does not answer ICMP echo -requests. - -:::{code-block} none -set firewall global-options all-ping disable -::: -When you set this command, VyOS answers no ICMP echo requests addressed to -itself, regardless of where they come from or what specific rules accept -them. -``` - -```{cfgcmd} set firewall global-options apply-to-bridged-traffic [ipv4 | ipv6] - -Apply IPv4 or IPv6 firewall rules to bridged traffic. -``` - -```{cfgcmd} set firewall global-options broadcast-ping [enable | disable] - -Enable or disable the response to ICMP broadcast messages. The system -alters the following parameter: -* ``net.ipv4.icmp_echo_ignore_broadcasts`` -``` - -```{cfgcmd} set firewall global-options ip-src-route [enable | disable] -``` - -```{cfgcmd} set firewall global-options ipv6-src-route [enable | disable] - -Set whether VyOS accepts packets with a source route option. -The following sysctl parameters will be changed: -* ``net.ipv4.conf.all.accept_source_route`` -* ``net.ipv6.conf.all.accept_source_route`` -``` - -```{cfgcmd} set firewall global-options receive-redirects [enable | disable] -``` - -```{cfgcmd} set firewall global-options ipv6-receive-redirects [enable | disable] - -Allow VyOS to accept ICMPv4 and ICMPv6 redirect messages. -The following sysctl parameters will be changed: -* ``net.ipv4.conf.all.accept_redirects`` -* ``net.ipv6.conf.all.accept_redirects`` -``` - -```{cfgcmd} set firewall global-options send-redirects [enable | disable] - -Allow VyOS to send ICMPv4 redirect messages. -The following sysctl parameter will be changed: -* ``net.ipv4.conf.all.send_redirects`` -``` - -```{cfgcmd} set firewall global-options log-martians [enable | disable] - -Allow VyOS to log martian IPv4 packets. -The following sysctl parameter will be changed: -* ``net.ipv4.conf.all.log_martians`` -``` - -```{cfgcmd} set firewall global-options source-validation [strict | loose | disable] - -Set the IPv4 source validation mode. -The following sysctl parameter will be changed: -* ``net.ipv4.conf.all.rp_filter`` -``` - -```{cfgcmd} set firewall global-options syn-cookies [enable | disable] - -Allow VyOS to use IPv4 TCP SYN Cookies. -The following sysctl parameter will be changed: -* ``net.ipv4.tcp_syncookies`` -``` - -```{cfgcmd} set firewall global-options twa-hazards-protection [enable | disable] - -Enable or disable VyOS {rfc}`1337` conformance. -The following sysctl parameter will be changed: -* ``net.ipv4.tcp_rfc1337`` -``` - -```{cfgcmd} set firewall global-options state-policy established action [accept | drop | reject] -``` - -```{cfgcmd} set firewall global-options state-policy established log -``` - -```{cfgcmd} set firewall global-options state-policy established log-level [emerg | alert | crit | err | warn | notice | info | debug] - -Set the global setting for an established connection. -``` - -```{cfgcmd} set firewall global-options state-policy invalid action [accept | drop | reject] -``` - -```{cfgcmd} set firewall global-options state-policy invalid log -``` - -```{cfgcmd} set firewall global-options state-policy invalid log-level [emerg | alert | crit | err | warn | notice | info | debug] - -Set the global setting for invalid packets. -``` - -```{cfgcmd} set firewall global-options state-policy related action [accept | drop | reject] -``` - -```{cfgcmd} set firewall global-options state-policy related log -``` - -```{cfgcmd} set firewall global-options state-policy related log-level [emerg | alert | crit | err | warn | notice | info | debug] - -Set the global setting for related connections. -``` - -VyOS supports setting timeouts for connections by connection type. You can -set timeout values for generic connections, ICMP connections, UDP -connections, or TCP connections in various states. - -```{eval-rst} -.. cfgcmd:: set firewall global-options timeout icmp <1-21474836> - :defaultvalue: -.. cfgcmd:: set firewall global-options timeout other <1-21474836> - :defaultvalue: -.. cfgcmd:: set firewall global-options timeout tcp close <1-21474836> - :defaultvalue: -.. cfgcmd:: set firewall global-options timeout tcp close-wait <1-21474836> - :defaultvalue: -.. cfgcmd:: set firewall global-options timeout tcp established <1-21474836> - :defaultvalue: -.. cfgcmd:: set firewall global-options timeout tcp fin-wait <1-21474836> - :defaultvalue: -.. cfgcmd:: set firewall global-options timeout tcp last-ack <1-21474836> - :defaultvalue: -.. cfgcmd:: set firewall global-options timeout tcp syn-recv <1-21474836> - :defaultvalue: -.. cfgcmd:: set firewall global-options timeout tcp syn-sent <1-21474836> - :defaultvalue: -.. cfgcmd:: set firewall global-options timeout tcp time-wait <1-21474836> - :defaultvalue: -.. cfgcmd:: set firewall global-options timeout udp other <1-21474836> - :defaultvalue: -.. cfgcmd:: set firewall global-options timeout udp stream <1-21474836> - :defaultvalue: - - Set the timeout in seconds for a protocol or state. -``` \ No newline at end of file diff --git a/docs/configuration/firewall/md-groups.md b/docs/configuration/firewall/md-groups.md deleted file mode 100644 index 817f610e..00000000 --- a/docs/configuration/firewall/md-groups.md +++ /dev/null @@ -1,477 +0,0 @@ ---- -lastproofread: '2026-03-30' ---- - -(firewall-groups-configuration)= - -# Firewall groups - -## Configuration - -Firewall groups represent collections of IP addresses, networks, ports, -MAC addresses, domains, or interfaces. You can reference a group in firewall, -NAT, and policy route rules as either a source or destination matcher, and/or -as inbound or outbound in the case of interface groups. - -### Address Groups - -An **address group** contains a single IP address or IP address range. - -```{cfgcmd} set firewall group address-group \ address [address | address range] - -``` -```{cfgcmd} set firewall group ipv6-address-group \ address \ - -Define an IPv4 or IPv6 address group. - -:::{code-block} none -set firewall group address-group ADR-INSIDE-v4 address 192.168.0.1 -set firewall group address-group ADR-INSIDE-v4 address 10.0.0.1-10.0.0.8 -set firewall group ipv6-address-group ADR-INSIDE-v6 address 2001:db8::1 -::: -``` - -```{cfgcmd} set firewall group address-group \ description \ -``` - -```{cfgcmd} set firewall group ipv6-address-group \ description \ - -Provide an IPv4 or IPv6 address group description. -``` - -### Remote Groups - -A **remote-group** uses a URL that hosts a newline-delimited list of IPv4 -and/or IPv6 addresses, CIDRs, and ranges. VyOS pulls this list periodically -according to the frequency you define in the firewall **resolver-interval** -and loads matching entries into the group for use in rules. The list is cached -in persistent storage, so rules continue to function if updates fail. - -```{cfgcmd} set firewall group remote-group \ url \ - -Specify a remote list of IPv4 and/or IPv6 addresses, ranges, and CIDRs -to fetch. -``` - -```{cfgcmd} set firewall group remote-group \ description \ - -Set a description for a remote group. -``` - -The remote list format is flexible. VyOS attempts to parse the first word of -each line as an entry and skips lines it cannot match. Lines that begin with -an alphanumeric character but do not match valid IPv4 or IPv6 addresses, -ranges, or CIDRs are logged to the system log. The following examples show -acceptable formats that VyOS parses correctly: - -```none -127.0.0.1 -127.0.0.0/24 -127.0.0.1-127.0.0.254 -2001:db8::1 -2001:db8:cafe::/48 -2001:db8:cafe::1-2001:db8:cafe::ffff -``` - -### Network Groups - -**Network groups** accept IP networks in CIDR notation. You can add specific -IP addresses as a 32-bit prefix. If you need to add a mix of addresses and -networks, use a network group. - -```{cfgcmd} set firewall group network-group \ network \ -``` - -```{cfgcmd} set firewall group ipv6-network-group \ network \ - -Define an IPv4 or IPv6 network group. - -:::{code-block} none -set firewall group network-group NET-INSIDE-v4 network 192.168.0.0/24 -set firewall group network-group NET-INSIDE-v4 network 192.168.1.0/24 -set firewall group ipv6-network-group NET-INSIDE-v6 network 2001:db8::/64 -::: -``` - -```{cfgcmd} set firewall group network-group \ description \ -``` - -```{cfgcmd} set firewall group ipv6-network-group \ description \ - -Provide an IPv4 or IPv6 network group description. -``` - -### Interface Groups - -An **interface group** represents a collection of interfaces. - -```{cfgcmd} set firewall group interface-group \ interface \ - -Define an interface group. -Wildcard ``*`` is supported. For example: ``eth3*``. -Prepend the character ``!`` to invert the criteria. For example: ``!eth2``. -``` - -```none -set firewall group interface-group LAN interface bond1001 -set firewall group interface-group LAN interface eth3* -``` - -```{cfgcmd} set firewall group interface-group \ description \ - -Provide an interface group description. -``` - -### Port Groups - -A **port group** represents only port numbers, not the protocol. You can -reference port groups for either TCP or UDP. Create TCP and UDP groups -separately to avoid accidentally filtering unnecessary ports. Specify port -ranges by using `-`. - -```{cfgcmd} set firewall group port-group \ port [portname | portnumber | startport-endport] - -Define a port group. A port name can be any name defined in -/etc/services. For example, ``http``. - -:::{code-block} none -set firewall group port-group PORT-TCP-SERVER1 port http -set firewall group port-group PORT-TCP-SERVER1 port 443 -set firewall group port-group PORT-TCP-SERVER1 port 5000-5010 -::: -``` - -```{cfgcmd} set firewall group port-group \ description \ - -Provide a port group description. -``` - -### MAC Groups - -A **mac group** represents a collection of mac addresses. - -```{cfgcmd} set firewall group mac-group \ mac-address \ - -Define a mac group. -``` - -```none -set firewall group mac-group MAC-G01 mac-address 88:a4:c2:15:b6:4f -set firewall group mac-group MAC-G01 mac-address 4c:d5:77:c0:19:81 -``` - -```{cfgcmd} set firewall group mac-group \ description \ - -Provide a MAC group description. -``` - -### Domain Groups - -A **domain group** represents a collection of domains. - -```{cfgcmd} set firewall group domain-group \ address \ - -Define a domain group. -``` - -```none -set firewall group domain-group DOM address example.com -``` - -```{cfgcmd} set firewall group domain-group \ description \ - -Provide a domain group description. -``` - -### Dynamic Groups - -Firewall dynamic groups differ from other groups because you can use them as -source/destination in firewall rules, and members are not defined statically -in VyOS configuration. Instead, firewall rules dynamically add members to -these groups. - -#### Defining Dynamic Address Groups - -Dynamic address groups support both IPv4 and IPv6 families. Use these -commands to define dynamic IPv4 and IPv6 address groups: - -```{cfgcmd} set firewall group dynamic-group address-group \ -``` - -```{cfgcmd} set firewall group dynamic-group ipv6-address-group \ -``` - -Add description to firewall groups: - -```{cfgcmd} set firewall group dynamic-group address-group \ description \ -``` - -```{cfgcmd} set firewall group dynamic-group ipv6-address-group \ description \ -``` - -#### Adding elements to Dynamic Firewall Groups - -After you define dynamic firewall groups, use them in firewall rules to -dynamically add elements to them. - -Commands used for this task are: -- Add destination IP address of the connection to a dynamic address group: - -```{cfgcmd} set firewall ipv4 [forward | input | output] filter rule \<1-999999\> add-address-to-group destination-address address-group \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> add-address-to-group destination-address address-group \ -``` - -```{cfgcmd} set firewall ipv6 [forward | input | output] filter rule \<1-999999\> add-address-to-group destination-address address-group \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> add-address-to-group destination-address address-group \ -``` - -- Add source IP address of the connection to a dynamic address group: - -```{cfgcmd} set firewall ipv4 [forward | input | output] filter rule \<1-999999\> add-address-to-group source-address address-group \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> add-address-to-group source-address address-group \ -``` - -```{cfgcmd} set firewall ipv6 [forward | input | output] filter rule \<1-999999\> add-address-to-group source-address address-group \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> add-address-to-group source-address address-group \ -``` - -You can define specific timeouts per rule. When a rule matches, the source or -destination address is added to the group, and the element remains in the group -until the timeout expires. If you do not define a timeout, the element remains -in the group until the next reboot or until you commit firewall configuration -changes. - -```{cfgcmd} set firewall ipv4 [forward | input | output] filter rule \<1-999999\> add-address-to-group [destination-address | source-address] timeout \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> add-address-to-group [destination-address | source-address] timeout \ -``` - -```{cfgcmd} set firewall ipv6 [forward | input | output] filter rule \<1-999999\> add-address-to-group [destination-address | source-address] timeout \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> add-address-to-group [destination-address | source-address] timeout \ -``` - -Timeout can be defined using seconds, minutes, hours or days: - -```none -set firewall ipv6 name FOO rule 10 add-address-to-group source-address timeout -Possible completions: -s Timeout value in seconds -m Timeout value in minutes -h Timeout value in hours -d Timeout value in days -``` - -#### Using Dynamic Firewall Groups - -Like other firewall groups, you can use dynamic firewall groups in firewall -rules as matching options. For example: - -```none -set firewall ipv4 input filter rule 10 source group dynamic-address-group FOO -set firewall ipv4 input filter rule 10 destination group dynamic-address-group BAR -``` - -## Examples - -### General example - -After you create firewall groups, you can reference them in firewall, NAT, -NAT66, and/or policy-route rules. The following example creates multiple -groups: - -```{eval-rst} - .. code-block:: none - - set firewall group address-group SERVERS address 198.51.100.101 - set firewall group address-group SERVERS address 198.51.100.102 - set firewall group network-group TRUSTEDv4 network 192.0.2.0/30 - set firewall group network-group TRUSTEDv4 network 203.0.113.128/25 - set firewall group ipv6-network-group TRUSTEDv6 network 2001:db8::/64 - set firewall group interface-group LAN interface eth2.2001 - set firewall group interface-group LAN interface bon0 - set firewall group port-group PORT-SERVERS port http - set firewall group port-group PORT-SERVERS port 443 - set firewall group port-group PORT-SERVERS port 5000-5010 -``` - -And next, some configuration example where groups are used: - -```{eval-rst} - .. code-block:: none - - set firewall ipv4 output filter rule 10 action accept - set firewall ipv4 output filter rule 10 outbound-interface group !LAN - set firewall ipv4 forward filter rule 20 action accept - set firewall ipv4 forward filter rule 20 source group network-group TRUSTEDv4 - set firewall ipv6 input filter rule 10 action accept - set firewall ipv6 input filter rule 10 source group network-group TRUSTEDv6 - set nat destination rule 101 inbound-interface group LAN - set nat destination rule 101 destination group address-group SERVERS - set nat destination rule 101 protocol tcp - set nat destination rule 101 destination group port-group PORT-SERVERS - set nat destination rule 101 translation address 203.0.113.250 - set policy route PBR rule 201 destination group port-group PORT-SERVERS - set policy route PBR rule 201 protocol tcp - set policy route PBR rule 201 set table 15 -``` - -### Port knocking example - -You can use dynamic firewall groups with port knocking to secure access to -the router or any other device. The following example shows a 4-step port -knocking configuration: - -```{eval-rst} - .. code-block:: none - - set firewall global-options state-policy established action 'accept' - set firewall global-options state-policy invalid action 'drop' - set firewall global-options state-policy related action 'accept' - set firewall group dynamic-group address-group ALLOWED - set firewall group dynamic-group address-group PN_01 - set firewall group dynamic-group address-group PN_02 - set firewall ipv4 input filter default-action 'drop' - set firewall ipv4 input filter rule 5 action 'accept' - set firewall ipv4 input filter rule 5 protocol 'icmp' - set firewall ipv4 input filter rule 10 action 'drop' - set firewall ipv4 input filter rule 10 add-address-to-group source-address address-group 'PN_01' - set firewall ipv4 input filter rule 10 add-address-to-group source-address timeout '2m' - set firewall ipv4 input filter rule 10 description 'Port_nock 01' - set firewall ipv4 input filter rule 10 destination port '9990' - set firewall ipv4 input filter rule 10 protocol 'tcp' - set firewall ipv4 input filter rule 20 action 'drop' - set firewall ipv4 input filter rule 20 add-address-to-group source-address address-group 'PN_02' - set firewall ipv4 input filter rule 20 add-address-to-group source-address timeout '3m' - set firewall ipv4 input filter rule 20 description 'Port_nock 02' - set firewall ipv4 input filter rule 20 destination port '9991' - set firewall ipv4 input filter rule 20 protocol 'tcp' - set firewall ipv4 input filter rule 20 source group dynamic-address-group 'PN_01' - set firewall ipv4 input filter rule 30 action 'drop' - set firewall ipv4 input filter rule 30 add-address-to-group source-address address-group 'ALLOWED' - set firewall ipv4 input filter rule 30 add-address-to-group source-address timeout '2h' - set firewall ipv4 input filter rule 30 description 'Port_nock 03' - set firewall ipv4 input filter rule 30 destination port '9992' - set firewall ipv4 input filter rule 30 protocol 'tcp' - set firewall ipv4 input filter rule 30 source group dynamic-address-group 'PN_02' - set firewall ipv4 input filter rule 99 action 'accept' - set firewall ipv4 input filter rule 99 description 'Port_nock 04 - Allow ssh' - set firewall ipv4 input filter rule 99 destination port '22' - set firewall ipv4 input filter rule 99 protocol 'tcp' - set firewall ipv4 input filter rule 99 source group dynamic-address-group 'ALLOWED' -``` - -Before testing, we can check the members of firewall groups: - -```none -vyos@vyos# run show firewall group -Firewall Groups - -Name Type References Members Timeout Expires -------- ---------------------- -------------------- ------------- --------- --------- -ALLOWED address_group(dynamic) ipv4-input-filter-30 N/D N/D N/D -PN_01 address_group(dynamic) ipv4-input-filter-10 N/D N/D N/D -PN_02 address_group(dynamic) ipv4-input-filter-20 N/D N/D N/D -[edit] -vyos@vyos# -``` - -With this configuration, to gain SSH access to the router, the user must: - -1. Create a new TCP connection to destination port 9990. A new entry is added - to dynamic firewall group `PN_01`. - - ```none - vyos@vyos# run show firewall group - Firewall Groups - - Name Type References Members Timeout Expires - ------- ---------------------- -------------------- ------------- --------- --------- - ALLOWED address_group(dynamic) ipv4-input-filter-30 N/D N/D N/D - PN_01 address_group(dynamic) ipv4-input-filter-10 192.168.89.31 120 119 - PN_02 address_group(dynamic) ipv4-input-filter-20 N/D N/D N/D - [edit] - vyos@vyos# - ``` - -2. Create a new TCP connection to destination port 9991. A new entry is added - to dynamic firewall group `PN_02`. - - ```none - vyos@vyos# run show firewall group - Firewall Groups - - Name Type References Members Timeout Expires - ------- ---------------------- -------------------- ------------- --------- --------- - ALLOWED address_group(dynamic) ipv4-input-filter-30 N/D N/D N/D - PN_01 address_group(dynamic) ipv4-input-filter-10 192.168.89.31 120 106 - PN_02 address_group(dynamic) ipv4-input-filter-20 192.168.89.31 180 179 - [edit] - vyos@vyos# - ``` - -3. Create a new TCP connection to destination port 9992. A new entry is added - to dynamic firewall group `ALLOWED`. - - ```none - vyos@vyos# run show firewall group - Firewall Groups - - Name Type References Members Timeout Expires - ------- ---------------------- -------------------- ------------- --------- --------- - ALLOWED address_group(dynamic) ipv4-input-filter-30 192.168.89.31 7200 7199 - PN_01 address_group(dynamic) ipv4-input-filter-10 192.168.89.31 120 89 - PN_02 address_group(dynamic) ipv4-input-filter-20 192.168.89.31 180 170 - [edit] - vyos@vyos# - ``` - -4. Now you can connect via SSH to the router (assuming SSH is - configured). - -## Operation-mode - -```{opcmd} show firewall group -``` - -```{opcmd} show firewall group \ - -Display an overview of defined groups, including the firewall group name, -type, references (where the group is used), members, timeout, and -expiration (the last two only apply to dynamic firewall groups). -``` - -Here is an example of such command: - -```none -vyos@vyos:~$ show firewall group -Firewall Groups - -Name Type References Members Timeout Expires ------------- ---------------------- ---------------------- ---------------- --------- --------- -SERVERS address_group nat-destination-101 198.51.100.101 - 198.51.100.102 -ALLOWED address_group(dynamic) ipv4-input-filter-30 192.168.77.39 7200 7174 -PN_01 address_group(dynamic) ipv4-input-filter-10 192.168.0.245 120 112 - 192.168.77.39 120 85 -PN_02 address_group(dynamic) ipv4-input-filter-20 192.168.77.39 180 151 -LAN interface_group ipv4-output-filter-10 bon0 - nat-destination-101 eth2.2001 -TRUSTEDv6 ipv6_network_group ipv6-input-filter-10 2001:db8::/64 -TRUSTEDv4 network_group ipv4-forward-filter-20 192.0.2.0/30 - 203.0.113.128/25 -PORT-SERVERS port_group route-PBR-201 443 - route-PBR-201 5000-5010 - nat-destination-101 http -vyos@vyos:~$ -``` diff --git a/docs/configuration/firewall/md-index.md b/docs/configuration/firewall/md-index.md deleted file mode 100644 index 9108a800..00000000 --- a/docs/configuration/firewall/md-index.md +++ /dev/null @@ -1,278 +0,0 @@ ---- -lastproofread: '2026-03-30' ---- - -# Firewall - -:::{warning} -Due to a boot-time race condition, all interfaces initialize -before the firewall. This temporarily leaves the system open to all traffic -and poses a security risk. -::: - -VyOS uses Netfilter. The Netfilter -project developed `iptables` and its successor `nftables` for the Linux -kernel to process packet data flows directly. This extends the concept of -zone-based security to let you manipulate data at multiple stages after the -network interface and driver accept it, and before sending it to its -destination (for example, a web server or another device). - -The following is a simplified traffic flow diagram based on Netfilter -packet flow. -This diagram provides an overview of how packets are processed and the -possible paths traffic can take. - -:::{figure} /_static/images/firewall-gral-packet-flow.webp -::: - -The main points regarding packet flow and terminology in VyOS firewall -are: - -- **Bridge Port?**: Choose the appropriate path based on whether the - interface where the packet was received is part of a bridge. - -If the interface where the packet was received is not part of a bridge, the -packet is processed at the **IP Layer**: - -```{eval-rst} - * **Prerouting**: The router processes all packets in this stage, - regardless of the destination. You can perform several actions in - this stage, and these actions are also defined in different parts of the - VyOS configuration. Order is important. The relevant configuration that - applies in this stage includes: - - * **Firewall prerouting**: Rules you define under ``set firewall - [ipv4 | ipv6] prerouting raw...``. The system processes all rules in - this section before the connection tracking subsystem. - - * **Conntrack Ignore**: Rules you define under ``set system conntrack - ignore [ipv4 | ipv6] ...``. You can configure this section with - ``firewall [ipv4 | ipv6] prerouting ...``. For compatibility reasons, - this feature is supported, but will be deprecated in the future. - - * **Policy Route**: Rules you define under ``set policy [route | - route6] ...``. - - * **Destination NAT**: Rules you define under ``set [nat | nat66] - destination...``. - - * **Destination is the router?**: Choose the appropriate path based on the - destination IP address. Transit traffic continues to **forward**, while - traffic destined for the router continues to **input**. - - * **Input**: The stage where you filter and control traffic destined for - the router itself. This is where you enforce all rules for securing the - router. This includes IPv4 and IPv6 filtering rules, defined in: - - * ``set firewall ipv4 input filter ...``. - - * ``set firewall ipv6 input filter ...``. - - * **Forward**: The stage where you filter and control transit traffic. - This includes IPv4 and IPv6 filtering rules, defined in: - - * ``set firewall ipv4 forward filter ...``. - - * ``set firewall ipv6 forward filter ...``. - - * **Output**: The stage where you filter and control traffic that the - router originates. Note that this traffic comes from either a new - connection that an internal process on the VyOS router (such as NTP) - originates or a response to traffic the router receives externally through - **input** (for example, a response to an SSH login attempt). This includes - IPv4 and IPv6 rules, and two different sections apply: - - * **Output Prerouting**: ``set firewall [ipv4 | ipv6] output - raw ...``. As described in **Prerouting**, the system processes - rules in this section before the connection tracking subsystem. - - * **Output Filter**: ``set firewall [ipv4 | ipv6] output filter ...``. - - * **Postrouting**: As in **Prerouting**, you can perform several actions - defined in different parts of VyOS configuration in this stage. This - includes: - - * **Source NAT**: Rules you define under ``set [nat | nat66] - source...``. -``` - -If the interface where the packet was received is part of a bridge, the -packet is processed at the **Bridge Layer**: - -```{eval-rst} - * **Prerouting (Bridge)**: The bridge processes all packets it receives in - this stage, regardless of the destination. First, you can apply filters - here, or you can configure rules that ignore the connection tracking - system. The relevant configuration that applies: - - * ``set firewall bridge prerouting filter ...``. - - * **Forward (Bridge)**: The stage where you filter and control traffic - that passes through the bridge: - - * ``set firewall bridge forward filter ...``. - - * **Input (Bridge)**: The stage where you filter and control traffic - destined for the bridge itself: - - * ``set firewall bridge input filter ...``. - - * **Output (Bridge)**: The stage where you filter and control traffic that - the bridge originates: - - * ``set firewall bridge output filter ...``. -``` - -The following is the overall structure of the VyOS firewall CLI: - -```none -- set firewall - * bridge - - forward - + filter - - input - + filter - - output - + filter - - prerouting - + filter - - name - + custom_name - * flowtable - - custom_flow_table - + ... - * global-options - + all-ping - + broadcast-ping - + ... - * group - - address-group - - ipv6-address-group - - network-group - - ipv6-network-group - - interface-group - - mac-group - - port-group - - domain-group - * ipv4 - - forward - + filter - - input - + filter - - output - + filter - + raw - - prerouting - + raw - - name - + custom_name - * ipv6 - - forward - + filter - - input - + filter - - output - + filter - + raw - - prerouting - + raw - - ipv6-name - + custom_name - * zone - - custom_zone_name - + ... -``` - -Here is a list of VyOS firewall CLI subcommands and their -corresponding pages in the documentation: - -```{cfgcmd} set firewall bridge ... - -Configure bridge firewall rules for traffic at the bridge layer. -See the Bridge Firewall Configuration page for detailed information. -``` - -```{cfgcmd} set firewall flowtable ... - -Configure firewall flowtables for stateful connection tracking and rules. -See the Flowtables Firewall Configuration page for detailed information. -``` - -```{cfgcmd} set firewall global-options ... - -Configure global firewall options such as ``all-ping``, ``broadcast-ping``, -``syn-cookies``, and other system-wide firewall settings. -See the Global Firewall Options page for detailed information. -``` - -```{cfgcmd} set firewall group ... - -Organize firewall rules by creating reusable address, network, interface, -MAC, port, and domain groups. Use groups in multiple rules to simplify -configuration and maintenance. -See the Firewall Groups page for detailed information. -``` - -```{cfgcmd} set firewall ipv4 ... - -Configure IPv4-specific firewall rules. -See the IPv4 Firewall Configuration page for detailed information. -``` - -```{cfgcmd} set firewall ipv6 ... - -Configure IPv6-specific firewall rules. -See the IPv6 Firewall Configuration page for detailed information. -``` - -```{cfgcmd} set firewall zone ... - -Configure zone-based firewall policies for controlling traffic between -different network zones. -See the Zone-Based Firewall Configuration page for detailed information. -``` - -For more information on firewall configuration, see the following pages: - -```{toctree} -:includehidden: true -:maxdepth: 1 - -global-options -groups -bridge -ipv4 -ipv6 -flowtables -``` - -:::{note} -For more information on Netfilter hooks and Linux networking packet flows, -see the [Netfilter-Hooks]() -documentation. -::: - -## Zone-Based firewall - -```{toctree} -:includehidden: true -:maxdepth: 1 - -zone -``` - -With zone-based firewalls, a new concept applies. In addition to the standard -in and out traffic flows, a local flow enables traffic originating from and -destined to the router itself. This means you must configure additional rules to -secure the firewall from the network, in addition to the existing inbound and -outbound rules. - -To configure VyOS with zone-based firewall, see -{doc}`Zone-Based Firewall Configuration `. - -As the following example image shows, you must configure rules to allow or block -traffic to or from the services running on the device that have open -connections on that interface. - -:::{figure} /_static/images/firewall-zonebased.webp -::: diff --git a/docs/configuration/firewall/md-ipv4.md b/docs/configuration/firewall/md-ipv4.md deleted file mode 100644 index 2107065d..00000000 --- a/docs/configuration/firewall/md-ipv4.md +++ /dev/null @@ -1,1517 +0,0 @@ ---- -lastproofread: '2026-03-30' ---- - -(firewall-ipv4-configuration)= - -# IPv4 Firewall Configuration - -## Overview - -This section provides information on IPv4 firewall configuration and -appropriate operation-mode commands. This section covers the following -configuration commands: - -```{cfgcmd} set firewall ipv4 ... -``` - -To learn about the general traffic flow in VyOS firewalls, see {doc}`Firewall `. - -```none -- set firewall - * ipv4 - - forward - + filter - - input - + filter - - output - + filter - + raw - - prerouting - + raw - - name - + custom_name -``` - -First, the router receives all traffic and processes it in the **prerouting** -stage. - -This stage includes: - -- **Firewall Prerouting**: commands found under `set firewall ipv4 - prerouting raw ...` -- {doc}`Conntrack Ignore`: `set system - conntrack ignore ipv4...` -- {doc}`Policy Route`: commands found under - `set policy route ...` -- {doc}`Destination NAT`: commands found under - `set nat destination ...` - -For transit traffic, which is received by the router and forwarded, the base -chain is **forward**. The following is a simplified packet flow diagram for -transit traffic: - -:::{figure} /_static/images/firewall-fwd-packet-flow.webp -::: - -The base firewall chain for configuring filtering rules for transit traffic is -`set firewall ipv4 forward filter ...`, which occurs in stage 5, highlighted -in red. - -For traffic to the router itself, the base chain is **input**. For traffic -the router originates, the base chain is **output**. A simplified packet flow -diagram is shown next, which shows the path for traffic destined to the router -itself and traffic the router generates (starting from circle number 6): - -:::{figure} /_static/images/firewall-input-packet-flow.webp -::: - -The base chain for traffic towards the router is -`set firewall ipv4 input filter ...` - -The base chain for traffic the router generates is `set firewall ipv4 -output ...`, where two sub-chains are available: **filter** and **raw**: - -- **Output Prerouting**: `set firewall ipv4 output raw ...`. As described - in **Prerouting**, the system processes rules in this section before the - connection tracking subsystem. -- **Output Filter**: `set firewall ipv4 output filter ...`. The system - processes rules in this section after the connection tracking subsystem. - -:::{note} -**Important note about default-actions:** -If you do not define a default action for a base chain, the system sets -the default action to **accept** for that chain. For custom chains, if you -do not define a default action, the system sets the default-action to -**drop**. -::: - -You can create custom firewall chains using the following commands: -`set firewall ipv4 name ...`. To use a custom chain, you must define -a rule with the **action jump** and the appropriate **target** in a base -chain. - -## Firewall - IPv4 Rules - -Each firewall rule has a -number, an action to apply if the rule matches, and the ability to specify -multiple matching criteria. Packets traverse rules numbered 1-999999, so order -is crucial. The system executes the rule action at the first match. - -### Actions - -If you define a rule, you must define an action for it. The action tells the -firewall what to do if all the criteria you define for that rule are met. - -The action can be: - -- `accept`: Accept the packet. -- `continue`: Continue parsing the next rule. -- `drop`: Drop the packet. -- `reject`: Reject the packet. -- `jump`: Jump to another custom chain. -- `return`: Return from the current chain and continue at the next rule - of the last chain. -- `queue`: Enqueue packet to userspace. -- `synproxy`: Synproxy the packet. - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> action [accept | continue | drop | jump | queue | reject | return | synproxy] -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> action [accept | continue | drop | jump | queue | reject | return | synproxy] -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> action [accept | continue | drop | jump | queue | reject | return] -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> action [accept | continue | drop | jump | queue | reject | return] - -This required setting defines the action of the current rule. If you set -the action to jump, you must also specify a jump-target. -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> jump-target \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> jump-target \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> jump-target \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> jump-target \ - -Use this command only when the action is set to ``jump``. Specify the -jump target. -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> queue \<0-65535\> -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> queue \<0-65535\> -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> queue \<0-65535\> -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> queue \<0-65535\> - -Use this command only when the action is set to ``queue``. Specify the -queue target to use. Queue range is also supported. -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> queue-options bypass -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> queue-options bypass -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> queue-options bypass -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> queue-options bypass - -Use this command only when the action is set to ``queue``. Allow the packet -to pass through the firewall when no userspace software is connected to the -queue. -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> queue-options fanout -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> queue-options fanout -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> queue-options fanout -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> queue-options fanout - -Use this command only when the action is set to ``queue``. Distribute -packets between several queues. -``` - -Also, **default-action** is an action that applies when a packet does not -match any rule in its chain. For base chains, possible options for -**default-action** are **accept** or **drop**. - -```{cfgcmd} set firewall ipv4 forward filter default-action [accept | drop] -``` - -```{cfgcmd} set firewall ipv4 input filter default-action [accept | drop] -``` - -```{cfgcmd} set firewall ipv4 output filter default-action [accept | drop] -``` - -```{cfgcmd} set firewall ipv4 name \ default-action [accept | drop | jump | queue | reject | return] - -This command sets the default action of the rule-set if a packet does not -match the criteria of any rule. If you set the default-action to ``jump``, -you must also specify ``default-jump-target``. Note that for base chains, -you can set the default action only to ``accept`` or ``drop``, while on -custom chains, more actions are available. -``` - -```{cfgcmd} set firewall ipv4 name \ default-jump-target \ - -Use this command only when you set ``default-action`` to ``jump``. Specify -the jump target for the default rule. -``` -:::{note} -**Important note about default-actions:** -If you do not define a default action for a base chain, the system sets -the default action to **accept** for that chain. For custom chains, if you -do not define a default action, the system sets the default-action to -**drop**. -::: - -### Firewall Logs - -You can enable logging for every single firewall rule. If you enable logging, -you can define other log options. - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> log -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> log -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> log -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> log - -Enable logging for the matched packet. If this command is not present, then -logging is not enabled. -``` - -```{cfgcmd} set firewall ipv4 forward filter default-log -``` - -```{cfgcmd} set firewall ipv4 input filter default-log -``` - -```{cfgcmd} set firewall ipv4 output filter default-log -``` - -```{cfgcmd} set firewall ipv4 name \ default-log - -Use this command to enable logging of the default action on the specified -chain. -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> log-options level [emerg | alert | crit | err | warn | notice | info | debug] -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> log-options level [emerg | alert | crit | err | warn | notice | info | debug] -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> log-options level [emerg | alert | crit | err | warn | notice | info | debug] -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> log-options level [emerg | alert | crit | err | warn | notice | info | debug] - -Define the log level. Only applicable if you enable rule logging. -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> log-options group \<0-65535\> -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> log-options group \<0-65535\> -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> log-options group \<0-65535\> -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> log-options group \<0-65535\> - -Define the log group to send messages to. Only applicable if you enable rule -logging. -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> log-options snapshot-length \<0-9000\> -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> log-options snapshot-length \<0-9000\> -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> log-options snapshot-length \<0-9000\> -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> log-options snapshot-length \<0-9000\> - -Define the length of packet payload to include in a netlink message. Only -applicable if you enable rule logging and define the log group. -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> log-options queue-threshold \<0-65535\> -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> log-options queue-threshold \<0-65535\> -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> log-options queue-threshold \<0-65535\> -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> log-options queue-threshold \<0-65535\> - -Define the number of packets to queue inside the kernel before sending them -to userspace. Only applicable if you enable rule logging and define the log -group. -``` - -### Firewall Description - -You can add a description for reference for every single rule and for every -defined custom chain. - -```{cfgcmd} set firewall ipv4 name \ description \ - -Provide a rule-set description for a custom firewall chain. -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> description \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> description \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> description \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> description \ - -Provide a description for each rule. -``` - -### Rule Status - -When you define a rule, it is enabled by default. In some cases, it is useful -to disable the rule rather than removing it. - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> disable -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> disable -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> disable -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> disable - -Command for disabling a rule but keeping it in the configuration. -``` - -### Matching criteria - -There are a lot of matching criteria against which the packet can be tested. - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> connection-status nat [destination | source] -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> connection-status nat [destination | source] -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> connection-status nat [destination | source] -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> connection-status nat [destination | source] - -Match based on nat connection status. -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> connection-mark \<1-2147483647\> -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> connection-mark \<1-2147483647\> -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> connection-mark \<1-2147483647\> -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> connection-mark \<1-2147483647\> - -Match based on connection mark. -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> conntrack-helper \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> conntrack-helper \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> conntrack-helper \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> conntrack-helper \ - -Match based on connection tracking protocol helper module to secure use of -that helper module. See below for possible completions \. - -:::{code-block} none -Possible completions: -ftp Related traffic from FTP helper -h323 Related traffic from H.323 helper -pptp Related traffic from PPTP helper -nfs Related traffic from NFS helper -sip Related traffic from SIP helper -tftp Related traffic from TFTP helper -sqlnet Related traffic from SQLNet helper -::: -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> source address [address | addressrange | CIDR] -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> source address [address | addressrange | CIDR] -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> source address [address | addressrange | CIDR] -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> source address [address | addressrange | CIDR] -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> destination address [address | addressrange | CIDR] -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> destination address [address | addressrange | CIDR] -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> destination address [address | addressrange | CIDR] -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> destination address [address | addressrange | CIDR] - -Match criteria based on source and/or destination address. This is similar -to the network groups part, but here you are able to negate the matching -addresses. - -:::{code-block} none -set firewall ipv4 name FOO rule 50 source address 192.0.2.10-192.0.2.11 -# with a '!' the rule match everything except the specified subnet -set firewall ipv4 name FOO rule 51 source address !203.0.113.0/24 -::: -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> source address-mask [address] -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> source address-mask [address] -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> source address-mask [address] -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> source address-mask [address] -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> destination address-mask [address] -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> destination address-mask [address] -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> destination address-mask [address] -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> destination address-mask [address] - -An arbitrary netmask can be applied to mask addresses to only match against -a specific portion. - -This functions for both individual addresses and address groups. - -:::{code-block} none -# Match any IPv4 address with `11` as the 2nd octet and `13` as the forth octet -set firewall ipv4 name FOO rule 100 destination address 0.11.0.13 -set firewall ipv4 name FOO rule 100 destination address-mask 0.255.0.255 -::: -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> source fqdn \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> source fqdn \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> source fqdn \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> source fqdn \ -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> destination fqdn \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> destination fqdn \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> destination fqdn \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> destination fqdn \ - -Specify a Fully Qualified Domain Name as source/destination to match. Ensure -that the router is able to resolve this dns query. -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> source geoip country-code \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> source geoip country-code \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> source geoip country-code \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> source geoip country-code \ -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> destination geoip country-code \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> destination geoip country-code \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> destination geoip country-code \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> destination geoip country-code \ -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> source geoip inverse-match -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> source geoip inverse-match -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> source geoip inverse-match -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> source geoip inverse-match -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> destination geoip inverse-match -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> destination geoip inverse-match -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> destination geoip inverse-match -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> destination geoip inverse-match - -Match IP addresses based on its geolocation. More info: geoip matching. -Use inverse-match to match anything except the given country-codes. -``` - -Data is provided by DB-IP.com under CC-BY-4.0 license. Attribution required, -permits redistribution so we can include a database in images(~3MB -compressed). Includes cron script (manually callable by op-mode update -geoip) to keep database and rules updated. - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> source mac-address \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> source mac-address \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> source mac-address \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> source mac-address \ - -You can only specify a source mac-address to match. - -:::{code-block} none -set firewall ipv4 input filter rule 100 source mac-address 00:53:00:11:22:33 -set firewall ipv4 input filter rule 101 source mac-address !00:53:00:aa:12:34 -::: -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> source port [1-65535 | portname | start-end] -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> source port [1-65535 | portname | start-end] -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> source port [1-65535 | portname | start-end] -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> source port [1-65535 | portname | start-end] -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> destination port [1-65535 | portname | start-end] -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> destination port [1-65535 | portname | start-end] -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> destination port [1-65535 | portname | start-end] -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> destination port [1-65535 | portname | start-end] - -A port can be set by number or name as defined in ``/etc/services``. - -:::{code-block} none -set firewall ipv4 forward filter rule 10 source port '22' -set firewall ipv4 forward filter rule 11 source port '!http' -set firewall ipv4 forward filter rule 12 source port 'https' -::: -Multiple source ports can be specified as a comma-separated list. -The whole list can also be "negated" using ``!``. For example: -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> source group address-group \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> source group address-group \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> source group address-group \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> source group address-group \ -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> destination group address-group \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> destination group address-group \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> destination group address-group \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> destination group address-group \ - -Use a specific address-group. Prepending the character ``!`` to invert the -criteria to match is also supported. -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> source group dynamic-address-group \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> source group dynamic-address-group \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> source group dynamic-address-group \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> source group dynamic-address-group \ -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> destination group dynamic-address-group \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> destination group dynamic-address-group \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> destination group dynamic-address-group \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> destination group dynamic-address-group \ - -Use a specific dynamic-address-group. Prepending the character ``!`` to -invert the criteria to match is also supported. -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> source group network-group \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> source group network-group \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> source group network-group \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> source group network-group \ -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> destination group network-group \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> destination group network-group \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> destination group network-group \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> destination group network-group \ - -Use a specific network-group. Prepending the character ``!`` to invert the -criteria to match is also supported. -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> source group port-group \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> source group port-group \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> source group port-group \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> source group port-group \ -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> destination group port-group \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> destination group port-group \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> destination group port-group \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> destination group port-group \ - -Use a specific port-group. Prepending the character ``!`` to invert the -criteria to match is also supported. -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> source group domain-group \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> source group domain-group \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> source group domain-group \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> source group domain-group \ -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> destination group domain-group \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> destination group domain-group \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> destination group domain-group \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> destination group domain-group \ - -Use a specific domain-group. Prepending the character ``!`` to invert the -criteria to match is also supported. -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> source group mac-group \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> source group mac-group \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> source group mac-group \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> source group mac-group \ -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> destination group mac-group \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> destination group mac-group \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> destination group mac-group \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> destination group mac-group \ - -Use a specific mac-group. Prepending the character ``!`` to invert the -criteria to match is also supported. -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> dscp [0-63 | start-end] -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> dscp [0-63 | start-end] -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> dscp [0-63 | start-end] -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> dscp [0-63 | start-end] -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> dscp-exclude [0-63 | start-end] -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> dscp-exclude [0-63 | start-end] -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> dscp-exclude [0-63 | start-end] -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> dscp-exclude [0-63 | start-end] - -Match based on dscp value. -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> fragment [match-frag | match-non-frag] -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> fragment [match-frag | match-non-frag] -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> fragment [match-frag | match-non-frag] -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> fragment [match-frag | match-non-frag] - -Match based on fragmentation. -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> icmp [code | type] \<0-255\> -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> icmp [code | type] \<0-255\> -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> icmp [code | type] \<0-255\> -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> icmp [code | type] \<0-255\> - -Match based on icmp code and type. -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> icmp type-name \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> icmp type-name \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> icmp type-name \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> icmp type-name \ - -Match based on icmp type-name. Use tab for information -about what **type-name** criteria are supported. -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> inbound-interface name \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> inbound-interface name \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> inbound-interface name \ - -Match based on inbound interface. Wildcard ``*`` is supported. For example: -``eth2*``. Prepend the character ``!`` to invert the criteria. For example: -``!eth2`` -``` -:::{note} -If an interface is attached to a non-default vrf, when using -**inbound-interface**, the vrf name must be used. For example `set firewall -ipv4 forward filter rule 10 inbound-interface name MGMT` -::: -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> inbound-interface group \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> inbound-interface group \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> inbound-interface group \ - -Match based on the inbound interface group. Prepend the character ``!`` to -invert the criteria. For example, ``!IFACE_GROUP`` -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> outbound-interface name \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> outbound-interface name \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> outbound-interface name \ - -Match based on outbound interface. Wildcard ``*`` is supported. For example: -``eth2*``. Prepend the character ``!`` to invert the criteria. For example: -``!eth2`` -``` -:::{note} -If an interface is attached to a non-default vrf, when using -**outbound-interface**, the real interface name must be used. For example -`set firewall ipv4 forward filter rule 10 outbound-interface name eth0` -::: -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> outbound-interface group \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> outbound-interface group \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> outbound-interface group \ - -Match based on outbound interface group. Prepend the character ``!`` to -invert the criteria. For example: ``!IFACE_GROUP`` -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> ipsec [match-ipsec-in | match-ipsec-out | match-none-in | match-none-out] -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> ipsec [match-ipsec-in | match-none-in] -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> ipsec [match-ipsec-out | match-none-out] -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> ipsec [match-ipsec-in | match-ipsec-out | match-none-in | match-none-out] - -Match based on ipsec. -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> limit burst \<0-4294967295\> -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> limit burst \<0-4294967295\> -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> limit burst \<0-4294967295\> -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> limit burst \<0-4294967295\> - -Match based on the maximum number of packets to allow in excess of rate. -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> limit rate \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> limit rate \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> limit rate \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> limit rate \ - -Specify the maximum average rate as **integer/unit**. For example: -**5/minutes** -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> packet-length \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> packet-length \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> packet-length \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> packet-length \ -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> packet-length-exclude \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> packet-length-exclude \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> packet-length-exclude \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> packet-length-exclude \ - -Match based on packet length. Specify multiple values from 1 to 65535 and -ranges. -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> packet-type [broadcast | host | multicast | other] -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> packet-type [broadcast | host | multicast | other] -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> packet-type [broadcast | host | multicast | other] -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> packet-type [broadcast | host | multicast | other] - -Match based on the packet type. -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> protocol [\ | \<0-255\> | all | tcp_udp] -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> protocol [\ | \<0-255\> | all | tcp_udp] -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> protocol [\ | \<0-255\> | all | tcp_udp] -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> protocol [\ | \<0-255\> | all | tcp_udp] - -Match based on protocol number or name as defined in ``/etc/protocols``. -Special names are ``all`` for all protocols and ``tcp_udp`` for TCP and UDP -based packets. The ``!`` character negates the selected protocol. - -:::{code-block} none -set firewall ipv4 forward filter rule 10 protocol tcp_udp -set firewall ipv4 forward filter rule 11 protocol !tcp_udp -::: -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> recent count \<1-255\> -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> recent count \<1-255\> -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> recent count \<1-255\> -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> recent count \<1-255\> -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> recent time [second | minute | hour] -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> recent time [second | minute | hour] -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> recent time [second | minute | hour] -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> recent time [second | minute | hour] - -Match based on recently seen sources. -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> tcp flags [not] \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> tcp flags [not] \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> tcp flags [not] \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> tcp flags [not] \ - -Specify TCP flags. Allowed values are ``ack``, ``cwr``, ``ecn``, ``fin``, -``psh``, ``rst``, ``syn``, and ``urg``. Specify multiple values, and use -``not`` for inverted selection, as shown in the example. - -:::{code-block} none -set firewall ipv4 input filter rule 10 tcp flags 'ack' -set firewall ipv4 input filter rule 12 tcp flags 'syn' -set firewall ipv4 input filter rule 13 tcp flags not 'fin' -::: -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> state [established | invalid | new | related] -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> state [established | invalid | new | related] -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> state [established | invalid | new | related] -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> state [established | invalid | new | related] - -Match against the state of a packet. -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> time startdate \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> time startdate \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> time startdate \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> time startdate \ -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> time starttime \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> time starttime \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> time starttime \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> time starttime \ -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> time stopdate \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> time stopdate \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> time stopdate \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> time stopdate \ -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> time stoptime \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> time stoptime \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> time stoptime \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> time stoptime \ -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> time weekdays \ -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> time weekdays \ -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> time weekdays \ -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> time weekdays \ - -Time to match the defined rule. -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> ttl \ \<0-255\> -``` - -```{cfgcmd} set firewall ipv4 input filter rule \<1-999999\> ttl \ \<0-255\> -``` - -```{cfgcmd} set firewall ipv4 output filter rule \<1-999999\> ttl \ \<0-255\> -``` - -```{cfgcmd} set firewall ipv4 name \ rule \<1-999999\> ttl \ \<0-255\> - -Match the time to live parameter, where 'eq' means 'equal', 'gt' means -'greater than', and 'lt' means 'less than'. -``` - -### Packet Modifications - -Starting from **VyOS-1.5-rolling-202410060007**, the firewall can modify -packets before sending them out. This feature provides more flexibility in -packet handling. - -```{cfgcmd} set firewall ipv4 prerouting raw rule \<1-999999\> set dscp \<0-63\> -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> set dscp \<0-63\> -``` - -```{cfgcmd} set firewall ipv4 output [filter | raw] rule \<1-999999\> set dscp \<0-63\> - -Set a specific value of Differentiated Services Codepoint (DSCP). -``` - -```{cfgcmd} set firewall ipv4 prerouting raw rule \<1-999999\> set mark \<1-2147483647\> -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> set mark \<1-2147483647\> -``` - -```{cfgcmd} set firewall ipv4 output [filter | raw] rule \<1-999999\> set mark \<1-2147483647\> - -Set a specific packet mark value. -``` - -```{cfgcmd} set firewall ipv4 prerouting raw rule \<1-999999\> set tcp-mss \<500-1460\> -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> set tcp-mss \<500-1460\> -``` - -```{cfgcmd} set firewall ipv4 output [filter | raw] rule \<1-999999\> set tcp-mss \<500-1460\> - -Set the TCP-MSS (TCP maximum segment size) for the connection. -``` - -```{cfgcmd} set firewall ipv4 prerouting raw rule \<1-999999\> set ttl \<0-255\> -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> set ttl \<0-255\> -``` - -```{cfgcmd} set firewall ipv4 output [filter | raw] rule \<1-999999\> set ttl \<0-255\> - -Set the TTL (Time to Live) value. -``` - -```{cfgcmd} set firewall ipv4 forward filter rule \<1-999999\> set connection-mark \<0-2147483647\> -``` - -```{cfgcmd} set firewall ipv4 output [filter | raw] rule \<1-999999\> set connection-mark \<0-2147483647\> - -Set connection mark value. -``` - -## Synproxy - -Synproxy connections - -```{cfgcmd} set firewall ipv4 [input | forward] filter rule \<1-999999\> action synproxy -``` - -```{cfgcmd} set firewall ipv4 [input | forward] filter rule \<1-999999\> protocol tcp -``` - -```{cfgcmd} set firewall ipv4 [input | forward] filter rule \<1-999999\> synproxy tcp mss \<501-65535\> - - Set the TCP-MSS (maximum segment size) for the connection -``` - -```{cfgcmd} set firewall ipv4 [input | forward] filter rule \<1-999999\> synproxy tcp window-scale \<1-14\> - - Set the window scale factor for TCP window scaling -``` - -### Example synproxy - -Requirements to enable synproxy: - -- Traffic must be symmetric. -- Synproxy relies on syncookies and TCP timestamps, ensure these are enabled. -- Disable conntrack loose track option. - -```none -set system sysctl parameter net.ipv4.tcp_timestamps value '1' - -set system conntrack tcp loose disable - -set system conntrack ignore ipv4 rule 10 destination port '8080' - -set system conntrack ignore ipv4 rule 10 protocol 'tcp' - -set system conntrack ignore ipv4 rule 10 tcp flags syn - -set firewall global-options syn-cookies 'enable' - -set firewall ipv4 input filter rule 10 action 'synproxy' - -set firewall ipv4 input filter rule 10 destination port '8080' - -set firewall ipv4 input filter rule 10 inbound-interface name 'eth1' - -set firewall ipv4 input filter rule 10 protocol 'tcp' - -set firewall ipv4 input filter rule 10 synproxy tcp mss '1460' - -set firewall ipv4 input filter rule 10 synproxy tcp window-scale '7' - -set firewall ipv4 input filter rule 1000 action 'drop' - -set firewall ipv4 input filter rule 1000 state invalid - -``` - -## Operation-mode Firewall - -### Rule-set overview - -```{opcmd} show firewall - -This will show you a basic firewall overview, for all rule-sets, not -only for IPv4. - -:::{code-block} none -vyos@vyos:~$ show firewall -Rulesets Information - ---------------------------------- -ipv4 Firewall "forward filter" - -Rule Action Protocol Packets Bytes Conditions -------- -------- ---------- --------- ------- ----------------------------- -20 accept all 0 0 ip saddr @N_TRUSTEDv4 accept -21 jump all 0 0 jump NAME_AUX -default accept all 0 0 - ---------------------------------- -ipv4 Firewall "input filter" - -Rule Action Protocol Packets Bytes Conditions -------- -------- ---------- --------- ------- ------------------------- -10 accept all 156 14377 iifname != @I_LAN accept -default accept all 0 0 - ---------------------------------- -ipv4 Firewall "name AUX" - -Rule Action Protocol Packets Bytes Conditions ------- -------- ---------- --------- ------- -------------------------------------------- -10 accept icmp 0 0 meta l4proto icmp accept -20 accept udp 0 0 meta l4proto udp ip saddr @A_SERVERS accept -30 drop all 0 0 ip saddr != @A_SERVERS iifname "eth2" - ---------------------------------- -ipv4 Firewall "output filter" - -Rule Action Protocol Packets Bytes Conditions -------- -------- ---------- --------- ------- ---------------------------------------- -10 reject all 0 0 oifname @I_LAN -20 accept icmp 2 168 meta l4proto icmp oifname "eth0" accept -default accept all 72 9258 - ---------------------------------- -ipv6 Firewall "input filter" - -Rule Action Protocol Packets Bytes Conditions -------- -------- ---------- --------- ------- ------------------------------- -10 accept all 0 0 ip6 saddr @N6_TRUSTEDv6 accept -default accept all 2 112 - -vyos@vyos:~$ -::: -``` - -```{opcmd} show firewall summary - -This shows you a summary of rule-sets and groups. - -:::{code-block} none -vyos@vyos:~$ show firewall summary -Ruleset Summary - -IPv6 Ruleset: - -Ruleset Hook Ruleset Priority Description --------------- -------------------- ------------------------- -forward filter -input filter -ipv6_name IPV6-VyOS_MANAGEMENT -ipv6_name IPV6-WAN_IN PUBLIC_INTERNET - -IPv4 Ruleset: - -Ruleset Hook Ruleset Priority Description --------------- ------------------ ------------------------- -forward filter -input filter -name VyOS_MANAGEMENT -name WAN_IN PUBLIC_INTERNET - -Firewall Groups - -Name Type References Members ------------------------ ------------------ ----------------------- ---------------- -PBX address_group WAN_IN-100 198.51.100.77 -SERVERS address_group WAN_IN-110 192.0.2.10 -WAN_IN-111 192.0.2.11 -WAN_IN-112 192.0.2.12 -WAN_IN-120 -WAN_IN-121 -WAN_IN-122 -SUPPORT address_group VyOS_MANAGEMENT-20 192.168.1.2 -WAN_IN-20 -PHONE_VPN_SERVERS address_group WAN_IN-160 10.6.32.2 -PINGABLE_ADRESSES address_group WAN_IN-170 192.168.5.2 -WAN_IN-171 -PBX ipv6_address_group IPV6-WAN_IN-100 2001:db8::1 -SERVERS ipv6_address_group IPV6-WAN_IN-110 2001:db8::2 -IPV6-WAN_IN-111 2001:db8::3 -IPV6-WAN_IN-112 2001:db8::4 -IPV6-WAN_IN-120 -IPV6-WAN_IN-121 -IPV6-WAN_IN-122 -SUPPORT ipv6_address_group IPV6-VyOS_MANAGEMENT-20 2001:db8::5 -IPV6-WAN_IN-20 -::: -``` - -```{opcmd} show firewall ipv4 [forward | input | output] filter -``` - -```{opcmd} show firewall ipv4 name \ - -This command will give an overview of a single rule-set. - -:::{code-block} none -vyos@vyos:~$ show firewall ipv4 input filter -Ruleset Information ---------------------------------- -IPv4 Firewall "input filter" -Rule Action Protocol Packets Bytes Conditions -------- -------- ---------- --------- ------- ----------------------------------------- -5 jump all 0 0 iifname "eth2" jump NAME_VyOS_MANAGEMENT -default accept all -::: -``` - -```{opcmd} show firewall ipv4 [forward | input | output] filter rule \<1-999999\> -``` - -```{opcmd} show firewall ipv4 name \ rule \<1-999999\> - -This command gives an overview of a rule in a single rule-set, plus -information for default action. -``` -```none -vyos@vyos:~$show firewall ipv4 output filter rule 20 -Rule Information - ---------------------------------- -ipv4 Firewall "output filter" - -Rule Action Protocol Packets Bytes Conditions -------- -------- ---------- --------- ------- ---------------------------------------- -20 accept icmp 2 168 meta l4proto icmp oifname "eth0" accept -default accept all 286 47614 - -vyos@vyos:~$ -``` - -```{opcmd} show firewall statistics - -This will show you statistics of all rule-sets since the last boot. -``` - -### Show Firewall log - -```{opcmd} show log firewall - -``` -```{opcmd} show log firewall ipv4 -``` - -```{opcmd} show log firewall ipv4 [forward | input | output | name] -``` - -```{opcmd} show log firewall ipv4 [forward | input | output] filter -``` - -```{opcmd} show log firewall ipv4 name \ -``` - -```{opcmd} show log firewall ipv4 [forward | input | output] filter rule \ -``` - -```{opcmd} show log firewall ipv4 name \ rule \ - -Show the logs of all firewall; show all IPv4 firewall logs; show all logs -for particular hook; show all logs for particular hook and priority; -show all logs for particular custom chain; show logs for specific rule-set. -``` - -### Example Partial Config - -```none -firewall { - group { - network-group BAD-NETWORKS { - network 198.51.100.0/24 - network 203.0.113.0/24 - } - network-group GOOD-NETWORKS { - network 192.0.2.0/24 - } - port-group BAD-PORTS { - port 65535 - } - } - ipv4 { - forward { - filter { - default-action accept - rule 5 { - action accept - source { - group { - network-group GOOD-NETWORKS - } - } - } - rule 10 { - action drop - description "Bad Networks" - protocol all - source { - group { - network-group BAD-NETWORKS - } - } - } - } - } - } -} -``` - -### Update geoip database - -```{opcmd} update geoip - -Command to update GeoIP database and firewall sets. -``` \ No newline at end of file diff --git a/docs/configuration/firewall/md-ipv6.md b/docs/configuration/firewall/md-ipv6.md deleted file mode 100644 index 770cb146..00000000 --- a/docs/configuration/firewall/md-ipv6.md +++ /dev/null @@ -1,1567 +0,0 @@ ---- -lastproofread: '2026-04-01' ---- - -(firewall-ipv6-configuration)= - -# IPv6 Firewall Configuration - -## Overview - -This section covers useful information about IPv6 firewall configuration and -appropriate operation-mode commands. - -This section describes the following configuration commands: - -```{cfgcmd} set firewall ipv6 ... -``` - -To learn about the general traffic flow in VyOS firewalls, see {doc}`Firewall `. - -```none -- set firewall - * ipv6 - - forward - + filter - - input - + filter - - output - + filter - + raw - - prerouting - + raw - - name - + custom_name -``` - -The router first receives all traffic and processes it in the **prerouting** -section. - - -This stage includes: - - -- **Firewall Prerouting**: commands found under `set firewall ipv6 - prerouting raw ...` -- {doc}`Conntrack Ignore`: `set system - conntrack ignore ipv6...` -- {doc}`Policy Route`: commands found under - `set policy route6 ...` -- {doc}`Destination NAT`: commands found under - `set nat66 destination ...` - - -For transit traffic that the router receives and forwards, the base chain is -**forward**. The following diagram shows a simplified packet flow for transit -traffic: - - -:::{figure} /_static/images/firewall-fwd-packet-flow.webp -::: - - -Use `set firewall ipv6 forward filter ...` to configure filtering rules for -transit traffic. This command corresponds to stage 5 and is highlighted in red -in the diagram. - - -For traffic destined to the router, use the **input** chain. For traffic the -router generates, use the **output** chain. The following diagram shows the -packet flow for traffic destined to the router and traffic generated by the -router (starting from circle number 6): - - -:::{figure} /_static/images/firewall-input-packet-flow.webp -::: - - -Use `set firewall ipv6 input filter ...` to configure traffic destined to -the router. - - -Use `set firewall ipv6 output ...` to configure traffic the router generates. -Two sub-chains are available: **filter** and **raw**: - - -- **Output Prerouting**: `set firewall ipv6 output raw ...`. - As described in **Prerouting**, the firewall processes rules in this - section before the connection tracking subsystem. -- **Output Filter**: `set firewall ipv6 output filter ...`. The firewall - processes rules in this section after the connection tracking subsystem. - - -:::{note} -**Important note about default-actions:** -If you do not define a default action for a base chain, the system sets -the default action to **accept** for that chain. For custom chains, if you -do not define a default action, the system sets the default-action to -**drop** -::: - - -Create custom firewall chains using the commands -`set firewall ipv6 name ...`. To use the custom chain, define a -rule with **action jump** and the appropriate **target** in a base chain. - - -## Firewall - IPv6 Rules - - -Create firewall rules for firewall filtering. Each rule is numbered and has -an action to apply when the rule is matched. You can specify multiple matching -criteria. Packets go through rules from 1 - 999999, so order is crucial. The -firewall executes the action of the first matching rule. - - -### Actions - - -If you define a rule, you must define an action for it. The action tells the -firewall what to do when all criteria for that rule are met. - - -The action can be : - - -- `accept`: accept the packet. -- `continue`: continue parsing next rule. -- `drop`: drop the packet. -- `reject`: reject the packet. -- `jump`: jump to another custom chain. -- `return`: Return from the current chain and continue at the next rule - of the last chain. -- `queue`: Enqueue packet to userspace. -- `synproxy`: synproxy the packet. - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> action [accept | continue | drop | jump | queue | reject | return | synproxy] -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> action [accept | continue | drop | jump | queue | reject | return | synproxy] -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> action [accept | continue | drop | jump | queue | reject | return] -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> action [accept | continue | drop | jump | queue | reject | return] - -This required setting defines the action of the current rule. If you set -the action to jump, you must also define a jump-target. -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> jump-target \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> jump-target \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> jump-target \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> jump-target \ - -Use this command only when action is set to ``jump``. Specify the jump -target. -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> queue \<0-65535\> -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> queue \<0-65535\> -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> queue \<0-65535\> -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> queue \<0-65535\> - -Use this command only when action is set to ``queue``. Specify the queue -target. Queue ranges are also supported. -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> queue-options bypass -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> queue-options bypass -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> queue-options bypass -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> queue-options bypass - -Use this command only when action is set to ``queue``. This command allows -the packet to go through the firewall when no userspace software is connected -to the queue. -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> queue-options fanout -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> queue-options fanout -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> queue-options fanout -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> queue-options fanout - -Use this command only when action is set to ``queue``. This command -distributes packets among multiple queues. -``` - -Also, **default-action** is an action that takes place whenever a packet does -not match any rule in its chain. For base chains, possible options for -**default-action** are **accept** or **drop**. - -```{cfgcmd} set firewall ipv6 forward filter default-action [accept | drop] -``` - -```{cfgcmd} set firewall ipv6 input filter default-action [accept | drop] -``` - -```{cfgcmd} set firewall ipv6 output filter default-action [accept | drop] -``` - -```{cfgcmd} set firewall ipv6 name \ default-action [accept | drop | jump | queue | reject | return] - -Set the default action of the rule-set if a packet does not match any rule -criteria. If you set default-action to ``jump``, you must also define -``default-jump-target``. For base chains, you can only set the default -action to ``accept`` or ``drop``. For custom chains, more actions are -available. -``` - -```{cfgcmd} set firewall ipv6 name \ default-jump-target \ - -To be used only when ``default-action`` is set to ``jump``. Use this -command to specify the jump target for the default rule. -``` -:::{note} -**Important note about default-actions:** -If you do not define the default action for a base chain, the system sets -the default action to **accept** for that chain. For custom chains, if you -do not define a default action, the system sets the default-action to -**drop**. -::: - - -### Firewall Logs - - -You can enable logging for each firewall rule. When enabled, you can also -define other log options. - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> log -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> log -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> log -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> log - -Enable logging for matched packets. If this configuration command is not -present, logging is disabled. -``` - -```{cfgcmd} set firewall ipv6 forward filter default-log -``` - -```{cfgcmd} set firewall ipv6 input filter default-log -``` - -```{cfgcmd} set firewall ipv6 output filter default-log -``` - -```{cfgcmd} set firewall ipv6 name \ default-log - -Use this command to enable the logging of the default action on -the specified chain. -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> log-options level [emerg | alert | crit | err | warn | notice | info | debug] -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> log-options level [emerg | alert | crit | err | warn | notice | info | debug] -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> log-options level [emerg | alert | crit | err | warn | notice | info | debug] -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> log-options level [emerg | alert | crit | err | warn | notice | info | debug] - -Define log-level. Only applicable if rule log is enabled. -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> log-options group \<0-65535\> -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> log-options group \<0-65535\> -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> log-options group \<0-65535\> -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> log-options group \<0-65535\> - -Define the log group to send messages to. Only applicable if rule log is -enabled. -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> log-options snapshot-length \<0-9000\> -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> log-options snapshot-length \<0-9000\> -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> log-options snapshot-length \<0-9000\> -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> log-options snapshot-length \<0-9000\> - -Define the length of packet payload to include in a netlink message. Only -applicable when rule logging is enabled and log group is defined. -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> log-options queue-threshold \<0-65535\> -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> log-options queue-threshold \<0-65535\> -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> log-options queue-threshold \<0-65535\> -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> log-options queue-threshold \<0-65535\> - -Define the number of packets to queue inside the kernel before sending them -to userspace. Only applicable when rule logging is enabled and log group is -defined. -``` - -### Firewall Description - - -For reference, you can define descriptions on every rule and custom chain. - -```{cfgcmd} set firewall ipv6 name \ description \ - -Provide a rule-set description to a custom firewall chain. -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> description \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> description \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> description \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> description \ - -Provide a description for each rule. -``` - -### Rule Status - - -New rules are enabled by default. In some cases, you may want to disable a -rule rather than remove it. - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> disable -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> disable -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> disable -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> disable - -Command for disabling a rule but keep it in the configuration. -``` - -### Matching criteria - - -There are a lot of matching criteria against which the packet can be tested. - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> connection-status nat [destination | source] -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> connection-status nat [destination | source] -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> connection-status nat [destination | source] -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> connection-status nat [destination | source] - -Match packets based on NAT connection status. -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> connection-mark \<1-2147483647\> -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> connection-mark \<1-2147483647\> -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> connection-mark \<1-2147483647\> -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> connection-mark \<1-2147483647\> - -Match packets based on connection mark. -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> source address [address | addressrange | CIDR] -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> source address [address | addressrange | CIDR] -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> source address [address | addressrange | CIDR] -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> source address [address | addressrange | CIDR] -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> destination address [address | addressrange | CIDR] -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> destination address [address | addressrange | CIDR] -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> destination address [address | addressrange | CIDR] -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> destination address [address | addressrange | CIDR] - -Match based on source or destination address. This is similar to network -groups, but you can negate the matching addresses here. - -:::{code-block} none -set firewall ipv6 name FOO rule 100 source address 2001:db8::202 -::: -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> source address-mask [address] -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> source address-mask [address] -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> source address-mask [address] -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> source address-mask [address] -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> destination address-mask [address] -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> destination address-mask [address] -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> destination address-mask [address] -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> destination address-mask [address] - -Apply an arbitrary netmask to mask addresses and match only a specific -portion. This is useful for IPv6 because rules remain valid when the IPv6 -prefix changes if the host portion of the system's IPv6 address is static. -Examples include SLAAC and tokenised IPv6 addresses - -This function works for both individual addresses and address groups. - - -:::{code-block} none -# Match any IPv6 address with the suffix ::0000:0000:0000:beef -set firewall ipv6 forward filter rule 100 destination address ::beef -set firewall ipv6 forward filter rule 100 destination address-mask ::ffff:ffff:ffff:ffff -# Address groups -set firewall group ipv6-address-group WEBSERVERS address ::1000 -set firewall group ipv6-address-group WEBSERVERS address ::2000 -set firewall ipv6 forward filter rule 200 source group address-group WEBSERVERS -set firewall ipv6 forward filter rule 200 source address-mask ::ffff:ffff:ffff:ffff -::: -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> source fqdn \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> source fqdn \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> source fqdn \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> source fqdn \ -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> destination fqdn \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> destination fqdn \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> destination fqdn \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> destination fqdn \ - -Specify a Fully Qualified Domain Name as source or destination to match. -Ensure that the router can resolve the DNS query. -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> source geoip country-code \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> source geoip country-code \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> source geoip country-code \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> source geoip country-code \ -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> destination geoip country-code \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> destination geoip country-code \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> destination geoip country-code \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> destination geoip country-code \ -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> source geoip inverse-match -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> source geoip inverse-match -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> source geoip inverse-match -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> source geoip inverse-match -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> destination geoip inverse-match -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> destination geoip inverse-match -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> destination geoip inverse-match -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> destination geoip inverse-match - -Match IP addresses based on their geolocation. For more information, see -GeoIP matching. -Use inverse-match to match anything except the specified country codes. -``` - -DB-IP.com provides data under CC-BY-4.0 license. Attribution is required and -redistribution is permitted, allowing VyOS to include a database in images -(approximately 3 MB compressed). The package includes a cron script that you -can manually call through op-mode update geoip to keep the database and rules -updated. - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> source mac-address \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> source mac-address \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> source mac-address \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> source mac-address \ - -You can specify only a source MAC address to match. - -:::{code-block} none -set firewall ipv6 input filter rule 100 source mac-address 00:53:00:11:22:33 -set firewall ipv6 input filter rule 101 source mac-address !00:53:00:aa:12:34 -::: -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> source port [1-65535 | portname | start-end] -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> source port [1-65535 | portname | start-end] -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> source port [1-65535 | portname | start-end] -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> source port [1-65535 | portname | start-end] -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> destination port [1-65535 | portname | start-end] -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> destination port [1-65535 | portname | start-end] -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> destination port [1-65535 | portname | start-end] -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> destination port [1-65535 | portname | start-end] - -Specify a port by number or by name as defined in ``/etc/services``. - -:::{code-block} none -set firewall ipv6 forward filter rule 10 source port '22' -set firewall ipv6 forward filter rule 11 source port '!http' -set firewall ipv6 forward filter rule 12 source port 'https' -::: -Multiple source ports can be specified as a comma-separated list. -The whole list can also be "negated" using ``!``. For example: - -:::{code-block} none -set firewall ipv6 forward filter rule 10 source port '!22,https,3333-3338' -::: -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> source group address-group \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> source group address-group \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> source group address-group \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> source group address-group \ -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> destination group address-group \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> destination group address-group \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> destination group address-group \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> destination group address-group \ - -Specify an address group. You can prepend the character ``!`` to invert the -matching criteria. -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> source group dynamic-address-group \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> source group dynamic-address-group \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> source group dynamic-address-group \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> source group dynamic-address-group \ -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> destination group dynamic-address-group \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> destination group dynamic-address-group \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> destination group dynamic-address-group \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> destination group dynamic-address-group \ - -Specify a dynamic address group. You can prepend the character ``!`` to -invert the matching criteria. -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> source group network-group \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> source group network-group \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> source group network-group \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> source group network-group \ -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> destination group network-group \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> destination group network-group \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> destination group network-group \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> destination group network-group \ - -Specify a network group. You can prepend the character ``!`` to invert the -matching criteria. -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> source group port-group \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> source group port-group \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> source group port-group \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> source group port-group \ -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> destination group port-group \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> destination group port-group \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> destination group port-group \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> destination group port-group \ - -Specify a port group. You can prepend the character ``!`` to invert the -matching criteria. -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> source group domain-group \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> source group domain-group \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> source group domain-group \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> source group domain-group \ -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> destination group domain-group \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> destination group domain-group \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> destination group domain-group \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> destination group domain-group \ - -Specify a domain group. You can prepend the character ``!`` to invert the -matching criteria. -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> source group mac-group \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> source group mac-group \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> source group mac-group \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> source group mac-group \ -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> destination group mac-group \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> destination group mac-group \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> destination group mac-group \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> destination group mac-group \ - -Specify a MAC group. You can prepend the character ``!`` to invert the -matching criteria. -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> dscp [0-63 | start-end] -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> dscp [0-63 | start-end] -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> dscp [0-63 | start-end] -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> dscp [0-63 | start-end] -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> dscp-exclude [0-63 | start-end] -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> dscp-exclude [0-63 | start-end] -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> dscp-exclude [0-63 | start-end] -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> dscp-exclude [0-63 | start-end] - -Match based on dscp value. -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> fragment [match-frag | match-non-frag] -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> fragment [match-frag | match-non-frag] -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> fragment [match-frag | match-non-frag] -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> fragment [match-frag | match-non-frag] - -Match packets based on fragmentation. -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> icmpv6 [code | type] \<0-255\> -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> icmpv6 [code | type] \<0-255\> -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> icmpv6 [code | type] \<0-255\> -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> icmpv6 [code | type] \<0-255\> - -Match packets based on ICMP or ICMPv6 code and type. -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> icmpv6 type-name \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> icmpv6 type-name \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> icmpv6 type-name \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> icmpv6 type-name \ - -Match based on ICMPv6 type-name. Press **Tab** for information about -supported **type-name** criteria. -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> inbound-interface name \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> inbound-interface name \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> inbound-interface name \ - -Match based on inbound interface. You can use the wildcard ``*``. For -example: ``eth2*``. You can prepend the character ``!`` to invert the -matching criteria. For example ``!eth2`` -``` -:::{note} -If an interface is attached to a non-default VRF, when using -**inbound-interface**, use the VRF name. For example: -`set firewall ipv6 forward filter rule 10 inbound-interface name MGMT` -::: -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> inbound-interface group \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> inbound-interface group \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> inbound-interface group \ - -Match based on the inbound interface group. You can prepend the character -``!`` to invert the matching criteria. For example ``!IFACE_GROUP`` -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> outbound-interface name \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> outbound-interface name \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> outbound-interface name \ - -Match based on outbound interface. You can use the wildcard ``*``. For -example: ``eth2*``. You can prepend the character ``!`` to invert the -matching criteria. For example ``!eth2`` -``` -:::{note} -If an interface is attached to a non-default VRF, when using -**outbound-interface**, use the physical interface name. For example: -`set firewall ipv6 forward filter rule 10 outbound-interface name eth0` -::: -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> outbound-interface group \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> outbound-interface group \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> outbound-interface group \ - -Match based on outbound interface group. You can prepend the character ``!`` -to invert the matching criteria. For example ``!IFACE_GROUP`` -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> ipsec [match-ipsec-in | match-ipsec-out | match-none-in | match-none-out] -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> ipsec [match-ipsec-in | match-none-in] -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> ipsec [match-ipsec-out | match-none-out] -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> ipsec [match-ipsec-in | match-ipsec-out | match-none-in | match-none-out] - -Match packets based on IPsec. -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> limit burst \<0-4294967295\> -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> limit burst \<0-4294967295\> -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> limit burst \<0-4294967295\> -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> limit burst \<0-4294967295\> - -Match based on the maximum number of packets allowed to exceed the rate -limit. -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> limit rate \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> limit rate \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> limit rate \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> limit rate \ - -Match based on the maximum average rate, specified as ``integer/unit``. -For example, specify ``5/minutes``. -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> packet-length \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> packet-length \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> packet-length \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> packet-length \ -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> packet-length-exclude \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> packet-length-exclude \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> packet-length-exclude \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> packet-length-exclude \ - -Match based on packet length. You can specify multiple values from 1 to -65535 and ranges. -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> packet-type [broadcast | host | multicast | other] -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> packet-type [broadcast | host | multicast | other] -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> packet-type [broadcast | host | multicast | other] -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> packet-type [broadcast | host | multicast | other] - -Match based on packet type. -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> protocol [\ | \<0-255\> | all | tcp_udp] -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> protocol [\ | \<0-255\> | all | tcp_udp] -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> protocol [\ | \<0-255\> | all | tcp_udp] -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> protocol [\ | \<0-255\> | all | tcp_udp] - -Match based on protocol number or name as defined in ``/etc/protocols``. -Specify ``all`` for all protocols and ``tcp_udp`` for TCP and UDP packets. -Prepend ``!`` to negate the protocol selection. - -:::{code-block} none -set firewall ipv6 input filter rule 10 protocol tcp -::: -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> recent count \<1-255\> -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> recent count \<1-255\> -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> recent count \<1-255\> -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> recent count \<1-255\> -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> recent time [second | minute | hour] -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> recent time [second | minute | hour] -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> recent time [second | minute | hour] -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> recent time [second | minute | hour] - -Match packets based on recently seen sources. -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> tcp flags [not] \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> tcp flags [not] \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> tcp flags [not] \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> tcp flags [not] \ - -Allowed values for TCP flags: ``ack``, ``cwr``, ``ecn``, ``fin``, ``psh``, -``rst``, ``syn``, and ``urg``. You can specify multiple values. To invert -the selection, use ``not``, as shown in the following example. - -:::{code-block} none -set firewall ipv6 input filter rule 10 tcp flags 'ack' -set firewall ipv6 input filter rule 12 tcp flags 'syn' -set firewall ipv6 input filter rule 13 tcp flags not 'fin' -::: -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> state [established | invalid | new | related] -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> state [established | invalid | new | related] -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> state [established | invalid | new | related] -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> state [established | invalid | new | related] - -Match based on packet state. -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> time startdate \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> time startdate \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> time startdate \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> time startdate \ -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> time starttime \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> time starttime \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> time starttime \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> time starttime \ -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> time stopdate \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> time stopdate \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> time stopdate \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> time stopdate \ -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> time stoptime \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> time stoptime \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> time stoptime \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> time stoptime \ -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> time weekdays \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> time weekdays \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> time weekdays \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> time weekdays \ - -Match packets based on time criteria. -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> hop-limit \ \<0-255\> -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> hop-limit \ \<0-255\> -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> hop-limit \ \<0-255\> -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> hop-limit \ \<0-255\> - -Match the hop-limit parameter. Use ``eq`` for equal, ``gt`` for greater than, -and ``lt`` for less than. -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> recent count \<1-255\> -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> recent count \<1-255\> -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> recent count \<1-255\> -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> recent count \<1-255\> -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> recent time \ -``` - -```{cfgcmd} set firewall ipv6 input filter rule \<1-999999\> recent time \ -``` - -```{cfgcmd} set firewall ipv6 output filter rule \<1-999999\> recent time \ -``` - -```{cfgcmd} set firewall ipv6 name \ rule \<1-999999\> recent time \ - -Match when the specified number of connections occur within the specified -time period. Use these criteria to block brute-force attempts. -``` - -### Packet Modifications - - -The firewall can modify packets before sending them. -This feature provides more flexibility for packet handling. - -```{cfgcmd} set firewall ipv6 prerouting raw rule \<1-999999\> set dscp \<0-63\> -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> set dscp \<0-63\> -``` - -```{cfgcmd} set firewall ipv6 output [filter | raw] rule \<1-999999\> set dscp \<0-63\> - -Set a specific value of Differentiated Services Codepoint (DSCP). -``` - -```{cfgcmd} set firewall ipv6 prerouting raw rule \<1-999999\> set mark \<1-2147483647\> -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> set mark \<1-2147483647\> -``` - -```{cfgcmd} set firewall ipv6 output [filter | raw] rule \<1-999999\> set mark \<1-2147483647\> - -Set a specific packet mark value. -``` - -```{cfgcmd} set firewall ipv6 prerouting raw rule \<1-999999\> set tcp-mss \<500-1460\> -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> set tcp-mss \<500-1460\> -``` - -```{cfgcmd} set firewall ipv6 output [filter | raw] rule \<1-999999\> set tcp-mss \<500-1460\> - -Set the TCP-MSS (TCP maximum segment size) for the connection. -``` - -```{cfgcmd} set firewall ipv6 prerouting raw rule \<1-999999\> set hop-limit \<0-255\> -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> set hop-limit \<0-255\> -``` - -```{cfgcmd} set firewall ipv6 output [filter | raw] rule \<1-999999\> set hop-limit \<0-255\> - -Set hop limit value. -``` - -```{cfgcmd} set firewall ipv6 forward filter rule \<1-999999\> set connection-mark \<0-2147483647\> -``` - -```{cfgcmd} set firewall ipv6 output [filter | raw] rule \<1-999999\> set connection-mark \<0-2147483647\> - -Set connection mark value. -``` - -## Synproxy - - -Synproxy connections - -```{cfgcmd} set firewall ipv6 [input | forward] filter rule \<1-999999\> action synproxy -``` - -```{cfgcmd} set firewall ipv6 [input | forward] filter rule \<1-999999\> protocol tcp -``` - -```{cfgcmd} set firewall ipv6 [input | forward] filter rule \<1-999999\> synproxy tcp mss \<501-65535\> - - Set the TCP MSS (maximum segment size) for the connection. -``` - -```{cfgcmd} set firewall ipv6 [input | forward] filter rule \<1-999999\> synproxy tcp window-scale \<1-14\> - - Set the window scale factor for TCP window scaling. -``` - -### Example synproxy - - -Requirements to enable synproxy: - - -- Traffic must be symmetric -- Synproxy relies on syncookies and TCP timestamps, ensure these are enabled -- Disable conntrack loose track option - -```none -set system sysctl parameter net.ipv4.tcp_timestamps value '1' - - -set system conntrack tcp loose disable - -set system conntrack ignore ipv6 rule 10 destination port '8080' - -set system conntrack ignore ipv6 rule 10 protocol 'tcp' - -set system conntrack ignore ipv6 rule 10 tcp flags syn - - -set firewall global-options syn-cookies 'enable' - -set firewall ipv6 input filter rule 10 action 'synproxy' - -set firewall ipv6 input filter rule 10 destination port '8080' - -set firewall ipv6 input filter rule 10 inbound-interface name 'eth1' - -set firewall ipv6 input filter rule 10 protocol 'tcp' - -set firewall ipv6 input filter rule 10 synproxy tcp mss '1460' - -set firewall ipv6 input filter rule 10 synproxy tcp window-scale '7' - -set firewall ipv6 input filter rule 1000 action 'drop' - -set firewall ipv6 input filter rule 1000 state invalid - -``` - -## Operation-mode Firewall - - -### Rule-set overview - -```{opcmd} show firewall - -Show a basic firewall overview for all rule-sets, not only for IPv6: - -:::{code-block} none -vyos@vyos:~$ show firewall -Rulesets Information - ---------------------------------- -IPv4 Firewall "forward filter" - -Rule Action Protocol Packets Bytes Conditions -------- -------- ---------- --------- ------- ----------------------------------------- -5 jump all 0 0 iifname "eth1" jump NAME_VyOS_MANAGEMENT -10 jump all 0 0 oifname "eth1" jump NAME_WAN_IN -15 jump all 0 0 iifname "eth3" jump NAME_WAN_IN -default accept all - ---------------------------------- -IPv4 Firewall "name VyOS_MANAGEMENT" - -Rule Action Protocol Packets Bytes Conditions -------- -------- ---------- --------- ------- -------------------------------- -5 accept all 0 0 ct state established accept -10 drop all 0 0 ct state invalid -20 accept all 0 0 ip saddr @A_GOOD_GUYS accept -30 accept all 0 0 ip saddr @N_ENTIRE_RANGE accept -40 accept all 0 0 ip saddr @A_VyOS_SERVERS accept -50 accept icmp 0 0 meta l4proto icmp accept -default drop all 0 0 - ---------------------------------- -IPv6 Firewall "forward filter" - -Rule Action Protocol -------- -------- ---------- -5 jump all -10 jump all -15 jump all -default accept all - ---------------------------------- -IPv6 Firewall "input filter" - -Rule Action Protocol -------- -------- ---------- -5 jump all -default accept all - ---------------------------------- -IPv6 Firewall "ipv6_name IPV6-VyOS_MANAGEMENT" - -Rule Action Protocol -------- -------- ---------- -5 accept all -10 drop all -20 accept all -30 accept all -40 accept all -50 accept ipv6-icmp -default drop all -::: -``` - -```{opcmd} show firewall summary - -This will show you a summary of rule-sets and groups - -:::{code-block} none -vyos@vyos:~$ show firewall summary -Ruleset Summary - -IPv6 Ruleset: - -Ruleset Hook Ruleset Priority Description --------------- -------------------- ------------------------- -forward filter -input filter -ipv6_name IPV6-VyOS_MANAGEMENT -ipv6_name IPV6-WAN_IN PUBLIC_INTERNET - -IPv4 Ruleset: - -Ruleset Hook Ruleset Priority Description --------------- ------------------ ------------------------- -forward filter -input filter -name VyOS_MANAGEMENT -name WAN_IN PUBLIC_INTERNET - -Firewall Groups - -Name Type References Members ------------------------ ------------------ ----------------------- ---------------- -PBX address_group WAN_IN-100 198.51.100.77 -SERVERS address_group WAN_IN-110 192.0.2.10 -WAN_IN-111 192.0.2.11 -WAN_IN-112 192.0.2.12 -WAN_IN-120 -WAN_IN-121 -WAN_IN-122 -SUPPORT address_group VyOS_MANAGEMENT-20 192.168.1.2 -WAN_IN-20 -PHONE_VPN_SERVERS address_group WAN_IN-160 10.6.32.2 -PINGABLE_ADRESSES address_group WAN_IN-170 192.168.5.2 -WAN_IN-171 -PBX ipv6_address_group IPV6-WAN_IN-100 2001:db8::1 -SERVERS ipv6_address_group IPV6-WAN_IN-110 2001:db8::2 -IPV6-WAN_IN-111 2001:db8::3 -IPV6-WAN_IN-112 2001:db8::4 -IPV6-WAN_IN-120 -IPV6-WAN_IN-121 -IPV6-WAN_IN-122 -SUPPORT ipv6_address_group IPV6-VyOS_MANAGEMENT-20 2001:db8::5 -IPV6-WAN_IN-20 -::: -``` - -```{opcmd} show firewall ipv6 [forward | input | output] filter -``` - -```{opcmd} show firewall ipv6 ipv6-name \ - -This command will give an overview of a single rule-set. - -:::{code-block} none -vyos@vyos:~$ show firewall ipv6 input filter -Ruleset Information - ---------------------------------- -ipv6 Firewall "input filter" - -Rule Action Protocol Packets Bytes Conditions -------- -------- ---------- --------- ------- ------------------------------------------------------------------------------ -10 jump all 13 1456 iifname "eth1" jump NAME6_INP-ETH1 -20 accept ipv6-icmp 10 1112 meta l4proto ipv6-icmp iifname "eth0" prefix "[ipv6-INP-filter-20-A]" accept -default accept all 14 1584 - -vyos@vyos:~$ -::: -``` - -```{opcmd} show firewall ipv6 [forward | input | output] filter rule \<1-999999\> -``` - -```{opcmd} show firewall ipv6 name \ rule \<1-999999\> -``` - -```{opcmd} show firewall ipv6 ipv6-name \ rule \<1-999999\> - -This command will give an overview of a rule in a single rule-set -``` - -```{opcmd} show firewall group \ - -Show an overview of defined groups, including the type, members, and where -the group is used. - -:::{code-block} none -vyos@vyos:~$ show firewall group LAN -Firewall Groups - -Name Type References Members ------------- ------------------ ----------------------- ---------------- -LAN ipv6_network_group IPV6-VyOS_MANAGEMENT-30 2001:db8::0/64 -IPV6-WAN_IN-30 -LAN network_group VyOS_MANAGEMENT-30 192.168.200.0/24 -WAN_IN-30 -::: -``` - -```{opcmd} show firewall statistics - -Show statistics of all rule-sets since the last boot. -``` - -### Show Firewall log - -```{opcmd} show log firewall -``` - -```{opcmd} show log firewall ipv6 -``` - -```{opcmd} show log firewall ipv6 [forward | input | output | name] -``` - -```{opcmd} show log firewall ipv6 [forward | input | output] filter -``` - -```{opcmd} show log firewall ipv6 name \ -``` - -```{opcmd} show log firewall ipv6 [forward | input | output] filter rule \ -``` - -```{opcmd} show log firewall ipv6 name \ rule \ - -Show firewall logs for all firewalls, all IPv6 firewalls, specific hooks, -specific priorities, specific custom chains, or specific rule-sets. -``` - -### Example Partial Config - -```none -firewall { - ipv6 { - input { - filter { - rule 10 { - action jump - inbound-interface { - name eth1 - } - jump-target INP-ETH1 - } - rule 20 { - action accept - inbound-interface { - name eth0 - } - log - protocol ipv6-icmp - } - } - } - name INP-ETH1 { - default-action drop - default-log - rule 10 { - action accept - protocol tcp_udp - } - } - } -} -``` - -### Update geoip database - -```{opcmd} update geoip - -Command used to update GeoIP database and firewall sets. -``` \ No newline at end of file diff --git a/docs/configuration/firewall/md-zone.md b/docs/configuration/firewall/md-zone.md deleted file mode 100644 index bbb93993..00000000 --- a/docs/configuration/firewall/md-zone.md +++ /dev/null @@ -1,201 +0,0 @@ ---- -lastproofread: '2026-03-30' ---- - -(firewall-zone)= - -# Zone-Based Firewall - -## Overview - -:::{note} -All VyOS versions built after 2023-10-22 (VyOS 1.4 and 1.5) support -this feature. -::: - -This section provides information on firewall configuration for the -zone-based firewall. This section covers the following configuration -commands: - -```{cfgcmd} set firewall zone ... -``` - -To learn about the general traffic flow in VyOS firewalls, -see {doc}`Firewall `. - -```none -- set firewall - * zone - - custom_zone_name - + ... -``` - -In zone-based policy, you assign interfaces to zones and apply inspection -policy to traffic moving between zones. The firewall acts on traffic -according to rules. A zone is a group of interfaces that have similar -functions or features. It establishes the security borders of a network. -A zone defines a boundary where the system subjects traffic to policy -restrictions as it crosses to another region of a network. - -Key Points: -- A zone must be configured before you assign an interface to it, and you - can assign an interface to only a single zone. -- All traffic to and from an interface within a zone flows freely. -- Existing policies affect all traffic between zones. -- Traffic cannot flow between a zone member interface and any interface that - is not a zone member. -- You must define 2 separate firewalls to define traffic: one for each - direction. - -:::{note} -In {vytask}`T2199` the syntax of the zone configuration was changed. -The zone configuration moved from ``zone-policy zone `` to -``firewall zone ``. -::: - -## Configuration - -As an alternative to applying policy to an interface directly, you can -create a zone-based firewall to simplify configuration when multiple -interfaces belong to the same security zone. Instead of applying rule-sets -to interfaces, you apply them to source-destination zone pairs. - -You can find a basic introduction to zone-based firewalls in the -[VyOS Knowledge Base](https://support.vyos.io/en/kb/articles/a-primer-to-zone-based-firewall), -and an example at {ref}`examples-zone-policy`. - -The following steps are required to create a zone-based firewall: -1. Define both the source and destination zones -2. Define the rule-set -3. Apply the rule-set to the zones - -### Define a Zone - -To define a zone, set up either one with interfaces or as the local zone. - -```{cfgcmd} set firewall zone \ interface \ - -Assign interfaces as a member of a zone. - -:::{note} -* An interface can only be a member of one zone. -* You can have multiple interfaces in a zone. Traffic between -interfaces in the same zone follows the intra-zone-filtering -policy (allowed by default). -::: -``` - -```{cfgcmd} set firewall zone \ local-zone - -Define the zone as the local zone for traffic that originates from or is -destined to the router itself. - -:::{note} -* A local zone cannot have any member interfaces -* You cannot have multiple local zones -::: -``` - -```{cfgcmd} set firewall zone \ default-action [drop | reject] - -Modify the zone default-action, which applies to traffic destined to this -zone that does not match any of the source zone rulesets applied. -``` - -```{cfgcmd} set firewall zone \ default-log - -Enable logging of packets that match this zone's default-action (disabled -by default). -``` - -```{cfgcmd} set firewall zone \ description - -Add a meaningful description. -``` - -### Defining a Rule-Set - -Zone-based firewall rule-sets define traffic from a *Source Zone* to a -*Destination Zone*. - -You create rule-sets as a custom firewall chain using the commands below -(refer to the firewall IPv4/IPv6 sections for the full syntax): -- For {ref}`IPv4`: - `set firewall ipv4 name ...` -- For {ref}`IPv6`: - `set firewall ipv6 name ...` - -It is helpful to name the rule-sets in the format -`--` to make them easily -identifiable. - -### Applying a Rule-Set to a Zone - -After you define a rule-set, apply it to the source and destination zones. -The configuration syntax anchors to the destination zone, with each of the -source zone rule-sets listed against the destination. - -```{cfgcmd} set firewall zone \ from \ firewall name \ -``` - -```{cfgcmd} set firewall zone \ from \ firewall ipv6-name \ -``` - -You should create two rule-sets for each source-destination zone -pair. - -```none -set firewall zone DMZ from LAN firewall name LAN-DMZ-v4 -set firewall zone LAN from DMZ firewall name DMZ-LAN-v4 -``` - -### Applying a Default Rule-Set to a Zone - -When a destination zone shares a common rule-set for multiple source zones, -or when you require a complex set of default policies, you can apply an -optional default rule-set. The default rule-set applies to all zones that do -not have a rule-set configured as defined in -{ref}`IPv4` - -```{cfgcmd} set firewall zone \ default-firewall name \ -``` - -```{cfgcmd} set firewall zone \ default-firewall ipv6-name \ -``` - -## Operation-mode - -```{opcmd} show firewall zone-policy - -Display a basic summary of the zone configuration. - -:::{code-block} none -vyos@vyos:~$ show firewall zone-policy -Zone Interfaces From Zone Firewall IPv4 Firewall IPv6 ------- ------------ ----------- --------------- --------------- -LAN eth1 WAN WAN-LAN-v4 -eth2 -LOCAL LOCAL LAN LAN-LOCAL-v4 -WAN WAN-LOCAL-v4 WAN-LOCAL-v6 -WAN eth3 LAN LAN-WAN-v4 -eth0 LOCAL LOCAL-WAN-v4 -::: -``` - -```{opcmd} show firewall zone-policy zone \ - -Display a basic summary of a particular zone. - -:::{code-block} none -vyos@vyos:~$ show firewall zone-policy zone WAN -Zone Interfaces From Zone Firewall IPv4 Firewall IPv6 ------- ------------ ----------- --------------- --------------- -WAN eth3 LAN LAN-WAN-v4 -eth0 LOCAL LOCAL-WAN-v4 -vyos@vyos:~$ show firewall zone-policy zone LOCAL -Zone Interfaces From Zone Firewall IPv4 Firewall IPv6 ------- ------------ ----------- --------------- --------------- -LOCAL LOCAL LAN LAN-LOCAL-v4 -WAN WAN-LOCAL-v4 WAN-LOCAL-v6 -::: -``` \ No newline at end of file diff --git a/docs/configuration/highavailability/md-index.md b/docs/configuration/highavailability/md-index.md deleted file mode 100644 index e26f5791..00000000 --- a/docs/configuration/highavailability/md-index.md +++ /dev/null @@ -1,561 +0,0 @@ ---- -lastproofread: '2021-06-30' ---- - -(high-availability)= - -# High availability - -VRRP (Virtual Router Redundancy Protocol) provides active/backup redundancy for -routers. Every VRRP router has a physical IP/IPv6 address, and a virtual -address. On startup, routers elect the master, and the router with the highest -priority becomes the master and assigns the virtual address to its interface. -All routers with lower priorities become backup routers. The master then starts -sending keepalive packets to notify other routers that it's available. If the -master fails and stops sending keepalive packets, the router with the next -highest priority becomes the new master and takes over the virtual address. - -VRRP keepalive packets use multicast, and VRRP setups are limited to a single -datalink layer segment. You can setup multiple VRRP groups -(also called virtual routers). Virtual routers are identified by a -VRID (Virtual Router IDentifier). If you setup multiple groups on the same -interface, their VRIDs must be unique if they use the same address family, -but it's possible (even if not recommended for readability reasons) to use -duplicate VRIDs on different interfaces. - -## Basic setup - -VRRP groups are created with the -`set high-availability vrrp group $GROUP_NAME` commands. The required -parameters are interface, vrid, and address. - -minimal config - -```none -set high-availability vrrp group Foo vrid 10 -set high-availability vrrp group Foo interface eth0 -set high-availability vrrp group Foo address 192.0.2.1/24 -``` - -You can verify your VRRP group status with the operational mode -`run show vrrp` command: - -```none -vyos@vyos# run show vrrp -Name Interface VRID State Last Transition ----------- ----------- ------ ------- ----------------- -Foo eth1 10 MASTER 2s -``` - -## IPv6 support - -The `address` parameter can be either an IPv4 or IPv6 address, but you can -not mix IPv4 and IPv6 in the same group, and will need to create groups with -different VRIDs specially for IPv4 and IPv6. -If you want to use IPv4 + IPv6 address you can use option `excluded-address` - -## Address - -The `address` can be configured either on the VRRP interface or on not VRRP -interface. - -```none -set high-availability vrrp group Foo address 192.0.2.1/24 -set high-availability vrrp group Foo address 203.0.113.22/24 interface eth2 -set high-availability vrrp group Foo address 198.51.100.33/24 interface eth3 -``` - -## Disabling a VRRP group - -You can disable a VRRP group with `disable` option: - -```none -set high-availability vrrp group Foo disable -``` - -A disabled group will be removed from the VRRP process and your router will not -participate in VRRP for that VRID. It will disappear from operational mode -commands output, rather than enter the backup state. - -## Exclude address - -Exclude IP addresses from `VRRP packets`. This option `excluded-address` is -used when you want to set IPv4 + IPv6 addresses on the same virtual interface -or when used more than 20 IP addresses. - -```none -set high-availability vrrp group Foo excluded-address '203.0.113.254/24' -set high-availability vrrp group Foo excluded-address '2001:db8:aa::1/64' -set high-availability vrrp group Foo excluded-address '2001:db8:22::1/64' -``` - -## Setting VRRP group priority - -VRRP priority can be set with `priority` option: - -```none -set high-availability vrrp group Foo priority 200 -``` - -The priority must be an integer number from 1 to 255. Higher priority value -increases router's precedence in the master elections. - -## Sync groups - -A sync group allows VRRP groups to transition together. - -```none -edit high-availability vrrp -set sync-group MAIN member VLAN9 -set sync-group MAIN member VLAN20 -``` - -In the following example, when VLAN9 transitions, VLAN20 will also transition: - -```none -vrrp { - group VLAN9 { - interface eth0.9 - address 10.9.1.1/24 - priority 200 - vrid 9 - } - group VLAN20 { - interface eth0.20 - priority 200 - address 10.20.20.1/24 - vrid 20 - } - sync-group MAIN { - member VLAN20 - member VLAN9 - } -} -``` - -:::{warning} -All items in a sync group should be similarly configured. -If one VRRP group is set to a different preemption delay or priority, -it would result in an endless transition loop. -::: - -## Preemption - -VRRP can use two modes: preemptive and non-preemptive. In the preemptive mode, -if a router with a higher priority fails and then comes back, routers with lower -priority will give up their master status. In non-preemptive mode, the newly -elected master will keep the master status and the virtual address indefinitely. - -By default VRRP uses preemption. You can disable it with the "no-preempt" -option: - -```none -set high-availability vrrp group Foo no-preempt -``` - -You can also configure the time interval for preemption with the "preempt-delay" -option. For example, to set the higher priority router to take over in 180 -seconds, use: - -```none -set high-availability vrrp group Foo preempt-delay 180 -``` - -## Track - -Track option to track non VRRP interface states. VRRP changes status to -`FAULT` if one of the track interfaces in state `down`. - -```none -set high-availability vrrp group Foo track interface eth0 -set high-availability vrrp group Foo track interface eth1 -``` - -Ignore VRRP main interface faults - -```none -set high-availability vrrp group Foo track exclude-vrrp-interface -``` - -## Unicast VRRP - -By default VRRP uses multicast packets. If your network does not support -multicast for whatever reason, you can make VRRP use unicast communication -instead. - -```none -set high-availability vrrp group Foo peer-address 192.0.2.10 -set high-availability vrrp group Foo hello-source-address 192.0.2.15 -``` - -## rfc3768-compatibility - -RFC 3768 defines a virtual MAC address to each VRRP virtual router. -This virtual router MAC address will be used as the source in all periodic VRRP -messages sent by the active node. When the rfc3768-compatibility option is set, -a new VRRP interface is created, to which the MAC address and the virtual IP -address is automatically assigned. - -```none -set high-availability vrrp group Foo rfc3768-compatibility -``` - -Verification - -```none -$show interfaces ethernet eth0v10 -eth0v10@eth0: mtu 1500 qdisc noqueue -state UP group default qlen 1000 -link/ether 00:00:5e:00:01:0a brd ff:ff:ff:ff:ff:ff -inet 172.25.0.247/16 scope global eth0v10 -valid_lft forever preferred_lft forever -``` - -:::{warning} -RFC 3768 creates a virtual interface. If you want to apply -the destination NAT rule to the traffic sent to the virtual MAC, set -the created virtual interface as `inbound-interface`. -::: - -## Global options - -On most scenarios, there's no need to change specific parameters, and using -default configuration is enough. But there are cases were extra configuration -is needed. - -```{eval-rst} -.. cfgcmd:: set high-availability vrrp global-parameters startup_delay <1-600> - - This option specifies a delay in seconds before vrrp instances start up - after keepalived starts. -``` - -## Gratuitous ARP - -These configuration is not mandatory and in most cases there's no -need to configure it. But if necessary, Gratuitous ARP can be configured in -`global-parameters` and/or in `group` section. - -```{eval-rst} -.. cfgcmd:: set high-availability vrrp global-parameters garp interval - <0.000-1000> -``` - -```{eval-rst} -.. cfgcmd:: set high-availability vrrp group garp interval <0.000-1000> - - Set delay between gratuitous ARP messages sent on an interface. - - 0 if not defined. -``` - -% stop_vyoslinter - -```{eval-rst} -.. cfgcmd:: set high-availability vrrp global-parameters garp master-delay <1-255> -``` - -% start_vyoslinter - -```{eval-rst} -.. cfgcmd:: set high-availability vrrp group garp master-delay <1-255> - - Set delay for second set of gratuitous ARPs after transition to MASTER. - - 5 if not defined. -``` - -```{eval-rst} -.. cfgcmd:: set high-availability vrrp global-parameters garp master-refresh - <1-600> -``` - -```{eval-rst} -.. cfgcmd:: set high-availability vrrp group garp master-refresh - <1-600> - - Set minimum time interval for refreshing gratuitous ARPs while MASTER. - - 0 if not defined, which means no refreshing. -``` - -```{eval-rst} -.. cfgcmd:: set high-availability vrrp global-parameters garp - master-refresh-repeat <1-600> -``` - -```{eval-rst} -.. cfgcmd:: set high-availability vrrp group garp - master-refresh-repeat <1-600> - - Set number of gratuitous ARP messages to send at a time while MASTER. - - 1 if not defined. -``` - -```{eval-rst} -.. cfgcmd:: set high-availability vrrp global-parameters garp master-repeat - <1-600> -``` - -```{eval-rst} -.. cfgcmd:: set high-availability vrrp group garp master-repeat - <1-600> - - Set number of gratuitous ARP messages to send at a time after transition to - MASTER. - - 5 if not defined. -``` - -## Version - -```{eval-rst} -.. cfgcmd:: set high-availability vrrp global-parameters version 2|3 - - Set the default VRRP version to use. This defaults to 2, but IPv6 instances - will always use version 3. -``` - -## Scripting - -VRRP functionality can be extended with scripts. VyOS supports two kinds of -scripts: health check scripts and transition scripts. Health check scripts -execute custom checks in addition to the master router reachability. Transition -scripts are executed when VRRP state changes from master to backup or fault and -vice versa and can be used to enable or disable certain services, for example. - -:::{note} -Simply placing script files in `/config/scripts/` does not mean the -system can execute them. To make custom scripts executable, grant them -**execute permissions**. Use the following command: - -```none -chmod +x /config/scripts/script-name.sh -``` -::: - -:::{warning} -It is not recommended to change VRRP configuration -inside health-check and transition scripts. -::: - -### Health check scripts - -There is the ability to run an arbitrary script at regular intervals -according to health-check parameters. If a script returns 0, it -indicates success. If a script returns anything else, it will indicate -that the VRRP instance should enter the FAULT state. - -This setup will make the VRRP process execute the -`/config/scripts/vrrp-check.sh script` every 60 seconds, and transition the -group to the fault state if it fails (i.e. exits with non-zero status) three -times: - -% stop_vyoslinter - -```none -set high-availability vrrp group Foo health-check script /config/scripts/vrrp-check.sh -set high-availability vrrp group Foo health-check interval 60 -set high-availability vrrp group Foo health-check failure-count 3 -``` - -% start_vyoslinter - -An optional `timeout` can be set to define the maximum number of seconds the -script is allowed to run. This is useful for scripts that may hang or take -longer than expected — setting the timeout higher than the interval allows -longer-running scripts to complete before being considered failed. - -% stop_vyoslinter - -```none -set high-availability vrrp group Foo health-check script /config/scripts/vrrp-check.sh -set high-availability vrrp group Foo health-check interval 20 -set high-availability vrrp group Foo health-check failure-count 3 -set high-availability vrrp group Foo health-check timeout 40 -``` - -% start_vyoslinter - -When the vrrp group is a member of the sync group will use only -the sync group health check script. -This example shows how to configure it for the sync group: - -% stop_vyoslinter - -```none -set high-availability vrrp sync-group Bar health-check script /config/scripts/vrrp-check.sh -set high-availability vrrp sync-group Bar health-check interval 60 -set high-availability vrrp sync-group Bar health-check failure-count 3 -``` - -% start_vyoslinter - -### Transition scripts - -Transition scripts can help you implement various fixups, such as starting and -stopping services, or even modifying the VyOS config on VRRP transition. -This setup will make the VRRP process execute the -`/config/scripts/vrrp-fail.sh` with argument `Foo` when VRRP fails, -and the `/config/scripts/vrrp-master.sh` when the router becomes the master: - -% stop_vyoslinter - -```none -set high-availability vrrp group Foo transition-script backup "/config/scripts/vrrp-fail.sh Foo" -set high-availability vrrp group Foo transition-script fault "/config/scripts/vrrp-fail.sh Foo" -set high-availability vrrp group Foo transition-script master "/config/scripts/vrrp-master.sh Foo" -``` - -% start_vyoslinter - -To know more about scripting, check the {ref}`command-scripting` section. - -## Virtual-server - -```{eval-rst} -.. include:: /_include/need_improvement.txt -``` - -Virtual Server allows to Load-balance traffic destination virtual-address:port -between several real servers. - -### Algorithm - -Load-balancing schedule algorithm: - -- round-robin -- weighted-round-robin -- least-connection -- weighted-least-connection -- source-hashing -- destination-hashing -- locality-based-least-connection - -```none -set high-availability virtual-server 203.0.113.1 algorithm 'least-connection' -``` - -### Forward method - -- NAT -- direct -- tunnel - -```none -set high-availability virtual-server 203.0.113.1 forward-method 'nat' -``` - -### Health-check - -Custom health-check script allows checking real-server availability - -% stop_vyoslinter - -```none -set high-availability virtual-server 203.0.113.1 real-server 192.0.2.11 health-check script -``` - -% start_vyoslinter - -### Fwmark - -Firewall mark. It possible to loadbalancing traffic based on `fwmark` value - -```none -set high-availability virtual-server 203.0.113.1 fwmark '111' -``` - -### Real server - -Real server IP address and port - -% stop_vyoslinter - -```none -set high-availability virtual-server 203.0.113.1 real-server 192.0.2.11 port '80' -``` - -% start_vyoslinter - -### Example - -Virtual-server can be configured with VRRP virtual address or without VRRP. - -In the next example all traffic destined to `203.0.113.1` and port `8280` -protocol TCP is balanced between 2 real servers `192.0.2.11` and -`192.0.2.12` to port `80` - -Real server is auto-excluded if port check with this server fail. - -% stop_vyoslinter - -```none -set interfaces ethernet eth0 address '203.0.113.11/24' -set interfaces ethernet eth1 address '192.0.2.1/24' -set high-availability vrrp group FOO interface 'eth0' -set high-availability vrrp group FOO no-preempt -set high-availability vrrp group FOO priority '150' -set high-availability vrrp group FOO address '203.0.113.1/24' -set high-availability vrrp group FOO vrid '10' - -set high-availability virtual-server 203.0.113.1 algorithm 'source-hashing' -set high-availability virtual-server 203.0.113.1 delay-loop '10' -set high-availability virtual-server 203.0.113.1 forward-method 'nat' -set high-availability virtual-server 203.0.113.1 persistence-timeout '180' -set high-availability virtual-server 203.0.113.1 port '8280' -set high-availability virtual-server 203.0.113.1 protocol 'tcp' -set high-availability virtual-server 203.0.113.1 real-server 192.0.2.11 port '80' -set high-availability virtual-server 203.0.113.1 real-server 192.0.2.12 port '80' -``` - -% start_vyoslinter - -A firewall mark `fwmark` allows using multiple ports for high-availability -virtual-server. -It uses fwmark value. - -In this example all traffic destined to ports "80, 2222, 8888" protocol TCP -marks to fwmark "111" and balanced between 2 real servers. -Port "0" is required if multiple ports are used. - -% stop_vyoslinter - -```none -set interfaces ethernet eth0 address 'dhcp' -set interfaces ethernet eth0 description 'WAN' -set interfaces ethernet eth1 address '192.0.2.1/24' -set interfaces ethernet eth1 description 'LAN' - -set policy route PR interface 'eth0' -set policy route PR rule 10 destination port '80,2222,8888' -set policy route PR rule 10 protocol 'tcp' -set policy route PR rule 10 set mark '111' - -set high-availability virtual-server vyos fwmark '111' -set high-availability virtual-server vyos protocol 'tcp' -set high-availability virtual-server vyos real-server 192.0.2.11 health-check script '/config/scripts/check-real-server-first.sh' -set high-availability virtual-server vyos real-server 192.0.2.11 port '0' -set high-availability virtual-server vyos real-server 192.0.2.12 health-check script '/config/scripts/check-real-server-second.sh' -set high-availability virtual-server vyos real-server 192.0.2.12 port '0' - -set nat source rule 100 outbound-interface name 'eth0' -set nat source rule 100 source address '192.0.2.0/24' -set nat source rule 100 translation address 'masquerade' -``` - -% start_vyoslinter - -Op-mode check virtual-server status - -```none -vyos@r14:~$ run show virtual-server -IP Virtual Server version 1.2.1 (size=4096) -Prot LocalAddress:Port Scheduler Flags - -> RemoteAddress:Port Forward Weight ActiveConn InActConn -FWM 111 lc persistent 300 - -> 192.0.2.11:0 Masq 1 0 0 - -> 192.0.2.12:0 Masq 1 1 0 -``` - diff --git a/docs/configuration/interfaces/md-bonding.md b/docs/configuration/interfaces/md-bonding.md deleted file mode 100644 index 7a07a27c..00000000 --- a/docs/configuration/interfaces/md-bonding.md +++ /dev/null @@ -1,764 +0,0 @@ ---- -lastproofread: '2025-12-09' ---- - -(bond-interface)= - -# Bond / link aggregation - -A **bonding interface** aggregates multiple network interfaces into a single -logical interface (referred to as a bond, {abbr}`LAG (Link Aggregation Group)`, -EtherChannel, or port-channel). - -The behavior of a bonding interface depends on the selected mode. Modes provide -either fault tolerance or a combination of load balancing and fault tolerance. -Additionally, the bonding interface can be configured for link integrity -monitoring. - -## Configuration - -### Common interface configuration - -```{cmdincludemd} /_include/interface-common-with-dhcp.txt -:var0: bonding -:var1: bond0 -``` - -### Member interfaces - -```{cfgcmd} set interfaces bonding \ member interface \ - -**Add an interface to the bonding group.** - -**Example:** - -To configure eth0 and eth1 as members of the bonding interface bond0, execute -the following commands: -``` - -```none -set interfaces bonding bond0 member interface eth0 -set interfaces bonding bond0 member interface eth1 -``` - -### Bond modes - -````{cfgcmd} set interfaces bonding \ mode \<802.3ad | active-backup | broadcast | round-robin | transmit-load-balance | adaptive-load-balance | xor-hash\> - -```{eval-rst} -**Configure the bonding mode on the interface. The default mode is** -``802.3ad``. - -The available modes are: - -* ``802.3ad`` - -.. list-table:: - :widths: 20 80 - - * - **Description:** - - IEEE 802.3ad Dynamic Link Aggregation. Groups only member - interfaces with the same speed (e.g., 1 Gbps) and duplex - settings. Member interfaces with different speed and duplex - settings are not included in the active bond. - - Provides load balancing and fault tolerance. Uses the - :abbr:`LACP (Link Aggregation Control Protocol)` to - negotiate the bond with the switch. - * - **Traffic distribution:** - - Traffic is distributed according to the **transmit hash - policy** (default: XOR). - - The bonding driver applies an XOR operation to specific - packet header fields, generating a hash value that maps to - a particular member interface. This ensures the same network - flow is consistently transmitted over the same member - interface. - - The transmit hash policy is configured via the ``hash-policy`` option. - * - **Failover:** - - If a member interface fails, the hash is recalculated to distribute - traffic among the remaining active member interfaces. - -.. note:: Not all transmit hash policies comply with 802.3ad, particularly - section 43.2.4. Using a non-compliant policy may result in out-of-order - packet delivery. - -* ``active-backup`` - -.. list-table:: - :widths: 20 80 - - * - **Description:** - - Provides fault tolerance. Only one member interface is active - at a time. Other member interfaces remain in a standby mode. - * - **Traffic distribution:** - - All traffic (incoming and outgoing) is routed via one active - member interface. - * - **Failover:** - - If the designated member interface fails, all traffic is - routed to another member interface. The bonding driver sends - a Gratuitous ARP to update the peer's MAC address table, - linking the bond's MAC address to another physical port. - -* ``broadcast`` - -.. list-table:: - :widths: 20 80 - - * - **Description:** - - Provides maximum fault tolerance by duplicating traffic. - * - **Traffic distribution:** - - Every packet is duplicated and transmitted on **all** member - interfaces. - * - **Failover:** - - Traffic flow is not interrupted as long as at least one - member interface remains active. - -* ``round-robin`` - -.. list-table:: - :widths: 20 80 - - * - **Description:** - - Provides load balancing and fault tolerance. - * - **Traffic distribution:** - - Packets are transmitted in sequential order across the member - interfaces (e.g., packet 1 > interface A, packet 2 > - interface B, etc.). - * - **Failover:** - - If a member interface fails, the sequence skips the failed - interface and continues with the remaining active members. - -* ``transmit-load-balance`` - -.. list-table:: - :widths: 20 80 - - * - **Description:** - - Provides adaptive transmit load balancing and fault tolerance. - * - **Traffic distribution:** - - **Outgoing:** Distributed across all active member interfaces - based on the current load. - - **Incoming:** Received by a designated member interface - (active receiver). - * - **Failover:** - - If the active receiver fails, another member interface takes - over as the new active receiver. - -* ``adaptive-load-balance`` - -.. list-table:: - :widths: 20 80 - - * - **Description:** - - Provides adaptive transmit load balancing identical to - ``transmit-load-balance``, receive load balancing for IPv4 - traffic, and fault tolerance for both incoming and outgoing - traffic. - * - **Traffic distribution:** - - **Outgoing:** Identical to ``transmit-load-balance``. - - **Incoming:** Distributed based on ARP manipulation. For - both local and remote connections, the bonding driver - intercepts ARP traffic and changes the source MAC address - to the MAC address of the least loaded member interface. - - All traffic from that peer is then routed to the chosen - member interface. - * - **Failover:** - - If a member interface's state changes (fails, recovers, is - added, or excluded), the traffic is redistributed among all - active member interfaces. - -* ``xor-hash``: Provides load balancing and fault tolerance - based on a hash formula. Distributes traffic and handles - failover identically to ``802.3ad``, but operates without - the :abbr:`LACP (Link Aggregation Control Protocol)`. -``` - -```` - -```{cfgcmd} set interfaces bonding \ min-links \<0-16\> - -**Configure how many member interfaces must be active (in the -link-up state) to mark the bonding interface UP (carrier -asserted).** - -This command applies only when the bonding interface is configured -in 802.3ad mode and functions like the Cisco EtherChannel min-links -feature. It ensures that a bonding interface is marked UP (carrier -asserted) only when a specified number of member interfaces are -active (in the link-up state). This helps guarantee a minimum level -of bandwidth for higher-level services (such as clustering) relying -on the bonding interface. - -The default value is 0. This marks the bonding interface UP -(carrier asserted) whenever an active LACP aggregator exists, -regardless of the number of member interfaces in that aggregator. - -:::{note} -In 802.3ad mode, a bond cannot be active without at least one active -member interface. Therefore, setting min-links to 0 or 1 has the same result: -the bonding interface is marked UP (carrier asserted). -::: -``` - -```{cfgcmd} set interfaces bonding \ lacp-rate \ - -**Configure the rate at which the bonding interface requests its link -partner to send** {abbr}`LACPDUs (Link Aggregation Control Protocol Data -Units)` **in 802.3ad mode.** - -This command applies only when the bonding interface is configured in -802.3ad mode. - -The following options are available: - -* **slow (default):** Requests the link partner to transmit LACPDUs every 30 seconds. - -* **fast:** Requests the link partner to transmit LACPDUs every 1 second. -``` -```{cfgcmd} set interfaces bonding \ system-mac \ - -**Configure a specific MAC address for the bonding interface.** - -This sets the 802.3ad system MAC address, which is used for {abbr}`LACPDU (Link -Aggregation Control Protocol Data Unit)` exchanges with the link partner. -You can assign a fixed MAC address or generate a random one for these -{abbr}`LACPDU (Link Aggregation Control Protocol Data Unit)` exchanges. -``` -```{cfgcmd} set interfaces bonding \ hash-policy \ - -**Configure which transmit hash policy to use for distributing traffic across -member interfaces.** - -The following policies are available: - -* ``layer2`` - -**Description:** Routes all traffic destined for a specific network peer through -the same member interface. The policy is 802.3ad-compliant. - -**Hash inputs:** Source MAC address, destination MAC address, and Ethernet packet -type ID. - -**Formula:** - -:::{code-block} none -hash = source MAC address XOR destination MAC address XOR packet type ID -member interface number = hash modulo member interface count -::: - -* ``layer2+3`` - -**Description:** Similar to ``layer2``, routes all traffic destined for a specific -network peer through the same member interface and is IEEE 802.3ad-compliant. Uses -both Layer 2 and Layer 3 information to provide a more balanced traffic distribution. - -**Hash inputs:** -* Source MAC address, destination MAC address, and Ethernet packet type ID. -* Source IP address, destination IP address. IPv6 addresses are first hashed - using ``IPv6_addr_hash``. - -**Formula:** - -:::{code-block} none -hash = source MAC address XOR destination MAC address XOR packet type ID -hash = hash XOR source IP address XOR destination IP address -hash = hash XOR (hash RSHIFT 16) -hash = hash XOR (hash RSHIFT 8) -member interface number = hash modulo member interface count -::: - -For non-IP traffic, the formula is the same as for ``layer2``. - -* ``layer3+4`` - -**Description:** Routes different connections (flows) destined for a specific -network peer through multiple member interfaces, but ensures each individual -flow is routed through only one member interface. - -:::{note} -This policy is not fully 802.3ad-compliant. When a single TCP or UDP flow -contains both fragmented and unfragmented packets, the algorithm may distribute -them across different member interfaces. This may result in out-of-order packet -delivery, violating the 802.3ad standard. -::: - -**Hash inputs:** -* Source port, destination port (if available). -* Source IP address, destination IP address. IPv6 addresses are first hashed - using ``IPv6_addr_hash``. - -**Formula:** - -:::{code-block} none -hash = source port, destination port (as in the header) -hash = hash XOR source IP address XOR destination IP address -hash = hash XOR (hash RSHIFT 16) -hash = hash XOR (hash RSHIFT 8) -member interface number = hash modulo member interface count -::: - -For fragmented TCP or UDP packets and all other IPv4 and IPv6 traffic, the -source and destination port information is omitted. - -For non-IP traffic, the formula is the same as for ``layer2``. -``` - - -```{cfgcmd} set interfaces bonding \ primary \ - -**Configure the primary member interface in the bond.** - -The primary member interface remains active as long as it is operational; -alternative member interfaces are used only if it fails. - -Use this configuration when a specific member interface is preferred, -such as one with higher throughput. - -This command applies only to ``active-backup``, ``transmit-load-balance``, and -``adaptive-load-balance`` modes. -``` - - -```{cfgcmd} set interfaces bonding \ arp-monitor interval \ - -**Configure the ARP monitoring interval, in seconds, for the bonding interface.** - -ARP monitoring periodically assesses the health of each member interface by -checking whether it has recently sent or received traffic (this criterion -varies depending on the bonding mode and the member interface’s state). ARP -probes are sent to the IP addresses specified with the arp-monitor target option. - -When ARP monitoring is used with EtherChannel-compatible modes (such as -``round-robin`` or ``xor-hash``), the switch should be configured to distribute -traffic across all member interfaces. If the switch distributes traffic using -an XOR-based policy, all ARP replies will be received on one member interface, -causing other member interfaces to be incorrectly marked as failed. - -Setting this value to 0 disables ARP monitoring. - -The default value is 0. -``` - - -```{cfgcmd} set interfaces bonding \ arp-monitor target \ - -**Configure the IP addresses for ARP monitoring requests.** - -The bonding driver sends ARP requests to these IP addresses to check the -state of member interfaces. - -To enable ARP monitoring, configure at least one IP address (up to 16 per -bonding interface). - -By default, no IP addresses are configured. -``` - -### {abbr}`VLAN (Virtual Local Area Network)` - -```{cmdincludemd} /_include/interface-vlan-8021q.txt -:var0: bonding -:var1: bond0 -``` - -### SPAN port mirroring - -```{cmdincludemd} ../../_include/interface-mirror.txt -:var0: bonding -:var1: bond1 -:var2: eth3 -``` - -#### EVPN multihoming - - -EVPN multihoming (EVPN-MH) is a standards-based solution (RFC 7432, RFC 8365) -that enables Customer Edge (CE) devices, such as servers, to connect to two -or more Provider Edge (PE) devices for redundancy and load balancing. - - -EVPN-MH is often used as a modern, standards-based alternative to -{abbr}`MLAG (Multi-Chassis Link Aggregation)` and {abbr}`VTEPs (Virtual -Tunnel Endpoints)`. - - -**Ethernet Segment (ES) and Ethernet Segment Identifier (ESI)** - - -Physical links that connect a CE device to PE devices are bundled using link -aggregation. This logical bundle is called an Ethernet Segment (ES) and is -uniquely identified by an Ethernet Segment Identifier (ESI) within the -EVPN domain. - - -To enable EVPN-MH, configure the same ESI on the bonding interfaces of all -PE devices connected to a single CE device. - - -An ESI is configured by specifying either a system MAC address and a local -discriminator, or an Ethernet Segment Identifier Name (ESINAME). - - -The following two commands generate a 10-byte Type-3 ESI by combining the -system MAC and local discriminator: - -```{cfgcmd} set interfaces bonding \ evpn es-id \<1-16777215|10-byte ID\> - -``` -```{cfgcmd} set interfaces bonding \ evpn es-sys-mac \ - -Alternatively, assign an ESINAME directly as a 10-byte Type-0 ESI using the -following format: 00:AA:BB:CC:DD:EE:FF:GG:HH:II. - -**BGP-EVPN route usage** - -EVPN-MH uses BGP-EVPN route types 1 and 2 for ES discovery and MAC-IP -synchronization: - -* **Type 1 (EAD-per-ES and EAD-per-EVI)** routes advertise the locally -attached ESs and discover remote ESs in the network. -* **Type 2 (MAC-IP advertisement)** routes are advertised with a -destination ESI, enabling MAC-IP synchronization between ES peers. -``` - -```{cfgcmd} set interfaces bonding \ evpn es-df-pref \<1-65535\> - -**Configure the** {abbr}`DF (Designated Forwarder)` **preference (1-65535) for -the interface. A higher value indicates a higher preference to become the** -{abbr}`DF (Designated Forwarder)`. **The** {abbr}`DF (Designated Forwarder)` -**preference is configured per-ES.** - -The DF election process determines which interface in a specific ES forwards -{abbr}`BUM (Broadcast, Unknown Unicast, and Multicast)` traffic from the EVPN -overlay to the connected CE device. EVPN Type-4 (Ethernet Segment) routes are -used to elect the DF, implementing the preference-based election method defined -in RFC 9785. - -Interfaces not elected as the DF drop any BUM traffic from the EVPN overlay -using non-DF filters. Similarly, traffic received from ES peers via the EVPN -overlay is blocked from forwarding to the CE device to maintain split-horizon -filtering with local bias. -``` - -```{cmdincludemd} /_include/interface-evpn-uplink.txt -:var0: bonding -:var1: bond0 -``` - -## Example - - -The following configuration example applies to all listed third-party vendors. -It creates a bonding interface with two member interfaces, defines VLANs 10 -and 100 on the bonding interface, and assigns an IPv4 address to each VLAN -subinterface. - -```none -# Create the bonding interface bond0 with 802.3ad LACP -set interfaces bonding bond0 hash-policy 'layer2' -set interfaces bonding bond0 mode '802.3ad' - -# Add the required VLANs and IPv4 addresses on them -set interfaces bonding bond0 vif 10 address 192.168.0.1/24 -set interfaces bonding bond0 vif 100 address 10.10.10.1/24 - -# Add the member interfaces to the bonding interface -set interfaces bonding bond0 member interface eth1 -set interfaces bonding bond0 member interface eth2 -``` -:::{note} -If you are running this configuration in a virtual environment like -EVE-NG, ensure the e1000 driver is chosen for your VyOS NIC. The default -drivers, such as ``virtio-net-pci`` or ``vmxnet3``, are incompatible with -this configuration. Specifically, ICMP messages will not be processed -correctly. - -To check your NIC driver, use the following command: -``show interfaces ethernet eth0 physical | grep -i driver`` -::: - - -### Cisco Catalyst configuration - - -Configure a Cisco Catalyst switch to integrate with a two-member VyOS bonding -interface. - - -Assign member interfaces to PortChannel: - -```none -interface GigabitEthernet1/0/23 - description VyOS eth1 - channel-group 1 mode active -! -interface GigabitEthernet1/0/24 - description VyOS eth2 - channel-group 1 mode active -! -``` - -A new interface, `Port-channel1`, becomes available; all configuration, -such as allowed VLAN interfaces and STP, is applied here. - -```none -interface Port-channel1 - description LACP Channel for VyOS - switchport trunk encapsulation dot1q - switchport trunk allowed vlan 10,100 - switchport mode trunk - spanning-tree portfast trunk -! -``` - -### Juniper EX Switch configuration - - -Configure a Juniper EX Series switch to integrate with a two-member VyOS bonding -interface. - -```none -# Create aggregated ethernet device with 802.3ad LACP and port speeds of 10gbit/s -set interfaces ae0 aggregated-ether-options link-speed 10g -set interfaces ae0 aggregated-ether-options lacp active - -# Create layer 2 on the aggregated ethernet device with trunking for our VLANs -set interfaces ae0 unit 0 family ethernet-switching port-mode trunk - -# Add the required vlans to the device -set interfaces ae0 unit 0 family ethernet-switching vlan members 10 -set interfaces ae0 unit 0 family ethernet-switching vlan members 100 - -# Add the two interfaces to the aggregated ethernet device, in this setup both -# ports are on the same switch (switch 0, module 1, port 0 and 1) -set interfaces xe-0/1/0 ether-options 802.3ad ae0 -set interfaces xe-0/1/1 ether-options 802.3ad ae0 - -# But this can also be done with multiple switches in a stack, a virtual -# chassis on Juniper (switch 0 and switch 1, module 1, port 0 on both switches) -set interfaces xe-0/1/0 ether-options 802.3ad ae0 -set interfaces xe-1/1/0 ether-options 802.3ad ae0 -``` - -### Aruba/HP configuration - - -Configure an Aruba/HP 2510G switch to integrate with a two-member VyOS bonding -interface. - -```none -# Create trunk with 2 member interfaces (interface 1 and 2) and LACP -trunk 1-2 Trk1 LACP - -# Add the required VLANs to the trunk -vlan 10 tagged Trk1 -vlan 100 tagged Trk1 -``` - -### Arista EOS configuration - - -When deploying VyOS in environments with Arista switches, use the following -blueprint as an initial setup to configure an operational LACP port-channel -between the two devices. - - -Let's assume the following topology: - - -```{eval-rst} -.. figure:: /_static/images/vyos_arista_bond_lacp.webp - :alt: VyOS Arista EOS setup -``` - - -**R1** - -```none -interfaces { - bonding bond10 { - hash-policy layer3+4 - member { - interface eth1 - interface eth2 - } - mode 802.3ad - vif 100 { - address 192.0.2.1/30 - address 2001:db8::1/64 - } - } -``` -**R2** - - - -```none -interfaces { - bonding bond10 { - hash-policy layer3+4 - member { - interface eth1 - interface eth2 - } - mode 802.3ad - vif 100 { - address 192.0.2.2/30 - address 2001:db8::2/64 - } - } -``` -**SW1** - -```none -! -vlan 100 - name FOO -! -interface Port-Channel10 - switchport trunk allowed vlan 100 - switchport mode trunk - spanning-tree portfast -! -interface Port-Channel20 - switchport mode trunk - no spanning-tree portfast auto - spanning-tree portfast network -! -interface Ethernet1 - channel-group 10 mode active -! -interface Ethernet2 - channel-group 10 mode active -! -interface Ethernet3 - channel-group 20 mode active -! -interface Ethernet4 - channel-group 20 mode active -! -``` -**SW2** - - - -```none -! -vlan 100 - name FOO -! -interface Port-Channel10 - switchport trunk allowed vlan 100 - switchport mode trunk - spanning-tree portfast -! -interface Port-Channel20 - switchport mode trunk - no spanning-tree portfast auto - spanning-tree portfast network -! -interface Ethernet1 - channel-group 10 mode active -! -interface Ethernet2 - channel-group 10 mode active -! -interface Ethernet3 - channel-group 20 mode active -! -interface Ethernet4 - channel-group 20 mode active -! -``` -:::{note} -When testing this environment in EVE-NG, ensure the e1000 driver -is chosen for your VyOS network interfaces. If the default virtio driver -is used, VyOS will not transmit LACP PDUs, preventing the port-channel -from ever becoming active. -::: - - -(operation)= - -## Operation - -```{opcmd} show interfaces bonding - -Show brief interface information. - - -:::{code-block} none -vyos@vyos:~$ show interfaces bonding -Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down -Interface IP Address S/L Description ---------- ---------- --- ----------- -bond0 - u/u my-sw1 int 23 and 24 -bond0.10 192.168.0.1/24 u/u office-net -bond0.100 10.10.10.1/24 u/u management-net -::: -``` -```{opcmd} show interfaces bonding \ - -Show detailed interface information. - -:::{code-block} none -vyos@vyos:~$ show interfaces bonding bond5 -bond5: mtu 1500 qdisc noqueue state DOWN group default qlen 1000 - link/ether 00:50:56:bf:ef:aa brd ff:ff:ff:ff:ff:ff - inet6 fe80::e862:26ff:fe72:2dac/64 scope link tentative - valid_lft forever preferred_lft forever - - RX: bytes packets errors dropped overrun mcast - 0 0 0 0 0 0 - TX: bytes packets errors dropped carrier collisions - 0 0 0 0 0 0 -::: -``` -```{opcmd} show interfaces bonding \ detail - -Show detailed information about the underlying physical links on the given -bonding interface. - -:::{code-block} none -vyos@vyos:~$ show interfaces bonding bond5 detail -Ethernet Channel Bonding Driver: v3.7.1 (April 27, 2011) -Bonding Mode: IEEE 802.3ad Dynamic link aggregation -Transmit Hash Policy: layer2 (0) -MII Status: down -MII Polling Interval (ms): 100 -Up Delay (ms): 0 -Down Delay (ms): 0 -802.3ad info -LACP rate: slow -Min links: 0 -Aggregator selection policy (ad_select): stable -Slave Interface: eth1 -MII Status: down -Speed: Unknown -Duplex: Unknown -Link Failure Count: 0 -Permanent HW addr: 00:50:56:bf:ef:aa -Slave queue ID: 0 -Aggregator ID: 1 -Actor Churn State: churned -Partner Churn State: churned -Actor Churned Count: 1 -Partner Churned Count: 1 -Slave Interface: eth2 -MII Status: down -Speed: Unknown -Duplex: Unknown -Link Failure Count: 0 -Permanent HW addr: 00:50:56:bf:19:26 -Slave queue ID: 0 -Aggregator ID: 2 -Actor Churn State: churned -Partner Churn State: churned -Actor Churned Count: 1 -Partner Churned Count: 1 -::: -``` \ No newline at end of file diff --git a/docs/configuration/interfaces/md-bridge.md b/docs/configuration/interfaces/md-bridge.md deleted file mode 100644 index 77775767..00000000 --- a/docs/configuration/interfaces/md-bridge.md +++ /dev/null @@ -1,431 +0,0 @@ ---- -lastproofread: '2025-12-22' ---- - -(bridge-interface)= - -# Bridge - -VyOS bridges connect Ethernet segments by grouping multiple interfaces into a -single bridge interface, which acts as a virtual software switch. Unlike -routers, which forward traffic based on Layer 3 IP addresses, bridges operate -at Layer 2 and forward traffic based on MAC addresses. Operating at Layer 2, -bridges are protocol-agnostic and transparently forward all Ethernet- -encapsulated traffic, whether it is IPv4, IPv6, or specialized industrial -protocols. - -This implementation utilizes the Linux bridge subsystem to support a subset of -the ANSI/IEEE 802.1d standard for transparent bridging and MAC address learning. - -:::{note} -{abbr}`STP (Spanning Tree Protocol)` is disabled by default in VyOS -and must be explicitly enabled if required. See {ref}`stp` for details. -::: - -## Configuration - -### Common interface configuration - -```{cmdincludemd} /_include/interface-common-with-dhcp.txt -:var0: bridge -:var1: br0 -``` - - -### Member interfaces - -```{cfgcmd} set interfaces bridge \ member interface \ - -**Configure an interface as a bridge member.** - -Valid interface types are: {ref}`ethernet-interface`, {ref}`bond-interface`, -{ref}`l2tpv3-interface`, {ref}`openvpn`, {ref}`vxlan-interface`, -{ref}`wireless-interface`, {ref}`tunnel-interface`, and -{ref}`geneve-interface`. - -Use tab completion to list interfaces that can be bridged. -``` - -```{cfgcmd} set interfaces bridge \ member interface \ priority \ - -**Configure the** {abbr}`STP (Spanning Tree Protocol)` **port priority -for a specific member interface within a bridge.** - -Within the {abbr}`STP (Spanning Tree Protocol)` topology, each member interface -in a bridge operates as a port with an assigned **priority** and **path cost**. -{abbr}`STP (Spanning Tree Protocol)` uses these values to determine the -**lowest-cost path** to the root bridge, maintaining a loop-free topology. -Traffic flows through the path with the lowest path cost, while alternate -paths remain in standby. - -A **lower** priority value means **higher** precedence in path selection. - -{abbr}`STP (Spanning Tree Protocol)` considers the port priority only if -multiple member interfaces have the same path costs. -``` - -```{cfgcmd} set interfaces bridge \ member interface \ cost \ - -**Configure the** {abbr}`STP (Spanning Tree Protocol)` **path cost for a -specific member interface within the bridge.** - -Path cost is the primary metric {abbr}`STP (Spanning Tree Protocol)` uses to -determine the path to the root bridge. This value is based on interface -bandwidth; faster interfaces receive lower costs. - -By assigning a lower cost, you give the interface higher precedence during -path selection. -``` - -```{cfgcmd} set interfaces bridge \ member interface \ disable-learning - -**Disable MAC address learning for a specific member interface -within a bridge.** - -When learning is disabled, the bridge will not add source MAC addresses -observed on this port to its forwarding database (FDB). Frames destined -to MACs not present in the FDB are then flooded to all bridge ports -rather than unicast-forwarded. -``` - - -### Bridge options - -Configure how bridge interfaces maintain their {abbr}`FDB (Forwarding Database)` -, react to topology changes, and optimize multicast data streams. - -```{cfgcmd} set interfaces bridge \ aging \ - -**Configure the MAC address aging time for the bridge.** - -The duration in seconds that a MAC address remains in the bridge’s {abbr}`FDB -(Forwarding Database)` before removal if no traffic is received from that -address. - -The default value is 300 seconds. -``` - -```{cfgcmd} set interfaces bridge \ max-age \ - -**Configure the** {abbr}`STP (Spanning Tree Protocol)` **max age timer for -the bridge.** - -The duration in seconds that the bridge waits for a {abbr}`BPDU (Bridge -Protocol Data Unit)` from the root bridge. - -If the bridge does not receive a {abbr}`BPDU (Bridge Protocol Data Unit)` -within this period, it recalculates the path to the root bridge or initiates -a new root bridge election. -``` - -```{cfgcmd} set interfaces bridge \ igmp querier - -**Configure the bridge interface to act as the** {abbr}`IGMP (Internet Group -Management Protocol)`/{abbr}`MLD (Multicast Listener Discovery)` **Querier.** - -**When configured:** The bridge interface sends {abbr}`IGMP (Internet Group -Management Protocol)` (IPv4) and {abbr}`MLD (Multicast Listener Discovery)` -(IPv6) general queries to all connected hosts to identify active multicast -listeners. -``` - -```{cfgcmd} set interfaces bridge \ igmp snooping - -**Configure the bridge interface to perform** {abbr}`IGMP (Internet Group -Management Protocol)`/{abbr}`MLD (Multicast Listener Discovery)` -**snooping.** - -**When configured:** The bridge interface monitors {abbr}`IGMP (Internet Group -Management Protocol)` (IPv4) and {abbr}`MLD (Multicast Listener Discovery)` -(IPv6) join requests and restricts multicast traffic forwarding to only active -listeners. This prevents network flooding. -``` - -(stp)= - -#### STP configuration - -{abbr}`STP (Spanning Tree Protocol)` is a Layer 2 protocol that prevents loops -in Ethernet networks by ensuring only one logical path exists between any two -bridges. This creates a loop-free topology and prevents broadcast storms that -can crash the network. - -By default, {abbr}`STP (Spanning Tree Protocol)` is disabled on bridge interfaces. -To activate loop prevention, you must explicitly enable the protocol and -configure its parameters. - -```{cfgcmd} set interfaces bridge \ stp - -Enable {abbr}`STP (Spanning Tree Protocol)` on the bridge interface. -``` - -```{cfgcmd} set interfaces bridge \ forwarding-delay \ - -**Configure the** {abbr}`STP (Spanning Tree Protocol)` **delay, in seconds, -for the bridge interface.** - -This parameter defines how long the bridge interface remains in the listening -and learning states before forwarding traffic. The delay ensures that the -bridge has sufficient time to detect loops (in the listening state) and learn -the MAC addresses of connected devices (in the learning state). - -The default value is 15 seconds. The total time before forwarding begins is -twice this value. -``` - -```{cfgcmd} set interfaces bridge \ hello-time \ - -**Configure the** {abbr}`STP (Spanning Tree Protocol)` **Hello advertisement -interval, in seconds.** - -This parameter sets the frequency at which the bridge interface transmits -Hello packets ({abbr}`BPDUs (Bridge Protocol Data Units)`). These packets -originate from the root bridge and are propagated by designated bridges. If -neighbors stop receiving Hello packets, they assume a connection failure and -trigger a topology recalculation. - -The default value is 2 seconds. -``` - - -### VLAN - -#### VLAN-aware bridges - -```{cfgcmd} set interfaces bridge \ enable-vlan - -**Enable VLAN filtering (also known as VLAN awareness) on the bridge interface.** - -When enabled, the bridge strictly segregates traffic among VLANs configured -on its member interfaces. - -:::{note} -Do not configure **vif 1** on a VLAN-aware bridge. The main bridge -interface acts as VLAN 1 (the default native VLAN) and automatically -handles all untagged traffic. -::: -``` - -```{cfgcmd} set interfaces bridge \ protocol \<802.1ad | 802.1q\> - -**Configure the VLAN protocol (EtherType) for the bridge interface.** - -The following options are available: -* ``802.1q`` (default): Sets the EtherType to ``0x8100``. Used for standard -enterprise VLANs. -* ``802.1ad``: Sets the EtherType to ``0x88a8``. Used for QinQ (provider bridging). -``` - - -#### VLAN configuration - -```{cmdincludemd} /_include/interface-vlan-8021q.txt -:var0: bridge -:var1: br0 -``` - -```{cfgcmd} set interfaces bridge \ member interface \ native-vlan \ - -**Configure the native VLAN ID for a specific member interface within a -VLAN-aware bridge.** - -This assigns the specified ```` to untagged traffic entering the member -interface. The bridge strips the VLAN tag from outgoing traffic matching this -ID. - -**Example:** - -Set the native VLAN ID to 2 for the member interface ``eth0``: - -:::{code-block} none -set interfaces bridge br1 member interface eth0 native-vlan 2 -::: -``` - -```{cfgcmd} set interfaces bridge \ member interface \ allowed-vlan \ - -**Configure allowed VLAN IDs for a specific member interface within a -VLAN-aware bridge.** - -Enter a single VLAN ID or a range of VLAN IDs separated by a hyphen. - -**Example:** - -To allow VLAN ID 4 on member interface ``eth0``: - -:::{code-block} none -set interfaces bridge br1 member interface eth0 allowed-vlan 4 -::: -**Example:** - -To allow VLAN IDs 6 through 8 on member interface ``eth0``: - -:::{code-block} none -set interfaces bridge br1 member interface eth0 allowed-vlan 6-8 -::: -``` - - -### SPAN port mirroring - -```{cmdincludemd} ../../_include/interface-mirror.txt -:var0: bridge -:var1: br1 -:var2: eth3 -``` - - -## Examples - -### Configure a standard bridge - -The following example creates a bridge named br100 with {abbr}`STP (Spanning -Tree Protocol)` enabled. - -Configuration requirements: -- **Bridge name:** `br100` -- **Member interfaces:** Physical interface `eth1` and VLAN interface `eth2.10`. -- **STP:** Enabled. -- **Bridge IP addresses:** `192.0.2.1/24` (IPv4) and `2001:db8::ffff/64` (IPv6). - -```none -set interfaces bridge br100 address 192.0.2.1/24 -set interfaces bridge br100 address 2001:db8::ffff/64 -set interfaces bridge br100 member interface eth1 -set interfaces bridge br100 member interface eth2.10 -set interfaces bridge br100 stp -``` - -Verify the configuration: - -```none -vyos@vyos# show interfaces bridge br100 - address 192.0.2.1/24 - address 2001:db8::ffff/64 - member { - interface eth1 { - } - interface eth2.10 { - } - } - stp -``` - - -### Configure a VLAN-aware bridge - -The following example creates a VLAN-aware bridge named br100. In this setup, -one member interface is configured as a trunk port, and the other as an access -port. The VLAN interface is configured with IP addresses. - -**Configuration requirements:** -- **Bridge name:** `br100`. -- **Trunk port** (`eth1`): Handles **tagged** traffic for VLAN 10. -- **Access port** (`eth2`): Handles **untagged** traffic (assigned to native - VLAN 10). -- **STP:** Enabled. -- **VLAN IP addresses** (`vif 10`): `192.0.2.1/24` (IPv4) and - `2001:db8::ffff/64` (IPv6). - -```none -set interfaces bridge br100 enable-vlan -set interfaces bridge br100 member interface eth1 allowed-vlan 10 -set interfaces bridge br100 member interface eth2 native-vlan 10 -set interfaces bridge br100 vif 10 address 192.0.2.1/24 -set interfaces bridge br100 vif 10 address 2001:db8::ffff/64 -set interfaces bridge br100 stp -``` - -Verify the configuration: - -```none -vyos@vyos# show interfaces bridge br100 - enable-vlan - member { - interface eth1 { - allowed-vlan 10 - } - interface eth2 { - native-vlan 10 - } - } - stp - vif 10 { - address 192.0.2.1/24 - address 2001:db8::ffff/64 - } -``` - - -### Operation - -```{opcmd} show bridge - -Show the status of member interfaces for all configured bridges. - -:::{code-block} none -vyos@vyos:~$ show bridge -3: eth1: mtu 1500 master br0 state forwarding -priority 32 cost 100 -4: eth2: mtu 1500 master br0 state forwarding -priority 32 cost 100 -::: -``` - -```{opcmd} show bridge \ fdb - -Show the {abbr}`FDB (Forwarding Database)` for the specified bridge. - -:::{code-block} none -vyos@vyos:~$ show bridge br0 fdb -50:00:00:08:00:01 dev eth1 vlan 20 master br0 permanent -50:00:00:08:00:01 dev eth1 vlan 10 master br0 permanent -50:00:00:08:00:01 dev eth1 master br0 permanent -33:33:00:00:00:01 dev eth1 self permanent -33:33:00:00:00:02 dev eth1 self permanent -01:00:5e:00:00:01 dev eth1 self permanent -50:00:00:08:00:02 dev eth2 vlan 20 master br0 permanent -50:00:00:08:00:02 dev eth2 vlan 10 master br0 permanent -50:00:00:08:00:02 dev eth2 master br0 permanent -33:33:00:00:00:01 dev eth2 self permanent -33:33:00:00:00:02 dev eth2 self permanent -01:00:5e:00:00:01 dev eth2 self permanent -33:33:00:00:00:01 dev br0 self permanent -33:33:00:00:00:02 dev br0 self permanent -33:33:ff:08:00:01 dev br0 self permanent -01:00:5e:00:00:6a dev br0 self permanent -33:33:00:00:00:6a dev br0 self permanent -01:00:5e:00:00:01 dev br0 self permanent -33:33:ff:00:00:00 dev br0 self permanent -::: -``` - -```{opcmd} show bridge \ mdb - -Show the {abbr}`MDB (Multicast group Database)` for the specified bridge. - -The {abbr}`MDB (Multicast group Database)` is populated by {abbr}`IGMP -(Internet Group Management Protocol)`/{abbr}`MLD (Multicast Listener -Discovery)` snooping and lists the multicast groups currently active on the -bridge. - -:::{code-block} none -vyos@vyos:~$ show bridge br0 mdb -dev br0 port br0 grp ff02::1:ff00:0 temp vid 1 -dev br0 port br0 grp ff02::2 temp vid 1 -dev br0 port br0 grp ff02::1:ff08:1 temp vid 1 -dev br0 port br0 grp ff02::6a temp vid 1 -::: -``` - -```{opcmd} show bridge \ macs - -Show the learned {abbr}`MAC (Media Access Control)` address table for the -specified bridge. - -:::{code-block} none -vyos@vyos:~$ show bridge br100 macs -port no mac addr is local? ageing timer - 1 00:53:29:44:3b:19 yes 0.00 -::: -``` \ No newline at end of file diff --git a/docs/configuration/interfaces/md-dummy.md b/docs/configuration/interfaces/md-dummy.md deleted file mode 100644 index d2d27c5d..00000000 --- a/docs/configuration/interfaces/md-dummy.md +++ /dev/null @@ -1,87 +0,0 @@ ---- -lastproofread: '2026-01-23' ---- - -(dummy-interface)= - -# Dummy - -A dummy interface is a virtual network interface that operates like the -loopback interface, accepting traffic and routing it back to the local host. -Unlike the loopback interface, which is limited to one per system and reserved -for internal system use, multiple dummy interfaces can be created, removed, and -managed without impacting core operations. - -As a software-based interface, the dummy interface does not depend on physical -link state and remains active as long as the operating system is running. - -Dummy interfaces are commonly used in environments with multiple redundant -uplinks (e.g., a server connected to two different switches), where assigning a -management IP address to a specific physical interface is risky. If that -interface fails, the management IP address becomes unreachable. - -Assigning the management IP address to a dummy interface and advertising it -over all available physical links ensures the address remains reachable as long -as at least one physical path is active. - -Dummy interfaces are also used for testing and simulation purposes. - -## Configuration - -### Common interface configuration - -```{cmdincludemd} /_include/interface-address.txt -:var0: dummy -:var1: dum0 -``` - -```{cmdincludemd} /_include/interface-description.txt -:var0: dummy -:var1: dum0 -``` - -```{cmdincludemd} /_include/interface-disable.txt -:var0: dummy -:var1: dum0 -``` - -```{cmdincludemd} /_include/interface-vrf.txt -:var0: dummy -:var1: dum0 -``` - - -## Operation - -```{opcmd} show interfaces dummy - -Show brief interface information. - -:::{code-block} none -vyos@vyos:~$ show interfaces dummy -Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down -Interface IP Address S/L Description ---------- ---------- --- ----------- -dum0 172.18.254.201/32 u/u -::: -``` - -```{opcmd} show interfaces dummy \ - -Show detailed interface information. - -:::{code-block} none -vyos@vyos:~$ show interfaces dummy dum0 -dum0: mtu 1500 qdisc noqueue state UNKNOWN group default qlen 1000 - link/ether 26:7c:8e:bc:fc:f5 brd ff:ff:ff:ff:ff:ff - inet 172.18.254.201/32 scope global dum0 - valid_lft forever preferred_lft forever - inet6 fe80::247c:8eff:febc:fcf5/64 scope link - valid_lft forever preferred_lft forever - - RX: bytes packets errors dropped overrun mcast - 0 0 0 0 0 0 - TX: bytes packets errors dropped carrier collisions - 1369707 4267 0 0 0 0 -::: -``` \ No newline at end of file diff --git a/docs/configuration/interfaces/md-ethernet.md b/docs/configuration/interfaces/md-ethernet.md deleted file mode 100644 index eac0b443..00000000 --- a/docs/configuration/interfaces/md-ethernet.md +++ /dev/null @@ -1,515 +0,0 @@ ---- -lastproofread: '2026-01-19' ---- - -(ethernet-interface)= - -# Ethernet - -Ethernet interfaces (e.g., `eth0`, `eth1`) represent the host's physical -or virtual network ports. - -They are the most common interface type, serving as the base layer upon which -IP addresses, VLANs, and tunnels are configured to carry traffic across both -LANs and WANs. - -## Configuration - -### Common interface configuration - -```{cmdincludemd} /_include/interface-common-with-dhcp.txt -:var0: ethernet -:var1: eth0 -``` - -```{cfgcmd} set interfaces ethernet \ switchdev - -**Enable** ``switchdev`` **mode for the interface.** - -In ``switchdev`` mode, the interface offloads traffic switching between ports -to the hardware, bypassing the host CPU. This increases the interface’s -traffic-handling capacity and reduces its forwarding delay. -``` - -:::{note} -`switchdev` mode is available only on certain physical network -interfaces and requires a switchdev-compatible driver. -::: - -### Ethernet options - -```{cfgcmd} set interfaces ethernet \ duplex \ - -**Configure duplex mode for the interface.** - -The following duplex modes are available: - -* ``auto``: The interface negotiates the duplex mode with the connected device. -* ``full``: The interface sends and receives data simultaneously. The - connected device must also be set to full-duplex to avoid a duplex mismatch. -* ``half``: The interface either sends or receives data, but not both at the - same time. - -The default duplex mode is ``auto``. -``` - -```{cfgcmd} set interfaces ethernet \ speed \ - -**Configure the interface's speed, in Mbit/s.** - -The following options are available: - -* ``auto``: The interface negotiates the speed with the connected device. -* ``10, 100, 1000 ...``: The interface operates at the selected speed. The - connected device must be set to the same speed to establish a connection. - -The default option is ``auto``. -``` - -```{cfgcmd} set interfaces ethernet \ ring-buffer rx \ - -**Configure the receive (RX) ring buffer size for the interface.** - -The RX ring buffer size defines the number of incoming packets the interface -can queue in hardware before the CPU processes them. - -Higher values reduce the risk of drops when the NIC receives network traffic -faster than the CPU can process it, though latency may increase. Lower values -reduce latency but increase the risk of packet drops during incoming traffic -bursts. - -To view supported values for a specific interface, use: -``` - -```none -ethtool -g -``` - -```{cfgcmd} set interfaces ethernet \ ring-buffer tx \ - -**Configure the transmit (TX) ring buffer size.** - -The TX ring buffer size defines the number of outgoing packets the interface -can queue in hardware before they are transmitted onto the network. - -Higher values reduce the risk of drops when the CPU generates traffic faster -than the NIC can handle, though latency may increase. Lower values reduce -latency but increase the risk of packet drops during outgoing traffic bursts. - -To view supported values for a specific interface, use: -``` - -```none -ethtool -g -``` - - -#### Interrupt Coalescing - -Interrupt coalescing is a mechanism that reduces CPU interrupt load by bundling -multiple packets into a single interrupt event instead of interrupting -the CPU for every packet arrival or transmission. - -:::{note} -Not all network drivers or virtual interfaces support all -coalescing parameters. Use `ethtool --show-coalesce ` -to verify which settings are supported by your hardware and driver. -::: - -**Basic adaptive coalescing** - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing adaptive-rx - -``` -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing adaptive-tx - -Enable adaptive interrupt coalescing. The NIC automatically tunes RX/TX -interrupt pacing based on traffic patterns to reduce CPU utilization -during high throughput while preserving latency at low packet rates. -``` - -**Basic interrupt delay** - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing rx-usecs \<0-16384\> -``` - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing tx-usecs \<0-16384\> - -Set the delay in microseconds before generating an RX/TX interrupt after -receiving or transmitting a packet. Lower values reduce latency; higher -values reduce CPU load. -``` - -**Interrupt frame thresholds** - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing rx-frames \ -``` - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing tx-frames \ - -Generate an RX/TX interrupt only after the specified number of packets -have been received or transmitted. -``` - -**IRQ-specific coalescing** - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing rx-usecs-irq \ -``` - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing rx-frames-irq \ -``` - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing tx-usecs-irq \ -``` - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing tx-frames-irq \ - -Control interrupt coalescing parameters while the driver is already -servicing an interrupt (IRQ context). These settings allow finer tuning -of interrupt behavior under sustained load. -``` - -**Adaptive rate thresholds** - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing pkt-rate-low \ -``` - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing pkt-rate-high \ - -Define packet-rate thresholds (packets per second) used by adaptive -coalescing to switch between low-rate and high-rate interrupt coalescing -profiles. -``` - -**Low-rate adaptive parameters** - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing rx-usecs-low \ -``` - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing rx-frame-low \ -``` - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing tx-usecs-low \ -``` - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing tx-frame-low \ - -Interrupt coalescing parameters applied when the packet rate is below -``pkt-rate-low``. Typically optimized for lower latency. -``` - -**High-rate adaptive parameters** - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing rx-usecs-high \ -``` - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing rx-frame-high \ -``` - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing tx-usecs-high \ -``` - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing tx-frame-high \ - -Interrupt coalescing parameters applied when the packet rate exceeds -``pkt-rate-high``. Typically optimized for maximum throughput and -reduced CPU utilization. -``` - -**Statistics and sampling** - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing stats-block-usecs \ -``` - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing sample-interval \ - -Control how frequently coalescing statistics are updated and how often -the NIC samples traffic rates for adaptive coalescing decisions. -``` - -**Completion queue (CQE) mode** - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing cqe-mode-rx -``` - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing cqe-mode-tx - -Enable RX/TX Completion Queue Entry (CQE) mode, if supported by the -driver. CQE mode can improve performance on high-speed NICs by -optimizing completion handling. -``` - -**Transmit aggregation** - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing tx-aggr-max-bytes \ -``` - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing tx-aggr-max-frames \ -``` - -```{cfgcmd} set interfaces ethernet \ interrupt-coalescing tx-aggr-time-usecs \ - -Control transmit packet aggregation. Packets may be buffered and sent -together until one of the configured limits (bytes, frames, or time) -is reached, reducing interrupt and DMA overhead. -``` - -#### Offloading - -```{cfgcmd} set interfaces ethernet \ offload \ - -**Configure the offloading features for the interface.** - -The interface offloading features define whether specific packet-processing tasks -are performed by hardware (the NIC) or by software (the kernel). You can enable -multiple offloading features for a single interface. - - * ``lro`` **(Large Receive Offload):** Instructs the NIC to merge multiple - incoming packets into one larger packet before sending it to the CPU. - - :::{note} - {abbr}`LRO (Large Receive Offload)` hardware support is often limited - to TCP/IPv4 packets. For details on LRO limitations, see - https://lwn.net/Articles/358910/ - ::: - :::{warning} - {abbr}`LRO (Large Receive Offload)` irreversibly alters packet - headers during merging. This prevents the merged packet from being correctly - split back into the original packets, causing packet drops and forwarding - failures on routers and bridges. Use {abbr}`LRO (Large Receive Offload)` only - for end-hosts that do not forward traffic. - ::: - * ``tso`` **(TCP Segmentation Offload):** Instructs the NIC to split large TCP - packets into smaller ones before transmitting them to the network. - - **Important:** {abbr}`SG (Scatter-Gather/Scatter-Gather DMA)` must be enabled - for {abbr}`TSO (TCP Segmentation Offload)` to work. Additionally, {abbr}`GSO - (Generic Segmentation Offload)` should be enabled as a safety fallback; it - ensures that if traffic is rerouted to hardware without {abbr}`TSO (TCP - Segmentation Offload)` support, the kernel can still segment the packets, - preventing transmission failures. - - * ``gso`` **(Generic Segmentation Offload):** Instructs the kernel to split - large packets into smaller ones before sending them to the NIC. - - {abbr}`GSO (Generic Segmentation Offload)` serves as a software fallback for - hardware that does not support {abbr}`TSO (TCP Segmentation Offload)` or for - protocols (like UDP) that hardware cannot offload. - - **Important:** {abbr}`SG (Scatter-Gather/Scatter-Gather DMA)` must be enabled - for {abbr}`GSO (Generic Segmentation Offload)` to work. - - * ``gro`` **(Generic Receive Offload):** Instructs the kernel to merge multiple - incoming packets into one larger packet before passing it to upper protocol - layers. - - Unlike LRO, GRO preserves the necessary packet metadata so the merged packet - can be correctly split back into the original packets. This makes GRO safe for - use on routers and bridges. - - :::{note} -The exception is for IPv4 IDs. If the "Don't Fragment" (DF) bit is -set and IDs are not sequential, {abbr}`GSO (Generic Segmentation Offload)` -alters them to maintain a consistent sequence for {abbr}`GSO (Generic -Segmentation Offload)` compatibility. - ::: - * ``rps`` **(Receive Packet Steering):** Instructs the kernel to distribute - the processing of incoming packets across multiple CPU cores. - - The kernel calculates a hash from packet headers (IP addresses and ports) to - ensure packets from the same flow are processed by the same CPU core. - - :::{note} -{abbr}`RPS (Receive Packet Steering)` is a software version of -{abbr}`RSS (Receive Side Scaling)` and is useful for NICs without hardware -multi-queue support. - ::: - * ``sg`` **(Scatter-Gather/Scatter-Gather DMA):** Instructs the NIC to fetch - data fragments from various RAM locations and transmit them as a single packet - to the network, eliminating the need for the kernel to copy them into a - contiguous block first. -``` - -#### 802.1X (EAPOL) authentication - -```{cmdincludemd} /_include/interface-eapol.txt -:var0: ethernet -:var1: eth0 -``` - -#### EVPN Multihoming - -Uplink/core tracking. - -```{cmdincludemd} /_include/interface-evpn-uplink.txt -:var0: ethernet -:var1: eth0 -``` - -### VLAN -#### Regular VLANs (802.1q) - -```{cmdincludemd} /_include/interface-vlan-8021q.txt -:var0: ethernet -:var1: eth0 -``` - -#### 802.1ad (QinQ) - -```{cmdincludemd} /_include/interface-vlan-8021ad.txt -:var0: ethernet -:var1: eth0 -``` - -### SPAN port mirroring - -```{cmdincludemd} ../../_include/interface-mirror.txt -:var0: ethernet -:var1: eth1 -:var2: eth3 -``` - -## Operation - -```{opcmd} show interfaces ethernet - -Show brief interface information. - -:::{code-block} none -vyos@vyos:~$ show interfaces ethernet -Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down -Interface IP Address S/L Description ---------- ---------- --- ----------- -eth0 172.18.201.10/24 u/u LAN -eth1 172.18.202.11/24 u/u WAN -eth2 - u/D -::: -``` - -```{opcmd} show interfaces ethernet \ - -Show detailed interface information. - -:::{code-block} none -vyos@vyos:~$ show interfaces ethernet eth0 -eth0: mtu 1500 qdisc pfifo_fast state UP group default qlen 1000 - link/ether 00:50:44:00:f5:c9 brd ff:ff:ff:ff:ff:ff - inet6 fe80::250:44ff:fe00:f5c9/64 scope link - valid_lft forever preferred_lft forever - - RX: bytes packets errors dropped overrun mcast - 56735451 179841 0 0 0 142380 - TX: bytes packets errors dropped carrier collisions - 5601460 62595 0 0 0 0 -::: -``` - -```{opcmd} show interfaces ethernet \ physical - -Show interface hardware-level and driver details. - -:::{code-block} none -vyos@vyos:~$ show interfaces ethernet eth0 physical -Settings for eth0: - Supported ports: [ TP ] - Supported link modes: 1000baseT/Full - 10000baseT/Full - Supported pause frame use: No - Supports auto-negotiation: No - Supported FEC modes: Not reported - Advertised link modes: Not reported - Advertised pause frame use: No - Advertised auto-negotiation: No - Advertised FEC modes: Not reported - Speed: 10000Mb/s - Duplex: Full - Port: Twisted Pair - PHYAD: 0 - Transceiver: internal - Auto-negotiation: off - MDI-X: Unknown - Supports Wake-on: uag - Wake-on: d - Link detected: yes -driver: vmxnet3 -version: 1.4.16.0-k-NAPI -firmware-version: -expansion-rom-version: -bus-info: 0000:0b:00.0 -supports-statistics: yes -supports-test: no -supports-eeprom-access: no -supports-register-dump: yes -supports-priv-flags: no -::: -``` - -```{opcmd} show interfaces ethernet \ physical offload - -Show the status of the interface offloading features. - -:::{code-block} none -vyos@vyos:~$ show interfaces ethernet eth0 physical offload -rx-checksumming on -tx-checksumming on -tx-checksum-ip-generic on -scatter-gather off -tx-scatter-gather off -tcp-segmentation-offload off -tx-tcp-segmentation off -tx-tcp-mangleid-segmentation off -tx-tcp6-segmentation off -udp-fragmentation-offload off -generic-segmentation-offload off -generic-receive-offload off -large-receive-offload off -rx-vlan-offload on -tx-vlan-offload on -ntuple-filters off -receive-hashing on -tx-gre-segmentation on -tx-gre-csum-segmentation on -tx-udp_tnl-segmentation on -tx-udp_tnl-csum-segmentation on -tx-gso-partial on -tx-nocache-copy off -rx-all off -::: -``` - -```{opcmd} show interfaces ethernet \ transceiver - -Show information about the transceiver module plugged into the interface -(e.g., SFP+, QSFP). - -:::{code-block} none -vyos@vyos:~$ show interfaces ethernet eth5 transceiver - Identifier : 0x03 (SFP) - Extended identifier : 0x04 (GBIC/SFP defined by 2-wire interface ID) - Connector : 0x07 (LC) - Transceiver codes : 0x00 0x00 0x00 0x01 0x00 0x00 0x00 0x00 0x00 - Transceiver type : Ethernet: 1000BASE-SX - Encoding : 0x01 (8B/10B) - BR, Nominal : 1300MBd - Rate identifier : 0x00 (unspecified) - Length (SMF,km) : 0km - Length (SMF) : 0m - Length (50um) : 550m - Length (62.5um) : 270m - Length (Copper) : 0m - Length (OM3) : 0m - Laser wavelength : 850nm - Vendor name : CISCO-FINISAR - Vendor OUI : 00:90:65 - Vendor PN : FTRJ-8519-7D-CS4 - Vendor rev : A - Option values : 0x00 0x1a - Option : RX_LOS implemented - Option : TX_FAULT implemented - Option : TX_DISABLE implemented - BR margin, max : 0% - BR margin, min : 0% - Vendor SN : FNS092xxxxx - Date code : 0506xx -::: -``` \ No newline at end of file diff --git a/docs/configuration/interfaces/md-geneve.md b/docs/configuration/interfaces/md-geneve.md deleted file mode 100644 index 1fce1119..00000000 --- a/docs/configuration/interfaces/md-geneve.md +++ /dev/null @@ -1,105 +0,0 @@ ---- -lastproofread: '2026-02-02' ---- - -(geneve-interface)= - -# Geneve - -{abbr}`Geneve (Generic Network Virtualization Encapsulation)` interfaces -operate as virtual network ports. Administrators can apply standard network -configurations on them, such as IP addressing, bridging, or firewall rules, -just as they would on physical Ethernet ports. - -The Geneve protocol encapsulates Layer 2 Ethernet frames originating from -endpoints such as virtual machines, containers, or physical servers inside UDP -packets. It unifies the features of earlier encapsulation protocols, including -VXLAN, NVGRE, and STT, and addresses their limitations, such as fixed header -structures and a lack of metadata support. Because of its extensibility, Geneve -may eventually replace those older protocols. - -Geneve tunnels are used to connect virtual switches residing within -hypervisors, physical switches, middleboxes, and other network appliances. - -Geneve tunnels operate over any standard IP network. In larger deployments, -the underlying network (underlay) is often built using a **Clos** topology, -also known as a *leaf-and-spine* or *fat-tree* topology. - -Geneve header: - -```none -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -|Ver| Opt Len |O|C| Rsvd. | Protocol Type | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Virtual Network Identifier (VNI) | Reserved | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Variable Length Options | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -``` - - -## Configuration - -### Common interface configuration - -```{cmdincludemd} /_include/interface-address.txt -:var0: geneve -:var1: gnv0 -``` - -```{cmdincludemd} /_include/interface-description.txt -:var0: geneve -:var1: gnv0 -``` - -```{cmdincludemd} /_include/interface-disable.txt -:var0: geneve -:var1: gnv0 -``` - -```{cmdincludemd} /_include/interface-mac.txt -:var0: geneve -:var1: gnv0 -``` - -```{cmdincludemd} /_include/interface-mtu.txt -:var0: geneve -:var1: gnv0 -``` - -```{cmdincludemd} /_include/interface-ip.txt -:var0: geneve -:var1: gnv0 -``` - -```{cmdincludemd} /_include/interface-ipv6.txt -:var0: geneve -:var1: gnv0 -``` - - -### Geneve options - -```{cfgcmd} set interfaces geneve gnv0 remote \ - -Configure the remote endpoint IP address for the Geneve tunnel. -``` - -```{cfgcmd} set interfaces geneve gnv0 vni \ - -**Configure** {abbr}`VNI (Virtual Network Identifier)` **for the Geneve -interface.** - -The VNI is a virtual network identifier. It allows multiple virtual networks to -share the same physical infrastructure and remain isolated. - -The VNI is also used to distribute traffic after it leaves the tunnel, for -example, to map packets with overlapping IP addresses to specific routing -tables. -``` - -```{cfgcmd} set interfaces gnv0 \ port \ - -**Configure the destination UDP port for the remote Geneve tunnel endpoint.** -Ensure the remote peer is configured to listen on this specific port. -``` \ No newline at end of file diff --git a/docs/configuration/interfaces/md-index.md b/docs/configuration/interfaces/md-index.md deleted file mode 100644 index 9082cd80..00000000 --- a/docs/configuration/interfaces/md-index.md +++ /dev/null @@ -1,26 +0,0 @@ -# Interfaces - -```{toctree} -:includehidden: true -:maxdepth: 1 - -bonding -bridge -dummy -ethernet -geneve -l2tpv3 -loopback -macsec -openvpn -wireguard -pppoe -pseudo-ethernet -sstp-client -tunnel -virtual-ethernet -vti -vxlan -wireless -wwan -``` diff --git a/docs/configuration/interfaces/md-l2tpv3.md b/docs/configuration/interfaces/md-l2tpv3.md deleted file mode 100644 index 324840fa..00000000 --- a/docs/configuration/interfaces/md-l2tpv3.md +++ /dev/null @@ -1,170 +0,0 @@ ---- -lastproofread: '2026-02-05' ---- - -(l2tpv3-interface)= - -# L2TPv3 - -{abbr}`L2TPv3 (Layer 2 Tunneling Protocol version 3)` interfaces let you -establish L2TPv3 tunnels to transport Layer 2 traffic over IP networks. - -The L2TPv3 protocol (defined in RFC 3931) wraps Layer 2 frames (e.g., Ethernet, -Frame Relay, HDLC) within IP packets, allowing them to traverse the underlying -IP infrastructure. - -Unlike L2TPv2, which strictly requires UDP encapsulation, the L2TPv3 protocol -is more flexible and supports two encapsulation types: - -> - **Direct IP:** Tunnel data is encapsulated directly inside IP packets -> (Protocol 115) for lower overhead. -> - **UDP:** Tunnel data is encapsulated inside a UDP datagram. This allows the -> tunnel to traverse NAT more easily. - -L2TPv3 tunnels connect geographically separated sites, serving as a simpler -alternative to {ref}`mpls` by operating over basic IP connectivity rather than -requiring a full MPLS infrastructure. - -L2TPv3 tunnels can be established over both IPv4 and IPv6 underlying networks. - -## Configuration - -### Common interface configuration - -```{cmdincludemd} /_include/interface-common-without-dhcp.txt -:var0: l2tpv3 -:var1: l2tpeth0 -``` - - -### L2TPv3 options - -Use the following commands to configure the L2TPv3 tunnel's specific parameters. - -```{cfgcmd} set interfaces l2tpv3 \ encapsulation \ - -**Configure the encapsulation type for the L2TPv3 tunnel.** - -Valid values are ``udp`` and ``ip``. - -The default encapsulation type is ``udp``. -``` - -:::{note} -The encapsulation type must match on both the local and remote peers -for the tunnel to establish. -::: - -```{cfgcmd} set interfaces l2tpv3 \ source-address \ - -**Configure the L2TPv3 tunnel source IP address.** - -The specified address must be a local interface IP address and can be either -IPv4 or IPv6. -``` - -```{cfgcmd} set interfaces l2tpv3 \ remote \ - -**Configure the L2TPv3 tunnel destination IP address.** - -The specified address must be a remote peer’s interface IP address and can be -either IPv4 or IPv6. -``` - -```{cfgcmd} set interfaces l2tpv3 \ session-id \ - -**Configure the local session ID within the L2TPv3 tunnel.** - -The ``session-id`` is a 32-bit value that identifies an incoming tunnel session -on the local peer. - -The ``peer-session-id`` that identifies this session on the remote peer must be -set to the same value. -``` - -```{cfgcmd} set interfaces l2tpv3 \ peer-session-id \ - -**Configure the peer session ID within the L2TPv3 tunnel.** - -The ``peer-session-id`` is a 32-bit value that identifies an outgoing tunnel -session from the local peer. - -The ``peer-session-id`` must match the ``session-id`` configured for this -session on the remote peer. -``` - -```{cfgcmd} set interfaces l2tpv3 \ tunnel-id \ - -**Configure the local identifier for the L2TPv3 tunnel.** - -The ``tunnel-id`` is a 32-bit value that identifies the L2TPv3 tunnel on the -local peer. - -The ``peer-tunnel-id`` that identifies this tunnel on the remote peer must be -set to the same value. -``` - -```{cfgcmd} set interfaces l2tpv3 \ peer-tunnel-id \ - -**Configure the peer identifier for the L2TPv3 tunnel.** - -The ``peer-tunnel-id`` is a 32-bit value that identifies the L2TPv3 tunnel on -the remote peer and must correspond to the ``tunnel-id`` configured for that -tunnel on that peer. - -The ``peer-tunnel-id`` must match the ``tunnel-id`` that identifies this tunnel -on the remote peer. -``` - - -## Example - -### L2TPv3 tunnel with IP encapsulation - -The following example shows the configuration of an L2TPv3 tunnel using direct -IP encapsulation: - -```none -# show interfaces l2tpv3 -l2tpv3 l2tpeth10 { - address 192.168.37.1/27 - encapsulation ip - source-address 192.0.2.1 - peer-session-id 100 - peer-tunnel-id 200 - remote 203.0.113.24 - session-id 100 - tunnel-id 200 -} -``` - -The inverse configuration must be applied to the remote peer. - -### L2TPv3 tunnel with UDP encapsulation - -The following example shows the configuration of an L2TPv3 tunnel using UDP -encapsulation. - -This setup is recommended when the tunnel traverses NAT devices. - -Configuration notes: -- Use a local LAN IP address as the `source-address`. -- Configure a forwarding rule to allow tunnel traffic on the specified UDP port - on the upstream NAT device. -- Use a distinct UDP port for each individual tunnel. - -```none -# show interfaces l2tpv3 -l2tpv3 l2tpeth10 { - address 192.168.37.1/27 - destination-port 9001 - encapsulation udp - source-address 192.0.2.1 - peer-session-id 100 - peer-tunnel-id 200 - remote 203.0.113.24 - session-id 100 - source-port 9000 - tunnel-id 200 -} -``` diff --git a/docs/configuration/interfaces/md-loopback.md b/docs/configuration/interfaces/md-loopback.md deleted file mode 100644 index 72f14c16..00000000 --- a/docs/configuration/interfaces/md-loopback.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -lastproofread: '2026-01-23' ---- - -(loopback-interface)= - -# Loopback - -The loopback interface is a virtual, software-based network interface. All -traffic sent to it loops back and only targets services on the local host. - -:::{note} -Only one loopback `lo` interface is allowed per operating system. -If you require multiple virtual interfaces, use the {ref}`dummy-interface` -interface type. -::: - -## Configuration - -### Common interface configuration - -```{cmdincludemd} /_include/interface-address.txt -:var0: loopback -:var1: lo -``` - -```{cmdincludemd} /_include/interface-description.txt -:var0: loopback -:var1: lo -``` - - -## Operation - -```{opcmd} show interfaces loopback - -Show brief interface information. - -:::{code-block} none -vyos@vyos:~$ show interfaces loopback -Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down -Interface IP Address S/L Description ---------- ---------- --- ----------- -lo 127.0.0.1/8 u/u - ::1/128 -::: -``` - -```{opcmd} show interfaces loopback lo - -Show detailed interface information. - -:::{code-block} none -vyos@vyos:~$ show interfaces loopback lo -lo: mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1000 - link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00 - inet 127.0.0.1/8 scope host lo - valid_lft forever preferred_lft forever - inet6 ::1/128 scope host - valid_lft forever preferred_lft forever - - RX: bytes packets errors dropped overrun mcast - 300 6 0 0 0 0 - TX: bytes packets errors dropped carrier collisions - 300 6 0 0 0 0 -::: -``` \ No newline at end of file diff --git a/docs/configuration/interfaces/md-macsec.md b/docs/configuration/interfaces/md-macsec.md deleted file mode 100644 index b3c70362..00000000 --- a/docs/configuration/interfaces/md-macsec.md +++ /dev/null @@ -1,319 +0,0 @@ ---- -lastproofread: '2026-02-13' ---- - -(macsec-interface)= - -# MACsec - -MACsec is an IEEE standard (IEEE 802.1AE) for MAC security, introduced in -2006\. It enables protocol-independent connectivity between two hosts, providing -data confidentiality, authenticity, and integrity using GCM-AES ciphers. MACsec -operates at the Ethernet layer as a Layer 2 protocol and secures traffic within -Layer 2 networks, including DHCP and ARP requests. It does not compete with -other security solutions, such as IPsec (Layer 3) or TLS (Layer 4), as each -addresses distinct use cases. - -## Configuration - -### Common interface configuration - -```{cmdincludemd} /_include/interface-common-with-dhcp.txt -:var0: macsec -:var1: macsec0 -``` - - -### MACsec options - -```{cfgcmd} set interfaces macsec \ security cipher \ - -**Configure the cipher suite for the MACsec interface.** - -This configuration parameter is mandatory. -``` - -```{cfgcmd} set interfaces macsec \ security encrypt - -**Enable encryption on the MACsec interface.** - -By default, MACsec interfaces only provide authentication; encryption is -optional. -When enabled, outgoing packets are encrypted using the configured cipher suite. -``` - -```{cfgcmd} set interfaces macsec \ source-interface \ - -**Configure a physical source interface for the MACsec interface.** - -Traffic transmitted through this interface is authenticated and, if configured, -encrypted. -``` - - -#### MACsec key management - -**Static** {abbr}`SAK (Secure Authentication Key)` **mode** - -In static SAK mode, administrators must manually configure and update SAKs on -each MACsec peer. {abbr}`MKA (MACsec Key Agreement protocol)` cannot be used in -this mode. - -```{cfgcmd} set interfaces macsec \ security static key \ - -**Configure the Transmit (TX) SAK for the MACsec interface.** - -The key must be a 16-byte (GCM-AES-128) or 64-byte (GCM-AES-256) hexadecimal -string. -``` - -```{cfgcmd} set interfaces macsec \ security static peer \ mac \ - -**Configure the MAC address associated with the MACsec peer.** -``` - -```{cfgcmd} set interfaces macsec \ security static peer \ key \ - -**Configure the RX SAK for traffic from the MACsec peer.** - -The key must be a 16-byte (GCM-AES-128) or 64-byte (GCM-AES-256) hexadecimal -string. -``` - -```{cfgcmd} set interfaces macsec \ security static peer \ disable -``` - -**Dynamic** {abbr}`MKA (MACsec Key Agreement protocol)` **mode** - -In this mode, the {abbr}`MKA (MACsec Key Agreement protocol)` protocol is used -to generate, distribute, and update {abbr}`CAKs (MACsec Connectivity -Association Keys)`, and to authenticate MACsec peers. - -```{cfgcmd} set interfaces macsec \ security mka cak \ - -**Configure the** {abbr}`CAK (MACsec Connectivity Association Key)` **for the -MACsec interface.** - -The {abbr}`CAK (MACsec Connectivity Association Key)` and its {abbr}`CKN -(MACsec Connectivity Association Key Name)` form the pre-shared master key pair -used to authenticate MACsec peers. -``` - -```{cfgcmd} set interfaces macsec \ security mka ckn \ - -Configure the {abbr}`CKN (MACsec Connectivity Association Key Name)` for the -MACsec interface. -``` - -```{cfgcmd} set interfaces macsec \ security mka priority \ - -Configure the MKA key server priority for the MACsec interface. -The peer with the lowest priority is elected as the key server. -``` - -#### Replay protection - -```{cfgcmd} set interfaces macsec \ security replay-window \ - -The replay protection window defines how many out-of-order frames can be -received before they are dropped as a potential replay attack. -The following values are valid: -- ``0``: Any out-of-order frame is immediately dropped. -- ``1-4294967295``: Allows the specified number of out-of-order frames. -``` - -## Operation - -```{opcmd} run generate macsec mka cak \ - -Generate a 128-bit (GCM-AES-128) or 256-bit (GCM-AES-256) {abbr}`MKA (MACsec -Key Agreement protocol)` {abbr}`CAK (MACsec Connectivity Association Key)`. - -:::{code-block} none -vyos@vyos:~$ generate macsec mka cak gcm-aes-128 -20693b6e08bfa482703a563898c9e3ad -::: -``` - -```{opcmd} run generate macsec mka ckn - -Generate an {abbr}`MKA (MACsec Key Agreement protocol)` {abbr}`CAK (MACsec -Connectivity Association Key)`. - -:::{code-block} none -vyos@vyos:~$ generate macsec mka ckn -88737efef314ee319b2cbf30210a5f164957d884672c143aefdc0f5f6bc49eb2 -::: -``` - -```{opcmd} show interfaces macsec - -Show all MACsec interfaces. - -:::{code-block} none -vyos@vyos:~$ show interfaces macsec -17: macsec1: protect on validate strict sc off sa off encrypt on send_sci on end_station off scb off replay off -cipher suite: GCM-AES-128, using ICV length 16 -TXSC: 005056bfefaa0001 on SA 0 -20: macsec0: protect on validate strict sc off sa off encrypt off send_sci on end_station off scb off replay off -cipher suite: GCM-AES-128, using ICV length 16 -TXSC: 005056bfefaa0001 on SA 0 -::: -``` - -```{opcmd} show interfaces macsec \ - -Show information for a specific MACsec interface. - -:::{code-block} none -vyos@vyos:~$ show interfaces macsec macsec1 -17: macsec1: protect on validate strict sc off sa off encrypt on send_sci on end_station off scb off replay off -cipher suite: GCM-AES-128, using ICV length 16 -TXSC: 005056bfefaa0001 on SA 0 -::: -``` - -## Examples - -**Site-to-site MACsec with dynamic MKA over an untrusted network** - -In the following example, two routers (R1 and R2) are connected via an -untrusted switch, using their `eth1` interfaces as the underlay. The MACsec -interface (`macsec1`) with dynamic MKA encrypts traffic between them. - -Topology details: -- R1 IP addresses: `192.0.2.1/24` and `2001:db8::1/64`. -- R2 IP addresses: `192.0.2.2/24` and `2001:db8::2/64`. - -**R1** - -```none -set interfaces macsec macsec1 address '192.0.2.1/24' -set interfaces macsec macsec1 address '2001:db8::1/64' -set interfaces macsec macsec1 security cipher 'gcm-aes-128' -set interfaces macsec macsec1 security encrypt -set interfaces macsec macsec1 security mka cak '232e44b7fda6f8e2d88a07bf78a7aff4' -set interfaces macsec macsec1 security mka ckn '40916f4b23e3d548ad27eedd2d10c6f98c2d21684699647d63d41b500dfe8836' -set interfaces macsec macsec1 source-interface 'eth1' -``` - -**R2** - -```none -set interfaces macsec macsec1 address '192.0.2.2/24' -set interfaces macsec macsec1 address '2001:db8::2/64' -set interfaces macsec macsec1 security cipher 'gcm-aes-128' -set interfaces macsec macsec1 security encrypt -set interfaces macsec macsec1 security mka cak '232e44b7fda6f8e2d88a07bf78a7aff4' -set interfaces macsec macsec1 security mka ckn '40916f4b23e3d548ad27eedd2d10c6f98c2d21684699647d63d41b500dfe8836' -set interfaces macsec macsec1 source-interface 'eth1' -``` - -Pinging (IPv6) the other host and intercepting traffic on `eth1` confirm that -the content is encrypted. - -```none -17:35:44.586668 00:50:56:bf:ef:aa > 00:50:56:b3:ad:d6, ethertype Unknown (0x88e5), length 150: - 0x0000: 2c00 0000 000a 0050 56bf efaa 0001 d9fb ,......PV....... - 0x0010: 920a 8b8d 68ed 9609 29dd e767 25a4 4466 ....h...)..g%.Df - 0x0020: 5293 487b 9990 8517 3b15 22c7 ea5c ac83 R.H{....;."..\.. - 0x0030: 4c6e 13cf 0743 f917 2c4e 694e 87d1 0f09 Ln...C..,NiN.... - 0x0040: 0f77 5d53 ed75 cfe1 54df 0e5a c766 93cb .w]S.u..T..Z.f.. - 0x0050: c4f2 6e23 f200 6dfe 3216 c858 dcaa a73b ..n#..m.2..X...; - 0x0060: 4dd1 9358 d9e4 ed0e 072f 1acc 31c4 f669 M..X...../..1..i - 0x0070: e93a 9f38 8a62 17c6 2857 6ac5 ec11 8b0e .:.8.b..(Wj..... - 0x0080: 6b30 92a5 7ccc 720b k0..|.r. -``` - -Disabling encryption on the MACsec interface by removing the `security -encrypt` option shows the unencrypted but authenticated content. - -```none -17:37:00.746155 00:50:56:bf:ef:aa > 00:50:56:b3:ad:d6, ethertype Unknown (0x88e5), length 150: - 0x0000: 2000 0000 0009 0050 56bf efaa 0001 86dd .......PV....... - 0x0010: 6009 86f3 0040 3a40 2001 0db8 0000 0000 `....@:@........ - 0x0020: 0000 0000 0000 0001 2001 0db8 0000 0000 ................ - 0x0030: 0000 0000 0000 0002 8100 d977 0f30 0003 ...........w.0.. - 0x0040: 1ca0 c65e 0000 0000 8d93 0b00 0000 0000 ...^............ - 0x0050: 1011 1213 1415 1617 1819 1a1b 1c1d 1e1f ................ - 0x0060: 2021 2223 2425 2627 2829 2a2b 2c2d 2e2f .!"#$%&'()*+,-./ - 0x0070: 3031 3233 3435 3637 87d5 eed3 3a39 d52b 01234567....:9.+ - 0x0080: a282 c842 5254 ef28 ...BRT.( -``` - -**Site-to-site MACsec with static SAK over an untrusted network** - -This example uses the same topology as above, but applies static SAK mode to -the MACsec interface configuration. - -**R1** - -```none -set interfaces macsec macsec1 address '192.0.2.1/24' -set interfaces macsec macsec1 address '2001:db8::1/64' -set interfaces macsec macsec1 security cipher 'gcm-aes-128' -set interfaces macsec macsec1 security encrypt -set interfaces macsec macsec1 security static key 'ddd6f4a7be4d8bbaf88b26f10e1c05f7' -set interfaces macsec macsec1 security static peer R2 mac 00:11:22:33:44:02 -set interfaces macsec macsec1 security static peer R2 key 'eadcc0aa9cf203f3ce651b332bd6e6c7' -set interfaces macsec macsec1 source-interface 'eth1' -``` - -**R2** - -```none -set interfaces macsec macsec1 address '192.0.2.2/24' -set interfaces macsec macsec1 address '2001:db8::2/64' -set interfaces macsec macsec1 security cipher 'gcm-aes-128' -set interfaces macsec macsec1 security encrypt -set interfaces macsec macsec1 security static key 'eadcc0aa9cf203f3ce651b332bd6e6c7' -set interfaces macsec macsec1 security static peer R1 mac 00:11:22:33:44:01 -set interfaces macsec macsec1 security static peer R1 key 'ddd6f4a7be4d8bbaf88b26f10e1c05f7' -set interfaces macsec macsec1 source-interface 'eth1' -``` - -## MACsec over WAN - -MACsec offers an alternative to traditional tunneling solutions by securing -Layer 2 with integrity, origin authentication, and optional encryption. - -While typically deployed between hosts and access switches, MACsec can also -secure traffic over a WAN. In the following example, we combine VXLAN (for -transport) and MACsec (for security) to create a secure tunnel between two -sites. - -**R1 MACsec01** - -```none -set interfaces macsec macsec1 address '192.0.2.1/24' -set interfaces macsec macsec1 address '2001:db8::1/64' -set interfaces macsec macsec1 security cipher 'gcm-aes-128' -set interfaces macsec macsec1 security encrypt -set interfaces macsec macsec1 security static key 'ddd6f4a7be4d8bbaf88b26f10e1c05f7' -set interfaces macsec macsec1 security static peer SEC02 key 'eadcc0aa9cf203f3ce651b332bd6e6c7' -set interfaces macsec macsec1 security static peer SEC02 mac '00:11:22:33:44:02' -set interfaces macsec macsec1 source-interface 'vxlan1' -set interfaces vxlan vxlan1 mac '00:11:22:33:44:01' -set interfaces vxlan vxlan1 remote '10.1.3.3' -set interfaces vxlan vxlan1 source-address '172.16.100.1' -set interfaces vxlan vxlan1 vni '10' -set protocols static route 10.1.3.3/32 next-hop 172.16.100.2 -``` - -**R2 MACsec02** - -```none -set interfaces macsec macsec1 address '192.0.2.2/24' -set interfaces macsec macsec1 address '2001:db8::2/64' -set interfaces macsec macsec1 security cipher 'gcm-aes-128' -set interfaces macsec macsec1 security encrypt -set interfaces macsec macsec1 security static key 'eadcc0aa9cf203f3ce651b332bd6e6c7' -set interfaces macsec macsec1 security static peer SEC01 key 'ddd6f4a7be4d8bbaf88b26f10e1c05f7' -set interfaces macsec macsec1 security static peer SEC01 mac '00:11:22:33:44:01' -set interfaces macsec macsec1 source-interface 'vxlan1' -set interfaces vxlan vxlan1 mac '00:11:22:33:44:02' -set interfaces vxlan vxlan1 remote '10.1.2.2' -set interfaces vxlan vxlan1 source-address '172.16.100.2' -set interfaces vxlan vxlan1 vni '10' -set protocols static route 10.1.2.2/32 next-hop 172.16.100.1 -``` diff --git a/docs/configuration/interfaces/md-openvpn-examples.md b/docs/configuration/interfaces/md-openvpn-examples.md deleted file mode 100644 index 817e6868..00000000 --- a/docs/configuration/interfaces/md-openvpn-examples.md +++ /dev/null @@ -1,769 +0,0 @@ -# Site-to-site - -:::{todo} -Convert raw command blocks in this file to cfgcmd/opcmd directives for command coverage tracking. -::: - -OpenVPN is popular for client-server setups, but its site-to-site mode is less common and often not supported by router appliances. Despite limited support, it is effective for quickly establishing tunnels between routers. - -As of VyOS 1.4, OpenVPN site-to-site mode can use either pre-shared keys or x.509 certificates. - -Pre-shared key mode is now deprecated and will be removed from future OpenVPN versions. VyOS will also discontinue support for this option because pre-shared keys are significantly less secure than TLS. - -We will configure OpenVPN with self-signed certificates, and then discuss the legacy pre-shared key mode. - -In both cases, we will use the following settings: - -- The public IP address of the local VPN endpoint is 198.51.100.10. -- The public IP address of the remote VPN endpoint is 203.0.113.11. -- The tunnel uses 10.255.1.1 for the local IP address and 10.255.1.2 for the remote IP address. -- The local site has a subnet of 10.0.0.0/16. -- The remote site has a subnet of 10.1.0.0/16. -- The official OpenVPN port 1194 is reserved for client VPN. For site-to-site VPN, port 1195 is used. -- The `persistent-tunnel` directive allows us to configure tunnel-related attributes, such as firewall policy, as we would on any standard network interface. -- If known, the remote router\'s IP address can be configured using the `remote-host` directive. If unknown, it can be omitted. We assume the remote router has a dynamic IP address. - -![](/_static/images/openvpn_site2site_diagram.webp) - -## Set up site-to-site certificates - -Deploying a complete Public Key Infrastructure (PKI) with a Certificate Authority (CA) would overcomplicate site-to-site OpenVPN setups, which are primarily designed for simplicity. To keep their configuration simple without compromising security, VyOS 1.4 and later lets you verify self-signed certificates using certificate fingerprints. - -Generate a self-signed certificate on each router, preferably using the Elliptic Curve (EC) type. In configuration mode, run the following command: `run generate pki certificate self-signed install `. This adds the certificate to the configuration session\'s `pki` subtree. Review and commit the changes. - -``` none -vyos@vyos# run generate pki certificate self-signed install openvpn-local -Enter private key type: [rsa, dsa, ec] (Default: rsa) ec -Enter private key bits: (Default: 256) -Enter country code: (Default: GB) -Enter state: (Default: Some-State) -Enter locality: (Default: Some-City) -Enter organization name: (Default: VyOS) -Enter common name: (Default: vyos.io) -Do you want to configure Subject Alternative Names? [y/N] -Enter how many days certificate will be valid: (Default: 365) -Enter certificate type: (client, server) (Default: server) -Note: If you plan to use the generated key on this router, do not encrypt the private key. -Do you want to encrypt the private key with a passphrase? [y/N] -2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. -[edit] - -vyos@vyos# compare -[pki] -+ certificate openvpn-local { -+ certificate "MIICJTCCAcugAwIBAgIUMXLfRNJ5iOjk/uAZqUe4phW8MdgwCgYIKoZIzj0EAwIwVzELMAkGA1UEBhMCR0IxEzARBgNVBAgMClNvbWUtU3RhdGUxEjAQBgNVBAcMCVNvbWUtQ2l0eTENMAsGA1UECgwEVnlPUzEQMA4GA1UEAwwHdnlvcy5pbzAeFw0yMzA5MDcyMTQzMTNaFw0yNDA5MDYyMTQzMTNaMFcxCzAJBgNVBAYTAkdCMRMwEQYDVQQIDApTb21lLVN0YXRlMRIwEAYDVQQHDAlTb21lLUNpdHkxDTALBgNVBAoMBFZ5T1MxEDAOBgNVBAMMB3Z5b3MuaW8wWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAASp7D0vE3SKSAWAzr/lw9Eq9Q89r247AJR6ec/GT26AIcVA1bsongV1YaWvRwzTPC/yi5pkzV/PcT/WU7JQIyMWo3UwczAMBgNVHRMBAf8EAjAAMA4GA1UdDwEB/wQEAwIHgDATBgNVHSUEDDAKBggrBgEFBQcDATAdBgNVHQ4EFgQUBrAxRdFppdG/UBRdo7qNyHutaTQwHwYDVR0jBBgwFoAUBrAxRdFppdG/UBRdo7qNyHutaTQwCgYIKoZIzj0EAwIDSAAwRQIhAI2+8C92z9wTcTWkQ/goRxs10EBC+h78O+vgo9k97z5iAiBSeqfaVr5taQTS31+McGTAK3cYWNTg0DlOBI8aKO2oRg==" -+ private { -+ key "MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQgtOeEb0dMb5P/2Exi09WWvk6Cvz0oOBoDuP68ZimS2LShRANCAASp7D0vE3SKSAWAzr/lw9Eq9Q89r247AJR6ec/GT26AIcVA1bsongV1YaWvRwzTPC/yi5pkzV/PcT/WU7JQIyMW" -+ } -+ } - -[edit] - -vyos@vyos# commit -``` - -You do **not** need to copy the certificate to the other router. Instead, retrieve its SHA-256 fingerprint. Since OpenVPN currently supports only SHA-256 fingerprints, use the following command: - -``` none -vyos@vyos# run show pki certificate openvpn-local fingerprint sha256 -5C:B8:09:64:8B:59:51:DC:F4:DF:2C:12:5C:B7:03:D1:68:94:D7:5B:62:C2:E1:83:79:F1:F0:68:B2:81:26:79 -``` - -::::{note} -Certificate names are arbitrary. While `openvpn-local` and `openvpn-remote` are used here, you may choose any names. -:::: - -Repeat the procedure on the other router. - -## Set up site-to-site OpenVPN - -Local configuration: - -``` none -Configure the tunnel: - -set interfaces openvpn vtun1 mode site-to-site -set interfaces openvpn vtun1 protocol udp -set interfaces openvpn vtun1 persistent-tunnel -set interfaces openvpn vtun1 remote-host '203.0.113.11' # Public IP of the other side -set interfaces openvpn vtun1 local-port '1195' -set interfaces openvpn vtun1 remote-port '1195' -set interfaces openvpn vtun1 local-address '10.255.1.1' # Local IP of vtun interface -set interfaces openvpn vtun1 remote-address '10.255.1.2' # Remote IP of vtun interface -set interfaces openvpn vtun1 tls certificate 'openvpn-local' # The self-signed certificate -set interfaces openvpn vtun1 tls peer-fingerprint # The output of 'run show pki certificate fingerprint sha256' on the remote router -set interfaces openvpn vtun1 tls role active -``` - -Remote configuration: - -``` none -set interfaces openvpn vtun1 mode site-to-site -set interfaces openvpn vtun1 protocol udp -set interfaces openvpn vtun1 persistent-tunnel -set interfaces openvpn vtun1 remote-host '198.51.100.10' # Pub IP of other site -set interfaces openvpn vtun1 local-port '1195' -set interfaces openvpn vtun1 remote-port '1195' -set interfaces openvpn vtun1 local-address '10.255.1.2' # Local IP of vtun interface -set interfaces openvpn vtun1 remote-address '10.255.1.1' # Remote IP of vtun interface -set interfaces openvpn vtun1 tls certificate 'openvpn-remote' # The self-signed certificate -set interfaces openvpn vtun1 tls peer-fingerprint # The output of 'run show pki certificate fingerprint sha256 on the local router -set interfaces openvpn vtun1 tls role passive -``` - - -## Set up pre-shared keys - -Before VyOS 1.4, site-to-site OpenVPN without PKI required pre-shared keys. This option is still available but is deprecated and will be removed in future releases. If you need to set up a tunnel to an older VyOS version or a system with older OpenVPN, you still need to use pre-shared keys. - -First, generate a key by running `run generate pki openvpn shared-secret install ` in configuration mode. You can use any name; in this example, we use `s2s`. - -``` none -vyos@local# run generate pki openvpn shared-secret install s2s -2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. -[edit] -vyos@local# compare -[pki openvpn shared-secret] -+ s2s { -+ key "7c73046a9da91e874d31c7ad894a32688cda054bde157c64270f28eceebc0bb2f44dbb70335fad45148b0456aaa78cb34a34c0958eeed4f75e75fd99ff519ef940f7029a316c436d2366a2b0fb8ea1d1c792a65f67d10a461af83ef4530adc25d1c872de6d9c7d5f338223d1f3b66dc3311bbbddc0e05228c47b91c817c721aadc7ed18f0662df52ad14f898904372679e3d9697d062b0869d12de47ceb2e626fa12e1926a3119be37dd29c9b0ad81997230f4038926900d5edb78522d2940cfe207f8e2b948e0d459fa137ebb18064ac5982b28dd1899020b4f2b082a20d5d4eb65710fbb1e62b5e061df39620267eab429d3eedd9a1ae85957457c8e4655f3" -+ version "1" -+ } - -[edit] - -vyos@local# commit -[edit] -``` - -Next, install the key on the remote router: - -``` none -vyos@remote# set pki openvpn shared-secret s2s key -``` - -Finally, configure the key in your OpenVPN interface settings: - -``` none -set interfaces openvpn vtun1 shared-secret-key s2s -``` - - -## Set up firewall exceptions - -To allow OpenVPN traffic to pass through the WAN interface, create a firewall exception: - -``` none -set firewall ipv4 name OUTSIDE_LOCAL rule 10 action 'accept' -set firewall ipv4 name OUTSIDE_LOCAL rule 10 description 'Allow established/related' -set firewall ipv4 name OUTSIDE_LOCAL rule 10 state 'established' -set firewall ipv4 name OUTSIDE_LOCAL rule 10 state 'related' -set firewall ipv4 name OUTSIDE_LOCAL rule 20 action 'accept' -set firewall ipv4 name OUTSIDE_LOCAL rule 20 description 'OpenVPN_IN' -set firewall ipv4 name OUTSIDE_LOCAL rule 20 destination port '1195' -set firewall ipv4 name OUTSIDE_LOCAL rule 20 log -set firewall ipv4 name OUTSIDE_LOCAL rule 20 protocol 'udp' -``` - -Apply the OUTSIDE_LOCAL firewall group to the WAN interface and to the input filter for traffic destined for the router itself: - -``` none -set firewall ipv4 input filter rule 10 action 'jump' -set firewall ipv4 input filter rule 10 inbound-interface name eth0 -set firewall ipv4 input filter rule 10 jump-target OUTSIDE_LOCAL -``` - -Static routing: - -Configure static routes by referencing the tunnel interface. For example, if the local router\'s network is `10.0.0.0/16` and the remote router\'s network is `10.1.0.0/16`, define the routes as follows: - -Local configuration: - -``` none -set protocols static route 10.1.0.0/16 interface vtun1 -``` - -Remote configuration: - -``` none -set protocols static route 10.0.0.0/16 interface vtun1 -``` - -As with standard Ethernet interfaces, you can apply firewall policies to the tunnel interface for input, output, and forward directions. - -If you use multiple tunnels, OpenVPN must distinguish between them beyond just the pre-shared key. To achieve this, assign either unique IP addresses or unique ports to each tunnel. - -Verify OpenVPN status using the show openvpn operational commands. - -``` none -vyos@vyos:~$ show openvpn site-to-site - -OpenVPN status on vtun1 - -Client CN Remote Host Tunnel IP Local Host TX bytes RX bytes Connected Since ------------ ----------------- ----------- ------------ ---------- ---------- ----------------- -N/A 10.110.12.54:1195 N/A N/A 504.0 B 656.0 B N/A -``` - - -### Server-client - -In OpenVPN's server-client mode, the server acts as a central hub, allowing multiple clients to connect and securely route their traffic or access a private network. Multi-client server is the most popular OpenVPN mode for routers. - -## Set up server-client certificates - -Server-client mode always uses x.509 authentication and therefore requires a PKI setup. The PKI utility now simplifies the creation of Certificate Authorities (CAs), server and client certificates, and Diffie-Hellman keys directly in VyOS using configuration or operational mode commands. - -On the server, generate all certificates by running the following commands in configuration mode. The certificates will be added to the configuration session\'s PKI subtree. - -Certificate Authority (CA): - -``` none -vyos@vyos# run generate pki ca install ca-1 -Enter private key type: [rsa, dsa, ec] (Default: rsa) -Enter private key bits: (Default: 2048) -Enter country code: (Default: GB) -Enter state: (Default: Some-State) -Enter locality: (Default: Some-City) -Enter organization name: (Default: VyOS) -Enter common name: (Default: vyos.io) ca-1 -Enter how many days certificate will be valid: (Default: 1825) -Note: If you plan to use the generated key on this router, do not encrypt the private key. -Do you want to encrypt the private key with a passphrase? [y/N] -2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. -[edit] -vyos@vyos# compare -[pki] -+ ca ca-1 { -+ certificate "MIIDlzCCAn+gAwIBAgIUQW7AtPu0Qzp7VzT0TyYx83/ME8swDQYJKoZIhvcNAQELBQAwVDELMAkGA1UEBhMCR0IxEzARBgNVBAgMClNvbWUtU3RhdGUxEjAQBgNVBAcMCVNvbWUtQ2l0eTENMAsGA1UECgwEVnlPUzENMAsGA1UEAwwEY2EtMTAeFw0yNTA2MTExMTIyMjJaFw0zMDA2MTAxMTIyMjJaMFQxCzAJBgNVBAYTAkdCMRMwEQYDVQQIDApTb21lLVN0YXRlMRIwEAYDVQQHDAlTb21lLUNpdHkxDTALBgNVBAoMBFZ5T1MxDTALBgNVBAMMBGNhLTEwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDi+v6i241T9ABxq1ngjWxDQITkqjV0nq2Jb3HSSuQpXRCu7DWdQZlbvnMHnkV/WTL0RNgkhS4iV/WYhE+bLihwiZ0GTeQnUd1QJSkusFROX46w6kKXYUR5IQtcBC+vdky8PESynPd+DXsJn5X9JTWqDeviUAQz/ZjDzWk+71MBCqa+Zps1zpIjK0ywn7pR/HnDrxJOQXlBMNgvbv8U3IAZ2jJp0jTB8TnuDtWSA+XZejMm/EN/AWUQyliX6OJFSCIhBL2BZ9lmVms4/HkRpbd50k3vvCoz+lAOEE6VsH0fEdLC3lZ+CtXZ7kjp2wdWWuSs5ggIJYZZkixsCisbtEmbAgMBAAGjYTBfMA8GA1UdEwEB/wQFMAMBAf8wDgYDVR0PAQH/BAQDAgGGMB0GA1UdJQQWMBQGCCsGAQUFBwMCBggrBgEFBQcDATAdBgNVHQ4EFgQUAG9lvr7AzJ/y4vY/XlWxXru+6m0wDQYJKoZIhvcNAQELBQADggEBAKsu4eZa8Fha9aKfuKqlGQHPpEFfVDaVJmebw0uMw+b5Y8EpBxzZrgbqbk3Mty8pBjNa9jkZzph04gHN4pR6kg3iQlUKGxZUfsB9ZUjKhkgNdUI9zq1323MKEvuIuYdt61DCfBHwY6Xax5Ge+BahR2bXdPaQH452/+xMTqkukkpLbioTeIDg6FCU2HYPY5emDF5DDZAZWXtTqi0zdT3Y6FqiTvs5VuWwXCcp+HM+Lwe1/VVJhwi4CHTq0CKWnQIH5blYjmyxzRBlrlZm4ntWlL5Mtepa1A3DJirY4kw/SqMAAh/Q9lh41JzBc8epf+OdnOzK55YmtmctGO2o+NBCFi0=" -+ private { -+ key "MIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQDi+v6i241T9ABxq1ngjWxDQITkqjV0nq2Jb3HSSuQpXRCu7DWdQZlbvnMHnkV/WTL0RNgkhS4iV/WYhE+bLihwiZ0GTeQnUd1QJSkusFROX46w6kKXYUR5IQtcBC+vdky8PESynPd+DXsJn5X9JTWqDeviUAQz/ZjDzWk+71MBCqa+Zps1zpIjK0ywn7pR/HnDrxJOQXlBMNgvbv8U3IAZ2jJp0jTB8TnuDtWSA+XZejMm/EN/AWUQyliX6OJFSCIhBL2BZ9lmVms4/HkRpbd50k3vvCoz+lAOEE6VsH0fEdLC3lZ+CtXZ7kjp2wdWWuSs5ggIJYZZkixsCisbtEmbAgMBAAECggEAZdykF6wV8Z4n8NsoG4j8E/ZJbWEhWjO3x1y3JNutJw735LhmmysMSsreToXtxGfgYRTgNwt5l7oHoqmGHCsLxO1NBb5A7JBllIkIwUYqn31syOJofg0NsJpuwZ2zVLfvWe5mGg4tV2lvVPNEWXWwbp+Ow2KLcFWXkA+H8tFuW6F2mH3ntYlIi/WiCNjsEotNx8Kk7OVwt43DbkN/rbF5lxquuLedaSspOHuhIAOfZB5ZySfqohQalSAaguVD66rGPMrerZ2Vc7B1iJ6Mn/KZrSaQeHwyWrwDDHdzVwG9waydevtGTVO0dvH4etWnRypDx8p1FPJJKD4XVcsl3rR6oQKBgQD497Ep2RJcbNnKVj+kNXGriSGmyRSp6CL61KotepzgucK0RtGMeFJge56/otMHMAxIOcDMX6vRn2MB2pqVqwqUBQy6JfLrSemdpIjMN9xlX6Dw3BWP39SdewZ896/Eo0Q1ythMj1ORp+u3PqOlSa14Cy9aPwDWmNy2deD68YDnsQKBgQDpZE/T84BMQ0FzL6NRijZRzR6Dc775hRfmmSTYI0KqpG0gXNSc5UgrWSLN5H7fnx36mT01P7UkgXCInV0AlJOfkt4a8QTqM1Fh/rZbLLWpQE55S6Fs28GDiFYl2kvZT/TtxhA/E0POf/YXl/8KITS7ZVAZxE8rxBe1hVUfDbnlCwKBgQDeWUguGaGeTdCMNk8MNnbYPdaCAB+mRp3G6ls51sF4qi5Lltva2jKn3H/AoohZaP3vGzUm0WLACdsAct2QQXtnCsN9FBtJK2+qzKEn0dPR7X/s3IGdRse6BX+b6BFgSnfGmuxmI7L86L1JoHXCTnTQOx0FOjNjdI3ZnplZRIpdYQKBgFJacASU9l9yl+SiGZnLEDG7FBpEPE3lVbKrtSGDB6IY1NzHhMo76URKdop6Jv6XMcfcTIm+ihdwiRnblRaAVrrG4xJUm2xcYUoXy5bOZudq5oXMVxCHVngoImXG6l6q5P0Fl3P6Q0HZSye2HWsgnm/FZwdAisMhtU/61TdY65BTAoGBAM4jKeImiXta5lz1RgNiW/TPhft3UbOLj3TbzchNCNAamqCv4Tmh9YKB2d/mz2hNxbnAGe2cYn4iRYKcjJLMZ0UfBL2WxlrgQYQPPGzSD0fH1pLIXPohpBZpsGqNR3Nc8Jd+Uw3IiIJ2oxPCOPTOJsklNB0Xf1AlUUagB16bhhZZ" -+ } -+ } - -[edit] -vyos@vyos# commit -``` - -Server certificate: - -``` none -vyos@vyos# run generate pki certificate sign ca-1 install srv-1 -Do you already have a certificate request? [y/N] N -Enter private key type: [rsa, dsa, ec] (Default: rsa) -Enter private key bits: (Default: 2048) -Enter country code: (Default: GB) -Enter state: (Default: Some-State) -Enter locality: (Default: Some-City) -Enter organization name: (Default: VyOS) -Enter common name: (Default: vyos.io) srv-1 -Do you want to configure Subject Alternative Names? [y/N] -Enter how many days certificate will be valid: (Default: 365) -Enter certificate type: (client, server) (Default: server) server -Note: If you plan to use the generated key on this router, do not encrypt the private key. -Do you want to encrypt the private key with a passphrase? [y/N] -2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. -[edit] -vyos@vyos# compare -[pki certificate] -+ srv-1 { -+ certificate "MIIDrDCCApSgAwIBAgIULpu+qZjfG01kUI58XNmqXbQC3qQwDQYJKoZIhvcNAQELBQAwVDELMAkGA1UEBhMCR0IxEzARBgNVBAgMClNvbWUtU3RhdGUxEjAQBgNVBAcMCVNvbWUtQ2l0eTENMAsGA1UECgwEVnlPUzENMAsGA1UEAwwEY2EtMTAeFw0yNTA2MTExMTMxMDJaFw0yNjA2MTExMTMxMDJaMFUxCzAJBgNVBAYTAkdCMRMwEQYDVQQIDApTb21lLVN0YXRlMRIwEAYDVQQHDAlTb21lLUNpdHkxDTALBgNVBAoMBFZ5T1MxDjAMBgNVBAMMBXNydi0xMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAysTrMfVH63aVidJT7bIf+zLwkLse07nGsv4aliGEbufr239RBHV4Jn8LbQ+nB/8mhYGjNY4OnZ7NYz3FU/iglo8qFtaZ26mWtPWpv2xW1F8JAEK7l5BAg42cBucxiIZFeRm+jkE6VN1bcNU0utnn3sbCwZMyH6pS9k08G1qrrFLA7ZFhv5AmgJcODmO8sigSAu7rRS/6O3eO6ICnVjvIfHLb+9DKKUEffHzFV8RrkqVCGmgisz9fF+j1Rvg9s+ylNc2lZJTbb1XnzixvSRro4t9I3uIWdpJ0iOu09YiTXGQgH9ER6V3rFiX00RdSiSXf+MJCV64hC1msg+8V3Nrw9QIDAQABo3UwczAMBgNVHRMBAf8EAjAAMA4GA1UdDwEB/wQEAwIHgDATBgNVHSUEDDAKBggrBgEFBQcDATAdBgNVHQ4EFgQUzH0h4vBxma89HF9rUQ+DW052c5swHwYDVR0jBBgwFoAUAG9lvr7AzJ/y4vY/XlWxXru+6m0wDQYJKoZIhvcNAQELBQADggEBAI/Cyd0y7AJ7wY3yRssCud2iJAl9/ZjgxzXOUo6ibawYIYOnSf9tS3eD4CIH4BgppDXoJZ/qEA4WvIsLx3yvnyOxiqyk3TQmKIZ27VJH+yQkgzPeiKrHn1pCXBKEb1/jlT8Ozu4Lmn/oFwDH6nk8toxI8DM+qsTxqUFlTA3ea9yaRtxeNPMWJdaxZSUYGVSZL0wVKw5ZuQ1Gn7vGVApWlYDKYbMozCuZUG1q8wMzFBRa7x0anvh5hM4bksLz+Y1ujCS8f8b4Xtb8KIdFrZtTvtl97crv62bN05VueAcbwtYbIBNWNoT/CvmqV7k3uPg95GYSNddFqEMbQHoyd8hdDCo=" -+ private { -+ key "MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQDKxOsx9UfrdpWJ0lPtsh/7MvCQux7Tucay/hqWIYRu5+vbf1EEdXgmfwttD6cH/yaFgaM1jg6dns1jPcVT+KCWjyoW1pnbqZa09am/bFbUXwkAQruXkECDjZwG5zGIhkV5Gb6OQTpU3Vtw1TS62efexsLBkzIfqlL2TTwbWqusUsDtkWG/kCaAlw4OY7yyKBIC7utFL/o7d47ogKdWO8h8ctv70MopQR98fMVXxGuSpUIaaCKzP18X6PVG+D2z7KU1zaVklNtvVefOLG9JGuji30je4hZ2knSI67T1iJNcZCAf0RHpXesWJfTRF1KJJd/4wkJXriELWayD7xXc2vD1AgMBAAECggEACsUk3PVzSX11+ekTDigM7NHK11UpEQPoGu/GR70mBKIK9BCyI/N9W0YaPEO9kn4p9KNrINgXzKV3sVLBnXEyTmzyRl5Fs9YxLBF0X7eIcSVPHBVvU2CVHKez5uX2ypKfNAx7A6FRUNqlFbwtXdNfLoUOKSwBWI86ctytWaKaRb/TTSGQkaP/z/cwIsXOLfG9m6iFkw98ShUzalrUWNo/4fJKlO1+DvXVYE9sv9rjD8J7DtAbr5KykQ5n0AAlZTCWQ7jwMybSnjjY9ypZUms0l17raJrfhrdbWayc6xMDvtrmNIDebkF+J7cHU06aEV+yQXV/7yjyZgUSM2ANcHMdzQKBgQDmTi5tUeaj1JUSl9lAP/XUzcElw2tcU1B8qpX69J4ofjTNgj5okLWQZVIy1UyAfLOI3LJbHTBUtSvedhH0VaMulq99NXs5qnbPGG3//RBAc0wKhJknB5Qv0D3FxMI14kMO6jzPly+aIGEk4dTtHvZuHbbVHbKSZ5MMouLyT+SS7wKBgQDhZETARZ0MazeWRaPJwdkjlfNcqqcsnDicdcppCkcDCjeLxkVPZc8ej37rshOvw2Pf1D0PddGyOhJoWCWA8QE2LQoDHLaDnQ0L6aQ3yjN5Gxx9RCDFi3Zuat/mPcv3tFO7uUmeYvRC5fGYrghq29NADmUefOopAc06Izd4A3iqWwKBgQC1uPrpR7a1jwgRo7/I8q8HO1MseQY903+u3ut5GYuyZ+NCRYL4/zZEua4ibivvNnZzh7E0M9PvAwWag4+nO+uG11+hbJHO7rLQtnYVh5lLQa6+neI66cAD+kzDwH1+BwriufFB3Amzk9kTQR7B+6x3NvsNLmG5JADj96Mbj+7MAQKBgFIevEXplyzdK6WevexWqoyip8aNjtdcG+w1pofa7MCYymAs3zfseihCVBYADdguModsxsqJPNvY+Lf31cJDDRP2GP3FSmJtqEE84U5KZ7KqRBkH54DSLVZRrj4vKc+YbiGpgr8ogqKVMQ9V6U81xKREGmefT5mdRG74Qc+CREadAoGAFtdsH5js1yFEeGFad4BZJ69grEavD3pNCfIe9oIPtXvvFdzxd+QbKgqFf3JMJp/HYi8A0iv/i4mzf00KXzF4JU7bIJYrUVlk/w8x77gzDRIphsPqpMBJkTI0jisQHZKWNEe7IbmM/dWW2S4jvCkrhB7F5Szf72Q+j/lPbfx2g/8=" -+ } -+ } - -[edit] -vyos@vyos# commit -``` - -Diffie-Hellman key: - -``` none -vyos@vyos# run generate pki dh install dh-1 -Enter DH parameters key size: (Default: 2048) -Generating parameters... -1 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. -[edit] -vyos@vyos# compare -[pki] -+ dh dh-1 { -+ parameters "MIIBCAKCAQEAp25kxwZeLZ7wcbRii5E5RD4uWCUOBxarzKEE0msa84omh5nZ9dv/4bfJw4gIXlA2+sGc2lLV/jajZminMryiSwJdisyVuUdOB7sJWZwrzHBAY0qFbNyaRMVJBar2xVm+XcKd3A2eNTEgn10G7rPPvf6CJ5isUKFaKT8ymUv+mI0upLneYdGs8/yS3sAojzeulCf49fa5SiaGCcZZkdOI3Nby1u/ZG4okqJ2wE2c2hRVLs1k5qrrono0OF4Dh0B91ihnywRfp1xPYeqpiln+OPh+PPgTuBxkz4VxwRDoQ+NhVr/LOCb3vbhnyFisxI0w4r3109cA3QiDmo1L14aKl1wIBAg==" -+ } - -[edit] -vyos@vyos# commit -``` - -Client certificate: - -``` none -vyos@vyos:~$ generate pki certificate sign ca-1 install client1 -Do you already have a certificate request? [y/N] N -Enter private key type: [rsa, dsa, ec] (Default: rsa) -Enter private key bits: (Default: 2048) -Enter country code: (Default: GB) -Enter state: (Default: Some-State) -Enter locality: (Default: Some-City) -Enter organization name: (Default: VyOS) -Enter common name: (Default: vyos.io) client1 -Do you want to configure Subject Alternative Names? [y/N] -Enter how many days certificate will be valid: (Default: 365) -Enter certificate type: (client, server) (Default: server) client -Note: If you plan to use the generated key on this router, do not encrypt the private key. -Do you want to encrypt the private key with a passphrase? [y/N] -You are not in configure mode, commands to install manually from configure mode: -set pki certificate client1 certificate 'MIIDrjCCApagAwIBAgIUPvtffeYTdoOiHxu++wdrjHwwVX4wDQYJKoZIhvcNAQELBQAwVDELMAkGA1UEBhMCR0IxEzARBgNVBAgMClNvbWUtU3RhdGUxEjAQBgNVBAcMCVNvbWUtQ2l0eTENMAsGA1UECgwEVnlPUzENMAsGA1UEAwwEY2EtMTAeFw0yNTA2MTExMTQxMDlaFw0yNjA2MTExMTQxMDlaMFcxCzAJBgNVBAYTAkdCMRMwEQYDVQQIDApTb21lLVN0YXRlMRIwEAYDVQQHDAlTb21lLUNpdHkxDTALBgNVBAoMBFZ5T1MxEDAOBgNVBAMMB2NsaWVudDEwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQC9H6E6gm0PfXO1n/WoA9xlg89/bnScLmfztVDn1uyNn8epE6zAi2GWBhtj4ixLllIwLdkJ7L2mF3yUZtA1Q0oYbGIqTbnaZ37JydCygVGnlLT7UX9zfRfS3KebCIvIte7OyCmnUfVfFzdIsp+4LI3S2wX/9Vyn4UBAR8QQNbezRB3XPMk9gzULnuLhmEDP6GVcPq7RzGXoXUMqsCxfEOJBjej0y4ANKH07HGVVrfVRiY+zlGkM4TFjVuZKnEA0BO6dhOA0E+7gsIXsC06UzzatkjsyWHpb2/DOECIifBoYej9DITu8VxyyZmgaINHEn2gGb0LRHO7rvQapc+XZ2z9DAgMBAAGjdTBzMAwGA1UdEwEB/wQCMAAwDgYDVR0PAQH/BAQDAgeAMBMGA1UdJQQMMAoGCCsGAQUFBwMCMB0GA1UdDgQWBBQnUyqEzG+AqZzsdSud5MDqsOxiXTAfBgNVHSMEGDAWgBQAb2W+vsDMn/Li9j9eVbFeu77qbTANBgkqhkiG9w0BAQsFAAOCAQEAplItvZpoX/joG3QREu9tHVKwDTmXB2lwUM5G8iKPgd6D6oOILZMe2KuvWt12dcdEzUCGfJwJJ8M8R2WD0OmcLdFqvM/8UM1hYzUP2BCnFCLtElVD+b4wMlQNpdHqNbdckw8J4MLQlhUgu9rZAZ0XjWCprr+U50bX++vYRw7Un3Ds6ETEvjflm5WAPb2e0V1hhISPl8K+VXO7RAwxy0DHcDuR+YaD+hnNgMsJV3/QwA17Iy8x86RpOgqmesbt0U7e9Rmo81aVgiy/V4OCV7u6bPX03fmZNS8UwwJuRUlxkjO+epHNYB2cnOcjSkUxaIJ9Hv3tMWHQEtbVZsNYSOZozw==' -set pki certificate client1 private key 'MIIEvAIBADANBgkqhkiG9w0BAQEFAASCBKYwggSiAgEAAoIBAQC9H6E6gm0PfXO1n/WoA9xlg89/bnScLmfztVDn1uyNn8epE6zAi2GWBhtj4ixLllIwLdkJ7L2mF3yUZtA1Q0oYbGIqTbnaZ37JydCygVGnlLT7UX9zfRfS3KebCIvIte7OyCmnUfVfFzdIsp+4LI3S2wX/9Vyn4UBAR8QQNbezRB3XPMk9gzULnuLhmEDP6GVcPq7RzGXoXUMqsCxfEOJBjej0y4ANKH07HGVVrfVRiY+zlGkM4TFjVuZKnEA0BO6dhOA0E+7gsIXsC06UzzatkjsyWHpb2/DOECIifBoYej9DITu8VxyyZmgaINHEn2gGb0LRHO7rvQapc+XZ2z9DAgMBAAECggEAPS/Fhtt5k2BgFivZW3FcVc+OS0keGwV8hkFsGoXTZIKEIzSFWIn/mX0CUY90C0Rn9MRwiqB4PwssOAsHY6QQjdRK8irRbVK8l2ZeydHC7DfVUdXtKR0YnxTaePML3nTV/TqPF14Rx6EINtHrkLeBbu2DhGsKfhoHIoTVbvUiKLHa2TkGJOkhvjsyMSPKzUXa1AzLmu+UBIhRYpEPHj0SQUUJJnKgIb7mTR2fhJScHcKwsrPq6S8OpChvsYZ6zatgrTFz9tuhD4IjL7NBiYP45BwGaLIaQjph8yAJwwHWoOP+TTj5WYflkW6Uu8F9gC0ve6dPGPNEi2TUdirvAe4LYQKBgQD0UfAPm6tQg8pdkvfMBvYc21fk8zqmgcA4OtvDi60aXuv5jI5+faISvOG2JLuFhKIDOb5ZerzGvkN+LvWgzr9H7YdGZNNtwKgpS/MGqcuuHncTxWBAwYgKhf26a/tqFZRNurJ6GowxDiAcQEc1mWnmdngRa+dvvCwNbXvGVqfVEQKBgQDGKi447TqD76QfvRPn/fRSjM+QE1duk+XorEJ0HHIha5HV9kCrZdV/olGRjDLwPJO6JW7iE2FUsS9SsIrccFE/9P2ZUqfYP2wL5vNO5kAmoLLUl0gwqg1WnBTPJfXeKReTj2uGmOdEuuMPXpL/49hDuPViiE2Q4MGe2Z+oEYN/EwKBgHfQMuTEl2e9qaDn8OM6SrluC5V4fjunh6dLnfgwaCx1fk1702lOnQuJWzsiml9o4raoO6PP4AGqzphz2PsKSJ2ya1NnIJRDFXRjDYQoAn2Z7RViBsja36chfINObxXgDUFtHBdrK3LnFXIlR4aOfHOLh2grvWx7IDNZjIiAeH+xAoGAJlmFZnjqiRv4bDgAQTZRcSRVCvHjSsAOj0++8I+MutEBgSHN9B2aCsBT/tHeDcX7ZNvXsKLFhElh+iO2S+DkqHb2GRT47I2hkFAaqBtBMPiKgz/ftaNDP46nLEuRYHQdXu4zhfHTV+a/CHtqAWGLuddyjaYJNM96SQ6eqjzxcMcCgYAzdxOF2e27hIgo2ttjsROMGqW0/0r/HsKGKPnao7xHQNCAswTnBT+QGugPCe0NXjuxbySP7V1GeWMWF+WV5khtteWerT1/ELAC48NSDpaMxVa4GP8Q/0w6+ZyJty3UGbCYQzZZue81dU+42LUIaVJ4NAc2tYj3jD780udasawS6w==' -``` - -Manually copy the CA, client certificate, and Diffie-Hellman key to the client device, then commit them before configuring the OpenVPN interface. - -For more options, refer to {ref}`configuration/pki/index:pki`. - -## Set up server-client OpenVPN - -The following example demonstrates the most complicated scenario: each client acts as a router with its own subnet (e.g., an HQ and multiple branch offices). Simpler setups are subsets of it. - -In this scenario, the 10.23.1.0/24 network is used for client tunnel endpoints, and all client subnets belong to 10.23.0.0/20. Each client needs access to the 192.168.0.0/16 network. - -Server configuration: - -``` none -set interfaces openvpn vtun10 encryption data-ciphers 'aes256' -set interfaces openvpn vtun10 hash 'sha512' -set interfaces openvpn vtun10 local-host '172.18.201.10' -set interfaces openvpn vtun10 local-port '1194' -set interfaces openvpn vtun10 mode 'server' -set interfaces openvpn vtun10 persistent-tunnel -set interfaces openvpn vtun10 protocol 'udp' -set interfaces openvpn vtun10 server client client1 ip '10.23.1.10' -set interfaces openvpn vtun10 server client client1 subnet '10.23.2.0/25' -set interfaces openvpn vtun10 server domain-name 'vyos.net' -set interfaces openvpn vtun10 server max-connections '250' -set interfaces openvpn vtun10 server name-server '172.16.254.30' -set interfaces openvpn vtun10 server subnet '10.23.1.0/24' -set interfaces openvpn vtun10 server topology 'subnet' -set interfaces openvpn vtun10 tls ca-certificate ca-1 -set interfaces openvpn vtun10 tls certificate srv-1 -set interfaces openvpn vtun10 tls dh-params dh-1 -``` - -The configuration above uses the default 1194/UDP port, 256-bit AES encryption, SHA-512 for HMAC authentication, and the persistent-tunnel option. Persistent-tunnel is recommended as it keeps the TUN/TAP device active during connection resets or daemon reloads. Clients are identified by the CN attribute in their SSL certificates. - -To grant clients access to a specific network behind the router, use the push-route option to automatically install the appropriate route on each client. - -``` none -set interfaces openvpn vtun10 server push-route 192.168.0.0/16 -``` - -OpenVPN does not automatically create kernel routes for client subnets when clients connect; it only uses client-subnet association internally. Therefore, you must manually create a route to the 10.23.0.0/20 network: - -``` none -set protocols static route 10.23.0.0/20 interface vtun10 -``` - - -## Set up OpenVPN client - -VyOS can operate not only as an OpenVPN site-to-site peer or a server for multiple clients, but also as an OpenVPN client. Any VyOS OpenVPN interface can be configured to connect to another VyOS or third-party OpenVPN server. - -Client configuration: - -``` none -set interfaces openvpn vtun10 encryption data-ciphers 'aes256' -set interfaces openvpn vtun10 hash 'sha512' -set interfaces openvpn vtun10 mode 'client' -set interfaces openvpn vtun10 persistent-tunnel -set interfaces openvpn vtun10 protocol 'udp' -set interfaces openvpn vtun10 remote-host '172.18.201.10' -set interfaces openvpn vtun10 remote-port '1194' -set interfaces openvpn vtun10 tls ca-certificate ca-1 -set interfaces openvpn vtun10 tls certificate client1 -``` - - -## Verification - -Check the tunnel status: - -``` none -vyos@vyos:~$ show openvpn server - -OpenVPN status on vtun10 - -Client CN Remote Host Tunnel IP Local Host TX bytes RX bytes Connected Since ------------ ------------------ ----------- ---------------- ---------- ---------- ------------------- -client1 172.16.12.54:33166 10.23.1.10 172.18.201.10:1194 3.4 KB 3.4 KB 2024-06-11 12:07:25 -``` - - -### Server bridge - -In Ethernet bridging configurations, an OpenVPN interface operating in server mode with the device type set to TAP can be added to a bridge. By encapsulating entire Ethernet frames (up to 1514 bytes) rather than just IP packets (up to 1500 bytes), this setup enables clients to transmit Layer 2 frames through the OpenVPN tunnel. - -The following is a basic configuration example: - -Server side: - -``` none -set interfaces bridge br10 member interface eth1.10 -set interfaces bridge br10 member interface vtun10 -set interfaces openvpn vtun10 device-type 'tap' -set interfaces openvpn vtun10 encryption data-ciphers 'aes192' -set interfaces openvpn vtun10 hash 'sha256' -set interfaces openvpn vtun10 local-host '172.18.201.10' -set interfaces openvpn vtun10 local-port '1194' -set interfaces openvpn vtun10 mode 'server' -set interfaces openvpn vtun10 server bridge gateway '10.10.0.1' -set interfaces openvpn vtun10 server bridge start '10.10.0.100' -set interfaces openvpn vtun10 server bridge stop '10.10.0.200' -set interfaces openvpn vtun10 server bridge subnet-mask '255.255.255.0' -set interfaces openvpn vtun10 server topology 'subnet' -set interfaces openvpn vtun10 tls ca-certificate 'ca-1' -set interfaces openvpn vtun10 tls certificate 'srv-1' -set interfaces openvpn vtun10 tls dh-params 'dh-1' -``` - -Client side: - -``` none -set interfaces openvpn vtun10 device-type 'tap' -set interfaces openvpn vtun10 encryption data-ciphers 'aes192' -set interfaces openvpn vtun10 hash 'sha256' -set interfaces openvpn vtun10 mode 'client' -set interfaces openvpn vtun10 protocol 'udp' -set interfaces openvpn vtun10 remote-host '172.18.201.10' -set interfaces openvpn vtun10 remote-port '1194' -set interfaces openvpn vtun10 tls ca-certificate 'ca-1' -set interfaces openvpn vtun10 tls certificate 'client-1' -``` - - -### Server LDAP authentication - -## LDAP - -Enterprise installations usually include a directory service to centralize employee password management. VyOS and OpenVPN support using LDAP and Active Directory as a single user backend. - -Authentication is performed by the `openvpn-auth-ldap.so` plugin, included with every VyOS installation. To use it, you must create a dedicated configuration file. -**Best practice:** Store the configuration file in the `/config` directory to ensure it is preserved after image updates. - -``` none -set interfaces openvpn vtun0 openvpn-option "--plugin /usr/lib/openvpn/openvpn-auth-ldap.so /config/auth/ldap-auth.config" -``` - -A sample configuration file is shown below: - -``` none - -# LDAP server URL -URL ldap://ldap.example.com -# Bind DN (If your LDAP server doesn't support anonymous binds) -BindDN cn=LDAPUser,dc=example,dc=com -# Bind Password password -Password S3cr3t -# Network timeout (in seconds) -Timeout 15 - - - -# Base DN -BaseDN "ou=people,dc=example,dc=com" -# User Search Filter -SearchFilter "(&(uid=%u)(objectClass=shadowAccount))" -# Require Group Membership - allow all users -RequireGroup false - -``` - - -### Active Directory - -A sample configuration file is shown below: - -``` none - - # LDAP server URL - URL ldap://dc01.example.com - # Bind DN (If your LDAP server doesn’t support anonymous binds) - BindDN CN=LDAPUser,DC=example,DC=com - # Bind Password - Password mysecretpassword - # Network timeout (in seconds) - Timeout 15 - # Enable Start TLS - TLSEnable no - # Follow LDAP Referrals (anonymously) - FollowReferrals no - - - - # Base DN - BaseDN "DC=example,DC=com" - # User Search Filter, user must be a member of the VPN AD group - SearchFilter "(&(sAMAccountName=%u)(memberOf=CN=VPN,OU=Groups,DC=example,DC=com))" - # Require Group Membership - RequireGroup false # already handled by SearchFilter - - BaseDN "OU=Groups,DC=example,DC=com" - SearchFilter "(|(cn=VPN))" - MemberAttribute memberOf - - -``` - -If you only want to check that the user account is enabled and can authenticate (against the primary group), the following snippet is sufficient: - -``` none - - URL ldap://dc01.example.com - BindDN CN=SA_OPENVPN,OU=ServiceAccounts,DC=example,DC=com - Password ThisIsTopSecret - Timeout 15 - TLSEnable no - FollowReferrals no - - - - BaseDN "DC=example,DC=com" - SearchFilter "sAMAccountName=%u" - RequireGroup false - -``` - -A complete example of an LDAP authentication configuration for OpenVPN is shown below: - -``` none -vyos@vyos# show interfaces openvpn - openvpn vtun0 { - mode server - openvpn-option "--tun-mtu 1500 --fragment 1300 --mssfix" - openvpn-option "--plugin /usr/lib/openvpn/openvpn-auth-ldap.so /config/auth/ldap-auth.config" - openvpn-option "--push redirect-gateway" - openvpn-option --duplicate-cn - openvpn-option "--verify-client-cert none" - openvpn-option --comp-lzo - openvpn-option --persist-key - openvpn-option --persist-tun - server { - domain-name example.com - max-connections 5 - name-server 203.0.113.0.10 - name-server 198.51.100.3 - subnet 172.18.100.128/29 - } - tls { - ca-certificate ca.crt - certificate server.crt - dh-params dh1024.pem - } - } -``` - -For a detailed example, refer to {doc}`OpenVPN with LDAP`. - -### Multi-factor authentication - -VyOS supports multi-factor authentication (MFA) or two-factor authentication using Time-based One-Time Passwords (TOTP). It is compatible with Google Authenticator and other software tokens. - -## Server side - -``` none -set interfaces openvpn vtun20 encryption cipher 'aes256' -set interfaces openvpn vtun20 hash 'sha512' -set interfaces openvpn vtun20 mode 'server' -set interfaces openvpn vtun20 persistent-tunnel -set interfaces openvpn vtun20 server client user1 -set interfaces openvpn vtun20 server mfa totp challenge 'disable' -set interfaces openvpn vtun20 server subnet '10.10.2.0/24' -set interfaces openvpn vtun20 server topology 'subnet' -set interfaces openvpn vtun20 tls ca-certificate 'openvpn_vtun20' -set interfaces openvpn vtun20 tls certificate 'openvpn_vtun20' -set interfaces openvpn vtun20 tls dh-params 'dh-pem' -``` - -A TOTP secret is created for each client in the OpenVPN server configuration. To display authentication information, use the following command: `show interfaces openvpn vtun20 user user1 mfa qrcode`. - -Example: - -``` none -vyos@vyos:~$ sh interfaces openvpn vtun20 user user1 mfa qrcode -█████████████████████████████████████ -█████████████████████████████████████ -████ ▄▄▄▄▄ █▀▄▀ ▀▀▄▀ ▀▀▄ █ ▄▄▄▄▄ ████ -████ █ █ █▀▀▄ █▀▀▀█▀██ █ █ █ ████ -████ █▄▄▄█ █▀█ ▄ █▀▀ █▄▄▄█ █▄▄▄█ ████ -████▄▄▄▄▄▄▄█▄█ █ █ ▀ █▄▀▄█▄▄▄▄▄▄▄████ -████▄▄ ▄ █▄▄ ▄▀▄█▄ ▄▀▄█ ▄▄▀ ▀▄█ ▀████ -████ ▀██▄▄▄█▄ ██ █▄▄▄▄ █▄▀█ █ █▀█████ -████ ▄█▀▀▄▄ ▄█▀ ▀▄ ▄▄▀▄█▀▀▀ ▄▄▀████ -████▄█ ▀▄▄▄▀ ▀ ▄█ ▄ █▄█▀ █▀ █▀█████ -████▀█▀ ▀ ▄█▀▄▀▀█▄██▄█▀▀ ▀ ▀ ▄█▀████ -████ ██▄▄▀▄▄█ ██ ▀█ ▄█ ▀▄█ █▀██▀████ -████▄███▄█▄█ ▀█▄ ██▄▄▄█▀ ▄▄▄ █ ▀ ████ -████ ▄▄▄▄▄ █▄█▀▄ ▀▄ ▀█▀ █▄█ ██▀█████ -████ █ █ █ ▄█▀█▀▀▄ ▄▀▀▄▄▄▄▄▄ ████ -████ █▄▄▄█ █ ▄ ▀ █▄▄▄██▄▀█▄▀▄█▄ █████ -████▄▄▄▄▄▄▄█▄██▄█▄▄▄▄▄█▄█▄█▄██▄██████ -█████████████████████████████████████ -█████████████████████████████████████ -``` - -Scan the QR code to add the user account to Google Authenticator. On the client side, use the generated OTP as the password. - -### Authentication with username/password - -An OpenVPN server can securely obtain a username and password from a connecting client and use this information for authentication. - -First, configure the server to use an authentication plugin or script. The server calls this plugin every time a client tries to connect, passing it the client\'s credentials. - -In the following example, the `--auth-user-pass-verify` directive is used with the via-env method and a specified script path to validate the client\'s username and password. - -## Server configuration - -``` none -set interfaces openvpn vtun10 local-port '1194' -set interfaces openvpn vtun10 mode 'server' -set interfaces openvpn vtun10 openvpn-option '--auth-user-pass-verify /config/auth/check_user.sh via-env' -set interfaces openvpn vtun10 openvpn-option '--script-security 3' -set interfaces openvpn vtun10 persistent-tunnel -set interfaces openvpn vtun10 protocol 'udp' -set interfaces openvpn vtun10 server client client-1 ip '10.10.10.55' -set interfaces openvpn vtun10 server push-route 192.0.2.0/24 -set interfaces openvpn vtun10 server subnet '10.10.10.0/24' -set interfaces openvpn vtun10 server topology 'subnet' -set interfaces openvpn vtun10 tls ca-certificate 'ca-1' -set interfaces openvpn vtun10 tls certificate 'srv-1' -set interfaces openvpn vtun10 tls dh-params 'dh-1' -``` - -The /config/auth/check_user.sh example includes two test users: - -``` none -#!/bin/bash -USERNAME="$username" -PASSWORD="$password" - -# Replace this with real user checking logic or use getent -if [[ "$USERNAME" == "client1" && "$PASSWORD" == "pass123" ]]; then - exit 0 -elif [[ "$USERNAME" == "peter" && "$PASSWORD" == "qwerty" ]]; then - exit 0 -else - exit 1 -fi -``` - - -## Client configuration - -Storing the client certificate locally lets you generate the OpenVPN client configuration file. Use the following command: - -``` none -vyos@vyos:~$ generate openvpn client-config interface vtun10 ca ca-1 certificate client1 -``` - -Copy the output and save it as a .ovpn file. Add the `auth-user-pass` directive to the file. This instructs the OpenVPN client to prompt the user for a username and password, which are then sent to the server over the TLS channel. You can now import this file into any OpenVPN client application. - -``` none -client -dev tun -proto udp -remote 192.168.77.10 1194 - -remote-cert-tls server -proto udp -dev tun -dev-type tun -persist-key -persist-tun -verb 3 -auth-user-pass - - - ------BEGIN CERTIFICATE----- -MIIDlzCCAn+gAwIBAgIUQW7AtPu0Qzp7VzT0TyYx83/ME8swDQYJKoZIhvcNAQEL -BQAwVDELMAkGA1UEBhMCR0IxEzARBgNVBAgMClNvbWUtU3RhdGUxEjAQBgNVBAcM -CVNvbWUtQ2l0eTENMAsGA1UECgwEVnlPUzENMAsGA1UEAwwEY2EtMTAeFw0yNTA2 -MTExMTIyMjJaFw0zMDA2MTAxMTIyMjJaMFQxCzAJBgNVBAYTAkdCMRMwEQYDVQQI -DApTb21lLVN0YXRlMRIwEAYDVQQHDAlTb21lLUNpdHkxDTALBgNVBAoMBFZ5T1Mx -DTALBgNVBAMMBGNhLTEwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDi -+v6i241T9ABxq1ngjWxDQITkqjV0nq2Jb3HSSuQpXRCu7DWdQZlbvnMHnkV/WTL0 -RNgkhS4iV/WYhE+bLihwiZ0GTeQnUd1QJSkusFROX46w6kKXYUR5IQtcBC+vdky8 -PESynPd+DXsJn5X9JTWqDeviUAQz/ZjDzWk+71MBCqa+Zps1zpIjK0ywn7pR/HnD -rxJOQXlBMNgvbv8U3IAZ2jJp0jTB8TnuDtWSA+XZejMm/EN/AWUQyliX6OJFSCIh -BL2BZ9lmVms4/HkRpbd50k3vvCoz+lAOEE6VsH0fEdLC3lZ+CtXZ7kjp2wdWWuSs -5ggIJYZZkixsCisbtEmbAgMBAAGjYTBfMA8GA1UdEwEB/wQFMAMBAf8wDgYDVR0P -AQH/BAQDAgGGMB0GA1UdJQQWMBQGCCsGAQUFBwMCBggrBgEFBQcDATAdBgNVHQ4E -FgQUAG9lvr7AzJ/y4vY/XlWxXru+6m0wDQYJKoZIhvcNAQELBQADggEBAKsu4eZa -8Fha9aKfuKqlGQHPpEFfVDaVJmebw0uMw+b5Y8EpBxzZrgbqbk3Mty8pBjNa9jkZ -zph04gHN4pR6kg3iQlUKGxZUfsB9ZUjKhkgNdUI9zq1323MKEvuIuYdt61DCfBHw -Y6Xax5Ge+BahR2bXdPaQH452/+xMTqkukkpLbioTeIDg6FCU2HYPY5emDF5DDZAZ -WXtTqi0zdT3Y6FqiTvs5VuWwXCcp+HM+Lwe1/VVJhwi4CHTq0CKWnQIH5blYjmyx -zRBlrlZm4ntWlL5Mtepa1A3DJirY4kw/SqMAAh/Q9lh41JzBc8epf+OdnOzK55Ym -tmctGO2o+NBCFi0= ------END CERTIFICATE----- - - - - ------BEGIN CERTIFICATE----- -MIIDrjCCApagAwIBAgIUN6vPxDEW89cfbEFPa0tZlnsW1GkwDQYJKoZIhvcNAQEL -BQAwVDELMAkGA1UEBhMCR0IxEzARBgNVBAgMClNvbWUtU3RhdGUxEjAQBgNVBAcM -CVNvbWUtQ2l0eTENMAsGA1UECgwEVnlPUzENMAsGA1UEAwwEY2EtMTAeFw0yNTA2 -MTExMTQ0MjlaFw0yNjA2MTExMTQ0MjlaMFcxCzAJBgNVBAYTAkdCMRMwEQYDVQQI -DApTb21lLVN0YXRlMRIwEAYDVQQHDAlTb21lLUNpdHkxDTALBgNVBAoMBFZ5T1Mx -EDAOBgNVBAMMB2NsaWVudDEwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIB -AQCdOWq8vdO8CznGN83uAXCuN4PcdTJaRFEdJIEfqHjlcG0MZQuPIAlDbOU+IWmu -QBmeCj7SlbYtVYo1uQOMUaIrAvxLIQUaL1Y60oLVTF5eAPrGV+NSTQR5uMApcH9/ -RcZcW530pu/QpYinKTbGkEd54so6YRVPmYbIOPNUMbnZbccpinYi5t2dqubBb585 -A7L40043VtsVVbPjQq5V0HDursvqlaMqMRcffhR8H4B4ByU/EPRK4yTKm1hi19v3 -UtRHiq74CfGtJzYtplgrLJBON7TsbIi/fEux4q1yhbKA0S66L6e5DZldRxNZOXG6 -QjEL0RkYloMgkbv/2HLCu09hAgMBAAGjdTBzMAwGA1UdEwEB/wQCMAAwDgYDVR0P -AQH/BAQDAgeAMBMGA1UdJQQMMAoGCCsGAQUFBwMCMB0GA1UdDgQWBBQCkfdfq3hv -7UtqAxq/5VDRIdgJLTAfBgNVHSMEGDAWgBQAb2W+vsDMn/Li9j9eVbFeu77qbTAN -BgkqhkiG9w0BAQsFAAOCAQEAJ43+aDVRC+y2vsu6WRG2l6zYnLoIJZW4afdKMC1a -nhTWhj4AhAt8evhVbAxi/8qhQX3yXF2bUQKdS++8AVcvZFlSES32S5eBx83AwGLt -QkgvGx+QThKmoJwrelyuS2X0XX3P0WzohYI6HzSr6p9F8KhTvSW97E6SnldpdvEM -uG1C+61/Vys7WLmDBh1PZTGE03nRp3H4Q9ynyXEEf1MK3eZkzg5H3Evj66p82pD5 -8IauRfghMHJf3tOC+y0YIoXshF3lPq4nYso5Jc/HGCHlsboCODMCnY3CZsH7/O1n -/MI710KpzZTCLnv4Qtx9JpZxR7FTddl36OOuYUXU3Gcnsg== ------END CERTIFICATE----- - - - - ------BEGIN PRIVATE KEY----- -MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQCdOWq8vdO8CznG -N83uAXCuN4PcdTJaRFEdJIEfqHjlcG0MZQuPIAlDbOU+IWmuQBmeCj7SlbYtVYo1 -uQOMUaIrAvxLIQUaL1Y60oLVTF5eAPrGV+NSTQR5uMApcH9/RcZcW530pu/QpYin -KTbGkEd54so6YRVPmYbIOPNUMbnZbccpinYi5t2dqubBb585A7L40043VtsVVbPj -Qq5V0HDursvqlaMqMRcffhR8H4B4ByU/EPRK4yTKm1hi19v3UtRHiq74CfGtJzYt -plgrLJBON7TsbIi/fEux4q1yhbKA0S66L6e5DZldRxNZOXG6QjEL0RkYloMgkbv/ -2HLCu09hAgMBAAECggEAOR3xRVUO9Sr816JRSQwz486eNDpNSxazgwtOb3JUTUH9 -E7onq1y/kMOgOmSIEHoP9GaTcQxbbPe86IxomhLT/50ri52YzWzx/heY2SVPyQXB -FMo79putKw0vnj5UyydNiyLrbMQyrhFc5iFmWVdz5/c4cWHwjIThPp7V4znXYwHZ -OB/Xn1NNHDNy872oQn5wZWzuA4ml0OqjU5D+Ne9srODl3r4OTo3lb1N3JuH3aOSA -cACl1JnN/KElN8IotIdweeUFAdn2jsGjZnCpGaJvZQ+2iMn6doJXHgFiF5+GMF7o -aOatglElIuqgPtB/4nvnegSL0DSnB36ojqv2PAh24wKBgQDPBt4S4muqo8SqP2e0 -8X78MyK3tz1VmgPKn3O68Vdi1V7FPz0RHRGsw/kdgxXsJlfZTWgzcq2NNFu0yPBJ -A/h7qo16mv8GW7cJCd2exjb+/oq4r5iWeqLdSsMUXN87x02LRaMNd9wz1mls1Z73 -oQ5hJ7zTtlyYXnvKPQo8X1ImjwKBgQDCaptQxZ/a3tcUQQlXAFMAScviODZd0LCL -30ZalwpNs6nVVIPoZHD3tlzWN5Es74gndfkC7/Gm2cnsOW9QQaU56q+5LeNXItW8 -rc6yXq3vNQerqJxHNUmKWwLCQtSyLRjFqpGTl/PyX2bGXQ7/zjTL3W8VMD5otf4Y -SJJB+sKjDwKBgHSVX3WvAAamFtfwwMwKuwH3IfPnQqj0BHKUfK2nvxgvJCFbzV3X -yt5Jtf3ClhPYO9xpVOa0C7va4lHaXkYf8Exj7SxAIKFKALccUStaYBoU6bW7XOhQ -w2pu8ZCEBEo7oBVv77Rj7SNb+R6K5ex5TAm2QQXQSjCb9IYc/ail3TNNAoGBALu6 -GPMrgKnlFyV1j0E1DPBwUbDEuqpoArFtDRAYXFifLVTS4PQbWIG403f9++659Gy2 -G5ZcfqiwD6xL4VJLsPF1zewvhR/0gRJJehb+GVGrkRaOHykbKUGxk75kreDGbu8f -PqaXyXS17hWIch1Lzes0jDiXdwvA//QOzztqmVq9AoGAVMbmf04+QtzckLolAP4q -Uwr5svfy14A7V3IGkwlsHZdm37L26lfxW0kpOOE7g7D6gdinuALo6oopP7RN/IDq -PLaaHaGrIoLAEVFa0bRLGsrU2q87ytwfSgdra4jmsTn+xEabdI4IgmqWgwSRvGVf -KN18e19Ssw5x7Wq0Rsw/3VM= ------END PRIVATE KEY----- - - -``` - -When prompted, log in with the username and password. diff --git a/docs/configuration/interfaces/md-openvpn.md b/docs/configuration/interfaces/md-openvpn.md deleted file mode 100644 index 170c585d..00000000 --- a/docs/configuration/interfaces/md-openvpn.md +++ /dev/null @@ -1,614 +0,0 @@ -(openvpn)= - -# OpenVPN - -Traditionally, hardware routers use IPsec exclusively because it is easy to -implement in hardware, and their CPUs lack sufficient power for software-based -encryption. This limitation is less relevant for VyOS, as it is a software -router. - -OpenVPN has been widely used on UNIX platforms for a long time and is a popular -choice for remote-access VPNs. It also supports site-to-site connections. - -OpenVPN offers the following advantages: - -- It uses a single TCP or UDP connection and does not rely on packet source - addresses, so it works even through double NAT. This makes it well-suited for - public hotspots. -- It is easy to set up and offers very flexible split tunneling. -- A variety of client GUI frontends are available for any platform. - -Disadvantages include: - -- It is slower than IPsec due to higher protocol overhead and because it runs - in user mode, while IPsec on Linux runs in kernel mode. -- No operating system includes OpenVPN client software by default. - -In the VyOS CLI, OpenVPN is configured as a network interface using `set -interfaces openvpn` rather than `set vpn`, which is often overlooked. - -## Configuration - -```{cfgcmd} set interfaces openvpn \ authentication password \ - - **Configure the password for the** ``auth-user-pass`` **authentication method.** - - This option applies only to OpenVPN clients. -``` - - -```{cfgcmd} set interfaces openvpn \ authentication username \ - -**Configure the username for the** ``auth-user-pass`` **authentication method.** - -This option applies only to OpenVPN clients. -``` - - -```{cfgcmd} set interfaces openvpn \ description \ - -Configure the description for the OpenVPN interface. -``` - - -```{cfgcmd} set interfaces openvpn \ device-type \ - -**Configure the virtual network device type for the OpenVPN interface:** - -* ``tun`` **(default)**: Operates at Layer 3, encapsulating IPv4 or IPv6 packets. -* ``tap``: Operates at Layer 2, encapsulating Ethernet 802.3 frames. -``` - - -```{cfgcmd} set interfaces openvpn \ disable - -Disable the specific OpenVPN interface. -``` - - -```{cfgcmd} set interfaces openvpn \ encryption cipher \< 3des | aes128 | aes128gcm | aes192 | aes192gcm | aes256 | aes256gcm | none \> - -**Configure the static encryption cipher for the OpenVPN tunnel.** - -The ``cipher`` option maps to OpenVPN’s ``--cipher`` directive and specifies -the symmetric encryption algorithm for both control and data channels. - -This was previously the default encryption method in all OpenVPN modes. In -newer OpenVPN versions, the ``--cipher`` directive is considered **legacy** -and should be used only in compatibility scenarios. -``` - - -```{cfgcmd} set interfaces openvpn \ encryption data-ciphers \< 3des | aes128 | aes128gcm | aes192 | aes192gcm | aes256 | aes256gcm | none \> - -**Configure a prioritized list of negotiated ciphers for OpenVPN in** -``client`` **or** ``server`` **mode.** - -The ``data-ciphers`` option represents a list of supported encryption -algorithms. It corresponds to OpenVPN’s ``--data-ciphers`` directive and -enables cipher negotiation, where both peers automatically agree on a mutually -supported cipher during session startup. - -:::{note} -This option is not compatible with ``site-to-site`` mode. -::: -``` - - -```{cfgcmd} set interfaces openvpn \ encryption data-ciphers-fallback \< 3des | aes128 | aes128gcm | aes192 | aes192gcm | aes256 | aes256gcm | none \> - -**Configure the fallback cipher for** ``site-to-site`` **mode.** - -The ``data-ciphers-fallback`` option maps to OpenVPN’s ``--data-ciphers- -fallback`` directive. It defines the cipher to use if negotiation is **not -supported**. - -:::{note} -This option ensures consistent encryption between two static peers -without cipher negotiation capability. -::: -``` - - -```{cfgcmd} set interfaces openvpn \ hash \ - -Configure the hashing algorithm for the OpenVPN interface. -``` - - -```{cmdincludemd} /_include/interface-ip.txt -:var0: openvpn -:var1: vtun0 -``` - - -```{cmdincludemd} /_include/interface-ipv6.txt -:var0: openvpn -:var1: vtun0 -``` - - -```{cfgcmd} set interfaces openvpn \ keep-alive failure-count \ - -**Configure the number of tolerated keepalive packet failures.** - -Default: 60 consecutive failures. -``` - - -```{cfgcmd} set interfaces openvpn \ keep-alive interval \ - -**Configure the frequency, in seconds, at which keepalive packets are sent.** - -Default: 10 seconds. -``` - - -```{cfgcmd} set interfaces openvpn \ local-address \ - -Configure the local tunnel IP address for ``site-to-site`` mode. -``` - - -```{cfgcmd} set interfaces openvpn \ local-host \ - -**Configure the local IP address to accept connections.** - -If configured, OpenVPN binds to this IP address only. - -By default, OpenVPN binds to all interfaces. -``` - - -```{cfgcmd} set interfaces openvpn \ local-port \ - -Configure the local port to accept connections. -``` - - -```{cfgcmd} set interfaces openvpn \ mirror egress \ - -Configure mirroring of outgoing traffic from this OpenVPN interface to the -designated monitor interface. -``` - - -```{cfgcmd} set interfaces openvpn \ mirror ingress \ - -Configure mirroring of incoming traffic from this OpenVPN interface to the -designated monitor interface. -``` - - -```{cfgcmd} set interfaces openvpn \ mode \ - -**Configure OpenVPN operation mode:** - -* ``site-to-site``: Establishes a site-to-site VPN connection. -* ``client``: Operates as a client in server-client mode. -* ``server``: Operates as a server in server-client mode. -``` - -### OpenVPN Data Channel Offload (DCO) - -OpenVPN {abbr}`DCO (Data Channel Offload)` improves the performance of -encrypted OpenVPN data processing by keeping most data handling in the kernel -and avoiding frequent context switches between the kernel and user space. - -As a result, packet processing becomes more efficient and may utilize hardware -encryption offload support available in the kernel. - -:::{note} -- {abbr}`DCO (Data Channel Offload)` is an **experimental**, not fully supported - OpenVPN feature. Some OpenVPN features and deployment scenarios are **not - compatible** with {abbr}`DCO (Data Channel Offload)`. - - For a complete list of supported features, visit: - -- {abbr}`DCO (Data Channel Offload)` is configured per tunnel and disabled - by default. Existing tunnels operate without {abbr}`DCO (Data Channel - Offload)` unless it is explicitly enabled. -- Enabling {abbr}`DCO (Data Channel Offload)` resets the interface. -::: - -**Best practice:** Create a new tunnel with {abbr}`DCO (Data Channel Offload)` -enabled to avoid compatibility issues with existing clients. - -```{cfgcmd} set interfaces openvpn \ offload dco - - **Enable** {abbr}`DCO (Data Channel Offload)` **for the specified OpenVPN - interface.** - - Example: - - :::{code-block} none - set interfaces openvpn vtun0 offload dco - ::: - This command enables {abbr}`DCO (Data Channel Offload)` and loads the required - kernel module. -``` - - -```{cfgcmd} set interfaces openvpn \ openvpn-option \ - -**Add raw OpenVPN configuration options to the openvpn.conf file.** - -OpenVPN provides many configuration options, but not all are available in the -VyOS CLI. - -If a required option is missing, you may submit a feature request at -Phabricator so all users can benefit from it (see Contributing/Issues and Features). - -Alternatively, use ``openvpn-option`` to pass raw OpenVPN configuration options -to the openvpn.conf file. - -:::{warning} -Use this option only as a last resort. Invalid options or syntax -may prevent OpenVPN from starting. Check system logs for errors after applying -changes. -::: -Example: - -:::{code-block} none -set interfaces openvpn vtun0 openvpn-option 'persist-key' -::: -This command adds ``persist-key`` to the configuration file. This solves the -problem by persisting keys across resets, so they do not need to be re-read. - -:::{code-block} none -set interfaces openvpn vtun0 openvpn-option 'route-up "/config/auth/tun_up.sh arg1"' -::: -This command adds ``route-up "/config/auth/tun_up.sh arg1"`` to the -configuration file. This option is executed after connection authentication, -either immediately or after a short delay, as defined. - -Ensure the path and arguments are enclosed in single or double quotes. - -:::{note} -Some raw configuration options require quotes. To include them, use -the " statement. -::: -``` - - -```{cfgcmd} set interfaces openvpn \ persistent-tunnel - -**Enable always-active mode for the TUN/TAP device.** - -When enabled, the TUN/TAP device remains active upon connection resets or -daemon reloads. -``` - - -```{cfgcmd} set interfaces openvpn \ protocol \ - -**Configure the protocol for OpenVPN communication with a remote host:** - -* ``udp`` **(default)**: Uses the UDP protocol. -* ``tcp-passive``: Uses the TCP protocol and accepts connections passively. -* ``tcp-active``: Uses the TCP protocol and initiates connections actively. -``` - - -```{cfgcmd} set interfaces openvpn \ redirect \ - -Enable redirection of incoming packets to the specified interface. -``` - - -```{cfgcmd} set interfaces openvpn \ remote-address \ - -Configure the remote tunnel IP address for site-to-site mode. -``` - - -```{cfgcmd} set interfaces openvpn \ remote-host \
- -**Configure the IPv4/IPv6 address or hostname for a server device if OpenVPN -runs in client mode.** - -This setting is not used in server mode. -``` - - -```{cfgcmd} set interfaces openvpn \ remote-port \ - -Configure the remote port to connect to the server. -``` - - -```{cfgcmd} set interfaces openvpn \ replace-default-route - -Configure the OpenVPN tunnel as the default route. -``` - - -```{cfgcmd} set interfaces openvpn \ server bridge disable - -Disable the given instance. -``` - - -```{cfgcmd} set interfaces openvpn \ server bridge gateway \ - -Configure the gateway IP address. -``` - - -```{cfgcmd} set interfaces openvpn \ server bridge start \ - -Configure the first IP address in the pool to allocate to connecting clients. -``` - - -```{cfgcmd} set interfaces openvpn \ server bridge stop \ - -Configure the last IP address in the pool to allocate to connecting clients. -``` - - -```{cfgcmd} set interfaces openvpn \ server bridge subnet-mask \ - -Configure the subnet mask pushed to dynamic clients. -``` - - -```{cfgcmd} set interfaces openvpn \ server client \ - -Configure the Common Name (CN) specified in the client certificate. -``` - - -```{cfgcmd} set interfaces openvpn \ server client \ disable - -Disable the client connection. -``` - - -```{cfgcmd} set interfaces openvpn \ server client \ ip \ - -Configure the IPv4/IPv6 address for the client. -``` - - -```{cfgcmd} set interfaces openvpn \ server client \ push-route \ - -Configure a route to be pushed to the specific client. -``` - - -```{cfgcmd} set interfaces openvpn \ server client \ subnet \ - -**Configure a fixed subnet to be routed from the server to the specified -client.** - -Used as OpenVPN’s ``iroute`` directive. -``` - - -```{cfgcmd} set interfaces openvpn \ server client-ip-pool start \ - -Configure the first IP address in the subnet's IPv4 pool to be dynamically -allocated to connecting clients. -``` - - -```{cfgcmd} set interfaces openvpn \ server client-ip-pool stop \ - -Configure the last IP address in the subnet's IPv4 pool to be dynamically -allocated to connecting clients. -``` - - -```{cfgcmd} set interfaces openvpn \ server client-ip-pool subnet \ - -**Configure the subnet mask pushed to dynamic clients.** - -Use this command only for the TAP device type. Do not use it for bridged -interfaces. -``` - - -```{cfgcmd} set interfaces openvpn \ server client-ipv6-pool base \ - -Configure the IPv6 address pool for dynamic assignment to clients. -``` - - -```{cfgcmd} set interfaces openvpn \ server domain-name \ - -Configure the DNS suffix to be pushed to all clients. -``` - - -```{cfgcmd} set interfaces openvpn \ server max-connections \<1-4096\> - -Configure the maximum number of client connections. -``` - - -```{cfgcmd} set interfaces openvpn \ server mfa totp challenge \ - -If enabled, openvpn-otp expects a password as a result of the challenge/ -response protocol. -``` - - -```{cfgcmd} set interfaces openvpn \ server mfa totp digits \<1-65535\> - -**Configure the number of digits to use for the** {abbr}`TOTP (Time-based -One-Time Password)` **hash.** - -Default: 6. -``` - - -```{cfgcmd} set interfaces openvpn \ server mfa totp drift \<1-65535\> - -**Configure the time drift in seconds.** - -Default: 0. -``` - - -```{cfgcmd} set interfaces openvpn \ server mfa totp slop \<1-65535\> - -**Configure the allowed clock slop in seconds.** - -Default: 180. -``` - - -```{cfgcmd} set interfaces openvpn \ server mfa totp step \<1-65535\> - -**Configure the step value for** {abbr}`TOTP (Time-based One-Time Password)` -**in seconds.** - -Default: 30. -``` - - -```{cfgcmd} set interfaces openvpn \ server name-server \ - -Define the client DNS configuration to be used with the connection. -``` - - -```{cfgcmd} set interfaces openvpn \ server push-route \ - -Configure the route to be pushed to all clients. -``` - - -```{cfgcmd} set interfaces openvpn \ server reject-unconfigured-client - -Reject connections from clients that are not explicitly configured. -``` - - -```{cfgcmd} set interfaces openvpn \ server subnet \ - -**Configure the IPv4 or IPv6 network.** - -This parameter is mandatory when operating in server mode. -``` - - -```{cfgcmd} set interfaces openvpn \ server topology \< net30 | point-to-point | subnet\> - -**Configure the virtual addressing topology for** ``tun`` **mode.** - -This command does not affect ``tap`` mode, which always uses the ``subnet`` -topology. - -* ``subnet`` **(default)**: Allocates a single IP address to each connecting client. -This is the recommended topology. -* ``net30``: Allocates a /30 subnet to each connecting client. This is a legacy -topology used to support Windows clients. It is now effectively deprecated. -* ``point-to-point``: Creates a point-to-point topology where the remote -endpoint of the client’s ``tun`` interface always points to the local endpoint -of the server’s ``tun`` interface. - -Like ``subnet``, this topology allocates a single IP address per client. Use it -only if no clients run Windows operating systems. -``` -```{cfgcmd} set interfaces openvpn \ shared-secret-key \ - -Configure the static secret key for a site-to-site OpenVPN connection. -``` -```{cfgcmd} set interfaces openvpn \ tls auth-key \ - -**Configure the TLS secret key for tls-auth.** - -This adds an HMAC signature to all SSL/TLS handshake packets to verify -integrity. - -Use ``run generate pki openvpn shared-secret install `` to generate -the key. -``` -```{cfgcmd} set interfaces openvpn \ tls ca-certificate \ - -Configure the Certificate Authority chain in the PKI configuration. -``` -```{cfgcmd} set interfaces openvpn \ tls certificate \ - -Configure the certificate name in the PKI configuration. -``` -```{cfgcmd} set interfaces openvpn \ tls crypt-key - -Configure a shared secret key to provide an additional level of security, -a variant similar to tls-auth. -``` -```{cfgcmd} set interfaces openvpn \ tls dh-params - -Configure Diffie-Hellman parameters for server mode. -``` -```{cfgcmd} set interfaces openvpn \ tls peer-fingerprint \ - -Configure the peer certificate SHA256 fingerprint for site-to-site mode. -``` -```{cfgcmd} set interfaces openvpn \ tls role \ - -**Configure the TLS negotiation role, preferably used in site-to-site mode:** -* ``active``: Initiates TLS negotiation actively. -* ``passive``: Waits for incoming TLS connections. -``` -```{cfgcmd} set interfaces openvpn \ tls tls-version-min \<1.0 | 1.1 | 1.2 | 1.3 \> - -Configure the minimum TLS version to be accepted from the peer. -``` -```{cfgcmd} set interfaces openvpn \ use-lzo-compression - -Configure fast LZO compression on this TUN/TAP interface. -``` -```{cfgcmd} set interfaces openvpn \ vrf \ - -Assign the interface to a specific VRF instance. -``` - -## Operation mode - -```{opcmd} show openvpn site-to-site - -Show tunnel status for OpenVPN site-to-site interfaces. -``` -```{opcmd} show openvpn server - -Show tunnel status for OpenVPN server interfaces. -``` -```{opcmd} show openvpn client - -Show tunnel status for OpenVPN client interfaces. -``` -```{opcmd} show log openvpn - -Show logs for all OpenVPN interfaces. -``` -```{opcmd} show log openvpn interface \ - -Show logs for the specific OpenVPN interface. -``` -```{opcmd} reset openvpn client \ - -Reset the specified OpenVPN client. -``` -```{opcmd} reset openvpn interface \ - -Reset the OpenVPN process on the specified interface. -``` -```{opcmd} generate openvpn client-config interface \ ca \ certificate \ - -Generate an OpenVPN client configuration file in the .ovpn format for client machines. -``` - -## Examples - -This section covers examples of OpenVPN configurations for various deployments. - -```{toctree} -:includehidden: true -:maxdepth: 1 - -openvpn-examples -``` - diff --git a/docs/configuration/interfaces/md-pppoe.md b/docs/configuration/interfaces/md-pppoe.md deleted file mode 100644 index b79f41a2..00000000 --- a/docs/configuration/interfaces/md-pppoe.md +++ /dev/null @@ -1,419 +0,0 @@ ---- -lastproofread: '2026-03-03' ---- - -(pppoe-interface)= - -# PPPoE - -{abbr}`PPPoE (Point-to-Point Protocol over Ethernet)` is a network protocol -that encapsulates PPP frames within Ethernet frames. -It's often used for connecting ISP clients to a broadband access server. - -## Configuration - -### Common interface configuration - -```{cmdincludemd} /_include/interface-description.txt -:var0: pppoe -:var1: pppoe0 -``` - -```{cmdincludemd} /_include/interface-disable.txt -:var0: pppoe -:var1: pppoe0 -``` - -```{cmdincludemd} /_include/interface-mtu.txt -:var0: pppoe -:var1: pppoe0 -``` - -```{cmdincludemd} /_include/interface-vrf.txt -:var0: pppoe -:var1: pppoe0 -``` - - -### PPPoE options - -```{cfgcmd} set interfaces pppoe \ access-concentrator \ - -**Configure the name of the target access concentrator for the PPPoE session.** - -During the PPPoE discovery process, the client sends a PPPoE initiation packet. -Multiple access concentrators may respond with offer packets, and the client -selects one of them. - -This setting restricts the client to establishing sessions only with the -specified access concentrator. -``` - -```{cfgcmd} set interfaces pppoe \ authentication username \ - -**Configure the username for PPPoE session authentication.** - -Although authentication is optional in the interface configuration, most ISPs -require it to establish a connection. -``` - -```{cfgcmd} set interfaces pppoe \ authentication password \ - -**Configure the password for PPPoE session authentication.** - -Although authentication is optional in the interface configuration, most ISPs -require it to establish a connection. -``` - -```{cfgcmd} set interfaces pppoe \ connect-on-demand - -**Enable dial-on-demand on the PPPoE interface.** - -When enabled, the system establishes a PPPoE connection only when traffic -passes through the interface. If the connection fails, it is reestablished when -traffic resumes. - -For on-demand connections, you must also configure an ``idle-timeout`` period -to disconnect the session after inactivity. - -:::{note} -Setting the idle timeout to zero, or leaving it unconfigured, keeps -the connection active continuously once established. -::: - -By default, the PPPoE connection is established at boot and remains active -continuously; if the connection fails, it is reestablished immediately. -``` - -```{cfgcmd} set interfaces pppoe \ no-default-route - -Request an IP address from the PPPoE server without installing a default route. - -Example: - -:::{code-block} none -set interfaces pppoe pppoe0 no-default-route -::: - -:::{note} -Introduced in VyOS 1.4, this command inverts the logic of the former -``default-route`` CLI option. -::: -``` - -```{cfgcmd} set interfaces pppoe \ default-route-distance \ - -Configure the distance for the default gateway provided by the PPPoE server. - -Example: - -:::{code-block} none -set interfaces pppoe pppoe0 default-route-distance 220 -::: -``` - -```{cfgcmd} set interfaces pppoe \ mru \ - -**Configure the** {abbr}`MRU (Maximum Receive Unit)` **for the PPPoE -interface.** - -This setting instructs the pppd daemon to restrict the remote peer from sending -packets larger than the configured MRU. Allowed MRU values range from 128 to -16384 bytes. - -An MRU of 296 is suitable for very slow links (40 bytes for the TCP/IP header -and 256 bytes for data). - -The default MRU is 1492 bytes. - -:::{note} -When using the IPv6 protocol, the MRU must be at least 1280 bytes. -::: -``` - -```{cfgcmd} set interfaces pppoe \ idle-timeout \ - -**Configure the idle timeout for on-demand PPPoE sessions.** - -This setting defines how long the connection remains active without any traffic -before being disconnected. - -:::{note} -Setting the idle timeout to zero, or leaving it unconfigured, keeps -the connection active continuously once established. -::: -``` - -```{cfgcmd} set interfaces pppoe \ holdoff \ - -**Configure the redial delay for persistent PPPoE sessions.** - -If a persistent session (with ``connect-on-demand`` disabled) is terminated by -the remote peer or drops unexpectedly, the router waits the specified interval -before attempting to reconnect. - -The default redial delay is 30 seconds. -``` - -```{cfgcmd} set interfaces pppoe \ local-address \ - -**Configure the local endpoint IP address for PPPoE sessions.** - -By default, this IP address is negotiated. -``` - -```{cfgcmd} set interfaces pppoe \ no-peer-dns - -Disable the installation of advertised DNS nameservers on the local system. -``` - -```{cfgcmd} set interfaces pppoe \ remote-address \ - -**Configure the remote endpoint IP address for PPPoE sessions.** - -By default, this IP address is negotiated. -``` - -```{cfgcmd} set interfaces pppoe \ service-name \ - -**Configure the service name of the target access concentrator for the PPPoE -session.** - -By default, the PPPoE interface connects to any available access concentrator. -``` - -```{cfgcmd} set interfaces pppoe \ source-interface \ - -**Configure the underlying interface for the PPPoE connection.** - -Each PPPoE connection is established over an underlying interface, which can be -an Ethernet interface, a VIF, or a bonding interface. -``` - -```{cfgcmd} set interfaces pppoe \ ip adjust-mss \ - -**Configure the** {abbr}`MSS (Maximum Segment Size)` **advertised in outgoing -TCP SYN packets on the specified interface.** - -By clamping the MSS value in TCP SYN packets, you instruct the remote side not -to send packets larger than the specified size. This helps prevent connection -issues if {abbr}`PMTUD (Path MTU Discovery)` fails. - -The following options are available: - -* ``mss``: Sets the MSS to a specific value in bytes. -* ``clamp-mss-to-pmtu``: Sets the MSS to the interface’s MTU minus 40 bytes for - IPv4 traffic (20 bytes for the IPv4 header and 20 bytes for the TCP header). - This option is recommended to automatically set the proper value. - -:::{note} -Introduced in VyOS 1.4, this command replaces the older ``set firewall -options interface adjust-mss `` syntax. -::: -``` - -```{cfgcmd} set interfaces pppoe \ ip disable-forwarding - -**Configure the interface for host or router behavior.** - -If configured, the interface switches to host mode, and IPv4 forwarding is -disabled on it. -``` - -```{cfgcmd} set interfaces pppoe \ ip source-validation \ - -**Configure source IP address validation using** -{abbr}`RPF (Reverse Path Forwarding)` **on this interface, as specified in** -{rfc}`3704`. - -The following options are available: - -* ``strict``: Each incoming packet’s source IP address is checked against the - {abbr}`FIB (Forwarding Information Base)`. If the interface is not the best - route back to that source, validation fails, and the packet is dropped. -* ``loose``: Each incoming packet’s source IP address is checked against the - {abbr}`FIB (Forwarding Information Base)`. If the source IP address is - unreachable through any interface, validation fails. -* ``disable``: No source IP address validation is performed. All incoming - packets are accepted. - -{rfc}`3704` recommends enabling ``strict`` mode to prevent IP spoofing, such as -DDoS attacks. For asymmetric or other complex routing scenarios, use ``loose`` -mode. -``` - - -#### IPv6 - -```{cfgcmd} set interfaces pppoe \ ipv6 address autoconf - -Enable IPv6 address assignment via {abbr}`SLAAC (Stateless Address -Auto-Configuration)` on this interface. -``` - -```{cfgcmd} set interfaces pppoe \ ipv6 adjust-mss \ - -**Configure the** {abbr}`MSS (Maximum Segment Size)` **advertised in outgoing -TCP SYN packets on the specified interface.** - -By clamping the MSS value in TCP SYN packets, you instruct the remote side not -to send packets larger than the specified size. This helps prevent connection -issues if {abbr}`PMTUD (Path MTU Discovery)` fails. - -The following options are available: - -* ``mss``: Sets the MSS to a specific value in bytes. -* ``clamp-mss-to-pmtu``: Sets the MSS to the interface’s MTU minus 60 bytes for - IPv6 traffic (40 bytes for the IPv6 header and 20 bytes for the TCP header). - This option is recommended to automatically set the proper value. - -:::{note} -Introduced in VyOS 1.4, this command replaces the older ``set firewall -options interface adjust-mss `` syntax. -::: -``` - -```{cfgcmd} set interfaces pppoe \ ipv6 disable-forwarding - -**Configure the interface for host or router behavior.** - -If configured, the interface switches to host mode, and IPv6 forwarding is -disabled on it. -``` - -```{cmdincludemd} /_include/interface-dhcpv6-prefix-delegation.txt -:var0: pppoe -:var1: pppoe0 -``` - - -## Operation - -```{opcmd} show interfaces pppoe \ - -Show detailed information about a specific PPPoE interface. - -:::{code-block} none -vyos@vyos:~$ show interfaces pppoe pppoe0 -pppoe0: mtu 1492 qdisc pfifo_fast state UNKNOWN group default qlen 3 - link/ppp - inet 192.0.2.1 peer 192.0.2.255/32 scope global pppoe0 - valid_lft forever preferred_lft forever - - RX: bytes packets errors dropped overrun mcast - 7002658233 5064967 0 0 0 0 - TX: bytes packets errors dropped carrier collisions - 533822843 1620173 0 0 0 0 -::: -``` - -```{opcmd} show interfaces pppoe \ queue - -Show queue information for a specific PPPoE interface. - -:::{code-block} none -vyos@vyos:~$ show interfaces pppoe pppoe0 queue -qdisc pfifo_fast 0: root refcnt 2 bands 3 priomap 1 2 2 2 1 2 0 0 1 1 1 1 1 1 1 1 - Sent 534625359 bytes 1626761 pkt (dropped 62, overlimits 0 requeues 0) - backlog 0b 0p requeues 0 -::: -``` - - -### Connect/disconnect - -```{opcmd} disconnect interface \ - -Disconnect the specified interface. -``` - -```{opcmd} connect interface \ - -Initiate a session on the specified interface. -``` - - -## Example - -### PPPoE over DSL - -**Configuration scenario:** - -- Your ISP's DSL modem is connected to the `eth0` interface on your VyOS - router. -- Your ISP does not require VLAN tagging. -- PPPoE credentials are provided by your ISP. The typical username format is - `name@host.net`, though this may vary. - -**Configuration notes:** - -- The maximum MTU size for DSL is 1492 because of PPPoE overhead. If you are - switching from a DHCP-based ISP (e.g., a standard cable connection), ensure - VPN links have MTU sizes adjusted accordingly. -- To ignore ISP-provided nameservers and use only your statically configured - ones, set the `name-server` option to `none`. -- A default route is automatically installed once the interface is up. To - change this behavior, use the `no-default-route` CLI option. - -:::{note} -The PPPoE configuration syntax changed after VyOS 1.2 (Crux) and is -automatically migrated during an upgrade. -::: - -```none -set interfaces pppoe pppoe0 authentication username 'userid' -set interfaces pppoe pppoe0 authentication password 'secret' -set interfaces pppoe pppoe0 source-interface 'eth0' -``` - -Secure your setup by creating rules matching the `pppoe0` interface in the -firewall chains: - -```none -set firewall ipv4 input filter rule 10 inbound-interface name 'pppoe0' -set firewall ipv4 forward filter rule 10 inbound-interface name 'pppoe0' -``` - - -### PPPoE over VLAN - -Some ISPs require PPPoE connections to be -established over a VLAN interface. This specific topology is fully supported by -VyOS. - -The following configuration establishes the PPPoE connection through VLAN 7, -which is the default VLAN for Deutsche Telekom: - -```none -set interfaces pppoe pppoe0 authentication username 'userid' -set interfaces pppoe pppoe0 authentication password 'secret' -set interfaces pppoe pppoe0 source-interface 'eth0.7' -``` - - -#### IPv6 DHCPv6 prefix delegation - -**Configuration scenario:** - -The following configuration establishes a PPPoE session on the `eth1` -interface, requests a `/56` IPv6 prefix delegation from the ISP, and assigns -a `/64` subnet from that delegation to the `eth0` interface. - -**Configuration notes:** - -- The IPv6 address assigned to `eth0` is `::1/64`. -- If you do not know your delegated prefix size, begin with `sla-len 0`. -- To advertise the prefix on the `eth0` link, configure IPv6 Router - Advertisement. - -```none -set interfaces pppoe pppoe0 authentication username vyos -set interfaces pppoe pppoe0 authentication password vyos -set interfaces pppoe pppoe0 dhcpv6-options pd 0 interface eth0 address '1' -set interfaces pppoe pppoe0 dhcpv6-options pd 0 interface eth0 sla-id '0' -set interfaces pppoe pppoe0 dhcpv6-options pd 0 length '56' -set interfaces pppoe pppoe0 ipv6 address autoconf -set interfaces pppoe pppoe0 source-interface eth1 - -set service router-advert interface eth0 prefix ::/64 -``` diff --git a/docs/configuration/interfaces/md-pseudo-ethernet.md b/docs/configuration/interfaces/md-pseudo-ethernet.md deleted file mode 100644 index fc8833eb..00000000 --- a/docs/configuration/interfaces/md-pseudo-ethernet.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -lastproofread: '2026-03-05' ---- - -(pseudo-ethernet-interface)= - -# MACVLAN (pseudo-Ethernet) - -MACVLAN, or pseudo-Ethernet interfaces, operate as logical subinterfaces of -standard Ethernet interfaces. Each subinterface has a unique MAC address but -shares a single physical Ethernet port. -That allows the user to send packets from different source IPv4 or IPv6 addresses -using a different MAC address. - -Pseudo-Ethernet interfaces behave like physical Ethernet interfaces. They -support IPv4 and IPv6 addressing, can obtain IP addresses through DHCP or -DHCPv6, and are mapped to a physical Ethernet port. They inherit -characteristics such as speed and duplex from their parent interface and can -be referenced like standard Ethernet interfaces once created. - -```{eval-rst} -Pseudo-Ethernet interfaces may not work in environments that require a - :abbr:`NIC (Network Interface Card)` to have only one MAC address. - This includes: - - * VMware machines with default settings. - * Network switches that permit only a single MAC address. - * xDSL modems that learn the NIC's MAC address. -``` - -## Configuration - -### Common interface configuration - -```{cmdincludemd} /_include/interface-common-with-dhcp.txt -:var0: pseudo-ethernet -:var1: peth0 -``` - -### MACVLAN (pseudo-Ethernet) options - -```{cfgcmd} set interfaces pseudo-ethernet \ source-interface \ - -Assign a physical Ethernet interface to the specified pseudo-Ethernet interface. -``` - -### VLAN - -```{cmdincludemd} /_include/interface-vlan-8021q.txt -:var0: pseudo-ethernet -:var1: peth0 -``` \ No newline at end of file diff --git a/docs/configuration/interfaces/md-sstp-client.md b/docs/configuration/interfaces/md-sstp-client.md deleted file mode 100644 index da98aecd..00000000 --- a/docs/configuration/interfaces/md-sstp-client.md +++ /dev/null @@ -1,170 +0,0 @@ ---- -lastproofread: '2026-03-16' ---- - -(sstp-client-interface)= - -# SSTP client - -{abbr}`SSTP (Secure Socket Tunneling Protocol)` transports PPP traffic over an -SSL/TLS channel, providing transport-level security through key negotiation, -encryption, and traffic integrity checking. The use of SSL/TLS over TCP port -443 (by default, the port can be changed) allows SSTP to pass through virtually -all firewalls and proxy servers, except for authenticated web proxies. - -:::{note} -VyOS includes a built-in SSTP server. For more information, see -{ref}`sstp`. -::: - -## Configuration - -### Common interface configuration - -```{cmdincludemd} /_include/interface-description.txt -:var0: sstpc -:var1: sstpc0 -``` - -```{cmdincludemd} /_include/interface-disable.txt -:var0: sstpc -:var1: sstpc0 -``` - -```{cmdincludemd} /_include/interface-mtu.txt -:var0: sstpc -:var1: sstpc0 -``` - -```{cmdincludemd} /_include/interface-vrf.txt -:var0: sstpc -:var1: sstpc0 -``` - - -### SSTP client options - -```{cfgcmd} set interfaces sstpc \ no-default-route - -Request an IP address from the SSTP server without installing a default route. - -Example: - -:::{code-block} none -set interfaces sstpc sstpc0 no-default-route -::: -:::{note} Introduced in VyOS 1.4, this command inverts the logic of the former -``default-route`` CLI option. -::: -``` - -```{cfgcmd} set interfaces sstpc \ default-route-distance \ - -Configure the distance for the default gateway provided by the SSTP server. - -Example: - -:::{code-block} none -set interfaces sstpc sstpc0 default-route-distance 220 -::: -``` - -```{cfgcmd} set interfaces sstpc \ no-peer-dns - -Disable the installation of advertised DNS nameservers on the local system. -``` - -```{cfgcmd} set interfaces sstpc \ server \ - -**Configure the remote SSTP server address for the client connection.** - -The address can be either an IP address or a {abbr}`FQDN (Fully Qualified -Domain Name)`. -``` - -```{cfgcmd} set interfaces sstpc \ ip adjust-mss \ - -**Configure the** {abbr}`MSS (Maximum Segment Size)` **advertised in outgoing -TCP SYN packets on the specified interface.** - -By clamping the MSS value in TCP SYN packets, you instruct the remote side not -to send packets larger than the specified size. This helps prevent connection -issues if {abbr}`PMTUD (Path MTU Discovery)` fails. - -The following options are available: - -* ``mss``: Sets the MSS to a specific value in bytes. -* ``clamp-mss-to-pmtu``: Sets the MSS to the interface’s MTU minus 40 bytes for -IPv4 traffic (20 bytes for the IPv4 header and 20 bytes for the TCP header). -This option is recommended to automatically set the proper value. - -:::{note} Introduced in VyOS 1.4, this command replaces the older ``set firewall -options interface adjust-mss `` syntax. -::: -``` - -```{cfgcmd} set interfaces sstpc \ ip disable-forwarding - -**Configure the interface for host or router behavior.** - -If configured, the interface switches to host mode, and IPv4 forwarding is -disabled on it. -``` - -```{cfgcmd} set interfaces sstpc \ ip source-validation \ - -**Configure source IP address validation using** -{abbr}`RPF (Reverse Path Forwarding)` **on this interface, as specified in** -{rfc}`3704`. - -The following options are available: - -* ``strict``: Each incoming packet’s source IP address is checked against the -{abbr}`FIB (Forwarding Information Base)`. If the interface is not the best -route back to that source, validation fails, and the packet is dropped. -* ``loose``: Each incoming packet’s source IP address is checked against the -{abbr}`FIB (Forwarding Information Base)`. If the source IP address is -unreachable through any interface, validation fails. -* ``disable``: No source IP address validation is performed. All incoming -packets are accepted. - -{rfc}`3704` recommends enabling ``strict`` mode to prevent IP spoofing, such as -DDoS attacks. For asymmetric or other complex routing scenarios, use ``loose`` -mode. -``` - - -## Operation - -```{opcmd} show interfaces sstpc \ - -Show detailed information about the specified interface. - -:::{code-block} none -vyos@vyos:~$ show interfaces sstpc sstpc10 -sstpc10: mtu 1500 qdisc pfifo_fast state UNKNOWN group default qlen 3 - link/ppp - inet 192.0.2.5 peer 192.0.2.254/32 scope global sstpc10 - valid_lft forever preferred_lft forever - inet6 fe80::fd53:c7ff:fe8b:144f/64 scope link - valid_lft forever preferred_lft forever - - RX: bytes packets errors dropped overrun mcast - 215 9 0 0 0 0 - TX: bytes packets errors dropped carrier collisions - 539 14 0 0 0 0 -::: -``` - - -### Connect/disconnect - -```{opcmd} disconnect interface \ - -Disconnect the specified interface. -``` - -```{opcmd} connect interface \ - -Initiate a session on the specified interface. -``` \ No newline at end of file diff --git a/docs/configuration/interfaces/md-tunnel.md b/docs/configuration/interfaces/md-tunnel.md deleted file mode 100644 index 9c9885d2..00000000 --- a/docs/configuration/interfaces/md-tunnel.md +++ /dev/null @@ -1,309 +0,0 @@ ---- -lastproofread: '2026-01-23' ---- - -(tunnel-interface)= - -# Tunnel - -Tunnel interfaces are virtual links that transmit encapsulated traffic between -private networks or hosts across public infrastructure, such as the Internet. -They operate using encapsulation protocols to wrap original traffic for -transport. The supported protocols include {abbr}`GRE (Generic Routing -Encapsulation)`, IPIP, IPIP6, IP6IP6, and 6in4 (SIT). - -While {abbr}`GRE (Generic Routing Encapsulation)` is often the preferred -one-size-fits-all solution due to its versatility, other encapsulation -protocols may be better suited for specific use cases. - -VyOS uses a single tunnel interface type for all of these protocols. There are -no separate {abbr}`GRE (Generic Routing Encapsulation)`, IPIP, or IP6IP6 -interface types; instead, the desired encapsulation protocol is selected within -the `set interfaces tunnel` configuration. - -Configuration options for each protocol are described below. - -:::{warning} -Do not change the encapsulation type for already configured tunnel -interfaces, as this may break their dependent configurations. -::: - -## Common interface configuration - -```{cmdincludemd} /_include/interface-address.txt -:var0: tunnel -:var1: tun0 -``` - -```{cmdincludemd} /_include/interface-common-without-mac.txt -:var0: tunnel -:var1: tun0 -``` - - -## IPIP - -IPIP is a straightforward encapsulation protocol defined in RFC 2003. It -encapsulates one IPv4 packet inside another IPv4 packet. - -Tunnels with IPIP encapsulation do not have protocol-specific configuration -options except for explicitly defining the encapsulation type as IPIP (see -the example below). - -Example: - -```none -set interfaces tunnel tun0 encapsulation ipip -set interfaces tunnel tun0 source-address 192.0.2.10 -set interfaces tunnel tun0 remote 203.0.113.20 -set interfaces tunnel tun0 address 192.168.100.200/24 -``` - - -## IP6IP6 - -IP6IP6 is the IPv6 counterpart to IPIP. It encapsulates one IPv6 packet inside -another IPv6 packet. - -Similar to their IPIP counterparts, tunnels with IP6IP6 encapsulation do not -have protocol-specific configuration options except for explicitly defining -the encapsulation type as IP6IP6. - -Example: - -```none -set interfaces tunnel tun0 encapsulation ip6ip6 -set interfaces tunnel tun0 source-address 2001:db8:aa::1 -set interfaces tunnel tun0 remote 2001:db8:aa::2 -set interfaces tunnel tun0 address 2001:db8:bb::1/64 -``` - - -## IPIP6 - -IPIP6 is an encapsulation protocol that wraps IPv4 packets inside IPv6 packets. - -Similar to IPIP and IP6IP6, protocol-specific configuration for tunnels with -IPIP6 encapsulation only requires defining the encapsulation type as IP6IP6. - -Example: - -```none -set interfaces tunnel tun0 encapsulation ipip6 -set interfaces tunnel tun0 source-address 2001:db8:aa::1 -set interfaces tunnel tun0 remote 2001:db8:aa::2 -set interfaces tunnel tun0 address 192.168.70.80/24 -``` - - -## 6in4 (SIT) - -6in4, also known as {abbr}`SIT (Simple Internet Transition)`, is an -encapsulation protocol defined in {rfc}`4213` that wraps IPv6 packets -inside IPv4 packets. The encapsulating IPv4 headers use IP protocol number 41, -which is reserved exclusively for IPv6 encapsulation. - -The encapsulation process adds a 20-byte IPv4 header to each IPv6 packet. -Consequently, 6in4 tunnel interfaces can transmit IPv6 packets up to 1480 bytes -over an underlying network with a standard MTU of 1500 bytes without -fragmentation. - -6in4 tunnel interfaces are frequently used by IPv6 tunnel brokers (such as -[Hurricane Electric]) to connect isolated IPv6 networks or individual hosts to -the IPv6 internet. - -Example: - -```none -set interfaces tunnel tun0 encapsulation sit -set interfaces tunnel tun0 source-address 192.0.2.10 -set interfaces tunnel tun0 remote 192.0.2.20 -set interfaces tunnel tun0 address 2001:db8:bb::1/64 -``` - -:::{seealso} -For a practical configuration example, see the -{ref}`Tunnelbroker.net (IPv6) ` section. -::: - -## Generic Routing Encapsulation (GRE) - -{abbr}`GRE (Generic Routing Encapsulation)` is a versatile encapsulation -protocol defined in RFC 2784. Unlike simpler protocols such as IPIP, it allows -both IPv4 and IPv6 to be transported through the same tunnel. - -{abbr}`GRE (Generic Routing Encapsulation)` encapsulates original data packets -by adding a {abbr}`GRE (Generic Routing Encapsulation)` header, followed by an -IP header (the delivery header). The delivery header uses IP protocol number 47 -to identify {abbr}`GRE (Generic Routing Encapsulation)`-encapsulated traffic. - -In VyOS, {abbr}`GRE (Generic Routing Encapsulation)` tunnels can be established -over both IPv4 (encapsulation `gre`) and IPv6 (encapsulation `ip6gre`) -transport networks. - -### Configuration - -To configure a {abbr}`GRE (Generic Routing Encapsulation)` tunnel, you need to -define a tunnel source IP address, a tunnel destination IP address, an -encapsulation type ({abbr}`GRE (Generic Routing Encapsulation)`), and a tunnel -interface IP address. - -Example: - -The following example shows how to configure an IPv4/IPv6-over-IPv6 {abbr}`GRE -(Generic Routing Encapsulation)` tunnel between a VyOS router and a Linux host -running `systemd-networkd`. - -**VyOS router:** - -```none -set interfaces tunnel tun101 address '2001:db8:feed:beef::1/126' -set interfaces tunnel tun101 address '192.168.5.1/30' -set interfaces tunnel tun101 encapsulation 'ip6gre' -set interfaces tunnel tun101 source-address '2001:db8:babe:face::3afe:3' -set interfaces tunnel tun101 remote '2001:db8:9bb:3ce::5' -``` - -**Linux** `systemd-networkd`: - -The `systemd-networkd` setup requires two configuration files: `xxx.netdev` -to create the {abbr}`GRE (Generic Routing Encapsulation)` tunnel interface, and -`xxx.network` to assign IP addresses to it. - -```none -# cat /etc/systemd/network/gre-example.netdev -[NetDev] -Name=gre-example -Kind=ip6gre -MTUBytes=14180 - -[Tunnel] -Remote=2001:db8:babe:face::3afe:3 - - -# cat /etc/systemd/network/gre-example.network -[Match] -Name=gre-example - -[Network] -Address=2001:db8:feed:beef::2/126 - -[Address] -Address=192.168.5.2/30 -``` - - -### GRE keys - -A GRE key is an optional 32-bit field in the GRE header that allows multiple -GRE tunnels to operate between the same source and destination endpoints. When -a packet arrives, the receiver checks the GRE key to determine which tunnel -interface should process it. - -Although it may sound security-related, the GRE key is only an identifier and -provides no encryption or data protection. - -Example: - -```none -set interfaces tunnel tun0 source-address 192.0.2.10 -set interfaces tunnel tun0 remote 192.0.2.20 -set interfaces tunnel tun0 address 10.40.50.60/24 -set interfaces tunnel tun0 parameters ip key 10 -``` - -```none -set interfaces tunnel tun1 source-address 192.0.2.10 -set interfaces tunnel tun1 remote 192.0.2.20 -set interfaces tunnel tun1 address 172.16.17.18/24 -set interfaces tunnel tun1 parameters ip key 20 -``` - - -### GRETAP - -Unlike GRE, which encapsulates only Layer 3 (IP) traffic, GRETAP encapsulates -Layer 2 (Ethernet) frames. - -That means that GRETAP tunnel interfaces can be members of a bridge interface. -This allows two geographically distant sites to connect as if they were on the -same LAN. - -GRETAP tunnels can be established over both IPv4 and IPv6 transport networks. - -Example: - -```none -set interfaces bridge br0 member interface eth0 -set interfaces bridge br0 member interface tun0 -set interfaces tunnel tun0 encapsulation gretap -set interfaces tunnel tun0 source-address 198.51.100.2 -set interfaces tunnel tun0 remote 203.0.113.10 -``` - - -### Troubleshooting - -GRE is a standardized tunneling protocol used in many network environments. - -Although the GRE tunnel setup is straightforward, connectivity failures -frequently occur because ACLs or firewall rules block IP protocol 47 or -prevent direct communication between the tunnel endpoints. - -If your GRE tunnel fails to establish, perform these diagnostic steps: - -1\. Verify that the remote peer is reachable from the configured -`source-address`. - -This ensures that the underlying physical path between the two endpoints is -functional. - -```none -vyos@vyos:~$ ping 203.0.113.10 interface 198.51.100.2 count 4 -PING 203.0.113.10 (203.0.113.10) from 198.51.100.2 : 56(84) bytes of data. -64 bytes from 203.0.113.10: icmp_seq=1 ttl=254 time=0.807 ms -64 bytes from 203.0.113.10: icmp_seq=2 ttl=254 time=1.50 ms -64 bytes from 203.0.113.10: icmp_seq=3 ttl=254 time=0.624 ms -64 bytes from 203.0.113.10: icmp_seq=4 ttl=254 time=1.41 ms - ---- 203.0.113.10 ping statistics --- -4 packets transmitted, 4 received, 0% packet loss, time 3007ms -rtt min/avg/max/mdev = 0.624/1.087/1.509/0.381 ms -``` - -2\. Verify that the tunnel interface is correctly configured (with the link type -set to GRE) and is actively processing traffic. - -```none -vyos@vyos:~$ show interfaces tunnel tun100 -tun100@NONE: mtu 1476 qdisc noqueue state UNKNOWN group default qlen 1000 - link/gre 198.51.100.2 peer 203.0.113.10 - inet 10.0.0.1/30 brd 10.0.0.3 scope global tun100 - valid_lft forever preferred_lft forever - inet6 fe80::5efe:c612:2/64 scope link - valid_lft forever preferred_lft forever - - RX: bytes packets errors dropped overrun mcast - 2183 27 0 0 0 0 - TX: bytes packets errors dropped carrier collisions - 836 9 0 0 0 0 -``` - -3\. Test the connection through the tunnel using the private IP addresses -assigned to each tunnel endpoint. - -```none -vyos@vyos:~$ ping 10.0.0.2 interface 10.0.0.1 count 4 -PING 10.0.0.2 (10.0.0.2) from 10.0.0.1 : 56(84) bytes of data. -64 bytes from 10.0.0.2: icmp_seq=1 ttl=255 time=1.05 ms -64 bytes from 10.0.0.2: icmp_seq=2 ttl=255 time=1.88 ms -64 bytes from 10.0.0.2: icmp_seq=3 ttl=255 time=1.98 ms -64 bytes from 10.0.0.2: icmp_seq=4 ttl=255 time=1.98 ms - ---- 10.0.0.2 ping statistics --- -4 packets transmitted, 4 received, 0% packet loss, time 3008ms -rtt min/avg/max/mdev = 1.055/1.729/1.989/0.395 ms -``` - -[hurricane electric]: https://tunnelbroker.net/ -[other proposals]: https://www.isc.org/othersoftware/ diff --git a/docs/configuration/interfaces/md-virtual-ethernet.md b/docs/configuration/interfaces/md-virtual-ethernet.md deleted file mode 100644 index dee1b332..00000000 --- a/docs/configuration/interfaces/md-virtual-ethernet.md +++ /dev/null @@ -1,119 +0,0 @@ ---- -lastproofread: '2026-01-26' ---- - -(virtual-ethernet)= - -# Virtual Ethernet - -Virtual Ethernet (veth) interfaces are software-based interfaces that operate -in pairs, creating a tunnel between each other. Traffic transmitted into one -interface of the pair (e.g., `veth0`) is delivered directly to its peer -interface (e.g., `veth1`). - -Veth interfaces are commonly used to connect network namespaces or VRFs, but -they can also function as standalone virtual network interfaces. - -:::{note} -Veth interfaces must be created in pairs, where each interface acts -as the peer of the other. -::: - -## Configuration - -### Common interface configuration - -```{cmdincludemd} /_include/interface-address-with-dhcp.txt -:var0: virtual-ethernet -:var1: veth0 -``` - -```{cmdincludemd} /_include/interface-description.txt -:var0: virtual-ethernet -:var1: veth0 -``` - - -### VLAN - -#### Regular VLANs (802.1q) - -```{cmdincludemd} /_include/interface-vlan-8021q.txt -:var0: virtual-ethernet -:var1: veth0 -``` - - -#### 802.1ad (QinQ) - -```{cmdincludemd} /_include/interface-vlan-8021ad.txt -:var0: virtual-ethernet -:var1: veth0 -``` - -```{cmdincludemd} /_include/interface-disable.txt -:var0: virtual-ethernet -:var1: veth0 -``` - -```{cmdincludemd} /_include/interface-vrf.txt -:var0: virtual-ethernet -:var1: veth0 -``` - - -## Operation - -```{opcmd} show interfaces virtual-ethernet - -Show brief interface information. - -:::{code-block} none -vyos@vyos:~$ show interfaces virtual-ethernet -Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down -Interface IP Address S/L Description ---------- ---------- --- ----------- -veth10 100.64.0.0/31 u/u -veth11 100.64.0.1/31 u/u -::: -``` - -```{opcmd} show interfaces virtual-ethernet \ - -Show detailed interface information. - -:::{code-block} none -vyos@vyos:~$ show interfaces virtual-ethernet veth11 -10: veth11@veth10: mtu 1500 qdisc noqueue master red state UP group default qlen 1000 -link/ether b2:7b:df:47:e9:11 brd ff:ff:ff:ff:ff:ff -inet 100.64.0.1/31 scope global veth11 -valid_lft forever preferred_lft forever -inet6 fe80::b07b:dfff:fe47:e911/64 scope link -valid_lft forever preferred_lft forever - -RX: bytes packets errors dropped overrun mcast -0 0 0 0 0 0 -TX: bytes packets errors dropped carrier collisions -1369707 4267 0 0 0 0 -::: -``` - - -## Example - -The following example shows how to connect the global VRF to VRF ‘red ‘ using -the `veth10` and `veth11` veth pair. - -```none -set interfaces virtual-ethernet veth10 address '100.64.0.0/31' -set interfaces virtual-ethernet veth10 peer-name 'veth11' -set interfaces virtual-ethernet veth11 address '100.64.0.1/31' -set interfaces virtual-ethernet veth11 peer-name 'veth10' -set interfaces virtual-ethernet veth11 vrf 'red' -set vrf name red table '1000' - -vyos@vyos:~$ ping 100.64.0.1 -PING 100.64.0.1 (100.64.0.1) 56(84) bytes of data. -64 bytes from 100.64.0.1: icmp_seq=1 ttl=64 time=0.080 ms -64 bytes from 100.64.0.1: icmp_seq=2 ttl=64 time=0.119 ms -``` diff --git a/docs/configuration/interfaces/md-vti.md b/docs/configuration/interfaces/md-vti.md deleted file mode 100644 index dbd2c88c..00000000 --- a/docs/configuration/interfaces/md-vti.md +++ /dev/null @@ -1,121 +0,0 @@ -(vti-interface)= - -# VTI (virtual tunnel interface) - -{abbr}`VTIs (virtual tunnel interfaces)` let you create secure, encrypted -tunnels between private networks or hosts across public infrastructure, such as -the Internet. They operate alongside an underlying IPsec tunnel, which handles -encapsulation and encryption, while VTIs function exclusively as routing -interfaces. - -## Configuration - -### Common interface configuration - -```{cmdincludemd} /_include/interface-address.txt -:var0: vti -:var1: vti0 -``` - -```{cmdincludemd} /_include/interface-description.txt -:var0: vti -:var1: vti0 -``` - -```{cmdincludemd} /_include/interface-disable.txt -:var0: vti -:var1: vti0 -``` - -```{cmdincludemd} /_include/interface-ip.txt -:var0: vti -:var1: vti0 -``` - -```{cmdincludemd} /_include/interface-ipv6.txt -:var0: vti -:var1: vti0 -``` - -```{cmdincludemd} /_include/interface-mtu.txt -:var0: vti -:var1: vti0 -``` - -```{cfgcmd} set interfaces vti \ mirror egress \ - -Configure mirroring of outgoing traffic from the specified VTI to the -designated monitor interface. -``` - -```{cfgcmd} set interfaces vti \ mirror ingress \ - -Configure mirroring of incoming traffic from the specified VTI to the -designated monitor interface. -``` - -```{cfgcmd} set interfaces vti \ redirect \ - -Enable redirection of incoming packets to the specified interface. -``` - -```{cmdincludemd} /_include/interface-vrf.txt -:var0: vti -:var1: vti0 -``` - - -## Operation - -```{opcmd} show interfaces vti \ - -Show the operational status and traffic statistics for the specified VTI. -``` - -```{opcmd} show interfaces vti \ brief - -Show a brief operational status summary for the specified VTI. -``` - - -## Example - -**Configure a VTI** - -Assign IPv4 and IPv6 addresses to the VTI, along with a brief description: - -```none -set interfaces vti vti0 address 192.168.2.249/30 -set interfaces vti vti0 address 2001:db8:2::249/64 -set interfaces vti vti0 description "Description" -``` - -Resulting configuration: - -```none -vyos@vyos# show interfaces vti -vti vti0 { - address 192.168.2.249/30 - address 2001:db8:2::249/64 - description "Description" -} -``` - -:::{warning} -When configuring site-to-site IPsec with VTIs, ensure that route -autoinstall is disabled. -::: - -```none -set vpn ipsec options disable-route-autoinstall -``` - -For more information about the IPsec and VTI issue, as well as the -`disable-route-autoinstall` option, see: - - -The root cause of the problem is that VTI tunnels require their traffic -selectors to be set to `0.0.0.0/0` for traffic to match the tunnel, even -though routing decisions are based on netfilter marks. Unless route insertion -is explicitly disabled, strongSWAN incorrectly inserts a default route through -the VTI peer address, causing all traffic to be misrouted. diff --git a/docs/configuration/interfaces/md-vxlan.md b/docs/configuration/interfaces/md-vxlan.md deleted file mode 100644 index 8dae75ff..00000000 --- a/docs/configuration/interfaces/md-vxlan.md +++ /dev/null @@ -1,373 +0,0 @@ ---- -lastproofread: '2026-03-16' ---- - -(vxlan-interface)= - -# VXLAN - -{abbr}`VXLAN (Virtual Extensible LAN)` is a network virtualization technology -that addresses scalability challenges in large cloud computing environments. -It encapsulates Ethernet frames (Layer 2) within UDP datagrams (Layer 4), which -are then transmitted via UDP port 4789, as assigned by IANA. VXLAN endpoints, -called {abbr}`VTEPs (VXLAN tunnel endpoints)`, terminate VXLAN tunnels and can -be either virtual or physical switch ports. - -VXLAN supports up to 16 million logical networks and enables Layer 2 adjacency -across Layer 3 IP networks. It uses multicast or unicast with head-end -replication (HER) to flood broadcast, unknown unicast, and multicast (BUM) -traffic. - -The VXLAN specification was initially developed by VMware, Arista Networks, and -Cisco. Other supporters include Huawei, Broadcom, Citrix, Pica8, Big Switch -Networks, Cumulus Networks, Dell EMC, Ericsson, Mellanox, FreeBSD, OpenBSD, Red -Hat, Joyent, and Juniper Networks. - -VXLAN is officially documented by the IETF in {rfc}`7348`. - -When configuring VXLAN in a VyOS virtual machine, ensure that MAC spoofing -(Hyper-V) or Forged Transmits (ESX) are permitted. Otherwise, the hypervisor -may block forwarded frames. - -:::{note} -Although the IANA-assigned VXLAN port is **4789**, VyOS uses the -Linux default UDP port **8472** for VXLAN interfaces. To ensure compatibility -with other vendors, set the port to the IANA standard **4789**. -::: - -## Configuration - -### Common interface configuration - -```{cmdincludemd} /_include/interface-common-without-dhcp.txt -:var0: vxlan -:var1: vxlan0 -``` - - -### VXLAN-specific options - -```{cfgcmd} set interfaces vxlan \ vni \ - -**Configure a** {abbr}`VNI (VXLAN Network Identifier)` **for the VXLAN -interface.** - -Each VXLAN segment is identified by this 24-bit VNI, allowing up to 16 million -segments to coexist within the same administrative domain. -``` - -```{cfgcmd} set interfaces vxlan \ port \ - -Configure the UDP port of the remote VXLAN endpoint. - -:::{note} -Although the IANA-assigned VXLAN port is **4789**, VyOS uses the -Linux default UDP port **8472** for VXLAN interfaces. -::: -``` - -```{cfgcmd} set interfaces vxlan \ source-address \ - -Configure the source IP address for the VXLAN underlay. - -:::{warning} -This setting is mandatory when deploying VXLAN via L2VPN/EVPN. -::: -``` - -```{cfgcmd} set interfaces vxlan \ gpe - -**Enable the** {abbr}`GPE (Generic Protocol Extension)` **for the VXLAN -interface.** - -To use this feature, you must configure the interface with the ``external`` -parameter. -``` - -```{cfgcmd} set interfaces vxlan \ parameters external - -**Configure the VXLAN interface to use an external control plane, such as BGP -L2VPN/EVPN, for remote endpoint discovery.** - -If not configured, the internal {abbr}`FDB (Forwarding Database)` is used. -``` - -```{cfgcmd} set interfaces vxlan \ parameters neighbor-suppress - -**Enable ARP and ND suppression on the VXLAN interface.** - -This reduces ARP and ND message flooding across the VXLAN network. As defined -in {rfc}`7432#section-10`, participating VTEPs use known MAC-to-IP bindings -to reply to local requests on behalf of remote hosts. -``` - -```{cfgcmd} set interfaces vxlan \ parameters nolearning - -Disable {abbr}`SLLA (Source Link-Layer Address)` and IP address learning on -the VXLAN interface. -``` - -```{cfgcmd} set interfaces vxlan \ parameters vni-filter - -**Enable** {abbr}`VNI (VXLAN Network Identifier)` **filtering on the VXLAN -interface.** - -When enabled, the interface only receives packets with VNIs configured in its -VNI filtering table. - -:::{note} -VNI filtering works only if the interface is configured with the -``external`` parameter. -::: -``` - - -#### Unicast - -```{cfgcmd} set interfaces vxlan \ remote \ - -**Configure the IPv4 or IPv6 address of the remote VTEP.** - -Unlike multicast setups, this command allows you to directly configure the -remote IPv4 or IPv6 address. -``` - - -#### Multicast - -```{cfgcmd} set interfaces vxlan \ source-interface \ - -**Configure the source interface for the VXLAN underlay.** - -All VXLAN traffic is sent and received through the specified interface. -This setting is mandatory when deploying VXLAN over a multicast network. -``` - -```{cfgcmd} set interfaces vxlan \ group \ - -**Configure the IPv4 or IPv6 multicast group address for the VXLAN interface.** - -VXLAN tunnels can be built using either multicast group or unicast IP addresses. -``` - - -## Multicast VXLAN - -Topology: PC4 - Leaf2 - Spine1 - Leaf3 - PC5 - -PC4 uses the IP address `10.0.0.4/24`, and PC5 uses the IP address -`10.0.0.5/24`. Both devices assume they reside within the same broadcast -domain. - -Assume PC4 on Leaf2 pings PC5 on Leaf3. Rather than manually specifying Leaf3 -as the remote endpoint, Leaf2 encapsulates the packet into a UDP datagram and -sends it to the designated multicast address via Spine1. Spine1 forwards the -packet to all leaves in the same multicast group, including Leaf3. Upon -receiving the datagram, Leaf3 forwards it to PC5 and learns that PC4 is -reachable through Leaf2 by inspecting the source IP in the encapsulated -datagram. - -PC5 receives the ping and responds with an echo reply. Leaf3, now aware of -PC4's location, forwards the reply directly to Leaf2's unicast address. Upon -receiving the echo reply, Leaf2 learns that PC5 is reachable through Leaf3. - -After this discovery, subsequent traffic between PC4 and PC5 will not use the -multicast address between the leaves, as both leaves have learned the PCs' -locations. This reduces multicast traffic and network load, improving -scalability as more leaves are added. - -## Single VXLAN device (SVD) - -In VyOS, you can configure multiple **VLAN-to-VNI mappings** for EVPN-VXLAN on -a single container interface, known as a single VXLAN device (SVD). This -enables significant VNI scaling because a separate VXLAN interface is not -required for each VNI. - -```{cfgcmd} set interfaces vxlan \ vlan-to-vni \ vni \ - -**Map a VLAN ID to a VNI on the specified VXLAN interface.** - -The VXLAN interface can be added to a bridge. - -The following example shows an SVD configuration with multiple VLAN-to-VNI -mappings. - -:::{code-block} none -set interfaces bridge br0 member interface vxlan0 -set interfaces vxlan vxlan0 parameters external -set interfaces vxlan vxlan0 source-interface 'dum0' -set interfaces vxlan vxlan0 vlan-to-vni 10 vni '10010' -set interfaces vxlan vxlan0 vlan-to-vni 11 vni '10011' -set interfaces vxlan vxlan0 vlan-to-vni 30 vni '10030' -set interfaces vxlan vxlan0 vlan-to-vni 31 vni '10031' -::: -``` - - -### Example - -The following example demonstrates a multicast VXLAN deployment. - -The setup includes three routers: Spine1, a Cisco IOS router, and Leaf2 and -Leaf3, which are VyOS routers. - -**Topology:** Leaf2 - Spine1 - Leaf3. - -The topology is built using GNS3. - -```none -Spine1: -fa0/2 towards Leaf2, IP-address: 10.1.2.1/24 -fa0/3 towards Leaf3, IP-address: 10.1.3.1/24 - -Leaf2: -Eth0 towards Spine1, IP-address: 10.1.2.2/24 -Eth1 towards a VLAN-aware switch - -Leaf3: -Eth0 towards Spine1, IP-address 10.1.3.3/24 -Eth1 towards a VLAN-aware switch -``` - -**Spine1 configuration:** - -```none -conf t -ip multicast-routing -! -interface fastethernet0/2 - ip address 10.1.2.1 255.255.255.0 - ip pim sparse-dense-mode -! -interface fastethernet0/3 - ip address 10.1.3.1 255.255.255.0 - ip pim sparse-dense-mode -! -router ospf 1 - network 10.0.0.0 0.255.255.255 area 0 -``` - -Multicast routing is required for scalable traffic forwarding between leaves. -{abbr}`PIM (Protocol Independent Multicast)` must be enabled towards the leaves -so the spine can learn from which multicast groups each leaf expects traffic. - -**Leaf2 configuration:** - -```none -set interfaces ethernet eth0 address '10.1.2.2/24' -set protocols ospf area 0 network '10.0.0.0/8' - -! First VXLAN interface -set interfaces bridge br241 address '172.16.241.1/24' -set interfaces bridge br241 member interface 'eth1.241' -set interfaces bridge br241 member interface 'vxlan241' - -set interfaces vxlan vxlan241 group '239.0.0.241' -set interfaces vxlan vxlan241 source-interface 'eth0' -set interfaces vxlan vxlan241 vni '241' - -! Second VXLAN interface -set interfaces bridge br242 address '172.16.242.1/24' -set interfaces bridge br242 member interface 'eth1.242' -set interfaces bridge br242 member interface 'vxlan242' - -set interfaces vxlan vxlan242 group '239.0.0.242' -set interfaces vxlan vxlan242 source-interface 'eth0' -set interfaces vxlan vxlan242 vni '242' -``` - -**Leaf3 configuration:** - -```none -set interfaces ethernet eth0 address '10.1.3.3/24' -set protocols ospf area 0 network '10.0.0.0/8' - -! First VXLAN interface -set interfaces bridge br241 address '172.16.241.1/24' -set interfaces bridge br241 member interface 'eth1.241' -set interfaces bridge br241 member interface 'vxlan241' - -set interfaces vxlan vxlan241 group '239.0.0.241' -set interfaces vxlan vxlan241 source-interface 'eth0' -set interfaces vxlan vxlan241 vni '241' - -! Second VXLAN interface -set interfaces bridge br242 address '172.16.242.1/24' -set interfaces bridge br242 member interface 'eth1.242' -set interfaces bridge br242 member interface 'vxlan242' - -set interfaces vxlan vxlan242 group '239.0.0.242' -set interfaces vxlan vxlan242 source-interface 'eth0' -set interfaces vxlan vxlan242 vni '242' -``` - -The configurations for Leaf2 and Leaf3 are nearly identical. Detailed -explanations for each command are provided below. - -```none -set interfaces bridge br241 address '172.16.241.1/24' -``` - -This command creates a bridge to bind traffic on `eth1` VLAN 241 with the -`vxlan241` interface. The IP address is optional. If configured, it can serve -as the default gateway for each leaf, allowing devices on the VLAN to reach -other subnets. Subnets must be redistributed by {abbr}`OSPF (Open Shortest Path -First)` so the spine can learn how to reach them. To advertise `172.16/12` -networks, change the {abbr}`OSPF (Open Shortest Path First)` network from -`10.0.0.0/8` to `0.0.0.0/0`. - -```none -set interfaces bridge br241 member interface 'eth1.241' -set interfaces bridge br241 member interface 'vxlan241' -``` - -These commands bind `eth1.241` and `vxlan241` as member interfaces of the -same bridge. - -```none -set interfaces vxlan vxlan241 group '239.0.0.241' -``` - -This command configures the multicast group used by all leaves for this VLAN -extension. It must be the same on all leaves that have this interface. - -```none -set interfaces vxlan vxlan241 source-interface 'eth0' -``` - -This command configures the interface that listens for multicast packets. It -can also be a loopback interface. - -```none -set interfaces vxlan vxlan241 vni '241' -``` - -This command configures the unique ID for the VXLAN interface. - -```none -set interfaces vxlan vxlan241 port 12345 -``` - -VyOS uses the Linux default UDP port **8472** for VXLAN interfaces. This -command allows you to configure a different UDP port. - -## Unicast VXLAN - -As an alternative to multicast, you can configure the VXLAN tunnel by -specifying the remote IPv4 address directly. The following updates the previous -multicast example: - -```none -# leaf2 and leaf3 -delete interfaces vxlan vxlan241 group '239.0.0.241' -delete interfaces vxlan vxlan241 source-interface 'eth0' - -# leaf2 -set interfaces vxlan vxlan241 remote 10.1.3.3 - -# leaf3 -set interfaces vxlan vxlan241 remote 10.1.2.2 -``` - -The default UDP port is 8472. To configure a different port, use `set -interfaces vxlan port `. diff --git a/docs/configuration/interfaces/md-wireguard.md b/docs/configuration/interfaces/md-wireguard.md deleted file mode 100644 index 121d1df0..00000000 --- a/docs/configuration/interfaces/md-wireguard.md +++ /dev/null @@ -1,434 +0,0 @@ ---- -lastproofread: '2026-03-02' ---- - -(wireguard)= - -# WireGuard - -WireGuard is an extremely simple, fast, and modern VPN that utilizes -state-of-the-art cryptography. See for more -information. - -## Site-to-site VPN - -The following diagram illustrates a site-to-site VPN setup. - -:::{figure} /_static/images/wireguard_site2site_diagram.webp -::: - -## Keypairs - -WireGuard requires a keypair, which includes a **private** key -to decrypt incoming traffic, and a **public** key for peer(s) to encrypt -outgoing traffic. - -### Generate keypair - -```{opcmd} generate pki wireguard key-pair - -Generate a keypair: a public and a private key. - -:::{note} -This command only outputs the keys to your console. It neither stores -them in the system nor applies them to the system configuration. -::: - -:::{code-block} none -vyos@vyos:~$ generate pki wireguard key-pair -Private key: iJJyEARGK52Ls1GYRCcFvPuTj7WyWYDo//BknoDU0XY= -Public key: EKY0dxRrSD98QHjfHOK13mZ5PJ7hnddRZt5woB3szyw= -::: -``` - - -```{opcmd} generate pki wireguard key-pair install interface \ - -Generate a keypair and output the private key assignment command for the -specified interface. - -:::{code-block} none -vyos@vyos:~$ generate pki wireguard key-pair install interface wg10 -"generate" CLI command executed from operational level. -Generated private key is not automatically added to the VyOS configuration, use the following configuration mode commands to install key: - -set interfaces wireguard wg10 private-key '4Krkv8h6NkAYMMaBWI957yYDJDMvj9URTHstdlOcDU0=' - -Corresponding public-key to use on peer system is: 'UxDsYT6EnpTIOKUzvMlw2p0sNOKQvFxEdSVrnNrX1Ro=' -::: - -:::{note} -If you invoke this command from configuration mode with the ``run`` -prefix, the generated private key is automatically assigned to the specified -interface. -::: - -:::{code-block} none -vyos@vyos# run generate pki wireguard key-pair install interface wg10 -"generate" CLI command executed from config session. -Generated private-key was imported to CLI! - -Use the following command to verify: show interfaces wireguard wg10 -Corresponding public-key to use on peer system is: '7d9KwabjLhHpJiEJeIGd0CBlao/eTwFOh6xyCovTfG8=' - -vyos@vyos# compare -[edit interfaces] -+wireguard wg10 { -+ private-key CJweb8FC6BU3Loj4PC2pn5V82cDjIPs7G1saW0ZfLWc= -+} -::: -``` - - -```{opcmd} show interfaces wireguard \ public-key - -Show the public key assigned to the interface. - -:::{code-block} none -vyos@vyos:~$ show interfaces wireguard wg01 public-key -EKY0dxRrSD98QHjfHOK13mZ5PJ7hnddRZt5woB3szyw= -::: -``` - -#### Optional - -```{opcmd} generate pki wireguard preshared-key - -Generate a pre-shared key. - -The pre-shared key is optional. It adds an additional layer of symmetric-key -cryptography on top of the asymmetric cryptography. - -:::{code-block} none -vyos@vyos:~$ generate pki wireguard preshared-key -Pre-shared key: OHH2EwZfMNK+1L6BXbYw3bKCtMrfjpR4mCAEeBlFnRs= -::: -``` - -```{opcmd} generate pki wireguard preshared-key install interface \ peer \ - -Generate a pre-shared key and output the key assignment command for the -specified peer. - -:::{code-block} none -vyos@vyos:~$ generate pki wireguard preshared-key install interface wg10 peer foo -"generate" CLI command executed from operational level. -Generated preshared-key is not stored to CLI, use configure mode commands to install key: - -set interfaces wireguard wg10 peer foo preshared-key '32vQ1w1yFKTna8n7Gu7EimubSe2Y63m8bafz55EG3Ro=' - -Pre-shared key: +LuaZ8W6DjsDFJFX3jJzoNqrsXHhvq08JztM9z8LHCs= -::: - -:::{note} -If you invoke this command from configuration mode with the run -prefix, the generated key is automatically assigned to the specified peer. -::: -``` - -## Interface configuration - -The next step is to configure your local WireGuard interface and define the -networks you want to tunnel (`allowed-ips`). - -If your system only initiates connections, specifying the listen port is -optional. If your system accepts incoming connections, you must define a port -for peers to connect to. Otherwise, WireGuard selects a random port at each -reboot, and that may break your peers' ability to connect if that port is not enabled in your firewall rules. - -To configure a WireGuard tunnel, you also need your peer's public key. - -:::{note} -The public key specified in the peer configuration block is always -the **remote** peer's public key, never your local one. -::: - -**Local side configuration** - -The local side is configured with the following parameters: -- Local WireGuard interface IP: `10.1.0.1/30` -- Local listen port: `51820` -- Remote peer name: `to-wg02` -- Remote peer endpoint: `192.0.2.1` on port `51820` -- Remote peer public key: `XMrlPykaxhdAAiSjhtPlvi30NVkvLQliQuKP7AI7CyI=` -- Allowed networks: `192.168.2.0/24` - -```none -set interfaces wireguard wg01 address '10.1.0.1/30' -set interfaces wireguard wg01 description 'VPN-to-wg02' -set interfaces wireguard wg01 peer to-wg02 allowed-ips '192.168.2.0/24' -set interfaces wireguard wg01 peer to-wg02 address '192.0.2.1' -set interfaces wireguard wg01 peer to-wg02 port '51820' -set interfaces wireguard wg01 peer to-wg02 public-key 'XMrlPykaxhdAAiSjhtPlvi30NVkvLQliQuKP7AI7CyI=' -set interfaces wireguard wg01 port '51820' - -set protocols static route 192.168.2.0/24 interface wg01 -``` - -To send traffic destined for `192.168.2.0/24` through the WireGuard interface -(`wg01`), configure a static route. Multiple IP addresses or networks can be -defined and routed. The final check is performed against `allowed-ips`, which -either permits or drops the traffic. - -:::{warning} -You cannot assign the same `allowed-ips` to multiple WireGuard -peers. This is a strict design restriction. For more information, check the -[WireGuard mailing list]. -::: - -```{cfgcmd} set interfaces wireguard \ private-key \ - -Assign a private key to the specified WireGuard interface. - -Example: - -:::{code-block} none -set interfaces wireguard wg01 private-key 'iJJyEARGK52Ls1GYRCcFvPuTj7WyWYDo//BknoDU0XY=' -::: - -To generate a private key, use the following command: -{opcmd}`generate pki wireguard key-pair`. - -To view the public key assigned to the interface so you can share it with a -peer, use the following command: -{opcmd}`show interfaces wireguard wg01 public-key`. -``` - - -```{cmdincludemd} /_include/interface-per-client-thread.txt -:var0: wireguard -:var1: wg01 -``` - -**Remote side configuration** - -```none -set interfaces wireguard wg01 address '10.1.0.2/30' -set interfaces wireguard wg01 description 'VPN-to-wg01' -set interfaces wireguard wg01 peer to-wg01 allowed-ips '192.168.1.0/24' -set interfaces wireguard wg01 peer to-wg01 address '192.0.2.2' -set interfaces wireguard wg01 peer to-wg01 port '51820' -set interfaces wireguard wg01 peer to-wg01 public-key 'EKY0dxRrSD98QHjfHOK13mZ5PJ7hnddRZt5woB3szyw=' -set interfaces wireguard wg01 port '51820' -set interfaces wireguard wg01 private-key 'OLTQY3HuK5qWDgVs6fJR093SwPgOmCKkDI1+vJLGoFU=' - -set protocols static route 192.168.1.0/24 interface wg01 -``` - -## Firewall exceptions - - -To allow WireGuard traffic through the WAN interface, create a firewall -exception: - -```none -set firewall ipv4 name OUTSIDE_LOCAL rule 10 action accept -set firewall ipv4 name OUTSIDE_LOCAL rule 10 description 'Allow established/related' -set firewall ipv4 name OUTSIDE_LOCAL rule 10 state established enable -set firewall ipv4 name OUTSIDE_LOCAL rule 10 state related enable -set firewall ipv4 name OUTSIDE_LOCAL rule 20 action accept -set firewall ipv4 name OUTSIDE_LOCAL rule 20 description WireGuard_IN -set firewall ipv4 name OUTSIDE_LOCAL rule 20 destination port 51820 -set firewall ipv4 name OUTSIDE_LOCAL rule 20 log enable -set firewall ipv4 name OUTSIDE_LOCAL rule 20 protocol udp -``` - -Ensure that the OUTSIDE_LOCAL firewall group is applied to the WAN interface -and in an input (local) direction. - -```none -set firewall ipv4 input filter rule 10 action jump -set firewall ipv4 input filter rule 10 jump-target 'OUTSIDE_LOCAL' -set firewall ipv4 input filter rule 10 inbound-interface name 'eth0' -``` - -Verify that your firewall rules permit traffic. If so, your WireGuard VPN -should be operational. - -```none -wg01# ping 192.168.1.1 -PING 192.168.1.1 (192.168.1.1) 56(84) bytes of data. -64 bytes from 192.168.1.1: icmp_seq=1 ttl=64 time=1.16 ms -64 bytes from 192.168.1.1: icmp_seq=2 ttl=64 time=1.77 ms - -wg02# ping 192.168.2.1 -PING 192.168.2.1 (192.168.2.1) 56(84) bytes of data. -64 bytes from 192.168.2.1: icmp_seq=1 ttl=64 time=4.40 ms -64 bytes from 192.168.2.1: icmp_seq=2 ttl=64 time=1.02 ms -``` - -An additional layer of symmetric-key cryptography can be used on top of the -asymmetric cryptography. This is optional. - -```none -vyos@vyos:~$ generate pki wireguard preshared-key -Pre-shared key: rvVDOoc2IYEnV+k5p7TNAmHBMEGTHbPU8Qqg8c/sUqc= -``` - -Copy the key, as it is not stored locally. Since it is a symmetric key, only -you and your peer should know its contents. Distribute the key securely. - -```none -wg01# set interfaces wireguard wg01 peer to-wg02 preshared-key 'rvVDOoc2IYEnV+k5p7TNAmHBMEGTHbPU8Qqg8c/sUqc=' -wg02# set interfaces wireguard wg01 peer to-wg01 preshared-key 'rvVDOoc2IYEnV+k5p7TNAmHBMEGTHbPU8Qqg8c/sUqc=' -``` - -## Remote access (road warrior) - - -With WireGuard, a road warrior VPN configuration is similar to a site-to-site -VPN. It just omits the `address` and `port` statements. - - -In the following example, the IP addresses for remote clients are defined -within each peer configuration. This allows peers to communicate with each -other. - - -Additionally, this setup uses a `persistent-keepalive` flag set to 15 seconds -to keep the connection alive. This setting is mainly relevant if a peer is -behind NAT and cannot be reached if the connection is lost. For effectiveness, -the value should be lower than the UDP timeout. - -```none -wireguard wg01 { - address 10.172.24.1/24 - address 2001:db8:470:22::1/64 - description RoadWarrior - peer MacBook { - allowed-ips 10.172.24.30/32 - allowed-ips 2001:db8:470:22::30/128 - persistent-keepalive 15 - pubkey F5MbW7ye7DsoxdOaixjdrudshjjxN5UdNV+pGFHqehc= - } - peer iPhone { - allowed-ips 10.172.24.20/32 - allowed-ips 2001:db8:470:22::20/128 - persistent-keepalive 15 - pubkey BknHcLFo8nOo8Dwq2CjaC/TedchKQ0ebxC7GYn7Al00= - } - port 2224 - private-key OLTQY3HuK5qWDgVs6fJR093SwPgOmCKkDI1+vJLGoFU= -} -``` - -Below is the configuration for the iPhone peer. The `AllowedIPs` wildcard -setting directs all IPv4 and IPv6 traffic through the VPN connection. - -```none -[Interface] -PrivateKey = ARAKLSDJsadlkfjasdfiowqeruriowqeuasdf= -Address = 10.172.24.20/24, 2001:db8:470:22::20/64 -DNS = 10.0.0.53, 10.0.0.54 - -[Peer] -PublicKey = RIbtUTCfgzNjnLNPQ/ulkGnnB2vMWHm7l2H/xUfbyjc= -AllowedIPs = 0.0.0.0/0, ::/0 -Endpoint = 192.0.2.1:2224 -PersistentKeepalive = 15 -``` - -To enable split tunneling, specify the remote subnets. This ensures that only -traffic destined for the remote site is sent through the tunnel, while all -other traffic remains unaffected. - -```none -[Interface] -PrivateKey = 8Iasdfweirousd1EVGUk5XsT+wYFZ9mhPnQhmjzaJE6Go= -Address = 10.172.24.30/24, 2001:db8:470:22::30/64 - -[Peer] -PublicKey = RIbtUTCfgzNjnLNPQ/ulkGnnB2vMWHm7l2H/xUfbyjc= -AllowedIPs = 10.172.24.30/24, 2001:db8:470:22::/64 -Endpoint = 192.0.2.1:2224 -PersistentKeepalive = 15 -``` - -## Operational commands - - -### Status - -```{opcmd} show interfaces wireguard wg01 summary - -Show information about the WireGuard service, including the latest handshake. - -:::{code-block} none -vyos@vyos:~$ show interfaces wireguard wg01 summary -interface: wg01 -public key: -private key: (hidden) -listening port: 51820 - -peer: -endpoint: -allowed ips: 10.69.69.2/32 -latest handshake: 23 hours, 45 minutes, 26 seconds ago -transfer: 1.26 MiB received, 6.47 MiB sent -::: -``` - - -```{opcmd} show interfaces wireguard - -Show a list of all WireGuard interfaces. - -:::{code-block} none -Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down -Interface IP Address S/L Description ---------- ---------- --- ----------- -wg01 10.0.0.1/24 u/u -::: -``` - -```{opcmd} show interfaces wireguard \ - -Show general information about a specific WireGuard interface. - -:::{code-block} none -vyos@vyos:~$ show interfaces wireguard wg01 -interface: wg01 -address: 10.0.0.1/24 -public key: h1HkYlSuHdJN6Qv4Hz4bBzjGg5WUty+U1L7DJsZy1iE= -private key: (hidden) -listening port: 41751 -RX: bytes packets errors dropped overrun mcast -0 0 0 0 0 0 -TX: bytes packets errors dropped carrier collisions -0 0 0 0 0 0 -::: -``` - -## Remote access (road warrior) clients - -Some users connect mobile devices to their VyOS router using WireGuard. To -simplify deployment, generate a per-mobile configuration from the VyOS CLI. - -:::{warning} -From a security perspective, it is not recommended to let a third -party create and share the private key for a secure connection. You should -create the private portion yourself and hand out only the public key. -::: - -```{opcmd} generate wireguard client-config \ interface \ server \ address \ - -**Generate a client configuration file that establishes a connection to the -specified interface.** - -The public key from the specified interface is automatically included in the -configuration file. - -The command also generates a configuration snippet that can be copied into the -VyOS CLI. The ```` you provide will be used as the peer name in the -snippet. - -You must also specify the IP address or FQDN of the server the client connects -to. The address parameter can be used twice to assign both an IPv4 (/32) and -an IPv6 (/128) address to the client. - -:::{figure} /_static/images/wireguard_qrcode.webp -:alt: WireGuard Client QR code -::: -``` - -[wireguard mailing list]: https://lists.zx2c4.com/pipermail/wireguard/2018-December/003704.html diff --git a/docs/configuration/interfaces/md-wireless.md b/docs/configuration/interfaces/md-wireless.md deleted file mode 100644 index 9e6b7c99..00000000 --- a/docs/configuration/interfaces/md-wireless.md +++ /dev/null @@ -1,923 +0,0 @@ ---- -lastproofread: '2026-03-23' ---- - -(wireless-interface)= - -# Wireless LAN / Wi-Fi - -{abbr}`WLAN (Wireless LAN)` interfaces provide 802.11 (a/b/g/n/ac) wireless -connectivity, referred to as Wi-Fi, and operate in one of the following -modes: - -- {abbr}`WAP (Wireless Access-Point)` mode provides network access to connecting - stations if the physical hardware supports acting as a WAP -- Station mode acts as a Wi-Fi client accessing the network through an available - WAP -- Monitor mode lets the system passively monitor wireless traffic - -If the system detects an unconfigured wireless device, it will be automatically -added to the configuration tree, specifying any detected settings (for example, -its MAC address) and configured to run in monitor mode. - -## Configuration - -### Common interface configuration - -```{cmdincludemd} /_include/interface-common-with-dhcp.txt -:var0: wireless -:var1: wlan0 -``` - - -### System-wide configuration - -```{cfgcmd} set system wireless country-code \ - -Country code (ISO/IEC 3166-1). Used to set regulatory domain. Set as needed -to indicate country in which device is operating. This can limit available -channels and transmit power. - -:::{note} -This option is mandatory in ``access-point`` mode. -::: -``` - - -### Wireless options - -```{cfgcmd} set interfaces wireless \ channel \ - -Configure the IEEE 802.11 wireless radio channel for the interface. -Channel allocation depends on the frequency band: -* **2.4 GHz** (802.11b/g/n/ax): Channels range from 1 to 14. -* **5 GHz** (802.11a/h/j/n/ac/ax): Channels range from 34 to 177. -* **6 GHz** (802.11ax): Channels range from 1 to 233. -* **Automatic channel selection:** 0. -``` - -```{cfgcmd} set interfaces wireless \ disable-broadcast-ssid - -Send empty SSID in beacons and ignore probe request frames that do not specify -full SSID, i.e., require stations to know the SSID. -``` - -```{cfgcmd} set interfaces wireless \ expunge-failing-stations - -Disassociate stations based on excessive transmission failures or other -indications of connection loss. - -This depends on the driver capabilities and may not be available with all -drivers. -``` - -```{cfgcmd} set interfaces wireless \ isolate-stations - -Client isolation can be used to prevent low-level bridging of frames between -associated stations in the BSS. - -By default, this bridging is allowed. -``` - -```{cfgcmd} set interfaces wireless \ max-stations \ - -Maximum number of stations allowed in station table. New stations will be -rejected after the station table is full. IEEE 802.11 has a limit of 2007 -different association IDs, so this number should not be larger than that. - -This defaults to 2007. -``` - -```{cfgcmd} set interfaces wireless \ mgmt-frame-protection - -Management Frame Protection (MFP) according to IEEE 802.11w - -:::{note} -{abbr}`MFP (Management Frame Protection)` is required for WPA3. -::: -``` - -```{cfgcmd} set interfaces wireless \ enable-bf-protection - -Beacon Protection: management frame protection for Beacon frames. - -:::{note} -This option requires {abbr}`MFP (Management Frame Protection)` -to be enabled. -::: -``` - -```{cfgcmd} set interfaces wireless \ mode \ - -Operation mode of wireless radio. -* ``a`` - 802.11a - 54 Mbits/sec -* ``b`` - 802.11b - 11 Mbits/sec -* ``g`` - 802.11g - 54 Mbits/sec (default) -* ``n`` - 802.11n - 600 Mbits/sec -* ``ac`` - 802.11ac - 1300 Mbits/sec -* ``ax`` - 802.11ax - exceeds 1GBit/sec - -:::{note} -In VyOS, 802.11ax is only implemented for 2.4GHz and 6GHz. -::: -``` - -```{cfgcmd} set interfaces wireless \ physical-device \ - -Wireless hardware device used as underlay radio. - -This defaults to phy0. -``` - -```{cfgcmd} set interfaces wireless \ reduce-transmit-power \ - -Adds the Power Constraint information element to Beacon and Probe Response -frames. - -This option adds the Power Constraint information element when applicable -and the Country information element is configured. The Power Constraint -element is required by Transmit Power Control. - -Valid values are 0..255. -``` - -```{cfgcmd} set interfaces wireless \ ssid \ - -SSID to be used in IEEE 802.11 management frames -``` - -```{cfgcmd} set interfaces wireless \ type \ - -Wireless device type for this interface -* ``access-point``: Forwards packets between other nodes. -* ``station``: Connects to another {abbr}`AP (Access Point)`. -* ``monitor``: Passively monitors all packets on the frequency/channel. -``` - -```{cmdincludemd} /_include/interface-per-client-thread.txt -:var0: wireless -:var1: wlan0 -``` - - -#### PPDU - -```{cfgcmd} set interfaces wireless \ capabilities require-ht - -``` -```{cfgcmd} set interfaces wireless \ capabilities require-vht -``` - -```{cfgcmd} set interfaces wireless \ capabilities require-he -``` - -##### HT (High Throughput) capabilities (802.11n) - -> Configuring HT mode options is required when using 802.11n or -> 802.11ax at 2.4GHz. - -```{cfgcmd} set interfaces wireless \ capabilities ht 40mhz-incapable - -Device is incapable of 40 MHz, do not advertise. This sets ``[40-INTOLERANT]`` -``` - -```{cfgcmd} set interfaces wireless \ capabilities ht auto-powersave - -WMM-PS Unscheduled Automatic Power Save Delivery [U-APSD] -``` - -```{cfgcmd} set interfaces wireless \ capabilities ht channel-set-width \ - -Supported channel width set. -* ``ht20`` - 20 MHz channel width -* ``ht40-`` - Both 20 MHz and 40 MHz with secondary channel below the primary -channel -* ``ht40+`` - Both 20 MHz and 40 MHz with secondary channel above the primary -channel - -:::{note} -Channel availability for HT40- and HT40+ is limited. The following -table lists channels permitted for HT40- and HT40+ according to IEEE -802.11n Annex J. Channel availability may vary by location. - - ::::{code-block} none - freq HT40- HT40+ - 2.4 GHz 5-13 1-7 (1-9 in Europe/Japan) - 5 GHz 40,48,56,64 36,44,52,60 - :::: -::: - -:::{note} -40 MHz channels may switch their primary and secondary channels if -needed or creation of 40 MHz channel may be rejected based on overlapping -BSSes. These changes are done automatically when hostapd is setting up the -40 MHz channel. -::: -``` - -```{cfgcmd} set interfaces wireless \ capabilities ht delayed-block-ack - -Enable HT-delayed Block Ack ``[DELAYED-BA]`` -``` - -```{cfgcmd} set interfaces wireless \ capabilities ht dsss-cck-40 - -DSSS/CCK Mode in 40 MHz, this sets ``[DSSS_CCK-40]`` -``` - -```{cfgcmd} set interfaces wireless \ capabilities ht greenfield - -This enables the greenfield option which sets the ``[GF]`` option -``` - -```{cfgcmd} set interfaces wireless \ capabilities ht ldpc - -Enable LDPC coding capability -``` - -```{cfgcmd} set interfaces wireless \ capabilities ht lsig-protection - -Enable L-SIG TXOP protection capability -``` - -```{cfgcmd} set interfaces wireless \ capabilities ht max-amsdu \<3839 | 7935\> - -Maximum A-MSDU length 3839 (default) or 7935 octets -``` - -```{cfgcmd} set interfaces wireless \ capabilities ht short-gi \<20 | 40\> - -Short GI capabilities for 20 and 40 MHz -``` - -```{cfgcmd} set interfaces wireless \ capabilities ht smps \ - -Spatial Multiplexing Power Save (SMPS) settings -``` - -```{cfgcmd} set interfaces wireless \ capabilities ht stbc rx \ - -Enable receiving PPDU using STBC (Space Time Block Coding) -``` - -```{cfgcmd} set interfaces wireless \ capabilities ht stbc tx - -Enable sending PPDU using STBC (Space Time Block Coding) -``` - -##### VHT (Very High Throughput) capabilities (802.11ac) - -```{cfgcmd} set interfaces wireless \ capabilities vht antenna-count \ -``` - -% -% Number of antennas on this card - -```{cfgcmd} set interfaces wireless \ capabilities vht antenna-pattern-fixed - -Set if antenna pattern does not change during the lifetime of an association -``` - -```{cfgcmd} set interfaces wireless \ capabilities vht beamform \ - -Beamforming capabilities: -* ``single-user-beamformer`` - Support for operation as -single user beamformer -* ``single-user-beamformee`` - Support for operation as -single user beamformee -* ``multi-user-beamformer`` - Support for operation as -multi user beamformer -* ``multi-user-beamformee`` - Support for operation as -multi user beamformee -``` - -```{cfgcmd} set interfaces wireless \ capabilities vht center-channel-freq \ \ - -VHT operating channel center frequency - center freq 1 -(for use with 80, 80+80 and 160 modes) - -VHT operating channel center frequency - center freq 2 -(for use with the 80+80 mode) - -\ must be from 34 - 173. For 80 MHz channels it should be channel + 6. -``` - -```{cfgcmd} set interfaces wireless \ capabilities vht channel-set-width \<0 | 1 | 2 | 3\> - -* ``0`` - 20 or 40 MHz channel width (default) -* ``1`` - 80 MHz channel width -* ``2`` - 160 MHz channel width -* ``3`` - 80+80 MHz channel width -``` - -```{cfgcmd} set interfaces wireless \ capabilities vht ldpc - -Enable LDPC (Low Density Parity Check) coding capability -``` - -```{cfgcmd} set interfaces wireless \ capabilities vht link-adaptation - -VHT link adaptation capabilities -``` - -```{cfgcmd} set interfaces wireless \ capabilities vht max-mpdu \ - -Increase Maximum MPDU length to 7991 or 11454 octets (default 3895 octets) -``` - -```{cfgcmd} set interfaces wireless \ capabilities vht max-mpdu-exp \ - -Set the maximum length of A-MPDU pre-EOF padding that the station can -receive -``` - -```{cfgcmd} set interfaces wireless \ capabilities vht short-gi \<80 | 160\> - -Short GI capabilities -``` - -```{cfgcmd} set interfaces wireless \ capabilities vht stbc rx \ - -Enable receiving PPDU using STBC (Space Time Block Coding) -``` - -```{cfgcmd} set interfaces wireless \ capabilities vht stbc tx - -Enable sending PPDU using STBC (Space Time Block Coding) -``` - -```{cfgcmd} set interfaces wireless \ capabilities vht tx-powersave - -Enable VHT TXOP Power Save Mode -``` - -```{cfgcmd} set interfaces wireless \ capabilities vht vht-cf - -Station supports receiving VHT variant HT Control field -``` - -##### HE (High Efficiency) capabilities (802.11ax) - -```{cfgcmd} set interfaces wireless \ capabilities he antenna-pattern-fixed - -Tell the AP that antenna positions are fixed and will not change -during the lifetime of an association. -``` - -```{cfgcmd} set interfaces wireless \ capabilities he beamform \ - -Beamforming capabilities: -* ``single-user-beamformer`` - Support for operation as -single user beamformer -* ``single-user-beamformee`` - Support for operation as -single user beamformee -* ``multi-user-beamformer`` - Support for operation as multi -user beamformer -``` - -```{cfgcmd} set interfaces wireless \ capabilities he bss-color \ - -BSS coloring helps to prevent channel jamming when multiple APs use -the same channels. - -Valid values are 1..63 -``` - -```{cfgcmd} set interfaces wireless \ capabilities he center-channel-freq \ \ - -HE operating channel center frequency - center freq 1 -(for use with 80, 80+80 and 160 modes) - -HE operating channel center frequency - center freq 2 -(for use with the 80+80 mode) - -\ must be within 1..233. For 80 MHz channels it should be -channel + 6 and for 160 MHz channels, it should be channel + 14. -``` - -```{cfgcmd} set interfaces wireless \ capabilities he channel-set-width \ - -\ must be one of: - -* ``81`` - 20 MHz channel width (2.4GHz) -* ``83`` - 40 MHz channel width, secondary 20MHz channel above primary -channel (2.4GHz) -* ``84`` - 40 MHz channel width, secondary 20MHz channel below primary -channel (2.4GHz) -* ``131`` - 20 MHz channel width (6GHz) -* ``132`` - 40 MHz channel width (6GHz) -* ``133`` - 80 MHz channel width (6GHz) -* ``134`` - 160 MHz channel width (6GHz) -* ``135`` - 80+80 MHz channel width (6GHz) -``` - -```{cfgcmd} set interfaces wireless \ capabilities he coding-scheme \ - -This setting configures Spatial Stream and Modulation Coding Scheme -settings for HE mode (HE-MCS). It is usually not needed to set this -explicitly, but it might help with some WiFi adapters. - -\ must be one of: -* ``0`` - HE-MCS 0-7 -* ``1`` - HE-MCS 0-9 -* ``2`` - HE-MCS 0-11 -* ``3`` - HE-MCS is not supported -``` - -### Wireless options (Station/Client) - -The example creates a wireless station (commonly referred to as Wi-Fi client) -that accesses the network through the WAP defined in the above example. The -default physical device (`phy0`) is used. - -```none -set system wireless country-code de -set interfaces wireless wlan0 type station -set interfaces wireless wlan0 address dhcp -set interfaces wireless wlan0 ssid 'TEST' -set interfaces wireless wlan0 security wpa passphrase '12345678' -``` - -Resulting configuration: - -```none -system { - wireless { - country-code de - } -} -interfaces { - wireless wlan0 { - address dhcp - security { - wpa { - passphrase "12345678" - } - } - ssid TEST - type station - } -``` - -### Security - -{abbr}`WPA (Wi-Fi Protected Access)`, WPA2 Enterprise and WPA3 Enterprise in -combination with 802.1X based authentication can be used to authenticate -users or computers in a domain. - -The wireless client (supplicant) authenticates against the RADIUS server -(authentication server) using an {abbr}`EAP (Extensible Authentication -Protocol)` method configured on the RADIUS server. The WAP (also referred -to as authenticator) role is to send all authentication messages between the -supplicant and the configured authentication server, thus the RADIUS server -is responsible for authenticating the users. - -The WAP in this example has the following characteristics: -- IP address `192.168.2.1/24` -- Network ID (SSID) `Enterprise-TEST` -- WPA passphrase `12345678` -- Use 802.11n protocol -- Wireless channel `1` -- RADIUS server at `192.168.3.10` with shared-secret `VyOSPassword` - -```none -set system wireless country-code de -set interfaces wireless wlan0 address '192.168.2.1/24' -set interfaces wireless wlan0 type access-point -set interfaces wireless wlan0 channel 1 -set interfaces wireless wlan0 mode n -set interfaces wireless wlan0 ssid 'Enterprise-TEST' -set interfaces wireless wlan0 security wpa mode wpa2 -set interfaces wireless wlan0 security wpa cipher CCMP -set interfaces wireless wlan0 security wpa radius server 192.168.3.10 key 'VyOSPassword' -set interfaces wireless wlan0 security wpa radius server 192.168.3.10 port 1812 -``` - -Resulting configuration: - -```none -system { - wireless { - country-code de - } -} -interfaces { - [...] - wireless wlan0 { - address 192.168.2.1/24 - channel 1 - mode n - security { - wpa { - cipher CCMP - mode wpa2 - radius { - server 192.168.3.10 { - key 'VyOSPassword' - port 1812 - } - } - } - } - ssid "Enterprise-TEST" - type access-point - } -} -``` - -### VLAN -#### Regular VLANs (802.1q) - -```{cmdincludemd} /_include/interface-vlan-8021q.txt -:var0: wireless -:var1: wlan0 -``` - -#### QinQ (802.1ad) - -```{cmdincludemd} /_include/interface-vlan-8021ad.txt -:var0: wireless -:var1: wlan0 -``` - -## Operation - -```{opcmd} show interfaces wireless info -``` - -Use this command to view operational status and wireless-specific information -about all wireless interfaces. - -```none -vyos@vyos:~$ show interfaces wireless info -Interface Type SSID Channel -wlan0 access-point VyOS-TEST-0 1 -``` - -```{opcmd} show interfaces wireless detail -``` - -Show the operational status and detailed wireless-specific -information about all wireless interfaces. - -```none -vyos@vyos:~$ show interfaces wireless detail -wlan0: mtu 1500 qdisc noqueue state UP group default qlen 1000 - link/ether XX:XX:XX:XX:XX:c3 brd XX:XX:XX:XX:XX:ff - inet xxx.xxx.99.254/24 scope global wlan0 - valid_lft forever preferred_lft forever - inet6 fe80::xxxx:xxxx:fe54:2fc3/64 scope link - valid_lft forever preferred_lft forever - - RX: bytes packets errors dropped overrun mcast - 66072 282 0 0 0 0 - TX: bytes packets errors dropped carrier collisions - 83413 430 0 0 0 0 - -wlan1: mtu 1500 qdisc noqueue state UP group default qlen 1000 - link/ether XX:XX:XX:XX:XX:c3 brd XX:XX:XX:XX:XX:ff - inet xxx.xxx.100.254/24 scope global wlan0 - valid_lft forever preferred_lft forever - inet6 fe80::xxxx:xxxx:ffff:2ed3/64 scope link - valid_lft forever preferred_lft forever - - RX: bytes packets errors dropped overrun mcast - 166072 5282 0 0 0 0 - TX: bytes packets errors dropped carrier collisions - 183413 5430 0 0 0 0 -``` - -```{opcmd} show interfaces wireless \ -``` - -This command shows both status and statistics on the specified wireless -interface. The wireless interface identifier can range from wlan0 to wlan999. - -```none -vyos@vyos:~$ show interfaces wireless wlan0 -wlan0: mtu 1500 qdisc noqueue state UP group default qlen 1000 - link/ether XX:XX:XX:XX:XX:c3 brd XX:XX:XX:XX:XX:ff - inet xxx.xxx.99.254/24 scope global wlan0 - valid_lft forever preferred_lft forever - inet6 fe80::xxxx:xxxx:fe54:2fc3/64 scope link - valid_lft forever preferred_lft forever - - RX: bytes packets errors dropped overrun mcast - 66072 282 0 0 0 0 - TX: bytes packets errors dropped carrier collisions - 83413 430 0 0 0 0 -``` - -```{opcmd} show interfaces wireless \ brief -``` - -This command gives a brief status overview of a specified wireless interface. -The wireless interface identifier can range from wlan0 to wlan999. - -```none -vyos@vyos:~$ show interfaces wireless wlan0 brief -Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down -Interface IP Address S/L Description ---------- ---------- --- ----------- -wlan0 192.168.2.254/24 u/u -``` - -```{opcmd} show interfaces wireless \ queue -``` - -Use this command to view wireless interface queue information. -The wireless interface identifier can range from wlan0 to wlan999. - -```none -vyos@vyos:~$ show interfaces wireless wlan0 queue -qdisc pfifo_fast 0: root bands 3 priomap 1 2 2 2 1 2 0 0 1 1 1 1 1 1 1 1 - Sent 810323 bytes 6016 pkt (dropped 0, overlimits 0 requeues 0) - rate 0bit 0pps backlog 0b 0p requeues 0 -``` - -```{opcmd} show interfaces wireless \ scan -``` - -This command is used to retrieve information about WAP within the range of your -wireless interface. This command is useful on wireless interfaces configured -in station mode. - -:::{note} -Scanning is not supported on all wireless drivers and wireless -hardware. Refer to your driver and wireless hardware documentation for -further details. -::: -```none -vyos@vyos:~$ show interfaces wireless wlan0 scan -Address SSID Channel Signal (dbm) -00:53:3b:88:6e:d8 WLAN-576405 1 -64.00 -00:53:3b:88:6e:da Telekom_FON 1 -64.00 -00:53:00:f2:c2:a4 BabyView_F2C2A4 6 -60.00 -00:53:3b:88:6e:d6 Telekom_FON 100 -72.00 -00:53:3b:88:6e:d4 WLAN-576405 100 -71.00 -00:53:44:a4:96:ec KabelBox-4DC8 56 -81.00 -00:53:d9:7a:67:c2 WLAN-741980 1 -75.00 -00:53:7c:99:ce:76 Vodafone Homespot 1 -86.00 -00:53:44:a4:97:21 KabelBox-4DC8 1 -78.00 -00:53:44:a4:97:21 Vodafone Hotspot 1 -79.00 -00:53:44:a4:97:21 Vodafone Homespot 1 -79.00 -00:53:86:40:30:da Telekom_FON 1 -86.00 -00:53:7c:99:ce:76 Vodafone Hotspot 1 -86.00 -00:53:44:46:d2:0b Vodafone Hotspot 1 -87.00 -``` - -## Examples - -The following example creates a WAP. When configuring multiple WAP interfaces, -you must specify unique IP addresses, channels, Network IDs commonly referred -to as {abbr}`SSID (Service Set Identifier)`, and MAC addresses. - -The WAP in this example has the following characteristics: -- IP address `192.168.2.1/24` -- Network ID (SSID) `TEST` -- WPA passphrase `12345678` -- Use 802.11n protocol -- Wireless channel `1` - -```none -set system wireless country-code de -set interfaces wireless wlan0 address '192.168.2.1/24' -set interfaces wireless wlan0 type access-point -set interfaces wireless wlan0 channel 1 -set interfaces wireless wlan0 mode n -set interfaces wireless wlan0 ssid 'TEST' -set interfaces wireless wlan0 security wpa mode wpa2 -set interfaces wireless wlan0 security wpa cipher CCMP -set interfaces wireless wlan0 security wpa passphrase '12345678' -``` - -Resulting configuration: - -```none -system { - wireless { - country-code de - } -} -interfaces { - [...] - wireless wlan0 { - address 192.168.2.1/24 - channel 1 - mode n - security { - wpa { - cipher CCMP - mode wpa2 - passphrase "12345678" - } - } - ssid "TEST" - type access-point - } -} -``` - -To enable access point functionality, configure a DHCP server for this -interface's network, or add the interface to an existing local bridge -(see {ref}`bridge-interface` for details). - -### Wi-Fi 6/6E (802.11ax) - -The following examples configure Wi-Fi 6 (2.4 GHz) and Wi-Fi 6E (6 GHz) -{abbr}`APs (Access Points)` with the following parameters: -- Network ID (SSID): `test.ax` -- WPA passphrase: `super-dooper-secure-passphrase` -- Protocol: 802.11ax -- Wireless channel for 2.4 GHz: `11` -- Wireless channel for 6 GHz: `5` - -#### Example configuration: Wi-Fi 6 at 2.4 GHz - -You may expect real throughput around 10 MB/s or higher in crowded areas. - -```none -set system wireless country-code de -set interfaces wireless wlan0 capabilities he antenna-pattern-fixed -set interfaces wireless wlan0 capabilities he beamform multi-user-beamformer -set interfaces wireless wlan0 capabilities he beamform single-user-beamformee -set interfaces wireless wlan0 capabilities he beamform single-user-beamformer -set interfaces wireless wlan0 capabilities he bss-color 13 -set interfaces wireless wlan0 capabilities he channel-set-width 81 -set interfaces wireless wlan0 capabilities ht 40mhz-incapable -set interfaces wireless wlan0 capabilities ht channel-set-width ht20 -set interfaces wireless wlan0 capabilities ht channel-set-width ht40+ -set interfaces wireless wlan0 capabilities ht channel-set-width ht40- -set interfaces wireless wlan0 capabilities ht short-gi 20 -set interfaces wireless wlan0 capabilities ht short-gi 40 -set interfaces wireless wlan0 capabilities ht stbc rx 2 -set interfaces wireless wlan0 capabilities ht stbc tx -set interfaces wireless wlan0 channel 11 -set interfaces wireless wlan0 description "802.11ax 2.4GHz" -set interfaces wireless wlan0 mode ax -set interfaces wireless wlan0 security wpa cipher CCMP -set interfaces wireless wlan0 security wpa cipher CCMP-256 -set interfaces wireless wlan0 security wpa cipher GCMP-256 -set interfaces wireless wlan0 security wpa cipher GCMP -set interfaces wireless wlan0 security wpa mode wpa2 -set interfaces wireless wlan0 security wpa passphrase super-dooper-secure-passphrase -set interfaces wireless wlan0 ssid test.ax -set interfaces wireless wlan0 type access-point -commit -``` - -Resulting configuration: - -```none -system { - wireless { - country-code de - } -} -interfaces { - [...] - wireless wlan0 { - capabilities { - he { - antenna-pattern-fixed - beamform { - multi-user-beamformer - single-user-beamformee - single-user-beamformer - } - bss-color 13 - channel-set-width 81 - } - ht { - 40mhz-incapable - channel-set-width ht20 - channel-set-width ht40+ - channel-set-width ht40- - short-gi 20 - short-gi 40 - stbc { - rx 2 - tx - } - } - } - channel 11 - description "802.11ax 2.4GHz" - hw-id [...] - mode ax - physical-device phy0 - security { - wpa { - cipher CCMP - cipher CCMP-256 - cipher GCMP-256 - cipher GCMP - mode wpa2 - passphrase super-dooper-secure-passphrase - } - } - ssid test.ax - type access-point - } -} -``` - -#### Example configuration: Wi-Fi 6E at 6 GHz - -You may expect real throughput between 50 MB/s and 150 MB/s, depending on -obstructions from walls, water, metal, or other materials -with high electromagnetic damping at 6 GHz. Best results are achieved -with the AP being in the same room and in line-of-sight. - -```none -set system wireless country-code de -set interfaces wireless wlan0 capabilities he antenna-pattern-fixed -set interfaces wireless wlan0 capabilities he beamform multi-user-beamformer -set interfaces wireless wlan0 capabilities he beamform single-user-beamformee -set interfaces wireless wlan0 capabilities he beamform single-user-beamformer -set interfaces wireless wlan0 capabilities he bss-color 13 -set interfaces wireless wlan0 capabilities he channel-set-width 134 -set interfaces wireless wlan0 capabilities he center-channel-freq freq-1 15 -set interfaces wireless wlan0 channel 5 -set interfaces wireless wlan0 description "802.11ax 6GHz" -set interfaces wireless wlan0 mode ax -set interfaces wireless wlan0 security wpa cipher CCMP -set interfaces wireless wlan0 security wpa cipher CCMP-256 -set interfaces wireless wlan0 security wpa cipher GCMP-256 -set interfaces wireless wlan0 security wpa cipher GCMP -set interfaces wireless wlan0 security wpa mode wpa3 -set interfaces wireless wlan0 security wpa passphrase super-dooper-secure-passphrase -set interfaces wireless wlan0 mgmt-frame-protection required -set interfaces wireless wlan0 enable-bf-protection -set interfaces wireless wlan0 ssid test.ax -set interfaces wireless wlan0 type access-point -set interfaces wireless wlan0 stationary-ap -commit -``` - -Resulting configuration: - -```none -system { - wireless { - country-code de - } -} -interfaces { - [...] - wireless wlan0 { - capabilities { - he { - antenna-pattern-fixed - beamform { - multi-user-beamformer - single-user-beamformee - single-user-beamformer - } - bss-color 13 - center-channel-freq { - freq-1 15 - } - channel-set-width 134 - } - } - channel 5 - description "802.11ax 6GHz" - enable-bf-protection - hw-id [...] - mgmt-frame-protection required - mode ax - physical-device phy0 - security { - wpa { - cipher CCMP - cipher CCMP-256 - cipher GCMP-256 - cipher GCMP - mode wpa3 - passphrase super-dooper-secure-passphrase - } - } - ssid test.ax - stationary-ap - type access-point - } -} -``` - -(wireless-interface-intel-ax200)= - -### Intel AX200 - -The Intel AX200 card does not work out of the box in AP mode. You can -still put this card into AP mode using the following configuration: - -```none -set system wireless country-code 'us' -set interfaces wireless wlan0 channel '1' -set interfaces wireless wlan0 mode 'n' -set interfaces wireless wlan0 physical-device 'phy0' -set interfaces wireless wlan0 ssid 'VyOS' -set interfaces wireless wlan0 type 'access-point' -``` - diff --git a/docs/configuration/interfaces/md-wwan.md b/docs/configuration/interfaces/md-wwan.md deleted file mode 100644 index e8121f28..00000000 --- a/docs/configuration/interfaces/md-wwan.md +++ /dev/null @@ -1,355 +0,0 @@ ---- -lastproofread: '2026-03-30' ---- - -(wwan-interface)= - -# WWAN - -{abbr}`WWAN (Wireless Wide Area Network)` interfaces provide access to cellular -networks via a cellular modem or card. - -Configure these interfaces under the `interfaces wwan` node. - -## Configuration - -### Common interface configuration - -```{cmdincludemd} /_include/interface-address-with-dhcp.txt -:var0: wwan -:var1: wwan0 -``` - -```{cmdincludemd} /_include/interface-description.txt -:var0: wwan -:var1: wwan0 -``` - -```{cmdincludemd} /_include/interface-disable.txt -:var0: wwan -:var1: wwan0 -``` - -```{cmdincludemd} /_include/interface-disable-link-detect.txt -:var0: wwan -:var1: wwan0 -``` - -```{cmdincludemd} /_include/interface-mtu.txt -:var0: wwan -:var1: wwan0 -``` - -```{cmdincludemd} /_include/interface-ip.txt -:var0: wwan -:var1: wwan0 -``` - -```{cmdincludemd} /_include/interface-ipv6.txt -:var0: wwan -:var1: wwan0 -``` - -```{cmdincludemd} /_include/interface-vrf.txt -:var0: wwan -:var1: wwan0 -``` - -**DHCP(v6)** - -```{cmdincludemd} /_include/interface-dhcp-options.txt -:var0: wwan -:var1: wwan0 -``` - -```{cmdincludemd} /_include/interface-dhcpv6-options.txt -:var0: wwan -:var1: wwan0 -``` - -```{cmdincludemd} /_include/interface-dhcpv6-prefix-delegation.txt -:var0: wwan -:var1: wwan0 -``` - - -### WWAN options - -```{cfgcmd} set interfaces wwan \ apn \ - -**Configure the** {abbr}`APN (Access Point Name)` **for the WWAN connection.** - -Every WWAN connection requires an {abbr}`APN (Access Point Name)` to connect to -the cellular network. - -This parameter is mandatory. Contact your service provider for the correct -{abbr}`APN (Access Point Name)`. -``` - - -## Operation - -```{opcmd} show interfaces wwan \ - -Show the operational status and traffic statistics for the specified WWAN -interface. - -:::{code-block} none -vyos@vyos:~$ show interfaces wwan wwan0 -wwan0: mtu 1500 qdisc pfifo_fast state UNKNOWN group default qlen 1000 -link/ether 02:c2:f3:00:01:02 brd ff:ff:ff:ff:ff:ff -inet 10.155.144.12/30 brd 10.155.144.15 scope global dynamic wwan0 -valid_lft 7012sec preferred_lft 7012sec -inet6 fe80::c2:f3ff:fe00:0102/64 scope link -valid_lft forever preferred_lft forever - -RX: bytes packets errors dropped overrun mcast -640 2 0 0 0 0 -TX: bytes packets errors dropped carrier collisions -3229 16 0 0 0 0 -::: -``` - - -```{opcmd} show interfaces wwan \ summary - -Show WWAN module hardware characteristics and connection information. - -:::{code-block} none -vyos@vyos:~$ show interfaces wwan wwan0 summary --------------------------------- -General | dbus path: /org/freedesktop/ModemManager1/Modem/0 -| device id: 79f4e9cc2e9fc8d4a3b8c8f6327c2e363170194d --------------------------------- -Hardware | manufacturer: Sierra Wireless, Incorporated -| model: MC7710 -| revision: SWI9200X_03.05.29.03ap r6485 CNSHZ-ED-XP0031 2014/12/02 17:53:15 -| h/w revision: 1.0 -| supported: gsm-umts, lte -| current: gsm-umts, lte -| equipment id: 358xxxxxxxxxxxx --------------------------------- -System | device: /sys/devices/pci0000:00/0000:00:13.0/usb3/3-1/3-1.3 -| drivers: qcserial, qmi_wwan -| plugin: Generic -| primary port: cdc-wdm0 -| ports: ttyUSB0 (qcdm), ttyUSB2 (at), cdc-wdm0 (qmi), wwan0 (net) --------------------------------- -Numbers | own: 4917xxxxxxxx --------------------------------- -Status | lock: sim-pin2 -| unlock retries: sim-pin (3), sim-pin2 (3), sim-puk (10), sim-puk2 (10) -| state: connected -| power state: on -| access tech: lte -| signal quality: 63% (recent) --------------------------------- -Modes | supported: allowed: 2g; preferred: none -| allowed: 3g; preferred: none -| allowed: 4g; preferred: none -| allowed: 2g, 3g; preferred: 3g -| allowed: 2g, 3g; preferred: 2g -| allowed: 2g, 4g; preferred: 4g -| allowed: 2g, 4g; preferred: 2g -| allowed: 3g, 4g; preferred: 3g -| allowed: 3g, 4g; preferred: 4g -| allowed: 2g, 3g, 4g; preferred: 4g -| allowed: 2g, 3g, 4g; preferred: 3g -| allowed: 2g, 3g, 4g; preferred: 2g -| current: allowed: 2g, 3g, 4g; preferred: 2g --------------------------------- -Bands | supported: egsm, dcs, pcs, utran-1, utran-8, eutran-1, eutran-3, -| eutran-7, eutran-8, eutran-20 -| current: egsm, dcs, pcs, utran-1, utran-8, eutran-1, eutran-3, -| eutran-7, eutran-8, eutran-20 --------------------------------- -IP | supported: ipv4, ipv6, ipv4v6 --------------------------------- -3GPP | imei: 358xxxxxxxxxxxx -| operator id: 26201 -| operator name: Telekom.de -| registration: home --------------------------------- -3GPP EPS | ue mode of operation: ps-1 --------------------------------- -SIM | dbus path: /org/freedesktop/ModemManager1/SIM/0 --------------------------------- -Bearer | dbus path: /org/freedesktop/ModemManager1/Bearer/0 -::: -``` - -```{opcmd} show interfaces wwan \ capabilities - -Show WWAN module radio capabilities. - -:::{code-block} none -vyos@vyos:~$ show interfaces wwan wwan0 capabilities -Max TX channel rate: '50000000' -Max RX channel rate: '100000000' -Data Service: 'simultaneous-cs-ps' -SIM: 'supported' -Networks: 'gsm, umts, lte' -Bands: 'gsm-dcs-1800, gsm-900-extended, gsm-900-primary, gsm-pcs-1900, wcdma-2100, wcdma-900' -LTE bands: '1, 3, 7, 8, 20' -::: -``` - - -```{opcmd} show interfaces wwan \ firmware - -Show WWAN module firmware information. - -:::{code-block} none -vyos@vyos:~$ show interfaces wwan wwan0 firmware -Model: MC7710 -Boot version: SWI9200X_03.05.29.03bt r6485 CNSHZ-ED-XP0031 2014/12/02 17:33:08 -AMSS version: SWI9200X_03.05.29.03ap r6485 CNSHZ-ED-XP0031 2014/12/02 17:53:15 -SKU ID: unknown -Package ID: unknown -Carrier ID: 0 -Config version: unknown -::: -``` - -```{opcmd} show interfaces wwan \ imei - -Show WWAN module IMEI. - -:::{code-block} none -vyos@vyos:~$ show interfaces wwan wwan0 imei -ESN: '0' -IMEI: '358xxxxxxxxxxxx' -MEID: 'unknown' -::: -``` - -```{opcmd} show interfaces wwan \ imsi - -Show the IMSI of the associated SIM card. - -:::{code-block} none -vyos@vyos:~$ show interfaces wwan wwan0 imsi -IMSI: '262xxxxxxxxxxxx' -::: -``` - -```{opcmd} show interfaces wwan \ model - -Show WWAN module model. - -:::{code-block} none -vyos@vyos:~$ show interfaces wwan wwan0 model -Model: 'MC7710' -::: -``` - -```{opcmd} show interfaces wwan \ msisdn - -Show the MSISDN of the associated SIM card. - -:::{code-block} none -vyos@vyos:~$ show interfaces wwan wwan0 msisdn -MSISDN: '4917xxxxxxxx' -::: -``` - -```{opcmd} show interfaces wwan \ revision - -Show WWAN module hardware revision. - -:::{code-block} none -vyos@vyos:~$ show interfaces wwan wwan0 revision -Revision: 'SWI9200X_03.05.29.03ap r6485 CNSHZ-ED-XP0031 2014/12/02 17:53:15' -::: -``` - -```{opcmd} show interfaces wwan \ signal - -Show signal information for the cellular connection. - -:::{code-block} none -vyos@vyos:~$ show interfaces wwan wwan0 signal -LTE: -RSSI: '-74 dBm' -RSRQ: '-7 dB' -RSRP: '-100 dBm' -SNR: '13.0 dB' -Radio Interface: 'lte' -Active Band Class: 'eutran-3' -Active Channel: '1300' -::: -``` - -```{opcmd} show interfaces wwan \ sim - -Show WWAN module SIM card information. - -:::{code-block} none -vyos@vyos:~$ show interfaces wwan wwan0 sim -Provisioning applications: -Primary GW: slot '1', application '1' -Primary 1X: session doesn't exist -Secondary GW: session doesn't exist -Secondary 1X: session doesn't exist -Slot [1]: -Card state: 'present' -UPIN state: 'not-initialized' -UPIN retries: '0' -UPUK retries: '0' -Application [1]: -Application type: 'usim (2)' -Application state: 'ready' -Application ID: -A0:00:00:00:87:10:02:FF:49:94:20:89:03:10:00:00 -Personalization state: 'ready' -UPIN replaces PIN1: 'no' -PIN1 state: 'disabled' -PIN1 retries: '3' -PUK1 retries: '10' -PIN2 state: 'enabled-not-verified' -PIN2 retries: '3' -PUK2 retries: '10' -::: -``` - - -## Example - -The following example shows how to configure a cellular connection using a -Sierra Wireless MC7710 miniPCIe card that operates over USB despite its form -factor. The card is installed in a {ref}`pc-engines-apu4`. - -```none -set interfaces wwan wwan0 apn 'internet.telekom' -set interfaces wwan wwan0 address 'dhcp' -``` - - -## Supported hardware - -The following WWAN modules have been successfully tested with a -{ref}`pc-engines-apu4` board: -- Sierra Wireless AirPrime MC7304 miniPCIe card (LTE) -- Sierra Wireless AirPrime MC7430 miniPCIe card (LTE) -- Sierra Wireless AirPrime MC7455 miniPCIe card (LTE) -- Sierra Wireless AirPrime MC7710 miniPCIe card (LTE) -- Huawei ME909u-521 miniPCIe card (LTE) -- Huawei ME909s-120 miniPCIe card (LTE) -- HP LT4120 Snapdragon X5 LTE - -## Firmware update - -WWAN modules include reprogrammable firmware, and most vendors regularly -provide updates for it. - -Since VyOS communicates with these devices via the QMI interface, you can -update firmware directly within the system using the `qmi-firmware-update` -utility. - -The following example shows how to update the firmware for a Sierra Wireless -MC7710 module using the provided .cwe file. - -```bash -$ sudo qmi-firmware-update --update -d 1199:68a2 \ - 9999999_9999999_9200_03.05.14.00_00_generic_000.000_001_SPKG_MC.cwe -``` diff --git a/docs/configuration/loadbalancing/md-haproxy.md b/docs/configuration/loadbalancing/md-haproxy.md deleted file mode 100644 index d60c5248..00000000 --- a/docs/configuration/loadbalancing/md-haproxy.md +++ /dev/null @@ -1,510 +0,0 @@ ---- -lastproofread: '2026-04-06' ---- - -# HAproxy - -```{include} /_include/need_improvement.txt -``` - -HAProxy is a load balancer and proxy server that provides -high-availability, load balancing, and proxying for TCP (level 4) and -HTTP-based (level 7) applications. - -## Configuration - -Service configuration specifies the port to bind to. Backend -configuration defines the load balancing method and specifies the backend -servers. - -### Service - -```{cfgcmd} set load-balancing haproxy service \ listen-address \ - -Set the IP address for the service to bind to. By default, the service -listens on all IPv4 and IPv6 addresses. -``` - -```{cfgcmd} set load-balancing haproxy service \ port \ - -Create service ** to listen on \ -``` - -```{cfgcmd} set load-balancing haproxy service \ mode \ - -Configure service ** mode TCP or HTTP -``` - -```{cfgcmd} set load-balancing haproxy service \ backend \ - -Configure service ** to use the backend \ -``` - -```{cfgcmd} set load-balancing haproxy service \ ssl certificate \ - -Set the SSL certificate \ for service \. You can define -multiple certificates. -``` - -```{cfgcmd} set load-balancing haproxy service \ http-response-headers \ value \ - -Set custom HTTP headers to include in all responses. -``` - -```{cfgcmd} set load-balancing haproxy service \ logging facility \ level \ - -Specify facility and level for logging. -For an explanation on {ref}`syslog_facilities` and -{ref}`syslog_severity_level`, -see tables in the syslog configuration section. -``` - -```{cfgcmd} set load-balancing haproxy service \ timeout client \ - -Set the maximum inactivity time on the client side for this service. -Value range 1-3600 seconds. -``` - -```{cfgcmd} set load-balancing haproxy service \ http-compression algorithm \ - -Set the compression algorithm to be used when compressing HTTP responses. -``` - -```{cfgcmd} set load-balancing haproxy service \ http-compression mime-type \ - -Set the list of HTTP response MIME types which haproxy will attempt to -compress, if received uncompressed from backend server. -``` - -#### Rules - -Rules control and route incoming traffic to specific backends based on -predefined conditions. Rules define matching criteria and specify actions -to perform. - -```{cfgcmd} set load-balancing haproxy service \ rule \ domain-name \ - -Match domain name -``` - -````{cfgcmd} set load-balancing haproxy service \ rule \ ssl \ - -```{eval-rst} -SSL match Server Name Indication (SNI) option: - * ``req-ssl-sni`` SSL Server Name Indication (SNI) request match - * ``ssl-fc-sni`` SSL frontend connection Server Name Indication match - * ``ssl-fc-sni-end`` SSL frontend match end of connection Server Name - - Indication -``` -```` - -````{cfgcmd} set load-balancing haproxy service \ rule \ url-path \ \ - -Define URL path matching rules for a specific service. Use this command -to specify how to match the URL path against incoming requests. - -```{eval-rst} -The available options for are: - * ``begin`` Matches the beginning of the URL path - * ``end`` Matches the end of the URL path. - * ``exact`` Matches the URL path exactly. -``` -```` - -```{cfgcmd} set load-balancing haproxy service \ rule \ set backend \ - -Assign a specific backend to a rule -``` - -```{cfgcmd} set load-balancing haproxy service \ rule \ redirect-location \ - -Redirect URL to a new location. -``` - -### Backend - -````{cfgcmd} set load-balancing haproxy backend \ balance \ - -Specify the load balancing algorithm for distributing requests among -available servers. - -```{eval-rst} -Balance algorithms: - * ``source-address`` Distributes requests based on the source IP address - of the client. - * ``round-robin`` Distributes requests in a circular manner, - sequentially sending each request to the next server in line. - * ``least-connection`` Distributes requests to the server with the fewest - active connections. -``` -```` - -```{cfgcmd} set load-balancing haproxy backend \ mode \ - -Configure backend ** mode TCP or HTTP. -``` - -```{cfgcmd} set load-balancing haproxy backend \ server \ address \ - -Set the address of the backend server that receives incoming traffic. -``` - -```{cfgcmd} set load-balancing haproxy backend \ server \ port \ - -Set the address of the backend port. -``` - -```{cfgcmd} set load-balancing haproxy backend \ server \ check - -Active health check backend server. -``` - -```{cfgcmd} set load-balancing haproxy backend \ server \ check port \ - -Set an alternative port number for health checks. -Overrides the default server port used for TCP/HTTP checks. -``` - -```{cfgcmd} set load-balancing haproxy backend \ server \ send-proxy - -Send a Proxy Protocol version 1 header (text format). -``` - -```{cfgcmd} set load-balancing haproxy backend \ server \ send-proxy-v2 - -Send a Proxy Protocol version 2 header (binary format). -``` - -```{cfgcmd} set load-balancing haproxy backend \ ssl ca-certificate \ - -Use SSL encryption for backend requests and authenticate the backend -against ````. -``` - -```{cfgcmd} set load-balancing haproxy backend \ ssl no-verify - -Use SSL encryption for backend requests without validating the server -certificate. -``` - -```{cfgcmd} set load-balancing haproxy backend \ http-response-headers \ value \ - -Set custom HTTP headers to include in all responses from the backend. -``` - -```{cfgcmd} set load-balancing haproxy backend \ logging facility \ level \ - -Specify facility and level for logging. -For an explanation on {ref}`syslog_facilities` and -{ref}`syslog_severity_level`, -see tables in the syslog configuration section. -``` - -```{cfgcmd} set load-balancing haproxy backend \ timeout check \ - -Set the timeout in seconds for established connections. -Value range 1-3600 seconds. -``` -```{cfgcmd} set load-balancing haproxy backend \ timeout connect \ - -Set the maximum time to wait for a connection attempt to a server to succeed. -Value range 1-3600 seconds. -``` - - -```{cfgcmd} set load-balancing haproxy backend \ timeout server \ - -Set the maximum inactivity time on the server side. -Value range 1-3600 seconds. -``` - -### Global - -Global configuration parameters: - -```{cfgcmd} set load-balancing haproxy global-parameters max-connections \ - -Limit maximum number of connections -``` - - -```{cfgcmd} set load-balancing haproxy global-parameters ssl-bind-ciphers \ - -Limit the cipher algorithms allowed during SSL/TLS handshake. -``` - - -```{cfgcmd} set load-balancing haproxy global-parameters tls-version-min \ - -Specify the minimum required TLS version 1.2 or 1.3 -``` - - -```{cfgcmd} set load-balancing haproxy global-parameters logging facility \ level \ - -Specify facility and level for logging. -For an explanation on {ref}`syslog_facilities` and -{ref}`syslog_severity_level`, -see tables in the syslog configuration section. -``` - - -```{cfgcmd} set load-balancing haproxy timeout check \ - -Set the timeout in seconds for established connections. -Value range 1-3600 seconds. Default is 5 seconds. -``` - - -```{cfgcmd} set load-balancing haproxy timeout client \ - -Set the maximum inactivity time on the client side. -Value range 1-3600 seconds. Default is 50 seconds. -``` - - -```{cfgcmd} set load-balancing haproxy timeout connect \ - -Set the maximum time to wait for a connection attempt to a server to succeed. -Value range 1-3600 seconds. Default is 10 seconds. -``` - - -```{cfgcmd} set load-balancing haproxy timeout server \ - -Set the maximum inactivity time on the server side. -Value range 1-3600 seconds. Default is 50 seconds. -``` - -## Health checks - - -### HTTP checks - - -Use HTTP health checks to monitor web applications that provide health status -information and determine their availability. - -```{cfgcmd} set load-balancing haproxy backend \ http-check - -Enables HTTP health checks using OPTION HTTP requests against '/' and -expecting a successful response code in the 200-399 range. -``` - - -```{cfgcmd} set load-balancing haproxy backend \ http-check method \ - -Set the HTTP method: ``OPTION``, ``GET``, ``POST``, or ``PUT``. -``` - - -```{cfgcmd} set load-balancing haproxy backend \ http-check uri \ - -Set the endpoint to use for health checks. -``` - - -````{cfgcmd} set load-balancing haproxy backend \ http-check expect \ - -Set the expected result condition for a server to be considered healthy. - -```{eval-rst} -Some possible examples are: - * ``status 200`` Expecting a 200 response code - * ``status 200-399`` Expecting a non-failure response code - * ``string success`` Expecting the string success in the response body -``` -```` - -### TCP checks - -Configure health checks for TCP mode backends. You can configure protocol-aware -checks for a range of Layer 7 protocols: - -````{cfgcmd} set load-balancing haproxy backend \ health-check \ - -```{eval-rst} -Available health check protocols: - * ``ldap`` LDAP protocol check. - * ``redis`` Redis protocol check. - * ``mysql`` MySQL protocol check. - * ``pgsql`` PostgreSQL protocol check. - * ``smtp`` SMTP protocol check. -``` -```` - -:::{note} -If you specify a server to check but do not configure a -protocol, HAProxy performs a basic TCP health check. A server is online if -it responds to a connection attempt with a valid `SYN/ACK` packet. -::: -## Redirect HTTP to HTTPS - -Configure a HAProxy service for HTTP that listens on port 80 and redirects -incoming requests to HTTPS: - -```none -set load-balancing haproxy service http port '80' -set load-balancing haproxy service http redirect-http-to-https -``` - -You can use a different service name; in this example, `http` is just for -convenience. - -## Examples -### Level 4 balancing - -This configuration enables the TCP reverse proxy for the `my-tcp-api` -service. Incoming TCP connections on port 8888 are load balanced across the -backend servers (srv01 and srv02) using the round-robin load balancing -algorithm. - -```none -set load-balancing haproxy service my-tcp-api backend 'bk-01' -set load-balancing haproxy service my-tcp-api mode 'tcp' -set load-balancing haproxy service my-tcp-api port '8888' - -set load-balancing haproxy backend bk-01 balance 'round-robin' -set load-balancing haproxy backend bk-01 mode 'tcp' - -set load-balancing haproxy backend bk-01 server srv01 address '192.0.2.11' -set load-balancing haproxy backend bk-01 server srv01 port '8881' -set load-balancing haproxy backend bk-01 server srv02 address '192.0.2.12' -set load-balancing haproxy backend bk-01 server srv02 port '8882' -``` - -### Balancing based on domain name - -The following configuration demonstrates how to use VyOS -to achieve load balancing based on the domain name: - -The HTTP service listens on TCP port 80. - -Rule 10 matches requests with the domain name `node1.example.com` and -forwards them to the backend `bk-api-01`. - -Rule 20 matches requests with the domain name `node2.example.com` and -forwards them to the backend `bk-api-02`. - -```none -set load-balancing haproxy service http description 'bind app listen on 443 port' -set load-balancing haproxy service http mode 'tcp' -set load-balancing haproxy service http port '80' - -set load-balancing haproxy service http rule 10 domain-name 'node1.example.com' -set load-balancing haproxy service http rule 10 set backend 'bk-api-01' -set load-balancing haproxy service http rule 20 domain-name 'node2.example.com' -set load-balancing haproxy service http rule 20 set backend 'bk-api-02' - -set load-balancing haproxy backend bk-api-01 description 'My API-1' -set load-balancing haproxy backend bk-api-01 mode 'tcp' -set load-balancing haproxy backend bk-api-01 server api01 address '127.0.0.1' -set load-balancing haproxy backend bk-api-01 server api01 port '4431' -set load-balancing haproxy backend bk-api-02 description 'My API-2' -set load-balancing haproxy backend bk-api-02 mode 'tcp' -set load-balancing haproxy backend bk-api-02 server api01 address '127.0.0.2' -set load-balancing haproxy backend bk-api-02 server api01 port '4432' -``` - -### Terminate SSL - -The following configuration terminates SSL on the router. - -The `http` service listens on port 80 and redirects HTTP requests to -HTTPS. - -The `https` service listens on port 443 with the `bk-default` backend -and handles HTTPS traffic using the `cert` certificate for SSL termination. -The HSTS header is set with a 1-year expiry to tell browsers to always use -SSL for the site. - -Rule 10 matches requests with the exact URL path `/.well-known/xxx` and -redirects them to `/certs/`. - -Rule 20 matches requests with URL paths ending in `/mail` or the exact -path `/email/bar` and redirects them to `/postfix/`. - -Global parameters include a maximum connection limit of 4000 and a minimum -TLS version of 1.3. - -```none -set load-balancing haproxy service http description 'Force redirect to HTTPS' -set load-balancing haproxy service http port '80' -set load-balancing haproxy service http redirect-http-to-https - -set load-balancing haproxy service https backend 'bk-default' -set load-balancing haproxy service https description 'listen on 443 port' -set load-balancing haproxy service https mode 'http' -set load-balancing haproxy service https port '443' -set load-balancing haproxy service https ssl certificate 'cert' -set load-balancing haproxy service https http-response-headers Strict-Transport-Security value 'max-age=31536000' - -set load-balancing haproxy service https rule 10 url-path exact '/.well-known/xxx' -set load-balancing haproxy service https rule 10 set redirect-location '/certs/' -set load-balancing haproxy service https rule 20 url-path end '/mail' -set load-balancing haproxy service https rule 20 url-path exact '/email/bar' -set load-balancing haproxy service https rule 20 set redirect-location '/postfix/' - -set load-balancing haproxy backend bk-default description 'Default backend' -set load-balancing haproxy backend bk-default mode 'http' -set load-balancing haproxy backend bk-default server sr01 address '192.0.2.23' -set load-balancing haproxy backend bk-default server sr01 port '80' - -set load-balancing haproxy global-parameters max-connections '4000' -set load-balancing haproxy global-parameters tls-version-min '1.3' -``` - -### SSL Bridging - -The following configuration terminates incoming HTTPS traffic on the router, -then re-encrypts the traffic and sends it to the backend server via HTTPS. -Use this when encryption is required for both paths but you do not want to -install publicly trusted certificates on each backend server. - -Backend service certificates are checked against the certificate authority -specified in the configuration, which could be an internal CA. - -The `https` service listens on port 443 with backend `bk-bridge-ssl` to -handle HTTPS traffic. It uses certificate named `cert` for SSL termination. - -The `bk-bridge-ssl` backend connects to `sr01` server on port 443 via HTTPS -and checks backend server has a valid certificate trusted by CA `cacert` - -```none -set load-balancing haproxy service https backend 'bk-bridge-ssl' -set load-balancing haproxy service https description 'listen on 443 port' -set load-balancing haproxy service https mode 'http' -set load-balancing haproxy service https port '443' -set load-balancing haproxy service https ssl certificate 'cert' - -set load-balancing haproxy backend bk-bridge-ssl description 'SSL backend' -set load-balancing haproxy backend bk-bridge-ssl mode 'http' -set load-balancing haproxy backend bk-bridge-ssl ssl ca-certificate 'cacert' -set load-balancing haproxy backend bk-bridge-ssl server sr01 address '192.0.2.23' -set load-balancing haproxy backend bk-bridge-ssl server sr01 port '443' -``` - -### Balancing with HTTP health checks - -This configuration enables HTTP health checks for backend servers. - -```none -set load-balancing haproxy service my-tcp-api backend 'bk-01' -set load-balancing haproxy service my-tcp-api mode 'tcp' -set load-balancing haproxy service my-tcp-api port '8888' - -set load-balancing haproxy backend bk-01 balance 'round-robin' -set load-balancing haproxy backend bk-01 mode 'tcp' - -set load-balancing haproxy backend bk-01 http-check method 'get' -set load-balancing haproxy backend bk-01 http-check uri '/health' -set load-balancing haproxy backend bk-01 http-check expect 'status 200' - -set load-balancing haproxy backend bk-01 server srv01 address '192.0.2.11' -set load-balancing haproxy backend bk-01 server srv01 port '8881' -set load-balancing haproxy backend bk-01 server srv01 check -set load-balancing haproxy backend bk-01 server srv02 address '192.0.2.12' -set load-balancing haproxy backend bk-01 server srv02 port '8882' -set load-balancing haproxy backend bk-01 server srv02 check port '8892' -``` diff --git a/docs/configuration/loadbalancing/md-index.md b/docs/configuration/loadbalancing/md-index.md deleted file mode 100644 index 3241edb7..00000000 --- a/docs/configuration/loadbalancing/md-index.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -lastproofread: '2026-04-06' ---- - -(load-balancing)= - -# Load-balancing - -```{toctree} -:includehidden: true -:maxdepth: 1 - -wan -haproxy -``` diff --git a/docs/configuration/loadbalancing/md-wan.md b/docs/configuration/loadbalancing/md-wan.md deleted file mode 100644 index a19bbfae..00000000 --- a/docs/configuration/loadbalancing/md-wan.md +++ /dev/null @@ -1,306 +0,0 @@ ---- -lastproofread: '2026-04-06' ---- - -# WAN load balancing - -```{todo} -Convert raw command blocks in this file to cfgcmd/opcmd -directives for command coverage tracking. -``` - -The load balancer distributes outbound traffic across two or more -interfaces. If a path fails, the load balancer balances traffic across the -remaining healthy paths. When a path recovers, it is automatically added back -to the routing table. The load balancer adds routes for each path and -distributes traffic based on interface health and weight. - -In a minimal configuration, the following must be provided: -> - An interface with a `nexthop`. -> - One rule with a LAN (inbound-interface) and the WAN (interface). - -The following examples uses two DHCP WAN interfaces and one LAN (`eth2`): - -```none -set load-balancing wan interface-health eth0 nexthop 'dhcp' -set load-balancing wan interface-health eth1 nexthop 'dhcp' -set load-balancing wan rule 1 inbound-interface 'eth2' -set load-balancing wan rule 1 interface eth0 -set load-balancing wan rule 1 interface eth1 -``` - -:::{note} -Do not use WAN load balancing with dynamic routing protocols. This -feature creates customized routing tables and firewall rules that are -incompatible with routing protocols. -::: - -## Load balancing rules - -You define interfaces, their weight, and the traffic type to balance in -numbered rule sets. The load balancer executes rules in numerical order -against outgoing packets. When a packet matches a rule, it is sent through the -specified interface. Packets that do not match any rule use the system routing -table. You cannot change rule numbers. - -Create a load balancing rule, it can be a number between 1 and 9999: - -```none -vyos@vyos# set load-balancing wan rule 1 -Possible completions: -description Description for this rule -> destination Destination -exclude Exclude packets matching this rule from wan load balance -failover Enable failover for packets matching this rule from wan load balance -inbound-interface Inbound interface name (e.g., "eth0") [REQUIRED] -+> interface Interface name [REQUIRED] -> limit Enable packet limit for this rule -per-packet-balancing Option to match traffic per-packet instead of the default, per-flow -protocol Protocol to match -> source Source information -``` - - -### Interface weight - -By default, the load balancer distributes outbound -traffic randomly across available interfaces. You can assign weights to -interfaces to influence the distribution. If `eth0` has more bandwidth -than `eth1`, you can assign a higher weight to `eth0` to send more -traffic through it: - -```none -set load-balancing wan rule 1 interface eth0 weight 2 -set load-balancing wan rule 1 interface eth1 weight 1 -``` - -In this example,\`\`eth0\`\` receives 66% of traffic, and `eth1` receives -33% of traffic. - -### Rate limit - -Set a packet rate limit for a rule to apply it to traffic above or below a -specified threshold. To configure rate limiting, use: - -```none -set load-balancing wan rule limit -``` - -- `burst`: Number of packets allowed to overshoot the limit within `period`. - Default 5. -- `period`: Time window for rate calculation. Possible values: - `second` (one second), `minute` (one minute), `hour` (one hour). - Default is `second`. -- `rate`: Number of packets. Default: `5`. -- `threshold`: `below` or `above` the specified rate limit. - -### Flow and packet-based balancing - -The load balancer balances outgoing traffic by flow. A connection tracking -table tracks flows by source address, destination address, and port. Each -flow is assigned to an interface based on the balancing rules, and subsequent -packets use the same interface. This ensures packets arrive in order when links -have different speeds. - -Packet-based balancing can improve balance across interfaces when packet -order is not critical. Enable per-packet balancing for a rule with: - -```none -set load-balancing wan rule per-packet-balancing -``` - - -### Exclude traffic - -To exclude traffic from load balancing, traffic matching an exclude rule -bypasses load balancing and uses the system routing table instead: - -```none -set load-balancing wan rule exclude -``` - - -## Health checks - -The load balancer periodically checks the health of interfaces and paths by -sending ICMP packets (ping) to remote destinations, performing TTL tests, or -executing a user-defined script. If an interface fails the health check, the -load balancer removes it from its interface pool. -To enable health checking for an interface: - -```none -vyos@vyos# set load-balancing wan interface-health -Possible completions: -failure-count Failure count -nexthop Outbound interface nexthop address. Can be 'dhcp or ip address' [REQUIRED] -success-count Success count -+> test Rule number -``` - -Specify the nexthop on the path to the destination. You can set -`ipv4-address` to `dhcp`. - -```none -set load-balancing wan interface-health nexthop -``` - -Set the number of health check failures before the load balancer marks an -interface as unavailable (range 1-10, default 1). Or set the number of -successful health checks before adding an interface back to the pool -(range 1-10, default 1). - -```none -set load-balancing wan interface-health failure-count -set load-balancing wan interface-health success-count -``` - -Configure each health check in its own test. Tests are numbered and processed -in numeric order. You can define multiple tests for multi-target health -checking: - -```none -vyos@vyos# set load-balancing wan interface-health eth1 test 0 -Possible completions: -resp-time Ping response time (seconds) -target Health target address -test-script Path to user defined script -ttl-limit Ttl limit (hop count) -type WLB test type -``` - -- `resp-time`: The maximum response time for ping in seconds. Range - 1-30, default `5`. -- `target`: The target to receive ICMP packets. The address can be an IPv4 - address or hostname. -- `test-script`: A user-defined script must return 0 to succeed and - non-zero to fail. Scripts reside in `/config/scripts`. For other locations, - provide the full path. -- `ttl-limit`: For the UDP TTL limit test, specify the hop count limit. - The limit must be shorter than the path length. The test succeeds when an - ICMP time-expired message is returned. Default `1`. -- `type`: Specify the test type: `ping`, `ttl`, or a user-defined - script. - -## Source NAT rules - -By default, interfaces in a load balancing pool replace the source IP of -each outgoing packet with their own address to ensure replies arrive on the -same interface. The load balancer handles this through automatically generated -Source NAT (SNAT) rules applied only to balanced traffic. To disable the -automatic generation of SNAT rules when this behavior is not desired, use: - -```none -set load-balancing wan disable-source-nat -``` - - -## Sticky connections - -Inbound connections to a WAN interface can be improperly handled when -replies are sent back to the client. - -```{image} /_static/images/sticky-connections.webp -:align: center -:width: 80% -``` - -When responding to an incoming packet, you may want to ensure the response -leaves from the same interface as the incoming packet. Enable sticky -connections in the load balancer to do this: - -```none -set load-balancing wan sticky-connections inbound -``` - - -## Failover - -In failover mode, one interface is primary and other interfaces are -secondary or spare. The load balancer uses only the primary interface. If it -fails, a secondary interface from the available pool takes over. The load -balancer selects the primary interface based on its weight and health. Other -interfaces become secondary. Secondary interfaces are chosen based on their -weight and health. You can also select interface roles based on rule order by -including interfaces in balancing rules and ordering those rules accordingly. -To enable failover mode, create a failover rule: - -```none -set load-balancing wan rule failover -``` - -Existing sessions do not automatically fail over to a new path. Flush the -session table on each connection state change to enable failover: - -```none -set load-balancing wan flush-connections -``` - -:::{warning} -Flushing the session table causes other connections to revert from -flow-based to packet-based balancing until each flow is reestablished. -::: - -## Script execution - -Run a script when an interface state changes. Scripts run from the -`/config/scripts` directory. To use a script in another location, -specify the full path: - -```none -set load-balancing wan hook script-name -``` - -Two environment variables are available: -- `WLB_INTERFACE_NAME=[interfacename]`: Interface to be monitored -- `WLB_INTERFACE_STATE=[ACTIVE|FAILED]`: Interface state - -:::{warning} -Blocking call with no timeout: VyOS becomes unresponsive if the -script does not return. -::: - -## Handling and monitoring - -The following command shows WAN load balancer information including test -types and targets. The character at the start of each line indicates the test -state: -- `+` successful. -- `-` failed. -- A blank indicates that no test has been carried out. - -```none -vyos@vyos:~$ show wan-load-balance -Interface: eth0 -Status: failed -Last Status Change: Tue Jun 11 20:12:19 2019 --Test: ping Target: - Last Interface Success: 55s - Last Interface Failure: 0s - # Interface Failure(s): 5 - -Interface: eth1 -Status: active -Last Status Change: Tue Jun 11 20:06:42 2019 -+Test: ping Target: - Last Interface Success: 0s - Last Interface Failure: 6m26s - # Interface Failure(s): 0 -``` - -Show connection data of load balanced traffic: - -```none -vyos@vyos:~$ show wan-load-balance connection -conntrack v1.4.2 (conntrack-tools): 3 flow entries have been shown. -Type State Src Dst Packets Bytes -tcp TIME_WAIT 10.1.1.13:38040 203.0.113.2:80 203.0.113.2 192.168.188.71 -udp 10.1.1.13:41891 198.51.100.3:53 198.51.100.3 192.168.188.71 -udp 10.1.1.13:55437 198.51.100.3:53 198.51.100.3 192.168.188.71 -``` - - -### Restart - -```none -restart wan-load-balance -``` diff --git a/docs/configuration/md-index.md b/docs/configuration/md-index.md deleted file mode 100644 index 3e215502..00000000 --- a/docs/configuration/md-index.md +++ /dev/null @@ -1,23 +0,0 @@ -# Configuration Guide - -The following structure represents the CLI structure. - -```{toctree} -:includehidden: true -:maxdepth: 1 - -container/index -firewall/index -highavailability/index -interfaces/index -loadbalancing/index -nat/index -policy/index -pki/index -protocols/index -service/index -system/index -trafficpolicy/index -vpn/index -vrf/index -``` diff --git a/docs/configuration/nat/md-cgnat.md b/docs/configuration/nat/md-cgnat.md deleted file mode 100644 index 914a466b..00000000 --- a/docs/configuration/nat/md-cgnat.md +++ /dev/null @@ -1,200 +0,0 @@ -(cgnat)= - -# CGNAT - -{abbr}`CGNAT (Carrier-Grade Network Address Translation)` , also known as -Large-Scale NAT (LSN), is a type of network address translation used by -Internet Service Providers (ISPs) to enable multiple private IP addresses to -share a single public IP address. This technique helps to conserve the limited -IPv4 address space. -The 100.64.0.0/10 address block is reserved for use in carrier-grade NAT - -## Overview - -CGNAT works by placing a NAT device within the ISP's network. This device -translates private IP addresses from customer networks to a limited pool of -public IP addresses assigned to the ISP. This allows many customers to share a -smaller number of public IP addresses. - -Not all {rfc}`6888` requirements are implemented in CGNAT. - -Implemented the following {rfc}`6888` requirements: - -- REQ 2: A CGN must have a default "IP address pooling" behavior of "Paired". - CGN must use the same external IP address mapping for all sessions associated - with the same internal IP address, be they TCP, UDP, ICMP, something else, - or a mix of different protocols. -- REQ 3: The CGN function should not have any limitations on the size or the - contiguity of the external address pool. -- REQ 4: A CGN must support limiting the number of external ports (or, - equivalently, "identifiers" for ICMP) that are assigned per subscriber - -### Advantages of CGNAT - -- **IPv4 Address Conservation**: CGNAT helps mitigate the exhaustion of IPv4 addresses by allowing multiple customers to share a single public IP address. -- **Scalability**: ISPs can support more customers without needing a proportional increase in public IP addresses. -- **Cost-Effective**: Reduces the cost associated with acquiring additional public IPv4 addresses. - -### Considerations - -- **Traceability Issues**: Since multiple users share the same public IP address, tracking individual users for security and legal purposes can be challenging. -- **Performance Overheads**: The translation process can introduce latency and potential performance bottlenecks, especially under high load. -- **Application Compatibility**: Some applications and protocols may not work well with CGNAT due to their reliance on unique public IP addresses. -- **Port Allocation Limits**: Each public IP address has a limited number of ports, which can be exhausted, affecting the ability to establish new connections. -- **Port Control Protocol**: PCP is not implemented. - -## Port calculation - -When implementing CGNAT, ensuring that there are enough ports allocated per subscriber is critical. Below is a summary based on RFC 6888. - -1. **Total Ports Available**: - - - Total Ports: 65536 (0 to 65535) - - Reserved Ports: Assume 1024 ports are reserved for well-known services and administrative purposes. - - Usable Ports: 65536 - 1024 = 64512 - -2. **Estimate Ports Needed per Subscriber**: - - - Example: A household might need 1000 ports to ensure smooth operation for multiple devices and applications. - -3. **Calculate the Number of Subscribers per Public IP**: - - - Usable Ports / Ports per Subscriber - - 64512 / 1000 ≈ 64 subscribers per public IP - -## Configuration - -```{cfgcmd} set nat cgnat pool external \ external-port-range \ - -Set an external port-range for the external pool, the default range is -1024-65535. Multiple entries can be added to the same pool. -``` - - -```{cfgcmd} set nat cgnat pool external \ per-user-limit port \ - -Set external source port limits that will be allocated to each subscriber -individually. The default value is 2000. -``` - - -```{cfgcmd} set nat cgnat pool external \ range [address | address range | network] [seq] - -Set the range of external IP addresses for the CGNAT pool. -The sequence is optional; if set, a lower value means higher priority. -``` - - -```{cfgcmd} set nat cgnat pool internal \ range [address range | network] - -Set the range of internal IP addresses for the CGNAT pool. -``` - - -```{cfgcmd} set nat cgnat rule \ source pool \ - -Set the rule for the source pool. -``` - - -```{cfgcmd} set nat cgnat rule \ translation pool \ - -Set the rule for the translation pool. -``` - - -```{cfgcmd} set nat cgnat log-allocation - -Enable logging of IP address and ports allocations. -``` - - -## Configuration Examples - -### Single external address - -Example of setting up a basic CGNAT configuration: -In the following example, we define an external pool named `ext-1` with one -external IP address. - -Each subscriber will be allocated a maximum of 2000 ports from the external pool. - -```none -set nat cgnat pool external ext1 external-port-range '1024-65535' -set nat cgnat pool external ext1 per-user-limit port '2000' -set nat cgnat pool external ext1 range '192.0.2.222/32' -set nat cgnat pool internal int1 range '100.64.0.0/28' -set nat cgnat rule 10 source pool 'int1' -set nat cgnat rule 10 translation pool 'ext1' -``` - - -### Multiple external addresses - -```none -set nat cgnat pool external ext1 external-port-range '1024-65535' -set nat cgnat pool external ext1 per-user-limit port '8000' -set nat cgnat pool external ext1 range '192.0.2.1-192.0.2.2' -set nat cgnat pool external ext1 range '203.0.113.253-203.0.113.254' -set nat cgnat pool internal int1 range '100.64.0.1-100.64.0.32' -set nat cgnat rule 10 source pool 'int1' -set nat cgnat rule 10 translation pool 'ext1' -``` - - -### External address sequences - -```none -set nat cgnat pool external ext-01 per-user-limit port '16000' -set nat cgnat pool external ext-01 range 203.0.113.1/32 seq '10' -set nat cgnat pool external ext-01 range 192.0.2.1/32 seq '20' -set nat cgnat pool internal int-01 range '100.64.0.0/29' -set nat cgnat rule 10 source pool 'int-01' -set nat cgnat rule 10 translation pool 'ext-01' -``` - - -## Operation commands - -```{opcmd} show nat cgnat allocation - -Show address and port allocations -``` - -```{opcmd} show nat cgnat allocation external-address \ - -Show all allocations for an external IP address -``` - -```{opcmd} show nat cgnat allocation internal-address \ - -Show all allocations for an internal IP address -``` - - -### Show CGNAT allocations - -```none -vyos@vyos:~$ show nat cgnat allocation -Internal IP External IP Port range -------------- ------------- ------------ -100.64.0.0 203.0.113.1 1024-17023 -100.64.0.1 203.0.113.1 17024-33023 -100.64.0.2 203.0.113.1 33024-49023 -100.64.0.3 203.0.113.1 49024-65023 -100.64.0.4 192.0.2.1 1024-17023 -100.64.0.5 192.0.2.1 17024-33023 -100.64.0.6 192.0.2.1 33024-49023 -100.64.0.7 192.0.2.1 49024-65023 - -vyos@vyos:~$ show nat cgnat allocation internal-address 100.64.0.4 -Internal IP External IP Port range -------------- ------------- ------------ -100.64.0.4 192.0.2.1 1024-17023 -``` - - -## Further Reading - -- {rfc}`6598` - IANA-Reserved IPv4 Prefix for Shared Address Space -- {rfc}`6888` - Requirements for CGNAT diff --git a/docs/configuration/nat/md-index.md b/docs/configuration/nat/md-index.md deleted file mode 100644 index 35e5d32b..00000000 --- a/docs/configuration/nat/md-index.md +++ /dev/null @@ -1,13 +0,0 @@ -(nat)= - -# NAT - -```{toctree} -:includehidden: true -:maxdepth: 1 - -nat44 -nat64 -nat66 -cgnat -``` diff --git a/docs/configuration/nat/md-nat44.md b/docs/configuration/nat/md-nat44.md deleted file mode 100644 index 4f5bd580..00000000 --- a/docs/configuration/nat/md-nat44.md +++ /dev/null @@ -1,788 +0,0 @@ -(nat44)= - -# NAT44 - -{abbr}`NAT (Network Address Translation)` is a common method of -remapping one IP address space into another by modifying network address -information in the IP header of packets while they are in transit across -a traffic routing device. The technique was originally used as a -shortcut to avoid the need to readdress every host when a network was -moved. It has become a popular and essential tool in conserving global -address space in the face of IPv4 address exhaustion. One -Internet-routable IP address of a NAT gateway can be used for an entire -private network. - -IP masquerading is a technique that hides an entire IP address space, -usually consisting of private IP addresses, behind a single IP address -in another, usually public address space. The hidden addresses are -changed into a single (public) IP address as the source address of the -outgoing IP packets so they appear as originating not from the hidden -host but from the routing device itself. Because of the popularity of -this technique to conserve IPv4 address space, the term NAT has become -virtually synonymous with IP masquerading. - -As network address translation modifies the IP address information in -packets, NAT implementations may vary in their specific behavior in -various addressing cases and their effect on network traffic. The -specifics of NAT behavior are not commonly documented by vendors of -equipment containing NAT implementations. - -The computers on an internal network can use any of the addresses set -aside by the {abbr}`IANA (Internet Assigned Numbers Authority)` for -private addressing (see {rfc}`1918`). These reserved IP addresses are -not in use on the Internet, so an external machine will not directly -route to them. The following addresses are reserved for private use: - -- 10.0.0.0 to 10.255.255.255 (CIDR: 10.0.0.0/8) -- 172.16.0.0 to 172.31.255.255 (CIDR: 172.16.0.0/12) -- 192.168.0.0 to 192.168.255.255 (CIDR: 192.168.0.0/16) - -If an ISP deploys a {abbr}`CGN (Carrier-grade NAT)`, and uses -{rfc}`1918` address space to number customer gateways, the risk of -address collision, and therefore routing failures, arises when the -customer network already uses an {rfc}`1918` address space. - -This prompted some ISPs to develop a policy within the {abbr}`ARIN -(American Registry for Internet Numbers)` to allocate new private -address space for CGNs, but ARIN deferred to the IETF before -implementing the policy indicating that the matter was not a typical -allocation issue but a reservation of addresses for technical purposes -(per {rfc}`2860`). - -IETF published {rfc}`6598`, detailing a shared address space for use in -ISP CGN deployments that can handle the same network prefixes occurring -both on inbound and outbound interfaces. ARIN returned address space to -the {abbr}`IANA (Internet Assigned Numbers Authority)` for this -allocation. - -The allocated address block is 100.64.0.0/10. - -Devices evaluating whether an IPv4 address is public must be updated to -recognize the new address space. Allocating more private IPv4 address -space for NAT devices might prolong the transition to IPv6. - -## Overview - -### Different NAT Types - -(source-nat)= - -#### SNAT - -{abbr}`SNAT (Source Network Address Translation)` is the most common -form of {abbr}`NAT (Network Address Translation)` and is typically -referred to simply as NAT. To be more correct, what most people refer -to as {abbr}`NAT (Network Address Translation)` is actually the process -of {abbr}`PAT (Port Address Translation)`, or NAT overload. SNAT is -typically used by internal users/private hosts to access the Internet -\- the source address is translated and thus kept private. - -(destination-nat)= - -#### DNAT - -{abbr}`DNAT (Destination Network Address Translation)` changes the -destination address of packets passing through the router, while -{ref}`source-nat` changes the source address of packets. DNAT is -typically used when an external (public) host needs to initiate a -session with an internal (private) host. A customer needs to access a -private service behind the routers public IP. A connection is -established with the routers public IP address on a well known port and -thus all traffic for this port is rewritten to address the internal -(private) host. - -(bidirectional-nat)= - -#### Bidirectional NAT - -This is a common scenario where both {ref}`source-nat` and -{ref}`destination-nat` are configured at the same time. It's commonly -used when internal (private) hosts need to establish a connection with -external resources and external systems need to access internal -(private) resources. - -### NAT, Routing, Firewall Interaction - -There is a very nice picture/explanation in the Vyatta documentation -which should be rewritten here. - -### NAT Ruleset - -{abbr}`NAT (Network Address Translation)` is configured entirely on a -series of so called *rules*. Rules are numbered and evaluated by the -underlying OS in numerical order! The rule numbers can be changes by -utilizing the {cfgcmd}`rename` and {cfgcmd}`copy` commands. - -:::{note} -Changes to the NAT system only affect newly established -connections. Already established connections are not affected. -::: - -:::{hint} -When designing your NAT ruleset leave some space between -consecutive rules for later extension. Your ruleset could start with -numbers 10, 20, 30. You thus can later extend the ruleset and place -new rules between existing ones. -::: - -Rules will be created for both {ref}`source-nat` and -{ref}`destination-nat`. - -For {ref}`bidirectional-nat` a rule for both {ref}`source-nat` and -{ref}`destination-nat` needs to be created. - -(traffic-filters)= - -### Traffic Filters - -Traffic Filters are used to control which packets will have the defined -NAT rules applied. Five different filters can be applied within a NAT -rule. - -- **outbound-interface** - applicable only to {ref}`source-nat`. It - configures the interface which is used for the outside traffic that - this translation rule applies to. Interface groups, inverted - selection and wildcard, are also supported. - - Examples: - - ```none - set nat source rule 20 outbound-interface name eth0 - set nat source rule 30 outbound-interface name bond1* - set nat source rule 20 outbound-interface name !vtun2 - set nat source rule 20 outbound-interface group GROUP1 - set nat source rule 20 outbound-interface group !GROUP2 - ``` - -- **inbound-interface** - applicable only to {ref}`destination-nat`. It - configures the interface which is used for the inside traffic the - translation rule applies to. Interface groups, inverted - selection and wildcard, are also supported. - - Example: - - ```none - set nat destination rule 20 inbound-interface name eth0 - set nat destination rule 30 inbound-interface name bond1* - set nat destination rule 20 inbound-interface name !vtun2 - set nat destination rule 20 inbound-interface group GROUP1 - set nat destination rule 20 inbound-interface group !GROUP2 - ``` - -- **protocol** - specify which types of protocols this translation rule - applies to. Only packets matching the specified protocol are NATed. - By default this applies to *all* protocols. - - Example: - - - Set SNAT rule 20 to only NAT TCP and UDP packets - - Set DNAT rule 20 to only NAT UDP packets - - ```none - set nat source rule 20 protocol tcp_udp - set nat destination rule 20 protocol udp - ``` - -- **source** - specifies which packets the NAT translation rule applies - to based on the packets source IP address and/or source port. Only - matching packets are considered for NAT. - - Example: - - - Set SNAT rule 20 to only NAT packets arriving from the 192.0.2.0/24 - network - - Set SNAT rule 30 to only NAT packets arriving from the 203.0.113.0/24 - network with a source port of 80 and 443 - - ```none - set nat source rule 20 source address 192.0.2.0/24 - set nat source rule 30 source address 203.0.113.0/24 - set nat source rule 30 source port 80,443 - ``` - -- **destination** - specify which packets the translation will be - applied to, only based on the destination address and/or port number - configured. - - :::{note} - If no destination is specified the rule will match on any - destination address and port. - ::: - - Example: - - - Configure SNAT rule (40) to only NAT packets with a destination - address of 192.0.2.1. - - ```none - set nat source rule 40 destination address 192.0.2.1 - ``` - -### Address Conversion - -Every NAT rule has a translation command defined. The address defined -for the translation is the address used when the address information in -a packet is replaced. - -#### Source Address - -For {ref}`source-nat` rules the packets source address will be replaced -with the address specified in the translation command. A port -translation can also be specified and is part of the translation -address. - -:::{note} -The translation address must be set to one of the available -addresses on the configured *outbound-interface* or it must be set to -*masquerade* which will use the primary IP address of the -*outbound-interface* as its translation address. -::: - -:::{note} -When using NAT for a large number of host systems it -recommended that a minimum of 1 IP address is used to NAT every 256 -private host systems. This is due to the limit of 65,000 port numbers -available for unique translations and a reserving an average of -200-300 sessions per host system. -::: - -Example: - -- Define a discrete source IP address of 100.64.0.1 for SNAT rule 20 -- Use address *masquerade* (the interfaces primary address) on rule 30 -- For a large amount of private machines behind the NAT your address - pool might to be bigger. Use any address in the range 100.64.0.10 - - 100.64.0.20 on SNAT rule 40 when doing the translation - -```none -set nat source rule 20 translation address 100.64.0.1 -set nat source rule 30 translation address 'masquerade' -set nat source rule 40 translation address 100.64.0.10-100.64.0.20 -``` - -#### Destination Address - -For {ref}`destination-nat` rules the packets destination address will be -replaced by the specified address in the *translation address* command. - -Example: - -- DNAT rule 10 replaces the destination address of an inbound packet - with 192.0.2.10 - -```none -set nat destination rule 10 translation address 192.0.2.10 -``` - -Also, in {ref}`destination-nat`, redirection to localhost is supported. -The redirect statement is a special form of dnat which always translates -the destination address to the local host’s one. - -Example of redirection: - -```none -set nat destination rule 10 translation redirect port 22 -``` - -### NAT Load Balance - -Advanced configuration can be used in order to apply source or destination NAT, -and within a single rule, be able to define multiple translated addresses, -so NAT balances the translations among them. - -NAT Load Balance uses an algorithm that generates a hash and based on it, then -it applies corresponding translation. This hash can be generated randomly, or -can use data from the ip header: source-address, destination-address, -source-port and/or destination-port. By default, it will generate the hash -randomly. - -When defining the translated address, called `backends`, a `weight` must -be configured. This lets the user define load balance distribution according -to their needs. Them sum of all the weights defined for the backends should -be equal to 100. In oder words, the weight defined for the backend is the -percentage of the connections that will receive such backend. - -```{cfgcmd} set nat [source | destination] rule \ load-balance hash [source-address | destination-address | source-port | destination-port | random] -``` - -```{cfgcmd} set nat [source | destination] rule \ load-balance backend \ weight \<1-100\> -``` - -## Configuration Examples - -To setup SNAT, we need to know: -- The internal IP addresses we want to translate -- The outgoing interface to perform the translation on -- The external IP address to translate to - -In the example used for the Quick Start configuration above, we -demonstrate the following configuration: - -```none -set nat source rule 100 outbound-interface name 'eth0' -set nat source rule 100 source address '192.168.0.0/24' -set nat source rule 100 translation address 'masquerade' -``` - -Which generates the following configuration: - -```none -rule 100 { - outbound-interface { - name eth0 - } - source { - address 192.168.0.0/24 - } - translation { - address masquerade - } -} -``` - -In this example, we use **masquerade** as the translation address -instead of an IP address. The **masquerade** target is effectively an -alias to say "use whatever IP address is on the outgoing interface", -rather than a statically configured IP address. This is useful if you -use DHCP for your outgoing interface and do not know what the external -address will be. - -When using NAT for a large number of host systems it recommended that a -minimum of 1 IP address is used to NAT every 256 host systems. This is -due to the limit of 65,000 port numbers available for unique -translations and a reserving an average of 200-300 sessions per host -system. - -Example: For an ~8,000 host network a source NAT pool of 32 IP addresses -is recommended. - -A pool of addresses can be defined by using a hyphen between two IP -addresses: - -```none -set nat source rule 100 translation address '203.0.113.32-203.0.113.63' -``` - -(avoidng-leaky-nat)= - -### Avoiding "leaky" NAT - -Linux netfilter will not NAT traffic marked as INVALID. This often -confuses people into thinking that Linux (or specifically VyOS) has a -broken NAT implementation because non-NATed traffic is seen leaving an -external interface. This is actually working as intended, and a packet -capture of the "leaky" traffic should reveal that the traffic is either -an additional TCP "RST", "FIN,ACK", or "RST,ACK" sent by client systems -after Linux netfilter considers the connection closed. The most common -is the additional TCP RST some host implementations send after -terminating a connection (which is implementation-specific). - -In other words, connection tracking has already observed the connection -be closed and has transition the flow to INVALID to prevent attacks from -attempting to reuse the connection. - -You can avoid the "leaky" behavior by using a firewall policy that drops -"invalid" state packets. - -Having control over the matching of INVALID state traffic, e.g. the -ability to selectively log, is an important troubleshooting tool for -observing broken protocol behavior. For this reason, VyOS does not -globally drop invalid state traffic, instead allowing the operator to -make the determination on how the traffic is handled. - -(hairpin-nat-reflection)= - -### Hairpin NAT/NAT Reflection - -A typical problem with using NAT and hosting public servers is the -ability for internal systems to reach an internal server using it's -external IP address. The solution to this is usually the use of -split-DNS to correctly point host systems to the internal address when -requests are made internally. Because many smaller networks lack DNS -infrastructure, a work-around is commonly deployed to facilitate the -traffic by NATing the request from internal hosts to the source address -of the internal interface on the firewall. - -This technique is commonly referred to as NAT Reflection or Hairpin NAT. - -Example: - -- Redirect Microsoft RDP traffic from the outside (WAN, external) world - via {ref}`destination-nat` in rule 100 to the internal, private host - 192.0.2.40. -- Redirect Microsoft RDP traffic from the internal (LAN, private) - network via {ref}`destination-nat` in rule 110 to the internal, - private host 192.0.2.40. We also need a {ref}`source-nat` rule 110 for - the reverse path of the traffic. The internal network 192.0.2.0/24 is - reachable via interface *eth0.10*. - -```none -set nat destination rule 100 description 'Regular destination NAT from external' -set nat destination rule 100 destination port '3389' -set nat destination rule 100 inbound-interface name 'pppoe0' -set nat destination rule 100 protocol 'tcp' -set nat destination rule 100 translation address '192.0.2.40' - -set nat destination rule 110 description 'NAT Reflection: INSIDE' -set nat destination rule 110 destination port '3389' -set nat destination rule 110 inbound-interface name 'eth0.10' -set nat destination rule 110 protocol 'tcp' -set nat destination rule 110 translation address '192.0.2.40' - -set nat source rule 110 description 'NAT Reflection: INSIDE' -set nat source rule 110 destination address '192.0.2.0/24' -set nat source rule 110 outbound-interface name 'eth0.10' -set nat source rule 110 protocol 'tcp' -set nat source rule 110 source address '192.0.2.0/24' -set nat source rule 110 translation address 'masquerade' -``` - -Which results in a configuration of: - -```none -vyos@vyos# show nat - destination { - rule 100 { - description "Regular destination NAT from external" - destination { - port 3389 - } - inbound-interface { - name pppoe0 - } - protocol tcp - translation { - address 192.0.2.40 - } - } - rule 110 { - description "NAT Reflection: INSIDE" - destination { - port 3389 - } - inbound-interface { - name eth0.10 - } - protocol tcp - translation { - address 192.0.2.40 - } - } - } - source { - rule 110 { - description "NAT Reflection: INSIDE" - destination { - address 192.0.2.0/24 - } - outbound-interface { - name eth0.10 - } - protocol tcp - source { - address 192.0.2.0/24 - } - translation { - address masquerade - } - } - } -``` - -### Destination NAT - -DNAT is typically referred to as a **Port Forward**. When using VyOS as -a NAT router and firewall, a common configuration task is to redirect -incoming traffic to a system behind the firewall. - -In this example, we will be using the example Quick Start configuration -above as a starting point. - -To setup a destination NAT rule we need to gather: -- The interface traffic will be coming in on; -- The protocol and port we wish to forward; -- The IP address of the internal system we wish to forward traffic to. - -In our example, we will be forwarding web server traffic to an internal -web server on 192.168.0.100. HTTP traffic makes use of the TCP protocol -on port 80. For other common port numbers, see: - - -Our configuration commands would be: - -```none -set nat destination rule 10 description 'Port Forward: HTTP to 192.168.0.100' -set nat destination rule 10 destination port '80' -set nat destination rule 10 inbound-interface name 'eth0' -set nat destination rule 10 protocol 'tcp' -set nat destination rule 10 translation address '192.168.0.100' -``` - -Which would generate the following NAT destination configuration: - -```none -nat { - destination { - rule 10 { - description "Port Forward: HTTP to 192.168.0.100" - destination { - port 80 - } - inbound-interface { - name eth0 - } - protocol tcp - translation { - address 192.168.0.100 - } - } - } -} -``` -:::{note} -If forwarding traffic to a different port than it is arriving -on, you may also configure the translation port using -*set nat destination rule [n] translation port*. -::: - -This establishes our Port Forward rule, but if we created a firewall -policy it will likely block the traffic. - -#### Firewall rules for Destination NAT - -It is important to note that when creating firewall rules, the DNAT -translation occurs **before** traffic traverses the firewall. In other -words, the destination address has already been translated to -192.168.0.100. - -So in our firewall ruleset, we want to allow traffic which previously matched -a destination nat rule. In order to avoid creating many rules, one for each -destination nat rule, we can accept all **'dnat'** connections with one simple -rule, using `connection-status` matcher: - -```none -set firewall ipv4 forward filter rule 10 action accept -set firewall ipv4 forward filter rule 10 connection-status nat destination -set firewall ipv4 forward filter rule 10 state new -``` - -This would generate the following configuration: - -```none -ipv4 { - forward { - filter { - rule 10 { - action accept - connection-status { - nat destination - } - state new - } - } - } -} -``` - -### 1-to-1 NAT - -Another term often used for DNAT is **1-to-1 NAT**. For a 1-to-1 NAT -configuration, both DNAT and SNAT are used to NAT all traffic from an -external IP address to an internal IP address and vice-versa. - -Typically, a 1-to-1 NAT rule omits the destination port (all ports) and -replaces the protocol with either **all** or **ip**. - -Then a corresponding SNAT rule is created to NAT outgoing traffic for -the internal IP to a reserved external IP. This dedicates an external IP -address to an internal IP address and is useful for protocols which -don't have the notion of ports, such as GRE. - -Here's an extract of a simple 1-to-1 NAT configuration with one internal -and one external interface: - -```none -set interfaces ethernet eth0 address '192.168.1.1/24' -set interfaces ethernet eth0 description 'Inside interface' -set interfaces ethernet eth1 address '192.0.2.30/24' -set interfaces ethernet eth1 description 'Outside interface' -set nat destination rule 2000 description '1-to-1 NAT example' -set nat destination rule 2000 destination address '192.0.2.30' -set nat destination rule 2000 inbound-interface name 'eth1' -set nat destination rule 2000 translation address '192.168.1.10' -set nat source rule 2000 description '1-to-1 NAT example' -set nat source rule 2000 outbound-interface name 'eth1' -set nat source rule 2000 source address '192.168.1.10' -set nat source rule 2000 translation address '192.0.2.30' -``` - -Firewall rules are written as normal, using the internal IP address as -the source of outbound rules and the destination of inbound rules. - -### NAT before VPN - -Some application service providers (ASPs) operate a VPN gateway to -provide access to their internal resources, and require that a -connecting organisation translate all traffic to the service provider -network to a source address provided by the ASP. - -### Load Balance - -Here we provide two examples on how to apply NAT Load Balance. - -First scenario: apply destination NAT for all HTTP traffic comming through -interface eth0, and user 4 backends. First backend should received 30% of -the request, second backend should get 20%, third 15% and the fourth 35% -We will use source and destination address for hash generation. - -```none -set nat destination rule 10 inbound-interface name eth0 -set nat destination rule 10 protocol tcp -set nat destination rule 10 destination port 80 -set nat destination rule 10 load-balance hash source-address -set nat destination rule 10 load-balance hash destination-address -set nat destination rule 10 load-balance backend 198.51.100.101 weight 30 -set nat destination rule 10 load-balance backend 198.51.100.102 weight 20 -set nat destination rule 10 load-balance backend 198.51.100.103 weight 15 -set nat destination rule 10 load-balance backend 198.51.100.104 weight 35 -``` - -Second scenario: apply source NAT for all outgoing connections from -LAN 10.0.0.0/8, using 3 public addresses and equal distribution. -We will generate the hash randomly. - -```none -set nat source rule 10 outbound-interface name eth0 -set nat source rule 10 source address 10.0.0.0/8 -set nat source rule 10 load-balance hash random -set nat source rule 10 load-balance backend 192.0.2.251 weight 33 -set nat source rule 10 load-balance backend 192.0.2.252 weight 33 -set nat source rule 10 load-balance backend 192.0.2.253 weight 34 -``` - -#### Example Network - -Here's one example of a network environment for an ASP. -The ASP requests that all connections from this company should come from -172.29.41.89 - an address that is assigned by the ASP and not in use at -the customer site. - -```{eval-rst} -.. figure:: /_static/images/nat_before_vpn_topology.webp - :scale: 100 % - :alt: NAT before VPN Topology - - NAT before VPN Topology -``` -#### Configuration - -The required configuration can be broken down into 4 major pieces: -- A dummy interface for the provider-assigned IP; -- NAT (specifically, Source NAT); -- IPSec IKE and ESP Groups; -- IPSec VPN tunnels. - -##### Dummy interface - -The dummy interface allows us to have an equivalent of the Cisco IOS -Loopback interface - a router-internal interface we can use for IP -addresses the router must know about, but which are not actually -assigned to a real network. - -We only need a single step for this interface: - -```none -set interfaces dummy dum0 address '172.29.41.89/32' -``` - -##### NAT Configuration - -```none -set nat source rule 110 description 'Internal to ASP' -set nat source rule 110 destination address '172.27.1.0/24' -set nat source rule 110 source address '192.168.43.0/24' -set nat source rule 110 translation address '172.29.41.89' -set nat source rule 120 description 'Internal to ASP' -set nat source rule 120 destination address '10.125.0.0/16' -set nat source rule 120 source address '192.168.43.0/24' -set nat source rule 120 translation address '172.29.41.89' -``` - -##### IPSec IKE and ESP - -The ASP has documented their IPSec requirements: -- IKE Phase: - - aes256 Encryption - - sha256 Hashes -- ESP Phase: - - aes256 Encryption - - sha256 Hashes - - DH Group 14 - -Additionally, we want to use VPNs only on our eth1 interface (the -external interface in the image above) - -```none -set vpn ipsec ike-group my-ike key-exchange 'ikev1' -set vpn ipsec ike-group my-ike lifetime '7800' -set vpn ipsec ike-group my-ike proposal 1 dh-group '14' -set vpn ipsec ike-group my-ike proposal 1 encryption 'aes256' -set vpn ipsec ike-group my-ike proposal 1 hash 'sha256' - -set vpn ipsec esp-group my-esp lifetime '3600' -set vpn ipsec esp-group my-esp mode 'tunnel' -set vpn ipsec esp-group my-esp pfs 'disable' -set vpn ipsec esp-group my-esp proposal 1 encryption 'aes256' -set vpn ipsec esp-group my-esp proposal 1 hash 'sha256' - -set vpn ipsec interface 'eth1' -``` - -##### IPSec VPN Tunnels - -We'll use the IKE and ESP groups created above for this VPN. Because we -need access to 2 different subnets on the far side, we will need two -different tunnels. If you changed the names of the ESP group and IKE -group in the previous step, make sure you use the correct names here -too. - -```none -set vpn ipsec authentication psk vyos id '203.0.113.46' -set vpn ipsec authentication psk vyos id '198.51.100.243' -set vpn ipsec authentication psk vyos secret 'MYSECRETPASSWORD' -set vpn ipsec site-to-site peer branch authentication local-id '203.0.113.46' -set vpn ipsec site-to-site peer branch authentication mode 'pre-shared-secret' -set vpn ipsec site-to-site peer branch authentication remote-id '198.51.100.243' -set vpn ipsec site-to-site peer branch connection-type 'initiate' -set vpn ipsec site-to-site peer branch default-esp-group 'my-esp' -set vpn ipsec site-to-site peer branch ike-group 'my-ike' -set vpn ipsec site-to-site peer branch ikev2-reauth 'inherit' -set vpn ipsec site-to-site peer branch local-address '203.0.113.46' -set vpn ipsec site-to-site peer branch remote-address '198.51.100.243' -set vpn ipsec site-to-site peer branch tunnel 0 local prefix '172.29.41.89/32' -set vpn ipsec site-to-site peer branch tunnel 0 remote prefix '172.27.1.0/24' -set vpn ipsec site-to-site peer branch tunnel 1 local prefix '172.29.41.89/32' -set vpn ipsec site-to-site peer branch tunnel 1 remote prefix '10.125.0.0/16' -``` - -##### Testing and Validation - -If you've completed all the above steps you no doubt want to see if it's -all working. - -Start by checking for IPSec SAs (Security Associations) with: - -```none -$ show vpn ipsec sa - -Peer ID / IP Local ID / IP ------------- ------------- -198.51.100.243 203.0.113.46 - - Tunnel State Bytes Out/In Encrypt Hash NAT-T A-Time L-Time Proto - ------ ----- ------------- ------- ---- ----- ------ ------ ----- - 0 up 0.0/0.0 aes256 sha256 no 1647 3600 all - 1 up 0.0/0.0 aes256 sha256 no 865 3600 all -``` - -That looks good - we defined 2 tunnels and they're both up and running. diff --git a/docs/configuration/nat/md-nat64.md b/docs/configuration/nat/md-nat64.md deleted file mode 100644 index c1b1c994..00000000 --- a/docs/configuration/nat/md-nat64.md +++ /dev/null @@ -1,73 +0,0 @@ -(nat64)= - -# NAT64 - -{abbr}`NAT64 (IPv6-to-IPv4 Prefix Translation)` is a critical component in -modern networking, facilitating communication between IPv6 and IPv4 networks. -This documentation outlines the setup, configuration, and usage of the NAT64 -feature in your project. Whether you are transitioning to IPv6 or need to -seamlessly connect IPv4 and IPv6 devices. -NAT64 is a stateful translation mechanism that translates IPv6 addresses to -IPv4 addresses and IPv4 addresses to IPv6 addresses. NAT64 is used to enable -IPv6-only clients to contact IPv4 servers using unicast UDP, TCP, or ICMP. - -## Overview - -### Different NAT Types - -(source-nat64)= - -#### SNAT64 - -{abbr}`SNAT64 (IPv6-to-IPv4 Source Address Translation)` is a stateful -translation mechanism that translates IPv6 addresses to IPv4 addresses. - -`64:ff9b::/96` is the well-known prefix for IPv4-embedded IPv6 addresses. -The prefix is used to represent IPv4 addresses in an IPv6 address format. -The IPv4 address is encoded in the low-order 32 bits of the IPv6 address. -The high-order 32 bits are set to the well-known prefix 64:ff9b::/96. - -## Configuration Examples - -The following examples show how to configure NAT64 on a VyOS router. -The 192.0.2.10 address is used as the IPv4 address for the translation pool. - -NAT64 server configuration: - -```none -set interfaces ethernet eth0 address '192.0.2.1/24' -set interfaces ethernet eth0 address '192.0.2.10/24' -set interfaces ethernet eth0 description 'WAN' -set interfaces ethernet eth1 address '2001:db8::1/64' -set interfaces ethernet eth1 description 'LAN' - -set service dns forwarding allow-from '2001:db8::/64' -set service dns forwarding dns64-prefix '64:ff9b::/96' -set service dns forwarding listen-address '2001:db8::1' - -set nat64 source rule 100 source prefix '64:ff9b::/96' -set nat64 source rule 100 translation pool 10 address '192.0.2.10' -set nat64 source rule 100 translation pool 10 port '1-65535' -``` - -NAT64 client configuration: - -```none -set interfaces ethernet eth1 address '2001:db8::2/64' -set protocols static route6 64:ff9b::/96 next-hop 2001:db8::1 -set system name-server '2001:db8::1' -``` - -Test from the IPv6 only client: - -```none -vyos@r1:~$ ping 64:ff9b::192.0.2.1 count 2 -PING 64:ff9b::192.0.2.1(64:ff9b::c000:201) 56 data bytes -64 bytes from 64:ff9b::c000:201: icmp_seq=1 ttl=63 time=0.351 ms -64 bytes from 64:ff9b::c000:201: icmp_seq=2 ttl=63 time=0.373 ms - ---- 64:ff9b::192.0.2.1 ping statistics --- -2 packets transmitted, 2 received, 0% packet loss, time 1023ms -rtt min/avg/max/mdev = 0.351/0.362/0.373/0.011 ms -``` - diff --git a/docs/configuration/nat/md-nat66.md b/docs/configuration/nat/md-nat66.md deleted file mode 100644 index 1cbe3317..00000000 --- a/docs/configuration/nat/md-nat66.md +++ /dev/null @@ -1,243 +0,0 @@ -(nat66)= - -# NAT66(NPTv6) - -```{todo} -Convert raw command blocks in this file to cfgcmd/opcmd -directives for command coverage tracking. -``` - -{abbr}`NPTv6 (IPv6-to-IPv6 Network Prefix Translation)` is an address -translation technology based on IPv6 networks, used to convert an IPv6 -address prefix in an IPv6 message into another IPv6 address prefix. -We call this address translation method NAT66. Devices that support the NAT66 -function are called NAT66 devices, which can provide NAT66 source -and destination address translation functions. - -## Overview - -### Different NAT Types - -(source-nat66)= - -#### SNAT66 - -{abbr}`SNPTv6 (Source IPv6-to-IPv6 Network Prefix Translation)` The conversion -function is mainly used in the following scenarios: -- A single internal network and external network. Use the NAT66 device to - connect a single internal network and public network, and the hosts in - the internal network use IPv6 address prefixes that only support - routing within the local range. When a host in the internal network - accesses the external network, the source IPv6 address prefix in - the message will be converted into a global unicast IPv6 address - prefix by the NAT66 device. -- Redundancy and load sharing. There are multiple NAT66 devices at the edge - of an IPv6 network to another IPv6 network. The path through the NAT66 - device to another IPv6 network forms an equivalent route, and traffic - can be load-shared on these NAT66 devices. In this case, you - can configure the same source address translation rules on these - NAT66 devices, so that any NAT66 device can handle IPv6 traffic between - different sites. -- Multi-homed. In a multi-homed network environment, the NAT66 device - connects to an internal network and simultaneously connects to - different external networks. Address translation can be configured - on each external network side interface of the NAT66 device to - convert the same internal network address into different external - network addresses, and realize the mapping of the same internal - address to multiple external addresses. -(destination-nat66)= - -#### DNAT66 - -The {abbr}`DNPTv6 (Destination IPv6-to-IPv6 Network Prefix Translation)` -destination address translation function is used in scenarios where the -server in the internal network provides services to the external network, -such as providing Web services or FTP services to the external network. -By configuring the mapping relationship between the internal server -address and the external network address on the external network -side interface of the NAT66 device, external network users can -access the internal network server through the designated -external network address. - -### Prefix Conversion - -#### Source Prefix - -Every SNAT66 rule has a translation command defined. The prefix defined -for the translation is the prefix used when the address information in -a packet is replaced.、 - -The {ref}`source-nat66` rule replaces the source address of the packet -and calculates the converted address using the prefix specified in the rule. - -Example: -- Convert the address prefix of a single `fc01::/64` network to `fc00::/64` -- Output from `eth0` network interface - -```none -set nat66 source rule 1 outbound-interface name 'eth0' -set nat66 source rule 1 source prefix 'fc01::/64' -set nat66 source rule 1 translation address 'fc00::/64' -``` - - -#### Destination Prefix - -For the {ref}`destination-nat66` rule, the destination address of -the packet isreplaced by the address calculated from the specified -address or prefix in the `translation address` command - -Example: -- Convert the address prefix of a single `fc00::/64` network - to `fc01::/64` -- Input from `eth0` network interface - -```none -set nat66 destination rule 1 inbound-interface name 'eth0' -set nat66 destination rule 1 destination address 'fc00::/64' -set nat66 destination rule 1 translation address 'fc01::/64' -``` - -For the destination, groups can also be used instead of an address. - -Example: - -```none -set firewall group ipv6-address-group ADR-INSIDE-v6 address fc00::1 - -set nat66 destination rule 1 inbound-interface name 'eth0' -set nat66 destination rule 1 destination group address-group ADR-INSIDE-v6 -set nat66 destination rule 1 translation address 'fc01::/64' -``` - - -## Configuration Examples - -Use the following topology to build a nat66 based isolated -network between internal and external networks (dynamic prefix is -not supported): - -:::{figure} /_static/images/vyos_1_4_nat66_simple.webp -:alt: VyOS NAT66 Simple Configure -::: - -R1: - -```none -set interfaces ethernet eth0 ipv6 address autoconf -set interfaces ethernet eth1 address 'fc01::1/64' -set nat66 destination rule 1 destination address 'fc00:470:f1cd:101::/64' -set nat66 destination rule 1 inbound-interface name 'eth0' -set nat66 destination rule 1 translation address 'fc01::/64' -set nat66 source rule 1 outbound-interface name 'eth0' -set nat66 source rule 1 source prefix 'fc01::/64' -set nat66 source rule 1 translation address 'fc00:470:f1cd:101::/64' -``` - -R2: - -```none -set interfaces bridge br1 address 'fc01::2/64' -set interfaces bridge br1 member interface eth0 -set interfaces bridge br1 member interface eth1 -set protocols static route6 ::/0 next-hop fc01::1 -set service router-advert interface br1 prefix ::/0 -``` - -Use the following topology to translate internal user local addresses -(`fc::/7`) to DHCPv6-PD provided prefixes from an ISP connected to -a VyOS HA pair. - -:::{figure} /_static/images/vyos_1_5_nat66_dhcpv6_wdummy.webp -:alt: VyOS NAT66 DHCPv6 using a dummy interface -::: - -Configure both routers (a and b) for DHCPv6-PD via dummy interface: - -```none -set interfaces dummy dum1 description 'DHCPv6-PD NPT dummy' -set interfaces bonding bond0 vif 20 dhcpv6-options pd 0 interface dum1 address '0' -set interfaces bonding bond0 vif 20 dhcpv6-options pd 1 interface dum1 address '0' -set interfaces bonding bond0 vif 20 dhcpv6-options pd 2 interface dum1 address '0' -set interfaces bonding bond0 vif 20 dhcpv6-options pd 3 interface dum1 address '0' -set interfaces bonding bond0 vif 20 dhcpv6-options rapid-commit -commit -``` - -Get the DHCPv6-PD prefixes from both routers: - -```none -trae@cr01a-vyos# run show interfaces dummy dum1 br -Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down -Interface IP Address S/L Description ---------- ---------- --- ----------- -dum1 2001:db8:123:b008::/64 u/u DHCPv6-PD NPT dummy - 2001:db8:123:b00a::/64 - 2001:db8:123:b00b::/64 - 2001:db8:123:b009::/64 - -trae@cr01b-vyos# run show int dummy dum1 brief -Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down -Interface IP Address S/L Description ---------- ---------- --- ----------- -dum1 2001:db8:123:b00d::/64 u/u DHCPv6-PD NPT dummy - 2001:db8:123:b00c::/64 - 2001:db8:123:b00e::/64 - 2001:db8:123:b00f::/64 -``` - -Configure the A-side router for NPTv6 using the prefixes above: - -```none -set nat66 source rule 10 description 'NPT to VLAN 10' -set nat66 source rule 10 outbound-interface name 'bond0.20' -set nat66 source rule 10 source prefix 'fd52:d62e:8011:a::/64' -set nat66 source rule 10 translation address '2001:db8:123:b008::/64' -set nat66 source rule 20 description 'NPT to VLAN 70' -set nat66 source rule 20 outbound-interface name 'bond0.20' -set nat66 source rule 20 source prefix 'fd52:d62e:8011:46::/64' -set nat66 source rule 20 translation address '2001:db8:123:b009::/64' -set nat66 source rule 30 description 'NPT to VLAN 200' -set nat66 source rule 30 outbound-interface name 'bond0.20' -set nat66 source rule 30 source prefix 'fd52:d62e:8011:c8::/64' -set nat66 source rule 30 translation address '2001:db8:123:b00a::/64' -set nat66 source rule 40 description 'NPT to VLAN 240' -set nat66 source rule 40 outbound-interface name 'bond0.20' -set nat66 source rule 40 source prefix 'fd52:d62e:8011:f0::/64' -set nat66 source rule 40 translation address '2001:db8:123:b00b::/64' -commit -``` - -Configure the B-side router for NPTv6 using the prefixes above: - -```none -set nat66 source rule 10 description 'NPT to VLAN 10' -set nat66 source rule 10 outbound-interface name 'bond0.20' -set nat66 source rule 10 source prefix 'fd52:d62e:8011:a::/64' -set nat66 source rule 10 translation address '2001:db8:123:b00c::/64' -set nat66 source rule 20 description 'NPT to VLAN 70' -set nat66 source rule 20 outbound-interface name 'bond0.20' -set nat66 source rule 20 source prefix 'fd52:d62e:8011:46::/64' -set nat66 source rule 20 translation address '2001:db8:123:b00d::/64' -set nat66 source rule 30 description 'NPT to VLAN 200' -set nat66 source rule 30 outbound-interface name 'bond0.20' -set nat66 source rule 30 source prefix 'fd52:d62e:8011:c8::/64' -set nat66 source rule 30 translation address '2001:db8:123:b00e::/64' -set nat66 source rule 40 description 'NPT to VLAN 240' -set nat66 source rule 40 outbound-interface name 'bond0.20' -set nat66 source rule 40 source prefix 'fd52:d62e:8011:f0::/64' -set nat66 source rule 40 translation address '2001:db8:123:b00f::/64' -commit -``` - -Verify that connections are hitting the rule on both sides: - -```none -trae@cr01a-vyos# run show nat66 source statistics -Rule Packets Bytes Interface ------- --------- ------- ----------- -10 1 104 bond0.20 -20 1 104 bond0.20 -30 8093 669445 bond0.20 -40 2446 216912 bond0.20 -``` diff --git a/docs/configuration/pki/md-index.md b/docs/configuration/pki/md-index.md deleted file mode 100644 index e7d793de..00000000 --- a/docs/configuration/pki/md-index.md +++ /dev/null @@ -1,583 +0,0 @@ ---- -lastproofread: '2024-01-05' ---- - -```{include} /_include/need_improvement.txt -``` - -(pki)= - -# PKI - -VyOS 1.4 changed the way in how encryption keys or certificates are stored on the -system. In the pre VyOS 1.4 era, certificates got stored under /config and every -service referenced a file. That made copying a running configuration from system -A to system B a bit harder, as you had to copy the files and their permissions -by hand. - -{vytask}`T3642` describes a new CLI subsystem that serves as a "certstore" to -all services requiring any kind of encryption key(s). In short, public and -private certificates are now stored in PKCS#8 format in the regular VyOS CLI. -Keys can now be added, edited, and deleted using the regular set/edit/delete -CLI commands. - -VyOS not only can now manage certificates issued by 3rd party Certificate -Authorities, it can also act as a CA on its own. You can create your own root -CA and sign keys with it by making use of some simple op-mode commands. - -Don't be afraid that you need to re-do your configuration. Key transformation is -handled, as always, by our migration scripts, so this will be a smooth transition -for you! - -## Key Generation - -### Certificate Authority (CA) - -VyOS now also has the ability to create CAs, keys, Diffie-Hellman and other -keypairs from an easy to access operational level command. - -```{opcmd} generate pki ca - -Create a new {abbr}`CA (Certificate Authority)` and output the CAs public and -private key on the console. -``` - -```{opcmd} generate pki ca install \ - -Create a new {abbr}`CA (Certificate Authority)` and output the CAs public and -private key on the console. - -:::{note} -In addition to the command above, the output is in a format which can be used -to directly import the key into the VyOS CLI by simply copy-pasting the output -from op-mode into configuration mode. - -``name`` is used for the VyOS CLI command to identify this key. This -key ``name`` is then used in the CLI configuration to reference the key -instance. -::: -``` - -```{opcmd} generate pki ca sign \ - -Create a new subordinate {abbr}`CA (Certificate Authority)` and sign it using -the private key referenced by ca-name. -``` - -```{opcmd} generate pki ca sign \ install \ - -Create a new subordinate {abbr}`CA (Certificate Authority)` and sign it using -the private key referenced by `name`. - -:::{note} -In addition to the command above, the output is in a format which can be used -to directly import the key into the VyOS CLI by simply copy-pasting the output -from op-mode into configuration mode. - -``name`` is used for the VyOS CLI command to identify this key. This -key ``name`` is then used in the CLI configuration to reference the key -instance. -::: -``` - -### Certificates - -```{opcmd} generate pki certificate - -Create a new public/private keypair and output the certificate on the console. -``` - -```{opcmd} generate pki certificate install \ - -Create a new public/private keypair and output the certificate on the console. - -:::{note} -In addition to the command above, the output is in a format which can be used -to directly import the key into the VyOS CLI by simply copy-pasting the output -from op-mode into configuration mode. - -``name`` is used for the VyOS CLI command to identify this key. This -key ``name`` is then used in the CLI configuration to reference the key -instance. -::: -``` - -```{opcmd} generate pki certificate self-signed - -Create a new self-signed certificate. The public/private is then shown on the -console. -``` - -```{opcmd} generate pki certificate self-signed install \ - -Create a new self-signed certificate. The public/private is then shown on the -console. - -:::{note} -In addition to the command above, the output is in a format which can be used -to directly import the key into the VyOS CLI by simply copy-pasting the output -from op-mode into configuration mode. - -``name`` is used for the VyOS CLI command to identify this key. This -key ``name`` is then used in the CLI configuration to reference the key -instance. -::: -``` - -```{opcmd} generate pki certificate sign \ - -Create a new public/private keypair which is signed by the CA referenced by -ca-name. The signed certificate is then output to the console. -``` - -```{opcmd} generate pki certificate sign \ install \ - -Create a new public/private keypair which is signed by the CA referenced by -ca-name. The signed certificate is then output to the console. - -:::{note} -In addition to the command above, the output is in a format which can be used -to directly import the key into the VyOS CLI by simply copy-pasting the output -from op-mode into configuration mode. - -``name`` is used for the VyOS CLI command to identify this key. This -key ``name`` is then used in the CLI configuration to reference the key -instance. -::: -``` - -### Diffie-Hellman parameters - -```{opcmd} generate pki dh - -Generate a new set of {abbr}`DH (Diffie-Hellman)` parameters. The key size -is requested by the CLI and defaults to 2048 bit. - -The generated parameters are then output to the console. -``` - -```{opcmd} generate pki dh install \ - -Generate a new set of {abbr}`DH (Diffie-Hellman)` parameters. The key size -is requested by the CLI and defaults to 2048 bit. - -:::{note} -In addition to the command above, the output is in a format which can be used -to directly import the key into the VyOS CLI by simply copy-pasting the output -from op-mode into configuration mode. - -``name`` is used for the VyOS CLI command to identify this key. This -key ``name`` is then used in the CLI configuration to reference the key -instance. -::: -``` - -### OpenVPN - -```{opcmd} generate pki openvpn shared-secret - -Generate a new OpenVPN shared secret. The generated secret is the output to -the console. -``` - -```{opcmd} generate pki openvpn shared-secret install \ - -Generate a new OpenVPN shared secret. The generated secret is the output to -the console. - -:::{note} -In addition to the command above, the output is in a format which can be used -to directly import the key into the VyOS CLI by simply copy-pasting the output -from op-mode into configuration mode. - -``name`` is used for the VyOS CLI command to identify this key. This -key ``name`` is then used in the CLI configuration to reference the key -instance. -::: -``` - -### WireGuard - -```{opcmd} generate pki wireguard key-pair - -Generate a new WireGuard public/private key portion and output the result to -the console. -``` - -```{opcmd} generate pki wireguard key-pair install \ - -Generate a new WireGuard public/private key portion and output the result to -the console. - -:::{note} -In addition to the command above, the output is in a format which can -be used to directly import the key into the VyOS CLI by simply copy-pasting -the output from op-mode into configuration mode. - -``interface`` is used for the VyOS CLI command to identify the WireGuard -interface where this private key is to be used. -::: -``` - -```{opcmd} generate pki wireguard preshared-key - -Generate a WireGuard pre-shared secret used for peers to communicate. -``` - -```{opcmd} generate pki wireguard preshared-key install \ - -Generate a WireGuard pre-shared secret used for peers to communicate. - -:::{note} -In addition to the command above, the output is in a format which can -be used to directly import the key into the VyOS CLI by simply copy-pasting -the output from op-mode into configuration mode. - -``peer`` is used for the VyOS CLI command to identify the WireGuard peer where -this secret is to be used. -::: -``` - -## Key usage (CLI) -### CA (Certificate Authority) - -```{cfgcmd} set pki ca \ certificate - -Add the public CA certificate for the CA named `name` to the VyOS CLI. - -:::{note} -When loading the certificate you need to manually strip the -``-----BEGIN CERTIFICATE-----`` and ``-----END CERTIFICATE-----`` tags. -Also, the certificate/key needs to be presented in a single line without -line breaks (``\n``), this can be done using the following shell command: - -``$ tail -n +2 ca.pem | head -n -1 | tr -d '\n'`` -::: -``` - -```{cfgcmd} set pki ca \ crl - -Certificate revocation list in PEM format. -``` - -```{cfgcmd} set pki ca \ description - -A human readable description what this CA is about. -``` - -```{cfgcmd} set pki ca \ private key - -Add the CAs private key to the VyOS CLI. This should never leave the system, -and is only required if you use VyOS as your certificate generator as -mentioned above. - -:::{note} -When loading the certificate you need to manually strip the -``-----BEGIN KEY-----`` and ``-----END KEY-----`` tags. Also, the -certificate/key needs to be presented in a single line without line -breaks (``\n``), this can be done using the following shell command: - -``$ tail -n +2 ca.key | head -n -1 | tr -d '\n'`` -::: -``` - -```{cfgcmd} set pki ca \ private password-protected - -Mark the CAs private key as password protected. User is asked for the password -when the key is referenced. -``` - -### Server Certificate - -After we have imported the CA certificate(s) we can now import and add -certificates used by services on this router. - -```{cfgcmd} set pki certificate \ certificate - -Add public key portion for the certificate named `name` to the VyOS CLI. - -:::{note} -When loading the certificate you need to manually strip the -``-----BEGIN CERTIFICATE-----`` and ``-----END CERTIFICATE-----`` tags. -Also, the certificate/key needs to be presented in a single line without -line breaks (``\n``), this can be done using the following shell command: - -``$ tail -n +2 cert.pem | head -n -1 | tr -d '\n'`` -::: -``` - -```{cfgcmd} set pki certificate \ description - -A human readable description what this certificate is about. -``` - -```{cfgcmd} set pki certificate \ private key - -Add the private key portion of this certificate to the CLI. This should never -leave the system as it is used to decrypt the data. - -:::{note} -When loading the certificate you need to manually strip the -``-----BEGIN KEY-----`` and ``-----END KEY-----`` tags. Also, the -certificate/key needs to be presented in a single line without line -breaks (``\n``), this can be done using the following shell command: - -``$ tail -n +2 cert.key | head -n -1 | tr -d '\n'`` -::: -``` - -```{cfgcmd} set pki certificate \ private password-protected - -Mark the private key as password protected. User is asked for the password -when the key is referenced. -``` - -```{cfgcmd} set pki certificate \ revoke - -If CA is present, this certificate will be included in generated CRLs -``` - -### Import files to PKI format - -VyOS provides this utility to import existing certificates/key files directly -into PKI from op-mode. Previous to VyOS 1.4, certificates were stored under the -/config folder permanently and will be retained post upgrade. - -```{opcmd} import pki ca \ file \ - -Import the public CA certificate from the defined file to VyOS CLI. -``` - -```{opcmd} import pki ca \ key-file \ - -Import the CAs private key portion to the CLI. This should never leave the -system as it is used to decrypt the data. The key is required if you use -VyOS as your certificate generator. -``` - -```{opcmd} import pki certificate \ file \ - -Import the certificate from the file to VyOS CLI. -``` - -```{opcmd} import pki certificate \ key-file \ - -Import the private key of the certificate to the VyOS CLI. This should never -leave the system as it is used to decrypt the data. -``` - -```{opcmd} import pki openvpn shared-secret \ file \ - -Import the OpenVPN shared secret stored in file to the VyOS CLI. -``` - -#### ACME - -The VyOS PKI subsystem can also be used to automatically retrieve Certificates -using the {abbr}`ACME (Automatic Certificate Management Environment)` protocol. - -```{cfgcmd} set pki certificate \ acme domain-name \ - -Domain names to apply, multiple domain-names can be specified. - -This is a mandatory option -``` - -```{cfgcmd} set pki certificate \ acme email \ - -Email used for registration and recovery contact. - -This is a mandatory option -``` - -```{cfgcmd} set pki certificate \ acme listen-address \ - -The address the server listens to during http-01 challenge -``` - -```{cfgcmd} set pki certificate \ acme rsa-key-size \<2048 | 3072 | 4096\> - -Size of the RSA key. - -This options defaults to 2048 -``` - -```{cfgcmd} set pki certificate \ acme url \ - -ACME Directory Resource URI. - -This defaults to https://acme-v02.api.letsencrypt.org/directory - -:::{note} -During initial deployment we recommend using the staging API -of LetsEncrypt to prevent and blacklisting of your system. The API -endpoint is https://acme-staging-v02.api.letsencrypt.org/directory -::: -``` - -## Operation - -VyOS operational mode commands are not only available for generating keys but -also to display them. - -```{opcmd} show pki ca - -Show a list of installed {abbr}`CA (Certificate Authority)` certificates. - -:::{code-block} none -vyos@vyos:~$ show pki ca -Certificate Authorities: -Name Subject Issuer CN Issued Expiry Private Key Parent --------------- ------------------------------------------------------- ----------------- ------------------- ------------------- ------------- -------------- -DST_Root_CA_X3 CN=ISRG Root X1,O=Internet Security Research Group,C=US CN=DST Root CA X3 2021-01-20 19:14:03 2024-09-30 18:14:03 No N/A -R3 CN=R3,O=Let's Encrypt,C=US CN=ISRG Root X1 2020-09-04 00:00:00 2025-09-15 16:00:00 No DST_Root_CA_X3 -vyos_rw CN=VyOS RW CA,O=VyOS,L=Some-City,ST=Some-State,C=GB CN=VyOS RW CA 2021-07-05 13:46:03 2026-07-04 13:46:03 Yes N/A -::: -``` - -```{opcmd} show pki ca \ - -Show only information for specified Certificate Authority. -``` - -```{opcmd} show pki certificate - -Show a list of installed certificates - -:::{code-block} none -vyos@vyos:~$ show pki certificate -Certificates: -Name Type Subject CN Issuer CN Issued Expiry Revoked Private Key CA Present ---------- ------ --------------------- ------------- ------------------- ------------------- --------- ------------- ------------- -ac2 Server CN=ac2.vyos.net CN=R3 2021-07-05 07:29:59 2021-10-03 07:29:58 No Yes Yes (R3) -rw_server Server CN=VyOS RW CN=VyOS RW CA 2021-07-05 13:48:02 2022-07-05 13:48:02 No Yes Yes (vyos_rw) -::: -``` - -```{opcmd} show pki certificate \ - -Show only information for specified certificate. -``` - -```{opcmd} show pki crl - -Show a list of installed {abbr}`CRLs (Certificate Revocation List)`. -``` - -```{opcmd} renew certbot - -Manually trigger certificate renewal. This will be done twice a day. -``` - -## Examples - -### Create a CA chain and leaf certificates - -This configuration generates & installs into the VyOS PKI system a root -certificate authority, alongside two intermediary certificate authorities for -client & server certificates. These CAs are then used to generate a server -certificate for the router, and a client certificate for a user. -- `vyos_root_ca` is the root certificate authority. -- `vyos_client_ca` and `vyos_server_ca` are intermediary certificate authorities, - which are signed by the root CA. -- `vyos_cert` is a leaf server certificate used to identify the VyOS router, - signed by the server intermediary CA. -- `vyos_example_user` is a leaf client certificate used to identify a user, - signed by client intermediary CA. - -First, we create the root certificate authority. - -```none -[edit] -vyos@vyos# run generate pki ca install vyos_root_ca -Enter private key type: [rsa, dsa, ec] (Default: rsa) rsa -Enter private key bits: (Default: 2048) 2048 -Enter country code: (Default: GB) GB -Enter state: (Default: Some-State) Some-State -Enter locality: (Default: Some-City) Some-City -Enter organization name: (Default: VyOS) VyOS -Enter common name: (Default: vyos.io) VyOS Root CA -Enter how many days certificate will be valid: (Default: 1825) 1825 -Note: If you plan to use the generated key on this router, do not encrypt the private key. -Do you want to encrypt the private key with a passphrase? [y/N] n -2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. -``` - -Secondly, we create the intermediary certificate authorities, which are used to -sign the leaf certificates. - -```none -[edit] -vyos@vyos# run generate pki ca sign vyos_root_ca install vyos_server_ca -Do you already have a certificate request? [y/N] n -Enter private key type: [rsa, dsa, ec] (Default: rsa) rsa -Enter private key bits: (Default: 2048) 2048 -Enter country code: (Default: GB) GB -Enter state: (Default: Some-State) Some-State -Enter locality: (Default: Some-City) Some-City -Enter organization name: (Default: VyOS) VyOS -Enter common name: (Default: vyos.io) VyOS Intermediary Server CA -Enter how many days certificate will be valid: (Default: 1825) 1095 -Note: If you plan to use the generated key on this router, do not encrypt the private key. -Do you want to encrypt the private key with a passphrase? [y/N] n -2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. - - -[edit] -vyos@vyos# run generate pki ca sign vyos_root_ca install vyos_client_ca -Do you already have a certificate request? [y/N] n -Enter private key type: [rsa, dsa, ec] (Default: rsa) rsa -Enter private key bits: (Default: 2048) 2048 -Enter country code: (Default: GB) GB -Enter state: (Default: Some-State) Some-State -Enter locality: (Default: Some-City) Some-City -Enter organization name: (Default: VyOS) VyOS -Enter common name: (Default: vyos.io) VyOS Intermediary Client CA -Enter how many days certificate will be valid: (Default: 1825) 1095 -Note: If you plan to use the generated key on this router, do not encrypt the private key. -Do you want to encrypt the private key with a passphrase? [y/N] n -2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. -``` - -Lastly, we can create the leaf certificates that devices and users will utilise. - -```none -[edit] -vyos@vyos# run generate pki certificate sign vyos_server_ca install vyos_cert -Do you already have a certificate request? [y/N] n -Enter private key type: [rsa, dsa, ec] (Default: rsa) rsa -Enter private key bits: (Default: 2048) 2048 -Enter country code: (Default: GB) GB -Enter state: (Default: Some-State) Some-State -Enter locality: (Default: Some-City) Some-City -Enter organization name: (Default: VyOS) VyOS -Enter common name: (Default: vyos.io) vyos.net -Do you want to configure Subject Alternative Names? [y/N] y -Enter alternative names in a comma separate list, example: ipv4:1.1.1.1,ipv6:fe80::1,dns:vyos.net -Enter Subject Alternative Names: dns:vyos.net,dns:www.vyos.net -Enter how many days certificate will be valid: (Default: 365) 365 -Enter certificate type: (client, server) (Default: server) server -Note: If you plan to use the generated key on this router, do not encrypt the private key. -Do you want to encrypt the private key with a passphrase? [y/N] n -2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. - - -[edit] -vyos@vyos# run generate pki certificate sign vyos_client_ca install vyos_example_user -Do you already have a certificate request? [y/N] n -Enter private key type: [rsa, dsa, ec] (Default: rsa) rsa -Enter private key bits: (Default: 2048) 2048 -Enter country code: (Default: GB) GB -Enter state: (Default: Some-State) Some-State -Enter locality: (Default: Some-City) Some-City -Enter organization name: (Default: VyOS) VyOS -Enter common name: (Default: vyos.io) Example User -Do you want to configure Subject Alternative Names? [y/N] y -Enter alternative names in a comma separate list, example: ipv4:1.1.1.1,ipv6:fe80::1,dns:vyos.net,rfc822:user@vyos.net -Enter Subject Alternative Names: rfc822:example.user@vyos.net -Enter how many days certificate will be valid: (Default: 365) 365 -Enter certificate type: (client, server) (Default: server) client -Note: If you plan to use the generated key on this router, do not encrypt the private key. -Do you want to encrypt the private key with a passphrase? [y/N] n -2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. -``` diff --git a/docs/configuration/policy/md-access-list.md b/docs/configuration/policy/md-access-list.md deleted file mode 100644 index c3a92e56..00000000 --- a/docs/configuration/policy/md-access-list.md +++ /dev/null @@ -1,70 +0,0 @@ -# Access List Policy - -Filtering is used for both input and output of the routing information. Once -filtering is defined, it can be applied in any direction. VyOS makes filtering -possible using acls and prefix lists. - -Basic filtering can be done using access-list and access-list6. - -## Configuration - -### Access Lists - -```{cfgcmd} set policy access-list \ - -This command creates the new access list policy, where `` must be -a number from 1 to 2699. -``` - -```{cfgcmd} set policy access-list \ description \ - -Set description for the access list. -``` - -```{cfgcmd} set policy access-list \ rule \<1-65535\> action \ - -This command creates a new rule in the access list and defines an action. -``` - -```{cfgcmd} set policy access-list \ rule \<1-65535\> \ \ - -This command defines matching parameters for access list rule. Matching -criteria could be applied to destination or source parameters: - -* any: any IP address to match. -* host: single host IP address to match. -* inverse-match: network/netmask to match (requires network be defined). -* network: network/netmask to match (requires inverse-match be defined). -``` - - -### IPv6 Access List - -Basic filtering could also be applied to IPv6 traffic. - -```{cfgcmd} set policy access-list6 \ - -This command creates the new IPv6 access list, identified by `` -``` - -```{cfgcmd} set policy access-list6 \ description \ - -Set description for the IPv6 access list. -``` - -```{cfgcmd} set policy access-list6 \ rule \<1-65535\> action \ - -This command creates a new rule in the IPv6 access list and defines an -action. -``` - -```{cfgcmd} set policy access-list6 \ rule \<1-65535\> source \ - -This command defines matching parameters for IPv6 access list rule. Matching -criteria could be applied to source parameters: - -* any: any IPv6 address to match. -* exact-match: exact match of the network prefixes. -* network: network/netmask to match (requires inverse-match be defined) BUG, -NO invert-match option in access-list6 -``` \ No newline at end of file diff --git a/docs/configuration/policy/md-as-path-list.md b/docs/configuration/policy/md-as-path-list.md deleted file mode 100644 index 1fcece91..00000000 --- a/docs/configuration/policy/md-as-path-list.md +++ /dev/null @@ -1,29 +0,0 @@ -# BGP - AS Path Policy - -VyOS provides policies commands exclusively for BGP traffic filtering and -manipulation: **as-path-list** is one of them. - -## Configuration - -### policy as-path-list - -```{cfgcmd} set policy as-path-list \ - -Create as-path-policy identified by name ``. -``` -```{cfgcmd} set policy as-path-list \ description \ - -Set description for as-path-list policy. -``` -```{cfgcmd} set policy as-path-list \ rule \<1-65535\> action \ - -Set action to take on entries matching this rule. -``` -```{cfgcmd} set policy as-path-list \ rule \<1-65535\> description \ - -Set description for rule. -``` -```{cfgcmd} set policy as-path-list \ rule \<1-65535\> regex \ - -Regular expression to match against an AS path. For example "64501 64502". -``` \ No newline at end of file diff --git a/docs/configuration/policy/md-community-list.md b/docs/configuration/policy/md-community-list.md deleted file mode 100644 index bdcf4140..00000000 --- a/docs/configuration/policy/md-community-list.md +++ /dev/null @@ -1,29 +0,0 @@ -# BGP - Community List - -VyOS provides policies commands exclusively for BGP traffic filtering and -manipulation: **community-list** is one of them. - -## Configuration - -### policy community-list - -```{cfgcmd} set policy community-list \ - -Creat community-list policy identified by name ``. -``` -```{cfgcmd} set policy community-list \ description \ - -Set description for community-list policy. -``` -```{cfgcmd} set policy community-list \ rule \<1-65535\> action \ - -Set action to take on entries matching this rule. -``` -```{cfgcmd} set policy community-list \ rule \<1-65535\> description \ - -Set description for rule. -``` -```{cfgcmd} set policy community-list \ rule \<1-65535\> regex \ - -Regular expression to match against a community-list. -``` \ No newline at end of file diff --git a/docs/configuration/policy/md-examples.md b/docs/configuration/policy/md-examples.md deleted file mode 100644 index 2b5d54d2..00000000 --- a/docs/configuration/policy/md-examples.md +++ /dev/null @@ -1,205 +0,0 @@ -# BGP Example - -**Policy definition:** - -```none -# Create policy -set policy route-map setmet rule 2 action 'permit' -set policy route-map setmet rule 2 set as-path prepend '2 2 2' - -# Apply policy to BGP -set protocols bgp system-as 1 -set protocols bgp neighbor 203.0.113.2 address-family ipv4-unicast route-map import 'setmet' -set protocols bgp neighbor 203.0.113.2 address-family ipv4-unicast soft-reconfiguration 'inbound' -``` - -Using 'soft-reconfiguration' we get the policy update without bouncing the -neighbor. - -**Routes learned before routing policy applied:** - -```none -vyos@vos1:~$ show ip bgp -BGP table version is 0, local router ID is 192.168.56.101 -Status codes: s suppressed, d damped, h history, * valid, > best, i - internal, - r RIB-failure, S Stale, R Removed -Origin codes: i - IGP, e - EGP, ? - incomplete - - Network Next Hop Metric LocPrf Weight Path -*> 198.51.100.3/32 203.0.113.2 1 0 2 i < Path - -Total number of prefixes 1 -``` - -**Routes learned after routing policy applied:** - -```none -vyos@vos1:~$ show ip bgp -BGP table version is 0, local router ID is 192.168.56.101 -Status codes: s suppressed, d damped, h history, * valid, > best, i - internal, - r RIB-failure, S Stale, R Removed -Origin codes: i - IGP, e - EGP, ? - incomplete - - Network Next Hop Metric LocPrf Weight Path -*> 198.51.100.3/32 203.0.113.2 1 0 2 2 2 2 i - -Total number of prefixes 1 -vyos@vos1:~$ -``` - -You now see the longer AS path. - -# Transparent Proxy - -The following example will show how VyOS can be used to redirect web -traffic to an external transparent proxy: - -```none -set policy route FILTER-WEB rule 1000 destination port 80 -set policy route FILTER-WEB rule 1000 protocol tcp -set policy route FILTER-WEB rule 1000 set table 100 -``` - -This creates a route policy called FILTER-WEB with one rule to set the -routing table for matching traffic (TCP port 80) to table ID 100 -instead of the default routing table. - -To create routing table 100 and add a new default gateway to be used by -traffic matching our route policy: - -```none -set protocols static table 100 route 0.0.0.0/0 next-hop 10.255.0.2 -``` - -This can be confirmed using the `show ip route table 100` operational -command. - -Finally, to apply the policy route to ingress traffic on our LAN -interface, we use: - -```none -set policy route FILTER-WEB interface eth1 -``` - - -# Multiple Uplinks - -VyOS Policy-Based Routing (PBR) works by matching source IP address -ranges and forwarding the traffic using different routing tables. - -Routing tables that will be used in this example are: - -- `table 10` Routing table used for VLAN 10 (192.168.188.0/24) -- `table 11` Routing table used for VLAN 11 (192.168.189.0/24) -- `main` Routing table used by VyOS and other interfaces not - participating in PBR - -:::{figure} /_static/images/pbr_example_1.webp -:alt: PBR multiple uplinks -:scale: 80 % - -Policy-Based Routing with multiple ISP uplinks -(source ./draw.io/pbr_example_1.drawio) -::: - -Add default routes for routing `table 10` and `table 11` - -```none -set protocols static table 10 route 0.0.0.0/0 next-hop 192.0.2.1 -set protocols static table 11 route 0.0.0.0/0 next-hop 192.0.2.2 -``` - -Add policy route matching VLAN source addresses - -```none -set policy route PBR rule 20 set table '10' -set policy route PBR rule 20 description 'Route VLAN10 traffic to table 10' -set policy route PBR rule 20 source address '192.168.188.0/24' - -set policy route PBR rule 30 set table '11' -set policy route PBR rule 30 description 'Route VLAN11 traffic to table 11' -set policy route PBR rule 30 source address '192.168.189.0/24' -``` - -Apply routing policy to **inbound** direction of out VLAN interfaces - -```none -set policy route 'PBR' interface eth0.10 -set policy route 'PBR' interface eth0.11 -``` - -**OPTIONAL:** Exclude Inter-VLAN traffic (between VLAN10 and VLAN11) -from PBR - -```none -set firewall group network-group VLANS-GR description 'VLANs networks' -set firewall group network-group VLANS-GR network '192.168.188.0/24' -set firewall group network-group VLANS-GR network '192.168.189.0/24' - -set policy route PBR rule 10 description 'VLAN10 <-> VLAN11 shortcut' -set policy route PBR rule 10 destination group network-group 'VLANS-GR' -set policy route PBR rule 10 set table 'main' -``` - -These commands allow the VLAN10 and VLAN11 hosts to communicate with -each other using the main routing table. - -## Local route - -The following example allows VyOS to use {abbr}`PBR (Policy-Based Routing)` -for traffic, which originated from the router itself. That solution for multiple -ISP's and VyOS router will respond from the same interface that the packet was -received. Also, it used, if we want that one VPN tunnel to be through one -provider, and the second through another. - -- `203.0.113.254` IP addreess on VyOS eth1 from ISP1 -- `192.168.2.254` IP addreess on VyOS eth2 from ISP2 -- `table 10` Routing table used for ISP1 -- `table 11` Routing table used for ISP2 - -```none -set policy local-route rule 101 set table '10' -set policy local-route rule 101 source address '203.0.113.254' -set policy local-route rule 102 set table '11' -set policy local-route rule 102 source address '192.0.2.254' -set protocols static table 10 route 0.0.0.0/0 next-hop '203.0.113.1' -set protocols static table 11 route 0.0.0.0/0 next-hop '192.0.2.2' -``` - -Add multiple source IP in one rule with same priority - -```none -set policy local-route rule 101 set table '10' -set policy local-route rule 101 source address '203.0.113.254' -set policy local-route rule 101 source address '203.0.113.253' -set policy local-route rule 101 source address '198.51.100.0/24' -``` - - -# Clamp MSS for a specific IP - -This example shows how to target an MSS clamp (in our example to 1360 bytes) -to a specific destination IP. - -```none -set policy route IP-MSS-CLAMP rule 10 description 'Clamp TCP session MSS to 1360 for 198.51.100.30' -set policy route IP-MSS-CLAMP rule 10 destination address '198.51.100.30/32' -set policy route IP-MSS-CLAMP rule 10 protocol 'tcp' -set policy route IP-MSS-CLAMP rule 10 set tcp-mss '1360' -set policy route IP-MSS-CLAMP rule 10 tcp flags 'SYN' -``` - -To apply this policy to the correct interface, configure it on the -interface the inbound local host will send through to reach our -destined target host (in our example eth1). - -```none -set policy route IP-MSS-CLAMP interface eth1 -``` - -You can view that the policy is being correctly (or incorrectly) utilised -with the following command: - -```none -show policy route statistics -``` diff --git a/docs/configuration/policy/md-extcommunity-list.md b/docs/configuration/policy/md-extcommunity-list.md deleted file mode 100644 index 5247c13c..00000000 --- a/docs/configuration/policy/md-extcommunity-list.md +++ /dev/null @@ -1,33 +0,0 @@ -# BGP - Extended Community List - -VyOS provides policies commands exclusively for BGP traffic filtering and -manipulation: **extcommunity-list** is one of them. - -## Configuration - -### policy extcommunity-list - -```{cfgcmd} set policy extcommunity-list \ - -Creat extcommunity-list policy identified by name \. -``` -```{cfgcmd} set policy extcommunity-list \ description \ - -Set description for extcommunity-list policy. -``` -```{cfgcmd} set policy extcommunity-list \ rule \<1-65535\> action \ - -Set action to take on entries matching this rule. -``` -```{cfgcmd} set policy extcommunity-list \ rule \<1-65535\> description \ - -Set description for rule. -``` -```{cfgcmd} set policy extcommunity-list \ rule \<1-65535\> regex \ - -Regular expression to match against an extended community list, where text -could be: -* \: Extended community list regular expression. -* \: Route Target regular expression. -* \: Site of Origin regular expression. -``` \ No newline at end of file diff --git a/docs/configuration/policy/md-index.md b/docs/configuration/policy/md-index.md deleted file mode 100644 index f919e70a..00000000 --- a/docs/configuration/policy/md-index.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -lastproofread: '2021-07-12' ---- - -```{include} /_include/need_improvement.txt -``` - - -# Policy - -Policies are used for filtering and traffic management. With policies, network -administrators could filter and treat traffic -according to their needs. - -There could be a wide range of routing policies. Some examples are listed -below: -- Filter traffic based on source/destination address. -- Set some metric to routes learned from a particular neighbor. -- Set some attributes (like AS PATH or Community value) to advertised routes - to neighbors. -- Prefer a specific routing protocol routes over another routing protocol - running on the same router. - -Policies, in VyOS, are implemented using FRR filtering and route maps. Detailed -information of FRR could be found in - -## Policy Sections - -```{toctree} -:includehidden: true -:maxdepth: 1 - -access-list -prefix-list -route -route-map -local-route -as-path-list -community-list -extcommunity-list -large-community-list -``` - -## Examples - -Examples of policies usage: - -```{toctree} -:includehidden: true -:maxdepth: 1 - -examples -``` diff --git a/docs/configuration/policy/md-large-community-list.md b/docs/configuration/policy/md-large-community-list.md deleted file mode 100644 index 23b9a85a..00000000 --- a/docs/configuration/policy/md-large-community-list.md +++ /dev/null @@ -1,29 +0,0 @@ -# BGP - Large Community List - -VyOS provides policies commands exclusively for BGP traffic filtering and -manipulation: **large-community-list** is one of them. - -## Configuration - -### policy large-community-list - -```{cfgcmd} set policy large-community-list \ - -Create large-community-list policy identified by name ``. -``` -```{cfgcmd} set policy large-community-list \ description \ - -Set description for large-community-list policy. -``` -```{cfgcmd} set policy large-community-list \ rule \<1-65535\> action \ - -Set action to take on entries matching this rule. -``` -```{cfgcmd} set policy large-community-list \ rule \<1-65535\> description \ - -Set description for rule. -``` -```{cfgcmd} set policy large-community-list \ rule \<1-65535\> regex \ - -Regular expression to match against a large community list. -``` \ No newline at end of file diff --git a/docs/configuration/policy/md-local-route.md b/docs/configuration/policy/md-local-route.md deleted file mode 100644 index 527a2380..00000000 --- a/docs/configuration/policy/md-local-route.md +++ /dev/null @@ -1,100 +0,0 @@ -# Local Route Policy - -Policies for local traffic are defined in this section. - -## Configuration - -### Local Route IPv4 - -```{cfgcmd} set policy local-route rule \<1-32765\> set table \<1-200|main\> - -Set the routing table to use for forwarding matching packets. -``` - -```{cfgcmd} set policy local-route rule \<1-32765\> set vrf \ - -Set the VRF to use for forwarding matching packets. -``` - -```{cfgcmd} set policy local-route rule \<1-32765\> protocol \ - -Match specified protocol (name or number). -``` - -```{cfgcmd} set policy local-route rule \<1-32765\> fwmark \<1-2147483647\> - -Match specified firewall mark (fwmark). -``` - -```{cfgcmd} set policy local-route rule \<1-32765\> source address \ - -Match specified source address or prefix. -``` - -```{cfgcmd} set policy local-route rule \<1-32765\> source port \<1-65535\> - -Match specified source port. -``` - -```{cfgcmd} set policy local-route rule \<1-32765\> destination address \ - -Match specified destination address or prefix. -``` - -```{cfgcmd} set policy local-route rule \<1-32765\> destination port \<1-65535\> - -Match specified destination port. -``` - -```{cfgcmd} set policy local-route rule \<1-32765\> inbound-interface \ - -Match specified inbound interface. -``` - - -### Local Route IPv6 - -```{cfgcmd} set policy local-route6 rule \<1-32765\> set table \<1-200|main\> - -Set the routing table to use for forwarding matching packets. -``` - -```{cfgcmd} set policy local-route6 rule \<1-32765\> set vrf \ - -Set the VRF to use for forwarding matching packets. -``` - -```{cfgcmd} set policy local-route6 rule \<1-32765\> protocol \ - -Match specified protocol (name or number). -``` - -```{cfgcmd} set policy local-route6 rule \<1-32765\> fwmark \<1-2147483647\> - -Match specified firewall mark (fwmark). -``` - -```{cfgcmd} set policy local-route6 rule \<1-32765\> source address \ - -Match specified source address or prefix. -``` - -```{cfgcmd} set policy local-route6 rule \<1-32765\> source port \<1-65535\> - -Match specified source port. -``` - -```{cfgcmd} set policy local-route6 rule \<1-32765\> destination address \ - -Match specified destination address or prefix. -``` - -```{cfgcmd} set policy local-route6 rule \<1-32765\> destination port \<1-65535\> - -Match specified destination port. -``` - -```{cfgcmd} set policy local-route6 rule \<1-32765\> inbound-interface \ - -Match specified inbound interface. -``` \ No newline at end of file diff --git a/docs/configuration/policy/md-prefix-list.md b/docs/configuration/policy/md-prefix-list.md deleted file mode 100644 index eb827c77..00000000 --- a/docs/configuration/policy/md-prefix-list.md +++ /dev/null @@ -1,152 +0,0 @@ -# Prefix List Policy - -Prefix lists provides the most powerful prefix based filtering mechanism. In -addition to access-list functionality, ip prefix-list has prefix length range -specification. - -If no ip prefix list is specified, it acts as permit. If ip prefix list is -defined, and no match is found, default deny is applied. - -Prefix filtering can be done using prefix-list and prefix-list6. - -## Configuration - -### IPv4 Prefix Lists (prefix-list) - -```{cfgcmd} set policy prefix-list \ - -This command creates the new prefix-list policy, identified by ``. -``` - -```{cfgcmd} set policy prefix-list \ description \ - -Set description for the prefix-list policy. -``` - -```{cfgcmd} set policy prefix-list \ rule \<1-65535\> action \ - -This command creates a new rule in the prefix-list and defines an action. -``` - -```{cfgcmd} set policy prefix-list \ rule \<1-65535\> description \ - -Set description for rule in the prefix-list. -``` - -```{cfgcmd} set policy prefix-list \ rule \<1-65535\> prefix \ - -Prefix to match against. -``` - -```{cfgcmd} set policy prefix-list \ rule \<1-65535\> ge \<0-32\> - -Netmask greater than length. -``` - -```{cfgcmd} set policy prefix-list \ rule \<1-65535\> le \<0-32\> - -Netmask less than length -``` - - -### Example: IPv4 Prefix Lists (prefix-list) - -This example creates an IPv4 prefix-list named PL4-EXAMPLE-NAME, defines 3 -rules each with 1 prefix, and matches le (less than/equal to) /32. - -```{cfgcmd} set policy prefix-list PL4-EXAMPLE-NAME rule 10 action 'permit' - -``` -```{cfgcmd} set policy prefix-list PL4-EXAMPLE-NAME rule 10 le '32' -``` - -```{cfgcmd} set policy prefix-list PL4-EXAMPLE-NAME rule 10 prefix '192.0.2.0/24' -``` - -```{cfgcmd} set policy prefix-list PL4-EXAMPLE-NAME rule 20 action 'permit' -``` - -```{cfgcmd} set policy prefix-list PL4-EXAMPLE-NAME rule 20 le '32' -``` - -```{cfgcmd} set policy prefix-list PL4-EXAMPLE-NAME rule 20 prefix '198.51.100.0/24' -``` - -```{cfgcmd} set policy prefix-list PL4-EXAMPLE-NAME rule 30 action 'permit' -``` - -```{cfgcmd} set policy prefix-list PL4-EXAMPLE-NAME rule 30 le '32' -``` - -```{cfgcmd} set policy prefix-list PL4-EXAMPLE-NAME rule 30 prefix '203.0.113.0/24' -``` - -### IPv6 Prefix Lists (prefix-list6) - -```{cfgcmd} set policy prefix-list6 \ - -This command creates the new IPv6 prefix-list policy, identified by ``. -``` - -```{cfgcmd} set policy prefix-list6 \ description \ - -Set description for the IPv6 prefix-list policy. -``` - -```{cfgcmd} set policy prefix-list6 \ rule \<1-65535\> action \ - -This command creates a new rule in the IPv6 prefix-list and defines an -action. -``` - -```{cfgcmd} set policy prefix-list6 \ rule \<1-65535\> description \ - -Set description for rule in IPv6 prefix-list. -``` - -```{cfgcmd} set policy prefix-list6 \ rule \<1-65535\> prefix \ - -IPv6 prefix. -``` - -```{cfgcmd} set policy prefix-list6 \ rule \<1-65535\> ge \<0-128\> - -Netmask greater than length. -``` - -```{cfgcmd} set policy prefix-list6 \ rule \<1-65535\> le \<0-128\> - -Netmask less than length -``` - -### Example: IPv6 Prefix Lists (prefix-list6) - -This example creates an IPv6 prefix-list6 named PL6-EXAMPLE-NAME, defines 3 -rules each with 1 prefix, and matches le (less than/equal to) /128. - -```{cfgcmd} set policy prefix-list6 PL6-EXAMPLE-NAME rule 10 action 'permit' -``` - -```{cfgcmd} set policy prefix-list6 PL6-EXAMPLE-NAME rule 10 le '128' -``` - -```{cfgcmd} set policy prefix-list6 PL6-EXAMPLE-NAME rule 10 prefix '2001:db8:0:0::/64' -``` - -```{cfgcmd} set policy prefix-list6 PL6-EXAMPLE-NAME rule 20 action 'permit' -``` - -```{cfgcmd} set policy prefix-list6 PL6-EXAMPLE-NAME rule 20 le '128' -``` - -```{cfgcmd} set policy prefix-list6 PL6-EXAMPLE-NAME rule 20 prefix '2001:db8:0:1::/64' -``` - -```{cfgcmd} set policy prefix-list6 PL6-EXAMPLE-NAME rule 30 action 'permit' -``` - -```{cfgcmd} set policy prefix-list6 PL6-EXAMPLE-NAME rule 30 le '128' -``` - -```{cfgcmd} set policy prefix-list6 PL6-EXAMPLE-NAME rule 30 prefix '2001:db8:0:2::/64' -``` \ No newline at end of file diff --git a/docs/configuration/policy/md-route-map.md b/docs/configuration/policy/md-route-map.md deleted file mode 100644 index 624b542c..00000000 --- a/docs/configuration/policy/md-route-map.md +++ /dev/null @@ -1,439 +0,0 @@ -# Route Map Policy - -Route map is a powerfull command, that gives network administrators a very -useful and flexible tool for traffic manipulation. - -## Configuration - -### Route Map - -```{cfgcmd} set policy route-map \ - - This command creates a new route-map policy, identified by \. -``` - - -```{cfgcmd} set policy route-map \ description \ - -Set description for the route-map policy. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> action \ - -Set action for the route-map policy. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> call \ - -Call another route-map policy on match. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> continue \<1-65535\> - -Jump to a different rule in this route-map on a match. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> description \ - -Set description for the rule in the route-map policy. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> match as-path \ - -BGP as-path list to match. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> match community community-list \ - -BGP community-list to match. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> match community exact-match - -Set BGP community-list to exactly match. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> match extcommunity \ - -BGP extended community to match. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> match interface \ - -First hop interface of a route to match. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> match ip address access-list \<1-2699\> - -IP address of route to match, based on access-list. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> match ip address prefix-list \ - -IP address of route to match, based on prefix-list. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> match ip address prefix-len \<0-32\> - -IP address of route to match, based on specified prefix-length. -Note that this can be used for kernel routes only. -Do not apply to the routes of dynamic routing protocols (e.g. BGP, -RIP, OSFP), as this can lead to unexpected results.. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> match ip nexthop access-list \<1-2699\> - -IP next-hop of route to match, based on access-list. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> match ip nexthop address \ - -IP next-hop of route to match, based on ip address. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> match ip nexthop prefix-len \<0-32\> - -IP next-hop of route to match, based on prefix length. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> match ip nexthop prefix-list \ - -IP next-hop of route to match, based on prefix-list. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> match ip nexthop type \ - -IP next-hop of route to match, based on type. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> match ip route-source access-list \<1-2699\> - -IP route source of route to match, based on access-list. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> match ip route-source prefix-list \ - -IP route source of route to match, based on prefix-list. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> match ipv6 address access-list \ - -IPv6 address of route to match, based on IPv6 access-list. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> match ipv6 address prefix-list \ - -IPv6 address of route to match, based on IPv6 prefix-list. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> match ipv6 address prefix-len \<0-128\> - -IPv6 address of route to match, based on specified prefix-length. -Note that this can be used for kernel routes only. -Do not apply to the routes of dynamic routing protocols (e.g. BGP, -RIP, OSFP), as this can lead to unexpected results.. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> match ipv6 nexthop \ - -Nexthop IPv6 address to match. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> match large-community large-community-list \ - -Match BGP large communities. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> match local-preference \<0-4294967295\> - -Match local preference. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> match metric \<1-65535\> - -Match route metric. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> match origin \ - -Boarder Gateway Protocol (BGP) origin code to match. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> match peer \ - -Peer IP address to match. -``` - - -````{cfgcmd} set policy route-map \ rule \<1-65535\> match protocol \ - -```{eval-rst} -Source protocol to match. - * ``babel`` - Babel routing protocol (Babel) - * ``bgp`` - Border Gateway Protocol (BGP) - * ``connected`` - Connected routes (directly attached subnet or host) - * ``isis`` - Intermediate System to Intermediate System (IS-IS) - * ``kernel`` - Kernel routes - * ``ospf`` - Open Shortest Path First (OSPFv2) - * ``ospfv3`` - Open Shortest Path First (IPv6) (OSPFv3) - * ``rip`` - Routing Information Protocol (RIP) - * ``ripng`` - Routing Information Protocol next-generation (IPv6) (RIPng) - * ``static`` - Statically configured routes - * ``table`` - Non-main Kernel Routing Table - * ``vnc`` - Virtual Network Control (VNC) -``` -```` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> match rpki \ - -Match RPKI validation result. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> match source-vrf \ - -Source VRF to match. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> match tag \<1-65535\> - -Route tag to match. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> on-match goto \<1-65535\> - -Exit policy on match: go to rule <1-65535> -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> on-match next - -Exit policy on match: go to next sequence number. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> set aggregator \ \<1-4294967295|x.x.x.x\> - -BGP aggregator attribute: AS number or IP address of an aggregation. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> set as-path exclude \<1-4294967295 | all\> - -Drop AS-NUMBER from the BGP AS path. - -If ``all`` is specified, remove all AS numbers from the AS_PATH of the BGP -path's NLRI. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> set as-path prepend \<1-4294967295\> - -Prepend the given string of AS numbers to the AS_PATH of the BGP path's NLRI. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> set as-path prepend-last-as \ - -Prepend the existing last AS number (the leftmost ASN) to the AS_PATH. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> set atomic-aggregate - -BGP atomic aggregate attribute. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> set community \ \ - -Add or replace BGP community attribute in format ``<0-65535:0-65535>`` -or from well-known community list -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> set community none - -Delete all BGP communities -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> set community delete \ - -Delete BGP communities matching the community-list. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> set large-community \ \ - -Add or replace BGP large-community attribute in format -``<0-4294967295:0-4294967295:0-4294967295>`` -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> set large-community none - -Delete all BGP large-communities -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> set large-community delete \ - -Delete BGP communities matching the large-community-list. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> set extcommunity bandwidth \<1-25600|cumulative|num-multipaths\> - -Set extcommunity bandwidth -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> set extcommunity bandwidth-non-transitive - -The link bandwidth extended community is encoded as non-transitive -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> set extcommunity rt \ - -Set route target value in format ``<0-65535:0-4294967295>`` or ````. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> set extcommunity soo \ - -Set site of origin value in format ``<0-65535:0-4294967295>`` or ````. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> set extcommunity none - -Clear all BGP extcommunities. -``` - - -```{cfgcmd} set policy route-map \ rule \<1-65535\> set distance \<0-255\> - -Locally significant administrative distance. -``` -```{cfgcmd} set policy route-map \ rule \<1-65535\> set ip-next-hop \ - -Nexthop IP address. -``` -```{cfgcmd} set policy route-map \ rule \<1-65535\> set ip-next-hop unchanged - -Set the next-hop as unchanged. Pass through the route-map without -changing its value -``` -```{cfgcmd} set policy route-map \ rule \<1-65535\> set ip-next-hop peer-address - -Set the BGP nexthop address to the address of the peer. For an incoming -route-map this means the ip address of our peer is used. For an -outgoing route-map this means the ip address of our self is used to -establish the peering with our neighbor. -``` -```{cfgcmd} set policy route-map \ rule \<1-65535\> set ipv6-next-hop \ \ - -Nexthop IPv6 address. -``` -```{cfgcmd} set policy route-map \ rule \<1-65535\> set ipv6-next-hop peer-address - -Set the BGP nexthop address to the address of the peer. For an incoming -route-map this means the ip address of our peer is used. For an -outgoing route-map this means the ip address of our self is used to -establish the peering with our neighbor. -``` -```{cfgcmd} set policy route-map \ rule \<1-65535\> set ipv6-next-hop prefer-global - -For Incoming and Import Route-maps if we receive a v6 global and v6 LL -address for the route, then prefer to use the global address as the -nexthop. -``` -```{cfgcmd} set policy route-map \ rule \<1-65535\> set local-preference \<0-4294967295\> - -Set BGP local preference attribute. -``` -```{cfgcmd} set policy route-map \ rule \<1-65535\> set metric \<+/-metric|0-4294967295|rtt|+rtt|-rtt\> - -Set the route metric. When used with BGP, set the BGP attribute MED -to a specific value. Use ``+/-`` to add or subtract the specified value -to/from the existing/MED. Use ``rtt`` to set the MED to the round trip -time or ``+rtt/-rtt`` to add/subtract the round trip time to/from the MED. -``` -```{cfgcmd} set policy route-map \ rule \<1-65535\> set metric-type \ - -Set OSPF external metric-type. -``` -```{cfgcmd} set policy route-map \ rule \<1-65535\> set origin \ - -Set BGP origin code. -``` -```{cfgcmd} set policy route-map \ rule \<1-65535\> set originator-id \ - -Set BGP originator ID attribute. -``` -```{cfgcmd} set policy route-map \ rule \<1-65535\> set src \ - -Set source IP/IPv6 address for route. -``` -```{cfgcmd} set policy route-map \ rule \<1-65535\> set table \<1-200\> - -Set prefixes to table. -``` -```{cfgcmd} set policy route-map \ rule \<1-65535\> set tag \<1-65535\> - -Set tag value for routing protocol. -``` -```{cfgcmd} set policy route-map \ rule \<1-65535\> set weight \<0-4294967295\> - -Set BGP weight attribute -``` - -### List of well-known communities - -> - `local-as` - Well-known communities value NO_EXPORT_SUBCONFED 0xFFFFFF03 -> - `no-advertise` - Well-known communities value NO_ADVERTISE 0xFFFFFF02 -> - `no-export` - Well-known communities value NO_EXPORT 0xFFFFFF01 -> - `graceful-shutdown` - Well-known communities value GRACEFUL_SHUTDOWN 0xFFFF0000 -> - `accept-own` - Well-known communities value ACCEPT_OWN 0xFFFF0001 -> - `route-filter-translated-v4` - Well-known communities value ROUTE_FILTER_TRANSLATED_v4 0xFFFF0002 -> - `route-filter-v4` - Well-known communities value ROUTE_FILTER_v4 0xFFFF0003 -> - `route-filter-translated-v6` - Well-known communities value ROUTE_FILTER_TRANSLATED_v6 0xFFFF0004 -> - `route-filter-v6` - Well-known communities value ROUTE_FILTER_v6 0xFFFF0005 -> - `llgr-stale` - Well-known communities value LLGR_STALE 0xFFFF0006 -> - `no-llgr` - Well-known communities value NO_LLGR 0xFFFF0007 -> - `accept-own-nexthop` - Well-known communities value accept-own-nexthop 0xFFFF0008 -> - `blackhole` - Well-known communities value BLACKHOLE 0xFFFF029A -> - `no-peer` - Well-known communities value NOPEER 0xFFFFFF04 diff --git a/docs/configuration/policy/md-route.md b/docs/configuration/policy/md-route.md deleted file mode 100644 index 828bd0f1..00000000 --- a/docs/configuration/policy/md-route.md +++ /dev/null @@ -1,424 +0,0 @@ -# Route and Route6 Policy - -IPv4 route and IPv6 route policies are defined in this section. These route -policies can then be associated to interfaces. - -## Rule-Sets - -A rule-set is a named collection of rules that can be applied to an interface. -Each rule is numbered, has an action to apply if the rule is matched, and the -ability to specify the criteria to match. Data packets go through the rules -from 1 - 999999, at the first match the action of the rule will be executed. - -```{cfgcmd} set policy route \ description \ - -``` -```{cfgcmd} set policy route6 \ description \ - -Provide a rule-set description. -``` - -```{cfgcmd} set policy route \ default-log -``` - -```{cfgcmd} set policy route6 \ default-log - -Option to log packets hitting default-action. -``` - -```{cfgcmd} set policy route \ interface \ -``` - -```{cfgcmd} set policy route6 \ interface \ - -Apply routing policy to interface -``` - -```{cfgcmd} set policy route \ rule \ description \ -``` - -```{cfgcmd} set policy route6 \ rule \ description \ - -Provide a description for each rule. -``` - -```{cfgcmd} set policy route \ rule \ log \ -``` - -```{cfgcmd} set policy route6 \ rule \ log \ - -Option to enable or disable log matching rule. -``` - -### Matching criteria - -There are a lot of matching criteria options available, both for -`policy route` and `policy route6`. These options are listed -in this section. - -```{cfgcmd} set policy route \ rule \ connection-mark \<1-2147483647\> -``` - -```{cfgcmd} set policy route6 \ rule \ connection-mark \<1-2147483647\> - -Set match criteria based on connection mark. -``` - -```{cfgcmd} set policy route \ rule \ mark \ -``` - -```{cfgcmd} set policy route6 \ rule \ mark \ - -Match based on the firewall mark (fwmark), where \ can be: - * \<0-2147483647\> a single fwmark - * !\<0-2147483647\> everything except a single fwmark - * <start-end> a range of marks - * !<start-end> everything except the range of marks - -:::{note} -When using the ``set table`` or ``set vrf`` commands the mark -settings are ignored and overwritten with a table-specific mark that -is set to 0x7FFFFFFF - the id of the table/VRF. -::: -``` - -```{cfgcmd} set policy route \ rule \ source address \ -``` - -```{cfgcmd} set policy route \ rule \ destination address \ -``` - -```{cfgcmd} set policy route6 \ rule \ source address \ -``` - -```{cfgcmd} set policy route6 \ rule \ destination address \ - -Set match criteria based on source or destination ipv4|ipv6 address, where -<match_criteria> could be: -``` - -For ipv4: -: - \: IP address to match. - - \: Subnet to match. - - \-\: IP range to match. - - !\: Match everything except the specified address. - - !\: Match everything except the specified subnet. - - !\-\: Match everything except the specified range. - -And for ipv6: -: - \: IPv6 address to match. - - \: IPv6 prefix to match. - - \-\: IPv6 range to match. - - !\: Match everything except the specified address. - - !\: Match everything except the specified prefix. - - !\-\: Match everything except the - specified range. - -```{cfgcmd} set policy route \ rule \ source group \ \ -``` - -```{cfgcmd} set policy route \ rule \ destination group \ \ -``` - -```{cfgcmd} set policy route6 \ rule \ source group \ \ -``` - -```{cfgcmd} set policy route6 \ rule \ destination group \ \ - -Set match criteria based on source or destination groups, where <text> -would be the group name/identifier. Prepend character '!' for inverted -matching criteria. -``` - -```{cfgcmd} set policy route \ rule \ destination port \ -``` - -```{cfgcmd} set policy route6 \ rule \ destination port \ - -Set match criteria based on destination port, where \ could -be: -* <port name>: Named port (any name in /etc/services, e.g., http). -* \<1-65535\>: Numbered port. -* <start>-<end>: Numbered port range (e.g., 1001-1005). - -Multiple destination ports can be specified as a comma-separated list. The -whole list can also be "negated" using '!'. For example: -'!22,telnet,http,123,1001-1005' -``` - -```{cfgcmd} set policy route \ rule \ disable -``` - -```{cfgcmd} set policy route6 \ rule \ disable - -Option to disable rule. -``` - -```{cfgcmd} set policy route \ rule \ dscp \ -``` - -```{cfgcmd} set policy route6 \ rule \ dscp \ -``` - -```{cfgcmd} set policy route \ rule \ dscp-exclude \ -``` - -```{cfgcmd} set policy route6 \ rule \ dscp-exclude \ - -Match based on dscp value criteria. Multiple values from 0 to 63 -and ranges are supported. -``` - -```{cfgcmd} set policy route \ rule \ fragment \ -``` - -```{cfgcmd} set policy route6 \ rule \ fragment \ - -Set IP fragment match, where: -* match-frag: Second and further fragments of fragmented packets. -* match-non-frag: Head fragments or unfragmented packets. -``` - -```{cfgcmd} set policy route \ rule \ icmp \ -``` - -```{cfgcmd} set policy route6 \ rule \ icmpv6 \ - -Match based on icmp|icmpv6 code and type. -``` - -```{cfgcmd} set policy route \ rule \ icmp type-name \ -``` - -```{cfgcmd} set policy route6 \ rule \ icmpv6 type-name \ - -Match based on icmp|icmpv6 type-name criteria. Use tab for information -about what type-name criteria are supported. -``` - -```{cfgcmd} set policy route \ rule \ ipsec \ -``` - -```{cfgcmd} set policy route6 \ rule \ ipsec \ - -Set IPSec inbound match criterias, where: -* match-ipsec: match inbound IPsec packets. -* match-none: match inbound non-IPsec packets. -``` - -```{cfgcmd} set policy route \ rule \ limit burst \<0-4294967295\> -``` - -```{cfgcmd} set policy route6 \ rule \ limit burst \<0-4294967295\> - -Set maximum number of packets to alow in excess of rate. -``` - -```{cfgcmd} set policy route \ rule \ limit rate \ -``` - -```{cfgcmd} set policy route6 \ rule \ limit rate \ - -Set maximum average matching rate. Format for rate: integer/time_unit, where -time_unit could be any one of second, minute, hour or day.For example -1/second implies rule to be matched at an average of once per second. -``` - -```{cfgcmd} set policy route \ rule \ protocol \ -``` - -```{cfgcmd} set policy route6 \ rule \ protocol \ - -Match a protocol criteria. A protocol number or a name which is defined in: -``/etc/protocols``. Special names are ``all`` for all protocols and -``tcp_udp`` for tcp and udp based packets. The ``!`` negates the selected -protocol. -``` - -```{cfgcmd} set policy route \ rule \ packet-length \ -``` - -```{cfgcmd} set policy route6 \ rule \ packet-length \ -``` - -```{cfgcmd} set policy route \ rule \ packet-length-exclude \ -``` - -```{cfgcmd} set policy route6 \ rule \ packet-length-exclude \ - -Match based on packet length criteria. Multiple values from 1 to 65535 -and ranges are supported. -``` - -```{cfgcmd} set policy route \ rule \ packet-type \[broadcast | host | multicast | other\] -``` - -```{cfgcmd} set policy route6 \ rule \ packet-type \[broadcast | host | multicast | other\] - -Match based on packet type criteria. -``` - -```{cfgcmd} set policy route \ rule \ recent count \<1-255\> -``` - -```{cfgcmd} set policy route6 \ rule \ recent count \<1-255\> -``` - -```{cfgcmd} set policy route \ rule \ recent time \<1-4294967295\> -``` - -```{cfgcmd} set policy route6 \ rule \ recent time \<1-4294967295\> - -Set parameters for matching recently seen sources. This match could be used -by seeting count (source address seen more than <1-255> times) and/or time -(source address seen in the last <0-4294967295> seconds). -``` - -```{cfgcmd} set policy route \ rule \ state \ -``` - -```{cfgcmd} set policy route6 \ rule \ state \ - -Set match criteria based on session state. -``` - -```{cfgcmd} set policy route \ rule \ tcp flags \ -``` - -```{cfgcmd} set policy route6 \ rule \ tcp flags \ - -Set match criteria based on tcp flags. Allowed values for TCP flags: SYN ACK -FIN RST URG PSH ALL. When specifying more than one flag, flags should be -comma-separated. For example : value of 'SYN,!ACK,!FIN,!RST' will only match -packets with the SYN flag set, and the ACK, FIN and RST flags unset. -``` - -```{cfgcmd} set policy route \ rule \ time monthdays \ -``` - -```{cfgcmd} set policy route6 \ rule \ time monthdays \ -``` - -```{cfgcmd} set policy route \ rule \ time startdate \ -``` - -```{cfgcmd} set policy route6 \ rule \ time startdate \ -``` - -```{cfgcmd} set policy route \ rule \ time starttime \ -``` - -```{cfgcmd} set policy route6 \ rule \ time starttime \ -``` - -```{cfgcmd} set policy route \ rule \ time stopdate \ -``` - -```{cfgcmd} set policy route6 \ rule \ time stopdate \ -``` - -```{cfgcmd} set policy route \ rule \ time stoptime \ -``` - -```{cfgcmd} set policy route6 \ rule \ time stoptime \ -``` - -```{cfgcmd} set policy route \ rule \ time weekdays \ -``` - -```{cfgcmd} set policy route6 \ rule \ time weekdays \ -``` - -```{cfgcmd} set policy route \ rule \ time utc -``` - -```{cfgcmd} set policy route6 \ rule \ time utc - -Time to match the defined rule. -``` - -```{cfgcmd} set policy route rule \ ttl \ \<0-255\> - -Match time to live parameter, where 'eq' stands for 'equal'; 'gt' stands for -'greater than', and 'lt' stands for 'less than'. -``` - -```{cfgcmd} set policy route6 rule \ hop-limit \ \<0-255\> - -Match hop-limit parameter, where 'eq' stands for 'equal'; 'gt' stands for -'greater than', and 'lt' stands for 'less than'. -``` - -### Actions - -When mathcing all patterns defined in a rule, then different actions can -be made. This includes droping the packet, modifying certain data, or -setting a different routing table. - -```{cfgcmd} set policy route \ rule \ action drop -``` - -```{cfgcmd} set policy route6 \ rule \ action drop - -Set rule action to drop. -``` - -```{cfgcmd} set policy route \ rule \ set connection-mark \<1-2147483647\> -``` - -```{cfgcmd} set policy route6 \ rule \ set connection-mark \<1-2147483647\> - -Set a specific connection mark. -``` - -```{cfgcmd} set policy route \ rule \ set dscp \<0-63\> -``` - -```{cfgcmd} set policy route6 \ rule \ set dscp \<0-63\> - -Set packet modifications: Packet Differentiated Services Codepoint (DSCP) -``` - -```{cfgcmd} set policy route \ rule \ set mark \<1-2147483647\> -``` - -```{cfgcmd} set policy route6 \ rule \ set mark \<1-2147483647\> - -Set a specific packet mark. -``` - -```{cfgcmd} set policy route \ rule \ set table \
-``` - -```{cfgcmd} set policy route6 \ rule \ set table \
- -Set the routing table to forward packet with. - -:::{note} -When using the ``set table`` or ``set vrf`` commands matching -against the mark is not possible, because it gets overwritten with a -table-specific mark that is 0x7FFFFFFF - the id of the table/VRF. -::: -``` - -```{cfgcmd} set policy route \ rule \ set tcp-mss \<500-1460\> -``` - -```{cfgcmd} set policy route6 \ rule \ set tcp-mss \<500-1460\> - -Set packet modifications: Explicitly set TCP Maximum segment size value. -``` - -```{cfgcmd} set policy route \ rule \ set vrf \ -``` - -```{cfgcmd} set policy route6 \ rule \ set vrf \ - -Set the VRF to forward packet with. - -:::{note} -When using the ``set table`` or ``set vrf`` commands matching -against the mark is not possible, because it gets overwritten with a -table-specific mark that is 0x7FFFFFFF - the id of the table/VRF. -::: -``` \ No newline at end of file diff --git a/docs/configuration/protocols/md-arp.md b/docs/configuration/protocols/md-arp.md deleted file mode 100644 index 7d9bf4f9..00000000 --- a/docs/configuration/protocols/md-arp.md +++ /dev/null @@ -1,72 +0,0 @@ -```{eval-rst} -.. meta:: - :description: The Address Resolution Protocol (ARP) resolves - network-layer addresses to link-layer MAC addresses. - :keywords: arp, network, protocol, mac, address, ipv4, static -``` - -(routing_static_arp)= - -# ARP - -The {abbr}`ARP (Address Resolution Protocol)` resolves IPv4 network layer addresses -to link layer MAC addresses. -addresses. This mapping is essential for communication within the Internet -Protocol suite. ARP was standardized in 1982 by {rfc}`826` (STD 37). - -:::{note} -In Internet Protocol version 6 (IPv6) networks, address resolution is -performed by the Neighbor Discovery Protocol (NDP). -::: - -Use the following commands to configure or view ARP table entries. - -## Configuration - -```{eval-rst} -.. cfgcmd:: set protocols static arp interface address mac - - **Configure a static ARP entry on the specified interface.** - - This creates a permanent mapping between an IP address and a MAC address - on the specified interface. - - Example: - - .. code-block:: none - - set protocols static arp interface eth0 address 192.0.2.1 mac 01:23:45:67:89:01 -``` - -## Operation - -```{eval-rst} -.. opcmd:: show protocols static arp - - Show all ARP table entries across all interfaces. - - .. code-block:: none - - vyos@vyos:~$ show protocols static arp - Address HWtype HWaddress Flags Mask Iface - 10.1.1.1 ether 00:53:00:de:23:2e C eth1 - 10.1.1.100 ether 00:53:00:de:23:aa CM eth1 -``` - -```{eval-rst} -.. opcmd:: show protocols static arp interface - - Show all ARP table entries for the specific interface. - - Example for ``eth1``: - - .. code-block:: none - - vyos@vyos:~$ show protocols static arp interface eth1 - Address HWtype HWaddress Flags Mask Iface - 10.1.1.1 ether 00:53:00:de:23:2e C eth1 - 10.1.1.100 ether 00:53:00:de:23:aa CM eth1 -``` - -[arp]: https://en.wikipedia.org/wiki/Address_Resolution_Protocol - diff --git a/docs/configuration/protocols/md-babel.md b/docs/configuration/protocols/md-babel.md deleted file mode 100644 index b03e9fa4..00000000 --- a/docs/configuration/protocols/md-babel.md +++ /dev/null @@ -1,296 +0,0 @@ -```{eval-rst} -.. meta:: - :description: The Babel routing protocol provides robust and efficient - routing for wired and wireless mesh networks. - :keywords: babel, routing, protocol, wireless, mesh, network, metric, - ipv4, ipv6 -``` - -(babel)= - -# Babel - -The Babel protocol provides robust and efficient routing for both wired and -wireless mesh networks. By default, Babel uses hop-count metrics on wired links -and a variant of Expected Transmission Count (ETX) on wireless links. -Administrators can configure Babel to account for radio diversity, -automatically compute link latency, and include that latency in the routing -metric. {rfc}`8966` defines the Babel protocol. - -Babel is a dual-stack protocol. A single Babel instance routes both IPv4 and -IPv6 traffic simultaneously. - -## General configuration - -VyOS does not require a specific command to start the Babel process. The system -automatically starts the routing process when you configure the first -Babel-enabled interface. - -```{cfgcmd} set protocols babel interface \ - -**Enable Babel routing on the specified interface.** - -The system immediately begins sending and receiving Babel packets on this -interface. -``` - -## Optional configuration - -```{cfgcmd} set protocols babel parameters diversity - -**Enable radio-frequency diversity routing for the Babel process.** - -Enabling this feature is highly recommended for networks with many -wireless nodes. - -:::{note} -When you enable diversity routing, you should also configure the -``diversity-factor`` and ``channel`` parameters. -::: -``` - -```{cfgcmd} set protocols babel parameters diversity-factor \<1-256\> - -**Configure the multiplicative factor for diversity routing, in units of -1/256.** - -Lower multiplicative factors give greater weight to diversity in route -selection. The default value is 256, which disables diversity routing. -On nodes with multiple independent radios, configure a value of 128 or less. -``` - -```{cfgcmd} set protocols babel parameters resend-delay \<20-655340\> - -**Configure the delay in milliseconds before the system resends an -important request or update.** - -The default value is 2000 ms. -``` - -```{cfgcmd} set protocols babel parameters smoothing-half-life \<0-65534\> - -**Configure the time constant, in seconds, for the smoothing algorithm used -to implement hysteresis.** - -Higher values reduce route oscillation but slightly increase convergence -time. A value of 0 disables hysteresis and is suitable for wired networks. -The default is 4 seconds. -``` - -## Interfaces configuration - -```{cfgcmd} set protocols babel interface \ type \ - -**Configure the network type for the Babel-enabled interface.** - -Choose from the following: - -* ``auto``: Babel automatically detects if an interface is wired or - wireless. -* ``wired``: Babel enables optimizations for wired interfaces. -* ``wireless``: Babel disables optimizations suitable only for wired - interfaces. Specifying wireless is always correct, but may cause slower - convergence and increased routing traffic. -``` - -```{cfgcmd} set protocols babel interface \ split-horizon \ - -**Configure the split-horizon routing behavior for the specified -interface.** - -Use one of the following options: - -* ``default``: Babel automatically enables split-horizon on wired - interfaces and disables it on wireless interfaces. -* ``enable``: Babel enables split-horizon on the interface. This - optimization should be used only on symmetric, transitive (wired) - networks. -* ``disable``: Babel disables split-horizon on the interface. Disabling - split-horizon is always safe and correct. -``` - -```{cfgcmd} set protocols babel interface \ hello-interval \<20-655340\> - -**Configure the interval, in milliseconds, between scheduled hello messages -on the specified interface.** - -On wired links, Babel detects link failures within two hello intervals. -On wireless links, link quality is reestimated at each interval. The -default is 4000 ms. -``` - -```{cfgcmd} set protocols babel interface \ update-interval \<20-655340\> - -**Configure the interval, in milliseconds, between scheduled routing -updates on the specified interface.** - -Because Babel uses triggered updates extensively, you can increase this -value on reliable links with minimal packet loss. The default is 20000 ms. -``` - -```{cfgcmd} set protocols babel interface \ rxcost \<1-65534\> - -**Configure the base receive cost for the specified interface.** - -Babel applies this value based on the configured network type: - -* ``wired``: The value is the routing cost advertised to neighboring - routers. -* ``wireless``: The value is a multiplier used to compute the ETX - (Expected Transmission Count) reception cost. - -The default value is 256. -``` - -```{cfgcmd} set protocols babel interface \ rtt-decay \<1-256\> - -**Configure the decay factor for the exponential moving average of RTT -samples, in units of 1/256.** - -Higher values discard older samples faster. The default value is 42. -``` - -```{cfgcmd} set protocols babel interface \ rtt-min \<1-65535\> - -**Configure the minimum RTT, in milliseconds, at which the cost to a -neighbor begins to increase.** - -The additional cost is linear in (rtt - rtt-min). The default value is 10 ms. -``` - -```{cfgcmd} set protocols babel interface \ rtt-max \<1-65535\> - -**Configure the maximum RTT, in milliseconds, above which the cost to a -neighbor stops increasing.** - -The default value is 120 ms. -``` - -```{cfgcmd} set protocols babel interface \ max-rtt-penalty \<0-65535\> - -**Configure the maximum cost added to a neighbor when RTT meets or exceeds -rtt-max.** - -Setting this value to 0 disables RTT-based costs. The default value is 150. -``` - -```{cfgcmd} set protocols babel interface \ enable-timestamps - -**Configure adding timestamps to each Hello and IHU message to calculate -RTT values.** - -Enabling timestamps is recommended for tunnel interfaces. -``` - -```{cfgcmd} set protocols babel interface \ channel \<1-254|interfering|noninterfering\> - -**Configure the channel identifier that diversity routing uses for the -specified interface.** - -Interfaces interfere with each other based on the assigned channel -identifier: - -* ``1–254``: The interface interferes with interfaces sharing the same - channel number and with interfaces configured as ``interfering``. -* ``interfering``: The interface interferes with all others except those - configured as ``noninterfering``. -* ``noninterfering``: The interface interferes only with itself. -``` - -## Redistribution configuration - -```{cfgcmd} set protocols babel redistribute \ \ - -**Configure the redistribution of routing information from the specified -route source into the Babel process.** - -The following route sources are available: - -* **ipv4:** ``bgp``, ``connected``, ``eigrp``, ``isis``, ``kernel``, - ``nhrp``, ``ospf``, ``rip``, ``static`` -* **ipv6:** ``bgp``, ``connected``, ``eigrp``, ``isis``, ``kernel``, - ``nhrp``, ``ospfv3``, ``ripng``, ``static`` -``` - -```{cfgcmd} set protocols babel distribute-list \ access-list \ \ - -**Configure global Babel route filtering using an access list.** - -Specify the direction in which the access list is applied: - -* ``in``: Filters incoming routes. -* ``out``: Filters outgoing routes. -``` - -```{cfgcmd} set protocols babel distribute-list \ interface \ access-list \ \ - -**Configure Babel route filtering on the specified interface using an -access list.** - -Specify the direction in which the access list is applied: - -* ``in``: Filters incoming routes. -* ``out``: Filters outgoing routes. -``` - -```{cfgcmd} set protocols babel distribute-list \ prefix-list \ \ - -**Configure global Babel route filtering using a prefix list.** - -Specify the direction in which the prefix list is applied: - -* ``in``: Filters incoming routes. -* ``out``: Filters outgoing routes. -``` - -```{cfgcmd} set protocols babel distribute-list \ interface \ prefix-list \ \ - -**Configure Babel route filtering on the specified interface using a -prefix list.** - -Specify the direction in which the prefix list is applied: - -* ``in``: Filters incoming routes. -* ``out``: Filters outgoing routes. -``` - -## Configuration example - -### Basic two-node babel network - -**Goal:** The following example connects two routers (Node 1 and Node 2) via -their eth0 interfaces and uses the Babel routing protocol to advertise -(redistribute) each router's locally configured networks (represented by -loopback addresses) to one another. - -**Node 1:** - -```none -# Configure the loopback (local networks) and physical (eth0) addresses -set interfaces loopback lo address 10.1.1.1/32 -set interfaces loopback lo address fd12:3456:dead:beef::1/128 -set interfaces ethernet eth0 address 192.168.1.1/24 - -# Enable Babel on the physical link -set protocols babel interface eth0 type wired - -# Instruct Babel to advertise (redistribute) the locally configured networks -set protocols babel redistribute ipv4 connected -set protocols babel redistribute ipv6 connected -``` - -**Node 2:** - -```none -# Configure the loopback (local networks) and physical (eth0) addresses -set interfaces loopback lo address 10.2.2.2/32 -set interfaces loopback lo address fd12:3456:beef:dead::2/128 -set interfaces ethernet eth0 address 192.168.1.2/24 - -# Enable Babel on the physical link -set protocols babel interface eth0 type wired - -# Tell Babel to advertise (redistribute) the locally configured networks -set protocols babel redistribute ipv4 connected -set protocols babel redistribute ipv6 connected -``` diff --git a/docs/configuration/protocols/md-bfd.md b/docs/configuration/protocols/md-bfd.md deleted file mode 100644 index 59541abc..00000000 --- a/docs/configuration/protocols/md-bfd.md +++ /dev/null @@ -1,205 +0,0 @@ ---- -lastproofread: '2023-01-27' ---- - -```{include} /_include/need_improvement.txt -``` - -(routing-bfd)= - -# BFD - -{abbr}`BFD (Bidirectional Forwarding Detection)` is described and extended by -the following RFCs: {rfc}`5880`, {rfc}`5881` and {rfc}`5883`. - -In the age of very fast networks, a second of unreachability may equal millions of lost packets. -The idea behind BFD is to detect very quickly when a peer is down and take action extremely fast. - -BFD sends lots of small UDP packets very quickly to ensures that the peer is still alive. - -This allows avoiding the timers defined in BGP and OSPF protocol to expires. - -## Configure BFD - -```{cfgcmd} set protocols bfd peer \ - -Set BFD peer IPv4 address or IPv6 address -``` - -```{cfgcmd} set protocols bfd peer \ echo-mode - -Enables the echo transmission mode -``` - -```{cfgcmd} set protocols bfd peer \ multihop - -Allow this BFD peer to not be directly connected -``` - -```{cfgcmd} set protocols bfd peer \ source [address \ | interface \] - -Bind listener to specific interface/address, mandatory for IPv6 -``` - -```{cfgcmd} set protocols bfd peer \ interval echo-interval \<10-60000\> - -The minimal echo receive transmission interval that this system is -capable of handling -``` - -```{cfgcmd} set protocols bfd peer \ interval multiplier \<2-255\> - -Remote transmission interval will be multiplied by this value -``` - -```{cfgcmd} set protocols bfd peer \ interval [receive | transmit] \<10-60000\> - -Interval in milliseconds -``` - -```{cfgcmd} set protocols bfd peer \ shutdown - -Disable a BFD peer -``` - -```{cfgcmd} set protocols bfd peer \ minimum-ttl \<1-254\> - -For multi hop sessions only. Configure the minimum expected TTL for an -incoming BFD control packet. - -This feature serves the purpose of thightening the packet validation -requirements to avoid receiving BFD control packets from other sessions. -``` - -### Enable BFD in BGP - -```{cfgcmd} set protocols bgp neighbor \ bfd - -Enable BFD on a single BGP neighbor -``` - -```{cfgcmd} set protocols bgp peer-group \ bfd - -Enable BFD on a BGP peer group -``` - -### Enable BFD in OSPF - -```{cfgcmd} set protocols ospf interface \ bfd - - Enable BFD for OSPF on an interface - -``` - -```{cfgcmd} set protocols ospfv3 interface \ bfd - -Enable BFD for OSPFv3 on an interface -``` - -### Enable BFD in ISIS - -```{cfgcmd} set protocols isis \ interface \ bfd - -Enable BFD for ISIS on an interface - -``` - -## Operational Commands - -```{opcmd} show bfd peers - - Show all BFD peers - - :::{code-block} none - BFD Peers: - peer 198.51.100.33 vrf default interface eth4.100 - ID: 4182341893 - Remote ID: 12678929647 - Status: up - Uptime: 1 month(s), 16 hour(s), 29 minute(s), 38 second(s) - Diagnostics: ok - Remote diagnostics: ok - Local timers: - Receive interval: 300ms - Transmission interval: 300ms - Echo transmission interval: 50ms - Remote timers: - Receive interval: 300ms - Transmission interval: 300ms - Echo transmission interval: 0ms - - peer 198.51.100.55 vrf default interface eth4.101 - ID: 4618932327 - Remote ID: 3312345688 - Status: up - Uptime: 20 hour(s), 16 minute(s), 19 second(s) - Diagnostics: ok - Remote diagnostics: ok - Local timers: - Receive interval: 300ms - Transmission interval: 300ms - Echo transmission interval: 50ms - Remote timers: - Receive interval: 300ms - Transmission interval: 300ms - Echo transmission interval: 0ms - ::: -``` - -## BFD Static Route Monitoring - - -A monitored static route conditions the installation to the RIB on the BFD -session running state: when BFD session is up the route is installed to RIB, -but when the BFD session is down it is removed from the RIB. - - -### Configuration - -```{cfgcmd} set protocols static route \ next-hop \ bfd profile \ - -Configure a static route for \ using gateway \ -and use the gateway address as BFD peer destination address. -``` - -```{cfgcmd} set protocols static route \ next-hop \ bfd multi-hop source \ profile \ - -Configure a static route for \ using gateway \, -use source address to indentify the peer when is multi-hop session -and the gateway address as BFD peer destination address. -``` - -```{cfgcmd} set protocols static route6 \ next-hop \ bfd profile \ - -Configure a static route for \ using gateway \ -and use the gateway address as BFD peer destination address. -``` - -```{cfgcmd} set protocols static route6 \ next-hop \ bfd multi-hop source \ profile \ - -Configure a static route for \ using gateway \, -use source address to indentify the peer when is multi-hop session -and the gateway address as BFD peer destination address. -``` - -(bfd-operational-commands)= - -## Operational Commands - -```{opcmd} show bfd static routes - -Showing BFD monitored static routes - -:::{code-block} none -Showing BFD monitored static routes: - - Next hops: - VRF default IPv4 Unicast: - 10.10.13.3/32 peer 192.168.2.3 (status: installed) - 172.16.10.3/32 peer 192.168.10.1 (status: uninstalled) - - VRF default IPv4 Multicast: - - VRF default IPv6 Unicast: -::: -``` \ No newline at end of file diff --git a/docs/configuration/protocols/md-bgp.md b/docs/configuration/protocols/md-bgp.md deleted file mode 100644 index 0af79f6e..00000000 --- a/docs/configuration/protocols/md-bgp.md +++ /dev/null @@ -1,1414 +0,0 @@ -(routing-bgp)= - -# BGP - -{abbr}`BGP (Border Gateway Protocol)` is one of the Exterior Gateway Protocols -and the de facto standard interdomain routing protocol. The latest BGP version -is 4. BGP-4 is described in {rfc}`1771` and updated by {rfc}`4271`. {rfc}`2858` -adds multiprotocol support to BGP. - -VyOS makes use of {abbr}`FRR (Free Range Routing)` and we would like to thank -them for their effort! - -## Basic Concepts - -(bgp-autonomous-systems)= - -### Autonomous Systems - -From {rfc}`1930`: - -> An AS is a connected group of one or more IP prefixes run by one or more -> network operators which has a SINGLE and CLEARLY DEFINED routing policy. - -Each {abbr}`AS (Autonomous System)` has an identifying number associated with it -called an {abbr}`ASN (Autonomous System Number)`. This is a two octet value -ranging in value from 1 to 65535. The AS numbers 64512 through 65535 are defined -as private AS numbers. Private AS numbers must not be advertised on the global -Internet. The 2-byte AS number range has been exhausted. 4-byte AS numbers are -specified in {rfc}`6793`, and provide a pool of 4294967296 AS numbers. - -The {abbr}`ASN (Autonomous System Number)` is one of the essential elements of -BGP. BGP is a distance vector routing protocol, and the AS-Path framework -provides distance vector metric and loop detection to BGP. - -```{cfgcmd} set protocols bgp system-as \ - -Set local {abbr}`ASN (Autonomous System Number)` that this router represents. -This is a a mandatory option! -``` - -(bgp-address-families)= - - -### Address Families - - -Multiprotocol extensions enable BGP to carry routing information for multiple -network layer protocols. BGP supports an Address Family Identifier (AFI) for -IPv4 and IPv6. - - -(bgp-route-selection)= - - -### Route Selection - - -The route selection process used by FRR's BGP implementation uses the following -decision criterion, starting at the top of the list and going towards the -bottom until one of the factors can be used. - - -01. **Weight check** - - - Prefer higher local weight routes to lower routes. - - -02. **Local preference check** - - - Prefer higher local preference routes to lower. - - -03. **Local route check** - - - Prefer local routes (statics, aggregates, redistributed) to received routes. - - -04. **AS path length check** - - - Prefer shortest hop-count AS_PATHs. - - -05. **Origin check** - - - Prefer the lowest origin type route. That is, prefer IGP origin routes to - EGP, to Incomplete routes. - - -06. **MED check** - - - Where routes with a MED were received from the same AS, prefer the route - with the lowest MED. - - -07. **External check** - - - Prefer the route received from an external, eBGP peer over routes received - from other types of peers. - - -08. **IGP cost check** - - - Prefer the route with the lower IGP cost. - - -09. **Multi-path check** - - - If multi-pathing is enabled, then check whether the routes not yet - distinguished in preference may be considered equal. If - {cfgcmd}`bgp bestpath as-path multipath-relax` is set, all such routes are - considered equal, otherwise routes received via iBGP with identical AS_PATHs - or routes received from eBGP neighbours in the same AS are considered equal. - - -10. **Already-selected external check** - - - Where both routes were received from eBGP peers, then prefer the route - which is already selected. Note that this check is not applied if - {cfgcmd}`bgp bestpath compare-routerid` is configured. This check can - prevent some cases of oscillation. - - -11. **Router-ID check** - - - Prefer the route with the lowest router-ID. If the route has an - ORIGINATOR_ID attribute, through iBGP reflection, then that router ID is - used, otherwise the router-ID of the peer the route was received from is - used. - - -12. **Cluster-List length check** - - - The route with the shortest cluster-list length is used. The cluster-list - reflects the iBGP reflection path the route has taken. - - -13. **Peer address** - - - Prefer the route received from the peer with the higher transport layer - address, as a last-resort tie-breaker. - - -(bgp-capability-negotiation)= - - -### Capability Negotiation - - -When adding IPv6 routing information exchange feature to BGP. There were some -proposals. {abbr}`IETF (Internet Engineering Task Force)` -{abbr}`IDR (Inter Domain Routing)` adopted a proposal called Multiprotocol -Extension for BGP. The specification is described in {rfc}`2283`. The protocol -does not define new protocols. It defines new attributes to existing BGP. When -it is used exchanging IPv6 routing information it is called BGP-4+. When it is -used for exchanging multicast routing information it is called MBGP. - - -*bgpd* supports Multiprotocol Extension for BGP. So if a remote peer supports -the protocol, *bgpd* can exchange IPv6 and/or multicast routing information. - - -Traditional BGP did not have the feature to detect a remote peer's -capabilities, e.g. whether it can handle prefix types other than IPv4 unicast -routes. This was a big problem using Multiprotocol Extension for BGP in an -operational network. {rfc}`2842` adopted a feature called Capability -Negotiation. *bgpd* use this Capability Negotiation to detect the remote peer's -capabilities. If a peer is only configured as an IPv4 unicast neighbor, *bgpd* -does not send these Capability Negotiation packets (at least not unless other -optional BGP features require capability negotiation). - - -By default, FRR will bring up peering with minimal common capability for the -both sides. For example, if the local router has unicast and multicast -capabilities and the remote router only has unicast capability the local router -will establish the connection with unicast only capability. When there are no -common capabilities, FRR sends Unsupported Capability error and then resets the -connection. - - -## Configuration - - -(bgp-router-configuration)= - - -### BGP Router Configuration - - -First of all you must configure BGP router with the {abbr}`ASN (Autonomous -System Number)`. The AS number is an identifier for the autonomous system. -The BGP protocol uses the AS number for detecting whether the BGP connection -is internal or external. VyOS does not have a special command to start the BGP -process. The BGP process starts when the first neighbor is configured. - -```{cfgcmd} set protocols bgp system-as \ - -Set local autonomous system number that this router represents. This is a -mandatory option! -``` - -#### Peers Configuration - - -##### Defining Peers - -```{cfgcmd} set protocols bgp neighbor \ remote-as \ - -This command creates a new neighbor whose remote-as is \. The neighbor -address can be an IPv4 address or an IPv6 address or an interface to use -for the connection. The command is applicable for peer and peer group. -``` - - -```{cfgcmd} set protocols bgp neighbor \ remote-as internal - -Create a peer as you would when you specify an ASN, except that if the -peers ASN is different than mine as specified under the {cfgcmd}`protocols -bgp ` command the connection will be denied. -``` - - -```{cfgcmd} set protocols bgp neighbor \ remote-as external - -Create a peer as you would when you specify an ASN, except that if the -peers ASN is the same as mine as specified under the {cfgcmd}`protocols -bgp ` command the connection will be denied. -``` - - -```{cfgcmd} set protocols bgp neighbor \ remote-as auto - -Create a peer as you would when you specify an ASN, except that the peers -remote ASN is detected automatically from the OPEN message. -``` - - -```{cfgcmd} set protocols bgp neighbor \ local-role \ [strict] - -BGP roles are defined in RFC {rfc}`9234` and provide an easy way to -add route leak prevention, detection and mitigation. The local Role -value is negotiated with the new BGP Role capability which has a -built-in check of the corresponding value. In case of a mismatch the -new OPEN Roles Mismatch Notification <2, 11> would be sent. -The correct Role pairs are: - -Provider - Customer - -Peer - Peer - -RS-Server - RS-Client - -If {cfgcmd}`strict` is set the BGP session won’t become established -until the BGP neighbor sets local Role on its side. This -configuration parameter is defined in RFC {rfc}`9234` and is used to -enforce the corresponding configuration at your counter-parts side. - -Routes that are sent from provider, rs-server, or the peer local-role -(or if received by customer, rs-client, or the peer local-role) will -be marked with a new Only to Customer (OTC) attribute. - -Routes with this attribute can only be sent to your neighbor if your -local-role is provider or rs-server. Routes with this attribute can -be received only if your local-role is customer or rs-client. - -In case of peer-peer relationship routes can be received only if OTC -value is equal to your neighbor AS number. - -All these rules with OTC will help to detect and mitigate route leaks -and happen automatically if local-role is set. -``` - - -```{cfgcmd} set protocols bgp neighbor \ shutdown - -This command disable the peer or peer group. To reenable the peer use -the delete form of this command. -``` - - -```{cfgcmd} set protocols bgp neighbor \ description \ - -Set description of the peer or peer group. -``` - - -```{cfgcmd} set protocols bgp neighbor \ update-source \ - -Specify the IPv4 source address to use for the BGP session to this neighbor, -may be specified as either an IPv4 address directly or as an interface name. -``` - -(bgp-capability-negotiation-1)= - - -##### Capability Negotiation - -```{cfgcmd} set protocols bgp neighbor \ capability dynamic - -This command would allow the dynamic update of capabilities over an -established BGP session. -``` - - -```{cfgcmd} set protocols bgp neighbor \ capability extended-nexthop - -Allow bgp to negotiate the extended-nexthop capability with it’s peer. -If you are peering over a IPv6 Link-Local address then this capability -is turned on automatically. If you are peering over a IPv6 Global Address -then turning on this command will allow BGP to install IPv4 routes with -IPv6 nexthops if you do not have IPv4 configured on interfaces. -``` - - -```{cfgcmd} set protocols bgp neighbor \ disable-capability-negotiation - -Suppress sending Capability Negotiation as OPEN message optional -parameter to the peer. This command only affects the peer is -configured other than IPv4 unicast configuration. - -When remote peer does not have capability negotiation feature, -remote peer will not send any capabilities at all. In that case, -bgp configures the peer with configured capabilities. - -You may prefer locally configured capabilities more than the negotiated -capabilities even though remote peer sends capabilities. If the peer is -configured by {cfgcmd}`override-capability`, VyOS ignores received -capabilities then override negotiated capabilities with configured values. - -Additionally you should keep in mind that this feature fundamentally -disables the ability to use widely deployed BGP features. BGP unnumbered, -hostname support, AS4, Addpath, Route Refresh, ORF, Dynamic Capabilities, -and graceful restart. -``` - - -```{cfgcmd} set protocols bgp neighbor \ override-capability - -This command allow override the result of Capability Negotiation with -local configuration. Ignore remote peer’s capability value. -``` - - -```{cfgcmd} set protocols bgp neighbor \ strict-capability-match - -This command forces strictly compare remote capabilities and local -capabilities. If capabilities are different, send Unsupported Capability -error then reset connection. - -You may want to disable sending Capability Negotiation OPEN message -optional parameter to the peer when remote peer does not implement -Capability Negotiation. Please use {cfgcmd}`disable-capability-negotiation` -command to disable the feature. -``` - -##### Peer Parameters - -```{cfgcmd} set protocols bgp neighbor \ address-family \ allowas-in number \ - -This command accept incoming routes with AS path containing AS -number with the same value as the current system AS. This is -used when you want to use the same AS number in your sites, -but you can’t connect them directly. - - The number parameter (1-10) configures the amount of accepted - occurences of the system AS number in AS path. - - This command is only allowed for eBGP peers. It is not applicable - for peer groups. -``` - - -```{cfgcmd} set protocols bgp neighbor \ address-family \ as-override - -This command override AS number of the originating router with -the local AS number. - -Usually this configuration is used in PEs (Provider Edge) to -replace the incoming customer AS number so the connected CE ( -Customer Edge) can use the same AS number as the other customer -sites. This allows customers of the provider network to use the -same AS number across their sites. - -This command is only allowed for eBGP peers. -``` - - -```{cfgcmd} set protocols bgp neighbor \ address-family \ attribute-unchanged \ - -This command specifies attributes to be left unchanged for -advertisements sent to a peer or peer group. -``` - - -```{cfgcmd} set protocols bgp neighbor \ address-family \ maximum-prefix \ - -This command specifies a maximum number of prefixes we can receive -from a given peer. If this number is exceeded, the BGP session -will be destroyed. The number range is 1 to 4294967295. -``` - - -```{cfgcmd} set protocols bgp neighbor \ address-family \ nexthop-self - -This command forces the BGP speaker to report itself as the -next hop for an advertised route it advertised to a neighbor. -``` - - -```{cfgcmd} set protocols bgp neighbor \ address-family \ remove-private-as - -This command removes the private ASN of routes that are advertised -to the configured peer. It removes only private ASNs on routes -advertised to EBGP peers. - -If the AS-Path for the route has only private ASNs, the private -ASNs are removed. - -If the AS-Path for the route has a private ASN between public -ASNs, it is assumed that this is a design choice, and the -private ASN is not removed. -``` - - -```{cfgcmd} set protocols bgp neighbor \ address-family \ soft-reconfiguration inbound - -Changes in BGP policies require the BGP session to be cleared. Clearing has a -large negative impact on network operations. Soft reconfiguration enables you -to generate inbound updates from a neighbor, change and activate BGP policies -without clearing the BGP session. - -This command specifies that route updates received from this neighbor will be -stored unmodified, regardless of the inbound policy. When inbound soft -reconfiguration is enabled, the stored updates are processed by the new -policy configuration to create new inbound updates. - -:::{note} -Storage of route updates uses memory. If you enable soft -reconfiguration inbound for multiple neighbors, the amount of memory used -can become significant. -::: -``` - - -```{cfgcmd} set protocols bgp neighbor \ address-family \ weight \ - -This command specifies a default weight value for the neighbor’s -routes. The number range is 1 to 65535. -``` - - -```{cfgcmd} set protocols bgp neighbor \ advertisement-interval \ - -This command specifies the minimum route advertisement interval for -the peer. The interval value is 0 to 600 seconds, with the default -advertisement interval being 0. -``` - - -```{cfgcmd} set protocols bgp neighbor \ disable-connected-check - -This command allows peerings between directly connected eBGP peers -using loopback addresses without adjusting the default TTL of 1. -``` - - -```{cfgcmd} set protocols bgp neighbor \ disable-send-community \ - -This command specifies that the community attribute should not be sent -in route updates to a peer. By default community attribute is sent. -``` - - -```{cfgcmd} set protocols bgp neighbor \ ebgp-multihop \ - -This command allows sessions to be established with eBGP neighbors -when they are multiple hops away. When the neighbor is not directly -connected and this knob is not enabled, the session will not establish. -The number of hops range is 1 to 255. This command is mutually -exclusive with {cfgcmd}`ttl-security hops`. -``` - - -```{cfgcmd} set protocols bgp neighbor \ local-as \ [no-prepend] [replace-as] - -Specify an alternate AS for this BGP process when interacting with -the specified peer or peer group. With no modifiers, the specified -local-as is prepended to the received AS_PATH when receiving routing -updates from the peer, and prepended to the outgoing AS_PATH (after -the process local AS) when transmitting local routes to the peer. - -If the {cfgcmd}`no-prepend` attribute is specified, then the supplied -local-as is not prepended to the received AS_PATH. - -If the {cfgcmd}`replace-as` attribute is specified, then only the supplied -local-as is prepended to the AS_PATH when transmitting local-route -updates to this peer. - -:::{note} -This command is only allowed for eBGP peers. -::: -``` - - -```{cfgcmd} set protocols bgp neighbor \ passive - -Configures the BGP speaker so that it only accepts inbound connections -from, but does not initiate outbound connections to the peer or peer group. -``` - - -```{cfgcmd} set protocols bgp neighbor \ password \ - -This command specifies a MD5 password to be used with the tcp socket that -is being used to connect to the remote peer. -``` - - -```{cfgcmd} set protocols bgp neighbor \ ttl-security hops \ - -This command enforces Generalized TTL Security Mechanism (GTSM), -as specified in {rfc}`5082`. With this command, only neighbors -that are specified number of hops away will be allowed to -become neighbors. The number of hops range is 1 to 254. This -command is mutually exclusive with {cfgcmd}`ebgp-multihop`. -``` - -##### Peer Groups - -Peer groups are used to help improve scaling by generating the same update -information to all members of a peer group. Note that this means that the -routes generated by a member of a peer group will be sent back to that -originating peer with the originator identifier attribute set to indicated -the originating peer. All peers not associated with a specific peer group -are treated as belonging to a default peer group, and will share updates. - -```{cfgcmd} set protocols bgp peer-group \ - - This command defines a new peer group. You can specify to the group the same - parameters that you can specify for specific neighbors. - - :::{note} - If you apply a parameter to an individual neighbor IP address, you - override the action defined for a peer group that includes that IP - address. - ::: -``` - - -```{cfgcmd} set protocols bgp neighbor \ peer-group \ - -This command bind specific peer to peer group with a given name. -``` - -#### Network Advertisement Configuration - -```{cfgcmd} set protocols bgp address-family \ network \ - -This command is used for advertising IPv4 or IPv6 networks. - - :::{note} - By default, the BGP prefix is advertised even if it's not present - in the routing table. This behaviour differs from the implementation of - some vendors. - ::: -``` - - -```{cfgcmd} set protocols bgp parameters network-import-check - -This configuration modifies the behavior of the network statement. If you -have this configured the underlying network must exist in the routing table. -``` - - -```{cfgcmd} set protocols bgp neighbor \ address-family \ default-originate [route-map \] - -By default, VyOS does not advertise a default route (0.0.0.0/0) even if it is -in routing table. When you want to announce default routes to the peer, use -this command. Using optional argument {cfgcmd}`route-map` you can inject the -default route to given neighbor only if the conditions in the route map are -met. -``` - -#### Route Aggregation Configuration - -```{cfgcmd} set protocols bgp address-family \ aggregate-address \ - -This command specifies an aggregate address. The router will also -announce longer-prefixes inside of the aggregate address. -``` - - -```{cfgcmd} set protocols bgp address-family \ aggregate-address \ as-set - -This command specifies an aggregate address with a mathematical set of -autonomous systems. This command summarizes the AS_PATH attributes of -all the individual routes. -``` - - -```{cfgcmd} set protocols bgp address-family \ aggregate-address \ summary-only - -This command specifies an aggregate address and provides that -longer-prefixes inside of the aggregate address are suppressed -before sending BGP updates out to peers. -``` - - -```{cfgcmd} set protocols bgp neighbor \ address-family \ unsuppress-map \ - -This command applies route-map to selectively unsuppress prefixes -suppressed by summarisation. -``` - -#### Redistribution Configuration - -```{cfgcmd} set protocols bgp address-family \ redistribute - -This command redistributes routing information from the given route source -to the BGP process. There are six modes available for route source: -connected, kernel, ospf, rip, static, table. -``` - - -```{cfgcmd} set protocols bgp address-family \ redistribute metric \ - -This command specifies metric (MED) for redistributed routes. The -metric range is 0 to 4294967295. There are six modes available for -route source: connected, kernel, ospf, rip, static, table. -``` - - -```{cfgcmd} set protocols bgp address-family \ redistribute route-map \ - -This command allows to use route map to filter redistributed routes. -There are six modes available for route source: connected, kernel, -ospf, rip, static, table. -``` - -#### General Configuration -##### Common parameters - -```{cfgcmd} set protocols bgp parameters allow-martian-nexthop - - When a peer receives a martian nexthop as part of the NLRI for a route - permit the nexthop to be used as such, instead of rejecting and resetting - the connection. -``` - - -```{cfgcmd} set protocols bgp parameters router-id \ - -This command specifies the router-ID. If router ID is not specified it will -use the highest interface IP address. -``` - - -```{cfgcmd} set protocols bgp address-family \ maximum-paths \ \ - -This command defines the maximum number of parallel routes that -the BGP can support. In order for BGP to use the second path, the -following attributes have to match: Weight, Local Preference, AS -Path (both AS number and AS path length), Origin code, MED, IGP -metric. Also, the next hop address for each path must be different. -``` - - -```{cfgcmd} set protocols bgp parameters no-hard-administrative-reset - -Do not send Hard Reset CEASE Notification for "Administrative Reset" -events. When set and Graceful Restart Notification capability is exchanged -between the peers, Graceful Restart procedures apply, and routes will be retained. -``` - - -```{cfgcmd} set protocols bgp parameters log-neighbor-changes - -This command enable logging neighbor up/down changes and reset reason. -``` - - -```{cfgcmd} set protocols bgp parameters no-client-to-client-reflection - -This command disables route reflection between route reflector clients. -By default, the clients of a route reflector are not required to be -fully meshed and the routes from a client are reflected to other clients. -However, if the clients are fully meshed, route reflection is not required. -In this case, use the {cfgcmd}`no-client-to-client-reflection` command -to disable client-to-client reflection. -``` - - -```{cfgcmd} set protocols bgp parameters no-fast-external-failover - -Disable immediate session reset if peer's connected link goes down. -``` - - -```{cfgcmd} set protocols bgp parameters no-ipv6-auto-ra - -By default, FRR sends router advertisement packets when Extended Next Hop is -on or when a connection is established directly using the device name (Unnumbered BGP). -Setting this option prevents FRR from sending router advertisement packets, but could break Unnumbered BGP. -``` - - -```{cfgcmd} set protocols bgp listen range \ peer-group \ - -This command is useful if one desires to loosen the requirement for BGP -to have strictly defined neighbors. Specifically what is allowed is for -the local router to listen to a range of IPv4 or IPv6 addresses defined -by a prefix and to accept BGP open messages. When a TCP connection -(and subsequently a BGP open message) from within this range tries to -connect the local router then the local router will respond and connect -with the parameters that are defined within the peer group. One must define -a peer-group for each range that is listed. If no peer-group is defined -then an error will keep you from committing the configuration. -``` - - -```{cfgcmd} set protocols bgp listen limit \ - -This command goes hand in hand with the listen range command to limit the -amount of BGP neighbors that are allowed to connect to the local router. -The limit range is 1 to 5000. -``` - - -```{cfgcmd} set protocols bgp parameters ebgp-requires-policy - -This command changes the eBGP behavior of FRR. By default FRR enables -{rfc}`8212` functionality which affects how eBGP routes are advertised, -namely no routes are advertised across eBGP sessions without some -sort of egress route-map/policy in place. In VyOS however we have this -RFC functionality disabled by default so that we can preserve backwards -compatibility with older versions of VyOS. With this option one can -enable {rfc}`8212` functionality to operate. -``` - - -```{cfgcmd} set protocols bgp parameters labeled-unicast \ - -By default, locally advertised prefixes use the implicit-null label to -encode in the outgoing NLRI. - -The following command uses the explicit-null label value for all the -BGP instances. -``` - -##### Administrative Distance - -```{cfgcmd} set protocols bgp parameters distance global \ \ - -This command change distance value of BGP. The arguments are the distance -values for external routes, internal routes and local routes respectively. -The distance range is 1 to 255. -``` - - -```{cfgcmd} set protocols bgp parameters distance prefix \ distance \ - -This command sets the administrative distance for a particular route. The -distance range is 1 to 255. - -:::{note} -Routes with a distance of 255 are effectively disabled and not -installed into the kernel. -::: -``` - -##### Timers - -```{cfgcmd} set protocols bgp timers holdtime \ - - This command specifies hold-time in seconds. The timer range is - 4 to 65535. The default value is 180 second. If you set value to 0 - VyOS will not hold routes. -``` - - -```{cfgcmd} set protocols bgp timers keepalive \ - -This command specifies keep-alive time in seconds. The timer -can range from 4 to 65535. The default value is 60 second. -``` - -##### Route Dampening - -When a route fails, a routing update is sent to withdraw the route from the -network's routing tables. When the route is re-enabled, the change in -availability is also advertised. A route that continually fails and returns -requires a great deal of network traffic to update the network about the -route's status. - -Route dampening wich described in {rfc}`2439` enables you to identify routes -that repeatedly fail and return. If route dampening is enabled, an unstable -route accumulates penalties each time the route fails and returns. If the -accumulated penalties exceed a threshold, the route is no longer advertised. -This is route suppression. Routes that have been suppressed are re-entered -into the routing table only when the amount of their penalty falls below a -threshold. - -A penalty of 1000 is assessed each time the route fails. When the penalties -reach a predefined threshold (suppress-value), the router stops advertising -the route. - -Once a route is assessed a penalty, the penalty is decreased by half each time -a predefined amount of time elapses (half-life-time). When the accumulated -penalties fall below a predefined threshold (reuse-value), the route is -unsuppressed and added back into the BGP routing table. - -No route is suppressed indefinitely. Maximum-suppress-time defines the maximum -time a route can be suppressed before it is re-advertised. - -```{cfgcmd} set protocols bgp parameters dampening half-life \ - -This command defines the amount of time in minutes after -which a penalty is reduced by half. The timer range is -10 to 45 minutes. -``` - - -```{cfgcmd} set protocols bgp parameters dampening re-use \ - -This command defines the accumulated penalty amount at which the -route is re-advertised. The penalty range is 1 to 20000. -``` - - -```{cfgcmd} set protocols bgp parameters dampening start-suppress-time \ - -This command defines the accumulated penalty amount at which the -route is suppressed. The penalty range is 1 to 20000. -``` - - -```{cfgcmd} set protocols bgp parameters dampening max-suppress-time \ - -This command defines the maximum time in minutes that a route is -suppressed. The timer range is 1 to 255 minutes. -``` - -#### Route Selection Configuration - -```{cfgcmd} set protocols bgp parameters always-compare-med - - This command provides to compare the MED on routes, even when they were - received from different neighbouring ASes. Setting this option makes the - order of preference of routes more defined, and should eliminate MED - induced oscillations. -``` - - -```{cfgcmd} set protocols bgp parameters bestpath as-path confed - -This command specifies that the length of confederation path sets and -sequences should be taken into account during the BGP best path -decision process. -``` - - -```{cfgcmd} set protocols bgp parameters bestpath as-path multipath-relax - -This command specifies that BGP decision process should consider paths -of equal AS_PATH length candidates for multipath computation. Without -the knob, the entire AS_PATH must match for multipath computation. -``` - - -```{cfgcmd} set protocols bgp parameters bestpath as-path ignore - -Ignore AS_PATH length when selecting a route -``` - - -```{cfgcmd} set protocols bgp parameters bestpath compare-routerid - -Ensure that when comparing routes where both are equal on most metrics, -including local-pref, AS_PATH length, IGP cost, MED, that the tie is -broken based on router-ID. - -If this option is enabled, then the already-selected check, where -already selected eBGP routes are preferred, is skipped. - -If a route has an ORIGINATOR_ID attribute because it has been reflected, -that ORIGINATOR_ID will be used. Otherwise, the router-ID of the peer -the route was received from will be used. - -The advantage of this is that the route-selection (at this point) will -be more deterministic. The disadvantage is that a few or even one lowest-ID -router may attract all traffic to otherwise-equal paths because of this -check. It may increase the possibility of MED or IGP oscillation, unless -other measures were taken to avoid these. The exact behaviour will be -sensitive to the iBGP and reflection topology. -``` - - -```{cfgcmd} set protocols bgp parameters bestpath med confed - -This command specifies that BGP considers the MED when comparing routes -originated from different sub-ASs within the confederation to which this -BGP speaker belongs. The default state, where the MED attribute is not -considered. -``` - - -```{cfgcmd} set protocols bgp parameters bestpath med missing-as-worst - -This command specifies that a route with a MED is always considered to be -better than a route without a MED by causing the missing MED attribute to -have a value of infinity. The default state, where the missing MED -attribute is considered to have a value of zero. -``` - - -```{cfgcmd} set protocols bgp parameters default local-pref - -This command specifies the default local preference value. The local -preference range is 0 to 4294967295. -``` - - -```{cfgcmd} set protocols bgp parameters deterministic-med - -This command provides to compare different MED values that advertised by -neighbours in the same AS for routes selection. When this command is -enabled, routes from the same autonomous system are grouped together, and -the best entries of each group are compared. -``` - - -```{cfgcmd} set protocols bgp address-family ipv4-unicast network \ backdoor - -This command allows the router to prefer route to specified prefix learned -via IGP through backdoor link instead of a route to the same prefix learned -via EBGP. -``` - -#### Route Filtering Configuration - -In order to control and modify routing information that is exchanged between -peers you can use route-map, filter-list, prefix-list, distribute-list. - -For inbound updates the order of preference is: - -> - route-map -> - filter-list -> - prefix-list, distribute-list - -For outbound updates the order of preference is: -> - prefix-list, distribute-list -> - filter-list -> - route-map -> -> :::{note} -> The attributes {cfgcmd}`prefix-list` and {cfgcmd}`distribute-list` -> are mutually exclusive, and only one command (distribute-list or -> prefix-list) can be applied to each inbound or outbound direction for a -> particular neighbor. -> ::: - -```{cfgcmd} set protocols bgp neighbor \ address-family \ distribute-list \ \ - -This command applies the access list filters named in \ to the -specified BGP neighbor to restrict the routing information that BGP learns -and/or advertises. The arguments {cfgcmd}`export` and {cfgcmd}`import` -specify the direction in which the access list are applied. -``` - - -```{cfgcmd} set protocols bgp neighbor \ address-family \ prefix-list \ \ - -This command applies the prfefix list filters named in \ to the -specified BGP neighbor to restrict the routing information that BGP learns -and/or advertises. The arguments {cfgcmd}`export` and {cfgcmd}`import` -specify the direction in which the prefix list are applied. -``` - - -```{cfgcmd} set protocols bgp neighbor \ address-family \ route-map \ \ - -This command applies the route map named in \ to the specified BGP -neighbor to control and modify routing information that is exchanged -between peers. The arguments {cfgcmd}`export` and {cfgcmd}`import` -specify the direction in which the route map are applied. -``` - - -```{cfgcmd} set protocols bgp neighbor \ address-family \ filter-list \ \ - -This command applies the AS path access list filters named in \ to the -specified BGP neighbor to restrict the routing information that BGP learns -and/or advertises. The arguments {cfgcmd}`export` and {cfgcmd}`import` -specify the direction in which the AS path access list are applied. -``` - - -```{cfgcmd} set protocols bgp neighbor \ address-family \ capability orf \ - -This command enables the ORF capability (described in {rfc}`5291`) on the -local router, and enables ORF capability advertisement to the specified BGP -peer. The {cfgcmd}`receive` keyword configures a router to advertise ORF -receive capabilities. The {cfgcmd}`send` keyword configures a router to -advertise ORF send capabilities. To advertise a filter from a sender, you -must create an IP prefix list for the specified BGP peer applied in inbound -derection. -``` - - -```{cfgcmd} set protocols bgp neighbor \ solo - -This command prevents from sending back prefixes learned from the neighbor. -``` - -#### BGP Scaling Configuration - - -BGP routers connected inside the same AS through BGP belong to an internal BGP -session, or IBGP. In order to prevent routing table loops, IBGP speaker does -not advertise IBGP-learned routes to other IBGP speaker (Split Horizon -mechanism). As such, IBGP requires a full mesh of all peers. For large -networks, this quickly becomes unscalable. - - -There are two ways that help us to mitigate the BGPs full-mesh requirement in -a network: - - -> - Using BGP route-reflectors -> - Using BGP confederation - - -##### Route Reflector Configuration - - -Introducing route reflectors removes the need for the full-mesh. When you -configure a route reflector you have to tell the router whether the other IBGP -router is a client or non-client. A client is an IBGP router that the route -reflector will “reflect” routes to, the non-client is just a regular IBGP -neighbor. Route reflectors mechanism is described in {rfc}`4456` and updated -by {rfc}`7606`. - -```{cfgcmd} set protocols bgp neighbor \ address-family \ route-reflector-client - -This command specifies the given neighbor as route reflector client. -``` - - -```{cfgcmd} set protocols bgp parameters cluster-id \ - -This command specifies cluster ID which identifies a collection of route -reflectors and their clients, and is used by route reflectors to avoid -looping. By default cluster ID is set to the BGP router id value, but can be -set to an arbitrary 32-bit value. -``` - -##### Confederation Configuration - -A BGP confederation divides our AS into sub-ASes to reduce the number of -required IBGP peerings. Within a sub-AS we still require full-mesh IBGP but -between these sub-ASes we use something that looks like EBGP but behaves like -IBGP (called confederation BGP). Confederation mechanism is described in -{rfc}`5065` - -```{cfgcmd} set protocols bgp parameters confederation identifier \ - -This command specifies a BGP confederation identifier. \ is the number -of the autonomous system that internally includes multiple sub-autonomous -systems (a confederation). -``` - - -```{cfgcmd} set protocols bgp parameters confederation peers \ - -This command sets other confederations \ as members of autonomous -system specified by {cfgcmd}`confederation identifier `. -``` - -## Operational Mode Commands -### Show - -```{opcmd} show bgp \ - - This command displays all entries in BGP routing table. -``` - - -```none -BGP table version is 10, local router ID is 10.0.35.3, vrf id 0 -Default local pref 100, local AS 65000 -Status codes: s suppressed, d damped, h history, * valid, > best, = multipath, - i internal, r RIB-failure, S Stale, R Removed -Nexthop codes: @NNN nexthop's vrf id, < announce-nh-self -Origin codes: i - IGP, e - EGP, ? - incomplete -RPKI validation codes: V valid, I invalid, N Not found - - Network Next Hop Metric LocPrf Weight Path -*> 198.51.100.0/24 10.0.34.4 0 0 65004 i -*> 203.0.113.0/24 10.0.35.5 0 0 65005 i - -Displayed 2 routes and 2 total paths -``` - - -```{opcmd} show bgp \ \ - -This command displays information about the particular entry in the BGP -routing table. -``` - - -```none -BGP routing table entry for 198.51.100.0/24 -Paths: (1 available, best #1, table default) - Advertised to non peer-group peers: - 10.0.13.1 10.0.23.2 10.0.34.4 10.0.35.5 - 65004 - 10.0.34.4 from 10.0.34.4 (10.0.34.4) - Origin IGP, metric 0, valid, external, best (First path received) - Last update: Wed Jan 6 12:18:53 2021 -``` - - -```{opcmd} show bgp cidr-only - -This command displays routes with classless interdomain routing (CIDR). -``` - - -```{opcmd} show bgp \ community \ - -This command displays routes that belong to specified BGP communities. -Valid value is a community number in the range from 1 to 4294967200, -or AA:NN (autonomous system-community number/2-byte number), no-export, -local-as, or no-advertise. -``` - - -```{opcmd} show bgp \ community-list \ - -This command displays routes that are permitted by the BGP -community list. -``` - - -```{opcmd} show bgp \ dampening dampened-paths - -This command displays BGP dampened routes. -``` - - -```{opcmd} show bgp \ dampening flap-statistics - -This command displays information about flapping BGP routes. -``` - - -```{opcmd} show bgp \ filter-list \ - -This command displays BGP routes allowed by the specified AS Path -access list. -``` - - -```{opcmd} show bgp \ neighbors \ advertised-routes - -This command displays BGP routes advertised to a neighbor. -``` - - -```{opcmd} show bgp \ neighbors \ received-routes - -This command displays BGP routes originating from the specified BGP -neighbor before inbound policy is applied. To use this command inbound -soft reconfiguration must be enabled. -``` - - -```{opcmd} show bgp \ neighbors \ routes - -This command displays BGP received-routes that are accepted after filtering. -``` - - -```{opcmd} show bgp \ neighbors \ dampened-routes - -This command displays dampened routes received from BGP neighbor. -``` - - -```{opcmd} show bgp \ regexp \ - -This command displays information about BGP routes whose AS path -matches the specified regular expression. -``` - - -```{opcmd} show bgp \ summary - -This command displays the status of all BGP connections. -``` - - -```none -IPv4 Unicast Summary: -BGP router identifier 10.0.35.3, local AS number 65000 vrf-id 0 -BGP table version 11 -RIB entries 5, using 920 bytes of memory -Peers 4, using 82 KiB of memory - -Neighbor V AS MsgRcvd MsgSent TblVer InQ OutQ Up/Down State/PfxRcd -10.0.13.1 4 65000 148 159 0 0 0 02:16:01 0 -10.0.23.2 4 65000 136 143 0 0 0 02:13:21 0 -10.0.34.4 4 65004 161 163 0 0 0 02:16:01 1 -10.0.35.5 4 65005 162 166 0 0 0 02:16:01 1 - -Total number of neighbors 4 -``` - -### Reset - -```{opcmd} reset bgp \ \ [soft [in|out]] - -This command resets BGP connections to the specified neighbor IP address. -With argument {cfgcmd}`soft` this command initiates a soft reset. If -you do not specify the {cfgcmd}`in` or {cfgcmd}`out` options, both -inbound and outbound soft reconfiguration are triggered. -``` - - -```{opcmd} reset bgp all - -This command resets all BGP connections of given router. -``` - - -```{opcmd} reset bgp \ external - -This command resets all external BGP peers of given router. -``` - - -```{opcmd} reset bgp \ peer-group \ [soft [in|out]] - -This command resets BGP connections to the specified peer group. -With argument {cfgcmd}`soft` this command initiates a soft reset. If -you do not specify the {cfgcmd}`in` or {cfgcmd}`out` options, both -inbound and outbound soft reconfiguration are triggered. -``` - -## Examples -### IPv4 peering - -A simple eBGP configuration: - -**Node 1:** - -```none -set protocols bgp system-as 65534 -set protocols bgp neighbor 192.168.0.2 ebgp-multihop '2' -set protocols bgp neighbor 192.168.0.2 remote-as '65535' -set protocols bgp neighbor 192.168.0.2 update-source '192.168.0.1' -set protocols bgp neighbor 192.168.0.2 address-family ipv4-unicast -set protocols bgp address-family ipv4-unicast network '172.16.0.0/16' -set protocols bgp parameters router-id '192.168.0.1' -``` - -**Node 2:** - -```none -set protocols bgp system-as 65535 -set protocols bgp neighbor 192.168.0.1 ebgp-multihop '2' -set protocols bgp neighbor 192.168.0.1 remote-as '65534' -set protocols bgp neighbor 192.168.0.1 update-source '192.168.0.2' -set protocols bgp neighbor 192.168.0.1 address-family ipv4-unicast -set protocols bgp address-family ipv4-unicast network '172.17.0.0/16' -set protocols bgp parameters router-id '192.168.0.2' -``` - -Don't forget, the CIDR declared in the network statement MUST **exist in your -routing table (dynamic or static), the best way to make sure that is true is -creating a static route:** - -**Node 1:** - -```none -set protocols static route 172.16.0.0/16 blackhole distance '254' -``` - -**Node 2:** - -```none -set protocols static route 172.17.0.0/16 blackhole distance '254' -``` - -### IPv6 peering - -A simple BGP configuration via IPv6. - -**Node 1:** - -```none -set protocols bgp system-as 65534 -set protocols bgp neighbor 2001:db8::2 ebgp-multihop '2' -set protocols bgp neighbor 2001:db8::2 remote-as '65535' -set protocols bgp neighbor 2001:db8::2 update-source '2001:db8::1' -set protocols bgp neighbor 2001:db8::2 address-family ipv6-unicast -set protocols bgp address-family ipv6-unicast network '2001:db8:1::/48' -set protocols bgp parameters router-id '10.1.1.1' -``` - -**Node 2:** - -```none -set protocols bgp system-as 65535 -set protocols bgp neighbor 2001:db8::1 ebgp-multihop '2' -set protocols bgp neighbor 2001:db8::1 remote-as '65534' -set protocols bgp neighbor 2001:db8::1 update-source '2001:db8::2' -set protocols bgp neighbor 2001:db8::1 address-family ipv6-unicast -set protocols bgp address-family ipv6-unicast network '2001:db8:2::/48' -set protocols bgp parameters router-id '10.1.1.2' -``` - -Don't forget, the CIDR declared in the network statement **MUST exist in your -routing table (dynamic or static), the best way to make sure that is true is -creating a static route:** - -**Node 1:** - -```none -set protocols static route6 2001:db8:1::/48 blackhole distance '254' -``` - -**Node 2:** - -```none -set protocols static route6 2001:db8:2::/48 blackhole distance '254' -``` - -### Route Filtering - -Route filter can be applied using a route-map: - -**Node1:** - -```none -set policy prefix-list AS65535-IN rule 10 action 'permit' -set policy prefix-list AS65535-IN rule 10 prefix '172.16.0.0/16' -set policy prefix-list AS65535-OUT rule 10 action 'deny' -set policy prefix-list AS65535-OUT rule 10 prefix '172.16.0.0/16' -set policy prefix-list6 AS65535-IN rule 10 action 'permit' -set policy prefix-list6 AS65535-IN rule 10 prefix '2001:db8:2::/48' -set policy prefix-list6 AS65535-OUT rule 10 action 'deny' -set policy prefix-list6 AS65535-OUT rule 10 prefix '2001:db8:2::/48' - -set policy route-map AS65535-IN rule 10 action 'permit' -set policy route-map AS65535-IN rule 10 match ip address prefix-list 'AS65535-IN' -set policy route-map AS65535-IN rule 10 match ipv6 address prefix-list 'AS65535-IN' -set policy route-map AS65535-IN rule 20 action 'deny' -set policy route-map AS65535-OUT rule 10 action 'deny' -set policy route-map AS65535-OUT rule 10 match ip address prefix-list 'AS65535-OUT' -set policy route-map AS65535-OUT rule 10 match ipv6 address prefix-list 'AS65535-OUT' -set policy route-map AS65535-OUT rule 20 action 'permit' - -set protocols bgp system-as 65534 -set protocols bgp neighbor 2001:db8::2 address-family ipv4-unicast route-map export 'AS65535-OUT' -set protocols bgp neighbor 2001:db8::2 address-family ipv4-unicast route-map import 'AS65535-IN' -set protocols bgp neighbor 2001:db8::2 address-family ipv6-unicast route-map export 'AS65535-OUT' -set protocols bgp neighbor 2001:db8::2 address-family ipv6-unicast route-map import 'AS65535-IN' -``` - -**Node2:** - -```none -set policy prefix-list AS65534-IN rule 10 action 'permit' -set policy prefix-list AS65534-IN rule 10 prefix '172.17.0.0/16' -set policy prefix-list AS65534-OUT rule 10 action 'deny' -set policy prefix-list AS65534-OUT rule 10 prefix '172.17.0.0/16' -set policy prefix-list6 AS65534-IN rule 10 action 'permit' -set policy prefix-list6 AS65534-IN rule 10 prefix '2001:db8:1::/48' -set policy prefix-list6 AS65534-OUT rule 10 action 'deny' -set policy prefix-list6 AS65534-OUT rule 10 prefix '2001:db8:1::/48' - -set policy route-map AS65534-IN rule 10 action 'permit' -set policy route-map AS65534-IN rule 10 match ip address prefix-list 'AS65534-IN' -set policy route-map AS65534-IN rule 10 match ipv6 address prefix-list 'AS65534-IN' -set policy route-map AS65534-IN rule 20 action 'deny' -set policy route-map AS65534-OUT rule 10 action 'deny' -set policy route-map AS65534-OUT rule 10 match ip address prefix-list 'AS65534-OUT' -set policy route-map AS65534-OUT rule 10 match ipv6 address prefix-list 'AS65534-OUT' -set policy route-map AS65534-OUT rule 20 action 'permit' - -set protocols bgp system-as 65535 -set protocols bgp neighbor 2001:db8::1 address-family ipv4-unicast route-map export 'AS65534-OUT' -set protocols bgp neighbor 2001:db8::1 address-family ipv4-unicast route-map import 'AS65534-IN' -set protocols bgp neighbor 2001:db8::1 address-family ipv6-unicast route-map export 'AS65534-OUT' -set protocols bgp neighbor 2001:db8::1 address-family ipv6-unicast route-map import 'AS65534-IN' -``` - -We could expand on this and also deny link local and multicast in the rule 20 -action deny. diff --git a/docs/configuration/protocols/md-failover.md b/docs/configuration/protocols/md-failover.md deleted file mode 100644 index 96374d11..00000000 --- a/docs/configuration/protocols/md-failover.md +++ /dev/null @@ -1,237 +0,0 @@ ---- -description: |- - Failover routes are static routes that are installed in the routing - table only while a configured health-check target responds. VyOS uses them - to switch traffic to a backup path when the primary next hop becomes - unreachable, and to restore the primary path automatically once it recovers. -keywords: |- - failover, failover route, static route, health check, icmp probe, - next hop, route metric ---- - -# Failover - -Failover routes are manually configured network paths used only while their -health-check targets are reachable. If the target stops responding, VyOS -removes the route from the routing table and reinstalls it once the target -recovers. - -## Configuration - -Use the following commands to configure failover routes for a specific remote -`` reachable via next-hop `
`. - -```{eval-rst} -.. cfgcmd:: set protocols failover route next-hop
check target - - **Configure the health check target IP address.** - - This is typically a highly available host, either within the destination - subnet or on the public internet. - - Example: - - .. code-block:: none - - set protocols failover route 203.0.113.1/32 next-hop 10.217.37.254 check target 8.8.8.8 -``` - -```{eval-rst} -.. cfgcmd:: set protocols failover route next-hop
check timeout - - **Configure the timeout interval, in seconds, between target health checks.** - - The valid range is 1 to 300 seconds. The default is 10 seconds. - - Example: - - .. code-block:: none - - set protocols failover route 203.0.113.1/32 next-hop 10.217.37.254 check timeout 2 -``` - -```{eval-rst} -.. cfgcmd:: set protocols failover route next-hop
check type - - **Configure the protocol to use for health checks.** - - The following protocols are available: - - * ``icmp``: VyOS sends two ICMP echo request packets with a 1-second - response timeout. The health check is successful if at least one response - is received. - * ``arp``: VyOS sends two ARP requests with a 1-second response timeout. - The health check is successful if at least one response is received. - * ``tcp``: VyOS verifies whether the destination TCP port is open. The - health check is successful if a TCP connection is successfully - established with the target port. - - The default protocol is ``icmp``. - - .. note:: - - When the check type is set to ``tcp``, you must also define the target - TCP port. - - Example: - - .. code-block:: none - - set protocols failover route 203.0.113.1/32 next-hop 10.217.37.254 check type tcp -``` - -```{eval-rst} -.. cfgcmd:: set protocols failover route next-hop
check port - - **Configure the destination TCP port on the health check target.** - - This parameter applies only when the check type is configured as ``tcp``. - - The valid port range is 1 to 65535. - - Example: - - .. code-block:: none - - set protocols failover route 203.0.113.1/32 next-hop 10.217.37.254 check port 443 -``` - -```{eval-rst} -.. cfgcmd:: set protocols failover route next-hop
check policy - - **Configure the health check success policy for multiple targets.** - - The following policies are available: - - * ``any-available``: The health check succeeds if at least one of the - configured targets responds successfully. - * ``all-available``: The health check succeeds only if every configured - target responds successfully. - - The default policy is ``any-available``. - - Example: - - .. code-block:: none - - set protocols failover route 203.0.113.1/32 next-hop 10.217.37.254 check policy all-available -``` - -```{eval-rst} -.. cfgcmd:: set protocols failover route next-hop
interface - - **Configure the local interface used to reach the next-hop address.** - - This parameter is mandatory. - - Example: - - .. code-block:: none - - set protocols failover route 203.0.113.1/32 next-hop 10.217.37.254 interface eth0 -``` - -```{eval-rst} -.. cfgcmd:: set protocols failover route next-hop
metric <1-255> - - **Configure the metric (cost) for the failover route.** - - The metric defines the route priority. A lower metric value indicates a - more preferred route. - - The default value is 1. - - Example: - - .. code-block:: none - - set protocols failover route 203.0.113.1/32 next-hop 10.217.37.254 metric 50 -``` - -```{eval-rst} -.. cfgcmd:: set protocols failover route next-hop
onlink - - Configure the next-hop to be reachable via the assigned interface, even - when ``
`` is outside any subnet configured on that interface. - - Example: - - .. code-block:: none - - set protocols failover route 203.0.113.1/32 next-hop 10.217.37.254 onlink -``` - -## Examples - -### Failover route with a single next-hop and ICMP health check - -The following example configures a failover route to `203.0.113.1/32` -through next-hop `192.0.2.1` on `eth0`. The next-hop is monitored with -ICMP probes to `192.0.2.1` every 5 seconds, and the route is installed with -a metric of 10. - -```none -set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 check target '192.0.2.1' -set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 check timeout '5' -set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 check type 'icmp' -set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 interface 'eth0' -set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 metric '10' -``` - -Verify the route: - -```none -vyos@vyos:~$ show ip route 203.0.113.1 -Routing entry for 203.0.113.1/32 - Known via "kernel", distance 0, metric 10, best - Last update 00:00:39 ago - Flags: Selected - Status: Installed - * 192.0.2.1, via eth0, weight 1 -``` - -### Two failover routes with different metrics - -The following example configures two failover routes to `203.0.113.1/32`, -each through a different next-hop. The primary next-hop `192.0.2.1` is -reached on `eth0` with metric 10, and the backup next-hop `198.51.100.1` -is reached on `eth2` with metric 20. Both next-hops are monitored with ICMP -probes every 5 seconds. - -While both health checks succeed, the lower-metric route through `eth0` is -preferred. If the primary target stops responding, its route is removed from -the routing table, and traffic falls over to `198.51.100.1` via `eth2`. - -```none -set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 check target '192.0.2.1' -set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 check timeout '5' -set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 check type 'icmp' -set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 interface 'eth0' -set protocols failover route 203.0.113.1/32 next-hop 192.0.2.1 metric '10' - -set protocols failover route 203.0.113.1/32 next-hop 198.51.100.1 check target '198.51.100.99' -set protocols failover route 203.0.113.1/32 next-hop 198.51.100.1 check timeout '5' -set protocols failover route 203.0.113.1/32 next-hop 198.51.100.1 check type 'icmp' -set protocols failover route 203.0.113.1/32 next-hop 198.51.100.1 interface 'eth2' -set protocols failover route 203.0.113.1/32 next-hop 198.51.100.1 metric '20' -``` - -Verify routes: - -```none -vyos@vyos:~$ show ip route 203.0.113.1 -Routing entry for 203.0.113.1/32 - Known via "kernel", distance 0, metric 10, best - Last update 00:08:06 ago - Flags: Selected - Status: Installed - * 192.0.2.1, via eth0, weight 1 - -Routing entry for 203.0.113.1/32 - Known via "kernel", distance 0, metric 20 - Last update 00:08:14 ago - Flags: None - Status: Installed - * 198.51.100.1, via eth2, weight 1 -``` - diff --git a/docs/configuration/protocols/md-igmp-proxy.md b/docs/configuration/protocols/md-igmp-proxy.md deleted file mode 100644 index 961f921b..00000000 --- a/docs/configuration/protocols/md-igmp-proxy.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -lastproofread: '2023-11-13' ---- - -(igmp-proxy)= - -# IGMP Proxy - -{abbr}`IGMP (Internet Group Management Protocol)` proxy sends IGMP host messages -on behalf of a connected client. The configuration must define one, and only one -upstream interface, and one or more downstream interfaces. - -## Configuration - -```{cfgcmd} set protocols igmp-proxy interface \ role \ - -* **upstream:** The upstream network interface is the outgoing interface -which is responsible for communicating to available multicast data sources. -There can only be one upstream interface. - -* **downstream:** Downstream network interfaces are the distribution -interfaces to the destination networks, where multicast clients can join -groups and receive multicast data. One or more downstream interfaces must -be configured. -``` - -```{cfgcmd} set protocols igmp-proxy interface \ alt-subnet \ - -Defines alternate sources for multicasting and IGMP data. The network address -must be on the following format 'a.b.c.d/n'. By default, the router will -accept data from sources on the same network as configured on an interface. -If the multicast source lies on a remote network, one must define from where -traffic should be accepted. - -This is especially useful for the upstream interface, since the source for -multicast traffic is often from a remote location. - -This option can be supplied multiple times. -``` - -```{cfgcmd} set protocols igmp-proxy disable-quickleave - -Disables quickleave mode. In this mode the daemon will not send a Leave IGMP -message upstream as soon as it receives a Leave message for any downstream -interface. The daemon will not ask for Membership reports on the downstream -interfaces, and if a report is received the group is not joined again the -upstream. - -If it's vital that the daemon should act exactly like a real multicast client -on the upstream interface, this function should be enabled. - -Enabling this function increases the risk of bandwidth saturation. -``` - -```{cfgcmd} set protocols igmp-proxy disable - -Disable this service. -``` - -(igmp-proxy-example)= - -### Example - -Interface eth1 LAN is behind NAT. In order to subscribe 10.0.0.0/23 subnet -multicast which is in eth0 WAN we need to configure igmp-proxy. - -```none -set protocols igmp-proxy interface eth0 role upstream -set protocols igmp-proxy interface eth0 alt-subnet 10.0.0.0/23 -set protocols igmp-proxy interface eth1 role downstream -``` - - -## Operation - -```{opcmd} restart igmp-proxy - -Restart the IGMP proxy process. -``` \ No newline at end of file diff --git a/docs/configuration/protocols/md-index.md b/docs/configuration/protocols/md-index.md deleted file mode 100644 index 5f190ce1..00000000 --- a/docs/configuration/protocols/md-index.md +++ /dev/null @@ -1,25 +0,0 @@ -# Protocols - -```{toctree} -:includehidden: true -:maxdepth: 1 - -arp -babel -bfd -bgp -failover -igmp-proxy -isis -mpls -multicast -segment-routing -traffic-engineering -openfabric -ospf -pim -pim6 -rip -rpki -static -``` diff --git a/docs/configuration/protocols/md-isis.md b/docs/configuration/protocols/md-isis.md deleted file mode 100644 index ac6db346..00000000 --- a/docs/configuration/protocols/md-isis.md +++ /dev/null @@ -1,746 +0,0 @@ -```{include} /_include/need_improvement.txt -``` - -(routing-isis)= - -# IS-IS - -{abbr}`IS-IS (Intermediate System to Intermediate System)` is a link-state -interior gateway protocol (IGP) which is described in ISO10589, -{rfc}`1195`, {rfc}`5308`. IS-IS runs the Dijkstra shortest-path first (SPF) -algorithm to create a database of the network’s topology, and -from that database to determine the best (that is, lowest cost) path to a -destination. The intermediate systems (the name for routers) exchange topology -information with their directly connected neighbors. IS-IS runs directly on -the data link layer (Layer 2). IS-IS addresses are called -{abbr}`NETs (Network Entity Titles)` and can be 8 to 20 bytes long, but are -generally 10 bytes long. The tree database that is created with IS-IS is -similar to the one that is created with OSPF in that the paths chosen should -be similar. Comparisons to OSPF are inevitable and often are reasonable ones -to make in regards to the way a network will respond with either IGP. - -## General - -### Configuration - -#### Mandatory Settings - -For IS-IS top operate correctly, one must do the equivalent of a Router ID in -CLNS. This Router ID is called the {abbr}`NET (Network Entity Title)`. This -must be unique for each and every router that is operating in IS-IS. It also -must not be duplicated otherwise the same issues that occur within OSPF will -occur within IS-IS when it comes to said duplication. - -```{cfgcmd} set protocols isis net \ - -This command sets network entity title (NET) provided in ISO format. - -Here is an example {abbr}`NET (Network Entity Title)` value: - -:::{code-block} none -49.0001.1921.6800.1002.00 -::: -The CLNS address consists of the following parts: - -* {abbr}`AFI (Address family authority identifier)` - ``49`` The AFI value - 49 is what IS-IS uses for private addressing. - -* Area identifier: ``0001`` IS-IS area number (numerical area ``1``) - -* System identifier: ``1921.6800.1002`` - for system identifiers we recommend - to use IP address or MAC address of the router itself. The way to construct - this is to keep all of the zeroes of the router IP address, and then change - the periods from being every three numbers to every four numbers. The - address that is listed here is ``192.168.1.2``, which if expanded will turn - into ``192.168.001.002``. Then all one has to do is move the dots to have - four numbers instead of three. This gives us ``1921.6800.1002``. - -* {abbr}`NET (Network Entity Title)` selector: ``00`` Must always be 00. This - setting indicates "this system" or "local system." - -``` - -```{cfgcmd} set protocols isis interface \ - -This command enables IS-IS on this interface, and allows for -adjacency to occur. Note that the name of IS-IS instance must be -the same as the one used to configure the IS-IS process. -``` - -#### IS-IS Global Configuration - -```{cfgcmd} set protocols isis dynamic-hostname - -This command enables support for dynamic hostname TLV. Dynamic hostname -mapping determined as described in {rfc}`2763`, Dynamic Hostname -Exchange Mechanism for IS-IS. -``` - -```{cfgcmd} set protocols isis level \ - -This command defines the IS-IS router behavior: - -* **level-1** - Act as a station (Level 1) router only. -* **level-1-2** - Act as a station (Level 1) router and area (Level 2) router. -* **level-2-only** - Act as an area (Level 2) router only. -``` - -```{cfgcmd} set protocols isis lsp-mtu \ - -This command configures the maximum size of generated -{abbr}`LSPs (Link State PDUs)`, in bytes. The size range is 128 to 4352. -``` - -```{cfgcmd} set protocols isis metric-style \ - -This command sets old-style (ISO 10589) or new style packet formats: - -* **narrow** - Use old style of TLVs with narrow metric. -* **transition** - Send and accept both styles of TLVs during transition. -* **wide** - Use new style of TLVs to carry wider metric. -``` - -```{cfgcmd} set protocols isis purge-originator - -This command enables {rfc}`6232` purge originator identification. Enable -purge originator identification (POI) by adding the type, length and value -(TLV) with the Intermediate System (IS) identification to the LSPs that do -not contain POI information. If an IS generates a purge, VyOS adds this TLV -with the system ID of the IS to the purge. -``` - -```{cfgcmd} set protocols isis set-attached-bit - -This command sets ATT bit to 1 in Level1 LSPs. It is described in {rfc}`3787`. -``` - -```{cfgcmd} set protocols isis set-overload-bit - -This command sets overload bit to avoid any transit traffic through this -router. It is described in {rfc}`3787`. -``` - -```{cfgcmd} set protocols isis default-information originate \ level-1 - -This command will generate a default-route in L1 database. -``` - -```{cfgcmd} set protocols isis default-information originate \ level-2 - -This command will generate a default-route in L2 database. -``` - -```{cfgcmd} set protocols isis ldp-sync - -This command will enable IGP-LDP synchronization globally for ISIS. This -requires for LDP to be functional. This is described in {rfc}`5443`. By -default all interfaces operational in IS-IS are enabled for synchronization. -Loopbacks are exempt. - -``` - -```{cfgcmd} set protocols isis ldp-sync holddown \ - -This command will change the hold down value globally for IGP-LDP -synchronization during convergence/interface flap events. -``` - -#### Interface Configuration - -```{cfgcmd} set protocols isis interface \ circuit-type \ - -This command specifies circuit type for interface: - -* **level-1** - Level-1 only adjacencies are formed. -* **level-1-2** - Level-1-2 adjacencies are formed -* **level-2-only** - Level-2 only adjacencies are formed - -``` - -```{cfgcmd} set protocols isis interface \ hello-interval \ - -This command sets hello interval in seconds on a given interface. -The range is 1 to 600. -``` - -```{cfgcmd} set protocols isis interface \ hello-multiplier \ - -This command sets multiplier for hello holding time on a given -interface. The range is 2 to 100. -``` - -```{cfgcmd} set protocols isis interface \ hello-padding - -This command configures padding on hello packets to accommodate asymmetrical -maximum transfer units (MTUs) from different hosts as described in -{rfc}`3719`. This helps to prevent a premature adjacency Up state when one -routing devices MTU does not meet the requirements to establish the adjacency. -``` - -```{cfgcmd} set protocols isis interface \ metric \ - -This command set default metric for circuit. - -The metric range is 1 to 16777215 (Max value depend if metric support narrow -or wide value). -``` - -```{cfgcmd} set protocols isis interface \ network point-to-point - -This command specifies network type to Point-to-Point. The default -network type is broadcast. -``` - -```{cfgcmd} set protocols isis interface \ passive - -This command configures the passive mode for this interface. -``` - -```{cfgcmd} set protocols isis interface \ password plaintext-password \ - -This command configures the authentication password for the interface. -``` - -```{cfgcmd} set protocols isis interface \ priority \ - -This command sets priority for the interface for -{abbr}`DIS (Designated Intermediate System)` election. The priority -range is 0 to 127. -``` - -```{cfgcmd} set protocols isis interface \ psnp-interval \ - -This command sets PSNP interval in seconds. The interval range is 0 -to 127. -``` - -```{cfgcmd} set protocols isis interface \ no-three-way-handshake - -This command disables Three-Way Handshake for P2P adjacencies which -described in {rfc}`5303`. Three-Way Handshake is enabled by default. -``` - -```{cfgcmd} set protocols isis interface \ ldp-sync disable - -This command disables IGP-LDP sync for this specific interface. -``` - -```{cfgcmd} set protocols isis interface \ ldp-sync holddown \ - -This command will change the hold down value for IGP-LDP synchronization -during convergence/interface flap events, but for this interface only. -``` - -```{cfgcmd} set protocols isis interface \ fast-reroute lfa [level-1 | level-2] enable - -This command enables per-prefix local LFA fast reroute link protection. -``` - -```{cfgcmd} set protocols isis interface \ fast-reroute lfa [level-1 | level-2] exclude - -This command excludes an interface from the local LFA backup nexthop computation. -``` - -```{cfgcmd} set protocols isis interface \ fast-reroute remote-lfa [level-1 | level-2] tunnel mpls-ldp - -This command enables per-prefix Remote LFA fast reroute link protection. -Note that other routers in the network need to be configured to accept LDP -targeted hello messages in order for RLFA to work. -``` - -```{cfgcmd} set protocols isis interface \ fast-reroute remote-lfa [level-1 | level-2] maximum-metric \ - -This command limits Remote LFA PQ node selection within the specified metric. Metric value range (1-16777215). -``` - -```{cfgcmd} set protocols isis interface \ fast-reroute ti-lfa [level-1|level-2] [node-protection [link-fallback]] - -This command enables per-prefix TI-LFA fast reroute link or node protection. -When node protection is used, option link-fallback enables the computation -and use of link-protecting LFAs for destinations unprotected by node -protection. -``` - -#### Route Redistribution - -```{cfgcmd} set protocols isis redistribute ipv4 \ level-1 - -This command redistributes routing information from the given route source -into the ISIS database as Level-1. There are six modes available for route -source: bgp, connected, kernel, ospf, rip, static. -``` - -```{cfgcmd} set protocols isis redistribute ipv4 \ level-2 - -This command redistributes routing information from the given route source -into the ISIS database as Level-2. There are six modes available for route -source: bgp, connected, kernel, ospf, rip, static. -``` - -```{cfgcmd} set protocols isis redistribute ipv4 \ \ metric \ - -This command specifies metric for redistributed routes from the given route -source. There are six modes available for route source: bgp, connected, -kernel, ospf, rip, static. The metric range is 1 to 16777215. -``` - -```{cfgcmd} set protocols isis redistribute ipv4 \ \ route-map \ - -This command allows to use route map to filter redistributed routes from -the given route source. There are six modes available for route source: -bgp, connected, kernel, ospf, rip, static. -``` - -#### Timers - -```{cfgcmd} set protocols isis lsp-gen-interval \ - -This command sets minimum interval in seconds between regenerating same -LSP. The interval range is 1 to 120. -``` - -```{cfgcmd} set protocols isis lsp-refresh-interval \ - -This command sets LSP refresh interval in seconds. IS-IS generates LSPs -when the state of a link changes. However, to ensure that routing -databases on all routers remain converged, LSPs in stable networks are -generated on a regular basis even though there has been no change to -the state of the links. The interval range is 1 to 65235. The default -value is 900 seconds. -``` - -```{cfgcmd} set protocols isis max-lsp-lifetime \ - -This command sets LSP maximum LSP lifetime in seconds. The interval range -is 350 to 65535. LSPs remain in a database for 1200 seconds by default. -If they are not refreshed by that time, they are deleted. You can change -the LSP refresh interval or the LSP lifetime. The LSP refresh interval -should be less than the LSP lifetime or else LSPs will time out before -they are refreshed. -``` - -```{cfgcmd} set protocols isis spf-interval \ - -This command sets minimum interval between consecutive SPF calculations in -seconds.The interval range is 1 to 120. -``` - -```{cfgcmd} set protocols isis spf-delay-ietf holddown \ -``` - -```{cfgcmd} set protocols isis spf-delay-ietf init-delay \ -``` - -```{cfgcmd} set protocols isis spf-delay-ietf long-delay \ -``` - -```{cfgcmd} set protocols isis spf-delay-ietf short-delay \ -``` - -```{cfgcmd} set protocols isis spf-delay-ietf time-to-learn \ - -This commands specifies the Finite State Machine (FSM) intended to -control the timing of the execution of SPF calculations in response -to IGP events. The process described in {rfc}`8405`. -``` - -#### Loop Free Alternate (LFA) - -```{cfgcmd} set protocols isis fast-reroute lfa remote prefix-list \ \ - -This command enables IP fast re-routing that is part of {rfc}`5286`. -Specifically this is a prefix list which references a prefix in which -will select eligible PQ nodes for remote LFA backups. -``` - -```{cfgcmd} set protocols isis fast-reroute lfa local load-sharing disable \ - -This command disables the load sharing across multiple LFA backups. -``` - -```{cfgcmd} set protocols isis fast-reroute lfa local tiebreaker \ index \ \ - -This command will configure a tie-breaker for multiple local LFA backups. -The lower index numbers will be processed first. -``` - -```{cfgcmd} set protocols isis fast-reroute lfa local priority-limit \ \ - -This command will limit LFA backup computation up to the specified -prefix priority. -``` - -#### Segment Routing over IPv6 (SRv6) - -```{cfgcmd} set protocols isis segment-routing srv6 interface \ - -The dummy interface used -to install SRv6 SIDs into the Linux data plane. The interface must exist and -must be present when configuring IS-IS with -SRv6. -``` - -```{cfgcmd} set protocols isis segment-routing srv6 locator \ - -Specifies the SRv6 locator to use for IS-IS. IS-IS automatically allocates -prefix and adjacency SIDs, creates local SID entries and advertises them -into the IGP domain. -``` - -```{cfgcmd} set protocols isis segment-routing srv6 node-msd max-end-d \<0-255\> - -The Maximum End D MSD Type specifies the maximum number of SIDs present in an -SRH when performing decapsulation. As specified in {rfc}`8986`, the permitted -SID types include, but are not limited to, End.DX6, End.DT4, End.DT46, End -with USD, and End.X with USD. - -If the advertised value is zero or no value is advertised, then the router -cannot apply any behavior that results in decapsulation and forwarding of the -inner packet if the outer IPv6 header contains an SRH. - -Reference: {rfc}`9352` -``` - -```{cfgcmd} set protocols isis segment-routing srv6 node-msd max-end-pop \<0-255\> - -The Maximum End Pop MSD Type signals the maximum number of SIDs in the SRH to -which the router can apply "Penultimate Segment Pop (PSP) of the SRH" or -"Ultimate Segment Pop (USP) of the SRH" behavior, as defined in "Flavors" -(Section 4.16 of {rfc}`8986`). - -If the advertised value is zero or no value is advertised, then the router -cannot apply PSP or USP flavors. - -Reference: {rfc}`9352` -``` - -```{cfgcmd} set protocols isis segment-routing srv6 node-msd max-h-encaps \<0-255\> - -The Maximum H.Encaps MSD Type signals the maximum number of SIDs that can be -added to the segment list of an SRH as part of the "H.Encaps" behavior, as -defined in {rfc}`8986`. - -If the advertised value is zero or no value is advertised, then the headend -can apply an SR Policy that only contains one segment without inserting any -SRH header. A non-zero SRH Max H.encaps MSD indicates that the headend can -insert an SRH up to the advertised number of SIDs. - -Reference: {rfc}`9352` -``` - -```{cfgcmd} set protocols isis segment-routing srv6 node-msd max-segs-left \<0-255\> - -The Maximum Segments Left MSD Type signals the maximum value of the -"Segments Left" field ({rfc}`8754`) in the SRH of a received packet before -applying the Endpoint behavior associated with a SID. - -If no value is advertised, the supported value is 0. - -Reference: {rfc}`9352` -``` - -## Examples - -### Enable IS-IS - -**Node 1:** - -```none -set interfaces loopback lo address '192.168.255.255/32' -set interfaces ethernet eth1 address '192.0.2.1/24' - -set protocols isis interface eth1 -set protocols isis interface lo -set protocols isis net '49.0001.1921.6825.5255.00' -``` - -**Node 2:** - -```none -set interfaces ethernet eth1 address '192.0.2.2/24' - -set interfaces loopback lo address '192.168.255.254/32' -set interfaces ethernet eth1 address '192.0.2.2/24' - -set protocols isis interface eth1 -set protocols isis interface lo -set protocols isis net '49.0001.1921.6825.5254.00' -``` - -This gives us the following neighborships, Level 1 and Level 2: - -```none -Node-1@vyos:~$ show isis neighbor -Area VyOS: - System Id Interface L State Holdtime SNPA - vyos eth1 1 Up 28 0c87.6c09.0001 - vyos eth1 2 Up 28 0c87.6c09.0001 - -Node-2@vyos:~$ show isis neighbor -Area VyOS: - System Id Interface L State Holdtime SNPA - vyos eth1 1 Up 29 0c33.0280.0001 - vyos eth1 2 Up 28 0c33.0280.0001 -``` - -Here's the IP routes that are populated. Just the loopback: - -```none -Node-1@vyos:~$ show ip route isis -Codes: K - kernel route, C - connected, S - static, R - RIP, - O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, - T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, - f - OpenFabric, - > - selected route, * - FIB route, q - queued, r - rejected, b - backup - t - trapped, o - offload failure - -I 192.0.2.0/24 [115/20] via 192.0.2.2, eth1 inactive, weight 1, 00:02:22 -I>* 192.168.255.254/32 [115/20] via 192.0.2.2, eth1, weight 1, 00:02:22 - -Node-2@vyos:~$ show ip route isis -Codes: K - kernel route, C - connected, S - static, R - RIP, - O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, - T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, - f - OpenFabric, - > - selected route, * - FIB route, q - queued, r - rejected, b - backup - t - trapped, o - offload failure - -I 192.0.2.0/24 [115/20] via 192.0.2.1, eth1 inactive, weight 1, 00:02:21 -I>* 192.168.255.255/32 [115/20] via 192.0.2.1, eth1, weight 1, 00:02:21 -``` - -### Enable IS-IS and redistribute routes not natively in IS-IS - -**Node 1:** - -```none -set interfaces dummy dum0 address '203.0.113.1/24' -set interfaces ethernet eth1 address '192.0.2.1/24' - -set policy prefix-list EXPORT-ISIS rule 10 action 'permit' -set policy prefix-list EXPORT-ISIS rule 10 prefix '203.0.113.0/24' -set policy route-map EXPORT-ISIS rule 10 action 'permit' -set policy route-map EXPORT-ISIS rule 10 match ip address prefix-list 'EXPORT-ISIS' - -set protocols isis interface eth1 -set protocols isis net '49.0001.1921.6800.1002.00' -set protocols isis redistribute ipv4 connected level-2 route-map 'EXPORT-ISIS' -``` - -**Node 2:** - -```none -set interfaces ethernet eth1 address '192.0.2.2/24' - -set protocols isis interface eth1 -set protocols isis net '49.0001.1921.6800.2002.00' -``` - -Routes on Node 2: - -```none -Node-2@r2:~$ show ip route isis -Codes: K - kernel route, C - connected, S - static, R - RIP, - O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, - T - Table, v - VNC, V - VNC-Direct, A - Babel, D - SHARP, - F - PBR, f - OpenFabric, - > - selected route, * - FIB route, q - queued route, r - rejected route - -I 203.0.113.0/24 [115/10] via 192.0.2.1, eth1, 00:03:42 -``` - -### Enable IS-IS and IGP-LDP synchronization - -**Node 1:** - -```none -set interfaces loopback lo address 192.168.255.255/32 -set interfaces ethernet eth0 address 192.0.2.1/24 - -set protocols isis interface eth0 -set protocols isis interface lo passive -set protocols isis ldp-sync -set protocols isis net 49.0001.1921.6825.5255.00 - -set protocols mpls interface eth0 -set protocols mpls ldp discovery transport-ipv4-address 192.168.255.255 -set protocols mpls ldp interface lo -set protocols mpls ldp interface eth0 -set protocols mpls ldp parameters transport-prefer-ipv4 -set protocols mpls ldp router-id 192.168.255.255 -``` - -This gives us IGP-LDP synchronization for all non-loopback interfaces with -a holddown timer of zero seconds: - -```none -Node-1@vyos:~$ show isis mpls ldp-sync -eth0 - LDP-IGP Synchronization enabled: yes - holddown timer in seconds: 0 - State: Sync achieved -``` - -### Enable IS-IS with Segment Routing (Experimental) - -**Node 1:** - -```none -set interfaces loopback lo address '192.168.255.255/32' -set interfaces ethernet eth1 address '192.0.2.1/24' - -set protocols isis interface eth1 -set protocols isis interface lo -set protocols isis net '49.0001.1921.6825.5255.00' -set protocols isis segment-routing global-block high-label-value '599' -set protocols isis segment-routing global-block low-label-value '550' -set protocols isis segment-routing prefix 192.168.255.255/32 index value '1' -set protocols isis segment-routing prefix 192.168.255.255/32 index explicit-null -set protocols mpls interface 'eth1' -``` - -**Node 2:** - -```none -set interfaces loopback lo address '192.168.255.254/32' -set interfaces ethernet eth1 address '192.0.2.2/24' - -set protocols isis interface eth1 -set protocols isis interface lo -set protocols isis net '49.0001.1921.6825.5254.00' -set protocols isis segment-routing global-block high-label-value '599' -set protocols isis segment-routing global-block low-label-value '550' -set protocols isis segment-routing prefix 192.168.255.254/32 index value '2' -set protocols isis segment-routing prefix 192.168.255.254/32 index explicit-null -set protocols mpls interface 'eth1' -``` - -This gives us MPLS segment routing enabled and labels for far end loopbacks: - -```none -Node-1@vyos:~$ show mpls table - Inbound Label Type Nexthop Outbound Label - ---------------------------------------------------------------------- - 552 SR (IS-IS) 192.0.2.2 IPv4 Explicit Null <-- Node-2 loopback learned on Node-1 - 15000 SR (IS-IS) 192.0.2.2 implicit-null - 15001 SR (IS-IS) fe80::e87:6cff:fe09:1 implicit-null - 15002 SR (IS-IS) 192.0.2.2 implicit-null - 15003 SR (IS-IS) fe80::e87:6cff:fe09:1 implicit-null - -Node-2@vyos:~$ show mpls table - Inbound Label Type Nexthop Outbound Label - --------------------------------------------------------------------- - 551 SR (IS-IS) 192.0.2.1 IPv4 Explicit Null <-- Node-1 loopback learned on Node-2 - 15000 SR (IS-IS) 192.0.2.1 implicit-null - 15001 SR (IS-IS) fe80::e33:2ff:fe80:1 implicit-null - 15002 SR (IS-IS) 192.0.2.1 implicit-null - 15003 SR (IS-IS) fe80::e33:2ff:fe80:1 implicit-null -``` - -Here is the routing tables showing the MPLS segment routing label operations: - -```none -Node-1@vyos:~$ show ip route isis -Codes: K - kernel route, C - connected, S - static, R - RIP, - O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, - T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, - f - OpenFabric, - > - selected route, * - FIB route, q - queued, r - rejected, b - backup - t - trapped, o - offload failure - -I 192.0.2.0/24 [115/20] via 192.0.2.2, eth1 inactive, weight 1, 00:07:48 -I>* 192.168.255.254/32 [115/20] via 192.0.2.2, eth1, label IPv4 Explicit Null, weight 1, 00:03:39 - -Node-2@vyos:~$ show ip route isis -Codes: K - kernel route, C - connected, S - static, R - RIP, - O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, - T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, - f - OpenFabric, - > - selected route, * - FIB route, q - queued, r - rejected, b - backup - t - trapped, o - offload failure - -I 192.0.2.0/24 [115/20] via 192.0.2.1, eth1 inactive, weight 1, 00:07:46 -I>* 192.168.255.255/32 [115/20] via 192.0.2.1, eth1, label IPv4 Explicit Null, weight 1, 00:03:43 -``` - -### Enable IS-IS with Segment Routing over IPv6 (Experimental) - -**Node 1:** - -```none -set interfaces dummy dum6 description "SRv6 IS-IS" -set interfaces ethernet eth1 address '192.0.2.1/24' -set interfaces loopback lo address '192.168.255.255/32' - -set protocols segment-routing srv6 locator MAIN prefix 2001:db8:1::/64 -set protocols segment-routing interface eth1 - -set protocols isis interface eth1 -set protocols isis interface lo -set protocols isis net '49.0001.1921.6825.5255.00' -set protocols isis segment-routing srv6 locator MAIN -set protocols isis segment-routing srv6 interface dum6 -``` - -**Node 2:** - -```none -set interfaces dummy dum6 description "SRv6 IS-IS" -set interfaces ethernet eth1 address '192.0.2.2/24' -set interfaces loopback lo address '192.168.255.254/32' - -set protocols segment-routing srv6 locator MAIN prefix 2001:db8:2::/64 -set protocols segment-routing interface eth1 - -set protocols isis interface eth1 -set protocols isis interface lo -set protocols isis net '49.0001.1921.6825.5254.00' -set protocols isis segment-routing srv6 locator MAIN -set protocols isis segment-routing srv6 interface dum6 -``` - -### Enable IS-IS with Segment Routing over IPv6 (uSID) (Experimental) - -**Node 1:** - -```none -set interfaces dummy dum6 description "SRv6 IS-IS" -set interfaces ethernet eth1 address '192.0.2.1/24' -set interfaces loopback lo address '192.168.255.255/32' - -set protocols segment-routing interface eth1 -set protocols segment-routing srv6 locator MAIN prefix 2001:db8:1::/48 -set protocols segment-routing srv6 locator MAIN behavior-usid -set protocols segment-routing srv6 locator MAIN block-len 32 -set protocols segment-routing srv6 locator MAIN format usid-f3216 -set protocols segment-routing srv6 locator MAIN func-bits 16 -set protocols segment-routing srv6 locator MAIN node-len 16 - -set protocols isis interface eth1 -set protocols isis interface lo -set protocols isis net '49.0001.1921.6825.5255.00' -set protocols isis segment-routing srv6 interface dum6 -set protocols isis segment-routing srv6 locator MAIN -``` - -**Node 2:** - -```none -set interfaces dummy dum6 description "SRv6 IS-IS" -set interfaces ethernet eth1 address '192.0.2.2/24' -set interfaces loopback lo address '192.168.255.254/32' - -set protocols segment-routing interface eth1 -set protocols segment-routing srv6 locator MAIN prefix 2001:db8:2::/48 -set protocols segment-routing srv6 locator MAIN behavior-usid -set protocols segment-routing srv6 locator MAIN block-len 32 -set protocols segment-routing srv6 locator MAIN format usid-f3216 -set protocols segment-routing srv6 locator MAIN func-bits 16 -set protocols segment-routing srv6 locator MAIN node-len 16 - -set protocols isis interface eth1 -set protocols isis interface lo -set protocols isis net '49.0001.1921.6825.5254.00' -set protocols isis segment-routing srv6 interface dum6 -set protocols isis segment-routing srv6 locator MAIN -``` diff --git a/docs/configuration/protocols/md-mpls.md b/docs/configuration/protocols/md-mpls.md deleted file mode 100644 index 71b14be2..00000000 --- a/docs/configuration/protocols/md-mpls.md +++ /dev/null @@ -1,285 +0,0 @@ -(mpls)= - -# MPLS - -{abbr}`MPLS (Multi-Protocol Label Switching)` is a packet forwarding paradigm -which differs from regular IP forwarding. Instead of IP addresses being used to -make the decision on finding the exit interface, a router will instead use an -exact match on a 32 bit/4 byte header called the MPLS label. This label is -inserted between the ethernet (layer 2) header and the IP (layer 3) header. -One can statically or dynamically assign label allocations, but we will focus -on dynamic allocation of labels using some sort of label distribution protocol -(such as the aptly named Label Distribution Protocol / LDP, Resource Reservation -Protocol / RSVP, or Segment Routing through OSPF/ISIS). These protocols allow -for the creation of a unidirectional/unicast path called a labeled switched -path (initialized as LSP) throughout the network that operates very much like -a tunnel through the network. An easy way of thinking about how an MPLS LSP -actually forwards traffic throughout a network is to think of a GRE tunnel. -They are not the same in how they operate, but they are the same in how they -handle the tunneled packet. It would be good to think of MPLS as a tunneling -technology that can be used to transport many different types of packets, to -aid in traffic engineering by allowing one to specify paths throughout the -network (using RSVP or SR), and to generally allow for easier intra/inter -network transport of data packets. - -For more information on how MPLS label switching works, please go visit -[Wikipedia (MPLS)]. - -:::{note} -MPLS support in VyOS is not finished yet, and therefore its -functionality is limited. Currently there is no support for MPLS enabled VPN -services such as L2VPNs and mVPNs. RSVP support is also not present as the -underlying routing stack (FRR) does not implement it. Currently VyOS -implements LDP as described in RFC 5036; other LDP standard are the -following ones: RFC 6720, RFC 6667, RFC 5919, RFC 5561, RFC 7552, RFC 4447. -Because MPLS is already available (FRR also supports RFC 3031). -::: - -## Label Distribution Protocol - -The {abbr}`MPLS (Multi-Protocol Label Switching)` architecture does not assume -a single protocol to create MPLS paths. VyOS supports the Label Distribution -Protocol (LDP) as implemented by FRR, based on {rfc}`5036`. - -{abbr}`LDP (Label Distribution Protocol)` is a TCP based MPLS signaling protocol -that distributes labels creating MPLS label switched paths in a dynamic manner. -LDP is not a routing protocol, as it relies on other routing protocols for -forwarding decisions. LDP cannot bootstrap itself, and therefore relies on said -routing protocols for communication with other routers that use LDP. - -In order to allow for LDP on the local router to exchange label advertisements -with other routers, a TCP session will be established between automatically -discovered and statically assigned routers. LDP will try to establish a TCP -session to the **transport address** of other routers. Therefore for LDP to -function properly please make sure the transport address is shown in the -routing table and reachable to traffic at all times. - -It is highly recommended to use the same address for both the LDP router-id and -the discovery transport address, but for VyOS MPLS LDP to work both parameters -must be explicitly set in the configuration. - -Another thing to keep in mind with LDP is that much like BGP, it is a protocol -that runs on top of TCP. It however does not have an ability to do something -like a refresh capability like BGPs route refresh capability. Therefore one -might have to reset the neighbor for a capability change or a configuration -change to work. - -## Configuration Options - -```{cfgcmd} set protocols mpls interface \ - -Use this command to enable MPLS processing on the interface you define. -``` - - -```{cfgcmd} set protocols mpls ldp interface \ - -Use this command to enable LDP on the interface you define. -``` - - -```{cfgcmd} set protocols mpls ldp router-id \ - -Use this command to configure the IP address used as the LDP router-id of the -local device. -``` - - -```{cfgcmd} set protocols mpls ldp discovery transport-ipv4-address \ - -``` -```{cfgcmd} set protocols mpls ldp discovery transport-ipv6-address \ - -Use this command to set the IPv4 or IPv6 transport-address used by LDP. -``` - -```{cfgcmd} set protocols mpls ldp neighbor \ password \ - -Use this command to configure authentication for LDP peers. Set the -IP address of the LDP peer and a password that should be shared in -order to become neighbors. -``` - -```{cfgcmd} set protocols mpls ldp neighbor \ session-holdtime \ - -Use this command to configure a specific session hold time for LDP peers. -Set the IP address of the LDP peer and a session hold time that should be -configured for it. You may have to reset the neighbor for this to work. -``` - -```{cfgcmd} set protocols mpls ldp neighbor \ ttl-security \ - -Use this command to enable, disable, or specify hop count for TTL security -for LDP peers. By default the value is set to 255 (or max TTL). -``` - -```{eval-rst} -.. cfgcmd:: set protocols mpls ldp discovery hello-ipv4-interval -.. cfgcmd:: set protocols mpls ldp discovery hello-ipv4-holdtime -.. cfgcmd:: set protocols mpls ldp discovery hello-ipv6-interval -.. cfgcmd:: set protocols mpls ldp discovery hello-ipv6-holdtime - - Use these commands if you would like to set the discovery hello and hold time - parameters. -``` - -```{eval-rst} -.. cfgcmd:: set protocols mpls ldp discovery session-ipv4-holdtime -.. cfgcmd:: set protocols mpls ldp discovery session-ipv6-holdtime - - Use this command if you would like to set the TCP session hold time intervals. -``` - -```{eval-rst} -.. cfgcmd:: set protocols mpls ldp import ipv4 import-filter filter-access-list - -.. cfgcmd:: set protocols mpls ldp import ipv6 import-filter filter-access-list6 - - - Use these commands to control the importing of forwarding equivalence classes - (FECs) for LDP from neighbors. This would be useful for example on only - accepting the labeled routes that are needed and not ones that are not - needed, such as accepting loopback interfaces and rejecting all others. -``` - -```{eval-rst} -.. cfgcmd:: set protocols mpls ldp export ipv4 export-filter filter-access-list - -.. cfgcmd:: set protocols mpls ldp export ipv6 export-filter filter-access-list6 - - - Use these commands to control the exporting of forwarding equivalence classes - (FECs) for LDP to neighbors. This would be useful for example on only - announcing the labeled routes that are needed and not ones that are not - needed, such as announcing loopback interfaces and no others. -``` - -```{eval-rst} -.. cfgcmd:: set protocols mpls ldp export ipv4 explicit-null -.. cfgcmd:: set protocols mpls ldp export ipv6 explicit-null - - Use this command if you would like for the router to advertise FECs with a - label of 0 for explicit null operations. -``` - -```{eval-rst} -.. cfgcmd:: set protocols mpls ldp allocation ipv4 access-list -.. cfgcmd:: set protocols mpls ldp allocation ipv6 access-list6 - - Use this command if you would like to control the local FEC allocations for - LDP. A good example would be for your local router to not allocate a label for - everything. Just a label for what it's useful. A good example would be just a - loopback label. -``` - -```{cfgcmd} set protocols mpls ldp parameters cisco-interop-tlv - -Use this command to use a Cisco non-compliant format to send and interpret -the Dual-Stack capability TLV for IPv6 LDP communications. This is related to -{rfc}`7552`. -``` - -```{cfgcmd} set protocols mpls ldp parameters ordered-control - -Use this command to use ordered label distribution control mode. FRR -by default uses independent label distribution control mode for label -distribution. This is related to {rfc}`5036`. -``` - -```{cfgcmd} set protocols mpls ldp parameters transport-prefer-ipv4 - -Use this command to prefer IPv4 for TCP peer transport connection for LDP -when both an IPv4 and IPv6 LDP address are configured on the same interface. -``` - -```{cfgcmd} set protocols mpls ldp targeted-neighbor ipv4 enable -``` - -```{cfgcmd} set protocols mpls ldp targeted-neighbor ipv6 enable - -Use this command to enable targeted LDP sessions to the local router. The -router will then respond to any sessions that are trying to connect to it that -are not a link local type of TCP connection. -``` - -```{cfgcmd} set protocols mpls ldp targeted-neighbor ipv4 address \ -``` - -```{cfgcmd} set protocols mpls ldp targeted-neighbor ipv6 address \ - -Use this command to enable the local router to try and connect with a targeted -LDP session to another router. -``` - -```{cfgcmd} set protocols mpls ldp targeted-neighbor ipv4 hello-holdtime \ -``` - -```{cfgcmd} set protocols mpls ldp targeted-neighbor ipv4 hello-interval \ -``` - -```{cfgcmd} set protocols mpls ldp targeted-neighbor ipv6 hello-holdtime \ -``` - -```{cfgcmd} set protocols mpls ldp targeted-neighbor ipv6 hello-interval \ - -Use these commands if you would like to set the discovery hello and hold time -parameters for the targeted LDP neighbors. -``` - -### Sample configuration to setup LDP on VyOS - -```none -set protocols ospf area 0 network '192.168.255.252/32' <--- Routing for loopback -set protocols ospf area 0 network '192.168.0.5/32' <--- Routing for an interface connecting to the network -set protocols ospf parameters router-id '192.168.255.252' <--- Router ID setting for OSPF -set protocols mpls interface 'eth1' <--- Enable MPLS for an interface connecting to network -set protocols mpls ldp discovery transport-ipv4-address '192.168.255.252' <--- Transport address for LDP for TCP sessions to connect to -set protocols mpls ldp interface 'eth1' <--- Enable LDP for an interface connecting to network -set protocols mpls ldp interface 'lo' <--- Enable LDP on loopback for future services connectivity -set protocols mpls ldp router-id '192.168.255.252' <--- Router ID setting for LDP -set interfaces ethernet eth1 address '192.168.0.5/31' <--- Interface IP for connecting to network -set interfaces loopback lo address '192.168.255.252/32' <--- Interface loopback IP for router ID and other uses -``` - -## Operational Mode Commands - -When LDP is working, you will be able to see label information in the outcome -of `show ip route`. Besides that information, there are also specific *show* -commands for LDP: - -### Show - -```{opcmd} show mpls ldp binding - -Use this command to see the Label Information Base. - -``` - -```{opcmd} show mpls ldp discovery - -Use this command to see discovery hello information -``` - -```{opcmd} show mpls ldp interface - -Use this command to see LDP interface information -``` - -```{opcmd} show mpls ldp neighbor - -Use this command to see LDP neighbor information -``` - -```{opcmd} show mpls ldp neighbor detail - -Use this command to see detailed LDP neighbor information -``` - -### Reset - -```{opcmd} reset mpls ldp neighbor \ - -Use this command to reset an LDP neighbor/TCP session that is established -``` - -[wikipedia (mpls)]: diff --git a/docs/configuration/protocols/md-multicast.md b/docs/configuration/protocols/md-multicast.md deleted file mode 100644 index 27150a29..00000000 --- a/docs/configuration/protocols/md-multicast.md +++ /dev/null @@ -1,31 +0,0 @@ -(routing-static)= - -# Multicast - -In order to influence Multicast {abbr}`RPF (Reverse Path Forwarding)` lookup, -it is possible to insert into zebra routes for the Multicast -{abbr}`RIB (Routing Information Base)`. These routes are only used for RPF -lookup and will not be used by ZEBRA for insertion into the kernel or for -normal RIB processing. As such it is possible to create weird states with -these commands. - -Use with caution. Most of the time this will not be necessary. - -```{cfgcmd} set protocols static mroute \ next-hop \ [distance \] - -Insert into the Multicast RIB Route `` with specified next-hop. -The distance can be specified as well if desired. -``` -```{cfgcmd} set protocols static mroute \ next-hop \ disable - -Do not install route for `` into the Multicast RIB. -``` -```{cfgcmd} set protocols static mroute \ interface \ [distance \] - -Insert into the Multicast RIB Route `` with specified ``. -The distance can be specified as well if desired. -``` -```{cfgcmd} set protocols static mroute \ interface \ disable - -Do not install route for `` into the Multicast RIB. -``` \ No newline at end of file diff --git a/docs/configuration/protocols/md-openfabric.md b/docs/configuration/protocols/md-openfabric.md deleted file mode 100644 index 09ff5900..00000000 --- a/docs/configuration/protocols/md-openfabric.md +++ /dev/null @@ -1,242 +0,0 @@ -(openfabric)= - -# OpenFabric - -OpenFabric, specified in [draft-white-openfabric-06.txt](https://datatracker.ietf.org/doc/html/draft-white-openfabric-06), is -a routing protocol derived from IS-IS, providing link-state routing with -efficient flooding for topologies like spine-leaf networks. - -OpenFabric a dual stack protocol. -A single OpenFabric instance is able to perform routing for both IPv4 and IPv6. - -## General - -### Configuration - -#### Mandatory Settings - -For OpenFabric to operate correctly, one must do the equivalent of a Router ID -in Connectionless Network Service (CLNS). This Router ID is called the -{abbr}`NET (Network Entity Title)`. The system identifier must be unique within -the network - -```{cfgcmd} set protocols openfabric net \ - -This command sets network entity title (NET) provided in ISO format. - -Here is an example {abbr}`NET (Network Entity Title)` value: - -:::{code-block} none -49.0001.1921.6800.1002.00 -::: -The CLNS address consists of the following parts: - -* {abbr}`AFI (Address family authority identifier)` - ``49`` The AFI value - 49 is what OpenFabric uses for private addressing. - -* Area identifier: ``0001`` OpenFabric area number (numerical area ``1``) - -* System identifier: ``1921.6800.1002`` - for system identifiers we recommend - to use IP address or MAC address of the router itself. The way to construct - this is to keep all of the zeroes of the router IP address, and then change - the periods from being every three numbers to every four numbers. The - address that is listed here is ``192.168.1.2``, which if expanded will turn - into ``192.168.001.002``. Then all one has to do is move the dots to have - four numbers instead of three. This gives us ``1921.6800.1002``. - -* {abbr}`NET (Network Entity Title)` selector: ``00`` Must always be 00. This - setting indicates "this system" or "local system." -``` - - -```{cfgcmd} set protocols openfabric domain \ interface \ address-family \ - -This command enables OpenFabric instance with \ on this interface, and -allows for adjacency to occur for address family (IPv4 or IPv6 or both). -``` - -#### OpenFabric Global Configuration - -```{cfgcmd} set protocols openfabric domain-password \ \ - -This command configures the authentication password for a routing domain, -as clear text or md5 one. -``` - - -```{cfgcmd} set protocols openfabric domain \ purge-originator - -This command enables {rfc}`6232` purge originator identification. -``` - - -```{cfgcmd} set protocols openfabric domain \ set-overload-bit - -This command sets overload bit to avoid any transit traffic through this -router. -``` - - -```{cfgcmd} set protocols openfabric domain \ log-adjacency-changes - -Log changes in adjacency state. -``` - - -```{cfgcmd} set protocols openfabric domain \ fabric-tier \ - -This command sets a static tier number to advertise as location -in the fabric. -``` - -#### Interface Configuration - -```{cfgcmd} set protocols openfabric interface \ hello-interval \ - -This command sets hello interval in seconds on a given interface. -The range is 1 to 600. Hello packets are used to establish and maintain -adjacency between OpenFabric neighbors. -``` - - -```{cfgcmd} set protocols openfabric domain \ interface \ hello-multiplier \ - -This command sets multiplier for hello holding time on a given -interface. The range is 2 to 100. -``` - - -```{cfgcmd} set protocols openfabric domain \ interface \ metric \ - -This command sets default metric for circuit. -The metric range is 1 to 16777215. -``` - - -```{cfgcmd} set protocols openfabric interface \ passive - -This command enables the passive mode for this interface. -``` - - -```{cfgcmd} set protocols openfabric domain \ interface \ password plaintext-password \ - -This command sets the authentication password for the interface. -``` - - -```{cfgcmd} set protocols openfabric domain \ interface \ csnp-interval \ - -This command sets Complete Sequence Number Packets (CSNP) interval in seconds. -The interval range is 1 to 600. -``` - - -```{cfgcmd} set protocols openfabric domain \ interface \ psnp-interval \ - -This command sets Partial Sequence Number Packets (PSNP) interval in seconds. -The interval range is 1 to 120. -``` - -#### Timers - -```{cfgcmd} set protocols openfabric domain \ lsp-gen-interval \ - -This command sets minimum interval at which link-state packets (LSPs) are -generated. The interval range is 1 to 120. -``` - - -```{cfgcmd} set protocols openfabric domain \ lsp-refresh-interval \ - -This command sets LSP refresh interval in seconds. The interval range -is 1 to 65235. -``` - - -```{cfgcmd} set protocols openfabric domain \ max-lsp-lifetime \ - -This command sets LSP maximum LSP lifetime in seconds. The interval range -is 360 to 65535. LSPs remain in a database for 1200 seconds by default. -If they are not refreshed by that time, they are deleted. You can change -the LSP refresh interval or the LSP lifetime. The LSP refresh interval -should be less than the LSP lifetime or else LSPs will time out before -they are refreshed. -``` - - -```{cfgcmd} set protocols openfabric domain \ spf-interval \ - -This command sets minimum interval between consecutive shortest path first -(SPF) calculations in seconds.The interval range is 1 to 120. -``` - -## Examples -### Enable OpenFabric - -**Node 1:** - -```none -set interfaces loopback lo address '192.168.255.255/32' -set interfaces ethernet eth1 address '192.0.2.1/24' - -set protocols openfabric domain VyOS interface eth1 address-family ipv4 -set protocols openfabric domain VyOS interface lo address-family ipv4 -set protocols openfabric net '49.0001.1921.6825.5255.00' -``` - -**Node 2:** - -```none -set interfaces loopback lo address '192.168.255.254/32' -set interfaces ethernet eth1 address '192.0.2.2/24' - -set protocols openfabric domain VyOS interface eth1 address-family ipv4 -set protocols openfabric domain VyOS interface lo address-family ipv4 -set protocols openfabric net '49.0001.1921.6825.5254.00' -``` - -This gives us the following neighborships: - -```none -Node-1@vyos:~$ show openfabric neighbor -show openfabric neighbor -Area VyOS: - System Id Interface L State Holdtime SNPA - vyos eth1 2 Up 27 2020.2020.2020 - - -Node-2@vyos:~$ show openfabric neighbor -show openfabric neighbor -Area VyOS: - System Id Interface L State Holdtime SNPA - vyos eth1 2 Up 30 2020.2020.2020 -``` - -Here's the IP routes that are populated: - -```none -Node-1@vyos:~$ show ip route openfabric -show ip route openfabric -Codes: K - kernel route, C - connected, S - static, R - RIP, - O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, - T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, - f - OpenFabric, - > - selected route, * - FIB route, q - queued, r - rejected, b - backup - t - trapped, o - offload failure - -f 192.0.2.0/24 [115/20] via 192.0.2.2, eth1 onlink, weight 1, 00:00:10 -f>* 192.168.255.254/32 [115/20] via 192.0.2.2, eth1 onlink, weight 1, 00:00:10 - -Node-2@vyos:~$ show ip route openfabric -show ip route openfabric -Codes: K - kernel route, C - connected, S - static, R - RIP, - O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, - T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, - f - OpenFabric, - > - selected route, * - FIB route, q - queued, r - rejected, b - backup - t - trapped, o - offload failure - -f 192.0.2.0/24 [115/20] via 192.0.2.1, eth1 onlink, weight 1, 00:00:48 -f>* 192.168.255.255/32 [115/20] via 192.0.2.1, eth1 onlink, weight 1, 00:00:48 -``` diff --git a/docs/configuration/protocols/md-ospf.md b/docs/configuration/protocols/md-ospf.md deleted file mode 100644 index 72fefb84..00000000 --- a/docs/configuration/protocols/md-ospf.md +++ /dev/null @@ -1,1504 +0,0 @@ -(routing-ospf)= - -# OSPF - -{abbr}`OSPF (Open Shortest Path First)` is a routing protocol for Internet -Protocol (IP) networks. It uses a link state routing (LSR) algorithm and falls -into the group of interior gateway protocols (IGPs), operating within a single -autonomous system (AS). It is defined as OSPF Version 2 in {rfc}`2328` (1998) -for IPv4. Updates for IPv6 are specified as OSPF Version 3 in {rfc}`5340` -(2008). OSPF supports the {abbr}`CIDR (Classless Inter-Domain Routing)` -addressing model. - -OSPF is a widely used IGP in large enterprise networks. - -## OSPFv2 (IPv4) - -### Configuration - -#### General - -VyOS does not have a special command to start the OSPF process. The OSPF process -starts when the first ospf enabled interface is configured. - -```{cfgcmd} set protocols ospf area \ network \ - - This command specifies the OSPF enabled interface(s). If the interface has - an address from defined range then the command enables OSPF on this - interface so router can provide network information to the other ospf - routers via this interface. - - This command is also used to enable the OSPF process. The area number can be - specified in decimal notation in the range from 0 to 4294967295. Or it - can be specified in dotted decimal notation similar to ip address. - - Prefix length in interface must be equal or bigger (i.e. smaller network) - than prefix length in network statement. For example statement above doesn't - enable ospf on interface with address 192.168.1.1/23, but it does on - interface with address 192.168.1.129/25. - - In some cases it may be more convenient to enable OSPF on a per - interface/subnet - basis {cfgcmd}`set protocols ospf interface area ` -``` - - -```{cfgcmd} set protocols ospf auto-cost reference-bandwidth \ - -This command sets the reference bandwidth for cost calculations, where -bandwidth can be in range from 1 to 4294967, specified in Mbits/s. The -default is 100Mbit/s (i.e. a link of bandwidth 100Mbit/s or higher will -have a cost of 1. Cost of lower bandwidth links will be scaled with -reference to this cost). -``` - - -```{cfgcmd} set protocols ospf parameters router-id \ - -This command sets the router-ID of the OSPF process. The router-ID may be an -IP address of the router, but need not be – it can be any arbitrary 32bit -number. However it MUST be unique within the entire OSPF domain to the OSPF -speaker – bad things will happen if multiple OSPF speakers are configured -with the same router-ID! -``` - -#### Optional - -```{cfgcmd} set protocols ospf default-information originate [always] [metric \] [metric-type \<1|2\>] [route-map \] - -Originate an AS-External (type-5) LSA describing a default route into all -external-routing capable areas, of the specified metric and metric type. -If the {cfgcmd}`always` keyword is given then the default is always -advertised, even when there is no default present in the routing table. -The argument {cfgcmd}`route-map` specifies to advertise the default route -if the route map is satisfied. -``` - - -```{cfgcmd} set protocols ospf distance global \ - -This command change distance value of OSPF globally. -The distance range is 1 to 255. -``` - - -```{cfgcmd} set protocols ospf distance ospf \ \ - -This command change distance value of OSPF. The arguments are the distance -values for external routes, inter-area routes and intra-area routes -respectively. The distance range is 1 to 255. - -:::{note} -Routes with a distance of 255 are effectively disabled and not -installed into the kernel. -::: -``` - - -```{cfgcmd} set protocols ospf log-adjacency-changes [detail] - -This command allows to log changes in adjacency. With the optional -{cfgcmd}`detail` argument, all changes in adjacency status are shown. -Without {cfgcmd}`detail`, only changes to full or regressions are shown. -``` - - -```{cfgcmd} set protocols ospf max-metric router-lsa \|on-startup \> - -This enables {rfc}`3137` support, where the OSPF process describes its -transit links in its router-LSA as having infinite distance so that other -routers will avoid calculating transit paths through the router while -still being able to reach networks through the router. - -This support may be enabled administratively (and indefinitely) with the -{cfgcmd}`administrative` command. It may also be enabled conditionally. -Conditional enabling of max-metric router-lsas can be for a period of -seconds after startup with the {cfgcmd}`on-startup ` command -and/or for a period of seconds prior to shutdown with the -{cfgcmd}`on-shutdown ` command. The time range is 5 to 86400. -``` - - -```{cfgcmd} set protocols ospf parameters abr-type \ - -This command selects ABR model. OSPF router supports four ABR models: - -**cisco** – a router will be considered as ABR if it has several configured -links to the networks in different areas one of which is a backbone area. -Moreover, the link to the backbone area should be active (working). -**ibm** – identical to "cisco" model but in this case a backbone area link -may not be active. -**standard** – router has several active links to different areas. -**shortcut** – identical to "standard" but in this model a router is -allowed to use a connected areas topology without involving a backbone -area for inter-area connections. - -Detailed information about "cisco" and "ibm" models differences can be -found in {rfc}`3509`. A "shortcut" model allows ABR to create routes -between areas based on the topology of the areas connected to this router -but not using a backbone area in case if non-backbone route will be -cheaper. For more information about "shortcut" model, -see ospf-shortcut-abr-02.txt -``` - - -```{cfgcmd} set protocols ospf parameters rfc1583-compatibility - -{rfc}`2328`, the successor to {rfc}`1583`, suggests according to section -G.2 (changes) in section 16.4.1 a change to the path preference algorithm -that prevents possible routing loops that were possible in the old version -of OSPFv2. More specifically it demands that inter-area paths and -intra-area backbone path are now of equal preference but still both -preferred to external paths. - -This command should NOT be set normally. -``` - - -```{cfgcmd} set protocols ospf interface \ passive [disable] - -This command specifies interface as passive. Passive interface advertises -its address, but does not run the OSPF protocol (adjacencies are not formed -and hello packets are not generated). - -The optional disable option allows to exclude interface from passive state. -This command is used if the command {cfgcmd}`passive-interface default` was -configured. -``` - - -```{cfgcmd} set protocols ospf passive-interface default - -This command specifies all interfaces as passive by default. Because this -command changes the configuration logic to a default passive; therefore, -interfaces where router adjacencies are expected need to be configured -with the {cfgcmd}`passive-interface-exclude` command. -``` - - -```{cfgcmd} set protocols ospf maximum-paths \<1-64\> - -Use this command to control the maximum number of equal cost paths to reach -a specific destination. The upper limit may differ if you change the value -of MULTIPATH_NUM during compilation. The default is MULTIPATH_NUM (64). -``` - - -```{cfgcmd} set protocols ospf refresh timers \ - -The router automatically updates link-state information with its neighbors. -Only an obsolete information is updated which age has exceeded a specific -threshold. This parameter changes a threshold value, which by default is -1800 seconds (half an hour). The value is applied to the whole OSPF router. -The timer range is 10 to 1800. -``` - - -```{cfgcmd} set protocols ospf timers throttle spf \ \ - -This command sets the initial delay, the initial-holdtime and the -maximum-holdtime between when SPF is calculated and the event which -triggered the calculation. The times are specified in milliseconds and must -be in the range of 0 to 600000 milliseconds. {cfgcmd}`delay` sets the -initial SPF schedule delay in milliseconds. The default value is 200 ms. -{cfgcmd}`initial-holdtime` sets the minimum hold time between two -consecutive SPF calculations. The default value is 1000 ms. -{cfgcmd}`max-holdtime` sets the maximum wait time between two -consecutive SPF calculations. The default value is 10000 ms. -``` - - -```{cfgcmd} set protocols ospf ldp-sync - -This command will enable IGP-LDP synchronization globally for OSPF. This -requires for LDP to be functional. This is described in {rfc}`5443`. By -default all interfaces operational in OSPF are enabled for synchronization. -Loopbacks are exempt. -``` - - -```{cfgcmd} set protocols ospf ldp-sync holddown \ - -This command will change the hold down value globally for IGP-LDP -synchronization during convergence/interface flap events. -``` - - -```{cfgcmd} set protocols ospf capability opaque - -ospfd supports Opaque LSA {rfc}`2370` as partial support for MPLS Traffic -Engineering LSAs. The opaque-lsa capability must be enabled in the -configuration. - -An alternate command could be "mpls-te on" (Traffic Engineering) - -:::{note} -FRR offers only partial support for some of the routing -protocol extensions that are used with MPLS-TE; it does not -support a complete RSVP-TE solution. -::: -``` - -#### Area Configuration - -```{cfgcmd} set protocols ospf area \ area-type stub - -This command specifies the area to be a Stub Area. That is, an area where -no router originates routes external to OSPF and hence an area where all -external routes are via the ABR(s). Hence, ABRs for such an area do not -need to pass AS-External LSAs (type-5) or ASBR-Summary LSAs (type-4) into -the area. They need only pass Network-Summary (type-3) LSAs into such an -area, along with a default-route summary. -``` - - -```{cfgcmd} set protocols ospf area \ area-type stub no-summary - -This command specifies the area to be a Totally Stub Area. In addition to -stub area limitations this area type prevents an ABR from injecting -Network-Summary (type-3) LSAs into the specified stub area. Only default -summary route is allowed. -``` - - -```{cfgcmd} set protocols ospf area \ area-type stub default-cost \ - -This command sets the cost of default-summary LSAs announced to stubby -areas. The cost range is 0 to 16777215. -``` - - -```{cfgcmd} set protocols ospf area \ area-type nssa - -This command specifies the area to be a Not So Stubby Area. External -routing information is imported into an NSSA in Type-7 LSAs. Type-7 LSAs -are similar to Type-5 AS-external LSAs, except that they can only be -flooded into the NSSA. In order to further propagate the NSSA external -information, the Type-7 LSA must be translated to a Type-5 AS-external-LSA -by the NSSA ABR. -``` - - -```{cfgcmd} set protocols ospf area \ area-type nssa no-summary - -This command specifies the area to be a NSSA Totally Stub Area. ABRs for -such an area do not need to pass Network-Summary (type-3) LSAs (except the -default summary route), ASBR-Summary LSAs (type-4) and AS-External LSAs -(type-5) into the area. But Type-7 LSAs that convert to Type-5 at the NSSA -ABR are allowed. -``` - - -```{cfgcmd} set protocols ospf area \ area-type nssa default-cost \ - -This command sets the default cost of LSAs announced to NSSA areas. -The cost range is 0 to 16777215. -``` - - -```{cfgcmd} set protocols ospf area \ area-type nssa translate \ - -Specifies whether this NSSA border router will unconditionally translate -Type-7 LSAs into Type-5 LSAs. When role is Always, Type-7 LSAs are -translated into Type-5 LSAs regardless of the translator state of other -NSSA border routers. When role is Candidate, this router participates in -the translator election to determine if it will perform the translations -duties. When role is Never, this router will never translate Type-7 LSAs -into Type-5 LSAs. -``` - - -```{cfgcmd} set protocols ospf area \ authentication plaintext-password - -This command specifies that simple password authentication should be used -for the given area. The password must also be configured on a per-interface -basis. -``` - - -```{cfgcmd} set protocols ospf area \ authentication md5 - -This command specify that OSPF packets must be authenticated with MD5 HMACs -within the given area. Keying material must also be configured on a -per-interface basis. -``` - - -```{cfgcmd} set protocols ospf area \ range \ [cost \] - -This command summarizes intra area paths from specified area into one -summary-LSA (Type-3) announced to other areas. This command can be used -only in ABR and ONLY router-LSAs (Type-1) and network-LSAs (Type-2) -(i.e. LSAs with scope area) can be summarized. AS-external-LSAs (Type-5) -can’t be summarized - their scope is AS. The optional argument -{cfgcmd}`cost` specifies the aggregated link metric. The metric range is 0 -to 16777215. -``` - - -```{cfgcmd} set protocols ospf area \ range \ not-advertise - -This command instead of summarizing intra area paths filter them - i.e. -intra area paths from this range are not advertised into other areas. -This command makes sense in ABR only. -``` - - -```{cfgcmd} set protocols ospf area \ export-list \ - -Filter Type-3 summary-LSAs announced to other areas originated from -intra- area paths from specified area. -This command makes sense in ABR only. -``` - - -```{cfgcmd} set protocols ospf area \ import-list \ - -Same as export-list, but it applies to paths announced into specified -area as Type-3 summary-LSAs. -This command makes sense in ABR only. -``` - - -```{cfgcmd} set protocols ospf area \ range \ substitute \ - -One Type-3 summary-LSA with routing info is announced into -backbone area if defined area contains at least one intra-area network -(i.e. described with router-LSA or network-LSA) from range . -This command makes sense in ABR only. -``` - - -```{cfgcmd} set protocols ospf area \ shortcut \ - -This parameter allows to "shortcut" routes (non-backbone) for inter-area -routes. There are three modes available for routes shortcutting: - -**default** – this area will be used for shortcutting only if ABR does not -have a link to the backbone area or this link was lost. -**enable** – the area will be used for shortcutting every time the route -that goes through it is cheaper. -**disable** – this area is never used by ABR for routes shortcutting. -``` - - -```{cfgcmd} set protocols ospf area \ virtual-link \ - -Provides a backbone area coherence by virtual link establishment. - -In general, OSPF protocol requires a backbone area (area 0) to be coherent -and fully connected. I.e. any backbone area router must have a route to any -other backbone area router. Moreover, every ABR must have a link to -backbone area. However, it is not always possible to have a physical link -to a backbone area. In this case between two ABR (one of them has a link to -the backbone area) in the area (not stub area) a virtual link is organized. - -\ – area identifier through which a virtual link goes. -\ – ABR router-id with which a virtual link is established. Virtual -link must be configured on both routers. - -Formally, a virtual link looks like a point-to-point network connecting two -ABR from one area one of which physically connected to a backbone area. -This pseudo-network is considered to belong to a backbone area. -``` - -#### Interface Configuration - -```{cfgcmd} set protocols ospf interface \ area \ - - Enable ospf on an interface and set associated area. - - If you have a lot of interfaces, and/or a lot of subnets, then enabling - OSPF via this command may result in a slight performance improvement. -``` - - -```{cfgcmd} set protocols ospf interface \ authentication plaintext-password \ - -This command sets OSPF authentication key to a simple password. After -setting, all OSPF packets are authenticated. Key has length up to 8 chars. - -Simple text password authentication is insecure and deprecated in favour of -MD5 HMAC authentication. -``` - - -```{cfgcmd} set protocols ospf interface \ authentication md5 key-id \ md5-key \ - -This command specifys that MD5 HMAC authentication must be used on this -interface. It sets OSPF authentication key to a cryptographic password. -Key-id identifies secret key used to create the message digest. This ID -is part of the protocol and must be consistent across routers on a link. -The key can be long up to 16 chars (larger strings will be truncated), -and is associated with the given key-id. -``` - - -```{cfgcmd} set protocols ospf interface \ bandwidth \ - -This command sets the interface bandwidth for cost calculations, where -bandwidth can be in range from 1 to 100000, specified in Mbits/s. -``` - - -```{cfgcmd} set protocols ospf interface \ cost \ - -This command sets link cost for the specified interface. The cost value is -set to router-LSA’s metric field and used for SPF calculation. The cost -range is 1 to 65535. -``` - - -```{cfgcmd} set protocols ospf interface \ dead-interval \ - -Set number of seconds for router Dead Interval timer value used for Wait -Timer and Inactivity Timer. This value must be the same for all routers -attached to a common network. The default value is 40 seconds. The -interval range is 1 to 65535. -``` - - -```{cfgcmd} set protocols ospf interface \ hello-multiplier \ - -The hello-multiplier specifies how many Hellos to send per second, from 1 -(every second) to 10 (every 100ms). Thus one can have 1s convergence time -for OSPF. If this form is specified, then the hello-interval advertised in -Hello packets is set to 0 and the hello-interval on received Hello packets -is not checked, thus the hello-multiplier need NOT be the same across -multiple routers on a common link. -``` - - -```{cfgcmd} set protocols ospf interface \ hello-interval \ - -Set number of seconds for Hello Interval timer value. Setting this value, -Hello packet will be sent every timer value seconds on the specified -interface. This value must be the same for all routers attached to a -common network. The default value is 10 seconds. The interval range is 1 -to 65535. -``` - - -```{cfgcmd} set protocols ospf interface \ bfd - -This command enables {abbr}`BFD (Bidirectional Forwarding Detection)` on -this OSPF link interface. -``` - - -```{cfgcmd} set protocols ospf interface \ mtu-ignore - -This command disables check of the MTU value in the OSPF DBD packets. Thus, -use of this command allows the OSPF adjacency to reach the FULL state even -though there is an interface MTU mismatch between two OSPF routers. -``` - - -```{cfgcmd} set protocols ospf interface \ network \ - -This command allows to specify the distribution type for the network -connected to this interface: - -**broadcast** – broadcast IP addresses distribution. -**non-broadcast** – address distribution in NBMA networks topology. -**point-to-multipoint** – address distribution in point-to-multipoint -networks. -**point-to-point** – address distribution in point-to-point networks. -``` - - -```{cfgcmd} set protocols ospf interface \ priority \ - -This command sets Router Priority integer value. The router with the -highest priority will be more eligible to become Designated Router. -Setting the value to 0, makes the router ineligible to become -Designated Router. The default value is 1. The interval range is 0 to 255. -``` - - -```{cfgcmd} set protocols ospf interface \ retransmit-interval \ - -This command sets number of seconds for RxmtInterval timer value. This -value is used when retransmitting Database Description and Link State -Request packets if acknowledge was not received. The default value is 5 -seconds. The interval range is 3 to 65535. -``` - - -```{cfgcmd} set protocols ospf interface \ transmit-delay \ - -This command sets number of seconds for InfTransDelay value. It allows to -set and adjust for each interface the delay interval before starting the -synchronizing process of the router's database with all neighbors. The -default value is 1 seconds. The interval range is 3 to 65535. -``` - - -```{cfgcmd} set protocols ospf interface \ ldp-sync disable - -This command disables IGP-LDP sync for this specific interface. -``` - - -```{cfgcmd} set protocols ospf interface \ ldp-sync holddown \ - -This command will change the hold down value for IGP-LDP synchronization -during convergence/interface flap events, but for this interface only. -``` - -#### External Route Summarisation - - -This feature summarises originated external LSAs (Type-5 and Type-7). Summary -Route will be originated on-behalf of all matched external LSAs. - -```{cfgcmd} set protocols ospf aggregation timer \ - -Configure aggregation delay timer interval. - -Summarisation starts only after this delay timer expiry. -``` - - -```{cfgcmd} set protocols ospf summary-address x.x.x.x/y [tag (1-4294967295)] - -This command enable/disables summarisation for the configured address range. - -Tag is the optional parameter. If tag configured Summary route will be -originated with the configured tag. -``` - - -```{cfgcmd} set protocols ospf summary-address x.x.x.x/y no-advertise - -This command to ensure not advertise the summary lsa for the matched -external LSAs. -``` - -#### Graceful Restart - -```{cfgcmd} set protocols ospf graceful-restart [grace-period (1-1800)] - -Configure Graceful Restart {rfc}`3623` restarting support. When enabled, -the default grace period is 120 seconds. - -To perform a graceful shutdown, the FRR ``graceful-restart prepare ip -ospf`` EXEC-level command needs to be issued before restarting the -ospfd daemon. -``` - - -```{cfgcmd} set protocols ospf graceful-restart helper enable [router-id A.B.C.D] - -Configure Graceful Restart {rfc}`3623` helper support. By default, helper support -is disabled for all neighbours. This config enables/disables helper support -on this router for all neighbours. - -To enable/disable helper support for a specific neighbour, the router-id -(A.B.C.D) has to be specified. -``` - - -```{cfgcmd} set protocols ospf graceful-restart helper no-strict-lsa-checking - -By default strict-lsa-checking is configured then the helper will abort -the Graceful Restart when a LSA change occurs which affects the restarting -router. - -This command disables it. -``` - - -```{cfgcmd} set protocols ospf graceful-restart helper supported-grace-time - -Supports as HELPER for configured grace period. -``` - - -```{cfgcmd} set protocols ospf graceful-restart helper planned-only - -It helps to support as HELPER only for planned restarts. - -By default, it supports both planned and unplanned outages. -``` - -#### Manual Neighbor Configuration - - -OSPF routing devices normally discover their neighbors dynamically by -listening to the broadcast or multicast hello packets on the network. -Because an NBMA network does not support broadcast (or multicast), the -device cannot discover its neighbors dynamically, so you must configure all -the neighbors statically. - -```{cfgcmd} set protocols ospf neighbor \ - -This command specifies the IP address of the neighboring device. -``` - - -```{cfgcmd} set protocols ospf neighbor \ poll-interval \ - -This command specifies the length of time, in seconds, before the routing -device sends hello packets out of the interface before it establishes -adjacency with a neighbor. The range is 1 to 65535 seconds. The default -value is 60 seconds. -``` - - -```{cfgcmd} set protocols ospf neighbor \ priority \ - -This command specifies the router priority value of the nonbroadcast -neighbor associated with the IP address specified. The default is 0. -This keyword does not apply to point-to-multipoint interfaces. -``` - -#### Redistribution Configuration - -```{cfgcmd} set protocols ospf redistribute \ - - This command redistributes routing information from the given route source - to the OSPF process. There are five modes available for route source: bgp, - connected, kernel, rip, static. -``` - - -```{cfgcmd} set protocols ospf default-metric \ - -This command specifies the default metric value of redistributed routes. -The metric range is 0 to 16777214. -``` - - -```{cfgcmd} set protocols ospf redistribute \ metric \ - -This command specifies metric for redistributed routes from the given -route source. There are five modes available for route source: bgp, -connected, kernel, rip, static. The metric range is 1 to 16777214. -``` - - -```{cfgcmd} set protocols ospf redistribute \ metric-type \<1|2\> - -This command specifies metric type for redistributed routes. Difference -between two metric types that metric type 1 is a metric which is -"commensurable" with inner OSPF links. When calculating a metric to the -external destination, the full path metric is calculated as a metric sum -path of a router which had advertised this link plus the link metric. -Thus, a route with the least summary metric will be selected. If external -link is advertised with metric type 2 the path is selected which lies -through the router which advertised this link with the least metric -despite of the fact that internal path to this router is longer (with more -cost). However, if two routers advertised an external link and with metric -type 2 the preference is given to the path which lies through the router -with a shorter internal path. If two different routers advertised two -links to the same external destimation but with different metric type, -metric type 1 is preferred. If type of a metric left undefined the router -will consider these external links to have a default metric type 2. -``` - - -```{cfgcmd} set protocols ospf redistribute \ route-map \ - -This command allows to use route map to filter redistributed routes from -the given route source. There are five modes available for route source: -bgp, connected, kernel, rip, static. -``` - -#### Operational Mode Commands - -```{opcmd} show ip ospf neighbor - - This command displays the neighbors status. -``` - - -```none -Neighbor ID Pri State Dead Time Address Interface RXmtL RqstL DBsmL -10.0.13.1 1 Full/DR 38.365s 10.0.13.1 eth0:10.0.13.3 0 0 0 -10.0.23.2 1 Full/Backup 39.175s 10.0.23.2 eth1:10.0.23.3 0 0 0 -``` - - -```{opcmd} show ip ospf neighbor detail - -This command displays the neighbors information in a detailed form, not -just a summary table. -``` - - -```none - Neighbor 10.0.13.1, interface address 10.0.13.1 - - In the area 0.0.0.0 via interface eth0 - - Neighbor priority is 1, State is Full, 5 state changes - - Most recent state change statistics: - - Progressive change 11m55s ago - - DR is 10.0.13.1, BDR is 10.0.13.3 - - Options 2 *|-|-|-|-|-|E|- - - Dead timer due in 34.854s - - Database Summary List 0 - - Link State Request List 0 - - Link State Retransmission List 0 - - Thread Inactivity Timer on - - Thread Database Description Retransmision off - - Thread Link State Request Retransmission on - - Thread Link State Update Retransmission on - - -Neighbor 10.0.23.2, interface address 10.0.23.2 - - In the area 0.0.0.1 via interface eth1 - - Neighbor priority is 1, State is Full, 4 state changes - - Most recent state change statistics: - - Progressive change 41.193s ago - - DR is 10.0.23.3, BDR is 10.0.23.2 - - Options 2 *|-|-|-|-|-|E|- - - Dead timer due in 35.661s - - Database Summary List 0 - - Link State Request List 0 - - Link State Retransmission List 0 - - Thread Inactivity Timer on - - Thread Database Description Retransmision off - - Thread Link State Request Retransmission on - - Thread Link State Update Retransmission on -``` - - -```{opcmd} show ip ospf neighbor \ - -This command displays the neighbors information in a detailed form for a -neighbor whose IP address is specified. -``` - - -```{opcmd} show ip ospf neighbor \ - -This command displays the neighbors status for a neighbor on the specified -interface. -``` - - -```{opcmd} show ip ospf interface [\] - -This command displays state and configuration of OSPF the specified -interface, or all interfaces if no interface is given. -``` - - -```none -eth0 is up - ifindex 2, MTU 1500 bytes, BW 4294967295 Mbit - Internet Address 10.0.13.3/24, Broadcast 10.0.13.255, Area 0.0.0.0 - MTU mismatch detection: enabled - Router ID 10.0.23.3, Network Type BROADCAST, Cost: 1 - Transmit Delay is 1 sec, State Backup, Priority 1 - Backup Designated Router (ID) 10.0.23.3, Interface Address 10.0.13.3 - Multicast group memberships: OSPFAllRouters OSPFDesignatedRouters - Timer intervals configured, Hello 10s, Dead 40s, Wait 40s, Retransmit 5 - Hello due in 4.470s - Neighbor Count is 1, Adjacent neighbor count is 1 -eth1 is up - ifindex 3, MTU 1500 bytes, BW 4294967295 Mbit - Internet Address 10.0.23.3/24, Broadcast 10.0.23.255, Area 0.0.0.1 - MTU mismatch detection: enabled - Router ID 10.0.23.3, Network Type BROADCAST, Cost: 1 - Transmit Delay is 1 sec, State DR, Priority 1 - Backup Designated Router (ID) 10.0.23.2, Interface Address 10.0.23.2 - Saved Network-LSA sequence number 0x80000002 - Multicast group memberships: OSPFAllRouters OSPFDesignatedRouters - Timer intervals configured, Hello 10s, Dead 40s, Wait 40s, Retransmit 5 - Hello due in 4.563s - Neighbor Count is 1, Adjacent neighbor count is 1 -``` - - -```{opcmd} show ip ospf route [detail] - -This command displays the OSPF routing table, as determined by the most -recent SPF calculation. With the optional {cfgcmd}`detail` argument, -each route item's advertiser router and network attribute will be shown. -``` - - -```none -============ OSPF network routing table ============ -N IA 10.0.12.0/24 [3] area: 0.0.0.0 - via 10.0.13.3, eth0 -N 10.0.13.0/24 [1] area: 0.0.0.0 - directly attached to eth0 -N IA 10.0.23.0/24 [2] area: 0.0.0.0 - via 10.0.13.3, eth0 -N 10.0.34.0/24 [2] area: 0.0.0.0 - via 10.0.13.3, eth0 - -============ OSPF router routing table ============= -R 10.0.23.3 [1] area: 0.0.0.0, ABR - via 10.0.13.3, eth0 -R 10.0.34.4 [2] area: 0.0.0.0, ASBR - via 10.0.13.3, eth0 - -============ OSPF external routing table =========== -N E2 172.16.0.0/24 [2/20] tag: 0 - via 10.0.13.3, eth0 -``` - -The table consists of following data: - - -**OSPF network routing table** – includes a list of acquired routes for all -accessible networks (or aggregated area ranges) of OSPF system. "IA" flag -means that route destination is in the area to which the router is not -connected, i.e. it’s an inter-area path. In square brackets a summary metric -for all links through which a path lies to this network is specified. "via" -prefix defines a router-gateway, i.e. the first router on the way to the -destination (next hop). -**OSPF router routing table** – includes a list of acquired routes to all -accessible ABRs and ASBRs. -**OSPF external routing table** – includes a list of acquired routes that are -external to the OSPF process. "E" flag points to the external link metric type -(E1 – metric type 1, E2 – metric type 2). External link metric is printed in -the "\/\" format. - -```{opcmd} show ip ospf border-routers - -This command displays a table of paths to area boundary and autonomous -system boundary routers. -``` - - -```{opcmd} show ip ospf database - -This command displays a summary table with a database contents (LSA). -``` - - -```none - OSPF Router with ID (10.0.13.1) - - Router Link States (Area 0.0.0.0) - -Link ID ADV Router Age Seq# CkSum Link count -10.0.13.1 10.0.13.1 984 0x80000005 0xd915 1 -10.0.23.3 10.0.23.3 1186 0x80000008 0xfe62 2 -10.0.34.4 10.0.34.4 1063 0x80000004 0x4e3f 1 - - Net Link States (Area 0.0.0.0) - -Link ID ADV Router Age Seq# CkSum -10.0.13.1 10.0.13.1 994 0x80000003 0x30bb -10.0.34.4 10.0.34.4 1188 0x80000001 0x9411 - - Summary Link States (Area 0.0.0.0) - -Link ID ADV Router Age Seq# CkSum Route -10.0.12.0 10.0.23.3 1608 0x80000001 0x6ab6 10.0.12.0/24 -10.0.23.0 10.0.23.3 981 0x80000003 0xe232 10.0.23.0/24 - - AS External Link States - -Link ID ADV Router Age Seq# CkSum Route -172.16.0.0 10.0.34.4 1063 0x80000001 0xc40d E2 172.16.0.0/24 [0x0] -``` - - -```{opcmd} show ip ospf database \ [A.B.C.D] [adv-router \|self-originate] - - This command displays a database contents for a specific link advertisement - type. - - The type can be the following: - asbr-summary, external, network, nssa-external, opaque-area, opaque-as, - opaque-link, router, summary. - - [A.B.C.D] – link-state-id. With this specified the command displays portion - of the network environment that is being described by the advertisement. - The value entered depends on the advertisement’s LS type. It must be - entered in the form of an IP address. - - {cfgcmd}`adv-router ` – router id, which link advertisements need - to be reviewed. - - {cfgcmd}`self-originate` displays only self-originated LSAs from the local - router. -``` - - -```none - OSPF Router with ID (10.0.13.1) - - Router Link States (Area 0.0.0.0) - -LS age: 1213 -Options: 0x2 : *|-|-|-|-|-|E|- -LS Flags: 0x3 -Flags: 0x0 -LS Type: router-LSA -Link State ID: 10.0.13.1 -Advertising Router: 10.0.13.1 -LS Seq Number: 80000009 -Checksum: 0xd119 -Length: 36 - - Number of Links: 1 - - Link connected to: a Transit Network - (Link ID) Designated Router address: 10.0.13.1 - (Link Data) Router Interface address: 10.0.13.1 - Number of TOS metrics: 0 - TOS 0 Metric: 1 -``` - - -```{opcmd} show ip ospf database max-age - -This command displays LSAs in MaxAge list. -``` - -#### Examples -### Enable OSPF - -**Node 1** - -```none -set interfaces loopback lo address 10.1.1.1/32 -set interfaces ethernet eth0 address 192.168.0.1/24 -set protocols ospf area 0 network 192.168.0.0/24 -set protocols ospf area 0 network 10.1.1.1/32 -set protocols ospf parameters router-id 10.1.1.1 -``` - -**Node 2** - -```none -set interfaces loopback lo address 10.1.1.2/32 -set interfaces ethernet eth0 address 192.168.0.2/24 -set protocols ospf area 0 network 192.168.0.0/24 -set protocols ospf area 0 network 10.1.1.2/32 -set protocols ospf parameters router-id 10.1.1.2 -``` - -Here's the neighbors up: - -```none -Node-1@vyos:~$ show ip ospf neighbor - -Neighbor ID Pri State Up Time Dead Time Address Interface RXmtL RqstL DBsmL -10.1.1.2 1 Full/DR 3m43s 36.094s 192.168.0.2 eth0:192.168.0.1 0 0 0 - - -Node-2@vyos:~$ show ip ospf neighbor - -Neighbor ID Pri State Up Time Dead Time Address Interface RXmtL RqstL DBsmL -10.1.1.1 1 Full/Backup 3m47s 31.736s 192.168.0.1 eth0:192.168.0.2 0 0 0 -``` - -Here's the routes: - -```none -Node-1@vyos:~$ show ip route ospf -Codes: K - kernel route, C - connected, S - static, R - RIP, - O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, - T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, - f - OpenFabric, - > - selected route, * - FIB route, q - queued, r - rejected, b - backup - t - trapped, o - offload failure - -O 10.1.1.1/32 [110/0] is directly connected, lo, weight 1, 00:00:14 -O>* 10.1.1.2/32 [110/1] via 192.168.0.2, eth0, weight 1, 00:00:07 -O 192.168.0.0/24 [110/1] is directly connected, eth0, weight 1, 00:03:32 - -Node-2@vyos:~$ show ip route ospf -Codes: K - kernel route, C - connected, S - static, R - RIP, - O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, - T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, - f - OpenFabric, - > - selected route, * - FIB route, q - queued, r - rejected, b - backup - t - trapped, o - offload failure - -O>* 10.1.1.1/32 [110/1] via 192.168.0.1, eth0, weight 1, 00:00:11 -O 10.1.1.2/32 [110/0] is directly connected, lo, weight 1, 00:00:04 -O 192.168.0.0/24 [110/1] is directly connected, eth0, weight 1, 00:03:18 -``` - -### Enable OSPF with route redistribution of the loopback and default originate: - -**Node 1** - -```none -set interfaces loopback lo address 10.1.1.1/32 -set protocols ospf area 0 network 192.168.0.0/24 -set protocols ospf default-information originate always -set protocols ospf default-information originate metric 10 -set protocols ospf default-information originate metric-type 2 -set protocols ospf log-adjacency-changes -set protocols ospf parameters router-id 10.1.1.1 -set protocols ospf redistribute connected metric-type 2 -set protocols ospf redistribute connected route-map CONNECT - -set policy route-map CONNECT rule 10 action permit -set policy route-map CONNECT rule 10 match interface lo -``` - -**Node 2** - -```none -set interfaces loopback lo address 10.2.2.2/32 -set protocols ospf area 0 network 192.168.0.0/24 -set protocols ospf log-adjacency-changes -set protocols ospf parameters router-id 10.2.2.2 -set protocols ospf redistribute connected metric-type 2 -set protocols ospf redistribute connected route-map CONNECT - -set policy route-map CONNECT rule 10 action permit -set policy route-map CONNECT rule 10 match interface lo -``` - -### Enable OSPF and IGP-LDP synchronization: - -**Node 1:** - -```none -set interfaces loopback lo address 10.1.1.1/32 -set interfaces ethernet eth0 address 192.168.0.1/24 - -set protocols ospf area 0 network '192.168.0.0/24' -set protocols ospf area 0 network '10.1.1.1/32' -set protocols ospf parameters router-id '10.1.1.1' -set protocols ospf ldp-sync - -set protocols mpls interface eth0 -set protocols mpls ldp discovery transport-ipv4-address 10.1.1.1 -set protocols mpls ldp interface lo -set protocols mpls ldp interface eth0 -set protocols mpls ldp parameters transport-prefer-ipv4 -set protocols mpls ldp router-id 10.1.1.1 -``` - -This gives us IGP-LDP synchronization for all non-loopback interfaces with -a holddown timer of zero seconds: - -```none -Node-1@vyos:~$ show ip ospf mpls ldp-sync - eth0 - LDP-IGP Synchronization enabled: yes - Holddown timer in seconds: 0 - State: Sync achieved -``` - -### Enable OSPF with Segment Routing (Experimental): - -**Node 1** - -```none -set interfaces loopback lo address 10.1.1.1/32 -set interfaces ethernet eth0 address 192.168.0.1/24 - -set protocols ospf area 0 network '192.168.0.0/24' -set protocols ospf area 0 network '10.1.1.1/32' -set protocols ospf parameters opaque-lsa -set protocols ospf parameters router-id '10.1.1.1' -set protocols ospf segment-routing global-block high-label-value '1100' -set protocols ospf segment-routing global-block low-label-value '1000' -set protocols ospf segment-routing prefix 10.1.1.1/32 index explicit-null -set protocols ospf segment-routing prefix 10.1.1.1/32 index value '1' -``` - -**Node 2** - -```none -set interfaces loopback lo address 10.1.1.2/32 -set interfaces ethernet eth0 address 192.168.0.2/24 - -set protocols ospf area 0 network '192.168.0.0/24' -set protocols ospf area 0 network '10.1.1.2/32' -set protocols ospf parameters opaque-lsa -set protocols ospf parameters router-id '10.1.1.2' -set protocols ospf segment-routing global-block high-label-value '1100' -set protocols ospf segment-routing global-block low-label-value '1000' -set protocols ospf segment-routing prefix 10.1.1.2/32 index explicit-null -set protocols ospf segment-routing prefix 10.1.1.2/32 index value '2' -``` - -This gives us MPLS segment routing enabled and labels for far end loopbacks: - -```none -Node-1@vyos:~$ show mpls table - Inbound Label Type Nexthop Outbound Label - ----------------------------------------------------------- - 1002 SR (OSPF) 192.168.0.2 IPv4 Explicit Null <-- Node-2 loopback learned on Node-1 - 15000 SR (OSPF) 192.168.0.2 implicit-null - 15001 SR (OSPF) 192.168.0.2 implicit-null - -Node-2@vyos:~$ show mpls table - Inbound Label Type Nexthop Outbound Label - ----------------------------------------------------------- - 1001 SR (OSPF) 192.168.0.1 IPv4 Explicit Null <-- Node-1 loopback learned on Node-2 - 15000 SR (OSPF) 192.168.0.1 implicit-null - 15001 SR (OSPF) 192.168.0.1 implicit-null -``` - -Here is the routing tables showing the MPLS segment routing label operations: - -```none -Node-1@vyos:~$ show ip route ospf -Codes: K - kernel route, C - connected, S - static, R - RIP, - O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, - T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, - f - OpenFabric, - > - selected route, * - FIB route, q - queued, r - rejected, b - backup - t - trapped, o - offload failure - -O 10.1.1.1/32 [110/0] is directly connected, lo, weight 1, 00:03:43 -O>* 10.1.1.2/32 [110/1] via 192.168.0.2, eth0, label IPv4 Explicit Null, weight 1, 00:03:32 -O 192.168.0.0/24 [110/1] is directly connected, eth0, weight 1, 00:03:43 - -Node-2@vyos:~$ show ip route ospf -Codes: K - kernel route, C - connected, S - static, R - RIP, - O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, - T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, - f - OpenFabric, - > - selected route, * - FIB route, q - queued, r - rejected, b - backup - t - trapped, o - offload failure - -O>* 10.1.1.1/32 [110/1] via 192.168.0.1, eth0, label IPv4 Explicit Null, weight 1, 00:03:36 -O 10.1.1.2/32 [110/0] is directly connected, lo, weight 1, 00:03:51 -O 192.168.0.0/24 [110/1] is directly connected, eth0, weight 1, 00:03:51 -``` - -(routing-ospfv3)= - -## OSPFv3 (IPv6) - -(ospf-v3-configuration)= - -### Configuration - -(ospf-v3-general)= - -#### General - -VyOS does not have a special command to start the OSPFv3 process. The OSPFv3 -process starts when the first ospf enabled interface is configured. - -```{cfgcmd} set protocols ospfv3 interface \ area \ - - This command specifies the OSPFv3 enabled interface. This command is also - used to enable the OSPF process. The area number can be specified in - decimal notation in the range from 0 to 4294967295. Or it can be specified - in dotted decimal notation similar to ip address. -``` - - -```{cfgcmd} set protocols ospfv3 parameters router-id \ - -This command sets the router-ID of the OSPFv3 process. The router-ID may be -an IP address of the router, but need not be – it can be any arbitrary -32bit number. However it MUST be unique within the entire OSPFv3 domain to -the OSPFv3 speaker – bad things will happen if multiple OSPFv3 speakers are -configured with the same router-ID! -``` - -(ospf-v3-optional)= - -#### Optional - -```{cfgcmd} set protocols ospfv3 distance global \ - -This command change distance value of OSPFv3 globally. -The distance range is 1 to 255. -``` -```{cfgcmd} set protocols ospfv3 distance ospfv3 \ \ - -This command change distance value of OSPFv3. The arguments are the -distance values for external routes, inter-area routes and intra-area -routes respectively. The distance range is 1 to 255. -``` - -(ospf-v3-area-configuration)= - -#### Area Configuration - -```{cfgcmd} set protocols ospfv3 area \ range \ - -This command summarizes intra area paths from specified area into one -Type-3 Inter-Area Prefix LSA announced to other areas. This command can be -used only in ABR. -``` -```{cfgcmd} set protocols ospfv3 area \ range \ not-advertise - -This command instead of summarizing intra area paths filter them - i.e. -intra area paths from this range are not advertised into other areas. This -command makes sense in ABR only. -``` - -(ospf-v3-interface-config)= - -#### Interface Configuration - -```{cfgcmd} set protocols ospfv3 interface \ ipv6 cost \ - -This command sets link cost for the specified interface. The cost value is -set to router-LSA’s metric field and used for SPF calculation. The cost -range is 1 to 65535. -``` -```{cfgcmd} set protocols ospfv3 interface \ dead-interval \ - -Set number of seconds for router Dead Interval timer value used for Wait -Timer and Inactivity Timer. This value must be the same for all routers -attached to a common network. The default value is 40 seconds. The -interval range is 1 to 65535. -``` -```{cfgcmd} set protocols ospfv3 interface \ hello-interval \ - -Set number of seconds for Hello Interval timer value. Setting this value, -Hello packet will be sent every timer value seconds on the specified -interface. This value must be the same for all routers attached to a -common network. The default value is 10 seconds. The interval range is 1 -to 65535. -``` -```{cfgcmd} set protocols ospfv3 interface \ mtu-ignore - -This command disables check of the MTU value in the OSPF DBD packets. -Thus, use of this command allows the OSPF adjacency to reach the FULL -state even though there is an interface MTU mismatch between two OSPF -routers. -``` -```{cfgcmd} set protocols ospfv3 interface \ network \ - -This command allows to specify the distribution type for the network -connected to this interface: - -**broadcast** – broadcast IP addresses distribution. -**point-to-point** – address distribution in point-to-point networks. -``` -```{cfgcmd} set protocols ospfv3 interface \ priority \ - -This command sets Router Priority integer value. The router with the -highest priority will be more eligible to become Designated Router. -Setting the value to 0, makes the router ineligible to become Designated -Router. The default value is 1. The interval range is 0 to 255. -``` -```{cfgcmd} set protocols ospfv3 interface \ passive - -This command specifies interface as passive. Passive interface advertises -its address, but does not run the OSPF protocol (adjacencies are not formed -and hello packets are not generated). -``` -```{cfgcmd} set protocols ospfv3 interface \ retransmit-interval \ - -This command sets number of seconds for RxmtInterval timer value. This -value is used when retransmitting Database Description and Link State -Request packets if acknowledge was not received. The default value is 5 -seconds. The interval range is 3 to 65535. -``` -```{cfgcmd} set protocols ospfv3 interface \ transmit-delay \ - -This command sets number of seconds for InfTransDelay value. It allows to -set and adjust for each interface the delay interval before starting the -synchronizing process of the router's database with all neighbors. The -default value is 1 seconds. The interval range is 3 to 65535. -``` - -(ospf-v3-graceful-restart)= - -#### Graceful Restart - -```{cfgcmd} set protocols ospfv3 graceful-restart [grace-period (1-1800)] - -Configure Graceful Restart {rfc}`3623` restarting support. When enabled, -the default grace period is 120 seconds. - -To perform a graceful shutdown, the FRR ``graceful-restart prepare ip -ospf`` EXEC-level command needs to be issued before restarting the -ospfd daemon. -``` -```{cfgcmd} set protocols ospfv3 graceful-restart helper enable [router-id A.B.C.D] - -Configure Graceful Restart {rfc}`3623` helper support. By default, helper support -is disabled for all neighbours. This config enables/disables helper support -on this router for all neighbours. - -To enable/disable helper support for a specific neighbour, the router-id -(A.B.C.D) has to be specified. -``` -```{cfgcmd} set protocols ospfv3 graceful-restart helper lsa-check-disable - -By default strict-lsa-checking is configured then the helper will abort -the Graceful Restart when a LSA change occurs which affects the restarting -router. - -This command disables it. -``` -```{cfgcmd} set protocols ospfv3 graceful-restart helper supported-grace-time - -Supports as HELPER for configured grace period. -``` -```{cfgcmd} set protocols ospfv3 graceful-restart helper planned-only - -It helps to support as HELPER only for planned restarts. -By default, it supports both planned and unplanned outages. -``` - -(ospf-v3-redistribution-config)= - -#### Redistribution Configuration - -```{cfgcmd} set protocols ospfv3 redistribute \ - -This command redistributes routing information from the given route source -to the OSPFv3 process. There are five modes available for route source: -bgp, connected, kernel, ripng, static. -``` -```{cfgcmd} set protocols ospf redistribute \ route-map \ - -This command allows to use route map to filter redistributed routes from -given route source. There are five modes available for route source: bgp, -connected, kernel, ripng, static. -``` - -(ospf-v3-op-cmd)= - -#### Operational Mode Commands - -```{opcmd} show ipv6 ospfv3 neighbor - -This command displays the neighbors status. -``` -```{opcmd} show ipv6 ospfv3 neighbor detail - -This command displays the neighbors information in a detailed form, not -just a summary table. -``` -```{opcmd} show ipv6 ospfv3 neighbor drchoice - -This command displays the neighbor DR choice information. -``` -```{opcmd} show ipv6 ospfv3 interface [prefix]|[\ [prefix]] - -This command displays state and configuration of OSPF the specified -interface, or all interfaces if no interface is given. Whith the argument -{cfgcmd}`prefix` this command shows connected prefixes to advertise. -``` -```{opcmd} show ipv6 ospfv3 route - -This command displays the OSPF routing table, as determined by the most -recent SPF calculation. -``` -```{opcmd} show ipv6 ospfv3 border-routers - -This command displays a table of paths to area boundary and autonomous -system boundary routers. -``` -```{opcmd} show ipv6 ospfv3 database - -This command displays a summary table with a database contents (LSA). -``` -```{opcmd} show ipv6 ospfv3 database \ [A.B.C.D] [adv-router \|self-originate] - -This command displays a database contents for a specific link -advertisement type. -``` -```{opcmd} show ipv6 ospfv3 redistribute - -This command displays external information redistributed into OSPFv3 -``` - -(ospf-v3-config-example)= - -#### Configuration Example - -A typical configuration using 2 nodes. - -**Node 1:** - -```none -set protocols ospfv3 interface eth1 area 0.0.0.0 -set protocols ospfv3 area 0.0.0.0 range 2001:db8:1::/64 -set protocols ospfv3 parameters router-id 192.168.1.1 -set protocols ospfv3 redistribute connected -``` - -**Node 2:** - -```none -set protocols ospfv3 interface eth1 area 0.0.0.0 -set protocols ospfv3 area 0.0.0.0 range 2001:db8:2::/64 -set protocols ospfv3 parameters router-id 192.168.2.1 -set protocols ospfv3 redistribute connected -``` - -**To see the redistributed routes:** - -```none -show ipv6 ospfv3 redistribute -``` - -Cost calculation wireguard interfaces is unreliable as ospfv3 uses the link speed to calculate the link cost. -You might therefore want to set the link cost to a fixed value on WireGuard tunnels. - -Example configuration for WireGuard interfaces: - -**Node 1** - -```none -set interfaces wireguard wg01 peer ospf02 allowed-ips '::/0' -set interfaces wireguard wg01 peer ospf02 endpoint '10.1.1.101:12345' -set interfaces wireguard wg01 peer ospf02 pubkey 'ie3...=' -set interfaces wireguard wg01 port '12345' -set protocols ospfv3 parameters router-id 192.168.1.1 -set protocols ospfv3 interface 'wg01' area 0.0.0.0 -set protocols ospfv3 interface 'wg01' cost 10 -set protocols ospfv3 interface 'lo' area 0.0.0.0 -``` - -**Node 2** - -```none -set interfaces wireguard wg01 peer ospf01 allowed-ips '::/0' -set interfaces wireguard wg01 peer ospf01 endpoint '10.1.1.100:12345' -set interfaces wireguard wg01 peer ospf01 pubkey 'NHI...=' -set interfaces wireguard wg01 port '12345' -set protocols ospfv3 parameters router-id 192.168.1.2 -set protocols ospfv3 interface 'wg01' area 0.0.0.0 -set protocols ospfv3 interface 'wg01' cost 10 -set protocols ospfv3 interface 'lo' area 0.0.0.0 -``` - -**Status** - -```none -vyos@ospf01:~$ sh ipv6 ospfv3 neighbor -Neighbor ID Pri DeadTime State/IfState Duration I/F[State] -192.168.0.2 1 00:00:37 Full/PointToPoint 00:18:03 wg01[PointToPoint] - -vyos@ospf02# run sh ipv6 ospfv3 neighbor -Neighbor ID Pri DeadTime State/IfState Duration I/F[State] -192.168.0.1 1 00:00:39 Full/PointToPoint 00:19:44 wg01[PointToPoint] -``` diff --git a/docs/configuration/protocols/md-pim.md b/docs/configuration/protocols/md-pim.md deleted file mode 100644 index db8c9fb7..00000000 --- a/docs/configuration/protocols/md-pim.md +++ /dev/null @@ -1,282 +0,0 @@ ---- -lastproofread: '2023-11-13' ---- - -(pim)= - -# PIM – Protocol Independent Multicast - -VyOS supports {abbr}`PIM-SM (PIM Sparse Mode)` as well as -{abbr}`IGMP (Internet Group Management Protocol)` v2 and v3 - -{abbr}`PIM (Protocol Independent Multicast)` must be configured in every -interface of every participating router. Every router must also have the -location of the Rendevouz Point manually configured. Then, unidirectional -shared trees rooted at the Rendevouz Point will automatically be built -for multicast distribution. - -Traffic from multicast sources will go to the Rendezvous Point, and -receivers will pull it from a shared tree using {abbr}`IGMP (Internet -Group Management Protocol)`. - -Multicast receivers will talk IGMP to their local router, so, besides -having PIM configured in every router, IGMP must also be configured in -any router where there could be a multicast receiver locally connected. - -VyOS supports both IGMP version 2 and version 3 (which allows -source-specific multicast). - -## PIM-SM - PIM Sparse Mode - -```{cfgcmd} set protocols pim ecmp - -If PIM has the a choice of ECMP nexthops for a particular -{abbr}`RPF (Reverse Path Forwarding)`, PIM will cause S,G flows to be -spread out amongst the nexthops. If this command is not specified then -the first nexthop found will be used. -``` - -```{cfgcmd} set protocols pim ecmp rebalance - -If PIM is using ECMP and an interface goes down, cause PIM to rebalance all -S,G flows across the remaining nexthops. If this command is not configured -PIM only modifies those S,G flows that were using the interface that went -down. -``` - -```{cfgcmd} set protocols pim join-prune-interval \ - -Modify the join/prune interval that PIM uses to the new value. Time is -specified in seconds. - -The default time is 60 seconds. - -If you enter a value smaller than 60 seconds be aware that this can and -will affect convergence at scale. -``` - -```{cfgcmd} set protocols pim keep-alive-timer \ - -Modify the time out value for a S,G flow from 1-65535 seconds. If choosing -a value below 31 seconds be aware that some hardware platforms cannot see -data flowing in better than 30 second chunks. -``` - -```{cfgcmd} set protocols pim packets \ - -When processing packets from a neighbor process the number of packets -incoming at one time before moving on to the next task. - -The default value is 3 packets. - -This command is only useful at scale when you can possibly have a large -number of PIM control packets flowing. -``` - -```{cfgcmd} set protocols pim register-accept-list \ - -When PIM receives a register packet the source of the packet will be compared -to the prefix-list specified, and if a permit is received normal processing -continues. If a deny is returned for the source address of the register packet -a register stop message is sent to the source. -``` - -```{cfgcmd} set protocols pim register-suppress-time \ - -Modify the time that pim will register suppress a FHR will send register -notifications to the kernel. -``` - -```{cfgcmd} set protocols pim rp \ group \ - -In order to use PIM, it is necessary to configure a {abbr}`RP (Rendezvous Point)` -for join messages to be sent to. Currently the only methodology to do this is -via static rendezvous point commands. - -All routers in the PIM network must agree on these values. - -The first ip address is the RP's address and the second value is the matching -prefix of group ranges covered. -``` - -```{cfgcmd} set protocols pim rp keep-alive-timer \ - -Modify the time out value for a S,G flow from 1-65535 seconds at -{abbr}`RP (Rendezvous Point)`. The normal keepalive period for the KAT(S,G) -defaults to 210 seconds. However, at the {abbr}`RP (Rendezvous Point)`, the -keepalive period must be at least the Register_Suppression_Time, or the RP -may time out the (S,G) state before the next Null-Register arrives. -Thus, the KAT(S,G) is set to max(Keepalive_Period, RP_Keepalive_Period) -when a Register-Stop is sent. - -If choosing a value below 31 seconds be aware that some hardware platforms -cannot see data flowing in better than 30 second chunks. - -See {rfc}`7761#section-4.1` for details. -``` - -```{cfgcmd} set protocols pim no-v6-secondary - -When sending PIM hello packets tell PIM to not send any v6 secondary -addresses on the interface. This information is used to allow PIM to use v6 -nexthops in it's decision for {abbr}`RPF (Reverse Path Forwarding)` lookup -if this option is not set (default). -``` - -```{cfgcmd} set protocols pim spt-switchover infinity-and-beyond [prefix-list \] - -On the last hop router if it is desired to not switch over to the SPT tree -configure this command. - -Optional parameter prefix-list can be use to control which groups to switch or -not switch. If a group is PERMIT as per the prefix-list, then the SPT switchover -does not happen for it and if it is DENY, then the SPT switchover happens. -``` - -```{cfgcmd} set protocols pim ssm prefix-list \ - -Specify a range of group addresses via a prefix-list that forces PIM to never -do {abbr}`SSM (Source-Specific Multicast)` over. -``` - - -### Interface specific commands - -```{cfgcmd} set protocols pim interface \ bfd [profile \] - -Automatically create BFD session for each RIP peer discovered in this -interface. When the BFD session monitor signalize that the link is down -the RIP peer is removed and all the learned routes associated with that -peer are removed. - -If optional profile parameter is used, select a BFD profile for the BFD -sessions created via this interface. -``` - -```{cfgcmd} set protocols pim interface \ dr-priority \ - -Set the {abbr}`DR (Designated Router)` Priority for the interface. -This command is useful to allow the user to influence what node becomes -the DR for a LAN segment. -``` - -```{cfgcmd} set protocols pim interface \ hello \ - -Set the PIM hello and hold interval for a interface. -``` - -```{cfgcmd} set protocols pim interface \ no-bsm - -Tell PIM that we would not like to use this interface to process -bootstrap messages. -``` - -```{cfgcmd} set protocols pim interface \ no-unicast-bsm - -Tell PIM that we would not like to use this interface to process -unicast bootstrap messages. -``` - -```{cfgcmd} set protocols pim interface \ passive - -Disable sending and receiving PIM control packets on the interface. -``` - -```{cfgcmd} set protocols pim interface \ source-address \ - -If you have multiple addresses configured on a particular interface and would -like PIM to use a specific source address associated with that interface. -``` - - -## IGMP - Internet Group Management Protocol) - -```{cfgcmd} set protocols pim igmp watermark-warning \ - -Configure watermark warning generation for an IGMP group limit. Generates -warning once the configured group limit is reached while adding new groups. -``` - -(pim-igmp-interface-commands)= - -### Interface specific commands - -```{cfgcmd} set protocols pim interface \ igmp join \ source-address \ - -Use this command to allow the selected interface to join a multicast -group defining the multicast address you want to join and the source -IP address too. -``` - -```{cfgcmd} set protocols pim interface \ igmp query-interval \ - -Use this command to configure in the selected interface the IGMP -host query interval (1-1800) in seconds that PIM will use. -``` - -```{cfgcmd} set protocols pim interface \ igmp query-max-response-time \ - -Use this command to configure in the selected interface the IGMP -query response timeout value (10-250) in deciseconds. If a report is -not returned in the specified time, it will be assumed the (S,G) or -(\*,G) state {rfc}`7761#section-4.1` has timed out. -``` - -```{cfgcmd} set protocols pim interface \ igmp version \ - -Use this command to define in the selected interface whether you -choose IGMP version 2 or 3. - -The default value is 3. -``` - - -#### Example - -In the following example we can see a basic multicast setup: - -```{image} /_static/images/multicast-basic.webp -:align: center -:alt: Network Topology Diagram -:width: 90% -``` - -**Router 1** - -```none -set interfaces ethernet eth2 address '172.16.0.2/24' -set interfaces ethernet eth1 address '100.64.0.1/24' -set protocols ospf area 0 network '172.16.0.0/24' -set protocols ospf area 0 network '100.64.0.0/24' -set protocols igmp interface eth1 -set protocols pim interface eth1 -set protocols pim interface eth2 -set protocols pim rp address 172.16.255.1 group '224.0.0.0/4' -``` - -**Router 3** - -```none -set interfaces dummy dum0 address '172.16.255.1/24' -set interfaces ethernet eth0 address '172.16.0.1/24' -set interfaces ethernet eth1 address '172.16.1.1/24' -set protocols ospf area 0 network '172.16.0.0/24' -set protocols ospf area 0 network '172.16.255.0/24' -set protocols ospf area 0 network '172.16.1.0/24' -set protocols pim interface dum0 -set protocols pim interface eth0 -set protocols pim interface eth1 -set protocols pim rp address 172.16.255.1 group '224.0.0.0/4' -``` - -**Router 2** - -```none -set interfaces ethernet eth1 address '10.0.0.1/24' -set interfaces ethernet eth2 address '172.16.1.2/24' -set protocols ospf area 0 network '10.0.0.0/24' -set protocols ospf area 0 network '172.16.1.0/24' -set protocols pim interface eth1 -set protocols pim interface eth2 -set protocols pim rp address 172.16.255.1 group '224.0.0.0/4' -``` diff --git a/docs/configuration/protocols/md-pim6.md b/docs/configuration/protocols/md-pim6.md deleted file mode 100644 index 707ae606..00000000 --- a/docs/configuration/protocols/md-pim6.md +++ /dev/null @@ -1,100 +0,0 @@ -(pim6)= - -# PIM6 - Protocol Independent Multicast for IPv6 - -VyOS facilitates IPv6 Multicast by supporting **PIMv6** and **MLD**. - -PIMv6 (Protocol Independent Multicast for IPv6) must be configured in every -interface of every participating router. Every router must also have the -location of the Rendevouz Point manually configured. -Then, unidirectional shared trees rooted at the Rendevouz Point will -automatically be built for multicast distribution. - -Traffic from multicast sources will go to the Rendezvous Point, and receivers -will pull it from a shared tree using MLD (Multicast Listener Discovery). - -Multicast receivers will talk MLD to their local router, so, besides having -PIMv6 configured in every router, MLD must also be configured in any router -where there could be a multicast receiver locally connected. - -VyOS supports both MLD version 1 and version 2 -(which allows source-specific multicast). - -## Basic commands - -These are the commands for a basic setup. - -```{cfgcmd} set protocols pim6 interface \ - - Use this command to enable PIMv6 in the selected interface so that it - can communicate with PIMv6 neighbors. This command also enables MLD reports - and query on the interface unless {cfgcmd}`mld disable` is configured. -``` - - -```{cfgcmd} set protocols pim6 interface \ mld disable - -Disable MLD reports and query on the interface. -``` - - -## Tuning commands - -You can also tune multicast with the following commands. - -```{cfgcmd} set protocols pim6 interface \ mld interval \ - -Use this command to configure in the selected interface the MLD -host query interval (1-65535) in seconds that PIM will use. -The default value is 125 seconds. -``` - -```{cfgcmd} set protocols pim6 interface \ mld join \ - -Use this command to allow the selected interface to join a multicast group. -``` - -```{cfgcmd} set protocols pim6 interface \ mld join \ source \ - -Use this command to allow the selected interface to join a source-specific multicast -group. -``` - -```{cfgcmd} set protocols pim6 interface \ mld last-member-query-count \ - -Set the MLD last member query count. The default value is 2. -``` - -```{cfgcmd} set protocols pim6 interface \ mld last-member-query-interval \ - -Set the MLD last member query interval in milliseconds (100-6553500). The default value is 1000 milliseconds. -``` - -```{cfgcmd} set protocols pim6 interface \ mld max-response-time \ - -Set the MLD query response timeout in milliseconds (100-6553500). The default value is 10000 milliseconds. -``` - -```{cfgcmd} set protocols pim6 interface \ mld version \ - -Set the MLD version used on this interface. The default value is 2. -``` - - -### Configuration Example - -To enable MLD reports and query on interfaces `eth0` and `eth1`: - -```none -set protocols pim6 interface eth0 -set protocols pim6 interface eth1 -``` - -The following configuration explicitly joins multicast group `ff15::1234` on interface `eth1` -and source-specific multicast group `ff15::5678` with source address `2001:db8::1` on interface -`eth1`: - -```none -set protocols pim6 interface eth0 mld join ff15::1234 -set protocols pim6 interface eth1 mld join ff15::5678 source 2001:db8::1 -``` diff --git a/docs/configuration/protocols/md-rip.md b/docs/configuration/protocols/md-rip.md deleted file mode 100644 index 684337d6..00000000 --- a/docs/configuration/protocols/md-rip.md +++ /dev/null @@ -1,294 +0,0 @@ ---- -lastproofread: '2021-10-04' ---- - -(rip)= - -# RIP - -{abbr}`RIP (Routing Information Protocol)` is a widely deployed interior gateway -protocol. RIP was developed in the 1970s at Xerox Labs as part of the XNS -routing protocol. RIP is a distance-vector protocol and is based on the -Bellman-Ford algorithms. As a distance-vector protocol, RIP router send updates -to its neighbors periodically, thus allowing the convergence to a known -topology. In each update, the distance to any given network will be broadcast -to its neighboring router. - -Supported versions of RIP are: - -> - RIPv1 as described in {rfc}`1058` -> - RIPv2 as described in {rfc}`2453` - -## General Configuration - -```{cfgcmd} set protocols rip network \ - -This command enables RIP and sets the RIP enable interface by NETWORK. -The interfaces which have addresses matching with NETWORK are enabled. -``` - - -```{cfgcmd} set protocols rip interface \ - -This command specifies a RIP enabled interface by interface name. Both -the sending and receiving of RIP packets will be enabled on the port -specified in this command. -``` - - -```{cfgcmd} set protocols rip neighbor \ - -This command specifies a RIP neighbor. When a neighbor doesn’t understand -multicast, this command is used to specify neighbors. In some cases, not -all routers will be able to understand multicasting, where packets are -sent to a network or a group of addresses. In a situation where a neighbor -cannot process multicast packets, it is necessary to establish a direct -link between routers. -``` - - -```{cfgcmd} set protocols rip passive-interface interface \ - -This command sets the specified interface to passive mode. On passive mode -interface, all receiving packets are processed as normal and VyOS does not -send either multicast or unicast RIP packets except to RIP neighbors -specified with neighbor command. -``` - - -```{cfgcmd} set protocols rip passive-interface interface default - -This command specifies all interfaces to passive mode. -``` - -## Optional Configuration - -```{cfgcmd} set protocols rip default-distance \ - -This command change the distance value of RIP. The distance range is 1 to 255. - -> :::{note} -> Routes with a distance of 255 are effectively disabled and not -> installed into the kernel. -> ::: -``` - - -```{cfgcmd} set protocols rip network-distance \ distance \ - -This command sets default RIP distance to a specified value when the routes -source IP address matches the specified prefix. -``` - - -```{cfgcmd} set protocols rip network-distance \ access-list \ - -This command can be used with previous command to sets default RIP distance -to specified value when the route source IP address matches the specified -prefix and the specified access-list. -``` - - -```{cfgcmd} set protocols rip default-information originate - -This command generate a default route into the RIP. -``` - - -```{cfgcmd} set protocols rip distribute-list access-list \ \ - -This command can be used to filter the RIP path using access lists. -{cfgcmd}`in` and {cfgcmd}`out` this is the direction in which the access -lists are applied. -``` - - -```{cfgcmd} set protocols rip distribute-list interface \ access-list \ \ - -This command allows you apply access lists to a chosen interface to -filter the RIP path. -``` - - -```{cfgcmd} set protocols rip distribute-list prefix-list \ \ - -This command can be used to filter the RIP path using prefix lists. -{cfgcmd}`in` and {cfgcmd}`out` this is the direction in which the prefix -lists are applied. -``` - - -```{cfgcmd} set protocols rip distribute-list interface \ prefix-list \ \ - -This command allows you apply prefix lists to a chosen interface to -filter the RIP path. -``` - - -```{cfgcmd} set protocols rip route \ - -This command is specific to FRR and VyOS. The route command makes a static -route only inside RIP. This command should be used only by advanced users -who are particularly knowledgeable about the RIP protocol. In most cases, -we recommend creating a static route in VyOS and redistributing it in RIP -using {cfgcmd}`redistribute static`. -``` - - -```{cfgcmd} set protocols rip timers update \ - -This command specifies the update timer. Every update timer seconds, the -RIP process is awakened to send an unsolicited response message containing -the complete routing table to all neighboring RIP routers. The time range -is 5 to 2147483647. The default value is 30 seconds. -``` - - -```{cfgcmd} set protocols rip timers timeout \ - -This command specifies the timeout timer. Upon expiration of the timeout, -the route is no longer valid; however, it is retained in the routing table -for a short time so that neighbors can be notified that the route has been -dropped. The time range is 5 to 2147483647. The default value is 180 -seconds. -``` - - -```{cfgcmd} set protocols rip timers garbage-collection \ - -This command specifies the garbage-collection timer. Upon expiration of -the garbage-collection timer, the route is finally removed from the -routing table. The time range is 5 to 2147483647. The default value is 120 -seconds. -``` - -## Redistribution Configuration - -```{cfgcmd} set protocols rip redistribute \ - -This command redistributes routing information from the given route source -into the RIP tables. There are five modes available for route source: bgp, -connected, kernel, ospf, static. -``` - - -```{cfgcmd} set protocols rip redistribute \ metric \ - -This command specifies metric for redistributed routes from the given route -source. There are five modes available for route source: bgp, connected, -kernel, ospf, static. The metric range is 1 to 16. -``` - - -```{cfgcmd} set protocols rip redistribute \ route-map \ - -This command allows to use route map to filter redistributed routes from -the given route source. There are five modes available for route source: -bgp, connected, kernel, ospf, static. -``` - - -```{cfgcmd} set protocols rip default-metric \ - -This command modifies the default metric (hop count) value for redistributed -routes. The metric range is 1 to 16. The default value is 1. This command -does not affect connected route even if it is redistributed by -{cfgcmd}`redistribute connected`. To modify connected routes metric -value, please use {cfgcmd}`redistribute connected metric`. -``` - -## Interfaces Configuration - -```{cfgcmd} set interfaces \ \ ip rip authentication plaintext-password \ - -This command sets the interface with RIP simple password authentication. -This command also sets authentication string. The string must be shorter -than 16 characters. -``` - - -```{cfgcmd} set interfaces \ \ ip rip authentication md5 \ password \ - -This command sets the interface with RIP MD5 authentication. This command -also sets MD5 Key. The key must be shorter than 16 characters. -``` - - -```{cfgcmd} set interfaces \ \ ip rip split-horizon disable - -This command disables split-horizon on the interface. By default, VyOS does -not advertise RIP routes out the interface over which they were learned -(split horizon).3 -``` - - -```{cfgcmd} set interfaces \ \ ip rip split-horizon poison-reverse - -This command enables poison-reverse on the interface. If both poison reverse -and split horizon are enabled, then VyOS advertises the learned routes -as unreachable over the interface on which the route was learned. -``` - -## Operational Mode Commands - -```{opcmd} show ip rip - -This command displays RIP routes. -``` -```none -Codes: R - RIP, C - connected, S - Static, O - OSPF, B - BGP -Sub-codes: - (n) - normal, (s) - static, (d) - default, (r) - redistribute, - (i) - interface - - Network Next Hop Metric From Tag Time -C(i) 10.0.12.0/24 0.0.0.0 1 self 0 -C(i) 10.0.13.0/24 0.0.0.0 1 self 0 -R(n) 10.0.23.0/24 10.0.12.2 2 10.0.12.2 0 02:53 -``` - -```{opcmd} show ip rip status - -The command displays current RIP status. It includes RIP timer, filtering, -version, RIP enabled interface and RIP peer information. -``` -```none -Routing Protocol is "rip" - Sending updates every 30 seconds with +/-50%, next due in 11 seconds - Timeout after 180 seconds, garbage collect after 120 seconds - Outgoing update filter list for all interface is not set - Incoming update filter list for all interface is not set - Default redistribution metric is 1 - Redistributing: - Default version control: send version 2, receive any version - Interface Send Recv Key-chain - eth0 2 1 2 - eth2 2 1 2 - Routing for Networks: - 10.0.12.0/24 - eth0 - Routing Information Sources: - Gateway BadPackets BadRoutes Distance Last Update - 10.0.12.2 0 0 120 00:00:11 - Distance: (default is 120) -``` - -## Configuration Example - -Simple RIP configuration using 2 nodes and redistributing connected interfaces. - -**Node 1:** - -```none -set interfaces loopback address 10.1.1.1/32 -set protocols rip network 192.168.0.0/24 -set protocols rip redistribute connected -``` - -**Node 2:** - -```none -set interfaces loopback address 10.2.2.2/32 -set protocols rip network 192.168.0.0/24 -set protocols rip redistribute connected -``` diff --git a/docs/configuration/protocols/md-rpki.md b/docs/configuration/protocols/md-rpki.md deleted file mode 100644 index 1f4cf5bf..00000000 --- a/docs/configuration/protocols/md-rpki.md +++ /dev/null @@ -1,210 +0,0 @@ -(rpki)= - -# RPKI - -:::{pull-quote} - -There are two types of Network Admins who deal with BGP, those who have -created an international incident and/or outage, and those who are lying - --- [tweet by EvilMog](https://twitter.com/Evil_Mog/status/1230924170508169216), 2020-02-21 -::: - -{abbr}`RPKI (Resource Public Key Infrastructure)` is a framework designed to -secure the Internet routing infrastructure. It associates BGP route -announcements with the correct originating {abbr}`ASN (Autonomus System -Number)` which BGP routers can then use to check each route against the -corresponding {abbr}`ROA (Route Origin Authorisation)` for validity. RPKI is -described in {rfc}`6480`. - -A BGP-speaking router like VyOS can retrieve ROA information from RPKI -"Relying Party software" (often just called an "RPKI server" or "RPKI -validator") by using {abbr}`RTR (RPKI to Router)` protocol. There are several -open source implementations to choose from, such as NLNetLabs' [Routinator] -(written in Rust), OpenBSD's [rpki-client] (written in C), and [StayRTR] (written -in Go). The RTR protocol is described in {rfc}`8210`. - -:::{tip} -If you are new to these routing security technologies then there is an -[excellent guide to RPKI] by NLnet Labs which will get you up to speed -very quickly. Their documentation explains everything from what RPKI is to -deploying it in production. It also has some -[help and operational guidance] including "What can I do about my route -having an Invalid state?" -::: - -## Getting started - -First you will need to deploy an RPKI validator for your routers to use. NLnet -Labs provides a collection of [software] you can compare and settle on one. -Once your server is running you can start validating announcements. - -Imported prefixes during the validation may have values: - -> valid -> -> : The prefix and ASN that originated it match a signed ROA. These are -> probably trustworthy route announcements. -> -> invalid -> -> : The prefix or prefix length and ASN that originated it doesn't -> match any existing ROA. This could be the result of a prefix hijack, or -> merely a misconfiguration, but should probably be treated as -> untrustworthy route announcements. -> -> notfound -> -> : No ROA exists which covers that prefix. Unfortunately this is the case for -> about 40%-50% of the prefixes which were announced to the {abbr}`DFZ -> (default-free zone)` at the start of 2024. - -:::{note} -If you are responsible for the global addresses assigned to your -network, please make sure that your prefixes have ROAs associated with them -to avoid being `notfound` by RPKI. For most ASNs this will involve -publishing ROAs via your {abbr}`RIR (Regional Internet Registry)` (RIPE -NCC, APNIC, ARIN, LACNIC, or AFRINIC), and is something you are encouraged -to do whenever you plan to announce addresses into the DFZ. - -Particularly large networks may wish to run their own RPKI certificate -authority and publication server instead of publishing ROAs via their RIR. -This is a subject far beyond the scope of VyOS' documentation. Consider -reading about [Krill] if this is a rabbit hole you need or especially want -to dive down. -::: - -### Features of the Current Implementation - -In a nutshell, the current implementation provides the following features: - -- The BGP router can connect to one or more RPKI cache servers to receive - validated prefix to origin AS mappings. Advanced failover can be implemented - by server sockets with different preference values. -- If no connection to an RPKI cache server can be established after a - pre-defined timeout, the router will process routes without prefix origin - validation. It still will try to establish a connection to an RPKI cache - server in the background. -- By default, enabling RPKI does not change best path selection. In particular, - invalid prefixes will still be considered during best path selection. However, - the router can be configured to ignore all invalid prefixes. -- Route maps can be configured to match a specific RPKI validation state. This - allows the creation of local policies, which handle BGP routes based on the - outcome of the Prefix Origin Validation. -- Updates from the RPKI cache servers are directly applied and path selection is - updated accordingly. (Soft reconfiguration must be enabled for this to work). - -## Configuration - -```{cfgcmd} set protocols rpki polling-period \<1-86400\> - -Define the time interval to update the local cache - -The default value is 300 seconds. -``` - -```{cfgcmd} set protocols rpki expire-interval \<600-172800\> - -Set the number of seconds the router waits until the router -expires the cache. - -The default value is 7200 seconds. -``` - -```{cfgcmd} set protocols rpki retry-interval \<1-7200\> - -Set the number of seconds the router waits until retrying to connect -to the cache server. - -The default value is 600 seconds. -``` - -```{cfgcmd} set protocols rpki cache \ port \ - -Defined the IPv4, IPv6 or FQDN and port number of the caching RPKI caching -instance which is used. - -This is a mandatory setting. -``` - -```{cfgcmd} set protocols rpki cache \ preference \ - -Multiple RPKI caching instances can be supplied and they need a preference in -which their result sets are used. - -This is a mandatory setting. -``` - - -### SSH - -Connections to the RPKI caching server can not only be established by TCP using -the RTR protocol but you can also rely on a secure SSH session to the server. -This provides transport integrity and confidentiality and it is a good idea if -your validation software supports it. To enable SSH, first you need to create -an SSH client keypair using `generate ssh client-key -/config/auth/id_rsa_rpki`. Once your key is created you can setup the -connection. - -```{cfgcmd} set protocols rpki cache \ ssh username \ - -SSH username to establish an SSH connection to the cache server. -``` - -```{cfgcmd} set protocols rpki cache \ ssh private-key-file \ - -Local path that includes the private key file of the router. -``` - -```{cfgcmd} set protocols rpki cache \ ssh public-key-file \ - -Local path that includes the public key file of the router. -``` - -:::{note} -When using SSH, private-key-file and public-key-file -are mandatory options. -::: - -## Example - -We can build route-maps for import based on these states. Here is a simple -RPKI configuration, where `routinator` is the RPKI-validating "cache" -server with ip `192.0.2.1`: - -```none -set protocols rpki cache 192.0.2.1 port '3323' -set protocols rpki cache 192.0.2.1 preference '1' -``` - -Here is an example route-map to apply to routes learned at import. In this -filter we reject prefixes with the state `invalid`, and set a higher -`local-preference` if the prefix is RPKI `valid` rather than merely -`notfound`. - -```none -set policy route-map ROUTES-IN rule 10 action 'permit' -set policy route-map ROUTES-IN rule 10 match rpki 'valid' -set policy route-map ROUTES-IN rule 10 set local-preference '300' -set policy route-map ROUTES-IN rule 20 action 'permit' -set policy route-map ROUTES-IN rule 20 match rpki 'notfound' -set policy route-map ROUTES-IN rule 20 set local-preference '125' -set policy route-map ROUTES-IN rule 30 action 'deny' -set policy route-map ROUTES-IN rule 30 match rpki 'invalid' -``` - -Once your routers are configured to reject RPKI-invalid prefixes, you can -test whether the configuration is working correctly using Cloudflare's [test] -website. Keep in mind that in order for this to work, you need to have no -default routes or anything else that would still send traffic to RPKI-invalid -destinations. - -[excellent guide to rpki]: https://rpki.readthedocs.io/ -[help and operational guidance]: https://rpki.readthedocs.io/en/latest/about/help.html -[krill]: https://www.nlnetlabs.nl/projects/rpki/krill/ -[routinator]: https://www.nlnetlabs.nl/projects/rpki/routinator/ -[rpki-client]: https://www.rpki-client.org/ -[software]: https://rpki.readthedocs.io/en/latest/ops/tools.html#relying-party-software -[stayrtr]: https://github.com/bgp/stayrtr/ -[test]: https://isbgpsafeyet.com/ -[tweet by evilmog]: diff --git a/docs/configuration/protocols/md-segment-routing.md b/docs/configuration/protocols/md-segment-routing.md deleted file mode 100644 index 45c89a41..00000000 --- a/docs/configuration/protocols/md-segment-routing.md +++ /dev/null @@ -1,359 +0,0 @@ -(segment-routing)= - -# Segment Routing - -Segment Routing (SR) is a network architecture that is similar to source-routing -. In this architecture, the ingress router adds a list of segments, known as -SIDs, to the packet as it enters the network. These segments represent different -portions of the network path that the packet will take. - -The SR segments are portions of the network path taken by the packet, and are -called SIDs. At each node, the first SID of the list is read, executed as a -forwarding function, and may be popped to let the next node read the next SID of -the list. The SID list completely determines the path where the packet is -forwarded. - -Segment Routing can be applied to an existing MPLS-based data plane and defines -a control plane network architecture. In MPLS networks, segments are encoded as -MPLS labels and are added at the ingress router. These MPLS labels are then -exchanged and populated by Interior Gateway Protocols (IGPs) like IS-IS or OSPF -which are running on most ISPs. - -:::{note} -Segment routing defines a control plane network architecture and -can be applied to an existing MPLS based dataplane. In the MPLS networks, -segments are encoded as MPLS labels and are imposed at the ingress router. -MPLS labels are exchanged and populated by IGPs like IS-IS.Segment Routing -as per RFC8667 for MPLS dataplane. It supports IPv4, IPv6 and ECMP and has -been tested against Cisco & Juniper routers.however,this deployment is still -EXPERIMENTAL for FRR. -::: - -## IS-IS SR Configuration - -Segment routing (SR) is used by the IGP protocols to interconnect network -devices, below configuration shows how to enable SR on IS-IS: - -:::{note} -``Known limitations:`` - -No support for level redistribution (L1 to L2 or L2 to L1) - -No support for binding SID - -No support for SRLB - -Only one SRGB and default SPF Algorithm is supported -::: - -```{cfgcmd} set protocols isis segment-routing global-block high-label-value \ - -Set the Segment Routing Global Block i.e. the label range used by MPLS to -store label in the MPLS FIB for Prefix SID. Note that the block size may -not exceed 65535. -``` - - -```{cfgcmd} set protocols isis segment-routing global-block low-label-value \ - -Set the Segment Routing Global Block i.e. the low label range used by MPLS to -store label in the MPLS FIB for Prefix SID. Note that the block size may -not exceed 65535. -``` - - -```{cfgcmd} set protocols isis segment-routing local-block high-label-value \ - -Set the Segment Routing Local Block i.e. the label range used by MPLS to -store label in the MPLS FIB for Prefix SID. Note that the block size may -not exceed 65535.Segment Routing Local Block, The negative command always -unsets both. -``` - - -```{cfgcmd} set protocols isis segment-routing local-block \ - -Set the Segment Routing Local Block i.e. the low label range used by MPLS to -store label in the MPLS FIB for Prefix SID. Note that the block size may -not exceed 65535.Segment Routing Local Block, The negative command always -unsets both. -``` - - -```{cfgcmd} set protocols isis segment-routing maximum-label-depth \<1-16\> - -Set the Maximum Stack Depth supported by the router. The value depend of -the MPLS dataplane. -``` - - -```{cfgcmd} set protocols isis segment-routing prefix \ index value \<0-65535\> - -A segment ID that contains an IP address prefix calculated by an IGP in the -service provider core network. Prefix SIDs are globally unique, this value -indentify it -``` - - -```{cfgcmd} set protocols isis segment-routing prefix \ index \ - -this option allows to configure prefix-sid on SR. The ‘no-php-flag’ means NO -Penultimate Hop Popping that allows SR node to request to its neighbor to -not pop the label. The ‘explicit-null’ flag allows SR node to request to its -neighbor to send IP packet with the EXPLICIT-NULL label. The ‘n-flag-clear’ -option can be used to explicitly clear the Node flag that is set by default -for Prefix-SIDs associated to loopback addresses. This option is necessary -to configure Anycast-SIDs. -``` - -```{opcmd} show isis segment-routing node - - Show detailed information about all learned Segment Routing Nodes -``` - - -```{opcmd} show isis route prefix-sid - -Show detailed information about prefix-sid and label learned -``` - -:::{note} -more information related IGP - {ref}`routing-isis` -::: - - -## OSPF SR Configuration - - -Segment routing (SR) is used by the IGP protocols to interconnect network -devices, below configuration shows how to enable SR on OSPF: - -```{cfgcmd} set protocols ospf parameters opaque-lsa - -Enable the Opaque-LSA capability (rfc2370), necessary to transport label -on IGP -``` - -```{cfgcmd} set protocols ospf segment-routing global-block high-label-value \ - -Set the Segment Routing Global Block i.e. the label range used by MPLS to -store label in the MPLS FIB for Prefix SID. Note that the block size may -not exceed 65535. -``` - -```{cfgcmd} set protocols ospf segment-routing global-block low-label-value \ - -Set the Segment Routing Global Block i.e. the low label range used by MPLS to -store label in the MPLS FIB for Prefix SID. Note that the block size may -not exceed 65535. -``` - -```{cfgcmd} set protocols ospf segment-routing local-block high-label-value \ - -Set the Segment Routing Local Block i.e. the label range used by MPLS to -store label in the MPLS FIB for Prefix SID. Note that the block size may -not exceed 65535.Segment Routing Local Block, The negative command always -unsets both. -``` - -```{cfgcmd} set protocols ospf segment-routing local-block \ - -Set the Segment Routing Local Block i.e. the low label range used by MPLS to -store label in the MPLS FIB for Prefix SID. Note that the block size may -not exceed 65535.Segment Routing Local Block, The negative command always -unsets both. -``` - -```{cfgcmd} set protocols ospf segment-routing maximum-label-depth \<1-16\> - -Set the Maximum Stack Depth supported by the router. The value depend of -the MPLS dataplane. -``` - -```{cfgcmd} set protocols ospf segment-routing prefix \ index value \<0-65535\> - -A segment ID that contains an IP address prefix calculated by an IGP in the -service provider core network. Prefix SIDs are globally unique, this value -indentify it -``` - -```{cfgcmd} set protocols ospf segment-routing prefix \ index \ - -this option allows to configure prefix-sid on SR. The ‘no-php-flag’ means NO -Penultimate Hop Popping that allows SR node to request to its neighbor to -not pop the label. The ‘explicit-null’ flag allows SR node to request to its -neighbor to send IP packet with the EXPLICIT-NULL label. The ‘n-flag-clear’ -option can be used to explicitly clear the Node flag that is set by default -for Prefix-SIDs associated to loopback addresses. This option is necessary -to configure Anycast-SIDs. -``` - -:::{note} -more information related IGP - {ref}`routing-ospf` -::: - -## Configuration Example - -we described the configuration SR ISIS / SR OSPF using 2 connected with them to -share label information. - -### Enable IS-IS with Segment Routing (Experimental) - -**Node 1:** - -```none -set interfaces loopback lo address '192.168.255.255/32' -set interfaces ethernet eth1 address '192.0.2.1/24' - -set protocols isis interface eth1 -set protocols isis interface lo -set protocols isis net '49.0001.1921.6825.5255.00' -set protocols isis segment-routing global-block high-label-value '599' -set protocols isis segment-routing global-block low-label-value '550' -set protocols isis segment-routing prefix 192.168.255.255/32 index value '1' -set protocols isis segment-routing prefix 192.168.255.255/32 index explicit-null -set protocols mpls interface 'eth1' -``` - -**Node 2:** - -```none -set interfaces loopback lo address '192.168.255.254/32' -set interfaces ethernet eth1 address '192.0.2.2/24' - -set protocols isis interface eth1 -set protocols isis interface lo -set protocols isis net '49.0001.1921.6825.5254.00' -set protocols isis segment-routing global-block high-label-value '599' -set protocols isis segment-routing global-block low-label-value '550' -set protocols isis segment-routing prefix 192.168.255.254/32 index value '2' -set protocols isis segment-routing prefix 192.168.255.254/32 index explicit-null -set protocols mpls interface 'eth1' -``` - -This gives us MPLS segment routing enabled and labels for far end loopbacks: - -```none -Node-1@vyos:~$ show mpls table - Inbound Label Type Nexthop Outbound Label - ---------------------------------------------------------------------- - 552 SR (IS-IS) 192.0.2.2 IPv4 Explicit Null <-- Node-2 loopback learned on Node-1 - 15000 SR (IS-IS) 192.0.2.2 implicit-null - 15001 SR (IS-IS) fe80::e87:6cff:fe09:1 implicit-null - 15002 SR (IS-IS) 192.0.2.2 implicit-null - 15003 SR (IS-IS) fe80::e87:6cff:fe09:1 implicit-null - -Node-2@vyos:~$ show mpls table - Inbound Label Type Nexthop Outbound Label - --------------------------------------------------------------------- - 551 SR (IS-IS) 192.0.2.1 IPv4 Explicit Null <-- Node-1 loopback learned on Node-2 - 15000 SR (IS-IS) 192.0.2.1 implicit-null - 15001 SR (IS-IS) fe80::e33:2ff:fe80:1 implicit-null - 15002 SR (IS-IS) 192.0.2.1 implicit-null - 15003 SR (IS-IS) fe80::e33:2ff:fe80:1 implicit-null -``` - -Here is the routing tables showing the MPLS segment routing label operations: - -```none -Node-1@vyos:~$ show ip route isis -Codes: K - kernel route, C - connected, S - static, R - RIP, - O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, - T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, - f - OpenFabric, - > - selected route, * - FIB route, q - queued, r - rejected, b - backup - t - trapped, o - offload failure - -I 192.0.2.0/24 [115/20] via 192.0.2.2, eth1 inactive, weight 1, 00:07:48 -I>* 192.168.255.254/32 [115/20] via 192.0.2.2, eth1, label IPv4 Explicit Null, weight 1, 00:03:39 - -Node-2@vyos:~$ show ip route isis -Codes: K - kernel route, C - connected, S - static, R - RIP, - O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, - T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, - f - OpenFabric, - > - selected route, * - FIB route, q - queued, r - rejected, b - backup - t - trapped, o - offload failure - -I 192.0.2.0/24 [115/20] via 192.0.2.1, eth1 inactive, weight 1, 00:07:46 -I>* 192.168.255.255/32 [115/20] via 192.0.2.1, eth1, label IPv4 Explicit Null, weight 1, 00:03:43 -``` - - -### Enable OSPF with Segment Routing (Experimental): - -**Node 1** - -```none -set interfaces loopback lo address 10.1.1.1/32 -set interfaces ethernet eth0 address 192.168.0.1/24 -set protocols ospf area 0 network '192.168.0.0/24' -set protocols ospf area 0 network '10.1.1.1/32' -set protocols ospf parameters opaque-lsa -set protocols ospf parameters router-id '10.1.1.1' -set protocols ospf segment-routing global-block high-label-value '1100' -set protocols ospf segment-routing global-block low-label-value '1000' -set protocols ospf segment-routing prefix 10.1.1.1/32 index explicit-null -set protocols ospf segment-routing prefix 10.1.1.1/32 index value '1' -``` - -**Node 2** - -```none -set interfaces loopback lo address 10.1.1.2/32 -set interfaces ethernet eth0 address 192.168.0.2/24 -set protocols ospf area 0 network '192.168.0.0/24' -set protocols ospf area 0 network '10.1.1.2/32' -set protocols ospf parameters opaque-lsa -set protocols ospf parameters router-id '10.1.1.2' -set protocols ospf segment-routing global-block high-label-value '1100' -set protocols ospf segment-routing global-block low-label-value '1000' -set protocols ospf segment-routing prefix 10.1.1.2/32 index explicit-null -set protocols ospf segment-routing prefix 10.1.1.2/32 index value '2' -``` - -This gives us MPLS segment routing enabled and labels for far end loopbacks: - -```none -Node-1@vyos:~$ show mpls table - Inbound Label Type Nexthop Outbound Label - ----------------------------------------------------------- - 1002 SR (OSPF) 192.168.0.2 IPv4 Explicit Null <-- Node-2 loopback learned on Node-1 - 15000 SR (OSPF) 192.168.0.2 implicit-null - 15001 SR (OSPF) 192.168.0.2 implicit-null - -Node-2@vyos:~$ show mpls table - Inbound Label Type Nexthop Outbound Label - ----------------------------------------------------------- - 1001 SR (OSPF) 192.168.0.1 IPv4 Explicit Null <-- Node-1 loopback learned on Node-2 - 15000 SR (OSPF) 192.168.0.1 implicit-null - 15001 SR (OSPF) 192.168.0.1 implicit-null -``` - -Here is the routing tables showing the MPLS segment routing label operations: - -```none -Node-1@vyos:~$ show ip route ospf -Codes: K - kernel route, C - connected, S - static, R - RIP, - O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, - T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, - f - OpenFabric, - > - selected route, * - FIB route, q - queued, r - rejected, b - backup - t - trapped, o - offload failure - -O 10.1.1.1/32 [110/0] is directly connected, lo, weight 1, 00:03:43 -O>* 10.1.1.2/32 [110/1] via 192.168.0.2, eth0, label IPv4 Explicit Null, weight 1, 00:03:32 -O 192.168.0.0/24 [110/1] is directly connected, eth0, weight 1, 00:03:43 - -Node-2@vyos:~$ show ip route ospf -Codes: K - kernel route, C - connected, S - static, R - RIP, - O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, - T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR, - f - OpenFabric, - > - selected route, * - FIB route, q - queued, r - rejected, b - backup - t - trapped, o - offload failure - -O>* 10.1.1.1/32 [110/1] via 192.168.0.1, eth0, label IPv4 Explicit Null, weight 1, 00:03:36 -O 10.1.1.2/32 [110/0] is directly connected, lo, weight 1, 00:03:51 -O 192.168.0.0/24 [110/1] is directly connected, eth0, weight 1, 00:03:51 -``` diff --git a/docs/configuration/protocols/md-static.md b/docs/configuration/protocols/md-static.md deleted file mode 100644 index 357f7076..00000000 --- a/docs/configuration/protocols/md-static.md +++ /dev/null @@ -1,298 +0,0 @@ -(routing-static)= - -# Static - -Static routes are manually configured routes, which, in general, cannot be -updated dynamically from information VyOS learns about the network topology from -other routing protocols. However, if a link fails, the router will remove -routes, including static routes, from the {abbr}`RIPB (Routing Information -Base)` that used this interface to reach the next hop. In general, static -routes should only be used for very simple network topologies, or to override -the behavior of a dynamic routing protocol for a small number of routes. The -collection of all routes the router has learned from its configuration or from -its dynamic routing protocols is stored in the RIB. Unicast routes are directly -used to determine the forwarding table used for unicast packet forwarding. - -## IPv4 Unicast Routes - -```{cfgcmd} set protocols static route \ next-hop \ - -Configure next-hop *\* for an IPv4 static route. Multiple static -routes can be created. -``` - -```{cfgcmd} set protocols static route \ next-hop \ disable - -Disable this IPv4 static route entry. -``` - -```{cfgcmd} set protocols static route \ next-hop \ distance \ - -Defines next-hop distance for this route, routes with smaller administrative -distance are elected prior to those with a higher distance. - -Range is 1 to 255, default is 1. - -:::{note} -Routes with a distance of 255 are effectively disabled and not -installed into the kernel. -::: -``` - - -### IPv4 Interface Routes - -```{cfgcmd} set protocols static route \ interface \ - -Allows you to configure the next-hop interface for an interface-based IPv4 -static route. *\* will be the next-hop interface where traffic is -routed for the given *\*. -``` - -```{cfgcmd} set protocols static route \ interface \ disable - -Disables interface-based IPv4 static route. -``` - -```{cfgcmd} set protocols static route \ interface \ distance \ - -Defines next-hop distance for this route, routes with smaller administrative -distance are elected prior to those with a higher distance. - -Range is 1 to 255, default is 1. -``` - - -### IPv4 BFD - -```{cfgcmd} set protocols static route \ next-hop \ bfd - -Configure a static route for *\* using gateway *\* and use the -gateway address as BFD peer destination address. -``` - -```{cfgcmd} set protocols static route \ next-hop \ bfd profile \ - -Configure a static route for *\* using gateway *\* and use the -gateway address as BFD peer destination address with BFD profile *\*. -``` - -```{cfgcmd} set protocols static route \ next-hop \ bfd multi-hop source-address \ - -Configure a static route for *\* using gateway *\* and use the -gateway address as BFD peer destination address with source address -*\* but initiate a multi-hop session. -``` - - -### DHCP Interface Routes - -```{cfgcmd} set protocols static route \ dhcp-interface \ - -Defines route with DHCP interface supplying next-hop IP address. -``` - - -### IPv4 Reject Routes - -```{cfgcmd} set protocol static route \ reject - -Defines route which emits an ICMP unreachable when matched. -``` - -```{cfgcmd} set protocols static route \ reject distance \ - -Defines distance for this route, routes with smaller administrative -distance are elected prior to those with a higher distance. -``` - -```{cfgcmd} set protocols static route \ reject tag \ - -Sets a tag for this route. -``` - -```{cfgcmd} set protocol static route6 \ reject - -Defines route which emits an ICMP unreachable when matched. -``` - - -### IPv4 Blackhole Routes - -```{cfgcmd} set protocols static route \ blackhole - -Use this command to configure a "black-hole" route on the router. A -black-hole route is a route for which the system silently discard packets -that are matched. This prevents networks leaking out public interfaces, but -it does not prevent them from being used as a more specific route inside your -network. -``` - -```{cfgcmd} set protocols static route \ blackhole distance \ - -Defines blackhole distance for this route, routes with smaller administrative -distance are elected prior to those with a higher distance. -``` - -```{cfgcmd} set protocols static route \ blackhole tag \ - -Sets a tag for this route. -``` - - -## IPv6 Unicast Routes - -```{cfgcmd} set protocols static route6 \ next-hop \ - -Configure next-hop *\* for an IPv6 static route. Multiple static -routes can be created. -``` - -```{cfgcmd} set protocols static route6 \ next-hop \ disable - -Disable this IPv6 static route entry. -``` - -```{cfgcmd} set protocols static route6 \ next-hop \ distance \ - -Defines next-hop distance for this route, routes with smaller administrative -distance are elected prior to those with a higher distance. - -Range is 1 to 255, default is 1. - -:::{note} -Routes with a distance of 255 are effectively disabled and not -installed into the kernel. -::: -``` - -```{cfgcmd} set protocols static route6 \ next-hop \ segments \ - -It is possible to specify a static route for ipv6 prefixes using an -SRv6 segments instruction. The ``/`` separator can be used to specify -multiple segment instructions. - -Example: - -:::{code-block} none -set protocols static route6 2001:db8:1000::/36 next-hop 2001:db8:201::ffff segments '2001:db8:aaaa::7/2002::4/2002::3/2002::2' -::: - -:::{code-block} none -vyos@vyos:~$ show ipv6 route -Codes: K - kernel route, C - connected, S - static, R - RIPng, - O - OSPFv3, I - IS-IS, B - BGP, N - NHRP, T - Table, - v - VNC, V - VNC-Direct, A - Babel, F - PBR, - f - OpenFabric, - > - selected route, * - FIB route, q - queued, r - rejected, b - backup - t - trapped, o - offload failure -C>* 2001:db8:201::/64 is directly connected, eth0.201, 00:00:46 -S>* 2001:db8:1000::/36 [1/0] via 2001:db8:201::ffff, eth0.201, seg6 2001:db8:aaaa::7,2002::4,2002::3,2002::2, weight 1, 00:00:08 -::: -``` - - -### IPv6 Interface Routes - -```{cfgcmd} set protocols static route6 \ interface \ - -Allows you to configure the next-hop interface for an interface-based IPv6 -static route. *\* will be the next-hop interface where traffic is -routed for the given *\*. -``` - -```{cfgcmd} set protocols static route6 \ interface \ disable - -Disables interface-based IPv6 static route. -``` - -```{cfgcmd} set protocols static route6 \ interface \ distance \ - -Defines next-hop distance for this route, routes with smaller administrative -distance are elected prior to those with a higher distance. - -Range is 1 to 255, default is 1. -``` - -```{cfgcmd} set protocols static route6 \ interface \ segments \ - -It is possible to specify a static route for ipv6 prefixes using an -SRv6 segments instruction. The ``/`` separator can be used to specify -multiple segment instructions. - -Example: - -:::{code-block} none -set protocols static route6 2001:db8:1000::/36 interface eth0 segments '2001:db8:aaaa::7/2002::4/2002::3/2002::2' -::: -``` - - -### IPv6 BFD - -```{cfgcmd} set protocols static route6 \ next-hop \ bfd - -Configure a static route for *\* using gateway *\* and use the -gateway address as BFD peer destination address. -``` - -```{cfgcmd} set protocols static route6 \ next-hop \ bfd profile \ - -Configure a static route for *\* using gateway *\* and use the -gateway address as BFD peer destination address with BFD profile *\*. -``` - -```{cfgcmd} set protocols static route6 \ next-hop \ bfd multi-hop source-address \ - -Configure a static route for *\* using gateway *\* and use the -gateway address as BFD peer destination address with source address -*\* but initiate a multi-hop session. -``` - - -### IPv6 Reject Routes - -```{cfgcmd} set protocol static route6 \ reject - -Defines route which emits an ICMP unreachable when matched. -``` - -```{cfgcmd} set protocols static route6 \ reject distance \ - -Defines distance for this route, routes with smaller administrative -distance are elected prior to those with a higher distance. -``` - -```{cfgcmd} set protocols static route6 \ reject tag \ - -Sets a tag for this route. -``` - - -### IPv6 Blackhole Routes - -```{cfgcmd} set protocols static route6 \ blackhole - -Use this command to configure a "black-hole" route on the router. A -black-hole route is a route for which the system silently discard packets -that are matched. This prevents networks leaking out public interfaces, but -it does not prevent them from being used as a more specific route inside your -network. -``` - -```{cfgcmd} set protocols static route6 \ blackhole distance \ - -Defines blackhole distance for this route, routes with smaller administrative -distance are elected prior to those with a higher distance. -``` - -```{cfgcmd} set protocols static route6 \ blackhole tag \ - -Sets a tag for this route. -``` - - -## Alternate Routing Tables - -Alternate routing tables are used with policy based routing by utilizing -{ref}`vrf`. diff --git a/docs/configuration/protocols/md-traffic-engineering.md b/docs/configuration/protocols/md-traffic-engineering.md deleted file mode 100644 index 832023a7..00000000 --- a/docs/configuration/protocols/md-traffic-engineering.md +++ /dev/null @@ -1,54 +0,0 @@ -(traffic-engineering)= - -# Traffic Engineering - -Traffic Engineering (TE) is possibility to send traffic from node to node using -alternative path. - -## Common link parameters - -Traffic Engineering parameters are used for both IS-IS and OSPF (not supported yet). - -```{cfgcmd} set protocols traffic-engineering admin-group \ bit-position \ - -Create Administrative group and assosiate bit position with it. These groups can be -used in the following commands. - -\ can have value 0-31. There cannot be two groups with same bit position. -``` - - -```{cfgcmd} set protocols traffic-engineering interface \ admin-group \ - -Set administrative group for interface \. Multiple values can be provided. -``` - - -```{cfgcmd} set protocols traffic-engineering interface \ max-bandwidth \ - -Set maximum bandwidth for interface \. Value given in Mbits per second. -``` - - -```{cfgcmd} set protocols traffic-engineering interface \ max-reservable-bandwidth \ - -Set maximum reservable bandwidth for interface \. Value given in Mbits per second. -``` - -## IS-IS TE Configuration - -Traffic Engineering (TE) can be enabled and exported for IS-IS -using the following commands: - -```{cfgcmd} set protocols isis traffic-engineering enable - -Enable Traffic Engineering for IS-IS. -``` -```{cfgcmd} set protocols isis traffic-engineering export - -Export Traffic Engineering data to neighbors. -``` -```{cfgcmd} set protocols isis traffic-engineering address \ - -Configure IPv4 address for MPLS-TE. -``` \ No newline at end of file diff --git a/docs/configuration/service/md-broadcast-relay.md b/docs/configuration/service/md-broadcast-relay.md deleted file mode 100644 index 4202ad6b..00000000 --- a/docs/configuration/service/md-broadcast-relay.md +++ /dev/null @@ -1,70 +0,0 @@ -(udp-broadcast-relay)= - -# UDP Broadcast Relay - -Certain vendors use broadcasts to identify their equipment within one ethernet -segment. Unfortunately if you split your network with multiple VLANs you loose -the ability of identifying your equipment. - -This is where "UDP broadcast relay" comes into play! It will forward received -broadcasts to other configured networks. - -Every UDP port which will be forward requires one unique ID. Currently we -support 99 IDs! - -## Configuration - -```{cfgcmd} set service broadcast-relay id \ description \ - -A description can be added for each and every unique relay ID. This is -useful to distinguish between multiple different ports/applications. -``` - -```{cfgcmd} set service broadcast-relay id \ interface \ - -The interface used to receive and relay individual broadcast packets. If you -want to receive/relay packets on both `eth1` and `eth2` both interfaces need -to be added. -``` - -```{cfgcmd} set service broadcast-relay id \ address \ - -Set the source IP of forwarded packets, otherwise original senders address -is used. -``` - -```{cfgcmd} set service broadcast-relay id \ port \ - -The UDP port number used by your application. It is mandatory for this kind -of operation. -``` - -```{cfgcmd} set service broadcast-relay id \ disable - -Each broadcast relay instance can be individually disabled without deleting -the configured node by using the following command: -``` - -```{cfgcmd} set service broadcast-relay disable - -In addition you can also disable the whole service without the need to remove -it from the current configuration. -``` - -:::{note} -You can run the UDP broadcast relay service on multiple routers -connected to a subnet. There is **NO** UDP broadcast relay packet storm! -::: - -## Example - -To forward all broadcast packets received on `UDP port 1900` on `eth3`, `eth4` -or `eth5` to all other interfaces in this configuration. - -```none -set service broadcast-relay id 1 description 'SONOS' -set service broadcast-relay id 1 interface 'eth3' -set service broadcast-relay id 1 interface 'eth4' -set service broadcast-relay id 1 interface 'eth5' -set service broadcast-relay id 1 port '1900' -``` diff --git a/docs/configuration/service/md-config-sync.md b/docs/configuration/service/md-config-sync.md deleted file mode 100644 index a575f947..00000000 --- a/docs/configuration/service/md-config-sync.md +++ /dev/null @@ -1,164 +0,0 @@ -(config-sync)= - -# Config Sync - -Configuration synchronization (config sync) is a feature of VyOS that -permits synchronization of the configuration of one VyOS router to -another in a network. - -The main benefit to configuration synchronization is that it eliminates having -to manually replicate configuration changes made on the primary router to the -secondary (replica) router. - -The writing of the configuration to the secondary router is performed through -the VyOS HTTP API. The user can specify which portion(s) of the configuration will -be synchronized and the mode to use - whether to replace or add. - -To prevent issues with divergent configurations between the pair of routers, -synchronization is strictly unidirectional from primary to replica. Both -routers should be online and run the same version of VyOS. - -## Configuration - -```{cfgcmd} set service config-sync secondary \ - -Specify the address, API key, timeout and port of the secondary router. -You need to enable and configure the HTTP API service on the secondary -router for config sync to operate. -``` - -```{cfgcmd} set service config-sync section \ - -Specify the section of the configuration to synchronize. If more than one -section is to be synchronized, repeat the command to add additional -sections as required. -``` - -```{cfgcmd} set service config-sync mode \ - -Two options are available for *mode*: either *load* and replace or *set* -the configuration section. -``` - -```none -Supported options for
include: - firewall - interfaces - nat - nat66 - pki - policy - protocols - qos - service - system - vpn - vrf -``` - - -## Operational Commands - -````{opcmd} show configuration secondary sync [commands] [running | candidate | saved] [\] - -Display configuration differences between the local node and -a config-sync secondary node. - -This command allows operators to compare configurations across nodes -participating in configuration synchronization (e.g., primary and -secondary routers). It helps detect configuration drift and validate -intended changes before synchronization. - -**Parameters:** - -```{eval-rst} -.. list-table:: - :widths: 30 70 - :header-rows: 0 - - * - ``commands`` (optional) - - Show output as a list of configuration commands instead of raw diff. - * - ``running|candidate|saved`` (optional, mutually exclusive) - - Select which configuration to compare: - ``running`` (current active configuration, default), - ``candidate`` (uncommitted changes), or - ``saved`` (last saved configuration). Only one of these may be - specified at a time; if omitted, ``running`` is used. -``` - -**Examples:** - -:::{code-block} none -# compare full running configuration with a secondary node -show configuration secondary sync - -# compare only interface configuration -show configuration secondary sync running interfaces dummy - -# compare candidate configuration and display as a list of commands -show configuration secondary sync commands candidate -::: -```` - -Without a built-in cross-node diff, operators may unintentionally push -changes that conflict with the remote configuration (e.g., mismatched -interfaces, firewall policies, or protocol settings). - - -## Example - -- Synchronize the time-zone and OSPF configuration from Router A to Router B -- The address of Router B is 10.0.20.112 and the port used is 8443 - -Configure the HTTP API service on Router B - -```none -set service https listen-address '10.0.20.112' -set service https port '8443' -set service https api keys id KID key 'foo' -set service https api rest -``` - -Configure the config-sync service on Router A - -```none -set service config-sync mode 'load' -set service config-sync secondary address '10.0.20.112' -set service config-sync secondary port '8443' -set service config-sync secondary key 'foo' -set service config-sync section protocols 'ospf' -set service config-sync section system 'time-zone' -``` - -Make config-sync relevant changes to Router A's configuration - -```none -vyos@vyos-A# set system time-zone 'America/Los_Angeles' -vyos@vyos-A# commit -INFO:vyos_config_sync:Config synchronization: Mode=load, -Secondary=10.0.20.112 -vyos@vyos-A# save - -vyos@vyos-A# set protocols ospf area 0 network '10.0.48.0/30' -vyos@vyos-A# commit -INFO:vyos_config_sync:Config synchronization: Mode=load, -Secondary=10.0.20.112 -yos@vyos-A# save -``` - -Verify configuration changes have been replicated to Router B - -```none -vyos@vyos-B:~$ show configuration commands | match time-zone -set system time-zone 'America/Los_Angeles' - -vyos@vyos-B:~$ show configuration commands | match ospf -set protocols ospf area 0 network '10.0.48.0/30' -``` - - -## Known issues - -Configuration resynchronization. With the current implementation of *service -config-sync*, the secondary node must be online. diff --git a/docs/configuration/service/md-conntrack-sync.md b/docs/configuration/service/md-conntrack-sync.md deleted file mode 100644 index 47a0ae2f..00000000 --- a/docs/configuration/service/md-conntrack-sync.md +++ /dev/null @@ -1,321 +0,0 @@ -(conntrack-sync)= - -# Conntrack Sync - -One of the important features built on top of the Netfilter framework is -connection tracking. Connection tracking allows the kernel to keep track of all -logical network connections or sessions, and thereby relate all of the packets -which may make up that connection. NAT relies on this information to translate -all related packets in the same way, and iptables can use this information to -act as a stateful firewall. - -The connection state however is completely independent of any upper-level -state, such as TCP's or SCTP's state. Part of the reason for this is that when -merely forwarding packets, i.e. no local delivery, the TCP engine may not -necessarily be invoked at all. Even connectionless-mode transmissions such as -UDP, IPsec (AH/ESP), GRE and other tunneling protocols have, at least, a pseudo -connection state. The heuristic for such protocols is often based upon a preset -timeout value for inactivity, after whose expiration a Netfilter connection is -dropped. - -Each Netfilter connection is uniquely identified by a (layer-3 protocol, source -address, destination address, layer-4 protocol, layer-4 key) tuple. The layer-4 -key depends on the transport protocol; for TCP/UDP it is the port numbers, for -tunnels it can be their tunnel ID, but otherwise is just zero, as if it were -not part of the tuple. To be able to inspect the TCP port in all cases, packets -will be mandatorily defragmented. - -It is possible to use either Multicast or Unicast to sync conntrack traffic. -Most examples below show Multicast, but unicast can be specified by using the -"peer" keywork after the specified interface, as in the following example: - -{cfgcmd}`set service conntrack-sync interface eth0 peer 192.168.0.250` - -## Configuration - -```{cfgcmd} set service conntrack-sync accept-protocol - -Accept only certain protocols: You may want to replicate the state of flows -depending on their layer 4 protocol. - -Protocols are: tcp, sctp, dccp, udp, icmp and ipv6-icmp. -``` - - -```{cfgcmd} set service conntrack-sync event-listen-queue-size \ - -The daemon doubles the size of the netlink event socket buffer size if it -detects netlink event message dropping. This clause sets the maximum buffer -size growth that can be reached. - -Queue size for listening to local conntrack events in MB. -``` - - -```{cfgcmd} set service conntrack-sync expect-sync \ - -Protocol for which expect entries need to be synchronized. -``` - - -```{cfgcmd} set service conntrack-sync failover-mechanism vrrp sync-group \ - -Failover mechanism to use for conntrack-sync. - -Only VRRP is supported. Required option. -``` - - -```{cfgcmd} set service conntrack-sync ignore-address \ - -IP addresses or networks for which local conntrack entries will not be synced -``` - - -```{cfgcmd} set service conntrack-sync interface \ - -Interface to use for syncing conntrack entries. -``` - - -```{cfgcmd} set service conntrack-sync interface \ port \ - -Port number used by connection. -``` - - -```{cfgcmd} set service conntrack-sync listen-address \ - -Local IPv4 addresses for service to listen on. -``` - - -```{cfgcmd} set service conntrack-sync mcast-group \ - -Multicast group to use for syncing conntrack entries. - -Defaults to 225.0.0.50. -``` - - -```{cfgcmd} set service conntrack-sync interface \ peer \ - -Peer to send unicast UDP conntrack sync entires to, if not using Multicast -configuration from above above. -``` - - -```{cfgcmd} set service conntrack-sync sync-queue-size \ - -Queue size for syncing conntrack entries in MB. -``` - - -```{cfgcmd} set service conntrack-sync disable-external-cache - -This diable the external cache and directly injects the flow-states into the -in-kernel Connection Tracking System of the backup firewall. -``` - - -```{cfgcmd} set service conntrack-sync purge-timeout \ - -Timeout (in seconds) for purging synchronized entries on handover events. - -On handover, ``conntrackd -t`` is invoked, which schedules a conntrack table -flush after ```` seconds to purge stale (“zombie”) entries and -reduce clashes when multiple handovers occur in a short period. -The default is 60 seconds. -``` - -:::{note} -In VRRP stateful firewall deployments, align VRRP timing with this -behavior: because synchronized conntrack state is purged after the purge -timeout, set **VRRP preempt-delay** to ≥ **purge-timeout** so mastership -can be restored before conntrack state is purged. -::: - -```{cfgcmd} set service conntrack-sync disable-syslog - -Disable connection logging via Syslog. -``` - - -```{cfgcmd} set service conntrack-sync startup-resync - -Order conntrackd to request a complete conntrack table resync against -the other node at startup. -``` - -## Operation - -```{opcmd} show conntrack table ipv4 - -Make sure conntrack is enabled by running and show connection tracking table. - -:::{code-block} none -vyos@vyos:~$ show conntrack table ipv4 -TCP state codes: SS - SYN SENT, SR - SYN RECEIVED, ES - ESTABLISHED, -FW - FIN WAIT, CW - CLOSE WAIT, LA - LAST ACK, -TW - TIME WAIT, CL - CLOSE, LI - LISTEN - -CONN ID Source Destination Protocol TIMEOUT -1015736576 10.35.100.87:58172 172.31.20.12:22 tcp [6] ES 430279 -1006235648 10.35.101.221:57483 172.31.120.21:22 tcp [6] ES 413310 -1006237088 10.100.68.100 172.31.120.21 icmp [1] 29 -1015734848 10.35.100.87:56282 172.31.20.12:22 tcp [6] ES 300 -1015734272 172.31.20.12:60286 239.10.10.14:694 udp [17] 29 -1006239392 10.35.101.221 172.31.120.21 icmp [1] 29 -::: -:::{note} -If the table is empty and you have a warning message, it means -conntrack is not enabled. To enable conntrack, just create a NAT or a firewall -rule. {cfgcmd}`set firewall state-policy established action accept` -::: -``` - - -```{opcmd} show conntrack-sync cache external - -Show connection syncing external cache entries -``` - - -```{opcmd} show conntrack-sync cache internal - -Show connection syncing internal cache entries -``` - - -```{opcmd} show conntrack-sync statistics - -Retrieve current statistics of connection tracking subsystem. - -:::{code-block} none -vyos@vyos:~$ show conntrack-sync statistics -Main Table Statistics: - -cache internal: -current active connections: 19606 -connections created: 6298470 failed: 0 -connections updated: 3786793 failed: 0 -connections destroyed: 6278864 failed: 0 - -cache external: -current active connections: 15771 -connections created: 1660193 failed: 0 -connections updated: 77204 failed: 0 -connections destroyed: 1644422 failed: 0 - -traffic processed: -0 Bytes 0 Pckts - -multicast traffic (active device=eth0.5): -976826240 Bytes sent 212898000 Bytes recv -8302333 Pckts sent 2009929 Pckts recv -0 Error send 0 Error recv - -message tracking: -0 Malformed msgs 263 Lost msgs -::: -``` -```{opcmd} show conntrack-sync status - -Retrieve current status of connection tracking subsystem. - -:::{code-block} none -vyos@vyos:~$ show conntrack-sync status -sync-interface : eth0.5 -failover-mechanism : vrrp [sync-group GEFOEKOM] -last state transition : no transition yet! -ExpectationSync : disabled -::: -``` - -## Example - -The next example is a simple configuration of conntrack-sync. - -:::{figure} /_static/images/service_conntrack_sync-schema.webp -:alt: Conntrack Sync Example -:scale: 60 % -::: - -Now configure conntrack-sync service on `router1` **and** `router2` - -```none -set high-availability vrrp group internal virtual-address ... etc ... -set high-availability vrrp sync-group syncgrp member 'internal' -set service conntrack-sync accept-protocol 'tcp' -set service conntrack-sync accept-protocol 'udp' -set service conntrack-sync accept-protocol 'icmp' -set service conntrack-sync failover-mechanism vrrp sync-group 'syncgrp' -set service conntrack-sync interface 'eth0' -set service conntrack-sync mcast-group '225.0.0.50' -``` - -On the active router, you should have information in the internal-cache of -conntrack-sync. The same current active connections number should be shown in -the external-cache of the standby router - -On active router run: - -```none -$ show conntrack-sync statistics - -Main Table Statistics: - -cache internal: -current active connections: 10 -connections created: 8517 failed: 0 -connections updated: 127 failed: 0 -connections destroyed: 8507 failed: 0 - -cache external: -current active connections: 0 -connections created: 0 failed: 0 -connections updated: 0 failed: 0 -connections destroyed: 0 failed: 0 - -traffic processed: - 0 Bytes 0 Pckts - -multicast traffic (active device=eth0): - 868780 Bytes sent 224136 Bytes recv - 20595 Pckts sent 14034 Pckts recv - 0 Error send 0 Error recv - -message tracking: - 0 Malformed msgs 0 Lost msgs -``` - -On standby router run: - -```none -$ show conntrack-sync statistics - -Main Table Statistics: - -cache internal: -current active connections: 0 -connections created: 0 failed: 0 -connections updated: 0 failed: 0 -connections destroyed: 0 failed: 0 - -cache external: -current active connections: 10 -connections created: 888 failed: 0 -connections updated: 134 failed: 0 -connections destroyed: 878 failed: 0 - -traffic processed: - 0 Bytes 0 Pckts - -multicast traffic (active device=eth0): - 234184 Bytes sent 907504 Bytes recv - 14663 Pckts sent 21495 Pckts recv - 0 Error send 0 Error recv - -message tracking: - 0 Malformed msgs 0 Lost msgs -``` diff --git a/docs/configuration/service/md-console-server.md b/docs/configuration/service/md-console-server.md deleted file mode 100644 index 9402e935..00000000 --- a/docs/configuration/service/md-console-server.md +++ /dev/null @@ -1,139 +0,0 @@ -(console-server)= - -# Console Server - -Starting of with VyOS 1.3 (equuleus) we added support for running VyOS as an -Out-of-Band Management device which provides remote access by means of SSH to -directly attached serial interfaces. - -Serial interfaces can be any interface which is directly connected to the CPU -or chipset (mostly known as a ttyS interface in Linux) or any other USB to -serial converter (Prolific PL2303 or FTDI FT232/FT4232 based chips). - -If you happened to use a Cisco NM-16A - Sixteen Port Async Network Module or -NM-32A - Thirty-two Port Async Network Module - this is your VyOS replacement. - -For USB port information please refor to: {ref}`hardware_usb`. - -## Configuration - -Between computers, the most common configuration used was "8N1": eight bit -characters, with one start bit, one stop bit, and no parity bit. Thus 10 Baud -times are used to send a single character, and so dividing the signalling -bit-rate by ten results in the overall transmission speed in characters per -second. This is also the default setting if none of those options are defined. - -```{cfgcmd} set service console-server device \ data-bits [7 | 8] - -Configure either seven or eight data bits. This defaults to eight data -bits if left unconfigured. -``` - - -```{cfgcmd} set service console-server device \ description \ - -A user friendly description identifying the connected peripheral. -``` - - -```{cfgcmd} set service console-server device \ alias \ - -A user friendly alias for this connection. Can be used instead of the -device name when connecting. -``` - - -```{cfgcmd} set service console-server device \ parity [even | odd | none] - -Set the parity option for the console. If unset this will default to none. -``` - - -```{cfgcmd} set service console-server device \ stop-bits [1 | 2] - -Configure either one or two stop bits. This defaults to one stop bits if -left unconfigured. -``` - - -```{cfgcmd} set service console-server device \ speed [ 300 | 1200 | 2400 | 4800 | 9600 | 19200 | 38400 | 57600 | 115200 ] - -:::{note} -USB to serial converters will handle most of their work in software -so you should be carefull with the selected baudrate as some times they -can't cope with the expected speed. -::: -``` - -### Remote Access - - -Each individual configured console-server device can be directly exposed to -the outside world. A user can directly connect via SSH to the configured -port. - -```{cfgcmd} set service console-server device \ ssh port \ - -Accept SSH connections for the given `` on TCP port ``. -After successfull authentication the user will be directly dropped to -the connected serial device. - -:::{hint} -Multiple users can connect to the same serial device but only -one is allowed to write to the console port. -::: -``` - -## Operation - -```{opcmd} show console-server ports - -Show configured serial ports and their respective interface configuration. - -:::{code-block} none -vyos@vyos:~$ show console-server ports -usb0b2.4p1.0 on /dev/serial/by-bus/usb0b2.4p1.0@ at 9600n -::: -``` - - -```{opcmd} show console-server user - -Show currently connected users. - -:::{code-block} none -vyos@vyos:~$ show console-server user -usb0b2.4p1.0 up vyos@localhost -::: -``` -```{opcmd} connect console \ - -Locally connect to serial port identified by ``. - -:::{code-block} none -vyos@vyos-r1:~$ connect console usb0b2.4p1.0 -[Enter `^Ec?' for help] -[-- MOTD -- VyOS Console Server] - -vyos-r2 login: -::: - -:::{hint} -Multiple users can connect to the same serial device but only -one is allowed to write to the console port. -::: - -:::{hint} -The sequence ``^Ec?`` translates to: ``Ctrl+E c ?``. To quit -the session use: ``Ctrl+E c .`` -::: - -:::{hint} -If ``alias`` is set, it can be used instead of the device when -connecting. -::: -``` -```{opcmd} show log console-server - -Show the console server log. -``` \ No newline at end of file diff --git a/docs/configuration/service/md-dhcp-relay.md b/docs/configuration/service/md-dhcp-relay.md deleted file mode 100644 index a4a10109..00000000 --- a/docs/configuration/service/md-dhcp-relay.md +++ /dev/null @@ -1,205 +0,0 @@ -(dhcp-relay)= - -# DHCP Relay - -If you want your router to forward DHCP requests to an external DHCP server -you can configure the system to act as a DHCP relay agent. The DHCP relay -agent works with IPv4 and IPv6 addresses. - -All interfaces used for the DHCP relay must be configured. This includes the -uplink to the DHCP server. - -## IPv4 relay - -### Configuration - -```{cfgcmd} set service dhcp-relay interface \ - -Interfaces that participate in the DHCP relay process. If this command is -used, at least two entries of it are required: one for the interface that -captures the dhcp-requests, and one for the interface to forward such -requests. A warning message will be shown if this command is used, since -new implementations should use ``listen-interface`` and -``upstream-interface``. -``` - -```{cfgcmd} set service dhcp-relay listen-interface \ - -Interface for DHCP Relay Agent to listen for requests. -``` - -```{cfgcmd} set service dhcp-relay upstream-interface \ - -Interface for DHCP Relay Agent to forward requests out. -``` - -```{cfgcmd} set service dhcp-relay server \ - -Configure IP address of the DHCP `` which will handle the relayed -packets. -``` - -```{cfgcmd} set service dhcp-relay relay-options relay-agents-packets discard - -The router should discard DHCP packages already containing relay agent -information to ensure that only requests from DHCP clients are forwarded. -``` - -```{cfgcmd} set service dhcp-relay disable - -Disable dhcp-relay service. -``` - - -#### Options - -```{cfgcmd} set service dhcp-relay relay-options hop-count \ - -Set the maximum hop `` before packets are discarded. Range 0...255, -default 10. -``` - -```{cfgcmd} set service dhcp-relay relay-options max-size \ - -Set maximum `` of DHCP packets including relay agent information. If a -DHCP packet size surpasses this value it will be forwarded without appending -relay agent information. Range 64...1400, default 576. -``` - -```{cfgcmd} set service dhcp-relay relay-options relay-agents-packets \ - -Four policies for reforwarding DHCP packets exist: -* **append:** The relay agent is allowed to append its own relay information -to a received DHCP packet, disregarding relay information already present -in the packet. -* **discard:** Received packets which already contain relay information will -be discarded. -* **forward:** All packets are forwarded, relay information already present -will be ignored. -* **replace:** Relay information already present in a packet is stripped and -replaced with the router's own relay information set. -``` - - -### Example - -- Listen for DHCP requests on interface `eth1`. -- DHCP server is located at IPv4 address 10.0.1.4 on `eth2`. -- Router receives DHCP client requests on `eth1` and relays them to the - server at 10.0.1.4 on `eth2`. - -:::{figure} /_static/images/service_dhcp-relay01.webp -:alt: DHCP relay example -:scale: 80 % -DHCP relay example -::: - -The generated configuration will look like: - -```none -show service dhcp-relay - listen-interface eth1 - upstream-interface eth2 - server 10.0.1.4 - relay-options { - relay-agents-packets discard - } -``` - -Also, for backwards compatibility this configuration, which uses generic -interface definition, is still valid: - -```none -show service dhcp-relay - interface eth1 - interface eth2 - server 10.0.1.4 - relay-options { - relay-agents-packets discard - } -``` - - -### Operation - -```{opcmd} restart dhcp relay-agent - -Restart DHCP relay service -``` - - -## IPv6 relay - -(dhcp-relay-ipv6-configuration)= - -### Configuration - -```{cfgcmd} set service dhcpv6-relay listen-interface \ - -Set eth1 to be the listening interface for the DHCPv6 relay. - -Multiple interfaces may be specified. -``` - -```{cfgcmd} set service dhcpv6-relay upstream-interface \ address \ - -Specifies an upstream network `` from which replies from -`` and other relay agents will be accepted. -``` - -(dhcp-relay-ipv6-options)= - -```{cfgcmd} set service dhcpv6-relay disable - -Disable dhcpv6-relay service. -``` - -(dhcp-relay-v6-options)= - -#### Options - -```{cfgcmd} set service dhcpv6-relay max-hop-count \ - -Set maximum hop count before packets are discarded, default: 10 -``` - -```{cfgcmd} set service dhcpv6-relay use-interface-id-option - -If this is set the relay agent will insert the interface ID. This option is -set automatically if more than one listening interfaces are in use. -``` - -(dhcp-relay-ipv6-example)= - -### Example - -- DHCPv6 requests are received by the router on `listening interface` `eth1` -- Requests are forwarded through `eth2` as the `upstream interface` -- External DHCPv6 server is at 2001:db8::4 - -:::{figure} /_static/images/service_dhcpv6-relay01.webp -:alt: DHCPv6 relay example -:scale: 80 % -DHCPv6 relay example -::: - -The generated configuration will look like: - -```none -commit -show service dhcpv6-relay - listen-interface eth1 { - } - upstream-interface eth2 { - address 2001:db8::4 - } -``` - -(dhcp-relay-ipv6-op-cmd)= - -### Operation - -```{opcmd} restart dhcpv6 relay-agent - -Restart DHCPv6 relay agent immediately. -``` \ No newline at end of file diff --git a/docs/configuration/service/md-dhcp-server.md b/docs/configuration/service/md-dhcp-server.md deleted file mode 100644 index 96c375da..00000000 --- a/docs/configuration/service/md-dhcp-server.md +++ /dev/null @@ -1,1178 +0,0 @@ -(dhcp-server)= - -# DHCP Server - -VyOS uses Kea DHCP server for both IPv4 and IPv6 address assignment. - -## IPv4 server - -The network topology is declared by shared-network-name and the subnet -declarations. The DHCP service can serve multiple shared networks, with each -shared network having 1 or more subnets. Each subnet must be present on an -interface. A range can be declared inside a subnet to define a pool of dynamic -addresses. Multiple ranges can be defined and can contain holes. Static -mappings can be set to assign "static" addresses to clients based on their MAC -address. - -### Configuration - -```{cfgcmd} set service dhcp-server hostfile-update - - Create DNS record per client lease, by adding clients to /etc/hosts file. - Entry will have format: `_.` -``` - - -```{cfgcmd} set service dhcp-server shared-network-name \ option domain-name \ - -The domain-name parameter should be the domain name that will be appended to -the client's hostname to form a fully-qualified domain-name (FQDN) (DHCP -Option 015). - -This is the configuration parameter for the entire shared network definition. -All subnets will inherit this configuration item if not specified locally. -``` - - -```{cfgcmd} set service dhcp-server shared-network-name \ option domain-search \ - -The domain-name parameter should be the domain name used when completing DNS -request where no full FQDN is passed. This option can be given multiple times -if you need multiple search domains (DHCP Option 119). - -This is the configuration parameter for the entire shared network definition. -All subnets will inherit this configuration item if not specified locally. -``` - - -```{cfgcmd} set service dhcp-server shared-network-name \ option name-server \ - -Inform client that the DNS server can be found at `
`. - -This is the configuration parameter for the entire shared network definition. -All subnets will inherit this configuration item if not specified locally. -Multiple DNS servers can be defined. -``` - - -```{cfgcmd} set service dhcp-server shared-network-name \ option vendor-option \ - -This configuration parameter lets you specify a vendor-option for the -entire shared network definition. All subnets will inherit this -configuration item if not specified locally. An example for Ubiquiti is -shown below: -``` - -**Example:** - - -Pass address of Unifi controller at `172.16.100.1` to all clients of `NET1` - -```none -set service dhcp-server shared-network-name 'NET1' option vendor-option -ubiquiti '172.16.100.1' -``` - - -```{cfgcmd} set service dhcp-server listen-address \ - -This configuration parameter lets the DHCP server to listen for DHCP -requests sent to the specified address, it is only realistically useful for -a server whose only clients are reached via unicasts, such as via DHCP relay -agents. -``` - -#### Individual Client Subnet - -```{cfgcmd} set service dhcp-server shared-network-name \ authoritative - -This says that this device is the only DHCP server for this network. If other -devices are trying to offer DHCP leases, this machine will send 'DHCPNAK' to -any device trying to request an IP address that is not valid for this -network. -``` - - -```{cfgcmd} set service dhcp-server shared-network-name \ subnet \ subnet-id \ - -This configuration parameter is required and must be unique to each subnet. -It is required to map subnets to lease file entries. -``` - - -```{cfgcmd} set service dhcp-server shared-network-name \ subnet \ option default-router \ - -This is a configuration parameter for the ``, saying that as part of -the response, tell the client that the default gateway can be reached at -`
`. -``` - - -```{cfgcmd} set service dhcp-server shared-network-name \ subnet \ option name-server \ - -This is a configuration parameter for the subnet, saying that as part of the -response, tell the client that the DNS server can be found at `
`. - -Multiple DNS servers can be defined. -``` - - -```{cfgcmd} set service dhcp-server shared-network-name \ subnet \ lease \ - -Assign the IP address to this machine for `