* => daily updates, approx. 150 entries
* [reg_cn](https://easylist-downloads.adblockplus.org/easylistchina+easylist.txt)
* => regional blocklist for China, daily updates, approx. 1.600 entries
+ * [reg_id](https://easylist-downloads.adblockplus.org/abpindo+easylist.txt)
+ * => regional blocklist for Indonesia, daily updates, approx. 800 entries
* [reg_nl](https://easylist-downloads.adblockplus.org/easylistdutch+easylist.txt)
* => regional blocklist for the Netherlands, weekly updates, approx. 1300 entries
* [reg_pl](http://adblocklist.org)
* => daily updates, approx. 440 entries
* zero-conf like automatic installation & setup, usually no manual changes needed
* simple but yet powerful adblock engine: adblock does not use error prone external iptables rulesets, http pixel server instances and things like that
-* automatically selects dnsmasq, unbound or bind as dns backend
+* supports five different dns backends / block list formats: dnsmasq, unbound, named (bind), kresd and dnscrypt-proxy
* automatically selects uclient-fetch or wget as download utility (other tools like curl or aria2c are supported as well)
-* support http only mode (without installed ssl library) for all non-SSL blocklist sources
-* automatically supports a wide range of router modes, even AP modes are supported
+* provides 'http only' mode without installed ssl library for all non-SSL block list sources
+* supports a wide range of router modes, even AP modes are supported
* full IPv4 and IPv6 support
-* supports tld compression (top level domain compression), this feature removes thousands of needless host entries from the block list and lowers the memory footprint for the dns backends
+* provides top level domain compression ('tld compression'), this feature removes thousands of needless host entries from the block list and lowers the memory footprint for the dns backends
* each block list source will be updated and processed separately
* block list source parsing by fast & flexible regex rulesets
* overall duplicate removal in central block list (adb_list.overall)
* quality checks during block list update to ensure a reliable dns backend service
* minimal status & error logging to syslog, enable debug logging to receive more output
* procd based init system support (start/stop/restart/reload/suspend/resume/query/status)
-* procd based hotplug support, the adblock start will be solely triggered by network interface triggers
+* procd network interface trigger support or classic time based startup
* suspend & resume adblock actions temporarily without block list reloading
-* runtime information available via LuCI & via 'status' init command
+* output comprehensive runtime information via LuCI or via 'status' init command
* query function to quickly identify blocked (sub-)domains, e.g. for whitelisting
+* strong LuCI support
* optional: force dns requests to local resolver
* optional: force overall sort / duplicate removal for low memory devices (handle with care!)
* optional: 'manual mode' to re-use blocklist backups during startup, get fresh lists only via manual reload or restart action
* a usual setup with an enabled dns backend at minimum - dump AP modes without a working dns backend are _not_ supported
* a download utility:
* to support all blocklist sources a full version (with ssl support) of 'wget', 'uclient-fetch' with one of the 'libustream-*' ssl libraries, 'aria2c' or 'curl' is required
- * for limited devices with real memory constraints, adblock provides also a plain http option and supports wget-nossl and uclient-fetch (without libustream-ssl), too
+ * for limited devices with real memory constraints, adblock provides also a 'http only' option and supports wget-nossl and uclient-fetch (without libustream-ssl) as well
* for more configuration options see examples below
-## LEDE trunk Installation & Usage
-* install 'adblock' (_opkg install adblock_) and that's it - the adblock start will be automatically triggered by procd interface trigger
+## Installation & Usage
+* install 'adblock' (_opkg install adblock_)
+* at minimum configure the appropriate dns backend ('dnsmasq' by default) and enable the adblock service in _/etc/config/adblock_
* control the adblock service manually with _/etc/init.d/adblock_ start/stop/restart/reload/suspend/resume/status or use the LuCI frontend
-* enable/disable your favored block list sources in _/etc/config/adblock_ - 'adaway', 'disconnect' and 'yoyo' are enabled by default
## LuCI adblock companion package
-* for easy management of the various block list sources and all other adblock options you can also use a nice & efficient LuCI frontend
+* for easy management of the various block list sources and all other adblock options you should use the provided LuCI frontend
* install 'luci-app-adblock' (_opkg install luci-app-adblock_)
* the application is located in LuCI under 'Services' menu
* **add white- / blacklist entries:** add domain white- or blacklist entries to always-allow or -deny certain (sub) domains, by default both lists are empty and located in _/etc/adblock_. Please add one domain per line - ip addresses, wildcards & regex are _not_ allowed (see example below)
* **backup & restore block lists:** enable this feature, to restore automatically the latest compressed backup of your block lists in case of any processing error (e.g. a single block list source is not available during update). Please use an (external) solid partition and _not_ your volatile router temp directory for this
* **scheduled list updates:** for a scheduled call of the adblock service add an appropriate crontab entry (see example below)
-* **restrict procd interface trigger:** restrict the procd interface trigger to a (list of) certain interface(s) (default: wan). To disable it at all, remove all entries
+* **change startup behaviour:** by default the startup will be triggered by the 'wan' procd interface trigger. Choose 'none' to disable automatic startups, 'timed' to use a classic timeout (default 30 sec.) or select another trigger interface.
* **suspend & resume adblocking:** to quickly switch the adblock service 'on' or 'off', simply use _/etc/init.d/adblock [suspend|resume]_
* **domain query:** to query the active block list for a specific domain, please run _/etc/init.d/adblock query `<DOMAIN>`_ (see example below)
* **add new list sources:** you could add new block list sources on your own via uci config, all you need is a source url and an awk one-liner (see example below)
## Further adblock config options
* usually the pre-configured adblock setup works quite well and no manual config overrides are needed, all listed options apply to the 'global' config section:
- * adb\_enabled => main switch to enable/disable adblock service (default: '1', enabled)
+ * adb\_enabled => main switch to enable/disable adblock service (default: '0', disabled)
* adb\_debug => enable/disable adblock debug output (default: '0', disabled)
- * adb\_iface => set the procd interface trigger to a (list of) lan / wan interface(s) (default: 'wan')
- * adb\_fetch => full path to a different download utility, see example below (default: not set, use wget)
- * adb\_fetchparm => options for the download utility, see example below (default: not set, use wget options)
- * adb\_triggerdelay => additional trigger delay in seconds before adblock processing starts (default: '2')
+ * adb\_dns => select the dns backend for your environment: 'dnsmasq', 'unbound', 'named', 'kresd' or 'dnscrypt-proxy' (default: 'dnsmasq')
+ * adb\_dnsdir => target directory for the generated blocklist 'adb_list.overall' (default: not set, use dns backend default)
+ * adb\_trigger => set the startup trigger to a certain interface, to 'timed' or to 'none' (default: 'wan')
+ * adb\_triggerdelay => additional trigger delay in seconds before adblock processing begins (default: '1')
+ * adb\_fetch => full path to a dedicated download utility, see example below (default: not set, use wget default)
+ * adb\_fetchparm => options for the download utility, see example below (default: not set, use wget default options)
* adb\_forcedns => force dns requests to local resolver (default: '0', disabled)
* adb\_forcesrt => force overall sort on low memory devices with less than 64 MB RAM (default: '0', disabled)
* adb\_manmode => do not automatically update block lists during startup, use backups instead (default: '0', disabled)
## Examples
-**change default dns backend to 'unbound':**
-<pre><code>
+**change default dns backend to 'unbound':**
+
Adblock deposits the sorted and filtered block list (adb_list.overall) in '/var/lib/unbound' where unbound can find them in its jail.
If you use manual configuration for unbound, then just include the following line in your 'server' clause:
-
+<pre><code>
include: "/var/lib/unbound/adb_list.overall"
</code></pre>
-**change default dns backend to 'bind':**
-<pre><code>
+**change default dns backend to 'named' (bind):**
+
Adblock deposits the sorted and filtered block list (adb_list.overall) in '/var/lib/bind' where bind can find them.
To use the block list please modify the following bind configuration files:
-
+<pre><code>
change '/etc/bind/named.conf', in the 'options' namespace add:
response-policy { zone "rpz"; };
$INCLUDE /var/lib/bind/adb_list.overall
</code></pre>
+**change default dns backend to 'kresd':**
+
+The knot-resolver (kresd) is only available on turris omnia devices. Currently there's no package for kresd in the official LEDE / OpenWrt package repository.
+Adblock deposits the sorted and filtered block list (adb_list.overall) in '/etc/kresd' where kresd can find them.
+To use the block list please create/modify the following kresd configuration files:
+<pre><code>
+TurrisOS > 3.6:
+ edit '/etc/config/resolver' and change / uncomment the following options:
+ forward_upstream '0'
+ list rpz_file '/etc/kresd/adb_list.overall'
+
+TurrisOS < 3.6:
+ edit '/etc/config/resolver' and change / uncomment the following options:
+ forward_upstream '0'
+ option include_config '/etc/kresd/custom.conf'
+
+ create '/etc/kresd/custom.conf' and add:
+ policy.add(policy.rpz(policy.DENY, '/etc/kresd/adb_list.overall'))
+ policy.add(policy.all(policy.FORWARD({'8.8.8.8', '8.8.4.4'})))
+</code></pre>
+
+**change default dns backend to 'dnscrypt-proxy':**
+
+Adblock deposits the sorted and filtered block list (adb_list.overall) by default in '/tmp' where DNSCrypt-Proxy can find them.
+The blacklist option is not supported by default, because DNSCrypt-Proxy is compiled without plugins support.
+Take a custom LEDE build with plugins support to use this feature:
+<pre><code>
+edit '/etc/config/dnscrypt-proxy' and add the following option per dnscrypt-proxy instance:
+ list blacklist 'domains:/tmp/adb_list.overall'
+</code></pre>
+
**configuration for different download utilities:**
<pre><code>
wget (default):
- option adb_fetch="/usr/bin/wget"
- option adb_fetchparm="--quiet --no-cache --no-cookies --max-redirect=0 --timeout=10 --no-check-certificate -O"
+ option adb_fetch '/usr/bin/wget'
+ option adb_fetchparm '--quiet --no-cache --no-cookies --max-redirect=0 --timeout=10 --no-check-certificate -O'
aria2c:
option adb_fetch '/usr/bin/aria2c'
<pre><code>
/etc/init.d/adblock status
::: adblock runtime information
- status : active
- adblock_version : 2.8.0
- blocked_domains : 122827
- fetch_info : wget (built-in)
- dns_backend : dnsmasq
- last_rundate : 26.06.2017 17:00:27
- system : LEDE Reboot SNAPSHOT r4434-b91a38d647
+ + adblock_status : enabled
+ + adblock_version : 3.0.0
+ + blocked_domains : 37406
+ + fetch_utility : wget (built-in)
+ + dns_backend : kresd (/etc/kresd)
+ + last_rundate : 08.09.2017 21:21:21
+ + system_release : OpenWrt omnia 15.05
</code></pre>
**cronjob for a regular block list update (/etc/crontabs/root):**
**query active block list for a certain (sub-)domain, e.g. for whitelisting:**
<pre><code>
/etc/init.d/adblock query example.www.doubleclick.net
-::: results for (sub-)domain 'example.www.doubleclick.net' (max. 5)
- - no match
-::: results for (sub-)domain 'www.doubleclick.net' (max. 5)
- - no match
-::: results for (sub-)domain 'doubleclick.net' (max. 5)
- + doubleclick.net
- + feedads.g.doubleclick.net
- + survey.g.doubleclick.net
+root@turris:~# /etc/init.d/adblock query example.www.doubleclick.net
+::: max. ten results for domain 'example.www.doubleclick.net'
+ - no match
+::: max. ten results for domain 'www.doubleclick.net'
+ - no match
+::: max. ten results for domain 'doubleclick.net'
+ + doubleclick.net
-The query function checks against the submitted (sub-)domain and recurses automatically to the upper top level domain(s).
-For every (sub-)domain it returns the first five relevant results.
+The query function checks against the submitted (sub-)domain and recurses automatically to the upper top level domain.
+For every (sub-)domain it returns the first ten relevant results.
In the example above whitelist "doubleclick.net" to free the submitted domain.
</code></pre>