Background

My home setup uses the full Unifi stack, with a UDM SE as the gateway. However, the UDM SE does not support PPPoE Hardware Offload, which means when it handles the dial-up itself, single-thread throughput is only about 500 Mbps (while multi-thread can saturate gigabit). If I switch to having the ONU handle the dial-up, it introduces a Double NAT problem, and the UDM also cannot detect IP changes in time to trigger DDNS updates.

So is there a way to use a dedicated device to handle PPPoE dial-up (and benefit from hardware offload performance), while still allowing the UDM SE to directly obtain the public IP address? The answer is the topic of this article — PPPoE Half Bridge.

What is PPPoE Half Bridge?

PPPoE Half Bridge is not a new concept. Some overseas ISPs' ONUs natively support PPPoE Half Bridge (also called PPPoE IP Extension or PPPoE IP Passthrough). The core idea is:

A front-end device (ONU or router) is responsible for establishing the PPPoE session, but it does not use the acquired public IP. Instead, it "passes through" the public IP to the downstream gateway via DHCP. This makes the downstream gateway think it obtained the public IP directly.

Comparison of several common solutions:

Simply put, PPPoE Half Bridge makes the front-end device act only as a "dial-up proxy," while the real public IP is held and used by the downstream gateway. The advantages are obvious:

• The front-end device (such as a router running OpenWrt) handles PPPoE dial-up and can use its hardware offload capability to fully utilize the bandwidth;
• The downstream gateway device (such as the UDM SE) directly obtains the public IP, avoiding Double NAT;
• The downstream gateway can normally handle NAT, firewall, DDNS, and all other functions, just as if it were dialing up directly.

This article shares an OpenWrt-based implementation of PPPoE Half Bridge, which I have been running stably for more than half a year with verified reliability. This solution can also be easily migrated to Debian-based systems.

Why does this work?

A PPPoE dial-up establishes a point-to-point connection (Point-to-Point). After the dial-up succeeds, the IP address on the PPPoE interface is really just an identifier. Unlike an Ethernet interface, it is not required for communication itself. Packet forwarding depends on the PPPoE Session and the routing table, not on the IP address bound to the interface.

Therefore, we can:

1. Keep the PPPoE session alive
2. Remove the IP address from the PPPoE interface (ip addr flush)
3. Manually create routing rules to direct downstream gateway traffic to the PPPoE interface
4. Assign the public IP to the downstream gateway via DHCP

After the downstream gateway gets the public IP, all outbound traffic is forwarded through the front-end device's PPPoE interface to the ISP, and return traffic comes back through the PPPoE interface to the front-end device and is then forwarded to the downstream gateway. The whole process requires no NAT; the front-end device only performs Layer 2 / Layer 3 forwarding.

Hardware preparation

You need an OpenWrt device that supports PPPoE Hardware Offload, which will be responsible for dialing and forwarding.

My hardware setup:

• Banana Pi BPI-R4: flashing the latest OpenWrt firmware enables PPPoE hardware acceleration (flow_offloading_hw), and it can saturate gigabit with barely any CPU usage
• ONU stick: inserted into the BPI-R4's SFP port to replace a traditional ONU
• DAC cable: connects the other SFP port of the BPI-R4 to the UDM SE

Tip

There are now also native OpenWrt 10G XGPON ONUs on the market. If your ISP supports GPON, that would be even more convenient. However, Shanghai Telecom uses EPON, so that is not an option.

Network topology

Interface description:

Overall approach

Before diving into the specific configuration, let's first look at the overall idea and traffic flow:

[ONU / ONU stick] <--PPPoE--> [OpenWrt (BPI-R4)] <--DHCP--> [UDM SE]
     eth2                                        eth1

1. OpenWrt completes PPPoE dial-up through the WAN port and obtains a public IP (for example a.b.c.d);
2. Strip the IP address from the PPPoE interface while keeping the PPPoE session alive;
3. Configure the gateway IP of the public subnet on the LAN port (eth1) connected to the downstream gateway, so OpenWrt "impersonates" the ISP gateway;
4. Assign the public IP to the downstream gateway via DHCP;
5. Configure policy routing so that the downstream gateway's traffic is forwarded to the public network through the PPPoE tunnel;
6. Disable NAT (masquerade) on OpenWrt — once the PPPoE interface IP is cleared, masquerade cannot work, and NAT should be handled by the downstream gateway.

After completing the above steps, the downstream gateway behaves as if it dialed up directly: it gets the public IP and accesses the Internet through the PPPoE tunnel, while OpenWrt becomes a transparent "bridged dialer."

Key points for the prerequisite configuration

Before getting into the core operations, there are several critical points to pay attention to in OpenWrt's static configuration:

network:

• The defaultroute of the PPPoE interface (ppp) must be set to '0' — the default route is managed manually via policy routing, and if PPPoE adds a default route automatically it will cause conflicts
• The lann interface (eth1) should first be assigned a placeholder IP (such as 192.168.2.1), which will be modified dynamically after dial-up

dhcp:

• Use odhcpd (the full version, not odhcpd-ipv6only) instead of dnsmasq as the DHCPv4 server. odhcpd is lightweight and flexible; after dynamically modifying the DHCP range, restarting it takes effect within seconds, which makes it ideal for this scenario
• Configure DHCP on the lann interface as start=2, limit=1, meaning the pool has only one assignable address, and later dynamically adjust start so that this single address becomes exactly the public IP
• Set leasetime to 60s; this very short lease ensures rapid updates when the IP changes

firewall:

• Create a separate zone (wann) for the PPPoE interface, with masq disabled — because the PPPoE interface IP will be cleared, masquerade will not be able to find a source address and Internet access will fail
• Enable bidirectional forwarding between lann and wann
• Enable flow_offloading_hw hardware flow offloading

Core operation steps

The following is the sequence of operations that needs to be performed after PPPoE dial-up succeeds. Assume the acquired public IP is 58.32.1.100, and the subnet assigned by the ISP is /22.

Step 1: Obtain the public IP and calculate the gateway address

After PPPoE dial-up succeeds, first get the assigned public IP via ifstatus:

wan_ip=$(ifstatus ppp | jsonfilter -e '@["ipv4-address"][0].address')
# → 58.32.1.100

Then calculate the gateway address from the subnet mask. Shanghai Telecom Premium Network assigns a /22 subnet (255.255.252.0), so align the third octet to the subnet boundary with a bitwise operation:

IFS=. read i1 i2 i3 i4 <<< "$wan_ip"
gateway_ip="$i1.$i2.$(( i3 & 252 )).1"
# 58.32.1.100 → 1 & 252 = 0 → gateway 58.32.0.1

[!TIP] If your ISP assigns a different subnet mask, you will need to modify the calculation logic here. For example, with a /24 subnet, you can directly use $i1.$i2.$i3.1.

Step 2: Clear the PPPoE interface IP and establish policy routing

This is the most critical step in the entire solution.

# Clear the IP address on the PPPoE interface, but keep the PPPoE session alive
ip addr flush dev pppoe-ppp

This removes the public IP from the PPPoE interface, but the PPPoE session itself is not affected.

Why remove it? Because next we are going to assign an IP from the same subnet to the downstream gateway. If OpenWrt's PPPoE interface still keeps the public IP, it will create a conflict where "two devices in the same subnet have IPs from the same range," resulting in routing confusion. After removing the PPPoE interface IP, OpenWrt no longer has a directly connected route for that subnet, and traffic direction is then entirely controlled by the routing rules we manually add.

Why can it be removed? PPPoE is a point-to-point tunnel protocol. Session maintenance depends on the underlying PPPoE session, not on IP-layer addressing. As long as the PPPoE session remains up, the tunnel exists and packets can be forwarded through it. The IP address is only for convenience at the upper-layer routing level and does not affect the tunnel itself.

# Establish policy routing: traffic coming from eth1 (downstream gateway) goes through the PPPoE tunnel
ip route add default dev pppoe-ppp table 100
ip rule add iif eth1 table 100

Since the PPPoE interface IP has been removed, the system default route also becomes invalid. We need to manually create routing rules to tell the system, "traffic coming from the downstream gateway should go out through the PPPoE tunnel."

Policy routing is used here:

• Create an independent routing table (table 100), and add a default route in it pointing to the pppoe-ppp device;
• Add a routing rule: all traffic entering from eth1 (the downstream gateway interface) should consult table 100 for routing.

This way, traffic sent by the downstream gateway is forwarded to the public Internet through the PPPoE tunnel, while OpenWrt's own management traffic remains unaffected.

Important

All IP changes here are made directly using the ip / ifconfig commands, and do not modify /etc/config/network. After OpenWrt reboots, it will automatically return to the default configuration, and these operations just need to be executed again after the next successful PPPoE dial-up. This is an intentional design choice to ensure the system remains recoverable.

Step 3: Configure eth1 as the gateway for the downstream gateway

ifconfig eth1 down
ifconfig eth1 "$gateway_ip" netmask "255.255.252.0" up
# eth1 IP becomes 58.32.0.1/22

Configure the calculated gateway IP (for example 58.32.0.1) on eth1 so that OpenWrt's eth1 "impersonates" the ISP gateway. Then, after the downstream gateway gets the public IP via DHCP, its default gateway will naturally point to that address, and routing will work normally.

Note

In practice, I found that modifying the IP directly sometimes does not take effect. It is more reliable to bring the interface down first and then reconfigure it up.

If you do not need to access neighbor IPs within the same subnet, simply keep the subnet mask consistent with what the ISP provides. If you do need that, you should make the subnet as small as possible. In theory, you could even use a /31 mask — as long as the gateway IP and your public IP are in the same subnet.

Step 4: Dynamically adjust the DHCP range to assign the public IP precisely

In the prerequisite configuration, we already set the odhcpd DHCP configuration for the lann interface as start=2, limit=1, so only one IP can be assigned from the pool. What we need to do now is: based on the currently acquired public IP, dynamically modify the start value so that the one and only IP handed out by DHCP is exactly the public IP.

The start parameter in odhcpd represents the offset relative to the start address of the subnet. After updating the configuration, restart the odhcpd service to make it effective.

# Calculate the offset of the public IP within the /22 subnet
# 58.32.1.100 → subnet start 58.32.0.0 → offset = 1*256 + 100 = 356
offset=$(( i3 * 256 + i4 - (i3 & 252) * 256 ))

# Modify odhcpd's DHCP start address and restart
uci -q set dhcp.lann.start="$offset"
uci -q commit dhcp
/etc/init.d/odhcpd restart

A concrete example:

• PPPoE obtains IP 58.32.1.100, subnet /22
• The subnet on eth1 is 58.32.0.0/22
• DHCP start = 356, limit = 1
• The downstream gateway obtains 58.32.0.0 + 356 = 58.32.1.100 via DHCP

Step 5: Make sure the PPPoE zone does not perform NAT

Check the masq (NAT) setting of the firewall zone where PPPoE resides, and ensure it is 0:

wan_idx=$(uci show firewall | grep -E "firewall.@zone\[[0-9]+\].name='wann'" \
          | cut -d'[' -f2 | cut -d']' -f1)
uci set firewall.@zone[$wan_idx].masq='0'
uci commit firewall
/etc/init.d/firewall reload

This step is absolutely crucial. In Step 2 we already flushed the PPPoE interface IP address, and masquerade works by using the egress interface IP as the SNAT source address. At this point, the PPPoE interface no longer has an IP, so the MASQUERADE rule cannot find a usable source address, which causes all packets passing through NAT to be dropped directly, appearing as complete loss of Internet connectivity. Therefore, you must set masq to 0 for the firewall zone containing PPPoE, so that traffic is forwarded through the PPPoE tunnel using the original source IP (that is, the downstream gateway's public IP), and NAT is handled entirely by the downstream gateway.

Step 6: Notify the downstream gateway to refresh DHCP immediately

After all the above configuration is complete, the downstream gateway needs to detect the new IP immediately. However, when OpenWrt redials (and the IP changes), the downstream gateway does not proactively refresh DHCP — it waits until the current lease expires before requesting a new one. But here we run into a practical problem: how can we make the downstream gateway immediately request DHCP again?

I tried the following approaches:

• DHCP FORCERENEW (RFC 3203): the server proactively notifies the client to refresh the DHCP lease. However, after testing, I found that the UDM SE does not support it.
• Link Down/Up: physically disconnect and reconnect eth1 on OpenWrt to trigger the downstream gateway to request DHCP again. But I used a DAC cable to connect the SFP ports of the two devices, and after the link state changed, the UDM still did not initiate a new DHCP request.

In the end, I came up with a simple and fast solution: deploy a simple listener service on the UDM SE that forcibly triggers DHCP renewal when it receives a specified message.

The principle is simple: use nc on the UDM to listen on a port (such as 99). When it receives the message dhcp_renew, send SIGUSR2 (release the current lease) and SIGUSR1 (request a new lease) to udhcpc (the DHCP client on the UDM).

while true; do
    message=$(nc -l -p 99)
    message=$(echo "$message" | tr -d "\n\r\t ")
    if [ "$message" = "dhcp_renew" ]; then
        if killall -SIGUSR2 udhcpc && killall -SIGUSR1 udhcpc; then
            logger -t "dhcp_listener" "Successfully renewed DHCP"
        fi
    fi
done

After OpenWrt completes dial-up and all configuration, just send a message:

echo "dhcp_renew" | nc 10.10.10.1 99

When the IP changes, the downstream gateway can update almost within seconds.

Automated execution

All the above steps can be packaged into a Shell script and configured to run automatically after PPPoE dial-up succeeds. In OpenWrt, you can place the script in the /etc/ppp/ip-up.d/ directory, and it will be triggered automatically each time PPPoE connects successfully.

This way, whether it is the first dial-up or a reconnection after a drop, the Half Bridge configuration is completed automatically for fully unattended operation.

Create /etc/hotplug.d/iface/99-half-bridge:

#!/bin/sh
[ "$ACTION" = "ifup" ] && [ "$INTERFACE" = "ppp" ] && {
    /root/start-half-bridge.sh
}

Each function has been made idempotent — if the current state is already the target state, the operation is skipped to avoid problems caused by repeated execution.

Overall data flow

Traffic flow after the configuration is complete:

Outbound (downstream devices → Internet):

Downstream device → UDM SE (NAT, source IP = public IP) → eth1 → policy routing table 100 → pppoe-ppp → ISP

Inbound (Internet → downstream devices):

ISP → pppoe-ppp → routing table matches destination IP → eth1 → UDM SE (NAT) → downstream device

The front-end device performs no NAT throughout the entire process. It only does Layer 3 routing and PPPoE encapsulation/decapsulation. Combined with hardware flow offloading, the performance overhead is almost zero.

Final thoughts

I have personally been running this PPPoE Half Bridge solution stably for more than half a year without any issues. In essence, it is a manual implementation on OpenWrt of the "ONU PPPoE IP Passthrough" feature.

That said, this solution really is quite Geeky. It involves coordinated interaction among PPPoE, DHCP, policy routing, firewall, and several other modules, so it is hard to abstract into a universal one-click script. Everyone's network environment, ISP-assigned subnet, and hardware are different, so adjustments are needed according to the actual situation.

Note

I have actually switched to the UCG Fiber — Unifi finally came to its senses and built in PPPoE hardware acceleration. So this article is basically my way of closing the loop, pointing people who are still tinkering with PPPoE Hardware Offload toward a workable path.

However, if you are using a device such as an OpenWrt XGPON ONU, this solution is still very valuable — it can give you a "pseudo-IPoE" broadband experience, making the downstream gateway completely unaware of PPPoE.

If you're interested, feel free to discuss and tinker together 🛠️

Appendix: Configuration and script reference

Network configuration (/etc/config/network)

config interface 'loopback'
    option device 'lo'
    option proto 'static'
    option ipaddr '127.0.0.1'
    option netmask '255.0.0.0'

config globals 'globals'
    option ula_prefix 'fd32:a520:fa07::/48'
    option packet_steering '1'

config device
    option name 'br-lan'
    option type 'bridge'
    list ports 'lan1'
    list ports 'lan2'
    list ports 'lan3'

config interface 'lan'
    option device 'br-lan'
    option proto 'static'
    option ipaddr '10.10.10.10'
    option netmask '255.255.255.0'
    option gateway '10.10.10.1'

config interface 'lann'
    option device 'eth1'
    option proto 'static'
    option defaultroute '0'
    option ipaddr '192.168.2.1'
    option netmask '255.255.255.0'

config device
    option name 'br-wan'
    option type 'bridge'
    list ports 'wan'
    list ports 'eth2'

config device
    option name 'wan'
    option macaddr 'fe:fe:b1:95:1f:1f'

config device
    option name 'eth2'
    option macaddr 'FE:FE:B1:95:1F:1D'

config interface 'wan'
    option device 'br-wan'
    option proto 'static'
    option ipaddr '192.168.0.2'
    option netmask '255.255.255.0'

config interface 'wan6'
    option device 'br-wan'
    option proto 'dhcpv6'

config interface 'ppp'
    option proto 'pppoe'
    option device 'br-wan'
    option ipv6 '0'
    option keepalive '0 1'
    option username 'ad12345'
    option password '12345'
    option defaultroute '0'

Key parts of the firewall configuration (/etc/config/firewall)

config defaults
    option input 'REJECT'
    option output 'ACCEPT'
    option forward 'REJECT'
    option synflood_protect '1'
    option flow_offloading '1'
    option flow_offloading_hw '1'

config zone
    option name 'lann'
    option input 'ACCEPT'
    option output 'ACCEPT'
    option forward 'ACCEPT'
    list network 'lann'

config zone
    option name 'wann'
    list network 'ppp'
    option input 'REJECT'
    option output 'ACCEPT'
    option forward 'REJECT'
    option mtu_fix '1'

config forwarding
    option src 'lann'
    option dest 'wann'

config forwarding
    option src 'wann'
    option dest 'lann'

Key parts of the DHCP configuration (/etc/config/dhcp)

config odhcpd 'odhcpd'
    option maindhcp '1'
    option leasefile '/tmp/hosts/odhcpd'
    option leasetrigger '/usr/sbin/odhcpd-update'
    option loglevel '4'

config dhcp 'lann'
    option interface 'lann'
    option dhcpv4 'server'
    option leasetime '60s'
    option start '2'
    option limit '1'
    option dns '223.5.5.5'

PPPoE Half Bridge startup script (/etc/ppp/ip-up.d/start-half-bridge.sh)

#!/bin/ash

# Logging function
log() {
    echo "$1"
    logger -t pppoe-half-bridge "$1"
}

# Get WAN IP and validate it
get_wan_ip() {
    local wan_ip=$(ifstatus ppp | jsonfilter -e '@["ipv4-address"][0].address')
    if [ -z "$wan_ip" ]; then
        log "Failed to obtain WAN IP"
        exit 1
    fi
    echo "$wan_ip"
}

# Calculate gateway address (22-bit subnet mask)
get_gateway_address() {
    local ip="$1"
    IFS=. read i1 i2 i3 i4 << EOF
$ip
EOF
    echo "$i1.$i2.$(( i3 & 252 )).1"
}

# Calculate DHCP start address offset (22-bit subnet mask)
get_ip_offset() {
    local ip="$1"
    IFS=. read i1 i2 i3 i4 << EOF
$ip
EOF
    echo "$(( i3 * 256 + i4 - (i3 & 252) * 256 ))"
}

# Configure DHCP service
configure_dhcp_service() {
    local start="$1"
    local current_start=$(uci -q get dhcp.lann.start)
    
    if [ "$current_start" = "$start" ]; then
        log "DHCP configuration not needed"
        return
    fi
    
    uci -q set dhcp.lann.start="$start"
    uci -q commit dhcp
    /etc/init.d/odhcpd restart
    log "DHCP configuration completed"
}

# Configure firewall
configure_firewall() {
    wan_idx=$(uci show firewall | grep -E "firewall.@zone\[[0-9]+\].name='wann'" | cut -d'[' -f2 | cut -d']' -f1)
    
    if [ -z "$wan_idx" ]; then
        log "wan zone not found"
        return
    fi

    masq_val=$(uci -q get firewall.@zone[$wan_idx].masq)
    if [ "$masq_val" = "0" ]; then
        log "Firewall configuration not needed"
        return
    fi
    uci set firewall.@zone[$wan_idx].masq='0'
    uci commit firewall
    /etc/init.d/firewall reload
    log "Firewall configuration completed"
}

# Configure eth1 IP address
configure_eth1_ip() {
    local gateway_ip="$1"
    local current_ip=$(ip addr show dev eth1 | grep -w "inet" | awk '{print $2}')
    
    if [ "$current_ip" = "$gateway_ip/22" ]; then
        log "eth1 IP configuration not needed"
        return
    else
        ifconfig eth1 down 
        ifconfig eth1 "$gateway_ip" netmask "255.255.252.0" up
        log "eth1 IP configuration completed"
    fi
}

# Main function
main() {
    local wan_ip=$(get_wan_ip)
    local gateway_ip=$(get_gateway_address "$wan_ip")
    log "WAN IP: $wan_ip, Gateway: $gateway_ip"

    # Step 1 & 2: Clear the PPPoE interface IP and establish policy routing
    ip addr flush dev pppoe-ppp
    ip route add default dev pppoe-ppp table 100
    ip rule add iif eth1 table 100
    log "PPPoE interface configuration completed"

    # Step 3: Configure eth1 as the downstream gateway's gateway
    configure_eth1_ip "$gateway_ip"

    # Step 4: Dynamically adjust the DHCP range
    configure_dhcp_service "$(get_ip_offset "$wan_ip")"

    # Step 5: Make sure the PPPoE zone does not perform NAT
    configure_firewall

    # Step 6: Notify the downstream gateway to refresh DHCP
    echo "dhcp_renew" | nc 10.10.10.1 99
    log "UDM DHCP refresh completed"
}

# Execute the main function
main

DHCP listener service on UDM SE (dhcp_listener.service)

Deploy it to /etc/systemd/system/dhcp_listener.service. After enabling it, it can receive DHCP refresh notifications from OpenWrt:

[Unit]
Description=DHCP Listener Service

[Service]
User=root
ExecStart=/bin/bash -c 'while true; do \
    message=$(nc -l -p 99); \
    message=$(echo "$message" | tr -d "\n\r\t "); \
    if [ "$message" = "dhcp_renew" ]; then \
        if killall -SIGUSR2 udhcpc && killall -SIGUSR1 udhcpc; then \
            logger -t "dhcp_listener" "Successfully renewed DHCP"; \
        fi; \
    fi; \
done'
Restart=always

[Install]
WantedBy=multi-user.target