Skip to content
The Gateway

WAN load balancing and failover

The Gateway v2.15.0 adds optional weighted WAN load balancing to priority-based failover. In automatic mode, the WAN manager can install a multipath egress over healthy, balancing-eligible uplinks; it still moves the preferred path when an uplink fails and holds failback during recovery.

Balancing is off by default. Leave wan_balance: false for the v2.14.0 primary/standby behaviour. This is not channel bonding: one TCP flow does not combine two links’ bandwidth, and configured weights do not guarantee an exact observed traffic ratio.

Goal

Section titled “Goal”

A home or small office has a primary ISP connection and a backup, such as fibre plus LTE:

  • Prefer the lowest priority number for failover; optionally share flows across healthy uplinks using weights.
  • Detect an ISP outage even if the local router still answers ping.
  • Move to a usable standby and restore the preferred path with hysteresis.
  • Keep tunnel and privacy enforcement during the transition, accepting a reconnection window rather than bypassing protection.

The WAN manager is inactive with fewer than two enabled uplinks. Existing single-uplink installations do not require a configuration change.

Section titled “Configure uplinks”

Install or update using the installation guide. Use Interfaces → WAN Uplinks & Failover to edit interfaces, priorities, enabled state, optional gateways, probe targets and per-uplink balancing eligibility. The load-balancing checkbox controls wan_balance.

Start with manual mode. It reports the switch the manager would make without changing the active uplink. Equivalent configuration:

network:
  wan_iface: eth0
  lan_iface: eth2
  wan_failover_mode: manual
  wan_balance: false
  wans:
    - iface: eth0
      priority: 100
      weight: 3
      enabled: true
      balance: true
    - iface: eth1
      priority: 200
      weight: 1
      enabled: true
      balance: true

Interface names are examples: select the actual uplinks on your node, never the client-facing LAN. Lower priority numbers are preferred. Each uplink needs a usable address and a resolvable next hop. A standby with carrier but no address can receive a per-interface DHCP client from the manager. Primary and standby may be on the same LAN; that does not remove shared upstream failure risks.

Verify before enabling automatic moves

Section titled “Verify before enabling automatic moves”
  1. Confirm the UI lists the intended primary and standby, their health and their order.
  2. Inspect the manager’s reasons and proposed decisions in manual mode.
  3. Confirm each uplink reaches the internet, not just its first-hop router.
  4. Keep local or out-of-band access and a backup before a disruptive test.
  5. Change wan_failover_mode to auto only when the proposed decisions match the intended topology.

An omitted mode defaults to auto; set manual explicitly for a staged rollout. The manager picks up saved uplink changes on its next tick, normally within five seconds.

Enable weighted balancing

Section titled “Enable weighted balancing”

After verifying the intended uplinks, set wan_failover_mode: auto and wan_balance: true. Keep two or more healthy balancing-eligible uplinks enabled. The configured 3:1 weights above bias kernel five-tuple flow hashing; they are not a promise of a 75/25 split in a small sample or a bandwidth multiplier.

For a metered backup, set that uplink’s balance: false. It remains a failover candidate but never contributes a balancing leg. With balancing off, weights do not distribute traffic. Manual mode reports decisions and does not install balancing routes.

Verify the actual result, rather than relying on the checkbox:

Terminal window
ip route show default

Expect one multipath default at metric 50 when multiple legs are installed. Inspect the UI’s egress view or /api/v1/system/wan-manager for egress and balanced, check the relevant policy table, and run node/leak checks. Read warnings returned when saving: they flag insufficient eligible uplinks, manual mode with balancing enabled, or a primary no longer in the list.

Both uplinks in the project’s test used one router/public IP. Validate independent ISP behaviour on your own test setup before depending on it; the release does not claim that scenario was exercised.

API and health

Section titled “API and health”

All paths below are under /api/v1 and require an appropriately scoped API key. Mutations require an operator role permitted by the server.

Method Path Purpose
GET /system/wan-uplinks Configured uplinks, wan_failover_mode, wan_balance, active interface, health and manager state.
PUT /system/wan-uplinks Replace uplinks and settings after validation; returns warnings. Include explicit enabled and balance flags.
GET /system/wan-manager Active/standby selection, reasons, order, flap pins, timings, egress and balanced.
GET /system/wan-health Per-uplink reachability results.

Read-only example; replace the example host and use its trusted CA:

Terminal window
curl --fail --silent --show-error \
  -H "Authorization: Bearer $API_KEY" \
  https://gateway.example:8080/api/v1/system/wan-manager

Reachability checks use device-bound TCP connections over each uplink’s own routing table and mark. Defaults are 1.1.1.1:443 and 8.8.8.8:443; configured per-uplink probe_targets are honoured. These are deliberate external connectivity checks. The manager does not send its probes to DNS port 53.

What happens during a move

Section titled “What happens during a move”

A primary transition updates the kernel default, system-default policy, policy uplink routes, NAT, tunnel binding, conntrack and DNS pins. Existing sessions may need to reconnect; this is not seamless connection migration.

Situation Behaviour
Both uplinks healthy Balancing off: one preferred path and standby. Balancing on in auto: weighted multipath over eligible Up legs.
A balancing leg degrades It is pruned after the first failed probe, subject to the five-second probe cadence.
Primary loses internet Failover selects a usable standby; multipath can widen again on a later tick.
Primary recovers Failback is held for 60 seconds, subject to a 30-second minimum dwell.
Repeated flapping Three flaps in ten minutes trigger flap pinning. Inspect the manager’s reason and state.
Manual mode Health and proposed decisions are reported; the manager does not move egress.
Fewer than two enabled uplinks The WAN manager is inactive.

The project’s v2.14.0 release record reports three real primary-link outages on a Raspberry Pi 4: primary declared down after 20–22 seconds, failover after 21–24 seconds, and standby verification 22 pass / 0 fail, with 9/9 leak checks. Those timings describe that setup, not a guaranteed SLA.

In the recorded transitions, protected clients remained fail-closed for about 10 seconds while a tunnel rebound; DNS through the gateway was unavailable for the same window. See release verification for evidence scope.

Limits and operational checks

Section titled “Limits and operational checks”
  • The v2.15.0 Pi balancing test recorded weights 3:1 and an 8:4 distribution over twelve destinations, 22 node checks passed / 0 failed, and 9/9 leak checks. Five primary outages were exercised; single-leg failover was recorded at 21 seconds. These are observations, not an SLA.
  • Balancing is not bonding or a guaranteed aggregate-throughput gain. Independent/asymmetric ISPs were not exercised in the release’s live test.
  • A failback now resolves the wan-failover alert. The stall watchdog follows the configured uplink set every 30 seconds; adding an uplink no longer requires a restart for watchdog coverage.
  • Per-interface probe tables and marks remain stable across priority edits; the implementation provides 32 slots. Removed uplinks leave the checker and stale masquerade rules are cleaned up.
  • Repeat failover, recovery and leak checks on your own hardware, ISP and tunnel configuration. Existing sessions or gateway DNS may pause while paths and tunnels recover.
Section titled “Related”