youtubeUnblock: filtering YouTube traffic at netfilter level on Linux

A targeted tool for one platform, on purpose

youtubeUnblock exists to work around one specific mechanism. The README describes it as a program that bypasses YouTube detection systems that rely on SNI, and says it was primarily developed to bypass the YouTube outage in Russia. The scope restriction is explicit and repeated: the program should be used only for the YouTube platform, and it must not be used for any other purpose. The reasoning offered is that access to YouTube is not officially restricted in Russia, and the author asks that it be used only in accordance with the laws of the reader's country.

That framing matters when you decide whether to run it. This is not a general purpose censorship tool with a config file listing domains, it is a program written for one service, and the author's position is that the problem it solves is a service outage rather than a general filtering regime.

Technically the project is Linux only, written in C, and licensed under GPL-3.0. The last push to the repository was on 2026-08-30, and the release history shows v1.3.1 on 2026-04-08, v1.3.0 on 2026-01-31 and v1.1.1 on 2025-12-28. The source tree holds a `src/` directory for the program, a `deps/` directory, a `test/` directory, and a `Padavan.md` file, which suggests support for a third router firmware in addition to OpenWRT and Entware.

Why the project ships two implementations

The same goal is reached in two very different ways, and the README is candid that the choice is a trade-off rather than a preference.

The userspace application is the default and the one normally used. It works on top of the nfnetlink queue, which requires the nfnetlink modules in the kernel plus firewall rules. The stated limitations are concrete. On embedded devices there may be no nfnetlink support at all, and the solution can reduce internet speed and raise CPU load because of the jumps between userspace and kernelspace for each packet. The README adds that this behaviour may be fixed with connbytes, but that in turn requires the conntrack kernel module, and conntrack can itself be a limitation on machines carrying transit traffic.

The kernel module integrates directly inside the netfilter stack and does not interact with the userspace firewall at all. Its requirement is stated more simply: netfilter kernel support, which the README says is present on every device connected to the internet. The catch is entirely on the build side. The maintainer explains that prebuilt modules cannot be supplied through GitHub Actions for each single kernel, even when the scope is limited to OpenWRT versions.

The performance argument is the main reason to consider the module. The README states that the kernel module is the fastest option because it processes every packet sent to the Linux network stack, while the normal userspace version needs connbytes to keep the internet speed up. In exchange, building it requires either a matching host system, a generic kernel build, or the OpenWRT SDK.

The Makefile splits the two builds into separate makefiles

The build system is plain make, and the top level `Makefile` exists mainly to dispatch into two different build systems, one per implementation. The userspace targets are `default`, `all`, `install`, `uninstall`, `dev` and `run_dev`, and each one is forwarded to `uspace.mk` with a recursive make call. The kernel targets are `kmake`, `kload`, `kunload`, `kreload`, `xmod` and `xtclean`, and they are forwarded to `kmake.mk`.

The `Makefile` also owns the version numbers, which the README and the release names both track. `PKG_VERSION` is `1.3.1` and `PKG_RELEASE` is `1`, giving `PKG_FULLVERSION` of `1.3.1-1`, and those variables are exported so the packaging step can use them.

USPACE_TARGETS := default all install uninstall dev run_dev
KMAKE_TARGETS := kmake kload kunload kreload xmod xtclean

PKG_VERSION := 1.3.1
PKG_RELEASE := 1

Beyond the two forwarded groups, the `Makefile` defines its own convenience targets. `build_test` and `test` call into `uspace.mk`, so the test suite belongs to the userspace side, while `clean`, `distclean` and `kclean` split the cleanup between the two worlds. The presence of a `Kbuild` file and a `kmake.mk` next to `uspace.mk` is the giveaway that the kernel side follows the kernel's own build conventions rather than the userspace one.

The module lifecycle also has a loading story, which is why `kload`, `kunload` and `kreload` exist as separate targets rather than a single build. The tree also contains a `youtubeUnblock.service` unit file and a `youtubeUnblock.pem` public key, and `.gitmodules` indicates that at least one dependency is pulled in as a submodule.

Installing on OpenWRT, Entware and apk-based images

For router firmware the project ships packages, and the README describes the router-side flow in enough detail to follow. With a release package in hand you install it through the router interface, going to System and Software, running Update lists, and then using the install package button. After that you go to the System and Startup menu and reload the firewall, or do the same from the Services and youtubeUnblock menu.

Package managers differ by firmware generation. The README says that on both OpenWRT and Entware you install with opkg, and that if you hit a read-only filesystem error you can unpack the binary manually or point opkg at a different destination with `opkg -o <destdir>`. It also says that OpenWRT main switched to apk instead of opkg, that apk is not yet in Releases, and that apk support exists in a pull request.

The warning that follows is the one to note if you run a 24.10 image: you get an UNTRUSTED SIGNATURE error. The fix is to put `youtubeUnblock.pem` into `/etc/apk/keys/`, or to install the package with the `--allow-untrusted` flag.

apk add youtubeUnblock*.apk --allow-untrusted

Binaries are also available through GitHub Actions and through GitHub releases, and the README advises using the latest pre-release for the most current build. Choosing the right binary requires knowing your hardware architecture, and on OpenWRT the README gives the command that reports it.

grep ARCH /etc/openwrt_release

Firewall rules, conntrack and the cost of the userspace path

Installing the package is not enough. The README states that to make it work you must register an iptables rule and install the required kernel modules, and that which modules those are depends on the OpenWRT version and on whether you use iptables or nftables. For recent OpenWRT versions, the v23.x and v22.x lines, the README points at the nftables rules, with older versions depending on the setup. The full rule text is in sections of the README that are not reproduced in the tree listing available here, so the exact commands have to be taken from the project documentation rather than from this summary.

The conntrack and connbytes question is the substantive part. The userspace implementation processes packets through the nfnetlink queue, and the cost of the userspace to kernelspace transition per packet shows up as speed and CPU load. The README's own recommendation is that connbytes addresses this, and that connbytes in turn needs conntrack. A separate troubleshooting entry in the README's table of contents is dedicated to conntrack, and another covers NAT hardware and software offloading, which is the same concern seen from the other side: if the router offloads NAT in hardware, the packets may bypass the path where the program intervenes.

There is also an IPv6 section in the configuration part of the README, and the same document has a dedicated entry for troubleshooting EPERMS, Operation not permitted, which points at the permissions needed to attach to the network stack. Both entries exist because they are the two failure modes a first-time installer is most likely to hit.

The README also carries a section on UDP and QUIC and one on Cloudflare, which is a good sign for a program that must keep working against a CDN that changes how clients are detected and routed.

What the project does not do, and where the friction is

Two limits are worth stating before you build this into a router you depend on.

The first is the legal and scope limit, which is the author's own condition rather than a technical one: YouTube only, and only in accordance with local law. The README is clear that access to YouTube is not officially restricted in Russia, and the whole legal argument rests on that specific fact. A reader in a jurisdiction where the service is restricted should not assume the same reasoning transfers.

The second is the operational one, and it is about how you obtain the program. The maintainer says plainly that prebuilt kernel modules cannot be provided for each single kernel, even for OpenWRT versions alone, and points readers at the kernel module section of the README for the three documented build paths: building on the host system, building on any kernel, and building with the OpenWRT SDK. The first two mean a machine that can compile a kernel module, and the third means the vendor SDK for the exact router firmware. In practice, a router user who wants the module will spend considerably more time on the build than on the installation, and the userspace application is the path most people should take first.

The README also has entries for TV devices and for the general troubleshooting questions, which tells you the project is used on more than routers, even though the target platform is Linux only. Entware on Keenetic and ASUS routers, and the Padavan firmware file in the repository, widen that range further.

Editorial conclusion

Adopt youtubeUnblock if you run Linux or an OpenWRT router in a network that blocks YouTube by SNI inspection and you want the fix applied at the netfilter layer rather than with a proxy client, because the userspace build installs on any Linux box and the kernel module removes the per-packet context switch. Do not adopt it for traffic other than YouTube, since the README restricts the program to that platform, and do not pick the kernel module unless you already build for your kernel, because the maintainer states that prebuilt modules cannot be provided for every kernel. Before deploying, check the architecture of your hardware with `grep ARCH /etc/openwrt_release`, confirm that nfnetlink or netfilter support is present, and decide whether conntrack and connbytes are available, since the userspace path depends on them for speed.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. README
4. Releases
5. Waujito/youtubeUnblock on GitHub