adblock: release 3.0

* add kresd & turris omnia support * add dnscrypt-proxy support * change start priority to 30, to fix possible trigger issues on slow booting hardware * simplify suspend/resume handling (no longer use a hideout directory) * enhanced LuCI frontend * many small changes & improvements * default config change (please update your config!), adblock is now disabled by default * documentation update Signed-off-by: Dirk Brenken <dev@brenken.org>
2026-04-29 23:18:42 +01:00 · 2017-09-09 17:35:42 +02:00
parent 7cdb6c7031
commit 206c847bb5
5 changed files with 238 additions and 188 deletions
@@ -29,6 +29,8 @@ A lot of people already use adblocker plugins within their desktop browsers, but
    * => 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)
@@ -57,12 +59,12 @@ A lot of people already use adblocker plugins within their desktop browsers, but
    * => 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, bind or kresd (experimental!) 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)
@@ -70,10 +72,11 @@ A lot of people already use adblocker plugins within their desktop browsers, but
 * 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
@@ -85,16 +88,16 @@ A lot of people already use adblocker plugins within their desktop browsers, but
 * 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

@@ -105,7 +108,7 @@ A lot of people already use adblocker plugins within their desktop browsers, but
 * **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)
@@ -113,12 +116,14 @@ A lot of people already use adblocker plugins within their desktop browsers, but

 ## 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)
@@ -132,7 +137,7 @@ If you use manual configuration for unbound, then just include the following lin
  include: "/var/lib/unbound/adb_list.overall"
 </code></pre>
  
-**change default dns backend to 'bind':**
+**change default dns backend to 'named' (bind):**
 <pre><code>
 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:
@@ -159,9 +164,9 @@ create the new file '/etc/bind/db.rpz' and add:
  
 **change default dns backend to 'kresd':**
 <pre><code>
-The knot-resolver (kresd) support is only available to turris omnia users. At this stage 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 '/tmp/kresd' where kresd can find them.
-To use the block list please modify the following kresd configuration files (experimental / untested!):
+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:

 edit '/etc/config/resolver' and uncomment the following option:
  option include_config '/etc/kresd/custom.conf'
@@ -169,25 +174,27 @@ edit '/etc/config/resolver' and uncomment the following option:
 in the same file change the 'forward_upstream' option like that:
  forward_upstream '0'

-edit '/etc/kresd/custom.conf' and add:
-  policy.add(policy.rpz(policy.DENY, '/etc/kresd/db.rpz'))
+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')))
  policy.add(policy.all(policy.FORWARD('8.8.4.4')))
+</code></pre>
+  
+**change default dns backend to 'dnscrypt-proxy':**
+<pre><code>
+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:

-create the new file '/etc/kresd/db.rpz' and add:
-  $TTL 2h
-  $ORIGIN rpz.
-  @ SOA localhost. root.localhost. (1 6h 1h 1w 2h)
-  NS localhost.
-
-  $INCLUDE /tmp/kresd/adb_list.overall
+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'
@@ -206,13 +213,13 @@ curl:
 <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):**
@@ -250,17 +257,16 @@ This entry does not remove:
 **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>