Wheelhouse docs

A PPPoE uplink#

You will end up with a pppoe0 interface running over a physical port, carrying a default route, and masqueraded. PPPoE is one of the five mechanisms the Uplinks tab understands, so once it is up it is ranked and health-checked like any other uplink.

Before you start#

  • The operator role and a licence.
  • The user name and password from the provider.
  • The physical port the modem or ONT is on, with no address of its own. PPPoE runs over the port; the port does not need an IP.

Network → High availability → Uplinks → + Add uplink. Choose the interface, then PPPoE as the addressing.

set interfaces pppoe pppoe0 source-interface eth1
set interfaces pppoe pppoe0 authentication username 'user@provider'
set interfaces pppoe pppoe0 authentication password 'the password'
set interfaces pppoe pppoe0 default-route-distance 1
set interfaces pppoe pppoe0 description 'fibre'
set nat source rule 100 outbound-interface name pppoe0
set nat source rule 100 translation address masquerade

The wizard picks the interface name (pppoe0 by default), the distance and the next free source-NAT rule number, and shows every line before it stages anything.

The distance is the rank. With no other uplink the wizard suggests 1. With uplinks already present it suggests ten above the highest, so a new one goes behind what you have rather than in front of it — which is what you want while you are testing it.

Step 2 — Leave the masquerade rule ticked#

Unless you already have a source NAT rule that covers this interface. Every uplink needs its own, and the Uplinks tab shows which rule is behind each one — Masquerade behind each uplink.

Step 3 — Make the firewall admit the session#

The installer's ruleset names the physical WAN interface. PPPoE traffic to the router arrives on pppoe0, not on eth1, so anything that referenced the port needs to reference the tunnel — in particular the DHCP-client accept rule becomes irrelevant and any rule that scoped something to the WAN now has the wrong name.

Check the input chain before you commit:

bash
show configuration commands | match 'firewall ipv4 input'

Step 4 — Commit with a confirm window#

Check it worked#

The session is up and has an address.

bash
show interfaces pppoe pppoe0
show ip route 0.0.0.0/0

The Uplinks tab agrees. It shows the uplink's addressing, its gateway, its rank and role, whether its default route is selected, installed, present or absent, its health, and which NAT rule masquerades behind it. An uplink that is up but shows no default route selected is one whose distance puts it behind something else.

Traffic leaves.

bash
ping -c 3 -I pppoe0 203.0.113.1

When it does not come up#

SymptomCheck
No session at allThe physical link. show interfaces ethernet eth1 — if the port is down, nothing above it will work.
Session negotiates then dropsCredentials. The journal carries pppd's own messages — the Logs page.
Session up, no trafficThe default route. If another uplink has a lower distance it wins; the Uplinks tab says which.
Large downloads stall, small ones workMTU. PPPoE costs eight bytes; the interface panel sets MTU — the interface panel.
Provider wants a VLAN tagPut the pppoe interface's source-interface on the VLAN sub-interface rather than the port. Add a VLAN.

Undoing it#

delete interfaces pppoe pppoe0
delete nat source rule 100

If this was the only uplink, have the replacement staged in the same commit.

See also#

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

Updated 2026-09-02 pppoe uplink wan

Edit this page