LibWrt: an OpenWrt source tree with NSS support for Qualcomm IPQ routers

The problem the project set out to solve

LibWrt is an OpenWrt source repository for Qualcomm IPQ series devices. The README describes the aim as providing a fully featured OpenWrt system for those devices, and it credits the community with solving a problem IPQ users had faced: running OpenWrt on IPQ series devices had meant giving up some NSS functionality or using an old kernel.

That is the whole pitch, and it is worth being precise about what it involves. Qualcomm's IPQ chipsets have a dedicated network processing unit, and using it is called NSS. A router that offloads packet processing to that unit handles far more throughput on the same CPU than one doing everything in software, and on a consumer router that is the difference between a usable gigabit connection and a saturated CPU.

The historical problem was that the NSS vendor tree and the mainline kernel tree had diverged. A user who wanted OpenWrt's current packages and kernel support had to give up the acceleration, and a user who wanted the acceleration had to stay on an old kernel with old packages.

The project solves this by merging rather than choosing. The README says it merged the NSS support code of two developers, JiaY-shi and qosmio, and adopted the LuCI interface and package feed from ImmortalWrt. Both upstream efforts are credited by name and linked.

The result is a fork with its own identity rather than a patch set. The default branch is 25.12-nss, the releases are named v25.12.2, v25.12.1 and v25.12.0, and the repository is under the LiBwrt organisation with a Chinese-language README and an English one at README-en.md.

The device support table, and what it rules out

The README opens with a device support overview, and the table is short enough to be decisive.

For the IPQ807X and IPQ60XX series, NSS functionality is supported, and both 2.4 GHz and 5 GHz Wi-Fi have NSS offload. For the IPQ50XX series, all three columns are marked unsupported. So the project covers two of the three families in scope and excludes the third entirely.

That exclusion is worth pausing on, because IPQ50XX is the entry-level part and it appears in plenty of budget routers. The README does not explain why, and does not need to: without NSS there is no reason to use this fork over stock OpenWrt, since the fork's entire purpose is to keep the acceleration.

The Wi-Fi columns say NSS offload, which is a separate mechanism from the general packet path. Both are marked as supported on the two families that qualify.

The default branch naming is also informative. 25.12-nss ties the tree to a specific OpenWrt release series with the NSS patches applied, so you know what base you are building on, and the release tags v25.12.0, v25.12.1 and v25.12.2 follow the same convention with a patch number. The last push was on 2026-09-29, and the newest release, v25.12.2, is from 2026-09-07.

The feature matrix: tunnels work, VPN protocols do not

The second table is the most useful documentation in the repository, because it tells you exactly which protocols keep their acceleration.

On the working side, both chips support TUNIPIP6, PPPOE, L2TPV2, BRIDGE, VLAN, MAP_T, TUN6RD, GRE, PPTP, IGS, VXLAN and MATCH. MIRROR is supported on both, and WIFI in AP and STA mode is supported on both.

On the not-working side, IPSEC, PVXLAN, CLMAP, TLS, CAPWAP and DTLS are marked unavailable on both chips, with the footnote that these are unavailable in NSS firmware versions 11.4 to 12.5. That is a meaningful limitation for anyone running a VPN or a TLS-terminating service on the router.

There is a third category, the conditional ones. RMNET is marked as requiring NSS firmware 11.4, with the configuration CONFIG_NSS_FIRMWARE_VERSION_11_4=y, and is separately noted as not available on one of the two platforms. WIFI in WDS and MESH modes and the BRIDGE entry are marked as requiring firmware 11.4 as well.

And there is a fourth: WIFI in AP VLAN mode is marked as faulty in the ath11k driver. That is a driver bug rather than a firmware limitation, and it is the kind of detail that only surfaces in a matrix maintained carefully by people who get support questions.

The legend underneath spells out each marker: a conditional marker means NSS firmware version 11.4 is required with that configuration option set, a barred marker means the feature is not available on that platform, a cross marker means unavailable in NSS firmware 11.4 to 12.5, and a warning marker means the feature is faulty in the ath11k driver.

For anyone deciding whether to flash this onto a router they depend on, this table is the document to read. It says plainly which features will still be accelerated and which will silently fall back.

Building the firmware: cloud images and a local toolchain

There are two routes to a firmware image.

The cloud route is a list of four community CI projects the README points to, including breeze303/openwrt-ci, ZqinKing/wrt_release, laipeng668/openwrt-ci-roc and VIKINGYFY/OpenWRT-CI. Using one of these means you never install a toolchain locally, which is the sensible choice for anyone who only wants the binary.

The local route has explicit prerequisites. The README warns against compiling as the root user, suggests that users in China enable a network proxy before building, and states that the build environment needs at least 4GB of memory and 25GB of free disk space. The recommended host is Ubuntu 22.04 LTS or Debian 11. The default configuration gives a login IP of 192.168.1.1 with the password none.

The dependency install is a long apt line covering the usual OpenWrt build requirements: ack, antlr3, asciidoc, autoconf, automake, binutils, bison, build-essential, ccache, cmake, cpio, curl, device-tree-compiler, flex, gawk, gettext, the multilib compilers, git, gperf, libelf, libglib2.0, libssl, libtool, ninja, python3, qemu-utils, rsync, squashfs-tools, swig, texinfo, unzip and wget among others.

Then the source and configuration steps:

git clone -b 25.12-nss --depth 1 --single-branch https://github.com/LiBwrt/LibWrt.git libwrt
cd libwrt

followed by the feeds update and install, then make menuconfig for the configuration.

The first build downloads dependencies in parallel and then compiles:

make download -j$(nproc)

make -j1 V=s

The README suggests compiling single-threaded on the first build so that errors are easier to trace, which is a reasonable piece of advice. The finished firmware ends up under the bin/targets directory.

Rebuilding and reconfiguring after the first image

The README's later steps cover the two operations you will actually perform repeatedly.

For a second build that keeps your configuration, you fetch the latest code and hard-reset to the branch, update the feeds, load the default configuration and build:

git fetch && git reset --hard origin/25.12-nss

./scripts/feeds update -a && ./scripts/feeds install -a

make defconfig

make -j$(nproc) V=s

The hard reset is the significant part of that sequence. It throws away local changes to tracked files, which is what makes the flow reproducible, and it also means a config file kept outside the repository or a change to the source is lost. The configuration itself survives because it lives in .config, which is not tracked.

For a clean reconfiguration, the README has a separate path. You remove the .config file entirely, run make menuconfig again to pick your options from scratch, and rebuild. That is the procedure to use when your configuration has drifted into a state where make defconfig does not produce what you expect.

The V=s flag on the make invocations is the OpenWrt convention for verbose output, printing the full command lines rather than the abbreviated ones, which is what you want when a build fails in a package.

The Makefile at the root of the repository is stock OpenWrt, with the standard structure of toolchain, tools, target and package sub-makes, a check target that runs the toolchain, tools and package stamp checks, and a guard against building in a path containing spaces. The rest of the tree is the standard OpenWrt layout as well, with config/, include/, package/, scripts/, target/, toolchain/ and tools/ directories plus the top-level Config.in and feeds.conf.default.

Limits: hardware coverage, firmware versions and the fork's own upkeep

The limits are stated in the tables and in the build requirements, and they are the ones you should check before installing anything.

The first is hardware. IPQ50XX is out of scope entirely, and the two supported families are the specific ones with NSS. If your router is on a different Qualcomm part, this fork does nothing for you.

The second is the firmware version dimension. Several features require NSS firmware 11.4 with a specific configuration option enabled, and the IPQ60XX lacks RMNET entirely. The NSS firmware lives in a separate download that is not part of this repository, so the version you have installed on the device, or that the image bundles, decides what works.

The third is the protocol set. IPSEC, PVXLAN, CLMAP, TLS, CAPWAP and DTLS are not accelerated on either supported chip within the 11.4 to 12.5 firmware range, and AP VLAN mode is faulty in the ath11k driver. For a router used as a VPN endpoint or a TLS terminator, those are not edge cases.

The fourth is the fork's own maintenance burden. A fork of a large project like OpenWrt has to be rebased onto every upstream release, and the release list shows the pattern: v25.12.0 in May 2026, v25.12.1 in July and v25.12.2 in September. That is roughly a six-week cycle, which is the pace you would expect, and it means you are choosing a branch that is a few weeks behind upstream.

The fifth is the build environment. 4GB of memory and 25GB of disk is what the README asks for, and the dependency list is long enough that a clean machine needs the full apt line before anything works. That is the cost of building OpenWrt itself rather than of this fork in particular, but it is why the cloud build projects are listed first.

Finally, the licence is a custom one that GitHub cannot classify, with the COPYING file and a LICENSES/ directory in the tree. For a fork of GPL software that ships firmware to your own hardware, the licensing terms are likely to be the upstream ones, but the custom classification is a reason to read the file before redistributing anything.

LibWrt against stock OpenWrt and against the upstream NSS forks

Two comparisons make the choice clearer.

The first is against stock OpenWrt for the same hardware. Stock OpenWrt is the better-maintained, better-documented option and it has the kernel and packages that upstream OpenWrt supports. What it does not have is the NSS acceleration on these chipsets, which in practice means the routing throughput of a much weaker device. If your router is handling a gigabit line and the CPU is the bottleneck, the difference is not a preference but a capability.

The second comparison is against the NSS forks that already existed, the ones by JiaY-shi and qosmio that this project merged. Those forks were where the NSS patches lived, and they were the reason a user had to choose between acceleration and a current kernel. LibWrt's contribution is the merge and the ongoing rebasing, plus the support matrix, the build documentation and the package feed from ImmortalWrt.

That last point deserves emphasis, because the matrix is the real artifact. A NSS fork that patches the kernel will work for the person who wrote it, and the next person will have to discover by experiment which features still accelerate after a firmware update. A documented matrix with explicit firmware version requirements converts that experimentation into a lookup.

The honest caveat is about what the fork inherits. It is built on OpenWrt, so it inherits OpenWrt's own release cycle, its security response and its package ecosystem, and it adds a layer of rebasing on top. A fork of a fork of a vendor tree is inherently a maintenance position, and the meaningful question for any user is how quickly a security update reaches their router, which is a question about the maintainers rather than about the code.

The decision is usually straightforward for the target user. If you have an IPQ807X or IPQ60XX router and you want the CPU headroom that NSS gives you while keeping current packages, this fork exists to make that possible, and the matrix tells you exactly what you get.

Editorial conclusion

Adopt LibWrt if you run a Qualcomm IPQ807X or IPQ60XX router and want NSS acceleration together with a current kernel instead of having to choose between the two. Do not adopt it for IPQ50XX hardware, where the matrix shows no NSS support at all, and expect the acceleration caveats to matter, since several protocols are marked as broken or firmware-dependent. Verify first that your exact chip and NSS firmware version match the support matrix, and that the VPN or tunnel protocols you rely on are not among the ones listed as unavailable in NSS firmware 11.4 to 12.5.

Frequently asked questions

Official sources

1. Issues
2. LiBwrt/LibWrt on GitHub
3. Project website
4. README
5. Releases