A second uplink with health-checked failover#

You will end up with two internet connections, one carrying traffic and one waiting, and a daemon that moves traffic to the second when the first stops working beyond the modem. That last part is the difference between this and merely having two default routes.

Before you start#

The operator role and a licence.
A second connection, on its own interface, already physically connected.
Check targets: two or three addresses out on the internet that answer ICMP and that you are happy to ping every ten seconds, indefinitely.

Understand the three ways first#

VyOS gives you three, and the Uplinks page names which one you are in.

Ranked by distance — cold standby, no checks. The lowest distance carries traffic; the kernel only falls back when the interface itself goes down. Cheap, and blind to a provider that is up at layer 2 and dead beyond it. Equal distances are equal-cost multipath, not failover, and the page says so.

Health-checked failover (protocols failover) — this guide. The daemon installs a default route per uplink while its check targets answer through that uplink, and withdraws it when they stop. Among the installed ones, the lowest metric wins.

Load-balanced (load-balancing wan) — new connections spread across members by weight. Share load across two uplinks.

Step 1 — Add the second uplink#

Network → High availability → Uplinks → + Add uplink.

Pick the interface, the addressing, and tick masquerade. The wizard suggests a distance ten above the highest that exists, so the new uplink starts behind the one you have.

a DHCP second uplink with a check, staged in one go

set interfaces ethernet eth2 address dhcp
set interfaces ethernet eth2 dhcp-options default-route-distance 210
set interfaces ethernet eth2 description 'backup'
set protocols failover route 0.0.0.0/0 dhcp-interface eth2 check target 9.9.9.9
set protocols failover route 0.0.0.0/0 dhcp-interface eth2 metric 210
set nat source rule 110 outbound-interface name eth2
set nat source rule 110 translation address masquerade

Note what the wizard does not do: it leaves the DHCP client's own default route in place. That is deliberate and it matters — see the warning in step 3.

Step 2 — Add a check to the first uplink too#

An uplink without a check is never withdrawn. The Uplinks page names any uplink in that state in its notes, because it is the mistake that makes failover look like it works right up until the day it has to.

Open the primary uplink's side panel and add a check:

set protocols failover route 0.0.0.0/0 next-hop 203.0.113.1 interface eth1
set protocols failover route 0.0.0.0/0 next-hop 203.0.113.1 check target 9.9.9.9
set protocols failover route 0.0.0.0/0 next-hop 203.0.113.1 check target 1.1.1.1
set protocols failover route 0.0.0.0/0 next-hop 203.0.113.1 metric 1

The editor's fields, and what each becomes:

Field	Command	Default
Targets	`check target <addr>`, one line each	— (required)
Type	`check type tcp` / `arp`	`icmp`, and not written
Port	`check port <n>`	only with `type tcp`
Timeout	`check timeout <s>`	`10`, and not written when it is 10
Policy	`check policy all-available`	`any-available`, and not written
Metric	`metric <n>`	the uplink's distance

A static uplink's failover entry is keyed on its next hop and also carries interface <if>; a DHCP or PPPoE uplink's entry is keyed on dhcp-interface <if>, because its gateway is not known until the lease arrives.

Step 3 — Understand what ranks what#

An installed failover route is a kernel route with distance 0, so it beats every static or client-installed default route. That means:

Among checked uplinks, the failover metric is the rank.
The static or DHCP default route sitting beside it is the last resort, used only when every checked route is withdrawn. That is harmless, and the page reports it as a note rather than a warning.
The page ranks checked uplinks ahead of unchecked ones.

Verified on a dual-WAN VM (2026-09-02): the daemon adds ip route … proto failover, FRR lists it as K>* 0.0.0.0/0 [0/<metric>], and a link cut turns the uplink to "link down / route withdrawn" within the check interval while the other keeps the selected route.

Step 4 — Commit with a confirm window#

Check it worked#

Both uplinks are up and one is selected. The Uplinks tab shows, per uplink: addressing, gateway (declared, or learned from the table for DHCP), rank and role, whether its default route is selected / installed / present / absent, health, and which NAT rule masquerades behind it. The stat tiles name the mode in force — single, ranked by distance, failover, load-balanced, or mixed.

What you want to see: WAN-A selected and passing, WAN-B installed as backup and passing.

Then break it on purpose. This is not optional; failover you have not tested is a belief.

bash

# on a VM
virsh domif-setlink <domain> <wan-a-interface> down
# on hardware: unplug WAN-A, or shut the switch port

Within the check interval, WAN-A should show "link down / route withdrawn" and WAN-B should take the selected route. Then restore WAN-A and watch it win back on its lower metric, with WAN-B returning to installed.