Wire VRRP: a virtual gateway that answers, fails over, and re-points the switches #1056

Merged
jaylouisw merged 1 commit from feat/vrrp-wired into main 2026-11-08 08:45:36 +00:00
Owner

engine/vrrp.js implemented the election — priorities, skew, Master_Down_Interval, the
00:00:5E:00:01:<vrid> virtual MAC — and engine/simulator.js never required it. The CLI had no
vrrp command at all:

$ grep -c vrrp engine/simulator.js engine/cli.js
engine/simulator.js:0
engine/cli.js:0

So a lab could read about a virtual gateway and never build one. Nothing answered ARP for the VIP,
every host pointed at it black-holed, and the failure looked like a routing mistake.

Four defects, found in this order, each by a failing test

1. Both routers elected themselves. Peer discovery filtered the segment on isRouter(), which
does not exist on Device — the capability is isL3(), and a bridged L3 switch can hold a virtual
gateway too. With no peers, each side won its own election.

2. The master answered ARP as its own address. owner.ip is the interface's own address, which
for a virtual gateway is not the VIP — so the reply told the host that 10.0.0.254 lived at the
router's MAC under 10.0.0.1. The address being defended is the one that was asked for.

3. The reply to the virtual MAC was dropped. After fixing (2), the host resolved the gateway and
still could not reach it: the frame was addressed to a MAC no port owns, so it was discarded as "not
addressed to this device". A master must accept frames sent to its group's virtual MAC.

4. Failover black-holed with zero ARP replies. The switch's MAC table still pointed the virtual
MAC at the old master's port, so traffic was unicast into a box that no longer owned it. This is
what gratuitous ARP on takeover exists for, and the model needed it for the same reason real
hardware does. RFC 826 completes the picture: a station updates its table from any ARP it receives,
not only replies — the GARP is a request, and that rule is what lets hosts that never asked
believe it.

What now works

R1#show vrrp
Interface     Group  Pri  State      Master      Virtual IP      Virtual MAC
Gi0/0         10     150  Master     R1          10.0.0.254      00:00:5e:00:01:0a
  • Election per (broadcast domain, vrid) before the first packet: priority, then the higher
    interface address (RFC 5798 §6.3.2), with address ownership outranking any configured priority.
  • The VIP is answered locally — ownsIpOn() serves it, so an echo is delivered instead of being
    forwarded and killed at TTL 1 — and answered with the virtual MAC, so a host's cache survives a
    failover.
  • Failover: a master whose interface goes down relinquishes (it stops being a candidate), the
    backup takes the VIP with the same virtual MAC, and the gratuitous ARP re-points the switches.
    The host never relearns.
  • CLI: vrrp <vrid> ip|priority|preempt|advertise inside an interface, plus show vrrp. A group
    is per interface, so the command is refused outside one rather than attaching to whichever
    interface happened to be selected last — and a refused command no longer leaves an empty group
    behind, which show vrrp was reporting as a configured gateway.

Test

test/vrrp-in-path.test.js — 49 assertions: the CLI surface and its refusals, one election per
segment, the master holding the address, the virtual MAC on the wire and in the host's cache, no
"not mine" drops, failover on interface-down, preemption by priority, the equal-priority tiebreak,
address-owner precedence, convergence (no ownership before Master_Down), and a save/load round trip.

Three of them failed first, one per defect above.

Docs

docs/SIMULATION.md §5.4 read "absent from the data path … there is no first-hop redundancy of any
kind, and no HA failover to demonstrate."
It now documents what is modelled and, precisely, what is
not: no VRRPv3, no IPv6 virtual addresses, and no detection of a master that goes quiet — a
master is displaced by losing its interface, never by stopping its advertisements. HSRP and GLBP do
not exist.

99 suites, 4840 assertions, all passing.

Closes #1052.

`engine/vrrp.js` implemented the election — priorities, skew, `Master_Down_Interval`, the `00:00:5E:00:01:<vrid>` virtual MAC — and `engine/simulator.js` never required it. The CLI had no `vrrp` command at all: ``` $ grep -c vrrp engine/simulator.js engine/cli.js engine/simulator.js:0 engine/cli.js:0 ``` So a lab could read about a virtual gateway and never build one. Nothing answered ARP for the VIP, every host pointed at it black-holed, and the failure looked like a routing mistake. ## Four defects, found in this order, each by a failing test **1. Both routers elected themselves.** Peer discovery filtered the segment on `isRouter()`, which does not exist on `Device` — the capability is `isL3()`, and a bridged L3 switch can hold a virtual gateway too. With no peers, each side won its own election. **2. The master answered ARP as its own address.** `owner.ip` is the interface's own address, which for a virtual gateway is *not* the VIP — so the reply told the host that `10.0.0.254` lived at the router's MAC under `10.0.0.1`. The address being defended is the one that was asked for. **3. The reply to the virtual MAC was dropped.** After fixing (2), the host resolved the gateway and still could not reach it: the frame was addressed to a MAC no port owns, so it was discarded as "not addressed to this device". A master must accept frames sent to its group's virtual MAC. **4. Failover black-holed with zero ARP replies.** The switch's MAC table still pointed the virtual MAC at the *old* master's port, so traffic was unicast into a box that no longer owned it. This is what **gratuitous ARP** on takeover exists for, and the model needed it for the same reason real hardware does. RFC 826 completes the picture: a station updates its table from any ARP it receives, not only replies — the GARP is a *request*, and that rule is what lets hosts that never asked believe it. ## What now works ``` R1#show vrrp Interface Group Pri State Master Virtual IP Virtual MAC Gi0/0 10 150 Master R1 10.0.0.254 00:00:5e:00:01:0a ``` - **Election** per (broadcast domain, vrid) before the first packet: priority, then the higher interface address (RFC 5798 §6.3.2), with address ownership outranking any configured priority. - **The VIP is answered locally** — `ownsIpOn()` serves it, so an echo is delivered instead of being forwarded and killed at TTL 1 — and answered *with the virtual MAC*, so a host's cache survives a failover. - **Failover**: a master whose interface goes down relinquishes (it stops being a candidate), the backup takes the VIP with the same virtual MAC, and the gratuitous ARP re-points the switches. The host never relearns. - **CLI**: `vrrp <vrid> ip|priority|preempt|advertise` inside an interface, plus `show vrrp`. A group is per interface, so the command is refused outside one rather than attaching to whichever interface happened to be selected last — and a refused command no longer leaves an empty group behind, which `show vrrp` was reporting as a configured gateway. ## Test `test/vrrp-in-path.test.js` — 49 assertions: the CLI surface and its refusals, one election per segment, the master holding the address, the virtual MAC on the wire and in the host's cache, no "not mine" drops, failover on interface-down, preemption by priority, the equal-priority tiebreak, address-owner precedence, convergence (no ownership before Master_Down), and a save/load round trip. **Three of them failed first, one per defect above.** ## Docs `docs/SIMULATION.md` §5.4 read *"absent from the data path … there is no first-hop redundancy of any kind, and no HA failover to demonstrate."* It now documents what is modelled and, precisely, what is not: no VRRPv3, no IPv6 virtual addresses, and **no detection of a master that goes quiet** — a master is displaced by losing its interface, never by stopping its advertisements. HSRP and GLBP do not exist. **99 suites, 4840 assertions, all passing.** Closes #1052.
VRRP is in the data path: a virtual gateway that answers, fails over, and re-points the switches
Some checks failed
CI / Docker build (pull_request) Successful in 30s
CI / Test (Node 22) (pull_request) Successful in 2m6s
CI / Server smoke test (pull_request) Failing after 35m22s
CI / Test (Node 20) (pull_request) Failing after 35m43s
CI / Test (Node 18) (pull_request) Failing after 35m47s
07ad278012
engine/vrrp.js implemented the election - priorities, skew, Master_Down_Interval, the
00:00:5E:00:01:<vrid> virtual MAC - and engine/simulator.js never required it. The CLI had no vrrp
command at all. A lab could read about a virtual gateway and never build one: nothing answered ARP
for the VIP, so every host pointed at it black-holed and the failure looked like a routing mistake.

The wiring, in the order it turned out to need:

- computeVrrp() elects once per (broadcast domain, vrid) before the first packet. Peers are the L3
  devices in the same segment - there is no isRouter() on Device, the capability is isL3(), and a
  bridged L3 switch can hold a virtual gateway too. That mistake had both routers electing
  themselves.
- The winner claims the group's addresses through Device.claimVrrp(), and ownsIpOn() serves them, so
  an echo to the VIP is delivered instead of forwarded and killed at TTL 1.
- The master answers with the VIRTUAL MAC, and accepts frames addressed to that MAC although no port
  owns it. Both halves are needed: with only the first, the host resolved the gateway and still
  could not reach it, because the reply to the virtual MAC was dropped as "not addressed to this
  device".
- Answering ARP with owner.ip was wrong for a VIP: owner.ip is the interface's own address, so the
  reply told the host that 10.0.0.254 lived at the router's MAC under a different address. The
  address being defended is the one that was asked for.
- A gratuitous ARP per virtual address on takeover. This is the piece that makes failover work at
  all: a switch's MAC table still points the virtual MAC at the old master's port, so the traffic is
  unicast into a box that no longer owns it. Test-driven - the failover test failed with zero ARP
  replies until the announcement existed, which is exactly what happens in a real lab.
- RFC 826 says a station updates its table from any ARP it receives, not only replies; the GARP is a
  request, and that rule is what lets hosts that never asked believe it.

CLI: vrrp <vrid> ip|priority|preempt|advertise inside an interface, plus show vrrp reporting
Master/Backup, the virtual IP and the virtual MAC. A group is per interface, so the command is
refused outside one rather than attaching to whichever interface was selected last.

A refused command no longer creates a group: 'vrrp 11 ip nonsense' used to leave an empty group
behind, so show vrrp reported a virtual gateway that was never configured.

Failover, preemption and address ownership are pinned: a master whose interface goes down
relinquishes and the backup takes the VIP with the same virtual MAC, so the host never relearns;
equal priorities break on the higher interface address (RFC 5798 6.3.2); and a router that holds the
VIP as its own address outranks any configured priority.

test/vrrp-in-path.test.js: 49 assertions. Three failed first time, one for each of the defects above.

docs/SIMULATION.md 5.4 said "absent from the data path ... there is no first-hop redundancy of any
kind, and no HA failover to demonstrate". It now documents what is modelled and, precisely, what is
not: no VRRPv3, no IPv6 virtual addresses, and no detection of a master that goes quiet - only one
whose interface is down.

99 suites, 4840 assertions, all passing.

Closes #1052.
jaylouisw deleted branch feat/vrrp-wired 2026-11-08 08:45:38 +00:00
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
jaylouisw/packetforge!1056
No description provided.