Awesome

⚔ adblock-lean

If you like adblock-lean and can benefit from it, then please leave a ⭐ (top right) and become a stargazer! And feel free to post any feedback on the official OpenWrt thread here. Thank you for your support.

adblock-lean is highly optimized for RAM & CPU efficiency during blocklist download & processing, and does not remain running in memory after execution. adblock-lean is designed to leverage the major rewrite of the DNS server and domain handling code associated with dnsmasq 2.86, which drastically improves dnsmasq performance and reduces memory footprint. This facilitates the use of very large blocklists even for low spec, low performance devices.

USER NOTICE: Current versions September 19, 2024 and onwards switch to using raw formatted blocklists by default (the default lists are still Hagezi). Dnsmasq formatted lists are still supported. Raw lists have the benefit of smaller file size dowload, improvements in processing speed and reduced ram usage. On the first run after updating, adblock-lean will prompt you (y/n) to automatically change URLs for Hagezi & OISD lists from dnsmasq format to raw format. For other lists, you can choose to find a raw formatted list or continue using dnsmasq formatted lists. You can always use service adblock-lean gen_config to generate a fresh configuration file if required.

Hagezi raw lists can be found here. NOTE that the file names of correct lists have the -onlydomains suffix. Visual example of raw blocklist_urls Hagezi light raw.
Visual example of dnsmasq formmatted dnsmasq_blocklist_urls Hagezi light dnsmasq.

oisd raw domains-formatted lists can be found here. NOTE that the correct lists are only the ones named domainswild2 (note the 2). oisd dnsmasq-formatted lists can be found at the same URL, except you would be looking for lists named dnsmasq2.

The default Hagezi dnsmasq format lists hagezi are recommended to block as many ads, affiliate, tracking, metrics, telemetry, fake, phishing, malware, scam, coins and other "crap" as possible, all while breaking as few websites as possible. Any other raw or dnsmasq format lists of your choice can also be configured and used.

Installation on OpenWrt

adblock-lean is written as a service script and is designed to run on a base OpenWrt installation without any dependencies.

uclient-fetch https://raw.githubusercontent.com/lynxthecat/adblock-lean/main/adblock-lean -O /etc/init.d/adblock-lean
chmod +x /etc/init.d/adblock-lean
service adblock-lean gen_config   # generates default config in /root/adblock-lean/config
uci add_list dhcp.@dnsmasq[0].addnmount='/bin/busybox' && uci commit   # Optional/recommended.  Enables blocklist compression to reduce RAM usage
service adblock-lean enable   # this will allow the script to automatically run on boot

A text editor like nano or vi can be used to modify the config file as needed:

opkg update
opkg install nano
nano /root/adblock-lean/config

Whilst adblock-lean does not require any dependencies to run, its performance can be improved by installing GNU awk, GNU sed and GNU sort:

opkg update
opkg install gawk sed coreutils-sort

adblock-lean automatically checks for any version updates both at the end of the start and status routines. adblock-lean can be updated to the latest version by simply running:

service adblock-lean update

Automatically update blocklist at 5am following delay by random number of minutes

Set up the following Scheduled Task:

0 5 * * * /etc/init.d/adblock-lean enabled && export RANDOM_DELAY="1" && /etc/init.d/adblock-lean start

This tests whether the adblock-lean service is enabled and if so launches the start function, which updates to the new blocklist list.

The random delay serves to prevent a thundering herd: from an altruistic perspective, amelioerate load on the blocklist server; and from a selfish perspective, increase the prospect that the server is not loaded during the download.

Config Updates

During certain updates, adblock-lean will require a configuration update. adblock-lean will detect any out-of-date configurations and prompt you to automatically update the config, using your existing settings where possible.

A new compatible config can be generated, which will overwrite the previous config fie:

service adblock-lean gen_config

Features

adblock-lean is written as a service and 'service adblock-lean start' will download and setup dnsmasq with a new blocklist file. Various checks are performed and, dependence on the outcome of those checks, the script will either: accept the new blocklist file; reject the blocklist file if it didn't pass the checks and fallback to a previous blocklist file if available; or as a last resort restart dnsmasq with no blocklist file.

adblock-lean includes, inter alia, the following features:

• support multiple blocklist files downloaded from user-specified urls
• support local blocklist
• same for downloaded and local allowlists
• removal of domains found in the allowlist form the blocklist files
• combining all downloaded and local lists into one final blocklist file
• check that each individual blocklist and allowlist file does not exceed configurable maximum size
• check that the total blocklist size does not exceeed configurable maximum file size
• check for rogue entries in blocklist file parts (e.g. check for redirection to specific IP)
• check that line count in blocklist file does not exceed configurable minimum (default: 100,000)
• save a compressed copy of the previous blocklist file, then load the new combined blocklist file into dnsmasq
• supports blocklist compression by leveraging the new conf-script functionality of dnsmasq
• perform checks on restarted dnsmasq with new blocklist file
• revert to previous blocklist file if checks fail
• if checks on previous blocklist file also fail then revert to not using any blocklist file
• implements optional calls to user-configurable script on success or failure (for example to send an email report)
• automatically check for application updates and self update functionality
• config keys and values validation and optional automatic config repair when problems are detected

Config

adblock-lean reads in a config file from /etc/adblock-lean/config

A default config can be generated using: service adblock-lean gen_config.

Each configuration option is internally documented with comments in /etc/adblock-lean/config.

For devices with low free memory, consider enabling the initial_dnsmasq_restart option to free up memory for use during the memory-intensive blocklist generation process by additionally restarting dnsmasq with no blocklist prior to the generation of the new blocklist. This option is disabled by default to prevent both the associated: dnsmasq downtime; and the temporary running of dnsmasq with no blocklist.

Selection of blocklist(s) and download and processing parameters

An important factor in selecting blocklist(s) is how much free memory is available for blocklist use. It is the responsibility of the user to ensure that there is sufficient free memory to prevent an out of memory situation.

The parameters described in the config section above relating to the intermediate sizes, blocklist line count and deduplication should be set according to the selected blocklists and available memory. These are considered self-explanatory, but if in any doubt please post on the OpenWrt thread at:

https://forum.openwrt.org/t/adblock-lean-set-up-adblock-using-dnsmasq-blocklist/157076.

Here are some example configuration settings:

• Mini 64mb routers. Aim for <100k entries. Example below: circa 85k entries

blocklist_urls="https://raw.githubusercontent.com/hagezi/dns-blocklists/main/wildcard/pro.mini-onlydomains.txt"
min_blocklist_file_part_line_count=1
max_blocklist_file_part_size_KB=4000
max_blocklist_file_size_KB=4000
min_good_line_count=40000

• Small 128mb routers. Aim for <300k entries. Example below: circa 250k entries

blocklist_urls="https://raw.githubusercontent.com/hagezi/dns-blocklists/main/wildcard/pro-onlydomains.txt https://raw.githubusercontent.com/hagezi/dns-blocklists/main/wildcard/tif.mini-onlydomains.txt"
min_blocklist_file_part_line_count=1
max_blocklist_file_part_size_KB=7000
max_blocklist_file_size_KB=10000
min_good_line_count=100000

• Medium 256mb routers. Aim for <600k entries. Example below: circa 350k entries

blocklist_urls="https://raw.githubusercontent.com/hagezi/dns-blocklists/main/wildcard/pro-onlydomains.txt https://raw.githubusercontent.com/hagezi/dns-blocklists/main/wildcard/tif.medium-onlydomains.txt https://raw.githubusercontent.com/hagezi/dns-blocklists/main/wildcard/popupads-onlydomains.txt"
min_blocklist_file_part_line_count=1
max_blocklist_file_part_size_KB=10000
max_blocklist_file_size_KB=20000
min_good_line_count=200000

• Large =>512mb routers. Example below: circa 700k entries

blocklist_urls="https://raw.githubusercontent.com/hagezi/dns-blocklists/main/wildcard/pro-onlydomains.txt https://raw.githubusercontent.com/hagezi/dns-blocklists/main/wildcard/tif-onlydomains.txt"
min_blocklist_file_part_line_count=1
max_blocklist_file_part_size_KB=30000
max_blocklist_file_size_KB=50000
min_good_line_count=200000

An excellent breakdown of highly suitable lists and their merits is provided at:

https://github.com/hagezi/dns-blocklists

User-configurable calls on success or failure

adblock-lean supports specifying a custom script which defines the functions report_success and report_failure to be called on success or failure (can be used to eg send an email/SMS/msg)

Example below for free Brevo (formerly sendinblue) email service, but use your favourite smtp/email/SMS etc method.

• Install mailsend package in OpenWRT
• Sign up for free Brevo account (not affiliated!) - provides 300 free email sends per day
• Edit your config file custom_script path. Recommended path is '/usr/libexec/abl_custom-script.sh', which the adblock-lean luci app will have permission to access (for when the luci app is ready)
• Create file /usr/libexec/abl_custom-script.sh - specific user details (user variables in CAPITALS below):

#!/bin/sh

report_success()
{
mailbody="${1}"
mailsend -port 587 -smtp smtp-relay.sendinblue.com -auth -f FROM@EMAIL.COM -t TO@EMAIL.COM -user BREVO@USERNAME.COM -pass PASSWORD -sub "Adblock-lean blocklist update success" -M "${mailbody}"
}

report_failure()
{
mailbody="${1}"
mailsend -port 587 -smtp smtp-relay.sendinblue.com -auth -f FROM@EMAIL.COM -t TO@EMAIL.COM -user BREVO@USERNAME.COM -pass PASSWORD -sub "Adblock-lean blocklist update failed" -M "${mailbody}"
}

• the Brevo password is supplied within their website, not the one created on sign-up.
• If copy-pasting from Windows, avoid copy-pasting Windows-style newlines. To make sure, in Windows use a text editor which supports changing newline style (such as Notepad++) and make sure it is set to Unix (LF), rather than Windows (CR LF).

Checking status of adblock-lean

The status of a running adblock-lean instance can be obtained by running:

service adblock-lean status

Example output:

root@OpenWrt-1:~# service adblock-lean status
Checking dnsmasq instance.
The dnsmasq check passed and the presently installed blocklist has good line count: 736225.
adblock-lean appears to be active.
Generating dnsmasq stats.
dnsmasq stats available for reading using 'logread'.
The locally installed adblock-lean is the latest version.

Testing advert blocking

Verify adverts are removed from newspaper sites and e.g. https://www.speedtest.net/.

This test can also be helpful: https://d3ward.github.io/toolz/adblock

Preserve service file and config across OpenWrt upgrades

Just add the files:

/etc/init.d/adblock-lean
/etc/adblock-lean/
/etc/adblock-lean/config
/etc/adblock-lean/allowlist   # if used with your config
/etc/adblock-lean/blocklist   # if used with your config

to the list of files to backup in the Configuration tab in LuCi here:

http://openwrt.lan/cgi-bin/luci/admin/system/flash

:stars: Stargazers <a name="stargazers"></a>