You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

114 lines
8.5 KiB

  1. # adblock script for openwrt
  2. ## Description
  3. A lot of people already use adblocker plugins within their desktop browsers, 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. 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.
  4. ## Main Features
  5. * support of the following domain blocklist sources (free for private usage, for commercial use please check their individual licenses):
  6. * [adaway](https://adaway.org)
  7. * => infrequent updates, approx. 400 entries (enabled by default)
  8. * [disconnect](https://disconnect.me)
  9. * => numerous updates on the same day, approx. 6.500 entries (enabled by default)
  10. * [dshield](http://dshield.org)
  11. * => daily updates, approx. 4.500 entries
  12. * [feodotracker](https://feodotracker.abuse.ch)
  13. * => daily updates, approx. 0-10 entries
  14. * [malwaredomains](http://malwaredomains.com)
  15. * => daily updates, approx. 16.000 entries
  16. * [malwaredomainlist](http://www.malwaredomainlist.com)
  17. * => daily updates, approx. 1.500 entries
  18. * [openphish](https://openphish.com)
  19. * => numerous updates on the same day, approx. 1.800 entries
  20. * [palevotracker](https://palevotracker.abuse.ch)
  21. * => daily updates, approx. 15 entries
  22. * [ruadlist/easylist](https://code.google.com/p/ruadlist)
  23. * => weekly updates, approx. 2.000 entries
  24. * [shallalist](http://www.shallalist.de) (categories "adv" "costtraps" "spyware" "tracker" "warez" enabled by default)
  25. * => daily updates, approx. 32.000 entries (a short description of all shallalist categories can be found [online](http://www.shallalist.de/categories.html))
  26. * [spam404](http://www.spam404.com)
  27. * => infrequent updates, approx. 5.000 entries
  28. * [sysctl/cameleon](http://sysctl.org/cameleon)
  29. * => weekly updates, approx. 21.000 entries
  30. * [whocares](http://someonewhocares.org)
  31. * => weekly updates, approx. 12.000 entries
  32. * [winhelp](http://winhelp2002.mvps.org)
  33. * => infrequent updates, approx. 15.000 entries
  34. * [yoyo](http://pgl.yoyo.org/adservers)
  35. * => weekly updates, approx. 2.500 entries (enabled by default)
  36. * [zeustracker](https://zeustracker.abuse.ch)
  37. * => daily updates, approx. 440 entries
  38. * zero-conf like automatic installation & setup, usually no manual changes needed (i.e. ip address, network devices etc.)
  39. * full IPv4 and IPv6 support
  40. * each blocklist source will be updated and processed separately
  41. * timestamp check to download and process only updated adblock list sources
  42. * overall duplicate removal in separate adblock lists (will be automatically disabled on low memory systems)
  43. * adblock source list parsing by fast & flexible regex rulesets
  44. * additional white- and blacklist support for manual overrides
  45. * quality checks during & after update of adblock lists to ensure a reliable dnsmasq service
  46. * basic adblock statistics via iptables packet counters for each chain
  47. * status & error logging to stdout and syslog
  48. * use a dynamic uhttpd instance as an adblock pixel server
  49. * use dynamic iptables rulesets for adblock related redirects/rejects
  50. * openwrt init system support (start/stop/restart/reload)
  51. * hotplug support, the adblock start will be triggered by wan 'ifup' event
  52. * optional: adblock list backup/restore (disabled by default)
  53. ## Prerequisites
  54. * [openwrt](https://openwrt.org), tested with latest stable release (Chaos Calmer 15.05) and with current trunk (Designated Driver > r47025)
  55. * usual openwrt setup with 'iptables' & 'uhttpd', additional required software packages:
  56. * wget
  57. * optional: 'kmod-ipt-nat6' for IPv6 support
  58. * the above dependencies and requirements will be checked during package installation & script runtime
  59. ## Designated Driver Installation & Usage
  60. * install the adblock package (*opkg install adblock*)
  61. * start the adblock service with */etc/init.d/adblock start* and check *logread -e "adblock"* for adblock related information
  62. * optional: enable/disable your required adblock list sources in */etc/config/adblock* - 'adaway', 'disconnect' and 'yoyo' are enabled by default
  63. * optional: maintain the adblock service in luci under 'System => Startup'
  64. ## LuCI adblock companion package
  65. For easy management of the various blocklist sources and and the adblock options there is also a nice & efficient LuCI frontend available.
  66. Please install the package 'luci-app-adblock' (*opkg install luci-app-adblock*). Then you will find the application in LuCI located under 'Services' menu.
  67. Thanks to Hannu Nyman for this great adblock LuCI frontend!
  68. ## Chaos Calmer installation notes
  69. * currently the adblock package is *not* part of the CC package repository
  70. * download the latest adblock package *adblock_x.xx.x-1_all.ipk* from a development snapshot [package directory](https://downloads.openwrt.org/snapshots/trunk/ar71xx/nand/packages/packages)
  71. * due to server hardware troubles the package directory link above may not work, if so please check the [main openwrt download area](https://downloads.openwrt.org) manually
  72. * manual transfer the package to your router and install the opkg package as usual
  73. ## Tweaks
  74. * there is no need to enable all blacklist sites at once, for normal use one to three adblock list sources should be sufficient
  75. * if you really need to handle all blacklists at once add an usb stick or any other storage device to enlarge your temp directory with a swap partition => see [openwrt wiki](https://wiki.openwrt.org/doc/uci/fstab) for further details
  76. * add personal domain white- or blacklist entries as an additional blocklist source, one domain per line (wildcards & regex are not allowed!), by default both empty lists are located in */etc/adblock*
  77. * enable the backup/restore feature, to restore automatically the latest stable backup of your adblock lists in case of any (partial) processing error (i.e. a single blocklist source server is down). Please use an (external) solid partition and *not* your volatile router temp directory for this
  78. * for a scheduled call of the adblock service via */etc/init.d/adblock start* add an appropriate crontab entry
  79. * in case of any script runtime errors, you should enable script debugging: for this please change the value of the main 'DEBUG' switch, you'll find it in the header of */usr/bin/adblock-update.sh*
  80. ## Further adblock config options
  81. * usually the adblock autodetection works quite well and no manual config overrides are needed, all options apply to 'global' adblock config section:
  82. * adb\_enabled => main switch to enable/disable adblock service (default: '1', enabled)
  83. * 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.
  84. * adb\_wanif => name of the logical wan interface (default: 'wan')
  85. * adb\_lanif => name of the logical lan interface (default: 'lan')
  86. * adb\_port => port of the adblock uhttpd instance (default: '65535')
  87. * adb\_nullipv4 => IPv4 blackhole ip address (default: '192.0.2.1')
  88. * adb\_nullipv6 => IPv6 blackhole ip address (default: '::ffff:c000:0201')
  89. * adb\_forcedns => redirect all DNS queries to local dnsmasq resolver (default: '1', enabled)
  90. ## Background
  91. This adblock package is a dns/dnsmasq based adblock solution for openwrt.
  92. Queries to ad/abuse domains are never forwarded and always replied with a local IP address which may be IPv4 or IPv6.
  93. For that purpose adblock uses an ip address from the private 'TEST-NET-1' subnet (192.0.2.1 / ::ffff:c000:0201) by default.
  94. 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).
  95. 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.
  96. ## Support
  97. 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>
  98. ## Removal
  99. * stop all adblock related services with */etc/init.d/adblock stop*
  100. * optional: remove the adblock package (*opkg remove adblock*)
  101. Have fun!
  102. Dirk