Guide

VRRP

VRRP gives a LAN a gateway address that survives the loss of the router holding it. Two or more routers share a virtual IP; one is Active (Master) and answers for it, the others wait. If the Active router dies, a Backup takes the address over, and the hosts on the segment never change their default gateway.

Ze implements RFC 9568 (VRRPv3, IPv4 and IPv6) by default, and RFC 3768 (VRRPv2, IPv4 only) as a per-group opt-in for talking to older equipment.

Status: Experimental. Wire-format tests and the keepalived scenarios below cover particular election, node-death, graceful-stop, and virtual-MAC ownership paths; they do not establish a complete implementation or production readiness. Tracked-priority handover and recovery have passed live ownership and reachability checks against keepalived 2.4.3, including peer loss at reduced priority and restoration of the tracked uplink. Those checks cover the corrected macvlan receive and unicast-only Backup-filter paths. See RFC status.

The Docker interop lab runs the vrrp-mastership-keepalived scenario (./le test integration interop). Ze at priority 200 and keepalived 2.4.3 at 100 contend for one virtual IP on a shared segment, VRID 10, VRRPv3 pinned on both sides (keepalived speaks v2 by default, and RFC 9568 Section 7.1 has a v3 router discard a v2 advertisement, so the two would never see each other). Every assertion reads which container owns the address with ip -o -f inet addr inside that container, never from ze's own output.

Phase What it asserts
1 Ze holds the virtual IP alone, continuously, for longer than keepalived's Active_Down_Interval. Held over a window and not read at an instant: a build whose SendAdvert returned without sending passed the instantaneous form.
2 Ze gets SIGTERM and keepalived takes the address over inside its own Active_Down_Interval (3 x 1s + Skew_Time = 3.61s at priority 100). Only ze's RFC 9568 Section 6.4.3 shutdown Priority 0 advertisement collapses that wait, so the bound is an assertion about ze rather than about a timeout.
3 Ze returns, preempts, and keepalived releases. The election runs again rather than latching.

Split brain is its own assertion: two owners is what a scenario watching only its own side would call a pass.

A second scenario, vrrp-v2-owner-keepalived, runs Ze as a VRRPv2 address owner. keepalived claims the same address at priority 255 from a greater source address. RFC 3768 Section 7.1 has the owner discard every advertisement, so Ze keeps the address on its virtual-MAC interface and counts each discard as owner under packet-errors in show vrrp statistics. Without the discard, keepalived's advertisement wins the tie-break and Ze gives the address up.

The IPv6 unsolicited Neighbor Advertisement burst on promotion is resolved on the caller's goroutine, because netlink sockets are created in the calling thread's network namespace and a lazy resolution on the announcer worker saw the wrong one. A compile-time check pins that path: a type assertion cannot report a break, so the break is a build error instead.

IPv4 forwarding and redirects

VRRP supplies the virtual gateway addresses and MACs; IPv4 forwarding must also be enabled for the router, including its virtual-MAC interfaces. A system-wide net.ipv4.ip_forward=1 before group creation enables forwarding on those devices.

When Linux emits an ICMP redirect for a packet sent to a virtual MAC, its source is that virtual router's VIP. Ze sets net.ipv4.icmp_errors_use_inbound_ifaddr=1 while IPv4 groups exist so that the reverse route to a host cannot select the physical address or another group's VIP. This affects IPv4 ICMP error source selection throughout the network namespace. The prior value is restored when the last IPv4 group is removed; Ze does not disable redirects.

Configuration

A VRRP group lives under the interface unit's address family, next to the addresses it backs:

interface {
    backend netlink;
    ethernet eth0 {
        unit 0 {
            ipv4 {
                address [ 192.0.2.251/24 ];
                vrrp {
                    group uplink {
                        vrid 10;
                        virtual-address [ 192.0.2.1 ];
                        priority 200;
                    }
                }
            }
        }
    }
}

group uplink is a name you choose, for your own readability: it names the group in show vrrp output, in log lines, and in the group metric label. It carries no protocol meaning. The protocol identity is vrid, which is mandatory, must be 1..255, and must match on every router in the group.

The two routers in a group differ only in priority. Give the router you want to win the higher number.

Leaf Default Meaning
vrid none (mandatory) Virtual Router ID, 1..255. The same value on every router in the group.
virtual-address none (at least one) The address(es) the group backs. A leaf-list: [ 192.0.2.1 192.0.2.2 ].
priority 100 1..254. Highest wins. 255 is reserved for the address owner and is assigned by ze, never by you.
preempt true Whether a higher-priority router takes mastership back when it returns.
preempt-delay-seconds 0 0..3600. How long a returning higher-priority router waits before preempting. Useful when a router's uplinks converge more slowly than it boots, so it does not take the gateway back before it can forward.
accept-mode false VRRPv3 only. Whether a non-owner Active accepts packets addressed to the virtual IP. False is the RFC default and means a ping to the virtual IP gets no reply from a non-owner. Forwarding, ARP and Neighbor Discovery are unaffected.
advertise-interval-milliseconds 1000 How often the Active router advertises.
version 3 2 opts this group into VRRPv2.
checksum rfc9568 IPv4 VRRPv3 only. rfc5798-compatible computes the checksum over the IPv4 pseudo-header as RFC 5798 did, which keepalived requires. See Running beside keepalived.
track absent Interfaces whose loss lowers the priority this group advertises. See Tracking an interface.

Tracking an interface

A group can watch other interfaces and lower the priority it advertises while one of them is down. That is how a router hands the gateway over when an uplink fails, rather than only when VRRP itself stops.

vrrp {
    group uplink {
        vrid 10;
        virtual-address [ 192.0.2.1 ];
        priority 200;
        track {
            interface eth1 {
                priority-decrement 150;
            }
        }
    }
}

While eth1 is down this router advertises 50 instead of 200, so a Backup configured at 100 takes the gateway. When eth1 returns, the router advertises 200 again and takes it back (subject to preempt).

The decrement changes preference, not eligibility. Ze remains Active until it receives a winning advertisement; it does not resign merely because an uplink went down. The higher-priority Backup must have preemption enabled to take over. If that peer then disappears while the tracked interface is still down, Ze can take the gateway at priority 50. A returning peer at 100 takes it back, and restoring the tracked interface lets Ze preempt at 200.

Leaf Default Meaning
interface <name> none The interface to watch. Up to 16 for one group. The name is an interface from the interface tree, or a kernel device name.
priority-decrement none (mandatory) 1..254. The priority subtracted while this interface is down.

Four rules decide what tracking does:

  • Decrements add up. Two tracked interfaces down cost the sum of their decrements.
  • The result never falls below 1. RFC 9568 Section 5.2.4 keeps a Backup router in 1..254, and 0 says the Active router stopped participating, so a decrement at or past the configured priority leaves this router at 1.
  • A name Ze cannot resolve counts as DOWN. An uplink Ze cannot find is not carrying traffic. Ze logs the resolver error, so a typo shows up in the log rather than in an unexplained priority.
  • Tracking is refused on the address owner. That router advertises 255 (RFC 9568 Section 5.2.4), so no decrement could take effect. Ze rejects the configuration rather than accepting it and ignoring it.

Ze reads the tracked interface's OPERATIONAL state and nothing else. An interface that is up while it blackholes traffic still counts as up. show vrrp reports effective-priority beside the configured priority, and lists the tracked interfaces that are down now under tracked-down.

Ze tracks an interface. It does not track a route or run a health-check script: both need machinery Ze does not have, and neither is configurable.

Choosing a version

VRRPv3 is the default and is what you want unless something else on the segment cannot speak it. Set version 2 per group for legacy peers:

vrrp {
    group legacy {
        vrid 20;
        version 2;
        virtual-address [ 192.0.2.5 ];
        advertise-interval-milliseconds 2000;
    }
}

VRRPv2 is IPv4-only and has no accept-mode; ze rejects a config that combines them rather than ignoring the leaf. The two versions also encode the advertise interval differently, which constrains what you can ask for:

Version Interval encoding Valid advertise-interval-milliseconds
3 centiseconds any multiple of 10
2 whole seconds any multiple of 1000

Ze refuses an interval it cannot put on the wire instead of silently rounding it, because a rounded interval is a timing mismatch you would only discover as a flapping election.

RFC 3768's authentication types are deliberately not implemented: RFC 9568 Section 9 removed them, as they protect against no real attack.

Running beside keepalived

RFC 9568 computes the IPv4 VRRPv3 checksum over the VRRP message alone, and ze does the same by default. keepalived, and other routers written to RFC 5798, compute it over an IPv4 pseudo-header as well and drop an advertisement in the other form, so the two routers never hear each other and both take the virtual IP. Set checksum rfc5798-compatible on a group that shares its segment with them:

vrrp {
    group gateway {
        vrid 10;
        checksum rfc5798-compatible;
        virtual-address [ 192.0.2.1 ];
    }
}

A group accepts only the form it is configured for, so every router in the group needs the same choice. A mismatch shows up as a rising checksum count in show vrrp statistics and the ze_vrrp_packet_errors_total metric. The leaf exists only for IPv4: IPv6 covers a pseudo-header in both RFCs. Version 2 always sums the message alone and refuses rfc5798-compatible.

IPv6

An IPv6 group's first virtual address must be the link-local one, because RFC 9568 Section 5.2.9 makes the first address the advert's source identity:

ipv6 {
    vrrp {
        group uplink-v6 {
            vrid 10;
            virtual-address [ fe80::1 2001:db8::1 ];
            priority 200;
        }
    }
}

IPv4 and IPv6 groups are independent state machines even when they share a vrid, so a group of each on one unit is normal and correct.

IPv6 needs none of the ARP-flux sysctls IPv4 needs: Neighbor Solicitation for the virtual IP targets its solicited-node multicast group, which only the virtual-MAC macvlan joins (the parent does not hold the virtual IP), so the parent never competes to answer. Ze does disable Duplicate Address Detection on that macvlan (accept_dad=0): a virtual IP lives on one router at a time, so DAD would only add a tentative window during which the address is unreachable right after a promotion. It also stops that macvlan answering ARP (arp_ignore=8), so the IPv6 virtual MAC is never offered for an IPv4 address, and makes it a router on the link (forwarding=1 on the macvlan only), so its Neighbor Advertisements for the virtual IP carry the Router flag RFC 9568 Section 6.4.3 requires. The macvlan derives no IPv6 link-local from the virtual MAC (addr_gen_mode none, RFC 9568 Section 7.4): its only link-local is the group's first virtual address, present while the group is Active, which is also the source of its ICMPv6 redirects. IPv6 interoperability is verified against keepalived under QEMU (election, node-death failover, and virtual-MAC resolution of the virtual IP).

The address owner

If a group's virtual address equals an address configured on the unit, that router owns the address and ze assigns it priority 255 automatically (RFC 9568 Section 5.2.4). The owner always wins. Do not set priority 255 yourself; ze rejects it, because the owner is derived from the addresses, and a hand-set 255 on a non-owner would claim an authority the router does not have.

A version 2 owner discards every advertisement it receives, as RFC 3768 Section 7.1 requires, and counts each one under the owner packet-error reason. A second box claiming the same address therefore cannot demote it. A version 3 owner follows RFC 9568 erratum 8298 instead: it processes the advertisement, so two owners of one address resolve by election. It still treats the advertisement as a sign of misconfiguration: each one is counted under the owner-conflict packet-error reason, and a warning naming the sender is logged at most once a minute per group. The exception is a version 3 group configured checksum rfc5798-compatible: that group keeps RFC 5798 as published, so its owner discards every advertisement it receives, as RFC 5798 Section 7.1 requires, and counts each one under the owner reason.

A version 2 backup that receives an advertisement whose address list differs from its own counts it under address-list. It drops it, unless the sender advertised priority 255: an advertisement from the address owner is still processed, as RFC 3768 Section 7.1 says.

Proxy ARP is refused

RFC 9568 Section 8.1.3 says: "If Proxy ARP is to be used on a VRRP Router, then the VRRP Router MUST advertise the Virtual Router MAC address in the Proxy ARP message." Linux answers a proxy ARP request with the receiving device's own MAC (LL-PROXY-ARP-MAC), so hosts would keep a MAC that does not move on failover. ze config verify and ze config commit therefore refuse proxy ARP on any unit that carries an IPv4 VRRP group, whatever turns it on: ipv4 proxy-arp true on the unit, a sysctl-profile on the unit that sets proxy_arp (the builtin proxy profile or one of your own), or a sysctl setting of net.ipv4.conf.<device>.proxy_arp, net.ipv4.conf.all.proxy_arp or net.ipv4.conf.default.proxy_arp. The last one counts because ze creates the virtual-MAC macvlan, which takes the default value. proxy_arp_pvlan (private VLAN proxy ARP) is the same reply path, so the same keys ending in proxy_arp_pvlan are refused alike. The device is matched under the interface name you configured and under the kernel device it resolves to (os-name or mac-match), and a VLAN unit's device matches in either spelling, eth0.100 or sysctl's eth0/100. Turn proxy ARP off there, or run the group on an interface without it.

The same check runs on a runtime write: set sysctl <key> <value> that turns proxy ARP on for a device a running IPv4 VRRP group uses, or for all or default, is refused with the same explanation.

The virtual MAC

Each group gets its own macvlan device carrying the RFC virtual MAC:

Family Virtual MAC
IPv4 00:00:5e:00:01:{vrid}
IPv6 00:00:5e:00:02:{vrid}

This is why failover works without the hosts noticing. The virtual MAC moves with the virtual IP, so a host's ARP or neighbour entry for the gateway stays valid: the address it points at simply arrives from a different router. Ze additionally sends gratuitous ARP (IPv4) or unsolicited Neighbor Advertisements (IPv6) on promotion so switches relearn the port immediately.

The macvlan is created and destroyed with the group. It belongs to the plugin, not to your config, and you do not declare it.

It hangs off the device the interface's hardware selector names. If you pin an interface to a NIC with mac/match, or alias it with os-name, the virtual router lives on THAT NIC, and the kernel name it currently wears does not matter. Move the card to another slot, let the kernel rename it, and the group follows on the next commit. A group on a VLAN-tagged unit lives on the tag of the selected device, not on the tag of the name you chose.

The device label on ze's VRRP metrics and state-change events names that same resolved device. On an interface with no selector nothing changes, because the logical name and the kernel name are the same string. On a selected interface the label carries the NIC's kernel name rather than the name you chose, so a dashboard or alert keyed on the old value follows it.

A selector that names no present device, or that more than one device answers, runs no virtual router at all. Ze does not fall back to a device that merely shares the interface's name: that device is not the link you asked to protect. The group starts when the selector answers exactly one device, and the daemon logs the reason while it does not. That log line says whether the group will retry: a group that never started waits for the next configuration apply.

A group that is ALREADY running is never stopped by a resolution failure. Ze cannot tell "this NIC is gone" from "I could not read the interface list this second", and treating the second as the first would fail a working master over for a transient error. A running group keeps the device it is on, and the ordinary liveness check decides whether it advertises there: if the NIC really did go away, the group stands down and comes back by itself when the NIC returns, with no commit from you.

A host on the segment that resolves the virtual IP gets the virtual MAC, not the router's real MAC, so failover is transparent at L2: the address moves to a different router without the host's ARP or neighbour entry changing. Achieving this on Linux, where the macvlan's parent holds a real address in the same subnet, requires the macvlan to be the sole ARP responder for the virtual IP. Ze arranges that automatically when it creates the macvlan (you configure nothing): the device is created in macvlan private mode, the virtual IP is installed with the parent's subnet prefix, and a small set of arp_ignore, arp_filter, and rp_filter sysctls stop the parent answering for the virtual IP while letting the macvlan answer with the virtual MAC. This mirrors what keepalived's use_vmac does, and ze restores the sysctls it changed when the last group on an interface goes away. This behaviour is verified against keepalived under QEMU (le test's VRRP interop lab).

If Ze cannot read or set a required sysctl, the group does not start. It attempts to restore shared settings changed by that setup and reports both setup and restoration errors. Failed restores retain the original values even when no group started. A later config apply retries the affected restoration before setup; teardown also retries settings no longer held by an active group.

A few consequences of this mechanism are worth knowing:

  • Ze owns the parent's arp_ignore, arp_filter, and rp_filter while a group is active. It re-asserts them on every config apply, so if you also set those knobs on the same interface unit, ze's values win for as long as VRRP runs there. Do not rely on a conflicting manual setting on a VRRP interface.
  • Two namespace-wide settings stay changed while IPv4 groups exist. net.ipv4.conf.all.rp_filter=0 lets the macvlan disable reverse-path filtering, and net.ipv4.icmp_errors_use_inbound_ifaddr=1 selects the inbound virtual router's address for ICMP errors. Normal teardown attempts to restore both saved values; failures are logged and retain the originals for retry. SIGKILL skips cleanup and leaves the settings in place until the namespace is reset or an operator restores them.
  • The address owner answers with the virtual MAC too. When the virtual IP equals a real address on the unit, that address also lives on the parent, and the kernel would answer ARP and Neighbor Solicitations for it from the parent with the real MAC. ze installs the address on the macvlan as a host route (to avoid a duplicate subnet route) and drops the parent's answers for it with two firewall tables, ze_vrrp_owner_arp and ze_vrrp_owner_nd, which show firewall ruleset lists. Hosts therefore learn only the virtual MAC, as the RFCs require. The ARP table needs a kernel built with CONFIG_NF_TABLES_ARP; ze's appliance kernel has it.
  • A Backup drops traffic sent to the virtual MAC. The virtual-MAC interface exists in every state, and the kernel would forward what it receives even with no virtual IP on it. While a group is not Active, ze drops host-type unicast received on that PRIVATE interface with the firewall table ze_vrrp_backup, which show firewall ruleset lists. Multicast VRRP advertisements and IPv6 ND remain receivable. The Active router forwards the virtual-MAC unicast traffic.
  • First-resolution race (IPv4 only). The very first host to ARP for the virtual IP right as a router becomes Active can, for one resolution, cache the parent's real MAC before the macvlan takes over; it converges to the virtual MAC on its next resolution. keepalived's use_vmac behaves identically. IPv6 has no such race (Neighbor Solicitation is not a broadcast).

Operating

Command Shows
show vrrp Every group: state, priority, vrid, virtual addresses.
show vrrp interface name eth0 Only the groups on one interface.
show vrrp statistics Per-group counters, including rejected packets and why.
clear vrrp statistics all Resets every group's counters. clear vrrp statistics alone is refused.

State changes are logged as vrrp: state change with from, to, and a reason, so a failover leaves a record of what triggered it.

The terminal lab keeps the shown Ze process running throughout two failures. First, losing zetrk1 lowers its priority from 200 to 50, below keepalived's 100. Then stopping only keepalived lets Ze take the VIP even at priority 50: tracking changes preference, not eligibility. Restarting keepalived hands the VIP back; restoring the tracked uplink lets Ze preempt at 200. The lab checks exclusive VIP ownership, the VRID 12 virtual MAC and reachability through each transition.

Ze terminal lab

Track an uplink and fail over without stopping Ze

Commit VRRP and uplink tracking live, observe priority reduction and backup demotion, then prove master failover and recovery while the shown Ze stays running.

Reproducible
Ze 26.10.283 minutes 28 secondsLinux namespace labTerminalZe recorder Plain-text transcript
Read the demonstration transcript
VRRP tracking and peer-failover walkthrough

Lab: VIP 203.0.113.1, VRID 12; shown Ze priority 200 and keepalived priority 100.
$ ze-demo card topic-vrrp overview
$ cat /src/tmp/terminal-demos/state/showcase-lab/ze.pid
$ ze cli -c 'show vrrp | no-more'

Load: gateway group and tracked zetrk1 decrement 150 in one SSH candidate.
$ sshpass -e ssh ze-demo
ze# load file absolute merge /src/demos/terminal/topics/vrrp/1-group.conf
ze# load file absolute merge /src/demos/terminal/topics/vrrp/2-tracking.conf
ze# show | compare
ze# commit now

Proof: show vrrp, kernel VIP ownership, virtual MAC and a real reachability probe.
$ ze-demo card topic-vrrp proof
$ ze cli -c 'show vrrp interface name zeptrk0 | no-more'
$ ip -br address show
$ ip netns exec showcase-vrrp ping -I eth0 -c 3 -W 2 203.0.113.1

Failure: uplink down makes Ze Backup at 50; stopping only keepalived makes Ze Master at 50.
$ ze-demo card topic-vrrp failure
$ ze-demo run showcase-lab control tracked-uplink down
$ ze cli -c 'show vrrp interface name zeptrk0 | no-more'
$ ip link show zetrk1
$ ip -n showcase-vrrp -br address show
$ ping -I zeptrk0 -c 3 -W 2 203.0.113.1
$ ze-demo card topic-vrrp takeover
$ ze-demo run showcase-lab control keepalived stop
$ ze cli -c 'show vrrp interface name zeptrk0 | no-more'
$ ip -br address show
$ ip -n showcase-vrrp -br address show
$ ip netns exec showcase-vrrp ping -I eth0 -c 3 -W 2 203.0.113.1

Fix: restart keepalived (Ze Backup 50), restore uplink (Ze Master 200), inspect statistics and reachability with the same shown PID.
$ ze-demo card topic-vrrp fix
$ ze-demo run showcase-lab control keepalived start
$ ze cli -c 'show vrrp interface name zeptrk0 | no-more'
$ ip -n showcase-vrrp -br address show
$ ze-demo run showcase-lab control tracked-uplink up
$ ze cli -c 'show vrrp interface name zeptrk0 | no-more'
$ ze cli -c 'show vrrp statistics | no-more'
$ ip -br link show
$ ip netns exec showcase-vrrp ping -I eth0 -c 3 -W 2 203.0.113.1
$ cat /src/tmp/terminal-demos/state/showcase-lab/ze.pid
$ ze-demo card topic-vrrp recap

For Prometheus:

Metric Meaning
ze_vrrp_state{device,group,vrid,family} Current state of each group.
ze_vrrp_transitions_total State transitions, for spotting a flapping group.

Requirements and limits

A ping to the virtual IP gets no reply unless you ask for one. RFC 9568 Section 6.4.3 says a non-owner Active router must not accept packets addressed to the virtual IP, and accept-mode defaults to false, so ze installs a drop rule for the virtual addresses while the group is Active. Forwarding is unaffected: hosts using the virtual IP as their default gateway keep working, the router still answers ARP and Neighbor Discovery for it, and IPv6 Neighbor Solicitations and Advertisements are never dropped. Set accept-mode true if you monitor the gateway by pinging its virtual IP. The router that owns the address as a real interface address accepts on it whatever the leaf says. The rules appear in show firewall ruleset under the vrrp table.

Tracking watches an interface, not a route or a script. track interface lowers the advertised priority while a watched interface is down, which is the failover Junos, Nokia and VyOS drive the same way. Route tracking and health-check-script tracking are not implemented: a tracked route needs a watch keyed on a prefix, and a health check needs a script runner with its own timers and security surface. Apart from tracking, failover is driven by VRRP's own triggers: loss of the Active router's adverts, carrier loss on the VRRP interface, or a graceful stop.

Netlink backend only. VRRP needs macvlan devices and raw sockets, which the VPP backend does not provide. A VPP-backed config carrying a VRRP group is rejected at validation rather than started in a degraded state.

Raw socket privileges. Ze needs CAP_NET_RAW and CAP_NET_ADMIN to send adverts (IP protocol 112) and to manage the macvlan.

Multicast must reach the segment. Adverts go to 224.0.0.18 (IPv4) or ff02::12 (IPv6) with TTL/hop-limit 255, and RFC 9568 requires receivers to discard anything arriving with a lower TTL. A device that rewrites the TTL or filters link-local multicast will break the election.

Diagnostics

ze doctor runs the same verifier a commit runs, so the two can never disagree.

Code Meaning
doctor-vrrp-config-invalid A cross-leaf rule was broken (for example accept-mode with version 2, or track on the address-owner group).
doctor-vrrp-backend-unusable The tree configures VRRP on a backend that cannot run it.
doctor-vrrp-raw-socket The raw socket VRRP needs cannot be opened, usually missing CAP_NET_RAW. On a host that is not Linux the transport cannot run at all, and the message names the host's OS.

Run ze show diagnostic <code> for the remediation.