A selective CPU bypass manager for Qualcomm NSS (Network Subsystem) on OpenWrt.
This tool allows you to mark specific connections so they are processed by the CPU instead of the NSS hardware accelerator.
Also compatible with MediaTek PPE/HNAT, other SFE solutions and Software Flow Offload.
Useful (and needed) for:
- Traffic that needs deep inspection (e.g.,
tcpdump,bandwidthd,snort) - Debugging or troubleshooting NSS offload issues
- Per-flow bypass rules without disabling NSS globally
No service/network restart required to bypass (hot-swapping) any NSS connection.
📌 Check
CHANGELOG.mdfor detailed history /PENDING.mdfor pending work.
# Bypass all traffic from a specific device
nss-switch add --src-ip 192.168.1.50 --comment "PC off NSS"
# Bypass SSH traffic (temporary)
nss-switch add --proto tcp --dst-port 22 --temp
# Interactive: pick a connection and create a rule
nss-switch pick
# Live monitor with 5-second refresh
nss-switch watch 5
| Command | Description |
|---|---|
nss-switch watch [--once] [interval] |
Live TUI monitor – refreshes every interval seconds. Use PgUp/PgDown / mouse to scroll. |
nss-switch pick |
Browse all active connections interactively and create a bypass rule from the selected one. |
nss-switch add [options] |
Manually add a bypass rule. |
nss-switch list |
List all defined bypass rules. |
nss-switch remove <id> |
Remove a bypass rule by ID. |
nss-switch kill <id> or [--options] |
Kill active connections matching rule ID, or --flags. |
nss-switch flush [--rules|--all|--temp] |
Remove rules from nftables. |
nss-switch apply |
Re-apply rules.conf to nftables. |
nss-switch status |
Show full status dashboard (ECM state, rules, conntrack). |
nss-switch config [KEY] [VALUE] |
View or set configuration (PERSIST_DEFAULT, DEBUG_MODE, WATCH_INTERVAL). |
nss-switch debug <subcmd> |
Debugging tools – see nss-switch debug --help. |
| Option | Description |
|---|---|
--proto tcp|udp|icmp|any |
Match protocol |
--src-ip <IP/CIDR> |
Match source IP or subnet |
--dst-ip <IP/CIDR> |
Match destination IP or subnet |
--src-port <port> |
Match source port (TCP/UDP) |
--dst-port <port> |
Match destination port (TCP/UDP) |
--iface <interface> |
Match input interface (out:<iface> for egress) |
--persist |
Rule survives reboot |
--temp |
Temporary rule (lost on reboot) |
--comment <text> |
Human-readable label |
--no-defunct |
Skip ECM defunct after adding |
- - OpenWRT +25.12 with NSS (QCA SSDK) enabled
- - Full
conntrack/iptables-nftsupport.
-
- Intended for
ipq807xdevices with NSS hardware offloading capabilities. Shell / C hybrid for performance optimisation.
- Intended for
-
beta-stagingversion for any platform (noarch)- Targeted for any device equipped with NSS, as well as any device using Software Flow Offloading (SFE). Bad performance (10x slower than C compiled components version). Suitable for tests or debug.
nss-switch-1.0.0-r1-aarch64-selfsigned.apk --allow-untrustedRSA
nss-switch.rsa.pubpublic key is included in the repository/releases so it can be added to/etc/apk/keys/directly, making the--allow-untrustedflag unnecessary.
- Using
install.shscript
# Put the install.sh into your /tmp/ and run the installer
chmod +x install.sh
./install.shThe installer:
- Copies all scripts to
/usr/bin/NSS-Switch/ - Creates the needed symlinks
- Sets up persistent firewall includes for
fw4 - Installs default configuration
Mark 0x00010000 to desired packet -> Makes an ECM defunct -> So, CPU handles this traffic -> NSS bypass achieved
NSS-Switch injects
nftablesrules into the kernel'smanglepre&posttables to set a specific packet mark (0x00010000) on matching connections. This mark is designed to not interfere with other marking schemes.
-
Marking: When a packet matches a user-defined rule (by IP, port, interface, etc.), nftables applies the
0x00010000mark to the packet. -
Saving to conntrack: A postrouting rule saves this mark to the connection tracking entry (
ct mark), ensuring both directions of the flow carry the same mark.
When ECM (Enhanced Connection Manager) detects this mark in a packet, it defuncts the connection (to shut it down for an established NSS path), forcing an immediate re‑evaluation. The mark persists as long as the rule persist, so ECM hands the flow to the CPU instead of the NSS hardware accelerator as needed.
- ECM defunct: The Enhanced Connection Manager (ECM), which normally accelerates connections via NSS hardware, detects this mark and immediately defuncts the connection, forcing a full re‑evaluation.
Now, the connection is processed by the CPU, bypassing NSS acceleration entirely.
No service restart is required, and only the marked connections are affected , and NSS continues to accelerate all other traffic normally.
-
CPU takeover: Because the mark persists, ECM hands the flow to the standard Linux network stack (CPU) instead of offloading it to NSS hardware.
-
Restore on reply: A prerouting rule restores the mark from conntrack for reply packets, maintaining bypass status in both directions.
| Qualcomm NSS (ipq807x, ipq60xx, ipq50xx) | ✅ Tested on ipq807x, expected to work on others |
| Other offload engines (SFE, PPE, Flowtable) | ✅ Compatible, not tested, expected to work |
nftables + conntrack |
✅ Fully working |
| Interactive UI (watch/pick) | ✅ Working |
| Persistent rules | ✅ Survive reboots |
📌 See
CHANGELOG.mdfor details /PENDING.mdfor pending work.
This tool is not yet ready for an official OpenWrt package.
## Reason
NSS-Switch is only useful for users running a non-official OpenWrt fork with NSS support (typically developed maintained by @AgustinLorenzo, here). Mainline OpenWrt does not include NSS drivers.
- [2025-05-23] Submitted for review and inclusion into official OpenWrt repositories, as it is compatible with any platform with SFE (Software Flow Offloading) in use and/or QualcommAX platforms with NSS.
- Test on other SoC's which includes any NSS solution (
ipq60xx,ipq50xx) - Report bugs with
nss-switch debug envoutput - Submit fixes or improvements
GPL-2.0
- @AgustinLorenzo / @qosmio: OpenWrt NSS forks,
nss_packages,qca-ssdk, and inspiration - Any community testers on
ipq807xhardware