Wheelhouse docs

Masquerade behind each uplink#

You will end up with a source NAT rule for every uplink, so traffic leaving by any of them is translated to that uplink's address. An uplink without one carries traffic that leaves with a private source address and never comes back.

Before you start#

  • The operator role and a licence.
  • At least one uplink. The Uplinks tab shows which rule is behind each one, and offers to write a missing one.

Step 1 — Look at what you have#

Network → High availability → Uplinks. The table shows, per uplink, which source NAT rule masquerades behind it. An uplink with none is the thing to fix.

bash
show nat source rules

Step 2 — Add the missing rule#

The Uplinks page offers a one-click masquerade rule for an uplink that has none, using the next free rule number.

set nat source rule 110 outbound-interface name eth2
set nat source rule 110 translation address masquerade
set nat source rule 110 description 'Wheelhouse: masquerade behind eth2'

masquerade means "use whatever address this interface currently has", which is what a DHCP or PPPoE uplink needs. A static uplink can use a literal instead if you want the translation pinned:

set nat source rule 110 translation address 198.51.100.7

Because the rule matches on the outbound interface. A rule naming eth1 does nothing for traffic leaving by eth2, and there is no wildcard that means "whichever uplink won". The symptom of a missing rule is specific and confusing: everything works until a failover, and then nothing does — because traffic is now leaving by an uplink whose packets have a private source address.

That is also why the add-uplink wizard offers a masquerade rule as part of adding an uplink, ticked by default.

Step 3 — Narrow it, if you need to#

The default rule translates everything leaving by that interface. To translate only one source network:

set nat source rule 110 source address 192.0.2.0/24

Rule numbers matter: rules are evaluated in order and the first match wins, so a narrow rule needs a lower number than the broad one it should take priority over.

The load balancer writes its own#

load-balancing wan writes masquerade rules for its members unless disable-source-nat is set. If you are running the balancer and your own per-uplink rules, turn its NAT off:

set load-balancing wan disable-source-nat

Two writers of masquerade rules is a configuration that works until the day the two disagree. Share load across two uplinks.

Check it worked#

From a client, through each uplink in turn. Use a policy route to pin a test host to one uplink, or fail the primary, then:

bash
curl -s https://ifconfig.co

The answer should be that uplink's public address, not a private one and not a timeout.

On the router, the per-rule counters tell you which rule is doing the work:

bash
show nat source statistics

The NAT page shows the same counters joined onto the rules. A rule with a flat counter after a failover is the one that did not match.

Undoing it#

delete nat source rule 110

The uplink's Stop using as uplink action on the Uplinks page stages the removal of the addressing, the failover entry and the balancer membership; the NAT rule is deleted from the NAT page.

See also#

Checked against ui/src/pages/Wan.tsx · agent/wan.go · docs/multi-wan.md · ui/src/pages/Nat.tsx

Updated 2026-09-02 nat multi-wan snat

Edit this page