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/configuration/highavailability/md-index.md | 561 ++++++++++++++++++++++++ 1 file changed, 561 insertions(+) create mode 100644 docs/configuration/highavailability/md-index.md (limited to 'docs/configuration/highavailability') diff --git a/docs/configuration/highavailability/md-index.md b/docs/configuration/highavailability/md-index.md new file mode 100644 index 00000000..e26f5791 --- /dev/null +++ b/docs/configuration/highavailability/md-index.md @@ -0,0 +1,561 @@ +--- +lastproofread: '2021-06-30' +--- + +(high-availability)= + +# High availability + +VRRP (Virtual Router Redundancy Protocol) provides active/backup redundancy for +routers. Every VRRP router has a physical IP/IPv6 address, and a virtual +address. On startup, routers elect the master, and the router with the highest +priority becomes the master and assigns the virtual address to its interface. +All routers with lower priorities become backup routers. The master then starts +sending keepalive packets to notify other routers that it's available. If the +master fails and stops sending keepalive packets, the router with the next +highest priority becomes the new master and takes over the virtual address. + +VRRP keepalive packets use multicast, and VRRP setups are limited to a single +datalink layer segment. You can setup multiple VRRP groups +(also called virtual routers). Virtual routers are identified by a +VRID (Virtual Router IDentifier). If you setup multiple groups on the same +interface, their VRIDs must be unique if they use the same address family, +but it's possible (even if not recommended for readability reasons) to use +duplicate VRIDs on different interfaces. + +## Basic setup + +VRRP groups are created with the +`set high-availability vrrp group $GROUP_NAME` commands. The required +parameters are interface, vrid, and address. + +minimal config + +```none +set high-availability vrrp group Foo vrid 10 +set high-availability vrrp group Foo interface eth0 +set high-availability vrrp group Foo address 192.0.2.1/24 +``` + +You can verify your VRRP group status with the operational mode +`run show vrrp` command: + +```none +vyos@vyos# run show vrrp +Name Interface VRID State Last Transition +---------- ----------- ------ ------- ----------------- +Foo eth1 10 MASTER 2s +``` + +## IPv6 support + +The `address` parameter can be either an IPv4 or IPv6 address, but you can +not mix IPv4 and IPv6 in the same group, and will need to create groups with +different VRIDs specially for IPv4 and IPv6. +If you want to use IPv4 + IPv6 address you can use option `excluded-address` + +## Address + +The `address` can be configured either on the VRRP interface or on not VRRP +interface. + +```none +set high-availability vrrp group Foo address 192.0.2.1/24 +set high-availability vrrp group Foo address 203.0.113.22/24 interface eth2 +set high-availability vrrp group Foo address 198.51.100.33/24 interface eth3 +``` + +## Disabling a VRRP group + +You can disable a VRRP group with `disable` option: + +```none +set high-availability vrrp group Foo disable +``` + +A disabled group will be removed from the VRRP process and your router will not +participate in VRRP for that VRID. It will disappear from operational mode +commands output, rather than enter the backup state. + +## Exclude address + +Exclude IP addresses from `VRRP packets`. This option `excluded-address` is +used when you want to set IPv4 + IPv6 addresses on the same virtual interface +or when used more than 20 IP addresses. + +```none +set high-availability vrrp group Foo excluded-address '203.0.113.254/24' +set high-availability vrrp group Foo excluded-address '2001:db8:aa::1/64' +set high-availability vrrp group Foo excluded-address '2001:db8:22::1/64' +``` + +## Setting VRRP group priority + +VRRP priority can be set with `priority` option: + +```none +set high-availability vrrp group Foo priority 200 +``` + +The priority must be an integer number from 1 to 255. Higher priority value +increases router's precedence in the master elections. + +## Sync groups + +A sync group allows VRRP groups to transition together. + +```none +edit high-availability vrrp +set sync-group MAIN member VLAN9 +set sync-group MAIN member VLAN20 +``` + +In the following example, when VLAN9 transitions, VLAN20 will also transition: + +```none +vrrp { + group VLAN9 { + interface eth0.9 + address 10.9.1.1/24 + priority 200 + vrid 9 + } + group VLAN20 { + interface eth0.20 + priority 200 + address 10.20.20.1/24 + vrid 20 + } + sync-group MAIN { + member VLAN20 + member VLAN9 + } +} +``` + +:::{warning} +All items in a sync group should be similarly configured. +If one VRRP group is set to a different preemption delay or priority, +it would result in an endless transition loop. +::: + +## Preemption + +VRRP can use two modes: preemptive and non-preemptive. In the preemptive mode, +if a router with a higher priority fails and then comes back, routers with lower +priority will give up their master status. In non-preemptive mode, the newly +elected master will keep the master status and the virtual address indefinitely. + +By default VRRP uses preemption. You can disable it with the "no-preempt" +option: + +```none +set high-availability vrrp group Foo no-preempt +``` + +You can also configure the time interval for preemption with the "preempt-delay" +option. For example, to set the higher priority router to take over in 180 +seconds, use: + +```none +set high-availability vrrp group Foo preempt-delay 180 +``` + +## Track + +Track option to track non VRRP interface states. VRRP changes status to +`FAULT` if one of the track interfaces in state `down`. + +```none +set high-availability vrrp group Foo track interface eth0 +set high-availability vrrp group Foo track interface eth1 +``` + +Ignore VRRP main interface faults + +```none +set high-availability vrrp group Foo track exclude-vrrp-interface +``` + +## Unicast VRRP + +By default VRRP uses multicast packets. If your network does not support +multicast for whatever reason, you can make VRRP use unicast communication +instead. + +```none +set high-availability vrrp group Foo peer-address 192.0.2.10 +set high-availability vrrp group Foo hello-source-address 192.0.2.15 +``` + +## rfc3768-compatibility + +RFC 3768 defines a virtual MAC address to each VRRP virtual router. +This virtual router MAC address will be used as the source in all periodic VRRP +messages sent by the active node. When the rfc3768-compatibility option is set, +a new VRRP interface is created, to which the MAC address and the virtual IP +address is automatically assigned. + +```none +set high-availability vrrp group Foo rfc3768-compatibility +``` + +Verification + +```none +$show interfaces ethernet eth0v10 +eth0v10@eth0: mtu 1500 qdisc noqueue +state UP group default qlen 1000 +link/ether 00:00:5e:00:01:0a brd ff:ff:ff:ff:ff:ff +inet 172.25.0.247/16 scope global eth0v10 +valid_lft forever preferred_lft forever +``` + +:::{warning} +RFC 3768 creates a virtual interface. If you want to apply +the destination NAT rule to the traffic sent to the virtual MAC, set +the created virtual interface as `inbound-interface`. +::: + +## Global options + +On most scenarios, there's no need to change specific parameters, and using +default configuration is enough. But there are cases were extra configuration +is needed. + +```{eval-rst} +.. cfgcmd:: set high-availability vrrp global-parameters startup_delay <1-600> + + This option specifies a delay in seconds before vrrp instances start up + after keepalived starts. +``` + +## Gratuitous ARP + +These configuration is not mandatory and in most cases there's no +need to configure it. But if necessary, Gratuitous ARP can be configured in +`global-parameters` and/or in `group` section. + +```{eval-rst} +.. cfgcmd:: set high-availability vrrp global-parameters garp interval + <0.000-1000> +``` + +```{eval-rst} +.. cfgcmd:: set high-availability vrrp group garp interval <0.000-1000> + + Set delay between gratuitous ARP messages sent on an interface. + + 0 if not defined. +``` + +% stop_vyoslinter + +```{eval-rst} +.. cfgcmd:: set high-availability vrrp global-parameters garp master-delay <1-255> +``` + +% start_vyoslinter + +```{eval-rst} +.. cfgcmd:: set high-availability vrrp group garp master-delay <1-255> + + Set delay for second set of gratuitous ARPs after transition to MASTER. + + 5 if not defined. +``` + +```{eval-rst} +.. cfgcmd:: set high-availability vrrp global-parameters garp master-refresh + <1-600> +``` + +```{eval-rst} +.. cfgcmd:: set high-availability vrrp group garp master-refresh + <1-600> + + Set minimum time interval for refreshing gratuitous ARPs while MASTER. + + 0 if not defined, which means no refreshing. +``` + +```{eval-rst} +.. cfgcmd:: set high-availability vrrp global-parameters garp + master-refresh-repeat <1-600> +``` + +```{eval-rst} +.. cfgcmd:: set high-availability vrrp group garp + master-refresh-repeat <1-600> + + Set number of gratuitous ARP messages to send at a time while MASTER. + + 1 if not defined. +``` + +```{eval-rst} +.. cfgcmd:: set high-availability vrrp global-parameters garp master-repeat + <1-600> +``` + +```{eval-rst} +.. cfgcmd:: set high-availability vrrp group garp master-repeat + <1-600> + + Set number of gratuitous ARP messages to send at a time after transition to + MASTER. + + 5 if not defined. +``` + +## Version + +```{eval-rst} +.. cfgcmd:: set high-availability vrrp global-parameters version 2|3 + + Set the default VRRP version to use. This defaults to 2, but IPv6 instances + will always use version 3. +``` + +## Scripting + +VRRP functionality can be extended with scripts. VyOS supports two kinds of +scripts: health check scripts and transition scripts. Health check scripts +execute custom checks in addition to the master router reachability. Transition +scripts are executed when VRRP state changes from master to backup or fault and +vice versa and can be used to enable or disable certain services, for example. + +:::{note} +Simply placing script files in `/config/scripts/` does not mean the +system can execute them. To make custom scripts executable, grant them +**execute permissions**. Use the following command: + +```none +chmod +x /config/scripts/script-name.sh +``` +::: + +:::{warning} +It is not recommended to change VRRP configuration +inside health-check and transition scripts. +::: + +### Health check scripts + +There is the ability to run an arbitrary script at regular intervals +according to health-check parameters. If a script returns 0, it +indicates success. If a script returns anything else, it will indicate +that the VRRP instance should enter the FAULT state. + +This setup will make the VRRP process execute the +`/config/scripts/vrrp-check.sh script` every 60 seconds, and transition the +group to the fault state if it fails (i.e. exits with non-zero status) three +times: + +% stop_vyoslinter + +```none +set high-availability vrrp group Foo health-check script /config/scripts/vrrp-check.sh +set high-availability vrrp group Foo health-check interval 60 +set high-availability vrrp group Foo health-check failure-count 3 +``` + +% start_vyoslinter + +An optional `timeout` can be set to define the maximum number of seconds the +script is allowed to run. This is useful for scripts that may hang or take +longer than expected — setting the timeout higher than the interval allows +longer-running scripts to complete before being considered failed. + +% stop_vyoslinter + +```none +set high-availability vrrp group Foo health-check script /config/scripts/vrrp-check.sh +set high-availability vrrp group Foo health-check interval 20 +set high-availability vrrp group Foo health-check failure-count 3 +set high-availability vrrp group Foo health-check timeout 40 +``` + +% start_vyoslinter + +When the vrrp group is a member of the sync group will use only +the sync group health check script. +This example shows how to configure it for the sync group: + +% stop_vyoslinter + +```none +set high-availability vrrp sync-group Bar health-check script /config/scripts/vrrp-check.sh +set high-availability vrrp sync-group Bar health-check interval 60 +set high-availability vrrp sync-group Bar health-check failure-count 3 +``` + +% start_vyoslinter + +### Transition scripts + +Transition scripts can help you implement various fixups, such as starting and +stopping services, or even modifying the VyOS config on VRRP transition. +This setup will make the VRRP process execute the +`/config/scripts/vrrp-fail.sh` with argument `Foo` when VRRP fails, +and the `/config/scripts/vrrp-master.sh` when the router becomes the master: + +% stop_vyoslinter + +```none +set high-availability vrrp group Foo transition-script backup "/config/scripts/vrrp-fail.sh Foo" +set high-availability vrrp group Foo transition-script fault "/config/scripts/vrrp-fail.sh Foo" +set high-availability vrrp group Foo transition-script master "/config/scripts/vrrp-master.sh Foo" +``` + +% start_vyoslinter + +To know more about scripting, check the {ref}`command-scripting` section. + +## Virtual-server + +```{eval-rst} +.. include:: /_include/need_improvement.txt +``` + +Virtual Server allows to Load-balance traffic destination virtual-address:port +between several real servers. + +### Algorithm + +Load-balancing schedule algorithm: + +- round-robin +- weighted-round-robin +- least-connection +- weighted-least-connection +- source-hashing +- destination-hashing +- locality-based-least-connection + +```none +set high-availability virtual-server 203.0.113.1 algorithm 'least-connection' +``` + +### Forward method + +- NAT +- direct +- tunnel + +```none +set high-availability virtual-server 203.0.113.1 forward-method 'nat' +``` + +### Health-check + +Custom health-check script allows checking real-server availability + +% stop_vyoslinter + +```none +set high-availability virtual-server 203.0.113.1 real-server 192.0.2.11 health-check script +``` + +% start_vyoslinter + +### Fwmark + +Firewall mark. It possible to loadbalancing traffic based on `fwmark` value + +```none +set high-availability virtual-server 203.0.113.1 fwmark '111' +``` + +### Real server + +Real server IP address and port + +% stop_vyoslinter + +```none +set high-availability virtual-server 203.0.113.1 real-server 192.0.2.11 port '80' +``` + +% start_vyoslinter + +### Example + +Virtual-server can be configured with VRRP virtual address or without VRRP. + +In the next example all traffic destined to `203.0.113.1` and port `8280` +protocol TCP is balanced between 2 real servers `192.0.2.11` and +`192.0.2.12` to port `80` + +Real server is auto-excluded if port check with this server fail. + +% stop_vyoslinter + +```none +set interfaces ethernet eth0 address '203.0.113.11/24' +set interfaces ethernet eth1 address '192.0.2.1/24' +set high-availability vrrp group FOO interface 'eth0' +set high-availability vrrp group FOO no-preempt +set high-availability vrrp group FOO priority '150' +set high-availability vrrp group FOO address '203.0.113.1/24' +set high-availability vrrp group FOO vrid '10' + +set high-availability virtual-server 203.0.113.1 algorithm 'source-hashing' +set high-availability virtual-server 203.0.113.1 delay-loop '10' +set high-availability virtual-server 203.0.113.1 forward-method 'nat' +set high-availability virtual-server 203.0.113.1 persistence-timeout '180' +set high-availability virtual-server 203.0.113.1 port '8280' +set high-availability virtual-server 203.0.113.1 protocol 'tcp' +set high-availability virtual-server 203.0.113.1 real-server 192.0.2.11 port '80' +set high-availability virtual-server 203.0.113.1 real-server 192.0.2.12 port '80' +``` + +% start_vyoslinter + +A firewall mark `fwmark` allows using multiple ports for high-availability +virtual-server. +It uses fwmark value. + +In this example all traffic destined to ports "80, 2222, 8888" protocol TCP +marks to fwmark "111" and balanced between 2 real servers. +Port "0" is required if multiple ports are used. + +% stop_vyoslinter + +```none +set interfaces ethernet eth0 address 'dhcp' +set interfaces ethernet eth0 description 'WAN' +set interfaces ethernet eth1 address '192.0.2.1/24' +set interfaces ethernet eth1 description 'LAN' + +set policy route PR interface 'eth0' +set policy route PR rule 10 destination port '80,2222,8888' +set policy route PR rule 10 protocol 'tcp' +set policy route PR rule 10 set mark '111' + +set high-availability virtual-server vyos fwmark '111' +set high-availability virtual-server vyos protocol 'tcp' +set high-availability virtual-server vyos real-server 192.0.2.11 health-check script '/config/scripts/check-real-server-first.sh' +set high-availability virtual-server vyos real-server 192.0.2.11 port '0' +set high-availability virtual-server vyos real-server 192.0.2.12 health-check script '/config/scripts/check-real-server-second.sh' +set high-availability virtual-server vyos real-server 192.0.2.12 port '0' + +set nat source rule 100 outbound-interface name 'eth0' +set nat source rule 100 source address '192.0.2.0/24' +set nat source rule 100 translation address 'masquerade' +``` + +% start_vyoslinter + +Op-mode check virtual-server status + +```none +vyos@r14:~$ run show virtual-server +IP Virtual Server version 1.2.1 (size=4096) +Prot LocalAddress:Port Scheduler Flags + -> RemoteAddress:Port Forward Weight ActiveConn InActConn +FWM 111 lc persistent 300 + -> 192.0.2.11:0 Masq 1 0 0 + -> 192.0.2.12:0 Masq 1 1 0 +``` + -- cgit v1.2.3