# adblock-lean: DNS blocking for OpenWrt that does not stay resident

> adblock-lean is a shell script set for OpenWrt that downloads blocklists, merges and deduplicates them, and pushes the result into dnsmasq as a compressed set, then exits. It leans on the dnsmasq 2.86 rewrite so that very large lists fit on low memory devices.

**lynxthecat/adblock-lean** — Lean and powerful adblocking solution for OpenWrt

- Repository: https://github.com/lynxthecat/adblock-lean
- Website: https://forum.openwrt.org/t/adblock-lean-set-up-adblock-using-dnsmasq-blocklist/157076
- Stars: 601 · Forks: 23
- Language: Shell
- License: GPL-2.0
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/lynxthecat-adblock-lean

## Set and forget, and what that means for the router

adblock-lean is described as a low maintenance, almost set and forget, powerful and ultra-efficient adblocking solution for OpenWrt that does not mandate any external dependencies or introduce unnecessary bloat. Two properties define it. The first is that it is highly optimized for RAM and CPU efficiency during blocklist download and processing, and that it does not remain running in memory after execution. So there is no daemon holding a list in memory on a router with 64 MiB of RAM. The second is that it is designed around the major rewrite of the DNS server and domain handling code associated with dnsmasq 2.86, which the README says drastically improves dnsmasq performance and reduces memory footprint, and that this facilitates the use of very large blocklists even for low spec, low performance devices. The primary language of the repository is Shell, and the licence is GPL-2.0, with the homepage being the official OpenWrt forum thread.

## The feature list, read as an engineering brief

The features list in the README is long, and it reads as a set of decisions about failure modes rather than a wish list. There is automated interactive setup with presets for devices based on memory capacity, from 64 MiB and 128 MiB up through 256, 512, 1024 MiB and higher. Multiple blocklist and allowlist files can be downloaded from user-specified URLs, and local blocklist and allowlist files are supported too. Automatic blocklist updates are supported, and blocklist compression is supported by leveraging the new conf-script functionality of dnsmasq, which significantly reduces memory consumption. The final blocklist is automatically optimized, and entries are deduplicated across all blocklist and allowlist parts. Domains found in the allowlist are removed from the blocklist files to reduce the final size. The last two features are the ones that separate it from a script that concatenates lists: constraints on minimum and maximum size and line count in each part and in the final list, and checks and sanitization of the downloaded parts designed to avoid loading incompatible, corrupted or malicious data.

## Failure handling, which is the real feature

Three features in the list are about what happens when something goes wrong, and they are worth separating out because they are the reason to trust the tool on a router you cannot easily reach. First, during a blocklist update a compressed backup copy of the previous blocklist file is kept until the new blocklist passes all checks, and if the checks fail adblock-lean restores the previous blocklist. That is the difference between a failed download and a working DNS resolver. Second, the configurable constraints on minimum and maximum size and lines count are designed to prevent memory over-use and to minimize the likelihood of loading an incomplete blocklist because of a download error, so a truncated file is rejected rather than applied. Third, there is config validation and optional automatic config repair when problems are detected. On top of that, adblocking can be paused and resumed without re-downloading the blocklist parts, and adblocking works on multiple dnsmasq instances, which matters on a router where the stock configuration has more than one.

## Installing it over SSH

The requirements are OpenWrt 23.05 or later and dnsmasq 2.87 or later, and the README notes that OpenWrt 23.05 includes dnsmasq 2.87, so the two conditions arrive together in practice. You connect to the router over SSH and run two commands, which download the install script and then run it:

```bash
uclient-fetch https://raw.githubusercontent.com/lynxthecat/adblock-lean/master/abl-install.sh -O /tmp/abl-install.sh
sh /tmp/abl-install.sh -v release
```

The install includes an automated interactive setup that asks several questions and makes the important changes based on your replies. If you missed that prompt or want to run it again later, the setup is started with:

```bash
sh /etc/init.d/adblock-lean setup
```

The manual path exists for anyone who wants to see what changes. It makes the script executable, generates a default config in `/root/adblock-lean/config` and sets up blocklist updates, enables the service so it runs on boot, and then optionally installs a few extra tools:

```bash
chmod +x /etc/init.d/adblock-lean # Makes the script executable
service adblock-lean gen_config   # Generates default config in /root/adblock-lean/config and sets up blocklist updates

# This will allow adblock-lean to automatically run on boot
service adblock-lean enable

# Optional/recommended. Makes list processing significantly faster (doesn't affect DNS resolution speed). gawk including dependencies may consume around 1MB. If flash space is an issue, consider skipping gawk installation.
opkg update
opkg install gawk sed coreutils-sort
```

That last block is worth reading carefully, because the trade-off is stated in the comment itself. gawk and its dependencies may consume around 1MB of flash, and if flash space is tight you are told to skip it, with the consequence being slower list processing rather than slower DNS resolution.

## Which dnsmasq instance you attach to

There is a detail here that will cause confusion if you skip it, so the README explains it in a collapsible section. The `gen_config` command is supposed to have worked out the dnsmasq instance automatically, or asked you which one you prefer if you have several, and the guidance is to ignore the manual section unless you have a good reason. The manual procedure starts by checking which `config dnsmasq` sections are defined in `/etc/config/dhcp`. If there is only one, the instance index is 0, and you note the instance name, which is either `cfg01411c` if the name is not specified or the optional word right after `config dnsmasq`. If `option confdir` is set, you note that value, and if it is not set then the default conf-dir is `/tmp/dnsmasq.cfg01411c.d` in OpenWrt 24.10 and later, including current snapshots, or `/tmp/dnsmasq.d` in older versions. If you have multiple sections, multiple instances are running and you have to pick the one you want adblocking on. The conf-dir path is the piece that changes between OpenWrt releases, and it is the kind of thing that breaks silently on a firmware upgrade.

## The layers the tool is built from

The repository layout is small and tells you the shape of the thing. There is `abl-install.sh` as the installer, an `adblock-lean` directory holding the service itself, a `usr/` directory for the files it installs into the system, a `HAGEZI-LISTS.md` file, a `LICENCE.md` and a `README.md`. That HAGEZI file is worth noting, because it points at the well known list collection that the tool's defaults are drawn from, and the repository also has a `test/` directory and a `demo/` directory. The README's table of contents shows the breadth of the configuration surface, with sections for basic configuration, supported formats, adding new lists, advanced configuration, whitelist mode, user-configurable calls on success or failure, checking status, testing advert blocking, preserving files and config across OpenWrt upgrades, version updates, advanced version update options and uninstalling. The two entries about surviving OpenWrt upgrades and about version updates are the ones a user of a router they do not have shell access to will care about most.

## Where this is the wrong choice

The limits are mostly about what kind of blocking this is. First, it is a DNS blocklist mechanism, not a filtering proxy, so there is no per-client policy, no per-category allowlisting for one device on the network, and no way to see which client asked for what. If you want that, you want a filtering resolver, and the topic list on the repository mentions adguard and filterlist, which are the projects in that category. Second, the blocklists are large and growing, and the tool's answer to that is compression and deduplication rather than a smaller list, so the flash and RAM cost of your chosen lists is still yours to manage, and the size constraints exist to stop that going wrong rather than to make it cheap. Third, the tool depends on the dnsmasq rewrite and on a specific conf-dir layout that differs between OpenWrt 24.10 and earlier versions, which means a firmware upgrade is an event that can break the setup, which is why the README has a section on preserving files and config across upgrades. Fourth, the automatic self update is initiated by the user rather than automatic, which is the right default for something that rewrites your resolver config, but it does mean the blocklists and the script go stale if you forget. And fifth, the whole thing assumes you can SSH to the router and edit configuration, so it is not for a locked-down consumer router.

## Conclusion

adblock-lean fits an OpenWrt user on a small router who wants ad blocking without a resident daemon eating RAM, and the design choices line up with that: compressed blocklists, deduplication, size constraints and a script that does its work and leaves. It is the wrong choice if you want per-client filtering, a web dashboard, or a subscription system, since this is a dnsmasq blocklist, not a filtering proxy, and it is the wrong choice on a router below the stated floor of OpenWrt 23.05 with dnsmasq 2.87. Before you install, read the whitelist mode and the allowlist behaviour, because the tool removes domains found in the allowlist from the blocklist, and check the config constraints so a failed download cannot leave you with a truncated list. The last push was on 2026-09-30, the newest release is v0.8.1 from 2025-12-03, and the licence is GPL-2.0.

## FAQ

### What are the requirements for adblock-lean?

OpenWrt 23.05 or later and dnsmasq 2.87 or later, and the README notes that OpenWrt 23.05 already includes dnsmasq 2.87. The design leans on the dnsmasq 2.86 rewrite of DNS and domain handling so that very large blocklists work on low memory devices.

### How do I install adblock-lean on OpenWrt?

Connect over SSH, then download and run the install script with `uclient-fetch https://raw.githubusercontent.com/lynxthecat/adblock-lean/master/abl-install.sh -O /tmp/abl-install.sh` and `sh /tmp/abl-install.sh -v release`. The install offers an interactive setup, which you can also start later with `sh /etc/init.d/adblock-lean setup`.

### What happens if a blocklist download fails or is corrupted?

A compressed backup copy of the previous blocklist is kept until the new blocklist passes all checks, and if the checks fail adblock-lean restores the previous one. Size and line count constraints on each part and on the final list are there to prevent an incomplete blocklist being loaded after a download error, and downloaded parts are sanitized and checked before use.

### Does adblock-lean keep running in memory?

No. The README states that it is optimized for RAM and CPU during blocklist download and processing and does not remain running in memory after execution, which is what allows it to work on devices with 64 MiB of RAM while using compressed blocklists.

## Sources

- [License: GPL-2.0](https://github.com/lynxthecat/adblock-lean/blob/master/LICENSE)
- [lynxthecat/adblock-lean on GitHub](https://github.com/lynxthecat/adblock-lean)
- [Project website](https://forum.openwrt.org/t/adblock-lean-set-up-adblock-using-dnsmasq-blocklist/157076)
- [README](https://github.com/lynxthecat/adblock-lean/blob/master/README.md)
- [Releases](https://github.com/lynxthecat/adblock-lean/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/lynxthecat-adblock-lean