OpenWrt Flow Offload + PBR Mitigation | Documentation & Package Feed

Installation

Choose an installation method based on your deployment workflow:

Add the repository feed to /etc/opkg/customfeeds.conf and install:

echo 'src/gz flowoffloadpbr https://bomberrie.github.io/openwrt-flowoffload-pbr-mac-misroute/ipk' >> /etc/opkg/customfeeds.conf
opkg update
opkg install openwrt-flowoffload-pbr-mitigation

The package configures /etc/nftables.d/99-flowoffload-pbr.nft and reloads firewall4 automatically.

Pipe the mitigation installer directly to your router over SSH:

ssh root@router 'sh -s' < mitigation/apply.sh

To revert the hotfix and restore original firewall state:

ssh root@router 'sh -s' < mitigation/rollback.sh

Download and install the standalone package on the router:

wget -O /tmp/openwrt-flowoffload-pbr-mitigation_0.1.4_all.ipk \
  https://github.com/bomberrie/openwrt-flowoffload-pbr-mac-misroute/releases/download/v0.1.4/openwrt-flowoffload-pbr-mitigation_0.1.4_all.ipk
opkg install /tmp/openwrt-flowoffload-pbr-mitigation_0.1.4_all.ipk

Manually configure the nftables include without installing packaging tools:

cat <<'EOF' > /etc/nftables.d/99-flowoffload-pbr.nft
table inet fw4 {
  chain ft {
    meta mark != 0 counter return
    ct status { dnat, snat } counter return
  }
}
EOF
/etc/init.d/firewall reload

Defect Analysis

When software or hardware flow offloading (e.g., MT7621 PPE) is active, netfilter's flowtable bypasses slow-path routing once connection tracking marks a flow established. In topologies utilizing Policy-Based Routing (PBR) and NAT, the flowtable caches the Layer-2 neighbor (MAC address) observed during the forward path.

As a consequence, return packets addressed to local LAN clients inherit the cached neighbor of the PBR next-hop or VPN gateway, delivering the Ethernet frames to the wrong physical host where they are discarded.

Standard Offload Behavior (Defect)

Client (10.0.0.2) sends UDP traffic.
PBR marks packet (fwmark 0xff) → routed via VPN gateway.
Flowtable caches fast-path forward tuple & next-hop neighbor.
Return reply arrives from WAN/VPN.
Fast-path delivers packet to VPN gateway's MAC on LAN.
Client never receives response; connection times out.

Mitigated Behavior (Selective Bypass)

Client (10.0.0.2) sends UDP traffic.
PBR marks packet (fwmark 0xff) → routed via VPN gateway.
Guard matches meta mark != 0 or ct status { dnat, snat }.
Early return keeps marked/NATted flows off the flowtable.
Packet handled in slow path: ARP & routing evaluated per-packet.
Return reply arrives at client with correct destination MAC.

Scope: The bypass applies exclusively to marked and NATted connections. Standard unmarked LAN ↔ WAN traffic continues to traverse the hardware/software flowtable at line rate.

Packages & Release Downloads

GitHub Releases ↗

Artifact	Format	SHA-256 Checksum	Download
`openwrt-flowoffload-pbr-mitigation_0.1.4_all.ipk`	OPKG package	`374954842a17...3520a11ce`	Download
`openwrt-flowoffload-pbr-mitigation_0.1.4_all.deb`	Debian-style	`374954842a17...3520a11ce`	Download
`openwrt-flowoffload-pbr-mac-misroute-v0.1.4.tar.gz`	Source archive	`6ca03e31be1c...382f5111`	Download
`Packages.gz`	Feed index	`fb6cac04842a...232d87e13`	Download
`v0.1.4.sha256`	Checksum verification	`Release manifest`	Download

Network Namespace Reproducer

A script-driven test environment using Linux network namespaces to simulate a four-node topology (client, router, VPN gateway, WAN responder). Runs on any Linux host with iproute2, nftables, and tcpdump:

# Run lab with flow offload on and mitigation enabled:
sudo ./reproducer/netns-lab.sh run

# Run lab with mitigation disabled to verify failure mode:
sudo FLOW_OFFLOAD=1 MITIGATION=0 ./reproducer/netns-lab.sh run

# Execute automated CI smoke suite:
make smoke

# Clean up namespaces and temporary logs:
make clean

Diagnostics Collection

Gather routing tables, nftables rulesets, flowtable entries, and synchronized LAN/WAN PCAP captures on OpenWrt routers:

# Transfer and execute on router:
./diagnostics/collect.sh

# Artifacts output to /tmp/offload-pbr-diag/

Router Triage Commands

Inspect flowtables:

nft list flowtables
nft list flowtable inet filter ftoffload

Check neighbor resolution:

ip -s neigh show

Inspect LAN L2 destination MAC:

tcpdump -nn -e -i br-lan udp port 53

Trace netfilter rule evaluation:

nft monitor trace

Changelog

v0.1.4

October 2026

Fixed fw4 include chain in mitigation (ft instead of ft_pbr_guard) so guards are evaluated.
Fixed rollback script rule deletion to use rule handles instead of unsupported text matching.
Configured apply.sh to install persistent include to /etc/nftables.d/ before firewall reload.
Preserved namespaces on normal exit in netns-lab.sh for post-run inspection.
Fixed odd query counts in traffic generator and tightened MAC mismatch verification.
Parallelized diagnostic packet captures across LAN and WAN interfaces.

v0.1.2

February 2026

Shortened tcpdump capture timeout to 45s and softened empty-capture handling for CI stability.
Corrected flowtable name for offload-on test case.

v0.1.0

February 2026

Initial release with netns reproducer, diagnostics collector, and firewall4 include hotfix.