High availability

Applies to SynapseOS builds from 2026-10-09 (20261009-141152 and later). See What changed.

Two units, one address. The one that holds it does the work.

A pair is configured at delivery. This page is what you need to know to operate one; the configuration itself is set once and listed on the Configuration reference.

How a pair works

The floating address	One address, the one traffic is sent to. It lives on whichever unit is active.
Where it lives	On the external leg, when both units share that network segment. On the internal leg when they do not: a floating address cannot cross a router, so a pair whose external addresses are in different routed networks floats the address on the shared private segment and takes public traffic through a provider floating IP or an upstream balancer instead.
The election	VRRP, between the two units, over the internal leg, unicast to the peer's address. The unit with the higher priority wins while it can advertise. When the address lives on the external leg, that leg is tracked too: if it goes down, the unit withdraws and the other takes the address. When the address lives on the internal leg, the election and the address share it, so a failure of that leg ends the advertisements by itself, and a failure of the external leg withdraws nothing.
After a failover	The unit that failed does not take the address back when it recovers (nopreempt). The pair stays where it is until the active unit fails in turn. This avoids a second cutover for a unit that was flapping.
The MAC	Optionally a virtual MAC (00:00:5e:00:01:<id>) on a macvlan interface named vrrp.<id>, so the address keeps the same MAC through a failover and upstream devices have nothing to relearn. Without it, failover relies on every upstream device honouring a gratuitous ARP.

Both units run the full data plane all the time; only the address moves. Synapse's own state (bans, verdicts, rules) comes from the platform, so the standby is as current as the active unit.

What to check

systemctl status keepalived           # active on both units
ip -br addr                           # the floating address appears on exactly one unit
journalctl -u keepalived -b           # elections, transitions and the reason for each

On a pair with a virtual MAC, the floating address is on an interface named vrrp.<id>, not on the physical interface:

eno1             UP   <unit's own address>/24 ...
vrrp.51@eno1     UP   <floating address>/24

A unit that holds the address logs Entering MASTER STATE; the other logs Entering BACKUP STATE.

Testing a failover

From the active unit:

systemctl stop keepalived

Within a few seconds the other unit logs Entering MASTER STATE and ip -br addr on it shows the floating address. Traffic to the address continues from there. Then:

systemctl start keepalived

The address stays on the new active unit: nopreempt means the recovered unit becomes the standby. Do this in a maintenance window the first time; existing connections through the address are cut at the cutover.

If the address moves but traffic does not follow

An upstream router that cached the address against the old unit's physical MAC, and ignores gratuitous ARP, keeps sending to the dead unit until the entry ages out. On a pair with a virtual MAC, one packet sent from the floating address refreshes it: ping -c3 -I <floating address> <gateway> on the new active unit. After that the MAC never changes again, which is the point of the virtual MAC.

Updating a pair

Update the standby first, confirm it, then the active unit. The address moves once.

1. On the standby: synapseos-ab-update update, systemctl reboot, then synapseos-ab-update status and synapseos-synapse status to confirm the new slot is running and the data plane is up. See Updating.
2. On the active unit: the same. When it reboots, the election hands the address to the already-updated standby, and nopreempt keeps it there afterwards.
3. Confirm with ip -br addr on both.

Do not update both at once: a pair with both units in their trial boots has no unit to fall back to.

What is the same on both

Configuration is written identically on both units at delivery, and should be kept so: the same /etc/synapse/config.yaml apart from the unit's own addresses, the same firewall rules, the same log forwarding. A change you make on one unit by hand has to be made on the other, or the pair behaves differently after a failover. The backup of one unit is a good template for the other.

Capacity

Each unit carries the full load on its own after a failover, so size a pair for one unit's capacity, not two. The throughput each product delivers is on its product page; the pair adds availability, not capacity.