WAN Uplinks

The WAN Uplinks tab on the Configuration page (/edges/:id/config) turns two or more WAN-role logical interfaces into a single managed uplink policy. The edge then decides, on its own and without waiting for the orchestrator, which uplink carries traffic and when to move it.

This is different from simply having several WAN interfaces. Multi-WAN configuration describes independent WAN interfaces, each with its own NAT and port-forwarding rules. This tab adds failover and load balancing across them.

Changes here are staged, not applied

Saving on this tab writes to the orchestrator and marks the edge as having pending changes. Nothing reaches the edge until you click Sync Config in the page header. An amber banner appears on the tab while changes are pending. See Syncing Configuration.

Before you start

You need at least two logical interfaces with Role = WAN on the edge, created on the Logical Interfaces tab. Only WAN-role interfaces can become uplinks.

Mode

Three modes, selected at the top of the tab. Changing the mode takes effect on the next sync.

Mode	Behaviour
Single	One uplink carries everything. No failover, no balancing. The edge still probes every uplink and reports its health.
Failover	The highest-priority healthy uplink carries everything. Traffic moves when it fails, and returns after the failback delay once it recovers. If nothing is confirmed healthy, see When nothing is confirmed healthy.
Load Balance	Flows are spread across healthy uplinks in proportion to their weights.

What Single does and does not do

In Single mode the edge does not steer traffic. It does not pick an uplink, install routes or move traffic when an uplink fails; traffic follows the edge's ordinary routing. What it still does is monitor: every uplink is probed and its health is reported, and the table marks the uplink the edge is actually sending traffic through with carrying traffic. That badge is observed, not chosen, which is why Single never shows an uplink as unverified or on backup.

Switching from Load Balance to Single narrows traffic to one uplink: the edge keeps only the path through the highest-priority uplink, and all new flows use it. Switching from Failover to Single leaves traffic where it is.

Health for an edge with only one uplink

With a single WAN uplink the policy is normally not sent at all, so the Health column stays empty. Health reporting for a one-uplink edge in Single mode is available as a per-edge opt-in (single_uplink_health), currently set through the API rather than this tab. It starts probing from that edge, which is why it is off by default.

The two-uplink threshold

The policy is sent to the edge only when at least two usable uplinks resolve, in every mode (the one exception is the single-uplink health opt-in above). An uplink is not usable if its logical interface has been deleted, is disabled, is no longer WAN-role, or has no resolvable physical port.

Below two, the policy is silently omitted from the configuration batch — which the edge treats as a removal. Failover and load balancing stop being applied, and health stops being reported, until a second uplink is available again. Switching a one-uplink edge to Failover or Load Balance is refused for the same reason.

This matters most when removing an uplink from a two-uplink policy: you are not shrinking multi-WAN, you are switching it off. The removal dialog says so.

The uplinks table

Each row is one uplink in the policy. The table mixes two different kinds of information, and it is worth knowing which is which.

What you configure

Column	Description
Priority	Failover order, shown in Failover mode. Lower number wins. Reorder with the up/down arrows — this swaps two uplinks' priority values rather than renumbering the list. Priority also decides which uplink Single keeps when you leave Load Balance.
Weight	Share of flows, shown in Load Balance and Single mode. 1–255. Set with the slider or the number box; editable only in Load Balance, because the other modes send everything over one uplink.
Share	In Load Balance, the configured weight as a percentage of the total, so an 80/20 split is readable without arithmetic. In Failover it says whether the uplink carries traffic or is held in reserve; in Single it shows —, since there is no split.

What the edge reports

Column	Description
Address	The uplink's IPv4 address, marked (DHCP) when learned by DHCP.
Health	Three detection layers — carrier, gateway reachable, internet reachable — plus a plain-language summary of what is failing. A grey layer is not a failure: no report means the edge has not measured it yet, and not checked means probing is off for that uplink.
carrying traffic	Badge on the uplink currently carrying traffic.
unverified	Amber badge beside carrying traffic. The edge moved here without any probe confirming the uplink works — see When nothing is confirmed healthy.
running at N	Appears under Share when the edge programmed a different weight than you configured.

"running at N" is the answer to "why is that uplink quiet"

The configured weight is your intent. running at N is what the forwarding table was actually programmed with. A DEGRADED uplink runs at half weight, so the two numbers disagreeing is the explanation, not a bug.

Priority and weight edits are collected as a draft — dragging a slider does not send a request per pixel. A Save changes button appears once anything is unsaved.

Adding an uplink

Click Add uplink to open the interface picker. It lists the WAN-role logical interfaces on this edge that are not already in the policy, with each one's address and physical port.

The new uplink is given the next free priority automatically. Interfaces that are administratively down, or have no address configured, can still be added but are flagged — they will not carry traffic until that is fixed.

If the list is empty, the picker says which of the two reasons applies: the edge has no WAN-role interfaces at all, or all of them are already uplinks. In the first case it offers a link to the Logical Interfaces tab.

Removing an uplink

The trash icon opens a confirmation dialog naming the uplink and stating the consequence. Removing an uplink does not delete the logical interface — only its membership of this policy — so it can be added back later. Traffic it currently carries moves to the remaining uplinks.

When the policy is down to two uplinks, the dialog warns that removal will disable multi-WAN on the edge entirely. See the two-uplink threshold.

Health probes

The activity icon on each row opens Health probes — <uplink>. This is how the edge decides that an uplink has failed, and it is the one place where a careless change can make failover worse rather than better.

Presets

Preset	What it configures
Standard	Three ICMP probes across three operators, plus TCP port 443 to two of them. Any one succeeding keeps the uplink up, including on links that filter ICMP.
Strict	Two ICMP probes plus two HTTPS checks, each on a different operator; three of the four must succeed. Catches captive portals and links that are up but broken, and tolerates one operator's outage. Not suitable for links that filter ICMP or inspect HTTPS. Needs Check every of at least 2000 ms, which applying the preset sets for you.
Restricted uplink	TCP and DNS only. For corporate or carrier links that filter ICMP.
Custom	Edit the probe set directly.

A newly added uplink starts with the Standard set, so it is probed without you opening this dialog.

Behind a proxy, Standard cannot see an outage

Some networks put a proxy between the edge and the internet that answers TCP connections itself, typically a corporate firewall that inspects HTTPS. That proxy completes the Standard set's TCP port 443 checks even after its own internet connection has failed. Because any one successful probe keeps the uplink up, the uplink stays up and traffic does not fail over.

For an uplink like that, use Custom: remove the TCP probes and add at least two HTTP probes, each with an Expected status. When the proxy cannot reach the site it answers with an error or times out, so the HTTP probe fails as it should. Adding HTTP probes while keeping the TCP ones does not help, because the proxy still answers the TCP probes and one success is enough. Each URL must use an IP address rather than a hostname, and should point at an endpoint that returns a known status.

The edge has no built-in probe set of its own. With probing on, the probe list cannot be left empty: an uplink probing nothing could never be judged up or down. To stop probing an uplink, turn probing off instead.

Turning probing off

With probing off, the uplink is judged on carrier and gateway alone: a pulled cable or a gateway that stops answering still marks it down and moves traffic, but an outage further upstream does not. Use it for an uplink whose provider blocks every probe type, or where sending probes is not wanted.

The Internet layer of its health strip then shows a grey not checked chip, not a failure: nothing beyond the gateway is being tested, and the summary beside it says so.

Probe types

Type	Target	Extra fields
ICMP	A literal IPv4 address	—
TCP	A literal IPv4 address	Port
DNS	The resolver's IPv4 address	Name to look up, record type
HTTP	A full URL (http:// or https://) whose host is an IPv4 address	Expected status code

ICMP and TCP need an address, not a hostname

The edge pins each ICMP and TCP probe to a specific uplink by source address. A hostname would have to be resolved first, and resolution itself depends on an uplink being up — so a name here would make the check depend on the thing it is meant to test.

HTTP needs an address, not a hostname

The same reasoning applies to an HTTP probe's URL: use an address such as https://1.1.1.1/cdn-cgi/trace, not a hostname. The edge will not look a name up over the uplink it is testing, so an HTTP probe with a hostname would fail every check.

All of an uplink's probes run together, once per check, at the uplink's Check every interval; there is no separate interval per probe.

Treat the uplink as up when

• Any probe succeeds — the most tolerant. One reachable anchor keeps the uplink up.
• N of M succeed (quorum) — requires an explicit probe list.
• All must succeed — the strictest, and the easiest way to cause a false failover.

At least two probes are required, so a single anchor going down cannot fail an uplink on its own.

Decision thresholds

Field	Meaning	Range
Declare DOWN after	Consecutive failed checks before the uplink is marked down	1–60
Declare UP after	Consecutive successful checks before it is marked up again	1–60
Check every	Probe interval in milliseconds	500 ms and above; 2000 ms and above when the uplink has an HTTP probe, since each check is then a full request to someone else's server

The dialog previews what these add up to in seconds, and names the uplink traffic would move to.

Quality thresholds (optional)

Max packet loss %, Max latency ms and Max jitter ms.

Quality thresholds never take an uplink down

Breaching one of these marks the uplink DEGRADED, which halves its weight — it is deprioritised, not removed. They are safe to set and cannot on their own cause an outage.

Setting any of them requires at least one ICMP probe, because that is what measures loss, latency and jitter.

If Save is refused

The dialog checks the same rules the server does and explains what to fix before sending anything. If a save is still rejected, the message names the field that was rejected rather than just reporting a failure.

When nothing is confirmed healthy

Failover normally moves traffic to the highest-priority uplink a probe has confirmed is up. There is one case where it moves without that confirmation.

If the uplink carrying traffic fails and no other uplink has a passing probe, the edge will still move — to an uplink whose carrier is up and whose gateway answers, if there is one. That is weaker evidence than a probe: it says the cable is in and the ISP's router is talking, not that anything gets through to the internet. The alternative is staying on an uplink known to be dead, which is a certain outage rather than a probable recovery.

The uplink then shows an amber unverified badge beside carrying traffic, and its health summary says so in words. Its Internet layer keeps reading no report, which is not a contradiction: nothing has tested it, and the edge does not pretend otherwise.

An unverified uplink is a question to answer, not a state to leave

It usually means that uplink has no working probe — most often no probe list, or probe targets it cannot reach. Give it probes it can actually check and the badge stops appearing, because the edge will have a real verdict to act on.

The edge leaves an unverified uplink as soon as any uplink reports a passing probe, without waiting for the failback delay: the delay exists to protect established sessions on a working uplink, and an unverified one has not been shown to be working.

Failback

In Failover mode, traffic returns to a higher-priority uplink once it has recovered, but not immediately:

1. The uplink must first pass Declare UP after consecutive checks.
2. It must then stay healthy for the failback delay (60 seconds by default).
3. Traffic moves back as soon as that delay ends.

The health probe dialog previews this timeline for the uplink you are editing.

Flapping uplinks wait longer. An uplink that has changed state more than four times in ten minutes has its failback delay doubled for each further change, up to 15 minutes. It earns the short delay back once it has been stable for ten minutes. This stops an unstable primary from pulling traffic back and forth.

Failback can be turned off (failback_enabled, set through the API together with failback_delay_sec). Traffic then stays on the backup until the backup itself fails, even after the primary recovers.

Restarting the edge agent does not move traffic

After an agent restart the edge keeps using the uplink it was already sending traffic through, and waits for that uplink's own first health check before making any change. The wait is bounded, from 30 seconds up to a few minutes depending on how often the uplinks are probed. Only a genuine failure, such as a pulled cable or failing probes, moves traffic during that window.

When traffic moves

What happens to connections already in progress depends on the mode.

• Failover. Connections using the uplink that stopped carrying traffic are ended, so applications reconnect over the new uplink instead of waiting on a dead one. Long downloads and other long-lived TCP connections restart when traffic fails over or fails back.
• Load Balance. When an uplink leaves, only its own connections are ended; connections on the remaining uplinks are untouched. When an uplink returns, connections already running stay on the uplink they started on, and only new connections are spread across it again.
• Single. The edge does not move traffic, so nothing is ended.

In Failover and Load Balance, the edge also limits the TCP segment size of LAN traffic to fit the smallest uplink MTU. This prevents stalled transfers when the uplinks' MTUs differ, for example a PPPoE link at 1492 alongside Ethernet at 1500.

Transition history

Below the table, every failover and failback the edge has reported: when, which uplink, the state change, the edge's own reason (for example carrier — link down or probe — loss 60%), and which uplink was carrying traffic afterwards.

The reason comes from the edge verbatim, because "carrier down" and "probe failing" send you to completely different places. An empty history is good news, not an error — it means no uplink has changed state.

Reason	Meaning	Where to look
carrier	The link is down	Cable, modem or ONT, switch port
next_hop	The link is up but the gateway does not answer	The ISP router, VLAN or addressing
lease	A DHCP uplink has no usable lease yet, or is still waiting for its router	The ISP's DHCP server; normal for a few seconds after a cable is plugged back in
probe	The gateway answers but the probe targets do not	An upstream ISP outage or a routing problem
sla	Probes succeed but breach a quality threshold	Loss, latency or jitter on the link (the uplink is DEGRADED, not down)
no_transport	The edge has no path to probe this uplink yet	Transient during start-up; if it persists, contact support

Health is reported by the edge on transition, plus a slow heartbeat, so the table can lag a very recent event by up to a minute.

Advanced

One setting, collapsed by default: Isolate uplinks from each other, which keeps each uplink's traffic in its own routing table.

Not available yet

Per-uplink VRF allocation is not implemented. Turning this on is rejected with an error explaining that all uplinks share the LAN VRF, which is the supported multi-WAN topology. Leave it off.

If your two ISPs use overlapping subnets, assign the WAN logical interfaces to different VRFs in the Logical Interface modal instead.

Worked example — two ISPs, primary and backup

1. On Logical Interfaces, confirm two WAN-role interfaces exist, e.g. WAN-Primary on G0 and WAN-Backup on G1.
2. On WAN Uplinks, choose Failover.
3. Click Add uplink and add both.
4. Use the arrows so WAN-Primary is priority 1.
5. Open health probes on each uplink, choose Standard, and confirm at least two probes are listed.
6. If the backup link is metered, set Max packet loss % on the primary so a lossy-but-up primary is deprioritised rather than left carrying everything.
7. Click Sync Config in the page header.
8. Verify: the carrying traffic badge sits on WAN-Primary, and its health strip shows carrier, gateway and internet all reachable.

To test failover, unplug the primary. The transition history should record the change with a carrier reason, and the badge should move to WAN-Backup. Plug it back in: once the primary has passed Declare UP after and the failback delay (60 seconds by default), the badge returns to WAN-Primary.

Limits

Setting	Range
Uplinks in a policy	2 or more for the policy to be applied; no upper limit
Weight	1–255
Priority	Unique per uplink; assigned automatically when adding
Probes per uplink	At least 2 when set explicitly
Probe interval / timeout	100 ms and above
Declare DOWN / UP after	1–60 checks
Failback delay	0 seconds and above, default 60; up to 15 minutes for a flapping uplink
Max packet loss	0–100 %
Max latency / jitter	Positive whole milliseconds