{"id":51398777,"url":"https://github.com/packerlschupfer/octeon-flowtable","last_synced_at":"2026-07-04T04:38:18.016Z","repository":{"id":362744545,"uuid":"1259549242","full_name":"packerlschupfer/octeon-flowtable","owner":"packerlschupfer","description":"Clean-room nftables flow offload for Cavium Octeon+ (CN50xx) — hardware-accelerated NAT/routing on OpenWrt for the EdgeRouter Lite 3","archived":false,"fork":false,"pushed_at":"2026-06-05T17:13:14.000Z","size":139,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-05T19:15:04.137Z","etag":null,"topics":["clean-room","cn50xx","edgeos","edgerouter-lite","erlite","flow-offload","hardware-offload","kernel-module","mips64","nat","netfilter","nftables","octeon","openwrt","qinq","reverse-engineering","ubiquiti","vlan"],"latest_commit_sha":null,"homepage":null,"language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/packerlschupfer.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-04T16:06:55.000Z","updated_at":"2026-06-05T17:13:18.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/packerlschupfer/octeon-flowtable","commit_stats":null,"previous_names":["packerlschupfer/octeon-flowtable"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/packerlschupfer/octeon-flowtable","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/packerlschupfer%2Focteon-flowtable","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/packerlschupfer%2Focteon-flowtable/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/packerlschupfer%2Focteon-flowtable/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/packerlschupfer%2Focteon-flowtable/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/packerlschupfer","download_url":"https://codeload.github.com/packerlschupfer/octeon-flowtable/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/packerlschupfer%2Focteon-flowtable/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35110270,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-04T02:00:05.987Z","response_time":113,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["clean-room","cn50xx","edgeos","edgerouter-lite","erlite","flow-offload","hardware-offload","kernel-module","mips64","nat","netfilter","nftables","octeon","openwrt","qinq","reverse-engineering","ubiquiti","vlan"],"created_at":"2026-07-04T04:38:17.264Z","updated_at":"2026-07-04T04:38:18.005Z","avatar_url":"https://github.com/packerlschupfer.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# octeon-flowtable\n\nA clean-room **nftables flow-offload backend** for the Cavium **Octeon+ (CN50xx)**\npacket complex — the SoC in the Ubiquiti EdgeRouter Lite 3 (ERLite-3). It gives an\nERLite-3 running mainline OpenWrt hardware-accelerated NAT/routing that **matches\nthe proprietary EdgeOS offload**, using only GPL kernel sources and the public\nOCTEON hardware reference manual — **no Ubiquiti binary, no Cavium SDK**.\n\nA WQE-level RX hook intercepts forwarded packets *before* any skb is built,\nrewrites L2/L3/L4 in the FPA packet buffer (NAT, next-hop MAC, TTL/hop-limit, VLAN\ntags) with incremental checksums, and transmits via PKO — no skb, no Linux stack.\nMisses fall through to normal forwarding.\n\n## Results (on a real ERLite-3, CN5020, 2×500 MHz)\n\n| metric | OpenWrt software | **this driver** | EdgeOS vendor |\n|---|---|---|---|\n| single-flow TCP NAT | 764 Mbps | **932 Mbps** | 940 Mbps |\n| multi-flow TCP NAT | 941 Mbps | **935 Mbps** | 563 Mbps |\n| UDP-64 NAT (pps) | 73k | **431k** | 247–431k |\n| RTT under load | 6.1 ms | **2.1 ms** | 2.6 ms |\n\n5.9× the software baseline on small-packet pps, 3× better latency — matching the\nvendor it reverse-engineered.\n\n## What it accelerates\n\nIPv4 + IPv6, NAT + routing, untagged + **802.1Q VLAN** (retag / pop / push) +\n**QinQ** (two tags) — all hardware-verified. Plus a global hardware FAU counter\nand a **PKO tail-drop AQM** that cuts bufferbloat 54 ms → 4 ms at equal\nthroughput. See [`docs/PROJECT-OUTCOME.md`](docs/PROJECT-OUTCOME.md) and\n[`docs/FUTURE-WORK.md`](docs/FUTURE-WORK.md) for the full matrix.\n\n## Layout\n\n```\ndocs/      design RFC, hardware model, behavioural spec, build + install guides, outcome\nsrc/octeon_flowtable/     the kernel module\nsrc/octeon_flowtable/tests/  regression suite + nft/topology rigs (see Testing)\nsrc/staging-patches/      the octeon_ethernet hook patch (adds the exported hooks)\npackage/octeon-flowtable/ OpenWrt kmod package (init script + UCI config)\nprompts/   reproducible runbooks (build / deploy / EdgeOS→OpenWrt config migration)\n```\n\n## Quick start\n\n1. Apply `src/staging-patches/120-octeon-flowtable-hooks.patch` to your OpenWrt\n   octeon kernel (`target/linux/octeon/patches-6.18/`) and rebuild.\n2. Build the module: `cd src/octeon_flowtable \u0026\u0026 make octeon OWRT=/path/to/openwrt`\n   (or select **kmod-octeon-flowtable** from `package/` in menuconfig).\n3. Enable hardware offload in `/etc/config/firewall`:\n   `option flow_offloading '1'` + `option flow_offloading_hw '1'`, then `fw4 reload`.\n4. Verify: `conntrack -L | grep HW_OFFLOAD`.\n\nBuilding from source: [`docs/BUILDING.md`](docs/BUILDING.md). Installing,\nenabling, and tuning: [`docs/INSTALLING.md`](docs/INSTALLING.md). Reproducible\nrunbooks: [`prompts/`](prompts/).\n\n## Prebuilt image\n\nDon't want to build the toolchain yourself? Tagged releases ship ready-to-flash\nEdgeRouter Lite images on the [Releases](../../releases) page, built by CI straight\nfrom this repo (GitHub Actions → [`build-image.yml`](.github/workflows/build-image.yml)).\nThe kernel already carries the staging hook patch and the offload tuning\n(CVMSEG=2, `receive_group_order=1`); `kmod-octeon-flowtable` is preinstalled.\n\nTwo variants are published (asset names prefixed `lean-` / `router-`):\n\n- **lean** — offload + `conntrack`/`tcpdump`; a clean base to add your own packages to.\n- **router** — lean + LuCI web UI + WireGuard, for a more turnkey home router.\n\nThe build is fully pinned (OpenWrt main @ `84f4f77`, kernel 6.18.34, pinned\n`packages`/`luci` feeds) so a given tag reproduces byte-for-byte — see [`ci/`](ci/).\n\n\u003e ⚠ **Unofficial community image for EOL hardware — flash at your own risk.** The\n\u003e ERLite installs via USB stick / U-Boot, not web sysupgrade; recovery over\n\u003e U-Boot/TFTP is in [`docs/INSTALLING.md`](docs/INSTALLING.md). Verify\n\u003e `sha256sums.txt` before flashing.\n\nTo cut a release: push a `v*` tag (`git tag v0.1.0 \u0026\u0026 git push origin v0.1.0`).\n`workflow_dispatch` builds the image without releasing (artifacts only).\n\n## Testing\n\n[`src/octeon_flowtable/tests/regression.sh`](src/octeon_flowtable/tests/regression.sh)\nis a 14-check regression suite run from a bench host against a DUT router\n(~8 min, exit code = failure count). It covers both flowtable VLAN encodings\n(subinterface-implicit and bridged-LAN lower-device with explicit\n`VLAN_PUSH`/VLAN-agnostic match), TCP **and** UDP in both directions at line\nrate, kill-`-9` tuple reuse with stale-entry eviction, fw4 reload churn\n(duplicate-entry leak check), orphan GC, link-flap recovery, and idle settle.\nOne check is worth stealing for any offload driver: it **proves fast-path\nengagement from the driver's `tx_ok` packet counter delta** rather than\ninferring it from throughput — on an idle router the software path also hits\nline rate, which can silently turn an offload test into a no-op. Run it after\nany module or staging-patch change before deploying.\n\nThe suite's preflight self-heals its topology (a `wan` netns endpoint and a\ntagged client subif). The remaining `tests/*.nft` files and `*-rig.sh` scripts\nare the standalone topology rigs used during VLAN/QinQ/IPv6 bring-up.\n\n## Status \u0026 caveats\n\nTested on the [ERLite-3](https://openwrt.org/toh/ubiquiti/edgerouter_lite) / CN5020\nagainst OpenWrt's kernel 6.18.34 (see that page for the device's hardware specs,\nserial-console pinout, and the stock OpenWrt install/recovery procedure). The\nCN50xx is a ~2008-era Octeon Plus part, long since discontinued; this exists\nbecause it's a tractable hardware-fast-path target on cheap silicon, not because\nthe world needs another router stack. Hardware ceilings (PIP\nparses ≤ 2 VLAN tags; the flowtable offloads TCP/UDP/GRE only; v6 extension\nheaders go slow-path) are documented in `docs/FUTURE-WORK.md`. VPN: transit\nWireGuard/IPsec-NAT-T is already offloaded (it's UDP); VPN *termination* is crypto,\na separate problem — see `docs/COP2-CRYPTO-SCOPING.md`.\n\n## Community\n\nQuestions, hardware quirks, or just want to compare notes on Octeon NPU\nprogramming? If you'd rather not open a GitHub issue for every little thing,\nyou're welcome to drop into the Discord:\n\n**[discord.gg/vbNaQRQ4cs](https://discord.gg/vbNaQRQ4cs)**\n\nNo pressure either way — issues and PRs are equally welcome. There's also a\n[project wiki](../../wiki) for longer-form notes.\n\n## License\n\nGPL-2.0 (it's a Linux kernel module). See [`LICENSE`](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpackerlschupfer%2Focteon-flowtable","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpackerlschupfer%2Focteon-flowtable","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpackerlschupfer%2Focteon-flowtable/lists"}