OPNsense plugin · os-wan-failover 1.4

WAN Failover

Decides when an IPv4 WAN leaves service and when it comes back, moves connections to the right WAN in both directions, and restarts Tailscale only when the default route really changed.

Why this plugin

Core's gateway monitor marks a WAN down when its loss crosses the gateway's threshold, and up again as soon as its reading drops back under it. On a link that drops packets in bursts, that flaps: the WAN leaves, returns while still lossy, and leaves again, and every change re-elects the default route. Connections opened during an outage stay on the other WAN after the preferred one recovers, because pf keeps a state on the path it was created on. Connections pinned to the failed WAN stay pinned to it. Tailscale, which picks its path once, keeps the old one.

The plugin turns that into one decision with hysteresis: a WAN goes out on loss and comes back only once it is clean.

How it decides

Out. A WAN whose dpinger loss exceeds the gateway's own high-loss threshold, or that is hard down, is held with core's Force down while another WAN is usable. A WAN whose link is down (no carrier or no IPv4 address) has no monitor at all, and is held as unavailable for as long as the link stays down.
Back. A held WAN is released only when a settled monitor window shows no loss at all, not merely loss under the threshold.
Never both. A hold needs a usable alternative, and every hold is released at once on positive evidence that the alternative failed.
Boot. A reboot releases the holds the plugin took before routing starts, so a box never boots with a WAN it forced down.
Only its own holds. Each hold is recorded with the boot that took it, saved together with Force down in one config write, outside the settings where the settings API cannot change it. Only a hold that record proves is ever released: a gateway you forced down by hand, or one a restored backup brings back forced down, stays down until you untick Force down.

It evaluates every minute, on every gateway monitor alarm and after a configuration change.

Moving connections

On a hold, the states routed via that WAN's gateway and interface are killed, so its connections reconnect over the other WAN at once instead of timing out.

On recovery, the connections that prefer the recovered WAN, by their rule's gateway or gateway-group tier or otherwise by the default route, are ended once the firewall already routes them there, so they reconnect through it. The failback delay (10 minutes by default) makes that wait until the WAN has read clean for that long; any loss restarts the wait, and a WAN held again never gets them back. Fail back now on the page ends the wait.

Tailscale is restarted when the IPv4 default route moves to another gateway and stays there, so it reconnects on the new path, and only then.

Settings

On System > Gateways > WAN Failover, with its log under WAN Failover Log.

Setting	What it does	Normally
Enable	Hold, release, move connections and restart Tailscale as above. Off releases every hold at once.	On
Dry run	Decide and log only: nothing is held, killed or restarted. Watch what it would do before letting it act.	On by default; off once you trust it
WAN gateways	The IPv4 gateways to manage, normally the two WANs. Only saved gateways are listed: save an automatic gateway once on System > Gateways > Configuration to select it.	Both WANs
Move connections back	End the connections that prefer a recovered WAN so they reconnect through it.	On
Failback delay (minutes)	How long a recovered WAN must read clean before connections move back. 0 moves them as soon as the WAN is released.	10
Restart Tailscale	Restart tailscaled on a real IPv4 default-route change.	On with Tailscale

Command line

configctl wanfailover holds          # JSON: each WAN's reading and judgement, whether it is held, any failback wait
configctl wanfailover status         # whether the plugin's minute job is installed
configctl wanfailover failback_now   # end the failback delay
configctl wanfailover release        # release every hold now

Limits

IPv4 WANs only. IPv6 gateways are left to core.
It acts on core's own monitor readings and thresholds; set the gateways' loss thresholds and monitor periods on System > Gateways.
Uninstalling the package releases its holds and re-syncs routing, and removes its minute job; an upgrade keeps the holds.

Source and install

Install it from the LegoTypes repository: see Install. Source: LegoTypes/plugins, net/wan-failover.