net/adblock/files/README.md

   1 # adblock script for openwrt
   2
   3 ## Description
   4 A lot of people already use adblocker plugins within their desktop browsers,
   5 but what if you are using your (smart) phone, tablet, watch or any other wlan gadget...getting rid of annoying ads, trackers and other abuse sites (like facebook ;-) is simple: block them with your router.
   6
   7 When the dns server on your router receives dns requests, you will sort out queries that ask for the resource records of ad servers and return the local ip address of your router and the internal web server delivers a transparent pixel instead.
   8
   9 ## Main Features
  10 * support of the following domain blocklist sources (free for private usage, for commercial use please check their individual licenses):
  11     * [adaway](https://adaway.org)
  12     * => infrequent updates, approx. 400 entries (enabled by default)
  13     * [disconnect](https://disconnect.me)
  14     * => numerous updates on the same day, approx. 6.500 entries (enabled by default)
  15     * [dshield](http://dshield.org)
  16     * => daily updates, approx. 4.500 entries
  17     * [feodotracker](https://feodotracker.abuse.ch)
  18     * => daily updates, approx. 0-10 entries
  19     * [malwaredomains](http://malwaredomains.com)
  20     * => daily updates, approx. 16.000 entries
  21     * [malwaredomainlist](http://www.malwaredomainlist.com)
  22     * => daily updates, approx. 1.500 entries
  23     * [openphish](https://openphish.com)
  24     * => numerous updates on the same day, approx. 1.800 entries
  25     * [palevotracker](https://palevotracker.abuse.ch)
  26     * => daily updates, approx. 15 entries
  27     * [ruadlist+easylist](https://code.google.com/p/ruadlist)
  28     * => weekly updates, approx. 2.000 entries
  29     * [shallalist](http://www.shallalist.de) (categories "adv" "costtraps" "spyware" "tracker" "warez" enabled by default)
  30     * => daily updates, approx. 32.000 entries (a short description of all shallalist categories can be found [online](http://www.shallalist.de/categories.html))
  31     * [spam404](http://www.spam404.com)
  32     * => infrequent updates, approx. 5.000 entries
  33     * [whocares](http://someonewhocares.org)
  34     * => weekly updates, approx. 12.000 entries
  35     * [winhelp](http://winhelp2002.mvps.org)
  36     * => infrequent updates, approx. 15.000 entries
  37     * [yoyo](http://pgl.yoyo.org/adservers)
  38     * => weekly updates, approx. 2.500 entries (enabled by default)
  39     * [zeustracker](https://zeustracker.abuse.ch)
  40     * => daily updates, approx. 440 entries
  41 * zero-conf like automatic installation & setup, usually no manual changes needed (i.e. ip address, network devices etc.)
  42 * full IPv4 and IPv6 support
  43 * each blocklist source will be updated and processed separately
  44 * timestamp check to download and process only updated adblock list sources
  45 * overall duplicate removal in separate adblock lists (will be automatically disabled on low memory systems)
  46 * adblock source list parsing by fast & flexible regex rulesets
  47 * additional white- and blacklist support for manual overrides
  48 * quality checks during & after update of adblock lists to ensure a reliable dnsmasq service
  49 * wan update check, to wait for an active wan uplink before update
  50 * basic adblock statistics via iptables packet counters for each chain
  51 * status & error logging to stdout and syslog
  52 * use of dynamic uhttpd instance as adblock pixel server
  53 * openwrt init system support (start/stop/restart/reload)
  54 * hotplug support, adblock start will be triggered by wan 'ifup' event
  55 * optional features (disabled by default):
  56     * adblock list backup/restore
  57     * debug logging to separate file
  58
  59 ## Prerequisites
  60 * [openwrt](https://openwrt.org), tested with latest stable release (Chaos Calmer 15.05) and with current trunk (Designated Driver > r47025)
  61 * usual openwrt setup with 'iptables' & 'uhttpd', additional required software packages:
  62     * wget
  63     * optional: 'kmod-ipt-nat6' for IPv6 support
  64 * the above dependencies and requirements will be checked during package installation & script runtime
  65
  66 ## Installation & Usage
  67 * install the adblock package (*opkg update & opkg install adblock*)
  68 * start the adblock service with */etc/init.d/adblock start* and check *logread -e "adblock"* for adblock related information
  69 * optional: enable/disable your required adblock list sources in */etc/config/adblock* - 'adaway', 'disconnect' and 'yoyo' are enabled by default
  70 * optional: maintain the adblock service in luci under 'System => Startup'
  71
  72 ## LuCI adblock companion package
  73 For easy management of the various blocklist sources and and the adblock options there is also a nice & efficient LuCI frontend available.
  74 Please install the package 'luci-app-adblock'. Then you will find the application in LuCI located under 'Services' menu.
  75 Thanks to Hannu Nyman for this great adblock LuCI frontend!
  76
  77 ## CC installation notes
  78 * currently the adblock package is *not* part of the CC package repository
  79 * download the latest adblock package *adblock_x.xx.x-1_all.ipk* from a DD snapshot [package directory](https://downloads.openwrt.org/snapshots/trunk/ar71xx/generic/packages/packages)
  80 * manual transfer the package to your router and install the opkg package as usual
  81
  82 ## Tweaks
  83 * there is no need to enable all blacklist sites at once, for normal use one to three adblock list sources should be sufficient
  84 * if you really need to handle all blacklists at once add an usb stick or any other storage device to supersize your temp directory with a swap partition => see [openwrt wiki](https://wiki.openwrt.org/doc/uci/fstab) for further details
  85 * add static, personal domain white- or blacklist entries, one domain per line (wildcards & regex are not allowed!), by default both lists are located in */etc/adblock*
  86 * enable the backup/restore feature, to restore automatically the latest, stable backup of your adblock lists in case of any processing error
  87 * enable the logging feature for continuous logfile writing to monitor the adblock runs over a longer period
  88 * for a scheduled call of the adblock service via */etc/init.d/adblock start* add an appropriate crontab entry
  89
  90 ## Further adblock config options
  91 * usually the adblock autodetection works quite well and no manual config overrides are needed, all options apply to 'global' adblock config section:
  92     * adb\_enabled => main switch to enable/disable adblock service (default: '1' (enabled))
  93     * adb\_cfgver => config version string (do not change!) - adblock checks this entry and automatically applies the current config, if none or an older revision was found.
  94     * adb\_wanif => name of the logical wan interface (default: 'wan')
  95     * adb\_lanif => name of the logical lan interface (default: 'lan')
  96     * adb\_port => port of the adblock uhttpd instance (default: '65535')
  97     * adb\_nullipv4 => IPv4 blackhole ip address (default: '192.0.2.1')
  98     * adb\_nullipv6 => IPv6 blackhole ip address (default: '::ffff:c000:0201')
  99
 100 ## Background
 101 This adblock package is a dns/dnsmasq based adblock solution for openwrt.
 102 Queries to ad/abuse domains are never forwarded and always replied with a local IP address which may be IPv4 or IPv6.
 103 For that purpose adblock uses an ip address from the private 'TEST-NET-1' subnet (192.0.2.1 / ::ffff:c000:0201) by default.
 104 Furthermore all ad/abuse queries will be filtered by ip(6)tables and redirected to internal adblock pixel server (in PREROUTING chain) or rejected (in FORWARD or OUTPUT chain).
 105 All iptables and uhttpd related adblock additions are non-destructive, no hard-coded changes in 'firewall.user', 'uhttpd' config or any other openwrt related config files. There is *no* adblock background daemon running, the (scheduled) start of the adblock service keeps only the adblock lists up-to-date.
 106
 107 ## Support
 108 Please join the adblock discussion in this [openwrt forum thread](https://forum.openwrt.org/viewtopic.php?id=59803) or contact me by mail <openwrt@brenken.org>
 109
 110 ## Removal
 111 * stop all adblock related services with */etc/init.d/adblock stop*
 112 * optional: remove the adblock package (*opkg remove adblock*)
 113
 114 Have fun!
 115 Dirk