Turn an OpenWrt device into a PPPoE Offload Device — it dials PPPoE, strips the Internet-facing IPv4, and hands it to a downstream router's WAN via DHCP. Now your router/gateway stills owns the public IP, no double-NAT here, while still having full control over the public IP, NAT, firewall, port forwarding (and UniFi's Direct Remote Connection), yet it doesn't have to deal with PPPoE.
PPPoE session Hand out public IPv4
ISP <===============> [PPPoE Offloading via OpenWrt] ========================> [UniFi Gateway]
Do not own public IPv4 Own public IPv4 from DHCP WAN
If your ISP's ONU/ONT supports "Advanced DMZ", or "IP Passthrough", or "DMZplus/DMZ+", you don't need this project. Those features are the same as this PPPoE half-bridge setup, and you can just use them directly without implementing your own PPPoE Offloading.
This is especially useful for UniFi Gateways, which have notoriously bad PPPoE performance. Now you can saturate 3000+ Mbps PPPoE with any UniFi Gateway (UDM Pro/SE/Pro Max, UXG Pro, EFG, etc.), even with multiple PPPoE sessions.
Do not let all the UniFi shills fool you into thinking "It is 2026 and UniFi Gateway can do 3 Gbps PPPoE, you smoking rock". And no, UniFi Gateway can not, and you know it.
| File | Deploy To | Purpose |
|---|---|---|
start-half-bridge.sh |
/root/start-half-bridge.sh |
Main script |
99-half-bridge |
/etc/hotplug.d/iface/99-half-bridge |
Hotplug trigger (runs script on PPPoE up) |
See EXAMPLE.md for a real-world walkthrough, where we set up a Banana Pi BPI-R4 Pro as the PPPoE offload device for a UDM Pro Max, with dual PPPoE WAN setup. However, you can use any hardware as you like, and you just need to change the interface names in the configuration to match your setup accordingly.
The script is fully configurable via environment variables (set in the top section of the 99-half-bridge file):
| Variable | Default | Description |
|---|---|---|
WAN_COUNT |
1 |
Number of PPPoE instances (1-3) |
WAN_FW_ZONE |
wan |
OpenWrt firewall zone name for all PPPoE interfaces |
PPPOE_IFNAME_{1,2,3} |
ppp1 / ppp2 / ppp3 |
OpenWrt UCI PPPoE interface name |
DOWNSTREAM_DEV_{1,2,3} |
eth1 / lan1 / lan2 |
Physical port to downstream router |
DOWNSTREAM_UCI_{1,2,3} |
lann1 / lann2 / lann3 |
OpenWrt UCI downstream interface name |
By setting WAN_COUNT and uncommenting out the relevant lines, you can easily setup multiple PPPoE connections Offload for multi-WAN setups.